@drawnagency/primitives 0.1.95 → 0.1.97

package/src/lib/nav-tree.ts

@@ -0,0 +1,192 @@
+import type { NavEntry, NavGroupEntry } from "../schemas/nav";
+import type { Page, SiteIndex } from "../schemas/site-config";
+
+/**
+ * Repair an authored nav against the current page set.
+ *
+ * Total, pure, and idempotent: every possible input maps to a valid nav in
+ * which each page appears exactly once. This is what lets the sidecar tolerate
+ * an older writer editing index.json without knowing about nav.json — the worst
+ * case is a page drifting to the bottom of the nav, never a hard failure. It is
+ * deliberately NOT a schema refinement: parse-rejecting content leaves viewer
+ * and editor both refusing to load, with no in-product repair path.
+ *
+ * "Total" is meant literally, so the shape guards below are load-bearing rather
+ * than paranoia: callers include agent-authored JSON and live editor state, and
+ * `pages` is not id-unique (IndexSchema checks slug uniqueness, not page ids).
+ * Every entry is cloned on the way out — the editor holds this in React state,
+ * where a returned-by-reference entry would let a later mutation silently edit
+ * prior state and defeat identity-based re-render checks.
+ */
+export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
+  const entryList = Array.isArray(entries) ? entries : [];
+  const pageList = Array.isArray(pages) ? pages : [];
+
+  const validIds = new Set<string>();
+  for (const p of pageList) {
+    if (p?.id) validIds.add(p.id);
+  }
+
+  const placed = new Set<string>();
+  const seenGroupIds = new Set<string>();
+  const result: NavEntry[] = [];
+
+  for (const entry of entryList) {
+    if (entry?.kind === "page") {
+      if (!validIds.has(entry.pageId) || placed.has(entry.pageId)) continue;
+      placed.add(entry.pageId);
+      result.push({ ...entry });
+      continue;
+    }
+
+    if (entry?.kind !== "group") continue;
+    if (seenGroupIds.has(entry.id)) continue;
+    seenGroupIds.add(entry.id);
+
+    const claimed = Array.isArray(entry.pageIds) ? entry.pageIds : [];
+    const pageIds = claimed.filter((id) => {
+      if (!validIds.has(id) || placed.has(id)) return false;
+      placed.add(id);
+      return true;
+    });
+    const group: NavGroupEntry = { ...entry, pageIds };
+    result.push(group);
+  }
+
+  for (const p of pageList) {
+    if (!p?.id || placed.has(p.id)) continue;
+    placed.add(p.id);
+    result.push({ kind: "page", pageId: p.id });
+  }
+
+  return result;
+}
+
+/**
+ * The ONLY sanctioned way to read the nav. Always reconciles, so callers never
+ * have to reason about whether index.nav is present, stale, or authored by an
+ * older writer. Cheap and idempotent — call it freely.
+ */
+export function navEntries(index: SiteIndex): NavEntry[] {
+  return reconcileNav(index.nav ?? [], index.pages);
+}
+
+/** Pages in authored nav order. Use this anywhere user-visible sequence matters. */
+export function pagesInNavOrder(index: SiteIndex): Page[] {
+  const byId = new Map(index.pages.map((p) => [p.id, p]));
+  const out: Page[] = [];
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "page") {
+      const p = byId.get(entry.pageId);
+      if (p) out.push(p);
+    } else {
+      for (const id of entry.pageIds) {
+        const p = byId.get(id);
+        if (p) out.push(p);
+      }
+    }
+  }
+  return out;
+}
+
+export function groupOfPage(index: SiteIndex, pageId: string): NavGroupEntry | null {
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "group" && entry.pageIds.includes(pageId)) return entry;
+  }
+  return null;
+}
+
+/** Display fallback for blank group labels — mirrors pageDisplayTitle in lib/pages.ts. */
+export function groupDisplayLabel(label: string): string {
+  return label || "Untitled group";
+}
+
+/** A position in the nav: inside a group, or at the top level when groupId is null. */
+export interface NavLocation {
+  groupId: string | null;
+  index: number;
+}
+
+export type NavRow =
+  | { kind: "page"; pageId: string; groupId: string | null; index: number }
+  | { kind: "group"; groupId: string; index: number }
+  | { kind: "empty-group"; groupId: string }
+  // The trailing drop target. Without it a page can never land AFTER a group
+  // that sits last in the nav: the group's header-bottom edge and every member
+  // edge all resolve to positions INSIDE it.
+  | { kind: "tail" };
+
+function withNav(index: SiteIndex, entries: NavEntry[]): SiteIndex {
+  return { ...index, nav: entries };
+}
+
+export function addGroup(index: SiteIndex, groupId: string): SiteIndex {
+  return withNav(index, [
+    ...navEntries(index),
+    { kind: "group", id: groupId, label: "", startCollapsed: false, pageIds: [] },
+  ]);
+}
+
+export function renameGroup(index: SiteIndex, groupId: string, label: string): SiteIndex {
+  return withNav(index, navEntries(index).map((e) =>
+    e.kind === "group" && e.id === groupId ? { ...e, label } : e,
+  ));
+}
+
+export function setGroupStartCollapsed(index: SiteIndex, groupId: string, startCollapsed: boolean): SiteIndex {
+  return withNav(index, navEntries(index).map((e) =>
+    e.kind === "group" && e.id === groupId ? { ...e, startCollapsed } : e,
+  ));
+}
+
+/** Removes the group; its members become top-level entries at the group's slot. */
+export function deleteGroup(index: SiteIndex, groupId: string): SiteIndex {
+  const out: NavEntry[] = [];
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "group" && entry.id === groupId) {
+      for (const pageId of entry.pageIds) out.push({ kind: "page", pageId });
+    } else {
+      out.push(entry);
+    }
+  }
+  return withNav(index, out);
+}
+
+/**
+ * The single reorder+reparent primitive. `from` and `to` are both NavLocations,
+ * so moving within a container, between containers, and promoting/demoting a
+ * page are all the same operation.
+ */
+export function moveNavEntry(index: SiteIndex, from: NavLocation, to: NavLocation): SiteIndex {
+  const entries = navEntries(index).map((e) => (e.kind === "group" ? { ...e, pageIds: [...e.pageIds] } : { ...e }));
+
+  // Lift the moved item out of its source container.
+  let moved: NavEntry | string | undefined;
+  if (from.groupId === null) {
+    if (from.index < 0 || from.index >= entries.length) return index;
+    [moved] = entries.splice(from.index, 1);
+  } else {
+    const group = entries.find((e) => e.kind === "group" && e.id === from.groupId);
+    if (!group || group.kind !== "group") return index;
+    if (from.index < 0 || from.index >= group.pageIds.length) return index;
+    [moved] = group.pageIds.splice(from.index, 1);
+  }
+  if (moved === undefined) return index;
+
+  // A group can only ever live at the top level — one level of nesting, enforced.
+  const movedIsGroup = typeof moved !== "string" && moved.kind === "group";
+  if (movedIsGroup && to.groupId !== null) return index;
+
+  if (to.groupId === null) {
+    const entry: NavEntry = typeof moved === "string" ? { kind: "page", pageId: moved } : moved;
+    entries.splice(Math.max(0, Math.min(to.index, entries.length)), 0, entry);
+  } else {
+    const group = entries.find((e) => e.kind === "group" && e.id === to.groupId);
+    if (!group || group.kind !== "group") return index;
+    const pageId = typeof moved === "string" ? moved : moved.kind === "page" ? moved.pageId : null;
+    if (pageId === null) return index;
+    group.pageIds.splice(Math.max(0, Math.min(to.index, group.pageIds.length)), 0, pageId);
+  }
+
+  return withNav(index, entries);
+}

package/src/lib/nav.ts

@@ -1,6 +1,7 @@
 import type { LoadedSection } from "./loader";
 import { getSection, type SectionRegistry } from "./registry";
 import { audiencePasses, homePage, pageDisplayTitle } from "./pages";
+import { navEntries } from "./nav-tree";
 import type { SiteIndex } from "../schemas/site-config";
 
 export interface NavItem {
@@ -93,9 +94,20 @@ export interface PageNavItem {
   headings: NavItem[];
 }
 
-export interface SiteNav {
+export interface GroupNavItem {
+  kind: "group";
+  id: string;
+  label: string;
+  startCollapsed: boolean;
   pages: PageNavItem[];
-  /** Live pages with showInNav off — editor-only group, like the archive. */
+}
+
+export type SiteNavEntry = ({ kind: "page" } & PageNavItem) | GroupNavItem;
+
+export interface SiteNav {
+  /** The authored tree: loose pages and groups, in nav order. */
+  entries: SiteNavEntry[];
+  /** Live pages with showInNav off — editor-only flat bucket, like the archive. */
   hidden: PageNavItem[];
   archive: PageNavItem[];
 }
@@ -114,6 +126,7 @@ export function generateSiteNav(opts: {
 }): SiteNav {
   const { index, activeSections, activePageId, mode, audience, registry } = opts;
   const active = activePageId ?? homePage(index).id;
+  const byId = new Map(index.pages.map((p) => [p.id, p]));
 
   const toNavItem = (p: (typeof index.pages)[number]): PageNavItem => ({
     id: p.id,
@@ -124,19 +137,39 @@ export function generateSiteNav(opts: {
     headings: p.id === active ? generateNavLinks(activeSections, registry) : [],
   });
 
+  // Tree membership: live + shown in nav, and for viewers also audience-passing.
+  // Hidden and archived pages keep their nav slot in the data but render in the
+  // flat editor buckets instead, so a group never appears in two places.
+  const inTree = (p: (typeof index.pages)[number]) =>
+    p.status === "live" && p.showInNav && (mode === "editor" || audiencePasses(p.access, audience));
+
+  const entries: SiteNavEntry[] = [];
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "page") {
+      const p = byId.get(entry.pageId);
+      if (p && inTree(p)) entries.push({ kind: "page", ...toNavItem(p) });
+      continue;
+    }
+    const pages = entry.pageIds
+      .map((id) => byId.get(id))
+      .filter((p): p is NonNullable<typeof p> => !!p && inTree(p))
+      .map(toNavItem);
+    // A group with nothing visible is noise for viewers; editors keep it so an
+    // empty group they just created doesn't disappear out from under them.
+    if (pages.length === 0 && mode === "viewer") continue;
+    entries.push({
+      kind: "group", id: entry.id, label: entry.label,
+      startCollapsed: entry.startCollapsed, pages,
+    });
+  }
+
   if (mode === "editor") {
     return {
-      pages: index.pages.filter((p) => p.status === "live" && p.showInNav).map(toNavItem),
+      entries,
       hidden: index.pages.filter((p) => p.status === "live" && !p.showInNav).map(toNavItem),
       archive: index.pages.filter((p) => p.status === "archived").map(toNavItem),
     };
   }
 
-  return {
-    pages: index.pages
-      .filter((p) => p.status === "live" && p.showInNav && audiencePasses(p.access, audience))
-      .map(toNavItem),
-    hidden: [],
-    archive: [],
-  };
+  return { entries, hidden: [], archive: [] };
 }

package/src/lib/pages.ts

@@ -4,6 +4,7 @@ import { RESERVED_SLUGS } from "../schemas/site-config";
 // is allowed to reach into its engine to write the page-level document options
 // block (mirrors the same sanctioned import in schemas/site-config.ts).
 import { documentOptionsSchema, type DocumentOptions } from "../document/engine/settings";
+import { navEntries } from "./nav-tree";
 
 /**
  * Display fallback for blank page titles. addPage creates pages with an empty
@@ -59,16 +60,11 @@ export function addPage(index: SiteIndex, id: string): SiteIndex {
   const page: Page = {
     id, title: "", slug, isHome: false, showInNav: true, status: "live", access: [], order: [],
   };
-  return { ...index, pages: [...index.pages, page] };
-}
-
-export function reorderPages(index: SiteIndex, fromIndex: number, toIndex: number): SiteIndex {
-  const len = index.pages.length;
-  if (fromIndex < 0 || fromIndex >= len || toIndex < 0 || toIndex >= len) return index;
-  const pages = [...index.pages];
-  const [moved] = pages.splice(fromIndex, 1);
-  pages.splice(toIndex, 0, moved);
-  return { ...index, pages };
+  return {
+    ...index,
+    pages: [...index.pages, page],
+    nav: [...navEntries(index), { kind: "page", pageId: id }],
+  };
 }
 
 export function setHomePage(index: SiteIndex, pageId: string): SiteIndex {
@@ -152,7 +148,14 @@ export function deletePage(
   const nextSections: Record<string, SectionMeta> = { ...index.sections };
   for (const id of removedSectionIds) delete nextSections[id];
   return {
-    index: { ...index, pages: index.pages.filter((p) => p.id !== pageId), sections: nextSections },
+    index: {
+      ...index,
+      pages: index.pages.filter((p) => p.id !== pageId),
+      sections: nextSections,
+      nav: navEntries(index)
+        .filter((e) => !(e.kind === "page" && e.pageId === pageId))
+        .map((e) => (e.kind === "group" ? { ...e, pageIds: e.pageIds.filter((id) => id !== pageId) } : e)),
+    },
     removedSectionIds,
   };
 }

package/src/lib/reorder.ts

@@ -1,3 +1,5 @@
+import type { NavLocation, NavRow } from "./nav-tree";
+
 /**
  * Compute the destination index for a closest-edge drag-to-reorder drop.
  *
@@ -18,3 +20,57 @@ export function computeReorderTarget(
   if (fromIndex < toIndex) toIndex--;
   return fromIndex === toIndex ? null : toIndex;
 }
+
+/**
+ * Resolve a closest-edge drop over a nav row into a destination NavLocation.
+ *
+ * With one level of nesting a target's own identity determines its container,
+ * so page drags need no depth inference. Group drags DO need remapping: a group
+ * can only live at the top level, so hovering a member row is reinterpreted as
+ * "next to that member's group" rather than rejected — otherwise every member
+ * row of every expanded group is an inert dead zone during a group drag.
+ *
+ * `overEntryIndex` is the row's index in the TOP-LEVEL entry list: its own index
+ * for a top-level page or group row, its enclosing group's index for a member
+ * row, and the total entry count for the tail row. Group-drag remapping targets
+ * it directly.
+ *
+ * Returns null when the drop would not move anything, or is not permitted.
+ */
+export function computeNavDropTarget(args: {
+  from: NavLocation;
+  fromKind: "page" | "group";
+  over: NavRow;
+  overEntryIndex: number;
+  edge: "top" | "bottom" | null;
+}): NavLocation | null {
+  const { from, fromKind, over, overEntryIndex, edge } = args;
+  const after = edge === "bottom";
+
+  let to: NavLocation;
+  if (over.kind === "tail") {
+    // A container-level target for both kinds. `overEntryIndex` for the tail row
+    // is the top-level entry count, so this appends. The shared decrement below
+    // makes "drag the last top-level row onto the tail" a correct no-op.
+    to = { groupId: null, index: overEntryIndex };
+  } else if (fromKind === "group") {
+    // Groups are top-level only. Empty-group rows have no top-level meaning here.
+    if (over.kind === "empty-group") return null;
+    to = { groupId: null, index: overEntryIndex + (after ? 1 : 0) };
+  } else if (over.kind === "empty-group") {
+    to = { groupId: over.groupId, index: 0 };
+  } else if (over.kind === "group") {
+    // Top edge = before the group at the top level; bottom edge = first slot
+    // INSIDE it. The header's lower boundary is visually the group's interior.
+    to = after ? { groupId: over.groupId, index: 0 } : { groupId: null, index: overEntryIndex };
+  } else {
+    to = { groupId: over.groupId, index: over.index + (after ? 1 : 0) };
+  }
+
+  // Removing the dragged item before re-inserting shifts later slots in the
+  // SAME container only — mirrors computeReorderTarget's decrement.
+  if (to.groupId === from.groupId && from.index < to.index) to = { ...to, index: to.index - 1 };
+
+  if (to.groupId === from.groupId && to.index === from.index) return null;
+  return to;
+}

package/src/schemas/index.ts

@@ -1,6 +1,7 @@
 export * from "./shared";
 export * from "./sections";
 export * from "./site-config";
+export * from "./nav";
 export * from "./media";
 export * from "./audience";
 export * from "./media-grid-options";

package/src/schemas/nav.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+/**
+ * The site's authored navigation tree, persisted to `src/content/nav.json`.
+ *
+ * Deliberately NOT a key on index.json: `applyContentWrite` re-serializes the
+ * Zod-parsed index, so any writer running a package version that predates a new
+ * index key silently deletes it from disk. A sidecar is absent from an old
+ * writer's file list and survives untouched.
+ */
+export const NavEntrySchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("page"),
+    pageId: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("group"),
+    id: z.string().min(1),
+    /** 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.
+    pageIds: z.array(z.string().min(1)).default([]),
+  }),
+]);
+
+export const NavFileSchema = z.object({
+  entries: z.array(NavEntrySchema),
+});
+
+export type NavEntry = z.infer<typeof NavEntrySchema>;
+export type NavPageEntry = Extract<NavEntry, { kind: "page" }>;
+export type NavGroupEntry = Extract<NavEntry, { kind: "group" }>;
+export type NavFile = z.infer<typeof NavFileSchema>;

package/src/schemas/site-config.ts

@@ -6,6 +6,7 @@ import { CORNER_RADIUS_OPTIONS } from "../lib/corner-radius";
 // site-config.ts is allowed to reach into its engine to wire the page-level
 // document options block onto PageSchema.
 import { documentOptionsSchema } from "../document/engine/settings";
+import type { NavEntry } from "./nav";
 
 export const StatusSchema = z.enum(["draft", "live", "archived", "published"]).transform(
   (val) => val === "published" ? "live" as const : val,
@@ -167,7 +168,14 @@ const CanonicalIndexSchema = z
 
 export const IndexSchema = RawIndexSchema.transform(normalizeRawIndex).pipe(CanonicalIndexSchema);
 
-export type SiteIndex = z.infer<typeof CanonicalIndexSchema>;
+/**
+ * `nav` is a RUNTIME field only: it is loaded from the src/content/nav.json
+ * sidecar and attached by the loader, never parsed from or written to
+ * index.json. It is optional because most SiteIndex values (tests, legacy
+ * content, partial writes) have no nav — reads go through navEntries(), which
+ * reconciles a missing nav into a flat one.
+ */
+export type SiteIndex = z.infer<typeof CanonicalIndexSchema> & { nav?: NavEntry[] };
 
 /** Parse + normalize any raw index (legacy or canonical) to the canonical shape. */
 export function normalizeSiteIndex(raw: unknown): SiteIndex {

package/src/storage/index.ts

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

package/src/storage/types.ts

@@ -31,6 +31,61 @@ export interface StorageProvider {
   getVersion(): Promise<string>;
 
   listDirectory(path: string, options?: { draft?: boolean }): Promise<string[]>;
+
+  /**
+   * Find a recent commit on the draft branch whose message carries the given
+   * `Idempotency-Key:` trailer, returning its sha (null if not found).
+   *
+   * This exists to make a retried write LEGIBLE, not to make it safe — safety is
+   * already `writeFiles`' baseVersion check, which a retry cannot get past once
+   * the original landed (the head moved, so the retry's baseVersion is stale).
+   * What the check cannot do is tell "your write failed" from "your write
+   * succeeded and you didn't hear back", and it reports both as a conflict. A
+   * caller that tagged its write can ask that question here.
+   *
+   * OPTIONAL: providers that cannot search history omit it, and callers fall
+   * back to surfacing the plain conflict.
+   *
+   * Best-effort by contract. It searches a BOUNDED window, so an old key reads
+   * as absent, and an implementation may answer "not found" when the history
+   * read itself fails — failing closed keeps the conflict rather than inventing
+   * a replay. So `null` means "could not confirm", NOT "your write did not
+   * land": a caller must not tell the user the earlier attempt failed.
+   */
+  findCommitByIdempotencyKey?(
+    key: string,
+    options?: { limit?: number },
+  ): Promise<string | null>;
+}
+
+/**
+ * Commit-message trailer carrying a write's idempotency key. The commit itself is
+ * the store — no table, and no TTL to tune: keys live exactly as long as the
+ * draft branch, and `promoteDraft` deletes it, which is the correct lifetime
+ * (after a publish there is no draft, so an old write must not replay).
+ */
+export const IDEMPOTENCY_TRAILER = "Idempotency-Key";
+
+/**
+ * Keys are interpolated into a commit message, so the charset is enforced HERE,
+ * at the interpolation point, and not only by the caller that happens to have a
+ * schema. A key containing a newline would let a caller append arbitrary further
+ * trailer lines to the commit.
+ */
+export const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:-]{8,200}$/;
+
+/**
+ * Build a commit message carrying `key` as a trailer, or return `subject`
+ * unchanged when no key is given. Throws on a malformed key: every caller
+ * reaches this through a write path that should have validated first, so an
+ * invalid key here is a bug, not user input to be tolerated.
+ */
+export function withIdempotencyTrailer(subject: string, key?: string): string {
+  if (!key) return subject;
+  if (!IDEMPOTENCY_KEY_RE.test(key)) {
+    throw new Error("Invalid idempotency key: expected 8-200 chars of A-Za-z0-9._:-");
+  }
+  return `${subject}\n\n${IDEMPOTENCY_TRAILER}: ${key}`;
 }
 
 export type FileWrite = {

package/dist/chunk-VAOW4WXQ.js

@@ -1,15 +0,0 @@
-// src/storage/types.ts
-var StorageConflictError = class extends Error {
-  constructor(currentVersion) {
-    super("Draft has been modified since it was loaded");
-    this.currentVersion = currentVersion;
-    this.name = "StorageConflictError";
-  }
-  currentVersion;
-};
-var ASSET_CACHE_CONTROL = "max-age=31536000, immutable";
-
-export {
-  StorageConflictError,
-  ASSET_CACHE_CONTROL
-};

package/dist/chunk-YBVK254P.js

@@ -1,14 +0,0 @@
-// src/lib/pages.ts
-function slugifyPageSlug(input) {
-  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-}
-function audiencePasses(access, audience) {
-  if (access.length === 0) return true;
-  if (!audience) return true;
-  return access.includes(audience);
-}
-
-export {
-  slugifyPageSlug,
-  audiencePasses
-};