@glw907/cairn-cms 0.60.0 → 0.62.1

package/dist/sveltekit/content-routes.js

@@ -7,7 +7,8 @@ import { findConcept } from '../content/concepts.js';
 import { extractCairnLinks, formatCairnToken, rewriteCairnLink } from '../content/links.js';
 import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
 import { deriveExcerpt } from '../content/excerpt.js';
-import { asString } from '../content/identity.js';
+import { asString, entryIdentity } from '../content/identity.js';
+import { buildAddressIndex, addressCollision } from '../content/advisories.js';
 import { isValidId, slugify, filenameFromId, composeDatedId, slugFromId, renameId } from '../content/ids.js';
 import { appCredentials } from '../github/credentials.js';
 import { listMarkdown, readRaw, commitFile, commitFiles } from '../github/repo.js';
@@ -15,6 +16,8 @@ import { branchHeadSha, createBranch, deleteBranch, listBranches } from '../gith
 import { PENDING_PREFIX, pendingBranch, parsePendingBranch } from '../content/pending.js';
 import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks } from '../content/manifest.js';
+import { deriveGettingStarted } from '../content/getting-started.js';
+import { markdownReference } from '../components/markdown-reference.js';
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
 import { dictionaryFileForDialect, DEFAULT_TIDY_MODEL, resolveTidyConventions, parseSiteConfig, setTidy, validateTidyConventions, TidyConventionsError } from '../nav/site-config.js';
@@ -40,19 +43,25 @@ import { buildOrphanScan } from '../media/orphan-scan.js';
 import { repointMediaRef, fillAltForHash } from '../content/media-rewrite.js';
 import { planMediaRewrite } from '../media/rewrite-plan.js';
 import { planBulkDelete } from '../media/bulk-delete-plan.js';
-/** The Worker-side request deadline for the tidy model call: 30 seconds. A tidy call to Sonnet on a
+/**
+ * The Worker-side request deadline for the tidy model call: 30 seconds. A tidy call to Sonnet on a
  *  full entry can run many seconds, so the action bounds it with an AbortSignal and maps the overrun to
  *  a retryable fail(502). This sits well under Cloudflare's per-request wall-clock ceiling (a Worker
  *  invocation can run far longer, but a single subrequest left open near that ceiling would surface as a
  *  platform timeout the action could not shape into a clean retry). 30s comfortably covers a proofread
- *  of the bounded input (see MAX_TIDY_CHARS) while leaving headroom under the platform limit. */
+ *  of the bounded input (see MAX_TIDY_CHARS) while leaving headroom under the platform limit.
+ */
 const DEFAULT_TIDY_TIMEOUT_MS = 30_000;
-/** The fallback site-config path when no nav menu names one: the convention every scaffolded site
+/**
+ * The fallback site-config path when no nav menu names one: the convention every scaffolded site
  *  uses. The settings save edits the same committed YAML the nav editor does, so it resolves the path
- *  from the configured nav menu first and falls back to this default. */
+ *  from the configured nav menu first and falls back to this default.
+ */
 const DEFAULT_SITE_CONFIG_PATH = 'src/lib/site.config.yaml';
-/** Plain-language labels for the known tidy models, so the read-only model fact reads as a name rather
- *  than a bare id. An unknown id falls back to itself. */
+/**
+ * Plain-language labels for the known tidy models, so the read-only model fact reads as a name rather
+ *  than a bare id. An unknown id falls back to itself.
+ */
 const TIDY_MODEL_LABELS = {
     'claude-sonnet-4-6': 'Claude Sonnet',
     'claude-haiku-4-5': 'Claude Haiku',
@@ -61,14 +70,18 @@ const TIDY_MODEL_LABELS = {
 function tidyModelLabel(model) {
     return TIDY_MODEL_LABELS[model] ?? model;
 }
-/** The input cap for a single tidy request: 24000 characters (~6k input tokens). A proofread runs at
+/**
+ * The input cap for a single tidy request: 24000 characters (~6k input tokens). A proofread runs at
  *  roughly input length, so this stays comfortably inside the 30s deadline; a longer entry refuses with
  *  fail(413) and the author tidies a selection instead. The cap is enforced BEFORE the model call, so an
- *  over-long body never spends a token or risks the deadline. */
+ *  over-long body never spends a token or risks the deadline.
+ */
 const MAX_TIDY_CHARS = 24_000;
-/** Resolve the effective preview for one concept: its `byConcept` override wins per key, with
+/**
+ * Resolve the effective preview for one concept: its `byConcept` override wins per key, with
  *  nullish coalescing so an override key that is present but undefined keeps the top-level value.
- *  Stylesheets are always shared, and the `byConcept` map never reaches the client. */
+ *  Stylesheets are always shared, and the `byConcept` map never reaches the client.
+ */
 function resolvePreview(preview, conceptId) {
     if (!preview)
         return null;
@@ -86,6 +99,9 @@ function conceptOf(runtime, params) {
         throw error(404, `Unknown content type: ${params.concept ?? ''}`);
     return concept;
 }
+/**
+ *
+ */
 export function createContentRoutes(runtime, deps = {}) {
     const mintToken = deps.mintToken ?? ((env) => cachedInstallationToken(appCredentials(runtime.backend, env)));
     // The default Anthropic factory builds the real SDK client from the resolved key. Tests inject a fake
@@ -93,15 +109,19 @@ export function createContentRoutes(runtime, deps = {}) {
     // SDK client satisfies TidyClient structurally; the cast names that to the compiler.
     const anthropicClient = deps.anthropic ?? ((opts) => new Anthropic({ apiKey: opts.apiKey }));
     const tidyTimeoutMs = deps.tidyTimeoutMs ?? DEFAULT_TIDY_TIMEOUT_MS;
-    /** Main's manifest, parsed. A missing file starts empty (a fresh repo before the first commit).
-     *  Always read from main: pending branches carry no manifest copy. */
+    /**
+     * Main's manifest, parsed. A missing file starts empty (a fresh repo before the first commit).
+     *  Always read from main: pending branches carry no manifest copy.
+     */
     async function readManifest(token) {
         const raw = await readRaw(runtime.backend, runtime.manifestPath, token);
         return raw === null ? emptyManifest() : parseManifest(raw);
     }
-    /** Parse a committed media.json body to a plain value for parseMediaManifest, degrading a missing
+    /**
+     * Parse a committed media.json body to a plain value for parseMediaManifest, degrading a missing
      *  or corrupt file to null (an empty manifest). The committed file is always our own serialization,
-     *  so the catch only guards a hand-edited or truncated file rather than a normal path. */
+     *  so the catch only guards a hand-edited or truncated file rather than a normal path.
+     */
     function parseMediaJson(raw) {
         if (raw === null)
             return null;
@@ -112,11 +132,13 @@ export function createContentRoutes(runtime, deps = {}) {
             return null;
         }
     }
-    /** The pending entry a `cairn/` ref names, or null for a ref the engine must ignore: a
+    /**
+     * The pending entry a `cairn/` ref names, or null for a ref the engine must ignore: a
      *  malformed name, an id that fails the slug rule (entry paths are built from it, so this is
      *  the path confinement), or a concept this site does not configure. Every ref consumer
      *  (the layout count, the list view, publish-all) applies this one predicate, so a stray
-     *  hand-pushed ref cannot inflate a count it can never clear or reach a contents read. */
+     *  hand-pushed ref cannot inflate a count it can never clear or reach a contents read.
+     */
     function pendingEntryOf(name) {
         const ref = parsePendingBranch(name);
         if (!ref || !isValidId(ref.id))
@@ -124,8 +146,10 @@ export function createContentRoutes(runtime, deps = {}) {
         const concept = findConcept(runtime.concepts, ref.concept);
         return concept ? { concept, id: ref.id } : null;
     }
-    /** Layout load for every admin page: the nav, the user, the active path, the resolved theme,
-     *  and the pending entries behind the topbar's publish-all action. */
+    /**
+     * Layout load for every admin page: the nav, the user, the active path, the resolved theme,
+     *  and the pending entries behind the topbar's publish-all action.
+     */
     async function layoutLoad(event) {
         const editor = requireSession(event);
         const cookieTheme = event.cookies?.get('cairn-admin-theme');
@@ -162,6 +186,33 @@ export function createContentRoutes(runtime, deps = {}) {
             pendingEntries,
         };
     }
+    /**
+     * Load the Help home: the getting-started progress derived from the committed manifest and the open
+     *  pending branches, the markdown reference, and the runtime's support contact. A GitHub failure
+     *  degrades to an empty corpus (0 of 3) rather than failing the screen, the same fail-safe layoutLoad uses.
+     */
+    async function helpLoad(event) {
+        requireSession(event);
+        let manifest = emptyManifest();
+        let pending = [];
+        try {
+            const token = await mintToken(event.platform?.env ?? {});
+            manifest = await readManifest(token);
+            const names = await listBranches(runtime.backend, PENDING_PREFIX, token);
+            pending = names.flatMap((name) => {
+                const entry = pendingEntryOf(name);
+                return entry ? [{ concept: entry.concept.id, id: entry.id }] : [];
+            });
+        }
+        catch (err) {
+            log.warn('github.unreachable', { scope: 'help', error: String(err) });
+        }
+        return {
+            gettingStarted: deriveGettingStarted(manifest, pending),
+            reference: markdownReference,
+            supportContact: runtime.supportContact,
+        };
+    }
     /** Redirect /admin to the first concept's list (spec §7.6: land on the first concept). */
     function indexRedirect() {
         const first = runtime.concepts[0];
@@ -169,8 +220,10 @@ export function createContentRoutes(runtime, deps = {}) {
             throw error(404, 'No content types configured');
         throw redirect(307, `/admin/${first.id}`);
     }
-    /** Read a file's frontmatter for its list row, degrading to the id on any read failure. The
-     *  repo defaults to main; a pending entry (edited or branch-only) passes its pending branch. */
+    /**
+     * Read a file's frontmatter for its list row, degrading to the id on any read failure. The
+     *  repo defaults to main; a pending entry (edited or branch-only) passes its pending branch.
+     */
     async function summarize(file, token, status, repo = runtime.backend) {
         try {
             const raw = await readRaw(repo, file.path, token);
@@ -188,17 +241,21 @@ export function createContentRoutes(runtime, deps = {}) {
             return { id: file.id, title: file.id, date: null, draft: false, status, summary: null };
         }
     }
-    /** Read an entry's list row from its pending branch, so a pending title or draft change shows
+    /**
+     * Read an entry's list row from its pending branch, so a pending title or draft change shows
      *  in the list instead of reading as a lost save. summarize degrades a failed or empty read to
-     *  an id-only row, so a ghost ref still lists. */
+     *  an id-only row, so a ghost ref still lists.
+     */
     function pendingRow(concept, id, status, token) {
         return summarize({ id, path: `${concept.dir}/${filenameFromId(id)}` }, token, status, {
             ...runtime.backend,
             branch: pendingBranch(concept.id, id),
         });
     }
-    /** The per-file crawl, kept only for a repo with no committed manifest yet: list main's files
-     *  and read each one for its row, with edited and new rows reading branch-first. */
+    /**
+     * The per-file crawl, kept only for a repo with no committed manifest yet: list main's files
+     *  and read each one for its row, with edited and new rows reading branch-first.
+     */
     async function crawlEntries(concept, pendingIds, token) {
         const files = await listMarkdown(runtime.backend, concept.dir, token);
         const entries = await Promise.all(files.map((f) => (pendingIds.has(f.id) ? pendingRow(concept, f.id, 'edited', token) : summarize(f, token, 'published'))));
@@ -207,12 +264,14 @@ export function createContentRoutes(runtime, deps = {}) {
         const newRows = await Promise.all([...pendingIds].filter((id) => !listed.has(id)).map((id) => pendingRow(concept, id, 'new', token)));
         return [...entries, ...newRows];
     }
-    /** List a concept's entries with their publish status. Published rows project straight from
+    /**
+     * List a concept's entries with their publish status. Published rows project straight from
      *  main's manifest, which publish, delete, and rename keep atomically in sync with main, so
      *  the listing costs one manifest read plus one branch read per pending entry rather than one
      *  read per file. A manifest row with a pending ref is `edited` and reads branch-first; a ref
      *  with no manifest row appends a `new` row read from its branch. A listing failure degrades
-     *  to an inline error, not a thrown 500. */
+     *  to an inline error, not a thrown 500.
+     */
     async function listLoad(event) {
         requireSession(event);
         const concept = conceptOf(runtime, event.params);
@@ -256,12 +315,14 @@ export function createContentRoutes(runtime, deps = {}) {
             return { ...base, entries: [], error: 'Could not load this content type from GitHub.' };
         }
     }
-    /** The admin Media Library load: union the media manifest across main and every open cairn/*
+    /**
+     * The admin Media Library load: union the media manifest across main and every open cairn/*
      *  branch (so a not-yet-published asset shows), project each row through the shared
      *  mediaLibraryEntry helper, and attach the cross-branch where-used overlay keyed by content
      *  hash. The assets union and the usage overlay degrade independently: a usage-build failure
      *  still lists the assets with an empty overlay, and a wholesale read failure degrades to the
-     *  assets gathered so far rather than a thrown 500, mirroring listLoad's posture. */
+     *  assets gathered so far rather than a thrown 500, mirroring listLoad's posture.
+     */
     async function mediaLibraryLoad(event) {
         requireSession(event);
         // Read the flash flags a redirected action carried back, mirroring listLoad's `?error`/
@@ -427,10 +488,10 @@ export function createContentRoutes(runtime, deps = {}) {
         const published = mainRaw !== null;
         const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
         const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
+        const manifest = manifestRaw !== null ? parseManifest(manifestRaw) : null;
         let linkTargets = [];
         let inbound = [];
-        if (manifestRaw !== null) {
-            const manifest = parseManifest(manifestRaw);
+        if (manifest !== null) {
             linkTargets = manifest.entries.map((e) => ({
                 concept: e.concept,
                 id: e.id,
@@ -441,6 +502,32 @@ export function createContentRoutes(runtime, deps = {}) {
             }));
             inbound = inboundLinks(manifest, concept.id, id);
         }
+        // The cross-branch address-collision advisory: warn-and-allow, never a gate. Build it from the
+        // same manifest read above (no second read) and degrade to no notice on any read failure, so a
+        // transient GitHub error never blocks the editor. Skip the build with no manifest to index.
+        let advisories = [];
+        if (manifest !== null) {
+            try {
+                const identity = entryIdentity(concept, path, parsed.frontmatter);
+                const addressIndex = await buildAddressIndex(runtime.backend, token, runtime.concepts, manifest);
+                const other = addressCollision(addressIndex, { concept: concept.id, id }, identity.permalink);
+                if (other) {
+                    const otherConcept = findConcept(runtime.concepts, other.concept);
+                    const label = otherConcept ? otherConcept.label : other.concept;
+                    advisories = [
+                        {
+                            kind: 'address-collision',
+                            severity: 'warn',
+                            message: `Another ${label} already uses the address ${identity.permalink}. Publish this one and it replaces the other at that address.`,
+                            actions: [{ label: `Open ${other.title}`, href: `/admin/${other.concept}/${other.id}` }],
+                        },
+                    ];
+                }
+            }
+            catch (err) {
+                log.warn('github.unreachable', { scope: 'edit-advisories', error: String(err) });
+            }
+        }
         // Project the one committed media manifest read two ways: the minimal resolver triple the preview
         // needs (`mediaTargets`) and the picker's full human layer (`mediaLibrary`), both keyed by hash.
         // A corrupt committed file degrades both to empty, not a throw.
@@ -487,16 +574,21 @@ export function createContentRoutes(runtime, deps = {}) {
                 model: runtime.tidy?.model || DEFAULT_TIDY_MODEL,
                 conventions: resolveTidyConventions(runtime.tidy?.conventions),
             },
+            advisories,
         };
     }
-    /** The repo-relative personal-dictionary path, defaulting a hand-built runtime that omits it to the
-     *  same `.cairn/` content root the manifests use. composeRuntime always fills `dictionaryPath`. */
+    /**
+     * The repo-relative personal-dictionary path, defaulting a hand-built runtime that omits it to the
+     *  same `.cairn/` content root the manifests use. composeRuntime always fills `dictionaryPath`.
+     */
     function dictionaryFilePath() {
         return runtime.dictionaryPath ?? 'src/content/.cairn/dictionary.txt';
     }
-    /** Log a failed commit: a conflict is the expected last-writer-wins outcome, so it warns with a
+    /**
+     * Log a failed commit: a conflict is the expected last-writer-wins outcome, so it warns with a
      *  reason; any other error is unexpected and logs at error with the stringified cause. Publish
-     *  failures carry the same shape under their own event name. */
+     *  failures carry the same shape under their own event name.
+     */
     function logCommitFailed(fields, err, event = 'commit.failed') {
         if (isConflict(err)) {
             log.warn(event, { ...fields, reason: 'conflict' });
@@ -505,9 +597,11 @@ export function createContentRoutes(runtime, deps = {}) {
             log.error(event, { ...fields, error: String(err) });
         }
     }
-    /** The shared commit catch for the entry actions: log the failure, bounce a conflict back to
+    /**
+     * The shared commit catch for the entry actions: log the failure, bounce a conflict back to
      *  `page` with `message` as the inline error, and rethrow anything else. `query` keeps any extra
-     *  params the bounce must carry (saveAction's `&new=1`). */
+     *  params the bounce must carry (saveAction's `&new=1`).
+     */
     function commitFailure(fields, err, page, message, opts = {}) {
         logCommitFailed(fields, err, opts.event);
         if (isConflict(err)) {
@@ -515,11 +609,13 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw err;
     }
-    /** The shared core of save and publish: parse the posted form, validate the frontmatter,
+    /**
+     * The shared core of save and publish: parse the posted form, validate the frontmatter,
      *  guard the body's cairn links, ensure the pending branch, and commit the entry file there
      *  with the session editor as author. Returns the broken-link fail for the page to render,
      *  or the held state; throws the redirect bounces save has always thrown (invalid
-     *  frontmatter, a branch-commit conflict). Main stays untouched. */
+     *  frontmatter, a branch-commit conflict). Main stays untouched.
+     */
     async function saveToBranch(event, editor, concept, id) {
         const path = `${concept.dir}/${filenameFromId(id)}`;
         const form = await event.request.formData();
@@ -604,8 +700,10 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         return { path, markdown, branch, branchSha, manifest: upserted, draftLinks, token, mediaChange };
     }
-    /** Save an edit: validate, then commit to the entry's pending branch with the session editor
-     *  as author. Main and its manifest stay untouched until publish. Fails safe on 409. */
+    /**
+     * Save an edit: validate, then commit to the entry's pending branch with the session editor
+     *  as author. Main and its manifest stay untouched until publish. Fails safe on 409.
+     */
     async function saveAction(event) {
         const editor = requireSession(event);
         const concept = conceptOf(runtime, event.params);
@@ -622,12 +720,14 @@ export function createContentRoutes(runtime, deps = {}) {
             : 'saved=1';
         throw redirect(303, `/admin/${concept.id}/${id}?${savedQuery}`);
     }
-    /** Publish an entry: validate and hold the posted form exactly like save (the branch gets the
+    /**
+     * Publish an entry: validate and hold the posted form exactly like save (the branch gets the
      *  same commit), then copy that markdown to main with the manifest row upserted in one atomic
      *  commit. Publish-what-you-see: the posted form is the published content, so text typed
      *  after the last save goes live too, and publish works regardless of prior branch state.
      *  The branch is deleted only when its head still matches the commit this action made; a
-     *  concurrent save moved it, so the entry stays pending and the next publish picks it up. */
+     *  concurrent save moved it, so the entry stays pending and the next publish picks it up.
+     */
     async function publishAction(event) {
         const editor = requireSession(event);
         const concept = conceptOf(runtime, event.params);
@@ -647,10 +747,37 @@ export function createContentRoutes(runtime, deps = {}) {
         ];
         if (mediaChange)
             changes.push(mediaChange);
+        // The cross-branch address-collision re-check: warn-and-allow, last-write-wins, never a gate.
+        // Resolve this entry's own address the way editLoad does and look it up in the index built from
+        // the same manifest the publish carries. The read fails open: a thrown index build degrades to
+        // no event and the publish proceeds, so a transient GitHub error never blocks a publish.
+        let address = '';
+        let collision = null;
+        try {
+            const { frontmatter } = parseMarkdown(markdown);
+            address = entryIdentity(concept, path, frontmatter).permalink;
+            const addressIndex = await buildAddressIndex(runtime.backend, token, runtime.concepts, manifest);
+            collision = addressCollision(addressIndex, { concept: concept.id, id }, address);
+        }
+        catch (err) {
+            // Fail open, the same as editLoad: a thrown index build degrades to no event and the publish
+            // proceeds. Log it so a persistently failing advisory build is diagnosable, not invisible.
+            collision = null;
+            log.warn('github.unreachable', { scope: 'publish-advisories', error: String(err) });
+        }
         const commitFields = { concept: concept.id, id, editor: editor.email };
         try {
             await commitFiles(runtime.backend, changes, { message: `Publish ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
             log.info('entry.published', { ...commitFields, batch: false });
+            // Only after the publish lands: a diagnostic that a live address now has a new owner.
+            if (collision) {
+                log.warn('publish.address_collision', {
+                    editor: editor.email,
+                    address,
+                    displacedConcept: collision.concept,
+                    displacedId: collision.id,
+                });
+            }
         }
         catch (err) {
             // The branch already holds the just-committed edits, so a conflict here loses nothing.
@@ -664,10 +791,12 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, `/admin/${concept.id}/${id}?published=1`);
     }
-    /** Publish every pending entry site-wide: one atomic commit on main carrying each branch's
+    /**
+     * Publish every pending entry site-wide: one atomic commit on main carrying each branch's
      *  entry file plus the manifest with every row upserted, then delete the consumed branches.
      *  Mounted on the concept list shim, but the topbar posts here from anywhere, so the route's
-     *  concept param is ignored and the redirect lands on the first configured concept. */
+     *  concept param is ignored and the redirect lands on the first configured concept.
+     */
     async function publishAllAction(event) {
         const editor = requireSession(event);
         const first = runtime.concepts[0];
@@ -745,8 +874,10 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, `${listPage}?publishedAll=${published.length}`);
     }
-    /** Discard an entry's pending edits: delete the branch (tolerant of already-gone) and return to
-     *  the edit page when the entry lives on main, else to the list (the entry is gone entirely). */
+    /**
+     * Discard an entry's pending edits: delete the branch (tolerant of already-gone) and return to
+     *  the edit page when the entry lives on main, else to the list (the entry is gone entirely).
+     */
     async function discardAction(event) {
         const editor = requireSession(event);
         const concept = conceptOf(runtime, event.params);
@@ -761,11 +892,13 @@ export function createContentRoutes(runtime, deps = {}) {
             throw redirect(303, `/admin/${concept.id}/${id}?discarded=1`);
         throw redirect(303, `/admin/${concept.id}`);
     }
-    /** The shared delete core. Block-until-clean: refuse while inbound links exist (naming them), else
+    /**
+     * The shared delete core. Block-until-clean: refuse while inbound links exist (naming them), else
      *  commit the file removal and the manifest patch in one commit. The inbound recheck here is the
      *  authoritative gate, closing the load-to-delete race. Both the editor delete (id from params) and
      *  the list delete (id from the form body) call this with an already-validated id, so the guard is
-     *  enforced once. */
+     *  enforced once.
+     */
     async function deleteEntry(event, concept, id, editor) {
         const path = `${concept.dir}/${filenameFromId(id)}`;
         const token = await mintToken(event.platform?.env ?? {});
@@ -832,10 +965,12 @@ export function createContentRoutes(runtime, deps = {}) {
             throw error(400, 'Invalid entry id');
         return deleteEntry(event, concept, id, editor);
     }
-    /** Rename an entry: change its slug, move the file, and rewrite every inbound cairn token in one
+    /**
+     * Rename an entry: change its slug, move the file, and rewrite every inbound cairn token in one
      *  atomic commit, so no internal link breaks. The collision check and the inbound recompute here
      *  are the authoritative gate. The same last-writer-wins manifest race as save and delete applies,
-     *  caught by the build's fail-closed backstop. */
+     *  caught by the build's fail-closed backstop.
+     */
     async function renameAction(event) {
         const editor = requireSession(event);
         const concept = conceptOf(runtime, event.params);
@@ -1042,7 +1177,8 @@ export function createContentRoutes(runtime, deps = {}) {
     const MEDIA_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
     /** A 16-hex content-hash prefix, the immutable asset key. */
     const MEDIA_HASH_RE = /^[0-9a-f]{16}$/;
-    /** Safe-delete a committed media asset. The gate rechecks usage server-side against a FRESH index
+    /**
+     * Safe-delete a committed media asset. The gate rechecks usage server-side against a FRESH index
      *  read at delete time (never a client-passed count), mirroring deleteEntry's authoritative inbound
      *  recheck. An in-use asset refuses unless the form carries the typed-slug override (the in-use
      *  alertdialog's type-to-confirm). When confirmed, the order is load-bearing: commit the manifest
@@ -1059,7 +1195,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *  a referenced asset for an orphan. There is an inherent stale-read window between the recheck and
      *  the commit (no sha-guard ties them); it is bounded because the resolver and the route key on the
      *  hash, so a reference added in that window still resolves to bytes that may be gone, the same
-     *  delete-races-an-edit window every safe delete carries. */
+     *  delete-races-an-edit window every safe delete carries.
+     */
     async function mediaDeleteAction(event) {
         const editor = requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1144,7 +1281,8 @@ export function createContentRoutes(runtime, deps = {}) {
         log.info('media.deleted', { editor: editor.email, hash });
         throw redirect(303, '/admin/media?deleted=1');
     }
-    /** Bulk safe-delete a multi-select of committed media assets. This is mediaDeleteAction extended to
+    /**
+     * Bulk safe-delete a multi-select of committed media assets. This is mediaDeleteAction extended to
      *  many items, with the same safety primitives and one rule that defines the batch: the gate is ONE
      *  shared strict cross-branch usage index built per batch, never N per-item reads (N strict reads
      *  would blow the workerd connection budget at many open branches). The fail-closed posture is for
@@ -1162,7 +1300,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *  leaves bytes with no row (a benign orphan) rather than a row pointing at deleted bytes. Each R2
      *  delete is best-effort and batch-resilient: a per-object error is reported in `failed` and never
      *  aborts the rest of the batch. The result is an itemized 207-style summary the component renders
-     *  (deleted / skipped with reasons / failed); there is no success redirect. */
+     *  (deleted / skipped with reasons / failed); there is no success redirect.
+     */
     async function mediaBulkDelete(event) {
         const editor = requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1245,7 +1384,8 @@ export function createContentRoutes(runtime, deps = {}) {
         log.info('media.bulk_deleted', { editor: editor.email, deleted: deleted.length, skipped: plan.skipped.length });
         return { deleted, skipped: plan.skipped, failed };
     }
-    /** The on-demand orphan scan: a read-only reconcile of stored R2 bytes against the manifest, joined
+    /**
+     * The on-demand orphan scan: a read-only reconcile of stored R2 bytes against the manifest, joined
      *  with one strict cross-branch usage index for the broken-reference where-used. It runs only when
      *  requested, never on the loaded index, because it is heavier than the load path: a full R2 list
      *  plus a reconcile pass on top of the strict usage build.
@@ -1259,7 +1399,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *
      *  The result is the OrphanScan projection: orphanedBytes (stored keys with no manifest row, the
      *  purge surface) and brokenRefs (manifest rows whose bytes are gone, read-only, shown with their
-     *  where-used so an operator can re-ingest rather than purge a still-referenced record). */
+     *  where-used so an operator can re-ingest rather than purge a still-referenced record).
+     */
     async function mediaOrphanScan(event) {
         requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1291,7 +1432,8 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         return buildOrphanScan(reconcile, manifest, index);
     }
-    /** Purge orphaned R2 bytes: the one IRREVERSIBLE media action. Raw object bytes live only in R2, not
+    /**
+     * Purge orphaned R2 bytes: the one IRREVERSIBLE media action. Raw object bytes live only in R2, not
      *  in git, so a purged orphan cannot be recovered the way a deleted manifest row can be reverted in
      *  history. The whole action is built around that fact.
      *
@@ -1315,7 +1457,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *
      *  There is no commit. An orphan by definition has no manifest row to remove, so the purge deletes
      *  the R2 object directly. Each delete is best-effort and batch-resilient: a per-object error is
-     *  reported in `failed` and the loop continues; an absent object is a no-op (the R2 contract). */
+     *  reported in `failed` and the loop continues; an absent object is a no-op (the R2 contract).
+     */
     async function mediaPurgeOrphans(event) {
         const editor = requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1383,10 +1526,12 @@ export function createContentRoutes(runtime, deps = {}) {
         log.info('media.orphans_purged', { editor: editor.email, purged: purged.length });
         return { purged, skippedClaimed, failed };
     }
-    /** Edit a committed asset's metadata: its display name, slug, and default alt. A single media.json
+    /**
+     * Edit a committed asset's metadata: its display name, slug, and default alt. A single media.json
      *  row commit, with NO reference rewrite: the resolver and the delivery route key on the hash, so a
      *  rename never breaks an existing `media:` reference. The default alt is the asset's value for the
-     *  next placement, never a propagating edit of the alt already committed in existing placements. */
+     *  next placement, never a propagating edit of the alt already committed in existing placements.
+     */
     async function mediaUpdateAction(event) {
         const editor = requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1416,13 +1561,16 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, '/admin/media?updated=1');
     }
-    /** Build the canonical `media:` token for a replacement, treating a slug that fails the grammar (or
+    /**
+     * Build the canonical `media:` token for a replacement, treating a slug that fails the grammar (or
      *  an empty one) as absent so the bare-hash form is used. The slug is cosmetic: the resolver keys on
-     *  the hash, so a missing slug still resolves. Shared by the preview and apply token construction. */
+     *  the hash, so a missing slug still resolves. Shared by the preview and apply token construction.
+     */
     function replacementToken(slug, hash) {
         return mediaToken({ slug: MEDIA_SLUG_RE.test(slug) ? slug : null, hash });
     }
-    /** Preview a replace-in-place: the display-only fetch action (the 2a transport). It plans the rewrite
+    /**
+     * Preview a replace-in-place: the display-only fetch action (the 2a transport). It plans the rewrite
      *  of every published main entry that references `oldHash` to the new asset's `media:` token, enriches
      *  each with its title and permalink, and returns the plan plus the report-only cross-branch delta.
      *  It commits nothing. The plan runs strict (fail-closed): an unverifiable usage read returns a 503
@@ -1432,7 +1580,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *  the `X-Cairn-CSRF` header (the raw-body transport, no form-CSRF), and a `MediaReplacePreviewPlan`
      *  returned as the 200 ActionResult the client reads. A refusal rides a `fail(status, ...)` envelope
      *  with the MediaReplaceFailure shape (the same fail shape the apply uses), so the client reads
-     *  `type`/`status` from the body, never the HTTP status. */
+     *  `type`/`status` from the body, never the HTTP status.
+     */
     async function mediaReplacePreview(event) {
         // CSRF first: this is a raw-body (JSON) POST, so the header witness is the authority, like the
         // upload action. A failed check refuses before the session read or any GitHub call.
@@ -1498,7 +1647,8 @@ export function createContentRoutes(runtime, deps = {}) {
         });
         return { affectedCount: plan.affectedCount, entries, branchDelta: plan.branchDelta };
     }
-    /** Apply a replace-in-place: rewrite every published main entry that references the old asset to the
+    /**
+     * Apply a replace-in-place: rewrite every published main entry that references the old asset to the
      *  new asset's `media:` token, and add the new media.json row, in ONE atomic commit. The plan is
      *  re-derived here from a FRESH read (never a client-passed plan), so a concurrent edit between the
      *  preview and the apply is rewritten too. EVERY replace is gated behind the typed-slug confirm
@@ -1509,7 +1659,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *
      *  No R2 operation: the new bytes were already stored put-first by the upload action, and the old
      *  bytes are KEPT (the old row stays in media.json), so this action writes only to git and never
-     *  resolves the bucket binding. It guards `resolvedAssets.enabled` for the media-off case only. */
+     *  resolves the bucket binding. It guards `resolvedAssets.enabled` for the media-off case only.
+     */
     async function mediaReplaceApply(event) {
         const editor = requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1598,7 +1749,8 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, '/admin/media?replaced=1');
     }
-    /** Preview an alt-propagation: the display-only fetch action (the 2a transport). It plans filling the
+    /**
+     * Preview an alt-propagation: the display-only fetch action (the 2a transport). It plans filling the
      *  asset's default alt across every published main entry that references it, bucketing each placement
      *  (a will-fill empty alt, a customized alt left as-is, a decorative hero skipped), and returns the
      *  enriched entries, the report-only cross-branch delta, and the bucket counts. It commits nothing.
@@ -1608,7 +1760,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *  Wire contract: a fetch POST with the JSON body `{ hash }`, the CSRF token in the `X-Cairn-CSRF`
      *  header (the raw-body transport, no form-CSRF), and a `MediaAltPreviewPlan` returned as the 200
      *  ActionResult the client reads. A refusal rides a `fail(status, ...)` envelope with the
-     *  MediaAltPropagateFailure shape, so the client reads `type`/`status` from the body. */
+     *  MediaAltPropagateFailure shape, so the client reads `type`/`status` from the body.
+     */
     async function mediaAltPreview(event) {
         // CSRF first: a raw-body (JSON) POST, so the header witness is the authority, like the upload and
         // replace-preview actions. A failed check refuses before the session read or any GitHub call.
@@ -1676,14 +1829,16 @@ export function createContentRoutes(runtime, deps = {}) {
         });
         return { entries, branchDelta: plan.branchDelta, counts };
     }
-    /** Apply an alt-propagation: fill the asset's default alt into every empty placement across the
+    /**
+     * Apply an alt-propagation: fill the asset's default alt into every empty placement across the
      *  published corpus (and, on the `overwrite` opt-in, customized placements too), in ONE atomic
      *  commit. The plan is re-derived from a FRESH read (never a client plan). Three deliberate
      *  differences from replace: there is NO typed-slug gate (alt fill is reversible and frequent), there
      *  is NO media.json change (the default alt is READ from the row, never rewritten there), and a
      *  decorative hero is never written regardless of `overwrite` (enforced inside fillAltForHash). A run
      *  that changes nothing commits nothing and still redirects (a no-op success). It fails the operation
-     *  closed on an unverifiable usage read, and writes only entry files in git (no R2 op). */
+     *  closed on an unverifiable usage read, and writes only entry files in git (no R2 op).
+     */
     async function mediaAltApply(event) {
         const editor = requireSession(event);
         const token = await mintToken(event.platform?.env ?? {});
@@ -1735,19 +1890,25 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, '/admin/media?altPropagated=1');
     }
-    /** The cap on a personal-dictionary word, matched by isValidDictionaryWord. A word is one line, so
+    /**
+     * The cap on a personal-dictionary word, matched by isValidDictionaryWord. A word is one line, so
      *  this bounds an abusive input; the real authority is the per-character validation, which rejects
-     *  whitespace and control bytes so a body can never inject an extra line into the committed file. */
+     *  whitespace and control bytes so a body can never inject an extra line into the committed file.
+     */
     const MAX_DICTIONARY_WORD = 64;
-    /** The cap on the words a single add request carries: an editor adds a handful at save time, never
-     *  a flood. Past this the body is treated as abusive and the surplus is dropped. */
+    /**
+     * The cap on the words a single add request carries: an editor adds a handful at save time, never
+     *  a flood. Past this the body is treated as abusive and the surplus is dropped.
+     */
     const MAX_DICTIONARY_BATCH = 100;
-    /** Read the committed personal dictionary, merge the validated additions in sorted order, and commit
+    /**
+     * Read the committed personal dictionary, merge the validated additions in sorted order, and commit
      *  the canonical file back. Shared by the first attempt and the post-conflict retry, so both re-read
      *  the head and re-merge the same additions; the merge is order-independent, so a concurrent editor's
      *  word that already landed is preserved and the result is the same sorted set regardless of order.
      *  Returns the merged word list. Throws CommitConflictError (via commitFiles) when the branch moves
-     *  under the commit, which the caller catches to retry once. */
+     *  under the commit, which the caller catches to retry once.
+     */
     async function mergeAndCommitDictionary(token, additions, editor) {
         const path = dictionaryFilePath();
         // The existing file as its canonical sorted set, so a no-op add is detected against the same
@@ -1762,25 +1923,31 @@ export function createContentRoutes(runtime, deps = {}) {
         await commitFiles(runtime.backend, [{ path, content: serializeDictionary(merged) }], { message: `Add to dictionary: ${additions.join(', ')}`, author: { name: editor.displayName, email: editor.email } }, token);
         return merged;
     }
-    /** The repo-relative site-config path the settings save reads and commits. It is the same committed
+    /**
+     * The repo-relative site-config path the settings save reads and commits. It is the same committed
      *  YAML the nav editor edits, so it comes from the configured nav menu first and falls back to the
-     *  scaffold default when no menu is configured. */
+     *  scaffold default when no menu is configured.
+     */
     function siteConfigPath() {
         return runtime.navMenu?.configPath ?? DEFAULT_SITE_CONFIG_PATH;
     }
-    /** Read whether the Anthropic API key secret is present in the load's env. A presence flag for the
+    /**
+     * Read whether the Anthropic API key secret is present in the load's env. A presence flag for the
      *  truthful visibility gate, never the key itself: the key is a Worker secret, so this only reports
-     *  that a non-empty `ANTHROPIC_API_KEY` exists and the value never leaves the server. */
+     *  that a non-empty `ANTHROPIC_API_KEY` exists and the value never leaves the server.
+     */
     function keyConfigured(event) {
         const env = (event.platform?.env ?? {});
         return typeof env.ANTHROPIC_API_KEY === 'string' && env.ANTHROPIC_API_KEY.length > 0;
     }
-    /** Load the two-tier tidy settings (spec 2.8, Task 15). The developer tier (enabled, key, model) is
+    /**
+     * Load the two-tier tidy settings (spec 2.8, Task 15). The developer tier (enabled, key, model) is
      *  read-only; the editor tier is the resolved conventions block. The visibility gate is truthful: the
      *  `enabled` flag is true only when `tidy.enabled` is set AND the key is present, so the screen renders
      *  the convention list only then and the honest gate note otherwise. No secret is returned: only a
      *  presence flag for the key. The conventions come straight from the runtime config (the same source
-     *  the tidy action's prompt reads), so the screen and the prompt can never diverge. */
+     *  the tidy action's prompt reads), so the screen and the prompt can never diverge.
+     */
     function settingsLoad(event) {
         requireSession(event);
         const tidy = runtime.tidy;
@@ -1798,13 +1965,15 @@ export function createContentRoutes(runtime, deps = {}) {
             error: event.url.searchParams.get('error'),
         };
     }
-    /** Save the editor-tier tidy conventions: validate the posted block, then read-modify-commit it into
+    /**
+     * Save the editor-tier tidy conventions: validate the posted block, then read-modify-commit it into
      *  the same committed YAML the nav editor writes, with the session editor as author. The transport is
      *  the nav save's exactly: a form POST carrying the conventions JSON, the read-modify-commit through
      *  `commitFile`, and a stale-SHA `isConflict` bounced back as a reload prompt. Only the conventions
      *  block is written (setTidy leaves `tidy.enabled` and `tidy.model` untouched), so an editor's save can
      *  never flip the developer-tier deploy facts. The save refuses before any commit when tidy is not
-     *  enabled, so the gate state's absent editor tier can never be saved past. */
+     *  enabled, so the gate state's absent editor tier can never be saved past.
+     */
     async function settingsSave(event) {
         const editor = requireSession(event);
         // The editor tier does not exist when tidy is off, so a save in that state is a 404 (no editable
@@ -1843,7 +2012,8 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, '/admin/settings?saved=1');
     }
-    /** Add a word (or batch) to the git-committed personal dictionary (spec 1.6). The transport mirrors
+    /**
+     * Add a word (or batch) to the git-committed personal dictionary (spec 1.6). The transport mirrors
      *  the media raw-body actions exactly: a `text/plain` POST, the CSRF token in `X-Cairn-CSRF` validated
      *  by validateCsrfHeader (CSRF first, then the session), and a small JSON body `{ word }` or
      *  `{ words }`. It reads the current file from the default branch, inserts the validated words in
@@ -1858,7 +2028,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *  Input validation is load-bearing here: this commits to the repo from request input, so every word
      *  is length-bounded and rejected if it carries whitespace or control characters (a word is one
      *  line), and the batch is capped. A body that yields no valid word refuses with a 400 and commits
-     *  nothing, so the committed file can never gain an injected or empty line. */
+     *  nothing, so the committed file can never gain an injected or empty line.
+     */
     async function addDictionaryWord(event) {
         // CSRF first: a raw-body (JSON) POST, so the header witness is the authority, like the upload and
         // media actions. A failed check refuses before the session read or any GitHub call.
@@ -1911,7 +2082,8 @@ export function createContentRoutes(runtime, deps = {}) {
             }
         }
     }
-    /** Tidy: a light LLM copy-edit of the author's markdown (spec 2.1). The first remote model call in
+    /**
+     * Tidy: a light LLM copy-edit of the author's markdown (spec 2.1). The first remote model call in
      *  the library, so this is the highest-blast-radius server action: untrusted content and the Anthropic
      *  API key. The transport mirrors the media raw-body actions (a `text/plain` POST carrying JSON
      *  `{ text, scope }`, the CSRF token in `X-Cairn-CSRF`, the response deserialized by the client), with
@@ -1929,7 +2101,8 @@ export function createContentRoutes(runtime, deps = {}) {
      *  prompt's injection framing (Task 10) treats it as data. The API key never leaves the action: it is
      *  not returned and not logged, and the log line carries no content. The action commits NOTHING, so a
      *  failed, aborted, or refused tidy can never corrupt the entry; the diff is computed on the client
-     *  (Task 12), so the server stays a thin model-call boundary. */
+     *  (Task 12), so the server stays a thin model-call boundary.
+     */
     async function tidyAction(event) {
         // CSRF first: a raw-body (JSON) POST, so the header witness is the authority. A failed check refuses
         // before the session read and before any model call.
@@ -2019,10 +2192,12 @@ export function createContentRoutes(runtime, deps = {}) {
         log.info('tidy.done', { editor: editor.email, model: message.model, usage: message.usage });
         return { corrected, model: message.model, usage: message.usage };
     }
-    return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, settingsLoad, settingsSave, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, addDictionaryWord, tidyAction, mintToken };
+    return { layoutLoad, helpLoad, indexRedirect, listLoad, mediaLibraryLoad, settingsLoad, settingsSave, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, addDictionaryWord, tidyAction, mintToken };
 }
-/** The cap, in characters, on the stored alt text. The human fields are display copy, not content,
- *  so a generous cap rejects only abuse-scale input. */
+/**
+ * The cap, in characters, on the stored alt text. The human fields are display copy, not content,
+ *  so a generous cap rejects only abuse-scale input.
+ */
 const MAX_ALT = 160;
 /** The cap, in characters, on the stored display name. */
 const MAX_DISPLAY_NAME = 120;
@@ -2030,8 +2205,10 @@ const MAX_DISPLAY_NAME = 120;
 const MAX_ORIGINAL_FILENAME = 120;
 /** The largest pixel dimension kept; anything larger is treated as bogus and clamped to null. */
 const MAX_DIMENSION = 60000;
-/** Decode a percent-encoded header value, yielding `''` on a malformed sequence or an absent header,
- *  so a hostile `X-Cairn-*` value cannot throw past the gate. */
+/**
+ * Decode a percent-encoded header value, yielding `''` on a malformed sequence or an absent header,
+ *  so a hostile `X-Cairn-*` value cannot throw past the gate.
+ */
 function safeDecode(value) {
     if (value === null)
         return '';
@@ -2042,35 +2219,46 @@ function safeDecode(value) {
         return '';
     }
 }
-/** The basename of a decoded filename: the final path segment after any `/` or `\`. A client value
- *  of `../../evil.png` yields `evil.png`, so no path component reaches the stored record. */
+/**
+ * The basename of a decoded filename: the final path segment after any `/` or `\`. A client value
+ *  of `../../evil.png` yields `evil.png`, so no path component reaches the stored record.
+ */
 function basename(name) {
     const parts = name.split(/[/\\]/);
     return parts[parts.length - 1];
 }
-/** Sort key for a where-used row's origin: published rows rank before branch rows, so the in-use
- *  refusal lists "Published on the site" first, then the edit-branch references. */
+/**
+ * Sort key for a where-used row's origin: published rows rank before branch rows, so the in-use
+ *  refusal lists "Published on the site" first, then the edit-branch references.
+ */
 function originRank(entry) {
     return entry.origin.kind === 'published' ? 0 : 1;
 }
-/** A where-used row's branch name for the secondary sort (the empty string for a published row,
- *  which sorts ahead of any branch by `originRank` already). */
+/**
+ * A where-used row's branch name for the secondary sort (the empty string for a published row,
+ *  which sorts ahead of any branch by `originRank` already).
+ */
 function branchKey(entry) {
     return entry.origin.kind === 'branch' ? entry.origin.branch : '';
 }
-/** The distinct-entry count behind a where-used set: a published use and an edit-branch edit of the
- *  same entry are two rows but one distinct entry, so count by concept/id. */
+/**
+ * The distinct-entry count behind a where-used set: a published use and an edit-branch edit of the
+ *  same entry are two rows but one distinct entry, so count by concept/id.
+ */
 function distinctEntryCount(rows) {
     return new Set(rows.map((e) => `${e.concept}/${e.id}`)).size;
 }
-/** Strip control characters from a human field and cap it at `max` characters. Control characters
- *  (C0 and DEL) never belong in display copy and could corrupt a log line or a committed JSON. */
+/**
+ * Strip control characters from a human field and cap it at `max` characters. Control characters
+ *  (C0 and DEL) never belong in display copy and could corrupt a log line or a committed JSON.
+ */
 function sanitizeField(value, max) {
-    // eslint-disable-next-line no-control-regex
     return value.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, max);
 }
-/** Parse an advisory pixel dimension header. A valid integer in `[1, MAX_DIMENSION]` is kept; an
- *  absent, non-numeric, or out-of-range value becomes null (MediaEntry dimensions are `number | null`). */
+/**
+ * Parse an advisory pixel dimension header. A valid integer in `[1, MAX_DIMENSION]` is kept; an
+ *  absent, non-numeric, or out-of-range value becomes null (MediaEntry dimensions are `number | null`).
+ */
 function clampDimension(value) {
     if (value === null)
         return null;