@drawnagency/primitives 0.1.96 → 0.1.98

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,7 +393,13 @@ export async function persistAll(
           key: "current",
           pages: siteIndex.pages,
           sections: siteIndex.sections,
-          deletedSections: [],
+          nav: siteIndex.nav,
+          // Record the deletion INTENT, not just its effect on the order. The
+          // restore path reads this back; when it was hardcoded `[]` that path
+          // had to re-derive deletions by diffing this snapshot against a fresh
+          // remote read, which treats a third party's additions (MCP connector,
+          // peer editor) as this editor's deletions.
+          deletedSections: deletedSectionIds ?? [],
           updatedAt: now,
         });
         await database.meta.put({

package/src/lib/index-ops.ts

@@ -1,5 +1,15 @@
 import { z } from "zod";
-import { IndexSchema, RESERVED_SLUGS, type SiteIndex, type SectionMeta } from "../schemas/site-config";
+import { IndexSchema, PageStatusSchema, RESERVED_SLUGS, SLUG_RE, type SiteIndex, type SectionMeta } from "../schemas/site-config";
+import type { NavEntry, NavGroupEntry } from "../schemas/nav";
+import type { NavLocation } from "./nav-tree";
+// Page and nav mutations are shared with the editor rather than reimplemented:
+// both surfaces must agree on what "delete a page" or "remove a group" means, and
+// a second implementation here is how they would drift.
+import { addPage as addPageToIndex, deletePage, slugifyPageSlug, uniquePageSlug } from "./pages";
+import {
+  addGroup, deleteGroup, groupOfPage, moveNavEntry, navEntries, reconcileNav,
+  renameGroup, setGroupStartCollapsed,
+} from "./nav-tree";
 
 /**
  * Server-applied index deltas for the MCP connector's save path. An agent
@@ -25,6 +35,11 @@ const OpStatusSchema = z.enum(["draft", "live", "archived"]);
 // path, which names neither the op nor the id.
 const SAFE_SECTION_ID = /^[a-zA-Z0-9_-]{1,64}$/;
 
+// Page and nav-group ids are not filenames, but they are dictionary keys an
+// agent has to echo back, so they get the same tame character set. Keeping the
+// shapes identical also means one remembered rule covers every id in this API.
+const SAFE_ENTITY_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".'),
@@ -67,10 +82,81 @@ export const IndexOpSchema = z.discriminatedUnion("op", [
     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."),
+    status: PageStatusSchema.optional().describe('Page status. "archived" hides the page and its sections from viewers without deleting anything; the home page cannot be archived.'),
+  }),
+  z.object({
+    op: z.literal("addPage"),
+    id: z.string().regex(SAFE_ENTITY_ID, "Page ids may only contain letters, numbers, dashes and underscores (max 64 chars).").describe("The new page's id: letters, numbers, dashes, underscores; max 64 chars. Must not already exist."),
+    title: z.string().describe("Page title, shown in navigation."),
+    slug: z.string().optional().describe("URL slug (lowercase words joined by dashes). Defaults to a unique slug derived from the title."),
+    showInNav: z.boolean().optional().describe("Whether the page appears in site navigation. Defaults to true."),
+    access: z.array(z.string()).optional().describe("Audience slugs from list_audiences. Defaults to [] (everyone)."),
+    navGroupId: z.string().optional().describe("Put the new page inside this existing nav group instead of at the top level."),
+  }),
+  z.object({
+    op: z.literal("removePage"),
+    pageId: z.string().describe("The page to delete. The home page cannot be deleted."),
+    removeSections: z.boolean().optional().describe("Required `true` when the page still holds sections — they are deleted with it and their content files removed. Without it a non-empty page is refused, so a page is never emptied by accident."),
+  }),
+  z.object({
+    op: z.literal("addNavGroup"),
+    id: z.string().regex(SAFE_ENTITY_ID, "Nav group ids may only contain letters, numbers, dashes and underscores (max 64 chars).").describe("The new group's id: letters, numbers, dashes, underscores; max 64 chars."),
+    label: z.string().optional().describe('Group heading in the sidebar. Blank renders as "Untitled group".'),
+    startCollapsed: z.boolean().optional().describe("Whether the group renders collapsed on first viewer load. Defaults to false."),
+    pageIds: z.array(z.string()).optional().describe("Existing page ids to move into the group, in order. A page belongs to at most one group, so listing it here removes it from wherever it was."),
+  }),
+  z.object({
+    op: z.literal("removeNavGroup"),
+    groupId: z.string().describe("The group to remove. Its member pages are NOT deleted — they become top-level nav entries at the group's former position."),
+  }),
+  z.object({
+    op: z.literal("setNavGroupMeta"),
+    groupId: z.string().describe("An existing nav group id."),
+    label: z.string().optional().describe("New sidebar heading."),
+    startCollapsed: z.boolean().optional().describe("Whether the group renders collapsed on first viewer load."),
+  }),
+  z.object({
+    op: z.literal("movePageInNav"),
+    pageId: z.string().describe("The page to reposition in the sidebar."),
+    groupId: z.string().nullable().describe("Destination group id, or null to move the page out to the top level."),
+    position: z.number().int().min(0).optional().describe("0-based slot within the destination (inside the group, or among top-level nav entries). Defaults to the end."),
   }),
 ]);
 
-export type IndexOp = z.infer<typeof IndexOpSchema>;
+/**
+ * Written out rather than `z.infer<typeof IndexOpSchema>`.
+ *
+ * The MCP SDK infers a tool's handler and JSON-Schema types from the Zod shape it
+ * is registered with, and at twelve union members each carrying several described
+ * optionals, re-deriving this union at that boundary overflowed tsc's stack — the
+ * `apps/mcp` typecheck segfaulted rather than failing with a diagnostic. Naming
+ * the type once caps that inference: consumers see this union directly instead of
+ * re-deriving it through the schema. `assertIndexOpTypesMatchSchema` in
+ * tests/lib/index-ops.test.ts pins the two together so they cannot drift.
+ */
+export type IndexOp =
+  | { op: "insertAfter"; pageId: string; afterId: string | null; sections: SectionInsert[] }
+  | { op: "insertAt"; pageId: string; position: number; sections: SectionInsert[] }
+  | { op: "move"; pageId: string; id: string; afterId: string | null }
+  | { op: "remove"; ids: string[] }
+  | { op: "setMeta"; id: string; status?: OpStatus; access?: string[] }
+  | {
+      op: "setPageMeta"; pageId: string; title?: string; slug?: string;
+      showInNav?: boolean; access?: string[]; status?: PageStatus;
+    }
+  | {
+      op: "addPage"; id: string; title: string; slug?: string;
+      showInNav?: boolean; access?: string[]; navGroupId?: string;
+    }
+  | { op: "removePage"; pageId: string; removeSections?: boolean }
+  | { op: "addNavGroup"; id: string; label?: string; startCollapsed?: boolean; pageIds?: string[] }
+  | { op: "removeNavGroup"; groupId: string }
+  | { op: "setNavGroupMeta"; groupId: string; label?: string; startCollapsed?: boolean }
+  | { op: "movePageInNav"; pageId: string; groupId: string | null; position?: number };
+
+type OpStatus = z.infer<typeof OpStatusSchema>;
+type PageStatus = z.infer<typeof PageStatusSchema>;
+type SectionInsert = z.infer<typeof SectionInsertSchema>;
 
 export type ApplyIndexOpsResult =
   | { ok: true; index: SiteIndex; removedIds: string[]; warnings: string[] }
@@ -104,6 +190,35 @@ export function opTouchedSectionIds(ops: IndexOp[]): string[] {
 
 const fmt = (ids: string[]) => ids.map((id) => `"${id}"`).join(", ");
 
+/**
+ * Id-based reparent/reposition of a page in the nav, expressed over the editor's
+ * index-based `moveNavEntry` primitive. Agents address pages and groups by id;
+ * the drag-and-drop surface addresses slots — this is the adapter between them,
+ * so both still go through one move implementation.
+ *
+ * `position === undefined` appends. `moveNavEntry` lifts the page out of its
+ * source container BEFORE inserting, so an append index computed against the
+ * pre-removal length can overshoot by one; it clamps, so that is safe.
+ */
+function moveIntoGroup(
+  index: SiteIndex,
+  pageId: string,
+  groupId: string | null,
+  position: number | undefined,
+): SiteIndex {
+  const entries = navEntries(index);
+  const currentGroup = groupOfPage(index, pageId);
+  // navEntries reconciles, so the page is guaranteed to appear exactly once —
+  // either as a top-level entry or inside exactly one group.
+  const from: NavLocation = currentGroup
+    ? { groupId: currentGroup.id, index: currentGroup.pageIds.indexOf(pageId) }
+    : { groupId: null, index: entries.findIndex((e) => e.kind === "page" && e.pageId === pageId) };
+  const destLength = groupId === null
+    ? entries.length
+    : entries.find((e): e is NavGroupEntry => e.kind === "group" && e.id === groupId)?.pageIds.length ?? 0;
+  return moveNavEntry(index, from, { groupId, index: position ?? destLength });
+}
+
 export function applyIndexOps(
   rawIndex: unknown,
   ops: IndexOp[],
@@ -123,17 +238,30 @@ export function applyIndexOps(
     };
   }
 
+  // IndexSchema strips `nav` (that strip is what keeps the sidecar out of
+  // index.json), so the authored nav has to be lifted off the RAW input to be
+  // available to the nav ops below. reconcileNav is total, so an unparseable
+  // shape here degrades to a flat nav rather than failing.
+  const rawNav = (rawIndex as { nav?: unknown } | null | undefined)?.nav;
+
   // Own copy: the caller's index is also its knownSiteTypes source and may be
-  // logged, so nothing here mutates it.
-  const index: SiteIndex = {
+  // logged, so nothing here mutates it. Reassigned by the page/nav ops, which
+  // are shared immutable helpers rather than in-place mutators.
+  let 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 }])),
+    ...(Array.isArray(rawNav) ? { nav: rawNav as NavEntry[] } : {}),
   };
 
   const removed = new Set<string>();
   const warnings: 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
+  // the posted index carries a `nav`, so omitting it is what guarantees an
+  // ordinary indexOps write cannot disturb a site's page groups.
+  let navTouched = false;
 
   for (const [i, op] of ops.entries()) {
     const at = `indexOps[${i}] ${op.op}`;
@@ -255,12 +383,129 @@ export function applyIndexOps(
       continue;
     }
 
+    if (op.op === "addPage") {
+      if (index.pages.some((p) => p.id === op.id)) {
+        return fail(`${at}: a page with id "${op.id}" already exists — use setPageMeta to edit it.`);
+      }
+      let slug: string;
+      if (op.slug !== undefined) {
+        // An explicit slug is never silently rewritten: uniquePageSlug would
+        // quietly hand back "about-2" and the agent would keep addressing "about".
+        if (!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 ((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 (index.pages.some((p) => p.slug === op.slug)) {
+          return fail(`${at}: slug "${op.slug}" is already used by another page. Slugs must be unique.`);
+        }
+        slug = op.slug;
+      } else {
+        // Derived slugs MAY be de-duplicated — nothing is addressing them yet.
+        slug = uniquePageSlug(slugifyPageSlug(op.title), index.pages.map((p) => p.slug));
+      }
+      if (op.navGroupId !== undefined && !navEntries(index).some((e) => e.kind === "group" && e.id === op.navGroupId)) {
+        return fail(`${at}: no nav group with id "${op.navGroupId}" — create it with addNavGroup first, or omit navGroupId to place the page at the top level.`);
+      }
+      index = addPageToIndex(index, op.id);
+      const created = index.pages.find((p) => p.id === op.id)!;
+      created.title = op.title;
+      created.slug = slug;
+      if (op.showInNav !== undefined) created.showInNav = op.showInNav;
+      if (op.access !== undefined) created.access = op.access;
+      if (op.navGroupId !== undefined) {
+        // addPageToIndex appended a top-level nav entry; lift it into the group.
+        index = moveIntoGroup(index, op.id, op.navGroupId, undefined);
+      }
+      navTouched = true;
+      continue;
+    }
+
+    if (op.op === "removePage") {
+      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 (page.isHome) {
+        return fail(`${at}: the home page cannot be removed — it is the site's root. Promote a different page to home in the editor first.`);
+      }
+      if (page.order.length > 0 && op.removeSections !== true) {
+        return fail(
+          `${at}: page "${op.pageId}" still holds ${page.order.length} section(s) (${fmt(page.order.slice(0, 5))}${page.order.length > 5 ? ", …" : ""}). ` +
+            "Pass removeSections: true to delete them with the page, or move them elsewhere first with move ops.",
+        );
+      }
+      const result = deletePage(index, op.pageId);
+      index = result.index;
+      for (const id of result.removedSectionIds) removed.add(id);
+      navTouched = true;
+      continue;
+    }
+
+    if (op.op === "addNavGroup") {
+      const entries = navEntries(index);
+      if (entries.some((e) => e.kind === "group" && e.id === op.id)) {
+        return fail(`${at}: a nav group with id "${op.id}" already exists — use setNavGroupMeta to edit it.`);
+      }
+      const missing = (op.pageIds ?? []).filter((id) => !index.pages.some((p) => p.id === id));
+      if (missing.length > 0) {
+        return fail(`${at}: no page with id ${fmt(missing)} — page ids come from get_site_index.`);
+      }
+      index = addGroup(index, op.id);
+      if (op.label !== undefined) index = renameGroup(index, op.id, op.label);
+      if (op.startCollapsed !== undefined) index = setGroupStartCollapsed(index, op.id, op.startCollapsed);
+      // In the order given: each move appends, so listing pages here places them
+      // in that sequence regardless of their previous nav positions.
+      for (const pageId of op.pageIds ?? []) index = moveIntoGroup(index, pageId, op.id, undefined);
+      navTouched = true;
+      continue;
+    }
+
+    if (op.op === "removeNavGroup") {
+      if (!navEntries(index).some((e) => e.kind === "group" && e.id === op.groupId)) {
+        return fail(`${at}: no nav group with id "${op.groupId}" — group ids come from the \`nav\` on get_site_index.`);
+      }
+      index = deleteGroup(index, op.groupId);
+      navTouched = true;
+      continue;
+    }
+
+    if (op.op === "setNavGroupMeta") {
+      if (op.label === undefined && op.startCollapsed === undefined) {
+        return fail(`${at}: nothing to set — provide label and/or startCollapsed.`);
+      }
+      if (!navEntries(index).some((e) => e.kind === "group" && e.id === op.groupId)) {
+        return fail(`${at}: no nav group with id "${op.groupId}" — group ids come from the \`nav\` on get_site_index.`);
+      }
+      if (op.label !== undefined) index = renameGroup(index, op.groupId, op.label);
+      if (op.startCollapsed !== undefined) index = setGroupStartCollapsed(index, op.groupId, op.startCollapsed);
+      navTouched = true;
+      continue;
+    }
+
+    if (op.op === "movePageInNav") {
+      if (!index.pages.some((p) => p.id === op.pageId)) {
+        return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+      }
+      if (op.groupId !== null && !navEntries(index).some((e) => e.kind === "group" && e.id === op.groupId)) {
+        return fail(`${at}: no nav group with id "${op.groupId}" — group ids come from the \`nav\` on get_site_index.`);
+      }
+      index = moveIntoGroup(index, op.pageId, op.groupId, op.position);
+      navTouched = true;
+      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.`);
+    if (
+      op.title === undefined && op.slug === undefined && op.showInNav === undefined &&
+      op.access === undefined && op.status === undefined
+    ) {
+      return fail(`${at}: nothing to set — provide title, slug, showInNav, access and/or status.`);
     }
     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.status === "archived" && page.isHome) {
+      return fail(`${at}: the home page cannot be archived — it is the site's root. Promote a different page to home in the editor first.`);
+    }
     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.`);
     }
@@ -276,6 +521,7 @@ export function applyIndexOps(
     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.status !== undefined) page.status = op.status;
     if (op.access !== undefined) {
       const dropped = page.access.filter((a) => !op.access!.includes(a));
       page.access = op.access;
@@ -305,5 +551,13 @@ export function applyIndexOps(
   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 };
+  // The parse above stripped `nav`. Reattach it ONLY when an op actually changed
+  // the navigation, reconciled against the resulting page set so a batch that
+  // added or removed pages emits a complete tree. When no nav op ran the result
+  // carries no `nav` at all, so content-ops leaves nav.json untouched and page
+  // groups survive untouched — the invariant every section-level op relies on.
+  const result: SiteIndex = navTouched
+    ? { ...validated.data, nav: reconcileNav(index.nav ?? [], validated.data.pages) }
+    : validated.data;
+  return { ok: true, index: result, 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);
 }