@drawnagency/primitives 0.1.95 → 0.1.97

package/src/hooks/useSortableNavRow.ts

@@ -0,0 +1,139 @@
+import { useEffect, useRef, useState } from "react";
+import { computeNavDropTarget } from "../lib/reorder";
+import type { NavLocation, NavRow } from "../lib/nav-tree";
+
+interface Options {
+  /** This row's identity — supplies the source location and the drop container. */
+  row: NavRow;
+  /** The row's index in the TOP-LEVEL entry list (a member row: its group's index). */
+  entryIndex: number;
+  kind: "page" | "group";
+  onMove: (from: NavLocation, to: NavLocation) => void;
+  enabled?: boolean;
+}
+
+const DRAG_TYPE = "nav-tree-row";
+
+/**
+ * Closest-edge drag wiring for one Pages-modal nav row. A sibling of
+ * useSortableRow that speaks NavLocation instead of a flat index; the section
+ * modal keeps using the original, so this cannot regress it.
+ *
+ * Loads the atlaskit adapter lazily, matching useSortableRow, so it stays out
+ * of the SSR and initial bundles.
+ */
+export function useSortableNavRow<R extends HTMLElement, H extends HTMLElement>({
+  row, entryIndex, kind, onMove, enabled = true,
+}: Options) {
+  const rowRef = useRef<R>(null);
+  const handleRef = useRef<H>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const [closestEdge, setClosestEdge] = useState<"top" | "bottom" | null>(null);
+  const [isDropTarget, setIsDropTarget] = useState(false);
+
+  // Read through a ref so the atlaskit effect doesn't re-subscribe every render.
+  const latest = useRef({ row, entryIndex, kind, onMove });
+  latest.current = { row, entryIndex, kind, onMove };
+
+  // MUST be a pure helper reading from `latest.current`, never a render-scope
+  // closure. The effect deliberately does not re-subscribe when the row's
+  // position changes, so a closure captured at mount would make every drag
+  // AFTER the first reorder report a stale `from` — and moveNavEntry would
+  // splice the wrong slot. Silent wrong-item moves, no error anywhere.
+  // (`useSortableRow` avoids this by re-subscribing on `[index, …]`; this hook
+  // cannot, because its identity is a NavLocation rather than a single number.)
+  const locationOf = (r: NavRow, ei: number): NavLocation =>
+    r.kind === "group"
+      ? { groupId: null, index: ei }
+      : r.kind === "page"
+        ? { groupId: r.groupId, index: r.index }
+        : r.kind === "empty-group"
+          ? { groupId: r.groupId, index: 0 }
+          : { groupId: null, index: ei };
+
+  useEffect(() => {
+    if (!enabled) return;
+    const element = rowRef.current;
+    const handle = handleRef.current;
+    if (!element) return;
+    // Only draggable rows need a handle; empty-group and tail rows are drop-only.
+    const dropOnly = row.kind === "empty-group" || row.kind === "tail";
+    if (!dropOnly && !handle) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+
+    Promise.all([
+      import("@atlaskit/pragmatic-drag-and-drop/element/adapter"),
+      import("@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge"),
+    ]).then(([{ draggable, dropTargetForElements }, { attachClosestEdge, extractClosestEdge }]) => {
+      if (cancelled) return;
+      const cleanups: (() => void)[] = [];
+
+      if (!dropOnly && handle) {
+        cleanups.push(draggable({
+          element, dragHandle: handle,
+          getInitialData: () => ({
+            dragType: DRAG_TYPE,
+            kind,
+            from: locationOf(latest.current.row, latest.current.entryIndex),
+          }),
+          onGenerateDragPreview: () => {
+            element.style.opacity = "0.4";
+            requestAnimationFrame(() => { element.style.opacity = ""; });
+          },
+          onDragStart: () => setIsDragging(true),
+          onDrop: () => setIsDragging(false),
+        }));
+      }
+
+      const resolve = (source: Record<string, unknown>, edge: "top" | "bottom" | null) =>
+        computeNavDropTarget({
+          from: source.from as NavLocation,
+          fromKind: source.kind as "page" | "group",
+          over: latest.current.row,
+          overEntryIndex: latest.current.entryIndex,
+          edge,
+        });
+
+      cleanups.push(dropTargetForElements({
+        element,
+        canDrop: ({ source }) => source.data.dragType === DRAG_TYPE,
+        getData: ({ input, element: el }) =>
+          attachClosestEdge({}, { input, element: el, allowedEdges: ["top", "bottom"] }),
+        onDragEnter: ({ self, source }) => {
+          const raw = extractClosestEdge(self.data);
+          const edge = raw === "top" || raw === "bottom" ? raw : null;
+          // Show an indicator only where the drop would actually land, so a
+          // rejected target reads as inert rather than as a silent failure.
+          const target = resolve(source.data, edge);
+          setClosestEdge(target ? edge : null);
+          setIsDropTarget(!!target);
+        },
+        onDrag: ({ self, source }) => {
+          const raw = extractClosestEdge(self.data);
+          const edge = raw === "top" || raw === "bottom" ? raw : null;
+          const target = resolve(source.data, edge);
+          setClosestEdge(target ? edge : null);
+          setIsDropTarget(!!target);
+        },
+        onDragLeave: () => { setClosestEdge(null); setIsDropTarget(false); },
+        onDrop: ({ self, source }) => {
+          setClosestEdge(null);
+          setIsDropTarget(false);
+          const raw = extractClosestEdge(self.data);
+          const edge = raw === "top" || raw === "bottom" ? raw : null;
+          const target = resolve(source.data, edge);
+          if (target) latest.current.onMove(source.data.from as NavLocation, target);
+        },
+      }));
+
+      cleanup = () => cleanups.forEach((c) => c());
+    });
+
+    return () => { cancelled = true; cleanup?.(); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, row.kind, kind]);
+
+  return { rowRef, handleRef, isDragging, closestEdge, isDropTarget };
+}

package/src/lib/dexie.ts

@@ -1,6 +1,7 @@
 import Dexie from "dexie";
 import type { SectionContent } from "../schemas/sections";
 import type { SiteIndex, SectionMeta, SiteConfig, Page } from "../schemas/site-config";
+import type { NavEntry } from "../schemas/nav";
 import type { LoadedSection } from "./loader";
 import type { MediaManifest, MediaItem } from "../media/types";
 
@@ -15,6 +16,8 @@ interface SiteIndexRow {
   key: string;
   pages: Page[];
   sections: Record<string, SectionMeta>;
+  /** Optional: rows written before page groups shipped have no nav. */
+  nav?: NavEntry[];
   deletedSections: string[];
   updatedAt: string;
 }
@@ -237,7 +240,7 @@ export async function restoreLocalChanges(): Promise<{
     const siteId = metaRow?.siteId ?? "";
     return {
       sections,
-      siteIndex: { siteId, pages: indexRow.pages, sections: indexRow.sections },
+      siteIndex: { siteId, pages: indexRow.pages, sections: indexRow.sections, nav: indexRow.nav },
       siteConfig: configRow?.config,
       deletedSections: indexRow.deletedSections ?? [],
     };
@@ -266,6 +269,7 @@ export async function persistSiteIndex(index: SiteIndex, deletedSections: string
       key: "current",
       pages: index.pages,
       sections: index.sections,
+      nav: index.nav,
       deletedSections,
       updatedAt: now,
     });
@@ -389,6 +393,7 @@ export async function persistAll(
           key: "current",
           pages: siteIndex.pages,
           sections: siteIndex.sections,
+          nav: siteIndex.nav,
           deletedSections: [],
           updatedAt: now,
         });

package/src/lib/index-ops.ts

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { IndexSchema, RESERVED_SLUGS, type SiteIndex, type SectionMeta } from "../schemas/site-config";
+
+/**
+ * Server-applied index deltas for the MCP connector's save path. An agent
+ * cannot reliably hand-transcribe a real site's 40–51 KB index into a tool
+ * parameter (two consecutive attempts each introduced an id-level slip), so
+ * structural edits are expressed as ops and applied here against the index the
+ * write is concurrency-checked against.
+ *
+ * Pure by contract: no I/O, no storage, no octokit. The caller owns reading the
+ * base index at the right commit and committing the result.
+ */
+
+// The three canonical statuses. Deliberately a plain enum rather than the
+// schemas' StatusSchema (a ZodPipe with a "published" -> "live" transform):
+// this shape is converted to JSON Schema for MCP clients, so it stays a flat
+// enum, and reads never surface "published" anyway (they return normalized
+// values).
+const OpStatusSchema = z.enum(["draft", "live", "archived"]);
+
+// Must match content-ops' SAFE_SECTION_ID: the id becomes a FILENAME
+// (src/content/sections/<id>.json). Enforced here so a bad id is a named op
+// error rather than a bare "[input] Invalid section ID" from deep in the write
+// path, which names neither the op nor the id.
+const SAFE_SECTION_ID = /^[a-zA-Z0-9_-]{1,64}$/;
+
+const SectionInsertSchema = z.object({
+  id: z.string().regex(SAFE_SECTION_ID, "Section ids may only contain letters, numbers, dashes and underscores (max 64 chars) — they become filenames.").describe("The new section's id: letters, numbers, dashes, underscores; max 64 chars. Must not already exist in the index."),
+  status: OpStatusSchema.optional().describe('Defaults to "draft" — invisible to viewers until promoted to "live".'),
+  access: z.array(z.string()).optional().describe("Audience slugs from list_audiences. Defaults to [] (everyone)."),
+});
+
+export const IndexOpSchema = z.discriminatedUnion("op", [
+  z.object({
+    op: z.literal("insertAfter"),
+    pageId: z.string().describe("The page whose order receives the sections."),
+    afterId: z.string().nullable().describe("Insert directly after this section id, or null for the start of the page."),
+    sections: z.array(SectionInsertSchema).min(1).describe("Sections to create, in the order they should appear. Each needs its body in this call's `sections`."),
+  }),
+  z.object({
+    op: z.literal("insertAt"),
+    pageId: z.string().describe("The page whose order receives the sections."),
+    position: z.number().int().min(0).describe("0-based index in the page's order; equal to the order's length appends."),
+    sections: z.array(SectionInsertSchema).min(1).describe("Sections to create, in the order they should appear. Each needs its body in this call's `sections`."),
+  }),
+  z.object({
+    op: z.literal("move"),
+    pageId: z.string().describe("Destination page id (may be the section's current page)."),
+    id: z.string().describe("The existing section to move."),
+    afterId: z.string().nullable().describe("Place it directly after this section id in the destination page, or null for the start."),
+  }),
+  z.object({
+    op: z.literal("remove"),
+    ids: z.array(z.string()).min(1).describe("Sections to delete: removed from the page order AND from sections{}, and their content files are deleted."),
+  }),
+  z.object({
+    op: z.literal("setMeta"),
+    id: z.string().describe("An existing section id."),
+    status: OpStatusSchema.optional().describe('New status. "live" is what makes a section visible to viewers.'),
+    access: z.array(z.string()).optional().describe("New audience slugs from list_audiences; [] means everyone."),
+  }),
+  z.object({
+    op: z.literal("setPageMeta"),
+    pageId: z.string().describe("An existing page id."),
+    title: z.string().optional().describe("New page title."),
+    slug: z.string().optional().describe("New URL slug (lowercase words joined by dashes). Not settable on the home page, whose slug is always empty."),
+    showInNav: z.boolean().optional().describe("Whether the page appears in site navigation."),
+    access: z.array(z.string()).optional().describe("New audience slugs from list_audiences; [] means everyone."),
+  }),
+]);
+
+export type IndexOp = z.infer<typeof IndexOpSchema>;
+
+export type ApplyIndexOpsResult =
+  | { ok: true; index: SiteIndex; removedIds: string[]; warnings: string[] }
+  | { ok: false; error: string };
+
+/** Section-body types keyed by id, for the ids an insert op creates. */
+export function collectPostedTypes(sections: { id: string; content: unknown }[] | undefined): Record<string, string> {
+  const types: Record<string, string> = {};
+  for (const s of sections ?? []) {
+    const type = (s.content as { type?: unknown } | null | undefined)?.type;
+    if (typeof type === "string") types[s.id] = type;
+  }
+  return types;
+}
+
+/**
+ * Every section id the ops name, derivable from the ops ALONE (no index read).
+ * Callers need this before applying anything: the collab broadcast has to tell
+ * browser editors which rows moved, and the audit trail has to record that an
+ * ops-only save touched anything at all. `setPageMeta` names no section.
+ */
+export function opTouchedSectionIds(ops: IndexOp[]): string[] {
+  const ids = new Set<string>();
+  for (const op of ops) {
+    if (op.op === "insertAfter" || op.op === "insertAt") for (const s of op.sections) ids.add(s.id);
+    else if (op.op === "move" || op.op === "setMeta") ids.add(op.id);
+    else if (op.op === "remove") for (const id of op.ids) ids.add(id);
+  }
+  return [...ids];
+}
+
+const fmt = (ids: string[]) => ids.map((id) => `"${id}"`).join(", ");
+
+export function applyIndexOps(
+  rawIndex: unknown,
+  ops: IndexOp[],
+  newSectionTypes: Record<string, string>,
+): ApplyIndexOpsResult {
+  // Apply to the CANONICAL shape, not the raw one: a legacy index
+  // (`order`/`sections` with no `pages`) normalizes into a synthetic home page
+  // carrying those ids, and ops against the raw shape would find no pages at
+  // all and silently miss every id.
+  const base = IndexSchema.safeParse(rawIndex);
+  if (!base.success) {
+    return {
+      ok: false,
+      error:
+        "the site's current index could not be parsed, so indexOps cannot be applied — read it with get_site_index and post a repaired full `index` instead. " +
+        base.error.issues.map((i) => i.message).join("; "),
+    };
+  }
+
+  // Own copy: the caller's index is also its knownSiteTypes source and may be
+  // logged, so nothing here mutates it.
+  const index: SiteIndex = {
+    ...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 }])),
+  };
+
+  const removed = new Set<string>();
+  const warnings: string[] = [];
+  const fail = (error: string): ApplyIndexOpsResult => ({ ok: false, error });
+
+  for (const [i, op] of ops.entries()) {
+    const at = `indexOps[${i}] ${op.op}`;
+
+    if (op.op === "insertAfter" || op.op === "insertAt") {
+      const page = index.pages.find((p) => p.id === op.pageId);
+      if (!page) return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+
+      let position: number;
+      if (op.op === "insertAfter") {
+        if (op.afterId === null) position = 0;
+        else {
+          const idx = page.order.indexOf(op.afterId);
+          if (idx === -1) return fail(`${at}: afterId "${op.afterId}" is not in page "${op.pageId}"'s order.`);
+          position = idx + 1;
+        }
+      } else {
+        if (op.position > page.order.length) {
+          return fail(`${at}: position ${op.position} is out of range for page "${op.pageId}" (valid: 0..${page.order.length}).`);
+        }
+        position = op.position;
+      }
+
+      const metas: [string, SectionMeta][] = [];
+      // Ids in THIS op are not in `index.sections` yet, so the existence check
+      // below cannot see them — without a local seen-set a repeated id splices
+      // twice and only fails at the final re-validation, as "appears in more
+      // than one page order" with no op index and a misleading description.
+      const seen = new Set<string>();
+      for (const s of op.sections) {
+        if (seen.has(s.id)) return fail(`${at}: section "${s.id}" is listed twice in this op's \`sections\`.`);
+        seen.add(s.id);
+        if (index.sections[s.id]) {
+          return fail(`${at}: section "${s.id}" already exists in the index — use move to relocate it, or setMeta to change its status/access.`);
+        }
+        if (!SAFE_SECTION_ID.test(s.id)) {
+          return fail(`${at}: section id "${s.id}" is not usable — ids become filenames, so they may only contain letters, numbers, dashes and underscores (max 64 chars).`);
+        }
+        const type = newSectionTypes[s.id];
+        if (!type) {
+          // Covers both "no body posted" and "body posted but its `type` is
+          // missing or not a string" — collectPostedTypes only records usable
+          // string types, so this cannot tell them apart, and the old wording
+          // ("has no body") sent an agent hunting for a body that was right there.
+          return fail(`${at}: section "${s.id}" has no usable body in this call — post its full body ({ "type": "...", "content": {...} }) in \`sections\` in the same save; an inserted section's type comes from the body.`);
+        }
+        const meta: SectionMeta = { type, status: s.status ?? "draft", access: s.access ?? [] };
+        // 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.`,
+          );
+        }
+        metas.push([s.id, meta]);
+      }
+      page.order.splice(position, 0, ...metas.map(([id]) => id));
+      for (const [id, meta] of metas) index.sections[id] = meta;
+      continue;
+    }
+
+    if (op.op === "move") {
+      const meta = index.sections[op.id];
+      if (!meta) return fail(`${at}: section "${op.id}" is not in the index.`);
+      const dest = index.pages.find((p) => p.id === op.pageId);
+      if (!dest) return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+      if (op.afterId === op.id) return fail(`${at}: cannot move section "${op.id}" after itself.`);
+
+      for (const p of index.pages) {
+        const idx = p.order.indexOf(op.id);
+        if (idx !== -1) p.order.splice(idx, 1);
+      }
+      let position: number;
+      if (op.afterId === null) position = 0;
+      else {
+        const idx = dest.order.indexOf(op.afterId);
+        if (idx === -1) return fail(`${at}: afterId "${op.afterId}" is not in destination page "${op.pageId}"'s order.`);
+        position = idx + 1;
+      }
+      dest.order.splice(position, 0, op.id);
+
+      // Advisory, never a silent rewrite: the editor's moveSection resets an
+      // incompatible section access, but an API doing that invisibly would
+      // 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.`,
+        );
+      }
+      continue;
+    }
+
+    if (op.op === "remove") {
+      for (const id of op.ids) {
+        if (!index.sections[id]) return fail(`${at}: section "${id}" is not in the index.`);
+        delete index.sections[id];
+        for (const p of index.pages) {
+          const idx = p.order.indexOf(id);
+          if (idx !== -1) p.order.splice(idx, 1);
+        }
+        removed.add(id);
+      }
+      continue;
+    }
+
+    if (op.op === "setMeta") {
+      if (op.status === undefined && op.access === undefined) {
+        return fail(`${at}: nothing to set — provide status and/or access.`);
+      }
+      const meta = index.sections[op.id];
+      if (!meta) return fail(`${at}: section "${op.id}" is not in the index.`);
+      if (op.status !== undefined) meta.status = op.status;
+      if (op.access !== undefined) meta.access = op.access;
+      continue;
+    }
+
+    // setPageMeta
+    if (op.title === undefined && op.slug === undefined && op.showInNav === undefined && op.access === undefined) {
+      return fail(`${at}: nothing to set — provide title, slug, showInNav and/or access.`);
+    }
+    const page = index.pages.find((p) => p.id === op.pageId);
+    if (!page) return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+    if (op.slug !== undefined && page.isHome) {
+      return fail(`${at}: the home page's slug is always empty and cannot be set. Promote a different page to home in the editor if you need to change which page is the root.`);
+    }
+    // IndexSchema hard-rejects only the five slugs reserved before client sites
+    // existed (PARSE_REJECTED_SLUGS) — the newer ones ("present", "print") are
+    // enforced at AUTHORING time on purpose, so a grandfathered index still
+    // loads (see schemas/site-config.ts). This is an authoring surface, so it
+    // owns that enforcement; without it a page silently disappears behind an
+    // injected platform route with no error anywhere.
+    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.`);
+    }
+    if (op.title !== undefined) page.title = op.title;
+    if (op.slug !== undefined) page.slug = op.slug;
+    if (op.showInNav !== undefined) page.showInNav = op.showInNav;
+    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.`,
+          );
+        }
+      }
+    }
+  }
+
+  // A remove followed by a re-insert of the same id is a net no-op for files:
+  // reporting it for deletion would delete the file the resulting index
+  // references, and content-ops' stillReferenced guard would reject the write.
+  const removedIds = [...removed].filter((id) => !index.sections[id]);
+
+  // Ops cannot break the order/sections partition by construction, but they can
+  // break page-level invariants the ops above do not check themselves: a
+  // duplicate slug, an invalid slug shape, one of the five parse-rejected legacy
+  // slugs. Re-run the canonical validation so the caller gets those named here
+  // rather than as an opaque ZodError from the write path. (The NEWER reserved
+  // slugs are not in that set — setPageMeta checks them itself, above.)
+  const validated = IndexSchema.safeParse(index);
+  if (!validated.success) {
+    return fail(`applying indexOps produced an invalid index: ${validated.error.issues.map((issue) => issue.message).join("; ")}`);
+  }
+  return { ok: true, index: validated.data, removedIds, warnings };
+}

package/src/lib/index.ts

@@ -3,6 +3,7 @@ export { cn } from "./cn";
 export { audiencePasses } from "./pages";
 export { resolveChatbotName, resolveThinkingPhrases, DEFAULT_CHATBOT_NAME } from "./chatbot";
 export { generateNavLinks, toSectionId, type NavItem } from "./nav";
+export { navEntries, pagesInNavOrder, groupOfPage, groupDisplayLabel, reconcileNav } from "./nav-tree";
 export {
   deriveContrast,
   contrastColor,

package/src/lib/loader.ts

@@ -3,6 +3,7 @@ import { IndexSchema, type SiteIndex, type SectionMeta } from "../schemas/site-c
 import { getAllSchemas } from "./registry";
 import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
 import { upgradeLegacySection } from "./migrate-sections-transform";
+import { NavFileSchema, type NavEntry } from "../schemas/nav";
 
 export interface LoadedSection {
   section: Section;
@@ -14,6 +15,21 @@ export interface SiteContent {
   index: SiteIndex;
 }
 
+/**
+ * Parse the nav.json sidecar defensively. A malformed sidecar must degrade to a
+ * flat nav, never brick the site — nav.json is optional content, and the whole
+ * point of the sidecar is that it tolerates writers that don't understand it.
+ */
+function parseNavFile(navFile: unknown): NavEntry[] {
+  if (!navFile) return [];
+  const result = NavFileSchema.safeParse(navFile);
+  if (!result.success) {
+    console.warn("Invalid nav.json, falling back to a flat navigation");
+    return [];
+  }
+  return result.data.entries;
+}
+
 /**
  * Merge a validated index with raw section file contents.
  * Validates each section file against its Zod schema.
@@ -21,7 +37,8 @@ export interface SiteContent {
  */
 export function mergeSiteContent(
   index: SiteIndex,
-  sectionFiles: Record<string, unknown>
+  sectionFiles: Record<string, unknown>,
+  navFile?: unknown,
 ): SiteContent {
   const sections: LoadedSection[] = [];
 
@@ -66,7 +83,7 @@ export function mergeSiteContent(
     }
   }
 
-  return { sections, index };
+  return { sections, index: { ...index, nav: parseNavFile(navFile) } };
 }
 
 /**
@@ -77,6 +94,7 @@ export function mergeSiteContent(
 export function loadStaticSiteContent(
   index: SiteIndex,
   sectionGlob: Record<string, unknown>,
+  navFile?: unknown,
 ): SiteContent {
   const sectionFiles: Record<string, unknown> = {};
   for (const [path, data] of Object.entries(sectionGlob)) {
@@ -84,7 +102,7 @@ export function loadStaticSiteContent(
     const id = filename.replace(".json", "");
     sectionFiles[id] = data;
   }
-  return mergeSiteContent(index, sectionFiles);
+  return mergeSiteContent(index, sectionFiles, navFile);
 }
 
 /**
@@ -105,5 +123,14 @@ export async function loadSiteContent(contentDir: string): Promise<SiteContent>
     sectionFiles[id] = JSON.parse(await fs.readFile(sectionPath, "utf-8"));
   }
 
-  return mergeSiteContent(index, sectionFiles);
+  // 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;
+  try {
+    navFile = JSON.parse(await fs.readFile(path.join(contentDir, "nav.json"), "utf-8"));
+  } catch {
+    navFile = undefined;
+  }
+
+  return mergeSiteContent(index, sectionFiles, navFile);
 }