@drawnagency/primitives 0.1.110 → 0.1.112

package/src/lib/deck-edit.ts

@@ -0,0 +1,196 @@
+import {
+  parseDeck,
+  type Deck,
+  type DeckComponent,
+  type DeckRichText,
+  type DeckSlide,
+} from "../schemas/deck";
+
+/**
+ * Direct-manipulation edits to a Deck Draft (#39).
+ *
+ * Every operation here is PURE and ends in `parseDeck`, which is what makes
+ * "a manual edit is always schema-valid" a property of this module rather than
+ * of its callers. It also means the schema owns the refusals: duplicating past
+ * `DECK_MAX_SLIDES` and deleting the last slide are reported with the same
+ * messages the authoring loop's validation retry reads, not with a second copy
+ * of those rules written here.
+ *
+ * The scope line is the product decision recorded in CONTEXT.md — "chat
+ * authors, direct manipulation adjusts". There is deliberately no operation
+ * here that changes a Layout, adds or removes a Deck Component, or composes a
+ * grid. Text leaves and slide order are the whole vocabulary.
+ */
+
+/**
+ * Which Deck Component within a slide's Layout. A slide-local coordinate: the
+ * runtime renders one slide and has no idea which one, so the slide index stays
+ * an argument at the call site.
+ */
+// Module-private VALUES, exported types only. The deck runtime imports
+// `DeckTextPath` from here, and `import type` is erased — exporting the arrays
+// would offer a value import that pulls this module, and the deck schema and
+// zod behind it, into the runtime chunk served to Public Link readers. Neither
+// fence would see it: the unit test cannot tell a type import from a value one
+// and excludes the runtime subtree anyway.
+const DECK_TEXT_SLOTS = ["content", "overlay", "left", "right"] as const;
+export type DeckTextSlot = (typeof DECK_TEXT_SLOTS)[number];
+
+const DECK_TEXT_FIELDS = ["kicker", "heading", "subheading", "paragraphs", "bullets"] as const;
+export type DeckTextField = (typeof DECK_TEXT_FIELDS)[number];
+
+/**
+ * A single editable text LEAF — always a plain string in the schema.
+ *
+ * That "always a leaf" framing is what keeps inline editing free of a
+ * formatting UI without ever destroying a mark: a paragraph carrying spans is
+ * edited one span at a time (`span`), so `bold`/`italic` are untouched by an
+ * edit that only ever writes `text`. A plain-string line has no `span`.
+ */
+export interface DeckTextPath {
+  slot: DeckTextSlot;
+  field: DeckTextField;
+  /** Index into `paragraphs`/`bullets`. Absent for the three single-line fields. */
+  line?: number;
+  /** Index into that line's spans, when the line is a span run rather than a string. */
+  span?: number;
+}
+
+export type DeckEditResult = { ok: true; deck: Deck } | { ok: false; errors: string[] };
+
+/** A path that points at nothing is a bug in the caller, not author input. */
+function unresolved(path: DeckTextPath): DeckEditResult {
+  return {
+    ok: false,
+    errors: [`no editable text at ${path.slot}.${path.field}${path.line === undefined ? "" : `[${path.line}]`}`],
+  };
+}
+
+/** The rich text a slot holds, or null when that slot holds something else. */
+export function richTextAt(slide: DeckSlide, slot: DeckTextSlot): DeckRichText | null {
+  const { layout } = slide;
+  if (layout.type === "centeredText") {
+    return slot === "content" && layout.content.type === "richText" ? layout.content : null;
+  }
+  if (layout.type === "fullBleedImage") {
+    return slot === "overlay" ? (layout.overlay?.content ?? null) : null;
+  }
+  if (slot !== "left" && slot !== "right") return null;
+  const component: DeckComponent = layout[slot];
+  return component.type === "richText" ? component : null;
+}
+
+/** The same addressing, as a setter. Returns null when the slot has no rich text. */
+function withRichTextAt(slide: DeckSlide, slot: DeckTextSlot, next: DeckRichText): DeckSlide | null {
+  const { layout } = slide;
+  if (layout.type === "centeredText") {
+    if (slot !== "content" || layout.content.type !== "richText") return null;
+    return { ...slide, layout: { ...layout, content: next } };
+  }
+  if (layout.type === "fullBleedImage") {
+    if (slot !== "overlay" || layout.overlay === undefined) return null;
+    return { ...slide, layout: { ...layout, overlay: { ...layout.overlay, content: next } } };
+  }
+  if (slot !== "left" && slot !== "right") return null;
+  if (layout[slot].type !== "richText") return null;
+  return { ...slide, layout: { ...layout, [slot]: next } };
+}
+
+/** Writes `text` into the addressed leaf, or null when the path resolves to nothing. */
+function withLeafText(content: DeckRichText, path: DeckTextPath, text: string): DeckRichText | null {
+  if (path.field === "kicker" || path.field === "heading" || path.field === "subheading") {
+    // Only a field that is already present is editable — a blank line the
+    // author never wrote is not a place to click, and inventing one here would
+    // be the structural editing this module does not do.
+    if (content[path.field] === undefined) return null;
+    return { ...content, [path.field]: text };
+  }
+
+  const lines = content[path.field];
+  if (lines === undefined || path.line === undefined || path.line < 0 || path.line >= lines.length) return null;
+
+  const nextLines = lines.slice();
+  const line = nextLines[path.line];
+
+  if (path.span === undefined) {
+    if (typeof line !== "string") return null;
+    nextLines[path.line] = text;
+  } else {
+    if (typeof line === "string" || path.span < 0 || path.span >= line.length) return null;
+    const spans = line.slice();
+    spans[path.span] = { ...spans[path.span], text };
+    nextLines[path.line] = spans;
+  }
+
+  return { ...content, [path.field]: nextLines };
+}
+
+/**
+ * Commit an inline text edit.
+ *
+ * Rejecting (rather than clamping) an over-long or emptied field is deliberate:
+ * the caps are the schema's, and a silent truncation is an edit the author did
+ * not make. The caller shows the schema's own message and leaves the draft
+ * untouched.
+ */
+export function applyDeckTextEdit(deck: Deck, slideIndex: number, path: DeckTextPath, text: string): DeckEditResult {
+  const slide = deck.slides[slideIndex];
+  if (slide === undefined) return { ok: false, errors: [`no slide at index ${slideIndex}`] };
+
+  const content = richTextAt(slide, path.slot);
+  if (content === null) return unresolved(path);
+
+  const nextContent = withLeafText(content, path, text);
+  if (nextContent === null) return unresolved(path);
+
+  const nextSlide = withRichTextAt(slide, path.slot, nextContent);
+  if (nextSlide === null) return unresolved(path);
+
+  const slides = deck.slides.slice();
+  slides[slideIndex] = nextSlide;
+  return parseDeck({ ...deck, slides });
+}
+
+/** Move a slide to a new index. `to` is the destination in the POST-removal list. */
+export function moveDeckSlide(deck: Deck, from: number, to: number): DeckEditResult {
+  if (from < 0 || from >= deck.slides.length) return { ok: false, errors: [`no slide at index ${from}`] };
+  if (to < 0 || to >= deck.slides.length) return { ok: false, errors: [`cannot move a slide to index ${to}`] };
+  const slides = deck.slides.slice();
+  const [moved] = slides.splice(from, 1);
+  slides.splice(to, 0, moved);
+  return parseDeck({ ...deck, slides });
+}
+
+/**
+ * A fresh slide id for a copy. Ids are unique within a deck (the schema refuses
+ * a duplicate by name) and double as diff anchors across revisions, so a copy
+ * has to be given its own rather than inheriting one.
+ */
+function copySlideId(sourceId: string, taken: ReadonlySet<string>): string {
+  // Copying a copy chains "-copy-2", not "-copy-copy". The slice keeps room for
+  // the suffix inside DeckIdSchema's 64-character cap.
+  const stem = sourceId.replace(/-copy(-\d+)?$/, "").slice(0, 52).replace(/-+$/, "") || "slide";
+  let candidate = `${stem}-copy`;
+  for (let n = 2; taken.has(candidate); n++) candidate = `${stem}-copy-${n}`;
+  return candidate;
+}
+
+/** Duplicate a slide, inserting the copy directly after the original. */
+export function duplicateDeckSlide(deck: Deck, index: number): DeckEditResult {
+  const source = deck.slides[index];
+  if (source === undefined) return { ok: false, errors: [`no slide at index ${index}`] };
+  const copy: DeckSlide = {
+    ...structuredClone(source),
+    id: copySlideId(source.id, new Set(deck.slides.map((s) => s.id))),
+  };
+  const slides = deck.slides.slice();
+  slides.splice(index + 1, 0, copy);
+  return parseDeck({ ...deck, slides });
+}
+
+/** Remove a slide. Removing the only one is refused by the schema, by design. */
+export function removeDeckSlide(deck: Deck, index: number): DeckEditResult {
+  if (deck.slides[index] === undefined) return { ok: false, errors: [`no slide at index ${index}`] };
+  const slides = deck.slides.filter((_, i) => i !== index);
+  return parseDeck({ ...deck, slides });
+}

package/src/lib/deck-media-assets.ts

@@ -0,0 +1,57 @@
+import type { DeckMediaAsset } from "../schemas/deck";
+import type { MediaManifest } from "../media/types";
+import type { MediaProvider } from "../media/provider";
+
+/**
+ * The production side of the deck runtime's media seam: the site's image
+ * manifest, resolved to the `mediaAssets` map `DeckPlayer` takes.
+ *
+ * A MAP, not a `DeckMediaResolver` function, because the builder mounts across
+ * an Astro island boundary and a function prop cannot survive that trip. It is
+ * built server-side, where the manifest and the media provider live.
+ *
+ * This replaces the dev preview route's generated plates
+ * (`core/src/lib/dev-deck-preview.ts`), which stay exactly where they are —
+ * they keep that route working offline and with no GitHub credentials.
+ */
+export function deckMediaAssets(
+  manifest: MediaManifest,
+  sizes: number[],
+  provider: MediaProvider,
+  /**
+   * The audience boundary, when the caller has one. Only these ids resolve.
+   *
+   * The builder's map must match the catalog the model is offered (#35, decided
+   * 2026-08-07) or the two disagree about what exists — and because this map
+   * travels as ISLAND PROPS, an unfiltered one also puts every asset's filename
+   * and alt text in the page source of a creator who cannot see those pages.
+   * Omitted means no filtering, which is what the dev preview route wants.
+   */
+  allowIds?: ReadonlySet<string>,
+): Record<string, DeckMediaAsset> {
+  const assets: Record<string, DeckMediaAsset> = {};
+  for (const [id, item] of Object.entries(manifest.images)) {
+    // System-generated assets (the social-preview raster) are excluded from the
+    // media library UI, so they are not part of the catalog a deck may cite.
+    if (item.hidden) continue;
+    if (allowIds && !allowIds.has(id)) continue;
+    const resolved = provider.resolve(item, sizes);
+    // An unresolvable entry is simply absent, which the runtime already renders
+    // as a quiet gap — the same thing a deleted asset produces.
+    if (!resolved) continue;
+    assets[id] = {
+      src: resolved.src,
+      alt: item.alt,
+      // The manifest always knows the intrinsic size, and supplying it is what
+      // lets the image grid reserve aspect-correct space before a byte loads.
+      width: resolved.width,
+      height: resolved.height,
+      ...(resolved.tag === "video" && resolved.poster ? { poster: resolved.poster } : {}),
+    };
+  }
+  // A plain object, and that is safe because every reader guards its lookups
+  // with `Object.hasOwn` (DeckPlayer's map resolver, DeckSlideSurface) and the
+  // deck schema constrains a media id's charset. A null-prototype object would
+  // also have to be re-spread to survive Astro's prop serialization.
+  return assets;
+}

package/src/lib/deck-media-refs.ts

@@ -0,0 +1,67 @@
+/**
+ * Every portal media reference a deck makes, extracted from RAW deck JSON.
+ *
+ * Publish-time GC builds its keep-set from the site's manifests and deletes
+ * every other bucket object (ADR 0002's "GC must learn the decks branch"), so a
+ * deck referencing an asset the editor later removed from portal content would
+ * otherwise have its media deleted underneath it.
+ *
+ * Deliberately untyped and structural rather than a walk over `Deck`: the media
+ * reference union lands with the image/grid components (#31), and this has to
+ * work the day it does without a second change here. It matches the union's
+ * discriminator shape — `{ kind: "portal", id: string }` — wherever it appears
+ * in the tree, at any depth, in any component. Staying schema-free is also what
+ * keeps this module off the deck-schema carrier list (tests/deck/viewer-isolation).
+ */
+
+/** One reference, with the path an author (or a model) can act on. */
+export interface DeckMediaRefSite {
+  /** `slides[2].layout.media` — the ref object's own path, not its `id` field. */
+  path: string;
+  id: string;
+}
+
+function step(path: string, key: string): string {
+  return path === "" ? key : `${path}.${key}`;
+}
+
+export function deckMediaRefSites(deck: unknown): DeckMediaRefSite[] {
+  const sites: DeckMediaRefSite[] = [];
+  const visit = (node: unknown, path: string): void => {
+    if (Array.isArray(node)) {
+      node.forEach((item, i) => visit(item, `${path}[${i}]`));
+      return;
+    }
+    if (typeof node !== "object" || node === null) return;
+    const record = node as Record<string, unknown>;
+    if (record.kind === "portal" && typeof record.id === "string" && record.id !== "") {
+      sites.push({ path, id: record.id });
+    }
+    for (const [key, value] of Object.entries(record)) visit(value, step(path, key));
+  };
+  visit(deck, "");
+  return sites;
+}
+
+export function deckMediaIds(deck: unknown): Set<string> {
+  return new Set(deckMediaRefSites(deck).map((site) => site.id));
+}
+
+/**
+ * Media references the catalog does not contain — the server-side half of media
+ * grounding (#35).
+ *
+ * The deck schema constrains a media id's CHARSET; only the catalog can say
+ * whether an id exists, so membership is checked here rather than in the schema
+ * (which is also read by the runtime, where no catalog is in hand). One line per
+ * offending reference, in the same `path: message` shape `formatDeckIssues`
+ * produces, so the authoring loop can hand both lists back in one tool_result.
+ */
+export function deckUnknownMediaIssues(deck: unknown, catalogIds: ReadonlySet<string>): string[] {
+  return deckMediaRefSites(deck)
+    .filter((site) => !catalogIds.has(site.id))
+    .map(
+      (site) =>
+        `${step(site.path, "id")}: "${site.id}" is not in the portal media catalog — use only the ids listed under "Media catalog", copied exactly.`,
+    );
+}

package/src/lib/deck-tool.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import {
+  DECK_COMPONENT_TYPES,
+  DECK_LAYOUT_TYPES,
+  DECK_MAX_SLIDES,
+  DECK_SCHEMA_VERSION,
+  DeckSchema,
+} from "../schemas/deck";
+
+/**
+ * The `update_deck` tool the deck-chat loop hands the model (#35, ADR 0001).
+ *
+ * The input schema is DERIVED from `DeckSchema` rather than written out, so the
+ * contract cannot drift from what the server will actually accept: every
+ * `.describe()` in the deck schema IS the LLM's documentation, and a field
+ * added there reaches the model on the next request with no second edit here.
+ *
+ * Emitted INLINE (zod's default `reused: "inline"`), not with `$defs`/`$ref`.
+ * The ref form is less than half the bytes, but names every shared node
+ * `__schema7`, which puts the layout and component descriptions an indirection
+ * away from the slot that uses them. The tool block sits in the cached prefix
+ * (tools precede `system`, and the corpus block carries the cache breakpoint),
+ * so the size is paid once per conversation while the legibility is paid on
+ * every turn.
+ */
+
+export const UPDATE_DECK_TOOL_NAME = "update_deck";
+
+export interface DeckToolDefinition {
+  name: string;
+  description: string;
+  /** JSON Schema; the tool's input IS the whole deck. */
+  input_schema: Record<string, unknown>;
+}
+
+/**
+ * The vocabulary, spelled out in prose above the schema.
+ *
+ * The derived JSON Schema already carries it, but only as `const` values buried
+ * in nested `anyOf` branches — and live authoring showed the model guessing
+ * layout and component types from there, burning validation retries on
+ * "unknown layout type" and sometimes exhausting them. A flat list costs a few
+ * dozen tokens in the cached tool block and removes the guess.
+ *
+ * The type names come from the schema's own constants, so a new Layout or
+ * Component cannot be added without appearing here; the slot shapes are spelled
+ * out because they are structure, not a list — `tests/deck/deck-tool.test.ts`
+ * pins that every name in both constants is mentioned.
+ */
+const VOCABULARY = [
+  `Layouts (a slide uses exactly one, and \`type\` must be one of these ${DECK_LAYOUT_TYPES.length}): ${DECK_LAYOUT_TYPES.map((t) => `\`${t}\``).join(", ")}.`,
+  "- `centeredText` — a title card. Slot: `content` (one Component). Optional `background`: `base` or `brand`.",
+  "- `fullBleedImage` — the image IS the slide. Takes `media` directly, plus an optional `overlay` panel whose `content` must be a `richText` Component. It has no other slots.",
+  "- `columnSplit` — two slots, `left` and `right`, each one Component, at a `ratio` of `1-2` or `2-1`.",
+  "",
+  `Components (what fills a Layout slot; \`type\` must be one of these ${DECK_COMPONENT_TYPES.length}): ${DECK_COMPONENT_TYPES.map((t) => `\`${t}\``).join(", ")}.`,
+  "- `richText` — kicker / heading / subheading / paragraphs / bullets. Text only; no media.",
+  "- `image` — one `media` reference and an optional caption.",
+  "- `imageGrid` — two to twelve `items`, each with its own `media`.",
+  "- `video` — one `media` reference.",
+  "",
+  "There is nothing else. A `type` outside those lists is rejected, and so is a slot a Layout does not have — do not invent `body`, `columns`, `slots` or `children`.",
+].join("\n");
+
+const DESCRIPTION = [
+  "Replace the ENTIRE deck with a new version. This is how every change to the deck is made — adding a slide, rewriting a line, reordering, or building the deck from nothing.",
+  "",
+  VOCABULARY,
+  "",
+  "Rules:",
+  "- Emit the COMPLETE deck every time, including slides you are not changing. There is no patch or partial form: whatever you send becomes the deck, and anything you leave out is deleted.",
+  `- Keep \`id\` exactly as it is in the current deck, and keep \`schemaVersion\` at ${DECK_SCHEMA_VERSION}.`,
+  "- Reuse a slide's existing `id` when that slide survives the edit, so revisions stay diffable. Give a genuinely new slide a new lowercase-hyphen id that no other slide uses.",
+  "- Every `media` reference must be a portal media id copied exactly from the Media catalog in your instructions. Never invent one, and never use a filename, path or URL.",
+  `- At most ${DECK_MAX_SLIDES} slides.`,
+  "",
+  "Say what you changed in your reply text; do not restate the deck JSON there.",
+].join("\n");
+
+export function updateDeckTool(): DeckToolDefinition {
+  const schema = z.toJSONSchema(DeckSchema, {
+    // `io: "input"` is what makes fields with defaults optional — under
+    // "output" the model would be told `background` is required. `unrepresentable
+    // : "any"` is for the superRefines (duplicate slide ids, the "a richText
+    // needs some content" rule); they are enforced server-side by parseDeck,
+    // and their messages are what a failed turn gets handed back.
+    target: "draft-2020-12",
+    io: "input",
+    unrepresentable: "any",
+  }) as Record<string, unknown>;
+  // The provider takes the schema body directly; `$schema` is inert there and
+  // is just tokens on every request.
+  delete schema.$schema;
+  return { name: UPDATE_DECK_TOOL_NAME, description: DESCRIPTION, input_schema: schema };
+}

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.ts

@@ -2,6 +2,7 @@ import type { LoadedSection } from "./loader";
 import { getSection, type SectionRegistry } from "./registry";
 import { audiencePasses, pageDisplayTitle } from "./pages";
 import { navEntries } from "./nav-tree";
+import { getContainerChildren } from "./container-ops";
 import type { SiteIndex } from "../schemas/site-config";
 import type { SiteDocument } from "./documents";
 
@@ -28,6 +29,25 @@ export function toSectionId(text: string): string {
   return `section-${Math.abs(hash).toString(36)}`;
 }
 
+/**
+ * Container children are real blocks on the page and their headings render with
+ * anchors like any other, so nav has to walk into them — a Sub Heading dropped
+ * into a container was silently missing from the sidebar. Children inherit the
+ * container's meta (its status governs theirs), and they take the container's
+ * slot in document order.
+ */
+function flattenForNav(sections: LoadedSection[]): LoadedSection[] {
+  const flat: LoadedSection[] = [];
+  const walk = (loaded: LoadedSection) => {
+    flat.push(loaded);
+    for (const child of getContainerChildren(loaded.section)) {
+      walk({ section: child, meta: loaded.meta });
+    }
+  };
+  sections.forEach(walk);
+  return flat;
+}
+
 export function generateNavLinks(
   sections: LoadedSection[],
   registry?: SectionRegistry,
@@ -41,7 +61,7 @@ export function generateNavLinks(
     return def?.navRole;
   };
 
-  for (const { section, meta } of sections) {
+  for (const { section, meta } of flattenForNav(sections)) {
     const content = section.content as { heading?: string; excludeFromNav?: boolean };
     if (!content.heading) continue;
 

package/src/schemas/deck-meta.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { DeckIdSchema, formatDeckIssues } from "./deck";
+
+/**
+ * `decks/{deckId}/meta.json` — the sidecar beside a published deck on the
+ * Decks Branch (ADR 0002). It carries everything a listing needs, so the list
+ * route never reads a single `deck.json`.
+ *
+ * Ownership is dual-identity from day one (feasibility decision 9): a viewer
+ * credential, an editor session, or — on env-mode standalone portals, which
+ * have no named credentials — the audience alone. Retrofitting that later
+ * would mean rewriting every deck's meta.
+ */
+
+/** Bumped when the sidecar's shape changes in a way old readers can't parse. */
+export const DECK_META_SCHEMA_VERSION = 1;
+
+/**
+ * Who owns a deck. `viewer` is the normal case (ownership is credential-keyed);
+ * `editor` covers a deck an agency editor built; `audience` is the env-mode
+ * standalone degradation, where a shared per-audience password means there is
+ * no person to attribute to.
+ */
+export const DeckOwnerSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("viewer"),
+    /** The `viewer_credentials` username — the person-level key. */
+    username: z.string().min(1).max(200),
+    /** The audience that credential signed in as, for editor-side context. */
+    audience: z.string().min(1).max(200),
+  }),
+  z.object({
+    kind: z.literal("editor"),
+    userId: z.string().min(1).max(200),
+  }),
+  z.object({
+    kind: z.literal("audience"),
+    audience: z.string().min(1).max(200),
+  }),
+]);
+
+/**
+ * Deliberately a LOOSE object: grants and the Public Link token land in later
+ * tickets (#36/#37), and a portal running an older package version must not
+ * silently strip fields it doesn't know when it rewrites this file. This is the
+ * same failure mode the nav sidecar exists to avoid — with unknown keys
+ * preserved, an old writer round-trips them instead of deleting them.
+ */
+export const DeckMetaSchema = z.looseObject({
+  schemaVersion: z.literal(DECK_META_SCHEMA_VERSION),
+  id: DeckIdSchema,
+  /** Mirrors deck.title so a listing needs no deck body. */
+  title: z.string().min(1).max(120),
+  /** Mirrors deck.slides.length, for the same reason. */
+  slideCount: z.number().int().min(1),
+  owner: DeckOwnerSchema,
+  createdAt: z.iso.datetime(),
+  updatedAt: z.iso.datetime(),
+  /**
+   * Bucket hashes this deck's media resolved to when it was published, and the
+   * whole reason publish-time GC can protect them (ADR 0002).
+   *
+   * A deck references media by MANIFEST ID, and an id is only resolvable to a
+   * bucket hash while the manifest still carries the entry — which is exactly
+   * what stops being true in the case the keep-set exists for: the editor
+   * removes the media from the library, the entry goes, and the object then
+   * looks unreferenced to every reader. Resolving at publish time and recording
+   * the answer here is what survives that. Absent when the deck references no
+   * bucket-backed media, which is every deck until the media components land.
+   */
+  assetHashes: z.array(z.string().min(1)).optional(),
+});
+
+export type DeckOwner = z.infer<typeof DeckOwnerSchema>;
+export type DeckMeta = z.infer<typeof DeckMetaSchema>;
+
+export type DeckMetaParseResult = { ok: true; meta: DeckMeta } | { ok: false; errors: string[] };
+
+/** Parse an untrusted meta sidecar, reporting every problem at once. */
+export function parseDeckMeta(input: unknown): DeckMetaParseResult {
+  const result = DeckMetaSchema.safeParse(input);
+  return result.success ? { ok: true, meta: result.data } : { ok: false, errors: formatDeckIssues(result.error) };
+}
+
+/** Pretty-printed with a trailing newline, matching every other repo-stored JSON. */
+export function serializeDeckMeta(meta: DeckMeta): string {
+  return JSON.stringify(meta, null, 2) + "\n";
+}