Support annotations on local files

Author: backnotprop

README.md

@@ -21,6 +21,8 @@ bun run dev
 
 Run `bun test` and `bun run build` before submitting changes.
 
+For local `file://` pages, enable **Allow access to file URLs** in App Notes' Chrome extension settings, then reload the file.
+
 See the [release checklist](docs/RELEASE_CHECKLIST.md) and [privacy policy](PRIVACY.md).
 
 ## License

docs/RELEASE_CHECKLIST.md

@@ -77,6 +77,7 @@ Test on Chrome Stable, Firefox Stable, Edge Stable, and current Arc. Test Safari
 ### Compatibility and quality
 
 -[ ] Test a conventional multi-page site, a React/Vue SPA, Yahoo, Hacker News, and a page with open Shadow DOM.
+-[ ] In Chrome, enable **Allow access to file URLs**, annotate a local HTML file, save and reload it, then confirm sibling HTML files share one folder workspace while a different folder remains isolated.
 -[ ] Restricted browser pages fail gracefully without broken controls.
 -[ ] Switch the operating system/browser between light and dark appearance; popup, composer, toast, markers, and notes workspace update automatically and remain legible on both light and dark host pages.
 -[ ] Keyboard focus order, visible focus, screen-reader labels, and 200% zoom are usable.

entrypoints/content/App.tsx

@@ -12,7 +12,7 @@ import {
 identifyElement,
 resolveAnnotationAnchor,
 }from'@/lib/anchoring';
-import{getAnnotationStorageKeyForUrl}from'@/lib/page';
+import{getAnnotationStorageKeyForUrl,getPageDisplayLabel}from'@/lib/page';
 import{getAnnotations,saveAnnotation}from'@/lib/storage';
 import{parseAnnotations}from'@/lib/types';
 importtype{Annotation,AnnotationAnchor}from'@/lib/types';
@@ -68,7 +68,9 @@ function getCurrentPageTitle(href: string): string {
 if(title)returntitle.slice(0,160);
 
 try{
-returnnewURL(href).hostname.slice(0,160);
+constparsed=newURL(href);
+constfallback=parsed.hostname||getPageDisplayLabel(href)||'Untitled page';
+returnfallback.slice(0,160);
 }catch{
 return'Untitled page';
 }

entrypoints/popup/App.tsx

@@ -19,6 +19,18 @@ function parseAnnotationModeResponse(value: unknown): AnnotationModeResponse | n
 returntypeofactive==='boolean' ? { active } : null;
 }
 
+functiongetUnavailablePageMessage(url: string): string{
+try{
+if(newURL(url).protocol==='file:'){
+return'Allow file access in the extension settings, then reload this file.';
+}
+}catch{
+// Fall through to the general unavailable-page message.
+}
+
+return'App Notes isn’t available on this page.';
+}
+
 functionApp(){
 const[active,setActive]=useState(false);
 const[count,setCount]=useState(0);
@@ -64,7 +76,7 @@ function App() {
 setModeAvailable(true);
 }
 }catch{
-if(!cancelled)setStatus('App Notes isn’t available on this page.');
+if(!cancelled)setStatus(getUnavailablePageMessage(tab.url));
 }
 };
 
@@ -113,7 +125,7 @@ function App() {
 }
 setActive(response.active);
 }catch{
-setStatus('App Notes isn’t available on this page.');
+setStatus(getUnavailablePageMessage(currentUrl));
 }finally{
 setIsToggling(false);
 }

entrypoints/sidepanel/App.tsx

@@ -14,6 +14,9 @@ import {
 }from'lucide-react';
 import{
 getAnnotationStoragePrefixForUrl,
+getPageDisplayLabel,
+getSiteDisplayLabel,
+parseSiteId,
 }from'@/lib/page';
 import{
 clearSiteAnnotations,
@@ -356,13 +359,7 @@ export function SidePanelApp() {
 constgroups=buildPanelGroups(annotations);
 constglobalAnnotations=allAnnotations??[];
 constpageUnavailable=site!==null&&site.storagePrefix===null;
-constdomain=(()=>{
-try{
-returnsite ? newURL(site.href).host : 'Current site';
-}catch{
-return'Current site';
-}
-})();
+constdomain=site ? getSiteDisplayLabel(site.href)??'Current site' : 'Current site';
 
 return(
 <mainclassName="flex h-screen flex-col bg-surface">
@@ -758,14 +755,13 @@ function buildGlobalGroups(
 ): ReadonlyArray<GlobalSiteGroup>{
 constgroups=newMap<string,{label: string;annotations: Annotation[]}>();
 for(constannotationofannotations){
-try{
-constparsed=newURL(annotation.url);
-constgroup=groups.get(parsed.origin)??{label: parsed.host,annotations: []};
-group.annotations.push(annotation);
-groups.set(parsed.origin,group);
-}catch{
-// Persisted annotations are parsed before reaching this view.
-}
+constsiteId=parseSiteId(annotation.url);
+constlabel=getSiteDisplayLabel(annotation.url);
+if(siteId===null||label===null)continue;
+
+constgroup=groups.get(siteId)??{ label,annotations: []};
+group.annotations.push(annotation);
+groups.set(siteId,group);
 }
 
 return[...groups.entries()]
@@ -803,12 +799,7 @@ function buildPanelGroups(
 }
 
 functiongetPageLabel(pageId: string): string{
-try{
-constpath=newURL(pageId).pathname;
-returnpath==='/' ? 'Home' : path;
-}catch{
-returnpageId;
-}
+returngetPageDisplayLabel(pageId)??pageId;
 }
 
 functiongetAnnotationPageLabel(annotation: Annotation): string{
@@ -833,11 +824,6 @@ function getAnnotationSummary(annotation: Annotation): string {
 }
 
 functiongetExportFilename(url: string): string{
-letsite='site';
-try{
-site=newURL(url).hostname.replace(/[^a-z0-9.-]+/gi,'-');
-}catch{
-// Keep the safe fallback filename.
-}
+constsite=(getSiteDisplayLabel(url)??'site').replace(/[^a-z0-9.-]+/gi,'-');
 return`app-notes-${site}-${newDate().toISOString().slice(0,10)}.md`;
 }

lib/page.test.ts

@@ -4,6 +4,8 @@ import {
 getAnnotationStorageKeyForUrl,
 getAnnotationStoragePrefix,
 getAnnotationStoragePrefixForUrl,
+getPageDisplayLabel,
+getSiteDisplayLabel,
 parsePageId,
 parseSiteId,
 }from'./page';
@@ -57,10 +59,53 @@ describe('page identity', () => {
 );
 });
 
+test('uses the canonical local file URL as a page identity',()=>{
+consturl='file:///Users/ramos/workspaces/design/My%20Review/index.html?mode=edit#hero';
+
+expect(parsePageId(url)?.toString()).toBe(
+'file:///Users/ramos/workspaces/design/My%20Review/index.html',
+);
+expect(getAnnotationStorageKeyForUrl(url)).toBe(
+'annotations:file:///Users/ramos/workspaces/design/My%20Review/index.html',
+);
+expect(getPageDisplayLabel(url)).toBe('index.html');
+});
+
+test('groups local files in the same parent folder as one site',()=>{
+constindexUrl='file:///Users/ramos/workspaces/design/guided-review/index.html';
+constdetailsUrl='file:///Users/ramos/workspaces/design/guided-review/details.html';
+
+expect(parseSiteId(indexUrl)?.toString()).toBe(
+'file:///Users/ramos/workspaces/design/guided-review',
+);
+expect(getAnnotationStoragePrefixForUrl(indexUrl)).toBe(
+'annotations:file:///Users/ramos/workspaces/design/guided-review/',
+);
+expect(getAnnotationStoragePrefixForUrl(detailsUrl)).toBe(
+getAnnotationStoragePrefixForUrl(indexUrl),
+);
+expect(getSiteDisplayLabel(indexUrl)).toBe('guided-review');
+});
+
+test('keeps local file folders isolated',()=>{
+expect(
+getAnnotationStoragePrefixForUrl('file:///Users/ramos/project-a/index.html'),
+).not.toBe(
+getAnnotationStoragePrefixForUrl('file:///Users/ramos/project-b/index.html'),
+);
+});
+
+test('handles files stored at the filesystem root',()=>{
+expect(getAnnotationStoragePrefixForUrl('file:///review.html')).toBe(
+'annotations:file:///',
+);
+expect(getSiteDisplayLabel('file:///review.html')).toBe('Local files');
+});
+
 test('rejects unsupported and malformed URLs',()=>{
 expect(parsePageId('not a url')).toBeNull();
 expect(parsePageId('chrome://extensions')).toBeNull();
-expect(parsePageId('file:///tmp/page.html')).toBeNull();
+expect(parsePageId('data:text/html,hello')).toBeNull();
 expect(parseSiteId('chrome://extensions')).toBeNull();
 });
 });

lib/page.ts

@@ -1,10 +1,10 @@
 declareconstpageIdBrand: unique symbol;
 declareconstsiteIdBrand: unique symbol;
 
-/** The canonical identity of one annotatable web page. */
+/** The canonical identity of one annotatable web or local-file page. */
 exporttypePageId=string&{readonly[pageIdBrand]: 'PageId'};
 
-/** The canonical identity of one annotatable website (its URL origin). */
+/** The canonical identity of one web origin or local-file folder workspace. */
 exporttypeSiteId=string&{readonly[siteIdBrand]: 'SiteId'};
 
 /** The browser storage key containing annotations for one page. */
@@ -14,45 +14,94 @@ export type AnnotationStorageKey = `annotations:${string}`;
 exporttypeAnnotationStoragePrefix= `annotations:${string}/`;
 
 /**
- * Parse an HTTP(S) URL into the page identity used by App Notes.
+ * Parse an HTTP(S) or local-file URL into the page identity used by App Notes.
  *
  * Query parameters and fragments are intentionally excluded so transient URL
  * state does not split annotations for the same origin and pathname.
  */
 exportfunctionparsePageId(url: string): PageId|null{
 try{
 constparsed=newURL(url);
-if(parsed.protocol!=='http:'&&parsed.protocol!=='https:')returnnull;
+if(!isAnnotatableProtocol(parsed.protocol))returnnull;
 
-constpageId=`${parsed.origin}${parsed.pathname}`;
-// SAFETY: URL parsing established an absolute HTTP(S) origin and pathname.
+parsed.search='';
+parsed.hash='';
+constpageId=parsed.protocol==='file:'
+ ? parsed.href
+ : `${parsed.origin}${parsed.pathname}`;
+
+// SAFETY: URL parsing and the protocol guard established a canonical,
+// absolute HTTP(S) or local-file page URL without transient state.
 returnpageIdasPageId;
 }catch{
 returnnull;
 }
 }
 
-/** Parse an HTTP(S) URL into the website identity used by App Notes. */
+/** Parse a URL into its web-origin or local parent-folder workspace identity. */
 exportfunctionparseSiteId(url: string): SiteId|null{
 try{
 constparsed=newURL(url);
-if(parsed.protocol!=='http:'&&parsed.protocol!=='https:')returnnull;
+if(!isAnnotatableProtocol(parsed.protocol))returnnull;
+
+if(parsed.protocol==='file:'){
+constdirectory=parsed.pathname.endsWith('/') ? parsed : newURL('.',parsed);
+directory.search='';
+directory.hash='';
+constsiteId=directory.pathname==='/'
+ ? directory.href
+ : directory.href.slice(0,-1);
+
+// SAFETY: URL parsing and the file protocol guard established a canonical
+// absolute directory URL. Non-root directories omit only the trailing slash.
+returnsiteIdasSiteId;
+}
 
-// SAFETY: URL parsing established an absolute HTTP(S) origin.
+// SAFETY: URL parsing and the protocol guard established an absolute HTTP(S) origin.
 returnparsed.originasSiteId;
 }catch{
 returnnull;
 }
 }
 
+/** Return a concise user-facing label for an annotatable site workspace. */
+exportfunctiongetSiteDisplayLabel(url: string): string|null{
+constsiteId=parseSiteId(url);
+if(siteId===null)returnnull;
+
+constparsed=newURL(siteId);
+if(parsed.protocol!=='file:')returnparsed.host;
+if(parsed.pathname==='/')return'Local files';
+
+constsegments=parsed.pathname.split('/').filter((segment)=>segment.length>0);
+constlastSegment=segments.at(-1);
+returnlastSegment===undefined ? 'Local files' : decodePathSegment(lastSegment);
+}
+
+/** Return a concise user-facing label for an annotatable page. */
+exportfunctiongetPageDisplayLabel(url: string): string|null{
+constpageId=parsePageId(url);
+if(pageId===null)returnnull;
+
+constparsed=newURL(pageId);
+if(parsed.protocol!=='file:')returnparsed.pathname==='/' ? 'Home' : parsed.pathname;
+if(parsed.pathname.endsWith('/'))return'Home';
+
+constsegments=parsed.pathname.split('/').filter((segment)=>segment.length>0);
+constlastSegment=segments.at(-1);
+returnlastSegment===undefined ? 'Local file' : decodePathSegment(lastSegment);
+}
+
 /** Return the browser storage key for a parsed page identity. */
 exportfunctiongetAnnotationStorageKey(pageId: PageId): AnnotationStorageKey{
 return`annotations:${pageId}`;
 }
 
 /** Return the exact storage prefix shared by all pages on a website. */
 exportfunctiongetAnnotationStoragePrefix(siteId: SiteId): AnnotationStoragePrefix{
-return`annotations:${siteId}/`;
+constprefix=`annotations:${siteId}${siteId.endsWith('/') ? '' : '/'}`;
+// SAFETY: the conditional suffix guarantees exactly one trailing slash.
+returnprefixasAnnotationStoragePrefix;
 }
 
 /** Parse a URL and return its annotation storage key, or null when unsupported. */
@@ -66,3 +115,15 @@ export function getAnnotationStoragePrefixForUrl(url: string): AnnotationStorage
 constsiteId=parseSiteId(url);
 returnsiteId===null ? null : getAnnotationStoragePrefix(siteId);
 }
+
+functionisAnnotatableProtocol(protocol: string): boolean{
+returnprotocol==='http:'||protocol==='https:'||protocol==='file:';
+}
+
+functiondecodePathSegment(segment: string): string{
+try{
+returndecodeURIComponent(segment);
+}catch{
+returnsegment;
+}
+}

lib/storage.test.ts

@@ -112,6 +112,31 @@ describe('annotation storage', () => {
 ]);
 });
 
+test('reads and clears local pages by their parent folder',async()=>{
+constarea=newInMemoryStorageArea();
+constindexUrl='file:///Users/ramos/workspaces/guided-review/index.html';
+constdetailsUrl='file:///Users/ramos/workspaces/guided-review/details.html?mode=edit';
+constnestedUrl='file:///Users/ramos/workspaces/guided-review/archive/old.html';
+constotherUrl='file:///Users/ramos/workspaces/other-review/index.html';
+area.seed(getRequiredKey(indexUrl),[annotationFixture('index','index note',indexUrl)]);
+area.seed(getRequiredKey(detailsUrl),[annotationFixture('details','details note',detailsUrl)]);
+area.seed(getRequiredKey(nestedUrl),[annotationFixture('nested','nested note',nestedUrl)]);
+area.seed(getRequiredKey(otherUrl),[annotationFixture('other','other note',otherUrl)]);
+conststorage=createAnnotationStorage(area,deterministicDependencies([]));
+
+expect((awaitstorage.getSiteAnnotations(indexUrl)).map(({ id })=>id).sort()).toEqual([
+'details',
+'index',
+]);
+
+expect(awaitstorage.execute({
+type: 'app-notes:annotation/clear-site',
+url: detailsUrl,
+})).toEqual({_tag: 'site-cleared',clearedPages: 2});
+expect((awaitstorage.getAnnotations(nestedUrl)).map(({ id })=>id)).toEqual(['nested']);
+expect((awaitstorage.getAnnotations(otherUrl)).map(({ id })=>id)).toEqual(['other']);
+});
+
 test('reads valid annotations across every website',async()=>{
 constarea=newInMemoryStorageArea();
 constfinanceUrl='https://www.yahoo.com/finance';
@@ -290,6 +315,22 @@ describe('site Markdown export', () => {
 expect(markdown).toContain('**Note**\n\nInvestigate this architecture');
 expect(markdown).not.toContain('## /');
 });
+
+test('exports local file workspaces with folder and file labels',()=>{
+constindexUrl='file:///Users/ramos/workspaces/guided-review/index.html';
+constdetailsUrl='file:///Users/ramos/workspaces/guided-review/details.html?mode=edit';
+constmarkdown=formatSiteAnnotationsMarkdown(indexUrl,[
+annotationFixture('index','Review the landing state',indexUrl),
+annotationFixture('details','Review the detail state',detailsUrl),
+]);
+
+expect(markdown).toContain('# Notes for guided-review');
+expect(markdown).toContain('2 notes across 2 pages');
+expect(markdown).toContain('## index.html');
+expect(markdown).toContain('file:///Users/ramos/workspaces/guided-review/index.html');
+expect(markdown).toContain('## details.html');
+expect(markdown).not.toContain('?mode=edit');
+});
 });
 
 classInMemoryStorageAreaimplementsAnnotationStorageArea{