@drawnagency/primitives 0.1.97 → 0.1.99

package/src/hooks/useEditorPublish.ts

@@ -24,7 +24,7 @@ function blobToBase64(blob: Blob): Promise<string> {
  *  is preserved verbatim; non-JSON bodies (platform-level rejections) get a
  *  status-coded fallback — or a size hint when the request body itself was
  *  near Netlify's ~6MB limit (should be unreachable once saves are chunked). */
-async function postSave(payload: object): Promise<{ sha: string }> {
+async function postSave(payload: object): Promise<{ sha: string; warnings?: string[] }> {
   const body = JSON.stringify(payload);
   let response: Response;
   try {
@@ -47,9 +47,9 @@ async function postSave(payload: object): Promise<{ sha: string }> {
       : `Save failed (HTTP ${response.status})`;
     throw Object.assign(new Error(serverMessage || fallback), { status: response.status });
   }
-  const data = await response.json().catch(() => null) as { sha?: string } | null;
+  const data = await response.json().catch(() => null) as { sha?: string; warnings?: string[] } | null;
   if (!data?.sha) throw new Error("Save response missing SHA");
-  return data as { sha: string };
+  return data as { sha: string; warnings?: string[] };
 }
 
 interface PublishDeps {
@@ -98,6 +98,11 @@ interface PublishDeps {
    *  dies at the first save (discardSavedChanges clears it) and later 409
    *  recoveries would silently merge local-wins. */
   onBaselineCommitted?: (args: { sha: string; sections: LoadedSection[]; index: SiteIndex; savedIds: string[] }) => Promise<void>;
+  /** Injected by EditorShell. Receives non-fatal server warnings from a
+   *  successful save (e.g. the nav.json replacement was declined by the
+   *  degraded-nav guard) so the shell can surface them instead of the save
+   *  reading as fully landed. */
+  onSaveWarnings?: (warnings: string[]) => void;
   /** Test hook: overrides the per-request payload budget (default 4MB). */
   saveChunkBudget?: number;
   /** Injected by EditorShell. Mirrors this hook's in-flight-save state out to the
@@ -141,6 +146,7 @@ export function useEditorPublish({
   getBaseVersion,
   recoverConflict,
   onBaselineCommitted,
+  onSaveWarnings,
   saveChunkBudget,
   savingRef,
   getEditGeneration,
@@ -232,6 +238,7 @@ export function useEditorPublish({
     mediaManifest: MediaManifest;
     manifestDirty: boolean;
     saveChunkBudget?: number;
+    onSaveWarnings?: (warnings: string[]) => void;
   }): Promise<{
     sha: string;
     // sectionId+updatedAt for compare-and-clear cleanup, plus the SENT content —
@@ -337,6 +344,12 @@ export function useEditorPublish({
         } : {}),
       });
 
+      // Surface server-side warnings (e.g. the degraded-nav guard declining to
+      // replace nav.json) — the save succeeded, but part of it was refused, and
+      // the editor believing it landed is exactly the silence the guard exists
+      // to break.
+      if (responseData.warnings?.length) args.onSaveWarnings?.(responseData.warnings);
+
       return {
         sha: responseData.sha,
         savedSections: dirty.map(({ sectionId, updatedAt, content }) => ({ sectionId, updatedAt, content })),
@@ -401,6 +414,7 @@ export function useEditorPublish({
       // below sees recoverConflict's rebased manifest, not this render's copy.
       mediaManifest: mediaManifestRef?.current ?? mediaManifest,
       saveChunkBudget,
+      onSaveWarnings,
     });
   }
 

package/src/lib/block-move.ts

@@ -3,7 +3,16 @@ import type { Section } from "../schemas/sections";
 import type { SiteIndex, SectionMeta } from "../schemas/site-config";
 import { ROOT_CONTAINER_ID, canDropBlock } from "./block-dnd";
 import { getContainerChildren, reorderChild, insertChildAt, removeChildAt, placeBlockAtColumn, trimTrailingSpacers } from "./container-ops";
-import { reorderSectionInPage, addSectionToPage, removeSectionFromPages } from "./pages";
+import { reorderVisibleSectionInPage, visibleInsertPosition, addSectionToPage, removeSectionFromPages } from "./pages";
+
+/** The root list the canvas actually renders: page order filtered to loaded
+ *  bodies. Drag indices refer to THIS list, not to `page.order` — a section
+ *  whose body the loader dropped (unparseable file, schema miss) is invisible
+ *  but still holds its order slot. */
+function visibleRootIds(index: SiteIndex, rootPageId: string, sections: LoadedSection[]): string[] {
+  const bodyIds = new Set(sections.map((l) => l.section.id));
+  return index.pages.find((p) => p.id === rootPageId)?.order.filter((id) => bodyIds.has(id)) ?? [];
+}
 
 export interface BlockMoveState {
   sections: LoadedSection[];
@@ -84,11 +93,11 @@ export function applyBlockMove(
 
   if (fromContainerId === toContainerId) {
     // toIndex is the raw insertion index in the original (pre-removal) array.
-    // Both reorderSectionInPage and reorderChild use splice(from,1)+splice(to,0,moved),
+    // Both reorder paths use splice(from,1)+splice(to,0,moved),
     // so we must convert to the post-removal position for same-container moves.
     const adjusted = fromIndex < toIndex ? toIndex - 1 : toIndex;
     if (fromContainerId === ROOT_CONTAINER_ID) {
-      const nextIndex = reorderSectionInPage(index, rootPageId, fromIndex, adjusted);
+      const nextIndex = reorderVisibleSectionInPage(index, rootPageId, visibleRootIds(index, rootPageId, sections), fromIndex, adjusted);
       if (nextIndex === index) return noop(state);
       return {
         sections,
@@ -133,7 +142,9 @@ export function applyBlockMove(
   if (toContainerId === ROOT_CONTAINER_ID) {
     const { layout: _dropLayout, ...rootBlock } = moving as Section & { layout?: unknown };
     const meta = DEFAULT_CHILD_META(rootBlock.type);
-    nextIndex = addSectionToPage(nextIndex, rootPageId, rootBlock.id, meta, toIndex);
+    const rootOrder = nextIndex.pages.find((p) => p.id === rootPageId)?.order ?? [];
+    nextIndex = addSectionToPage(nextIndex, rootPageId, rootBlock.id, meta,
+      visibleInsertPosition(rootOrder, visibleRootIds(nextIndex, rootPageId, nextSections), toIndex));
     nextSections = [...nextSections, { section: rootBlock as Section, meta }];
     indexDirty = true;
     createSectionIds.push(rootBlock.id);

package/src/lib/dexie.ts

@@ -394,7 +394,12 @@ export async function persistAll(
           pages: siteIndex.pages,
           sections: siteIndex.sections,
           nav: siteIndex.nav,
-          deletedSections: [],
+          // 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[] }
@@ -102,8 +188,53 @@ export function opTouchedSectionIds(ops: IndexOp[]): string[] {
   return [...ids];
 }
 
+/**
+ * The ops that materialize and write the nav sidecar (the ones that set
+ * `navTouched` in applyIndexOps — keep the two in sync; the "nav sidecar
+ * preservation" test asserts they agree). Callers must refuse to apply these
+ * over a DEGRADED nav read: the tree they'd commit was built from only the
+ * entries that version could parse, so writing it destroys the rest.
+ * Section-level ops are absent by design — they emit no `nav` key at all.
+ */
+const NAV_TOUCHING_OPS = new Set<IndexOp["op"]>([
+  "addPage", "removePage", "addNavGroup", "removeNavGroup", "setNavGroupMeta", "movePageInNav",
+]);
+
+export function opsTouchNav(ops: IndexOp[]): boolean {
+  return ops.some((op) => NAV_TOUCHING_OPS.has(op.op));
+}
+
 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 +254,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 +399,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 +537,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 +567,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/loader.ts

@@ -3,7 +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";
+import { NavEntrySchema, type NavEntry } from "../schemas/nav";
 
 export interface LoadedSection {
   section: Section;
@@ -13,21 +13,41 @@ export interface LoadedSection {
 export interface SiteContent {
   sections: LoadedSection[];
   index: SiteIndex;
+  /** True when nav.json was present but held entries this package version could
+   *  not represent (unknown kinds, invalid shapes) — the returned nav is missing
+   *  them. Writers must treat a degraded nav as read-only: wholesale-replacing
+   *  nav.json from a degraded read permanently destroys the entries this
+   *  version dropped. */
+  navDegraded: boolean;
 }
 
 /**
- * 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.
+ * Parse the nav.json sidecar defensively, entry by entry. A malformed sidecar
+ * must degrade, 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. Tolerance is PER ENTRY: one unknown entry kind (a newer package version's
+ * addition, or an authoring typo) drops that entry alone, not every group on
+ * the site. Any drop is reported as `degraded` so write paths can refuse to
+ * persist the lossy tree back over the original.
  */
-function parseNavFile(navFile: unknown): NavEntry[] {
-  if (!navFile) return [];
-  const result = NavFileSchema.safeParse(navFile);
-  if (!result.success) {
+function parseNavFile(navFile: unknown): { entries: NavEntry[]; degraded: boolean } {
+  if (!navFile) return { entries: [], degraded: false };
+  const rawEntries = (navFile as { entries?: unknown }).entries;
+  if (!Array.isArray(rawEntries)) {
     console.warn("Invalid nav.json, falling back to a flat navigation");
-    return [];
+    return { entries: [], degraded: true };
   }
-  return result.data.entries;
+  const entries: NavEntry[] = [];
+  let dropped = 0;
+  for (const raw of rawEntries) {
+    const result = NavEntrySchema.safeParse(raw);
+    if (result.success) entries.push(result.data);
+    else dropped++;
+  }
+  if (dropped > 0) {
+    console.warn(`nav.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; navigation is degraded`);
+  }
+  return { entries, degraded: dropped > 0 };
 }
 
 /**
@@ -83,7 +103,8 @@ export function mergeSiteContent(
     }
   }
 
-  return { sections, index: { ...index, nav: parseNavFile(navFile) } };
+  const nav = parseNavFile(navFile);
+  return { sections, index: { ...index, nav: nav.entries }, navDegraded: nav.degraded };
 }
 
 /**

package/src/lib/pages.ts

@@ -203,6 +203,54 @@ export function reorderSectionInPage(
   return { ...index, pages };
 }
 
+/**
+ * Translate an insertion index expressed over the VISIBLE section list (what the
+ * editor renders: `page.order` filtered to loadable bodies) into a `page.order`
+ * position. The two disagree whenever a section body was dropped by the loader
+ * (unparseable file, schema miss, site-local type) — splicing a display index
+ * straight into `order` then moves the WRONG section. `displayIndex` may be
+ * `visibleIds.length` ("after the last visible entry"), which lands right after
+ * the last visible id so hidden trailing sections keep their place.
+ */
+export function visibleInsertPosition(order: string[], visibleIds: string[], displayIndex: number): number {
+  if (displayIndex < visibleIds.length) {
+    const pos = order.indexOf(visibleIds[displayIndex]);
+    if (pos >= 0) return pos;
+  }
+  const lastVisible = visibleIds[visibleIds.length - 1];
+  const lastPos = lastVisible !== undefined ? order.indexOf(lastVisible) : -1;
+  return lastPos >= 0 ? lastPos + 1 : order.length;
+}
+
+/**
+ * Reorder a section using DISPLAY indices over the visible list (same semantics
+ * as `reorderSectionInPage`: `toIndex` is the post-removal position). Resolves
+ * both endpoints to ids before touching `page.order`, so filtered-out sections
+ * can neither be moved by mistake nor shift the splice onto a different entry.
+ * Falls back to a no-op when the endpoints don't resolve.
+ */
+export function reorderVisibleSectionInPage(
+  index: SiteIndex,
+  pageId: string,
+  visibleIds: string[],
+  fromIndex: number,
+  toIndex: number,
+): SiteIndex {
+  const fromId = visibleIds[fromIndex];
+  if (fromId === undefined) return index;
+  const withoutFrom = visibleIds.filter((id) => id !== fromId);
+  const pages = index.pages.map((p) => {
+    if (p.id !== pageId) return p;
+    const fromPos = p.order.indexOf(fromId);
+    if (fromPos < 0) return p;
+    const order = [...p.order];
+    order.splice(fromPos, 1);
+    order.splice(visibleInsertPosition(order, withoutFrom, toIndex), 0, fromId);
+    return { ...p, order };
+  });
+  return { ...index, pages };
+}
+
 export function moveSection(
   index: SiteIndex,
   sectionId: string,

package/src/media/provider.ts

@@ -1,7 +1,6 @@
 import type { MediaManifest, MediaItem, ResolvedMedia } from "./types";
 
 export interface MediaProvider {
-  getManifest(): Promise<MediaManifest>;
   resolve(item: MediaItem, sizes: number[]): ResolvedMedia | null;
   exists(hash: string, manifest: MediaManifest): boolean;
 }

package/src/schemas/nav.ts

@@ -19,9 +19,9 @@ export const NavEntrySchema = z.discriminatedUnion("kind", [
     /** May be blank — agent-authored files can omit it; UI falls back to "Untitled group". */
     label: z.string().default(""),
     startCollapsed: z.boolean().default(false),
-    // Everything but `id` defaults: NavFileSchema is all-or-nothing, and the
-    // loader degrades a failed parse to a flat nav — so one agent-authored group
-    // missing a key would silently discard every group on the site.
+    // Everything but `id` defaults: the loader parses entries individually and
+    // drops the ones that fail — defaulting here keeps an agent-authored group
+    // missing a key from being dropped (and its drop marking the nav degraded).
     pageIds: z.array(z.string().min(1)).default([]),
   }),
 ]);

package/src/schemas/site-config.ts

@@ -53,7 +53,9 @@ export const PageSchema = z.object({
 
 export type Page = z.infer<typeof PageSchema>;
 
-const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// Exported so authoring surfaces (indexOps' addPage) can reject a bad slug with a
+// named error instead of letting it surface as an opaque index-parse failure.
+export const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 // Raw input: accepts legacy (order[]) OR canonical (pages[]).
 const RawIndexSchema = z.object({

package/src/storage/index.ts

@@ -1,2 +1,2 @@
 export type { StorageProvider, FileWrite, AssetStore } from "./types";
-export { StorageConflictError, ASSET_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";
+export { StorageConflictError, IdempotencyLookupUnavailableError, ASSET_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";