@drawnagency/primitives 0.1.109 → 0.1.111

package/src/lib/dexie.ts

@@ -25,9 +25,6 @@ interface SiteIndexRow {
 
 interface MetaRow {
   key: string;
-  lastSavedSha: string | null;
-  mainSha: string | null;
-  lastSavedAt: string | null;
   siteId: string;
 }
 
@@ -63,6 +60,10 @@ interface ContentCacheRow {
   // never as "nothing here".
   mediaManifest?: MediaManifest | null;
   documentManifest?: DocumentManifest | null;
+  // Section files the loader could not read at this sha. Optional for rows
+  // written by older packages. Without it a cache-hit load dropped the warning
+  // banner entirely, so damaged sections were invisible until a fresh fetch.
+  unparseableSectionIds?: string[];
 }
 
 interface PendingMediaRow {
@@ -108,8 +109,13 @@ class EditorDatabase extends Dexie {
   preservedEdits!: Dexie.Table<PreservedEditRow, string>;
   pendingDocuments!: Dexie.Table<PendingDocumentRow, string>;
 
+  /** The site this connection was opened for. Authoritative when the `meta` row
+   *  is missing — see restoreLocalChanges. */
+  readonly siteId: string;
+
   constructor(siteId: string) {
     super(`brand-portal-${siteId}`);
+    this.siteId = siteId;
     this.version(1).stores({
       sections: "sectionId",
       siteIndex: "key",
@@ -257,6 +263,12 @@ function getDb(): EditorDatabase {
 }
 
 export function initEditorStore(siteId: string): void {
+  // Re-initialising for the site we already hold is a no-op: replacing the
+  // instance would leave the old connection open, and an open connection on the
+  // previous version is exactly what makes the next schema bump fire `blocked`
+  // and hang the upgrade forever.
+  if (db?.name === `brand-portal-${siteId}`) return;
+  db?.close();
   db = new EditorDatabase(siteId);
 }
 
@@ -293,7 +305,10 @@ export async function restoreLocalChanges(): Promise<{
 
   if (indexRow) {
     const metaRow = await getDb().meta.get("current");
-    const siteId = metaRow?.siteId ?? "";
+    // Fall back to the connection's own site, never to "". An empty siteId is
+    // not a site — it rides the restored index into the editor and then into the
+    // next save's payload, where nothing downstream can tell it from a real one.
+    const siteId = metaRow?.siteId || getDb().siteId;
     return {
       sections,
       siteIndex: { siteId, pages: indexRow.pages, sections: indexRow.sections, nav: indexRow.nav },
@@ -307,13 +322,17 @@ export async function restoreLocalChanges(): Promise<{
 
 export async function discardLocalChanges(): Promise<void> {
   const database = getDb();
-  await database.transaction("rw", [database.sections, database.siteIndex, database.meta, database.siteConfig, database.pendingMedia, database.pendingMediaDeletions], async () => {
+  await database.transaction("rw", [database.sections, database.siteIndex, database.meta, database.siteConfig, database.pendingMedia, database.pendingMediaDeletions, database.pendingDocuments], async () => {
     await database.sections.clear();
     await database.siteIndex.clear();
     await database.meta.clear();
     await database.siteConfig.clear();
     await database.pendingMedia.clear();
     await database.pendingMediaDeletions.clear();
+    // Without this a staged document survives discard AND history-restore, and
+    // hydratePendingDocuments re-stages it on the next mount — the next save
+    // then commits a document the user explicitly discarded.
+    await database.pendingDocuments.clear();
   });
 }
 
@@ -329,13 +348,7 @@ export async function persistSiteIndex(index: SiteIndex, deletedSections: string
       deletedSections,
       updatedAt: now,
     });
-    await database.meta.put({
-      key: "current",
-      lastSavedSha: null,
-      mainSha: null,
-      lastSavedAt: null,
-      siteId: index.siteId,
-    });
+    await database.meta.put({ key: "current", siteId: index.siteId });
   });
 }
 
@@ -403,12 +416,14 @@ export async function discardSavedChanges(
     "rw",
     [database.sections, database.siteIndex, database.meta, database.siteConfig, database.contentCache],
     async () => {
-      for (const { sectionId, updatedAt } of savedSections) {
-        const row = await database.sections.get(sectionId);
-        if (row && row.updatedAt === updatedAt) {
-          await database.sections.delete(sectionId);
-        }
-      }
+      // One bulkGet, not a get per section: these are serial round-trips inside
+      // an open write transaction, so a 200-section save held the sections,
+      // index, meta, config and contentCache tables locked for 200 of them.
+      const rows = await database.sections.bulkGet(savedSections.map((s) => s.sectionId));
+      const untouched = savedSections
+        .filter((s, i) => rows[i]?.updatedAt === s.updatedAt)
+        .map((s) => s.sectionId);
+      if (untouched.length > 0) await database.sections.bulkDelete(untouched);
       await database.siteIndex.clear();
       await database.meta.clear();
       await database.siteConfig.clear();
@@ -458,13 +473,7 @@ export async function persistAll(
           deletedSections: deletedSectionIds ?? [],
           updatedAt: now,
         });
-        await database.meta.put({
-          key: "current",
-          lastSavedSha: null,
-          mainSha: null,
-          lastSavedAt: null,
-          siteId: siteIndex.siteId,
-        });
+        await database.meta.put({ key: "current", siteId: siteIndex.siteId });
       }
 
       if (siteConfig) {
@@ -478,29 +487,6 @@ export async function persistAll(
   );
 }
 
-export async function updateBranchShas(savedSha: string | null, mainSha: string | null): Promise<void> {
-  const database = getDb();
-  const existing = await database.meta.get("current");
-  if (!existing) return;
-  await database.meta.put({
-    ...existing,
-    lastSavedSha: savedSha,
-    mainSha,
-    lastSavedAt: new Date().toISOString(),
-  });
-}
-
-export async function getBranchShas(): Promise<{ savedSha: string | null; mainSha: string | null } | null> {
-  const row = await getDb().meta.get("current");
-  if (!row) return null;
-  return { savedSha: row.lastSavedSha, mainSha: row.mainSha ?? null };
-}
-
-export async function getDeletedSections(): Promise<string[]> {
-  const row = await getDb().siteIndex.get("current");
-  return row?.deletedSections ?? [];
-}
-
 /**
  * Write the content snapshot for one commit.
  *
@@ -522,6 +508,7 @@ export async function cacheContent(
     savedBranchSha?: string | null;
     changedSectionIds?: string[];
     mainIndex?: SiteIndex | null;
+    unparseableSectionIds?: string[];
   },
 ): Promise<void> {
   const now = new Date().toISOString();
@@ -537,6 +524,7 @@ export async function cacheContent(
     mainIndex: diff?.mainIndex ?? null,
     mediaManifest: manifests.media,
     documentManifest: manifests.documents,
+    unparseableSectionIds: diff?.unparseableSectionIds ?? [],
   });
 }
 
@@ -555,6 +543,7 @@ export async function getCachedContent(): Promise<{
    *  value and is not null. */
   mediaManifest: MediaManifest | null;
   documentManifest: DocumentManifest | null;
+  unparseableSectionIds: string[];
 } | null> {
   const row = await getDb().contentCache.get("current");
   if (!row) return null;
@@ -570,6 +559,7 @@ export async function getCachedContent(): Promise<{
     mainIndex: row.mainIndex ?? row.index,
     mediaManifest: row.mediaManifest ?? null,
     documentManifest: row.documentManifest ?? null,
+    unparseableSectionIds: row.unparseableSectionIds ?? [],
   };
 }
 
@@ -648,13 +638,20 @@ export async function clearPendingMediaByIds(
 
 /** Snapshot a local edit that is about to be superseded (takeover or conflict
  *  resolution) so it is recoverable rather than silently destroyed. */
+let preservedEditSeq = 0;
+
 export async function preserveEdit(
   sectionId: string,
   content: SectionContent,
   reason: "takeover" | "conflict",
 ): Promise<string> {
   const preservedAt = new Date().toISOString();
-  const id = `${sectionId}:${preservedAt}`;
+  // A monotonic suffix, because the ISO timestamp only has millisecond
+  // resolution: resolving the same section twice inside one millisecond (a
+  // takeover immediately followed by a conflict, or two rapid recoveries) put
+  // both under the same key, and the `put` destroyed the edit it was called to
+  // rescue.
+  const id = `${sectionId}:${preservedAt}:${preservedEditSeq++}`;
   await getDb().preservedEdits.put({ id, sectionId, content, reason, preservedAt });
   return id;
 }

package/src/lib/index-ops.ts

@@ -267,11 +267,31 @@ export function applyIndexOps(
     ...base.data,
     pages: base.data.pages.map((p) => ({ ...p, order: [...p.order] })),
     sections: Object.fromEntries(Object.entries(base.data.sections).map(([k, v]) => [k, { ...v }])),
-    ...(Array.isArray(rawNav) ? { nav: rawNav as NavEntry[] } : {}),
+    // COPIED, not aliased. Taking the caller's array by reference meant any nav
+    // op that spliced in place would mutate the caller's index — the one thing
+    // this function's own comment promises it never does.
+    ...(Array.isArray(rawNav)
+      ? {
+          nav: (rawNav as NavEntry[]).map((entry) =>
+            entry && typeof entry === "object" && "pageIds" in entry
+              ? { ...entry, pageIds: [...(entry as { pageIds: string[] }).pageIds] }
+              : { ...entry },
+          ),
+        }
+      : {}),
   };
 
   const removed = new Set<string>();
   const warnings: string[] = [];
+  // Audience advisories are RECORDED here during the loop and decided after it,
+  // against the finished index. Deciding them at op time made them wrong in both
+  // directions whenever a later op in the same batch moved the section, removed
+  // it, or changed the page's access — insert-then-widen warned about nothing,
+  // and widen-then-insert stayed silent about a genuine stranding.
+  const advisories: (
+    | { kind: "section"; at: string; sectionId: string; pageId: string }
+    | { kind: "pageAccess"; at: string; pageId: string; dropped: string[] }
+  )[] = [];
   const fail = (error: string): ApplyIndexOpsResult => ({ ok: false, error });
   // Whether any op in this batch changed the navigation sidecar. Section-level
   // ops must leave `nav` OFF the result: content-ops writes nav.json only when
@@ -328,12 +348,7 @@ export function applyIndexOps(
         // Same advisory as `move`: an inserted section whose audiences the
         // destination page does not allow is invisible to every audienced
         // viewer, and saying nothing would make that look like a successful save.
-        const stranded = page.access.length > 0 ? meta.access.filter((a) => !page.access.includes(a)) : [];
-        if (stranded.length > 0) {
-          warnings.push(
-            `${at}: section "${s.id}" carries audience(s) ${fmt(stranded)} that page "${op.pageId}" does not allow, so no audienced viewer will see it — clear it with setMeta, or widen the page's access.`,
-          );
-        }
+        advisories.push({ kind: "section", at, sectionId: s.id, pageId: op.pageId });
         metas.push([s.id, meta]);
       }
       page.order.splice(position, 0, ...metas.map(([id]) => id));
@@ -366,12 +381,7 @@ export function applyIndexOps(
       // change who can see content without saying so. "no audienced viewer",
       // not "everyone" — audiencePasses returns true for a viewer with no
       // audience at all (lib/pages.ts).
-      const stranded = dest.access.length > 0 ? meta.access.filter((a) => !dest.access.includes(a)) : [];
-      if (stranded.length > 0) {
-        warnings.push(
-          `${at}: section "${op.id}" carries audience(s) ${fmt(stranded)} that page "${op.pageId}" does not allow, so no audienced viewer will see it — clear it with setMeta, or widen the page's access.`,
-        );
-      }
+      advisories.push({ kind: "section", at, sectionId: op.id, pageId: op.pageId });
       continue;
     }
 
@@ -534,6 +544,16 @@ export function applyIndexOps(
     if (op.slug !== undefined && (RESERVED_SLUGS as readonly string[]).includes(op.slug)) {
       return fail(`${at}: slug "${op.slug}" is reserved by a platform route and would shadow this page. Pick another slug.`);
     }
+    // Shape and uniqueness inline, exactly as addPage checks them. Leaving these
+    // to the final IndexSchema re-validation produced a message carrying none of
+    // the `indexOps[i]` prefix every other failure has, so an agent could not
+    // tell which op in a batch was rejected.
+    if (op.slug !== undefined && !SLUG_RE.test(op.slug)) {
+      return fail(`${at}: slug "${op.slug}" is not a valid URL slug — use lowercase words joined by dashes (e.g. "brand-guide").`);
+    }
+    if (op.slug !== undefined && index.pages.some((p) => p.id !== op.pageId && p.slug === op.slug)) {
+      return fail(`${at}: slug "${op.slug}" is already used by another page. Slugs must be unique.`);
+    }
     if (op.title !== undefined) page.title = op.title;
     if (op.slug !== undefined) page.slug = op.slug;
     if (op.showInNav !== undefined) page.showInNav = op.showInNav;
@@ -541,14 +561,37 @@ export function applyIndexOps(
     if (op.access !== undefined) {
       const dropped = page.access.filter((a) => !op.access!.includes(a));
       page.access = op.access;
-      if (dropped.length > 0 && op.access.length > 0) {
-        const stranded = page.order.filter((id) => index.sections[id]?.access.some((a) => dropped.includes(a)));
-        if (stranded.length > 0) {
-          warnings.push(
-            `${at}: section(s) ${fmt(stranded)} still carry audience(s) ${fmt(dropped)} that page "${op.pageId}" no longer allows, so no audienced viewer will see them — clear them with setMeta.`,
-          );
-        }
+      if (dropped.length > 0) advisories.push({ kind: "pageAccess", at, pageId: op.pageId, dropped });
+    }
+  }
+
+  // Advisories, decided against the finished index (see the declaration above).
+  for (const advisory of advisories) {
+    const page = index.pages.find((p) => p.id === advisory.pageId);
+    if (!page || page.access.length === 0) continue;
+
+    if (advisory.kind === "section") {
+      const meta = index.sections[advisory.sectionId];
+      // A later op removed the section, or moved it off this page — either way
+      // the stranding this op would have caused no longer exists.
+      if (!meta || !page.order.includes(advisory.sectionId)) continue;
+      const stranded = meta.access.filter((a) => !page.access.includes(a));
+      if (stranded.length > 0) {
+        warnings.push(
+          `${advisory.at}: section "${advisory.sectionId}" carries audience(s) ${fmt(stranded)} that page "${advisory.pageId}" does not allow, so no audienced viewer will see it — clear it with setMeta, or widen the page's access.`,
+        );
       }
+      continue;
+    }
+
+    // A later setPageMeta may have put one of the dropped audiences back.
+    const dropped = advisory.dropped.filter((a) => !page.access.includes(a));
+    if (dropped.length === 0) continue;
+    const stranded = page.order.filter((id) => index.sections[id]?.access.some((a) => dropped.includes(a)));
+    if (stranded.length > 0) {
+      warnings.push(
+        `${advisory.at}: section(s) ${fmt(stranded)} still carry audience(s) ${fmt(dropped)} that page "${advisory.pageId}" no longer allows, so no audienced viewer will see them — clear them with setMeta.`,
+      );
     }
   }
 

package/src/lib/loader.ts

@@ -1,4 +1,4 @@
-import { getSectionSchema, type Section } from "../schemas/sections";
+import { getSectionSchemaForType, type Section } from "../schemas/sections";
 import { IndexSchema, type SiteIndex, type SectionMeta } from "../schemas/site-config";
 import { getAllSchemas } from "./registry";
 import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
@@ -62,8 +62,12 @@ export function mergeSiteContent(
 ): SiteContent {
   const sections: LoadedSection[] = [];
 
+  // Validation is per-TYPE, not against a union of every registered schema.
+  // The union validates members in order and fully validates each miss, so a
+  // 200-section site with ~20 types paid O(N x M) object validations on every
+  // SSR load. Every section schema pins `type: z.literal(...)`, so selecting by
+  // type picks exactly the member the union would have matched.
   const canValidate = getAllSchemas().length >= 2;
-  const schema = canValidate ? getSectionSchema() : null;
 
   const orderedIds = index.pages.flatMap((p) => p.order);
   for (const id of orderedIds) {
@@ -86,11 +90,15 @@ export function mergeSiteContent(
       ? { ...baseMeta, type: upgradedType }
       : baseMeta;
 
-    if (canValidate && schema) {
-      const result = schema.safeParse(raw);
-      if (!result.success) {
-        const type = (raw as Record<string, unknown>).type ?? "unknown";
-        console.warn(`Skipping section "${id}" (type: ${type}): invalid schema`);
+    if (canValidate) {
+      const type = (raw as Record<string, unknown>)?.type;
+      // An unregistered type has no member in the union either, so this is the
+      // same outcome the whole-union parse produced — just without validating
+      // against every other type first.
+      const schema = typeof type === "string" ? getSectionSchemaForType(type) : null;
+      const result = schema ? schema.safeParse(raw) : null;
+      if (!result?.success) {
+        console.warn(`Skipping section "${id}" (type: ${type ?? "unknown"}): invalid schema`);
         continue;
       }
       if (blockDepth(result.data) > MAX_BLOCK_DEPTH) {
@@ -146,12 +154,33 @@ export async function loadSiteContent(contentDir: string): Promise<SiteContent>
 
   // nav.json is an optional sidecar — absent (every portal predating page
   // groups) or unreadable must degrade to a flat nav, never fail the load.
-  let navFile: unknown;
+  //
+  // ABSENT and UNREADABLE are not the same answer, though: absent is the normal
+  // case and safe to overwrite, while a present-but-unparseable sidecar holds
+  // groups this load cannot see. Collapsing both to `undefined` reported
+  // navDegraded: false, so the next nav-touching save wholesale-wrote a flat
+  // nav.json over a file that was still hand-recoverable. Mirrors the
+  // GitHub-backed loader's navRaw/navFile split in @drawnagency/core.
+  let navRaw: string | undefined;
+  let readFailed = false;
   try {
-    navFile = JSON.parse(await fs.readFile(path.join(contentDir, "nav.json"), "utf-8"));
-  } catch {
-    navFile = undefined;
+    navRaw = await fs.readFile(path.join(contentDir, "nav.json"), "utf-8");
+  } catch (err) {
+    // Only a genuinely missing file is "absent". A permissions/IO error leaves
+    // the sidecar's contents unknown, which must not license overwriting it.
+    readFailed = (err as { code?: string })?.code !== "ENOENT";
   }
 
-  return mergeSiteContent(index, sectionFiles, navFile);
+  let navFile: unknown;
+  let parseFailed = false;
+  if (navRaw !== undefined) {
+    try {
+      navFile = JSON.parse(navRaw);
+    } catch {
+      parseFailed = true;
+    }
+  }
+
+  const content = mergeSiteContent(index, sectionFiles, navFile);
+  return readFailed || parseFailed ? { ...content, navDegraded: true } : content;
 }

package/src/lib/media-folders.ts

@@ -195,12 +195,38 @@ export function healMediaManifest(manifest: MediaManifest): MediaManifest {
  *
  * Images union, ours winning, so local alt/folder-move edits survive; a pending
  * local deletion isn't removed from the manifest until save, so the union can't
- * resurrect one. Folders stay ours verbatim — deleting a folder removes it from
- * our map with no wire signal, so unioning would undo the delete. Mirrors the
- * server-side merge in core's content-ops.
+ * resurrect one. Mirrors the server-side merge in core's content-ops.
+ *
+ * Folders union too, minus the ones we deleted — which is why `base` (the
+ * manifest we diverged from, i.e. the last one we fetched) is needed: a folder
+ * deletion just removes the entry from our map, so without a baseline "we
+ * deleted it" and "they created it" are the same shape. Keeping folders ours
+ * verbatim, as this did, silently dropped a concurrent writer's new folders and
+ * then let `healMediaManifest` strip the now-dangling `folderId` off their
+ * images, flattening their whole organisation to root on our next save.
+ *
+ * Without `base` it degrades to the old folders-stay-ours behaviour.
  */
-export function rebaseMediaManifest(local: MediaManifest, remote: MediaManifest): MediaManifest {
-  return { ...local, images: { ...remote.images, ...local.images } };
+export function rebaseMediaManifest(
+  local: MediaManifest,
+  remote: MediaManifest,
+  base?: MediaManifest,
+): MediaManifest {
+  const images = { ...remote.images, ...local.images };
+  if (!base) return { ...local, images };
+
+  const deletedLocally = new Set(
+    Object.keys(base.folders).filter((id) => !(id in local.folders)),
+  );
+  const folders: Record<string, MediaFolder> = {};
+  for (const [id, folder] of Object.entries(remote.folders)) {
+    if (!deletedLocally.has(id)) folders[id] = folder;
+  }
+  // Ours last: a local rename or move of a folder we both have wins, matching
+  // the image rule above.
+  for (const [id, folder] of Object.entries(local.folders)) folders[id] = folder;
+
+  return { ...local, images, folders };
 }
 
 /**

package/src/lib/migrate-sections-transform.ts

@@ -43,7 +43,27 @@ function upgradeContainerChildren(section: Obj): unknown {
     return up;
   });
   if (!changed) return section;
-  return { ...section, content: { ...content, children: mapped } };
+  // Normalize the container's OWN layout keys while we are rewriting it. A
+  // legacy container that never carried them emitted a content object the
+  // container schema then defaulted, so `transform(raw)` no longer deep-equalled
+  // `parse(transform(raw))` — the convergence contract this file is built on.
+  return {
+    ...section,
+    content: {
+      ...content,
+      layout: content?.layout ?? "grid",
+      columns: normalizeColumns(content?.columns),
+      equalizeRowHeight: content?.equalizeRowHeight ?? false,
+      children: mapped,
+    },
+  };
+}
+
+/** The container schema's `columns` default. Emitting `undefined` for a legacy
+ *  grid with no columns key parsed to 1 anyway — but only AFTER the parse, which
+ *  broke convergence. */
+function normalizeColumns(columns: unknown): number {
+  return typeof columns === "number" && Number.isFinite(columns) ? columns : 1;
 }
 
 /** Carry only known BaseMediaRef (+ video) fields; drops render artifacts (src/srcset/alt) and any stray keys. */
@@ -98,7 +118,7 @@ function upgradeGrid(section: Obj): Obj {
     id,
     type: "container",
     content: {
-      columns: content.columns,
+      columns: normalizeColumns(content.columns),
       layout: "grid",
       equalizeRowHeight: false,
       children: media.map((item, i) => mapRefItem(item, id, i)),

package/src/lib/nav-progress.ts

@@ -0,0 +1,108 @@
+// Top progress bar for viewer page navigation. Viewer pages are per-request SSR
+// renders, so a click can sit for a beat with no feedback beyond the browser's
+// own tab spinner; this gives that wait an in-page affordance in the brand
+// color.
+//
+// There is no client router here — the browser performs a real navigation and
+// keeps painting the outgoing page until the new response commits, which is
+// exactly the window the bar fills. Nothing hides it: the incoming document
+// replaces it. The only teardown paths are a bfcache restore (pageshow) and the
+// safety timeout for a navigation that never lands.
+
+/** Delay before the bar appears, so a prefetched (near-instant) navigation
+ *  never flashes it. Mirrors EditorLoading's reasoning. */
+const SHOW_DELAY_MS = 200;
+/** Give up if the navigation never commits (blocked, aborted, offline) rather
+ *  than leaving a stuck bar across the top of a page the viewer is still on. */
+const SAFETY_MS = 15_000;
+
+export interface NavProgressOptions {
+  showDelayMs?: number;
+  safetyMs?: number;
+}
+
+function isModifiedClick(event: MouseEvent): boolean {
+  // Anything that doesn't navigate this tab: middle/right click, new tab, new
+  // window, download.
+  return event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey;
+}
+
+/** Would this click actually navigate the current tab to a different document? */
+function navigatesAway(link: HTMLAnchorElement): boolean {
+  if (link.hasAttribute("download") || link.dataset.navProgress === "false") return false;
+  if (link.target && link.target !== "_self") return false;
+  if (!link.getAttribute("href")) return false;
+
+  let url: URL;
+  try {
+    url = new URL(link.href, window.location.href);
+  } catch {
+    return false;
+  }
+  // mailto:/tel: land here too — their origin is never the page's.
+  if (url.origin !== window.location.origin) return false;
+  // Same-document hash links, including the nav's `#doc=` document launchers.
+  return url.pathname !== window.location.pathname || url.search !== window.location.search;
+}
+
+/**
+ * Wire the bar rendered by Layout.astro. No-ops when the element is absent,
+ * which is how /edit opts out — Astro hoists a layout's module script to the
+ * page bundle regardless of the branch it was rendered in, so the element, not
+ * the script tag, is the gate.
+ *
+ * Returns a teardown function (used by tests; production never unwires).
+ */
+export function initNavProgress(options?: NavProgressOptions): () => void {
+  const bar = document.querySelector<HTMLElement>("[data-nav-progress]");
+  if (!bar) return () => {};
+
+  const showDelayMs = options?.showDelayMs ?? SHOW_DELAY_MS;
+  const safetyMs = options?.safetyMs ?? SAFETY_MS;
+
+  let showTimer: ReturnType<typeof setTimeout> | null = null;
+  let safetyTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Arrow consts, not function declarations: hoisting would discard the
+  // null-narrowing `bar` just got from the guard above.
+  const reset = () => {
+    if (showTimer) clearTimeout(showTimer);
+    if (safetyTimer) clearTimeout(safetyTimer);
+    showTimer = null;
+    safetyTimer = null;
+    bar.classList.remove("is-active");
+  };
+
+  const start = () => {
+    reset();
+    showTimer = setTimeout(() => {
+      showTimer = null;
+      bar.classList.add("is-active");
+    }, showDelayMs);
+    safetyTimer = setTimeout(reset, safetyMs);
+  };
+
+  const onClick = (event: MouseEvent) => {
+    if (event.defaultPrevented || isModifiedClick(event)) return;
+    const target = event.target;
+    const link = target instanceof Element ? target.closest("a") : null;
+    if (!(link instanceof HTMLAnchorElement)) return;
+    if (!navigatesAway(link)) return;
+    start();
+  };
+
+  // A bfcache restore replays the outgoing page as it was — bar included, since
+  // it was mid-animation when the viewer left. Clear it.
+  const onPageShow = (event: PageTransitionEvent) => {
+    if (event.persisted) reset();
+  };
+
+  document.addEventListener("click", onClick);
+  window.addEventListener("pageshow", onPageShow);
+
+  return () => {
+    reset();
+    document.removeEventListener("click", onClick);
+    window.removeEventListener("pageshow", onPageShow);
+  };
+}

package/src/lib/nav-tree.ts

@@ -40,16 +40,30 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
     }
 
     if (entry?.kind !== "group") continue;
+    // `id` is the one group key with no schema default, so a group missing it
+    // (or carrying a non-string) cannot be repaired — spreading it through left
+    // an entry that NavFileSchema rejects, which is a nav the writer refuses,
+    // and "total" would be a lie. Dropping it spills its members to the tail
+    // append below: a group lost, never a page.
+    if (typeof entry.id !== "string" || entry.id === "") continue;
     if (seenGroupIds.has(entry.id)) continue;
     seenGroupIds.add(entry.id);
 
     const claimed = Array.isArray(entry.pageIds) ? entry.pageIds : [];
     const pageIds = claimed.filter((id) => {
-      if (!validIds.has(id) || placed.has(id)) return false;
+      if (typeof id !== "string" || !validIds.has(id) || placed.has(id)) return false;
       placed.add(id);
       return true;
     });
-    const group: NavGroupEntry = { ...entry, pageIds };
+    // Rebuilt key by key rather than spread: the other two keys default in the
+    // schema, so normalizing them here is what makes every output parseable.
+    const group: NavGroupEntry = {
+      kind: "group",
+      id: entry.id,
+      label: typeof entry.label === "string" ? entry.label : "",
+      startCollapsed: entry.startCollapsed === true,
+      pageIds,
+    };
     result.push(group);
   }
 

package/src/lib/nav.ts

@@ -51,6 +51,10 @@ export function generateNavLinks(
     if (role === "h1") {
       if (content.excludeFromNav) {
         currentParent = null;
+        // Clear the child cursor too: leaving it pointing into the PREVIOUS
+        // h1's subtree made an h3 following an excluded h1 nest under that
+        // earlier branch instead of being dropped with its excluded parent.
+        currentChild = null;
         continue;
       }
       currentParent = {
@@ -62,7 +66,12 @@ export function generateNavLinks(
       currentChild = null;
       nav.push(currentParent);
     } else if (role === "h2") {
-      if (content.excludeFromNav) continue;
+      // Same cursor reset as the excluded h1 above — an h3 under an excluded
+      // h2 belongs nowhere, not under the preceding h2.
+      if (content.excludeFromNav) {
+        currentChild = null;
+        continue;
+      }
       if (!currentParent) continue;
       currentChild = {
         href: `#${toSectionId(content.heading)}`,