@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/llms-txt.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/llms-txt.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * `/llms.txt` for a tenant site, in the llmstxt.org format (AGL-2716).\n *\n * The file an agent reads FIRST — before the sitemap, before the homepage — to\n * decide whether this site can answer the question it is holding, and which\n * URL to fetch if it can.\n *\n * ## The format, exactly\n *\n * llmstxt.org specifies, in this order: an H1 with the project name (the ONLY\n * required part), an optional blockquote summary, zero or more non-heading\n * markdown sections, then zero or more H2-delimited sections of \"file lists\" —\n * markdown lists whose items are a required `[name](url)` link optionally\n * followed by `:` and a note.\n *\n * Every H2 section this builder emits is a file list of that shape, INCLUDING\n * the when-to-use section. That is the design decision worth keeping: guidance\n * written as prose tells an agent what the site is about and leaves it to\n * guess a URL, while guidance written as a link list answers \"which address\n * serves this job\" in the same breath. It also keeps the file inside the\n * format rather than beside it.\n *\n * ## What goes in it, and what does not\n *\n * NOT every URL — that is the sitemap's job, and this file links to it. A site\n * with five hundred pages has an llms.txt of the same length as a site with\n * five: identity, what it is for, the handful of entry points that lead\n * everywhere else, and the machine-readable descriptions of its own surface.\n *\n * ## Why the derived guidance is factual and never promotional\n *\n * A site whose author writes nothing still gets a when-to-use section, built\n * from what the site demonstrably HAS: the collections it publishes, the\n * endpoints it answers, the entry counts. Marketing copy in this position is\n * worse than an empty section — an agent scoring a dozen candidate sources\n * discounts a claim it cannot check, and the whole point of the section is to\n * be checkable.\n */\n\n/** A content collection published by the site. */\nexport interface LlmsTxtCollection {\n  /** Public slug — the path segment the list answers at. */\n  slug: string\n  /** Display name, falling back to the slug. */\n  name?: string\n  /** The collection's own description, when the author wrote one. */\n  description?: string\n  /** Published entries, when the count is known and cheap to have. */\n  entryCount?: number\n}\n\n/** One curated page link. */\nexport interface LlmsTxtPage {\n  /** Route path, with or without its leading slash. */\n  path: string\n  /** Link text; the path is used when a screen has no name. */\n  title?: string\n  /** Optional note after the colon. */\n  note?: string\n}\n\n/** Author-written agent guidance, as `host.seo.agent` stores it. */\nexport interface LlmsTxtAgentGuidance {\n  /** \"When to use this site\" — the jobs it is the right answer to. */\n  whenToUse?: string\n  /** How an agent should call it — endpoints, auth, rate limits, etiquette. */\n  howToUse?: string\n}\n\nexport interface LlmsTxtOptions {\n  /** The site's name — the H1, and the only required field in the format. */\n  siteName: string\n  /** Absolute origin, no trailing slash. */\n  origin: string\n  /** The summary blockquote. */\n  description?: string\n  agent?: LlmsTxtAgentGuidance | null\n  pages?: readonly LlmsTxtPage[]\n  collections?: readonly LlmsTxtCollection[]\n  /** Whether this site serves `/search`. */\n  hasSearch?: boolean\n  /** Where a human is reached, when the site publishes one. */\n  contactEmail?: string\n}\n\n/** Path of the agent-guidance file, at the site root, per llmstxt.org. */\nexport const LLMS_TXT_PATH = '/llms.txt'\n\n/** Path of the machine-readable API description. */\nexport const OPENAPI_PATH = '/openapi.json'\n\n/** Join an origin and a path into an absolute URL with exactly one slash. */\nexport function absoluteSiteUrl(origin: string, path: string): string {\n  const base = origin.replace(/\\/+$/, '')\n  if (!path || path === '/') return `${base}/`\n  return `${base}/${String(path).replace(/^\\/+/, '')}`\n}\n\n/**\n * Markdown link text, escaped.\n *\n * Only `[` and `]` — the two characters that can close a link label early and\n * turn the rest of the line into loose text. Escaping more would put\n * backslashes in a page title for no benefit; this is a label, not a document.\n */\nconst label = (value: string): string =>\n  String(value).replace(/\\s+/g, ' ').trim().replace(/([[\\]])/g, '\\\\$1')\n\n/** One file-list item: `- [name](url): note`. */\nconst item = (name: string, url: string, note?: string): string =>\n  note ? `- [${label(name)}](${url}): ${note}` : `- [${label(name)}](${url})`\n\n/** Title-case-ish display name for a slug with no name of its own. */\nfunction nameForSlug(slug: string): string {\n  const words = slug.replace(/[-_]+/g, ' ').trim()\n  return words ? words.charAt(0).toUpperCase() + words.slice(1) : slug\n}\n\n/**\n * The when-to-use items derived from what the site actually publishes.\n *\n * Each is a job an agent might hold, paired with the URL that answers it. The\n * counts and names come from the site's own data, so nothing here is a claim\n * the reader cannot verify by following the link.\n */\nfunction derivedGuidance(options: LlmsTxtOptions): string[] {\n  const { origin, siteName } = options\n  const lines: string[] = []\n  for (const collection of options.collections ?? []) {\n    const name = collection.name || nameForSlug(collection.slug)\n    const count =\n      typeof collection.entryCount === 'number' && collection.entryCount > 0\n        ? `${collection.entryCount} published ${\n            collection.entryCount === 1 ? 'entry' : 'entries'\n          }`\n        : 'the published entries'\n    lines.push(\n      item(\n        name,\n        absoluteSiteUrl(origin, collection.slug),\n        collection.description\n          ? `${label(collection.description)} — ${count}, newest first`\n          : `${count}, newest first. Read this when you need ${label(\n              name.toLowerCase(),\n            )} published by ${label(siteName)}`,\n      ),\n    )\n  }\n  if (options.hasSearch) {\n    lines.push(\n      item(\n        'Search this site',\n        `${absoluteSiteUrl(origin, 'search')}?q=`,\n        'full-text search across this site’s pages and published entries; ' +\n          'append your query to `?q=`',\n      ),\n    )\n  }\n  lines.push(\n    item(\n      'Sitemap index',\n      absoluteSiteUrl(origin, 'sitemap.xml'),\n      'every indexable URL on this site, split into dated child sitemaps',\n    ),\n  )\n  lines.push(\n    item(\n      'OpenAPI description',\n      absoluteSiteUrl(origin, OPENAPI_PATH),\n      'every public endpoint this site serves, with typed parameters, ' +\n        'response schemas and a unique operationId per operation',\n    ),\n  )\n  if (options.contactEmail) {\n    lines.push(\n      item(\n        'Contact a person',\n        `mailto:${options.contactEmail}`,\n        'reach the people who publish this site when the answer is not on it',\n      ),\n    )\n  }\n  return lines\n}\n\n/** Build the `/llms.txt` body. */\nexport function buildLlmsTxt(options: LlmsTxtOptions): string {\n  const { origin } = options\n  const sections: string[] = []\n\n  sections.push(`# ${label(options.siteName || 'Site')}`)\n\n  const description = String(options.description ?? '').replace(/\\s+/g, ' ').trim()\n  if (description) sections.push(`> ${description}`)\n\n  /*\n    The author's own guidance leads, in their words, because they know things\n    this file cannot derive — which questions the site is genuinely the best\n    source for, and which it is not.\n  */\n  const whenToUse = String(options.agent?.whenToUse ?? '').trim()\n  if (whenToUse) sections.push(whenToUse)\n\n  /*\n    The negotiation contract, stated once. An agent that knows a Markdown\n    variant exists asks for it; one that does not, parses HTML it did not need.\n    Both spellings are given because the two conventions have different\n    audiences: `Accept` is acceptmarkdown.com, `.md` is llmstxt.org, and an\n    agent that only knows one of them still gets clean text.\n  */\n  sections.push(\n    'Every page on this site serves a Markdown representation of itself. ' +\n      'Send `Accept: text/markdown`, or append `.md` to any path — ' +\n      `for example \\`${absoluteSiteUrl(origin, 'about.md')}\\`. ` +\n      'Responses vary on `Accept`, so a cache cannot hand you the wrong one.',\n  )\n\n  const howToUse = String(options.agent?.howToUse ?? '').trim()\n  if (howToUse) sections.push(howToUse)\n\n  const guidance = derivedGuidance(options)\n  if (guidance.length) {\n    sections.push(['## When to use this site', ...guidance].join('\\n'))\n  }\n\n  const pages = options.pages ?? []\n  if (pages.length) {\n    sections.push(\n      [\n        '## Pages',\n        ...pages.map((entry) =>\n          item(\n            entry.title || nameForSlug(entry.path.replace(/^\\/+/, '')) || 'Home',\n            absoluteSiteUrl(origin, entry.path),\n            entry.note,\n          ),\n        ),\n      ].join('\\n'),\n    )\n  }\n\n  const collections = options.collections ?? []\n  if (collections.length) {\n    sections.push(\n      [\n        '## Feeds',\n        ...collections.map((collection) =>\n          item(\n            `${collection.name || nameForSlug(collection.slug)} (RSS)`,\n            absoluteSiteUrl(origin, `${collection.slug}/rss.xml`),\n            'newest entries as RSS 2.0',\n          ),\n        ),\n      ].join('\\n'),\n    )\n  }\n\n  return `${sections.join('\\n\\n').trim()}\\n`\n}\n"],"names":["LLMS_TXT_PATH","OPENAPI_PATH","absoluteSiteUrl","origin","path","base","replace","String","label","value","trim","item","name","url","note","nameForSlug","slug","words","charAt","toUpperCase","slice","derivedGuidance","options","siteName","lines","collection","collections","count","entryCount","push","description","toLowerCase","hasSearch","contactEmail","buildLlmsTxt","sections","whenToUse","agent","howToUse","guidance","length","join","pages","map","entry","title"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCC,GAED,gDAAgD,GA8ChD,wEAAwE,GACxE,OAAO,MAAMA,gBAAgB,YAAW;AAExC,kDAAkD,GAClD,OAAO,MAAMC,eAAe,gBAAe;AAE3C,2EAA2E,GAC3E,OAAO,SAASC,gBAAgBC,MAAc,EAAEC,IAAY;IAC1D,MAAMC,OAAOF,OAAOG,OAAO,CAAC,QAAQ;IACpC,IAAI,CAACF,QAAQA,SAAS,KAAK,OAAO,GAAGC,KAAK,CAAC,CAAC;IAC5C,OAAO,GAAGA,KAAK,CAAC,EAAEE,OAAOH,MAAME,OAAO,CAAC,QAAQ,KAAK;AACtD;AAEA;;;;;;CAMC,GACD,MAAME,QAAQ,CAACC,QACbF,OAAOE,OAAOH,OAAO,CAAC,QAAQ,KAAKI,IAAI,GAAGJ,OAAO,CAAC,YAAY;AAEhE,+CAA+C,GAC/C,MAAMK,OAAO,CAACC,MAAcC,KAAaC,OACvCA,OAAO,CAAC,GAAG,EAAEN,MAAMI,MAAM,EAAE,EAAEC,IAAI,GAAG,EAAEC,MAAM,GAAG,CAAC,GAAG,EAAEN,MAAMI,MAAM,EAAE,EAAEC,IAAI,CAAC,CAAC;AAE7E,oEAAoE,GACpE,SAASE,YAAYC,IAAY;IAC/B,MAAMC,QAAQD,KAAKV,OAAO,CAAC,UAAU,KAAKI,IAAI;IAC9C,OAAOO,QAAQA,MAAMC,MAAM,CAAC,GAAGC,WAAW,KAAKF,MAAMG,KAAK,CAAC,KAAKJ;AAClE;AAEA;;;;;;CAMC,GACD,SAASK,gBAAgBC,OAAuB;QAGrBA;IAFzB,MAAM,EAAEnB,MAAM,EAAEoB,QAAQ,EAAE,GAAGD;IAC7B,MAAME,QAAkB,EAAE;IAC1B,KAAK,MAAMC,eAAcH,uBAAAA,QAAQI,WAAW,YAAnBJ,uBAAuB,EAAE,CAAE;QAClD,MAAMV,OAAOa,WAAWb,IAAI,IAAIG,YAAYU,WAAWT,IAAI;QAC3D,MAAMW,QACJ,OAAOF,WAAWG,UAAU,KAAK,YAAYH,WAAWG,UAAU,GAAG,IACjE,GAAGH,WAAWG,UAAU,CAAC,WAAW,EAClCH,WAAWG,UAAU,KAAK,IAAI,UAAU,WACxC,GACF;QACNJ,MAAMK,IAAI,CACRlB,KACEC,MACAV,gBAAgBC,QAAQsB,WAAWT,IAAI,GACvCS,WAAWK,WAAW,GAClB,GAAGtB,MAAMiB,WAAWK,WAAW,EAAE,GAAG,EAAEH,MAAM,cAAc,CAAC,GAC3D,GAAGA,MAAM,wCAAwC,EAAEnB,MACjDI,KAAKmB,WAAW,IAChB,cAAc,EAAEvB,MAAMe,WAAW;IAG7C;IACA,IAAID,QAAQU,SAAS,EAAE;QACrBR,MAAMK,IAAI,CACRlB,KACE,oBACA,GAAGT,gBAAgBC,QAAQ,UAAU,GAAG,CAAC,EACzC,sEACE;IAGR;IACAqB,MAAMK,IAAI,CACRlB,KACE,iBACAT,gBAAgBC,QAAQ,gBACxB;IAGJqB,MAAMK,IAAI,CACRlB,KACE,uBACAT,gBAAgBC,QAAQF,eACxB,oEACE;IAGN,IAAIqB,QAAQW,YAAY,EAAE;QACxBT,MAAMK,IAAI,CACRlB,KACE,oBACA,CAAC,OAAO,EAAEW,QAAQW,YAAY,EAAE,EAChC;IAGN;IACA,OAAOT;AACT;AAEA,gCAAgC,GAChC,OAAO,SAASU,aAAaZ,OAAuB;QAMvBA,mCAiCbA,gBAgBMA;QAzCKA,gBAiBDA;IA9BxB,MAAM,EAAEnB,MAAM,EAAE,GAAGmB;IACnB,MAAMa,WAAqB,EAAE;IAE7BA,SAASN,IAAI,CAAC,CAAC,EAAE,EAAErB,MAAMc,QAAQC,QAAQ,IAAI,SAAS;IAEtD,MAAMO,cAAcvB,QAAOe,uBAAAA,QAAQQ,WAAW,YAAnBR,uBAAuB,IAAIhB,OAAO,CAAC,QAAQ,KAAKI,IAAI;IAC/E,IAAIoB,aAAaK,SAASN,IAAI,CAAC,CAAC,EAAE,EAAEC,aAAa;IAEjD;;;;EAIA,GACA,MAAMM,YAAY7B,gBAAOe,iBAAAA,QAAQe,KAAK,qBAAbf,eAAec,SAAS,mBAAI,IAAI1B,IAAI;IAC7D,IAAI0B,WAAWD,SAASN,IAAI,CAACO;IAE7B;;;;;;EAMA,GACAD,SAASN,IAAI,CACX,yEACE,iEACA,CAAC,cAAc,EAAE3B,gBAAgBC,QAAQ,YAAY,IAAI,CAAC,GAC1D;IAGJ,MAAMmC,WAAW/B,iBAAOe,kBAAAA,QAAQe,KAAK,qBAAbf,gBAAegB,QAAQ,oBAAI,IAAI5B,IAAI;IAC3D,IAAI4B,UAAUH,SAASN,IAAI,CAACS;IAE5B,MAAMC,WAAWlB,gBAAgBC;IACjC,IAAIiB,SAASC,MAAM,EAAE;QACnBL,SAASN,IAAI,CAAC;YAAC;eAA+BU;SAAS,CAACE,IAAI,CAAC;IAC/D;IAEA,MAAMC,SAAQpB,iBAAAA,QAAQoB,KAAK,YAAbpB,iBAAiB,EAAE;IACjC,IAAIoB,MAAMF,MAAM,EAAE;QAChBL,SAASN,IAAI,CACX;YACE;eACGa,MAAMC,GAAG,CAAC,CAACC,QACZjC,KACEiC,MAAMC,KAAK,IAAI9B,YAAY6B,MAAMxC,IAAI,CAACE,OAAO,CAAC,QAAQ,QAAQ,QAC9DJ,gBAAgBC,QAAQyC,MAAMxC,IAAI,GAClCwC,MAAM9B,IAAI;SAGf,CAAC2B,IAAI,CAAC;IAEX;IAEA,MAAMf,eAAcJ,uBAAAA,QAAQI,WAAW,YAAnBJ,uBAAuB,EAAE;IAC7C,IAAII,YAAYc,MAAM,EAAE;QACtBL,SAASN,IAAI,CACX;YACE;eACGH,YAAYiB,GAAG,CAAC,CAAClB,aAClBd,KACE,GAAGc,WAAWb,IAAI,IAAIG,YAAYU,WAAWT,IAAI,EAAE,MAAM,CAAC,EAC1Dd,gBAAgBC,QAAQ,GAAGsB,WAAWT,IAAI,CAAC,QAAQ,CAAC,GACpD;SAGL,CAACyB,IAAI,CAAC;IAEX;IAEA,OAAO,GAAGN,SAASM,IAAI,CAAC,QAAQ/B,IAAI,GAAG,EAAE,CAAC;AAC5C"}

package/src/lib/app-utils/local-storage-budget.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * `localStorage` is ~5 MB per origin and a besigner node map is not small —
+ * a 222-node screen is a substantial fraction of that on its own. Every
+ * writer of a node-map-sized value therefore has to answer "and what happens
+ * when it is full?", and until AGL-1256 none of them did: `writePreviewState`
+ * called `setItem` bare, so a full origin threw a `QuotaExceededError` up
+ * through a click handler.
+ *
+ * The answer here is: drop the least recently written value belonging to the
+ * *same feature* and try again. Scoping eviction to explicit prefixes is the
+ * whole point — a snapshot store must never be able to evict somebody else's
+ * keys (auth markers, the selected org, notification preferences) to make
+ * room for itself.
+ */
+/** How the caller decides which keys may be sacrificed, and in what order. */
+export interface LocalStorageBudgetOptions {
+    key: string;
+    value: string;
+    /**
+     * Only keys starting with one of these may be evicted, and the order is
+     * the sacrifice order: everything under the first prefix goes (oldest
+     * first) before anything under the second is touched. That is what lets a
+     * draft write reclaim regenerable preview snapshots without ever costing
+     * somebody another document's unsaved work. The key being written is never
+     * evicted, even when it matches.
+     */
+    evictPrefixes: string[];
+    /** Defaults to `window.localStorage`; injectable for tests. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem' | 'key' | 'length'>;
+}
+export interface LocalStorageBudgetResult {
+    /** False when the value could not be stored even after evicting. */
+    ok: boolean;
+    /** Keys dropped to make room, oldest first. */
+    evicted: string[];
+}
+/**
+ * Writes `value` at `key`, evicting oldest-first within `evictPrefixes` if
+ * the origin is full.
+ *
+ * Never throws: a caller storing a crash-recovery snapshot must not be able
+ * to break the edit that triggered it. A failed write leaves any existing
+ * value at `key` in place — an older snapshot that is honest about its own
+ * age beats no snapshot at all.
+ */
+export declare function writeLocalStorageWithBudget(options: LocalStorageBudgetOptions): LocalStorageBudgetResult;
+/**
+ * Removes every key under `prefix` whose `updatedAt` is older than `maxAge`.
+ *
+ * Snapshot stores are caches, and a cache with no expiry silently becomes an
+ * archive — see the note in `besigner-draft-store` about why an unbounded
+ * pile of dated snapshots is the wrong shape for this feature specifically.
+ */
+export declare function pruneLocalStorageByAge(options: {
+    prefix: string;
+    maxAgeMs: number;
+    now: number;
+    storage?: LocalStorageBudgetOptions['storage'];
+}): string[];

package/src/lib/app-utils/local-storage-budget.js

@@ -0,0 +1,153 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * `localStorage` is ~5 MB per origin and a besigner node map is not small —
+ * a 222-node screen is a substantial fraction of that on its own. Every
+ * writer of a node-map-sized value therefore has to answer "and what happens
+ * when it is full?", and until AGL-1256 none of them did: `writePreviewState`
+ * called `setItem` bare, so a full origin threw a `QuotaExceededError` up
+ * through a click handler.
+ *
+ * The answer here is: drop the least recently written value belonging to the
+ * *same feature* and try again. Scoping eviction to explicit prefixes is the
+ * whole point — a snapshot store must never be able to evict somebody else's
+ * keys (auth markers, the selected org, notification preferences) to make
+ * room for itself.
+ */ /** How the caller decides which keys may be sacrificed, and in what order. */ /**
+ * Browsers disagree about how a full quota surfaces: a `QuotaExceededError`
+ * by name, Firefox's `NS_ERROR_DOM_QUOTA_REACHED`, or the legacy numeric
+ * codes. Anything else (a `SecurityError` from a blocked origin, say) is not
+ * something eviction can fix and is reported rather than retried.
+ */ function isQuotaExceeded(error) {
+    if (!error || typeof error !== 'object') return false;
+    const { name, code } = error;
+    return name === 'QuotaExceededError' || name === 'NS_ERROR_DOM_QUOTA_REACHED' || code === 22 || code === 1014;
+}
+/**
+ * The sort key for eviction. Values written by this module's callers are
+ * JSON objects carrying `updatedAt`; anything unparseable or missing it
+ * sorts as oldest, because a value we cannot date is a value we cannot
+ * justify keeping ahead of one we can.
+ */ function writtenAt(raw) {
+    if (!raw) return 0;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof (parsed == null ? void 0 : parsed.updatedAt) === 'number' ? parsed.updatedAt : 0;
+    } catch (unused) {
+        return 0;
+    }
+}
+function resolveStorage(storage) {
+    if (storage) return storage;
+    try {
+        return typeof window === 'undefined' ? null : window.localStorage;
+    } catch (unused) {
+        // Storage access can throw outright when cookies are blocked.
+        return null;
+    }
+}
+/**
+ * Writes `value` at `key`, evicting oldest-first within `evictPrefixes` if
+ * the origin is full.
+ *
+ * Never throws: a caller storing a crash-recovery snapshot must not be able
+ * to break the edit that triggered it. A failed write leaves any existing
+ * value at `key` in place — an older snapshot that is honest about its own
+ * age beats no snapshot at all.
+ */ export function writeLocalStorageWithBudget(options) {
+    const { key, value, evictPrefixes } = options;
+    const storage = resolveStorage(options.storage);
+    const evicted = [];
+    if (!storage) return {
+        ok: false,
+        evicted
+    };
+    const attempt = ()=>{
+        try {
+            storage.setItem(key, value);
+            return true;
+        } catch (error) {
+            return isQuotaExceeded(error) ? 'retry' : false;
+        }
+    };
+    let outcome = attempt();
+    if (outcome !== 'retry') return {
+        ok: outcome === true,
+        evicted
+    };
+    // Snapshot the candidates once: `key()` indices shift as we remove, and
+    // re-scanning per eviction is O(n²) on the one path already under stress.
+    const candidates = [];
+    for(let index = 0; index < storage.length; index += 1){
+        const candidate = storage.key(index);
+        if (!candidate || candidate === key) continue;
+        const rank = evictPrefixes.findIndex((prefix)=>candidate.startsWith(prefix));
+        if (rank < 0) continue;
+        candidates.push({
+            key: candidate,
+            rank,
+            writtenAt: writtenAt(storage.getItem(candidate))
+        });
+    }
+    candidates.sort((a, b)=>a.rank - b.rank || a.writtenAt - b.writtenAt);
+    for (const candidate of candidates){
+        try {
+            storage.removeItem(candidate.key);
+        } catch (unused) {
+            continue;
+        }
+        evicted.push(candidate.key);
+        outcome = attempt();
+        if (outcome !== 'retry') return {
+            ok: outcome === true,
+            evicted
+        };
+    }
+    return {
+        ok: false,
+        evicted
+    };
+}
+/**
+ * Removes every key under `prefix` whose `updatedAt` is older than `maxAge`.
+ *
+ * Snapshot stores are caches, and a cache with no expiry silently becomes an
+ * archive — see the note in `besigner-draft-store` about why an unbounded
+ * pile of dated snapshots is the wrong shape for this feature specifically.
+ */ export function pruneLocalStorageByAge(options) {
+    const storage = resolveStorage(options.storage);
+    const pruned = [];
+    if (!storage) return pruned;
+    const stale = [];
+    for(let index = 0; index < storage.length; index += 1){
+        const candidate = storage.key(index);
+        if (!(candidate == null ? void 0 : candidate.startsWith(options.prefix))) continue;
+        const age = options.now - writtenAt(storage.getItem(candidate));
+        if (age > options.maxAgeMs) stale.push(candidate);
+    }
+    for (const candidate of stale){
+        try {
+            storage.removeItem(candidate);
+            pruned.push(candidate);
+        } catch (unused) {
+        // A storage that refuses removal will refuse the write too; the
+        // caller's write path reports that.
+        }
+    }
+    return pruned;
+}
+
+//# sourceMappingURL=local-storage-budget.js.map

package/src/lib/app-utils/local-storage-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/local-storage-budget.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * `localStorage` is ~5 MB per origin and a besigner node map is not small —\n * a 222-node screen is a substantial fraction of that on its own. Every\n * writer of a node-map-sized value therefore has to answer \"and what happens\n * when it is full?\", and until AGL-1256 none of them did: `writePreviewState`\n * called `setItem` bare, so a full origin threw a `QuotaExceededError` up\n * through a click handler.\n *\n * The answer here is: drop the least recently written value belonging to the\n * *same feature* and try again. Scoping eviction to explicit prefixes is the\n * whole point — a snapshot store must never be able to evict somebody else's\n * keys (auth markers, the selected org, notification preferences) to make\n * room for itself.\n */\n\n/** How the caller decides which keys may be sacrificed, and in what order. */\nexport interface LocalStorageBudgetOptions {\n  key: string\n  value: string\n  /**\n   * Only keys starting with one of these may be evicted, and the order is\n   * the sacrifice order: everything under the first prefix goes (oldest\n   * first) before anything under the second is touched. That is what lets a\n   * draft write reclaim regenerable preview snapshots without ever costing\n   * somebody another document's unsaved work. The key being written is never\n   * evicted, even when it matches.\n   */\n  evictPrefixes: string[]\n  /** Defaults to `window.localStorage`; injectable for tests. */\n  storage?: Pick<\n    Storage,\n    'getItem' | 'setItem' | 'removeItem' | 'key' | 'length'\n  >\n}\n\nexport interface LocalStorageBudgetResult {\n  /** False when the value could not be stored even after evicting. */\n  ok: boolean\n  /** Keys dropped to make room, oldest first. */\n  evicted: string[]\n}\n\n/**\n * Browsers disagree about how a full quota surfaces: a `QuotaExceededError`\n * by name, Firefox's `NS_ERROR_DOM_QUOTA_REACHED`, or the legacy numeric\n * codes. Anything else (a `SecurityError` from a blocked origin, say) is not\n * something eviction can fix and is reported rather than retried.\n */\nfunction isQuotaExceeded(error: unknown): boolean {\n  if (!error || typeof error !== 'object') return false\n  const { name, code } = error as { name?: string; code?: number }\n  return (\n    name === 'QuotaExceededError' ||\n    name === 'NS_ERROR_DOM_QUOTA_REACHED' ||\n    code === 22 ||\n    code === 1014\n  )\n}\n\n/**\n * The sort key for eviction. Values written by this module's callers are\n * JSON objects carrying `updatedAt`; anything unparseable or missing it\n * sorts as oldest, because a value we cannot date is a value we cannot\n * justify keeping ahead of one we can.\n */\nfunction writtenAt(raw: string | null): number {\n  if (!raw) return 0\n  try {\n    const parsed = JSON.parse(raw) as { updatedAt?: unknown }\n    return typeof parsed?.updatedAt === 'number' ? parsed.updatedAt : 0\n  } catch {\n    return 0\n  }\n}\n\nfunction resolveStorage(\n  storage: LocalStorageBudgetOptions['storage'],\n): LocalStorageBudgetOptions['storage'] | null {\n  if (storage) return storage\n  try {\n    return typeof window === 'undefined' ? null : window.localStorage\n  } catch {\n    // Storage access can throw outright when cookies are blocked.\n    return null\n  }\n}\n\n/**\n * Writes `value` at `key`, evicting oldest-first within `evictPrefixes` if\n * the origin is full.\n *\n * Never throws: a caller storing a crash-recovery snapshot must not be able\n * to break the edit that triggered it. A failed write leaves any existing\n * value at `key` in place — an older snapshot that is honest about its own\n * age beats no snapshot at all.\n */\nexport function writeLocalStorageWithBudget(\n  options: LocalStorageBudgetOptions,\n): LocalStorageBudgetResult {\n  const { key, value, evictPrefixes } = options\n  const storage = resolveStorage(options.storage)\n  const evicted: string[] = []\n  if (!storage) return { ok: false, evicted }\n\n  const attempt = (): boolean | 'retry' => {\n    try {\n      storage.setItem(key, value)\n      return true\n    } catch (error) {\n      return isQuotaExceeded(error) ? 'retry' : false\n    }\n  }\n\n  let outcome = attempt()\n  if (outcome !== 'retry') return { ok: outcome === true, evicted }\n\n  // Snapshot the candidates once: `key()` indices shift as we remove, and\n  // re-scanning per eviction is O(n²) on the one path already under stress.\n  const candidates: Array<{ key: string; rank: number; writtenAt: number }> =\n    []\n  for (let index = 0; index < storage.length; index += 1) {\n    const candidate = storage.key(index)\n    if (!candidate || candidate === key) continue\n    const rank = evictPrefixes.findIndex((prefix) =>\n      candidate.startsWith(prefix),\n    )\n    if (rank < 0) continue\n    candidates.push({\n      key: candidate,\n      rank,\n      writtenAt: writtenAt(storage.getItem(candidate)),\n    })\n  }\n  candidates.sort((a, b) => a.rank - b.rank || a.writtenAt - b.writtenAt)\n\n  for (const candidate of candidates) {\n    try {\n      storage.removeItem(candidate.key)\n    } catch {\n      continue\n    }\n    evicted.push(candidate.key)\n    outcome = attempt()\n    if (outcome !== 'retry') return { ok: outcome === true, evicted }\n  }\n\n  return { ok: false, evicted }\n}\n\n/**\n * Removes every key under `prefix` whose `updatedAt` is older than `maxAge`.\n *\n * Snapshot stores are caches, and a cache with no expiry silently becomes an\n * archive — see the note in `besigner-draft-store` about why an unbounded\n * pile of dated snapshots is the wrong shape for this feature specifically.\n */\nexport function pruneLocalStorageByAge(options: {\n  prefix: string\n  maxAgeMs: number\n  now: number\n  storage?: LocalStorageBudgetOptions['storage']\n}): string[] {\n  const storage = resolveStorage(options.storage)\n  const pruned: string[] = []\n  if (!storage) return pruned\n\n  const stale: string[] = []\n  for (let index = 0; index < storage.length; index += 1) {\n    const candidate = storage.key(index)\n    if (!candidate?.startsWith(options.prefix)) continue\n    const age = options.now - writtenAt(storage.getItem(candidate))\n    if (age > options.maxAgeMs) stale.push(candidate)\n  }\n  for (const candidate of stale) {\n    try {\n      storage.removeItem(candidate)\n      pruned.push(candidate)\n    } catch {\n      // A storage that refuses removal will refuse the write too; the\n      // caller's write path reports that.\n    }\n  }\n  return pruned\n}\n"],"names":["isQuotaExceeded","error","name","code","writtenAt","raw","parsed","JSON","parse","updatedAt","resolveStorage","storage","window","localStorage","writeLocalStorageWithBudget","options","key","value","evictPrefixes","evicted","ok","attempt","setItem","outcome","candidates","index","length","candidate","rank","findIndex","prefix","startsWith","push","getItem","sort","a","b","removeItem","pruneLocalStorageByAge","pruned","stale","age","now","maxAgeMs"],"mappings":"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"}