@drawnagency/primitives 0.1.98 → 0.1.100

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

@@ -4,6 +4,7 @@ import type { SiteIndex, SectionMeta, SiteConfig, Page } from "../schemas/site-c
 import type { NavEntry } from "../schemas/nav";
 import type { LoadedSection } from "./loader";
 import type { MediaManifest, MediaItem } from "../media/types";
+import type { DocumentManifestEntry } from "../schemas/documents";
 
 interface SectionRow {
   sectionId: string;
@@ -70,6 +71,17 @@ interface PendingMediaDeletionRow {
   deletedAt: string;
 }
 
+/** A document staged locally and not yet committed. Git-tier rows carry the
+ *  bytes (they ride /api/save); bucket-tier rows are manifest-only — their
+ *  object is already in the private docs bucket. */
+interface PendingDocumentRow {
+  id: string;
+  entry: DocumentManifestEntry;
+  blob: Blob | null;
+  localUrl: string;
+  updatedAt: string;
+}
+
 export interface PreservedEditRow {
   id: string;
   sectionId: string;
@@ -88,6 +100,7 @@ class EditorDatabase extends Dexie {
   pendingMedia!: Dexie.Table<PendingMediaRow, string>;
   pendingMediaDeletions!: Dexie.Table<PendingMediaDeletionRow, string>;
   preservedEdits!: Dexie.Table<PreservedEditRow, string>;
+  pendingDocuments!: Dexie.Table<PendingDocumentRow, string>;
 
   constructor(siteId: string) {
     super(`brand-portal-${siteId}`);
@@ -190,6 +203,21 @@ class EditorDatabase extends Dexie {
       pendingMediaDeletions: "id",
       preservedEdits: "id, sectionId",
     });
+    // v10: pendingDocuments — locally staged document uploads. Additive store
+    // only; every existing table declaration is carried forward unchanged so
+    // no data is dropped on upgrade.
+    this.version(10).stores({
+      sections: "sectionId",
+      siteIndex: "key",
+      meta: "key",
+      siteConfig: "key",
+      contentCache: "key",
+      mediaManifest: "key",
+      pendingMedia: "id",
+      pendingMediaDeletions: "id",
+      preservedEdits: "id, sectionId",
+      pendingDocuments: "id",
+    });
   }
 }
 
@@ -593,3 +621,29 @@ export async function listPreservedEdits(): Promise<PreservedEditRow[]> {
 export async function removePreservedEdit(id: string): Promise<void> {
   await getDb().preservedEdits.delete(id);
 }
+
+export interface PendingDocumentRecord {
+  id: string;
+  entry: DocumentManifestEntry;
+  blob: Blob | null;
+  localUrl: string;
+}
+
+export async function addPendingDocument(record: PendingDocumentRecord): Promise<void> {
+  await getDb().pendingDocuments.put({ ...record, updatedAt: new Date().toISOString() });
+}
+
+export async function getPendingDocuments(): Promise<PendingDocumentRecord[]> {
+  const rows = await getDb().pendingDocuments.toArray();
+  return rows.map(({ id, entry, blob, localUrl }) => ({ id, entry, blob, localUrl }));
+}
+
+export async function getPendingDocumentBlob(id: string): Promise<Blob | null> {
+  const row = await getDb().pendingDocuments.get(id);
+  return row?.blob ?? null;
+}
+
+export async function clearPendingDocumentsByIds(ids: string[]): Promise<void> {
+  if (ids.length === 0) return;
+  await getDb().pendingDocuments.bulkDelete(ids);
+}

package/src/lib/document-refs.ts

@@ -0,0 +1,83 @@
+import type { Section } from "../schemas/sections";
+import { getContainerChildren } from "./container-ops";
+
+/**
+ * Structural walkers over section content for `document` references, the
+ * counterpart to `image-refs` for the document manifest: `tallyDocumentIds`
+ * feeds the media modal's usage pills, `clearDocumentRefs` repairs sections
+ * that pointed at a deleted document.
+ *
+ * Two differences from `image-refs`. The reference is identified by NODE TYPE
+ * (`type === "document"`, then `content.doc.documentId`) rather than by key
+ * name, so an unrelated field that happens to be called `doc` is never touched.
+ * And the walk recurses through container children structurally, deliberately
+ * without a depth cap: `MAX_BLOCK_DEPTH` currently makes depth 1 the only
+ * reachable nesting, but a counter that miscounts if that rule changes would
+ * silently under-report usage and leave dangling references behind.
+ */
+
+interface DocumentSectionContent {
+  doc?: { documentId?: string };
+}
+
+/** The non-empty `documentId` this node references, or "" if it references none. */
+function documentIdOf(section: Section): string {
+  if (section.type !== "document") return "";
+  return (section.content as DocumentSectionContent).doc?.documentId ?? "";
+}
+
+/**
+ * Count every non-empty `documentId` referenced by `value` — a section, or an
+ * array of them — including sections nested inside containers. Accepts a
+ * caller-supplied accumulator so a list of `LoadedSection`s can be tallied one
+ * `.section` at a time into a single map.
+ */
+export function tallyDocumentIds(
+  value: Section | readonly Section[],
+  counts: Map<string, number> = new Map(),
+): Map<string, number> {
+  if (Array.isArray(value)) {
+    for (const item of value) tallyDocumentIds(item, counts);
+    return counts;
+  }
+  const section = value as Section;
+  const documentId = documentIdOf(section);
+  if (documentId) counts.set(documentId, (counts.get(documentId) ?? 0) + 1);
+  for (const child of getContainerChildren(section)) tallyDocumentIds(child, counts);
+  return counts;
+}
+
+/**
+ * Blank every `doc.documentId` in `ids` to "" (the deleted-media repair pass).
+ *
+ * Returns `changed: false` and the ORIGINAL section reference when nothing
+ * matched, so callers can skip a re-render and a dirty mark. A match on a
+ * nested child returns a rewritten CONTAINER — the container is the section
+ * that owns the child's bytes, so it is what gets dirtied and saved; untouched
+ * siblings are carried over by reference.
+ */
+export function clearDocumentRefs(
+  section: Section,
+  ids: Set<string>,
+): { changed: boolean; section: Section } {
+  const documentId = documentIdOf(section);
+  if (documentId && ids.has(documentId)) {
+    const content = section.content as DocumentSectionContent;
+    return {
+      changed: true,
+      section: { ...section, content: { ...section.content, doc: { ...content.doc, documentId: "" } } },
+    };
+  }
+
+  const children = getContainerChildren(section);
+  if (children.length === 0) return { changed: false, section };
+
+  let changed = false;
+  const next = children.map((child) => {
+    const result = clearDocumentRefs(child, ids);
+    if (result.changed) changed = true;
+    return result.section;
+  });
+  if (!changed) return { changed: false, section };
+  return { changed: true, section: { ...section, content: { ...section.content, children: next } } };
+}

package/src/lib/document-uploads.ts

@@ -0,0 +1,66 @@
+import {
+  DOCUMENT_BUCKET_MAX_BYTES,
+  DOCUMENT_GIT_MAX_BYTES,
+  DOCUMENT_MIME_TO_EXT,
+  documentGitPath as documentGitPathFromSlug,
+  documentBucketPath,
+} from "../schemas/documents";
+import { sanitizeMediaName } from "../media/utils";
+
+// Bucket keys are already spelled once, in schemas/documents (S1) — re-exported
+// so this module is the single import site for the whole upload flow.
+export { documentBucketPath };
+
+/** Every way a document upload can be refused. The first three are decidable
+ *  client-side; `no_documents_store` only comes back from the upload-intent
+ *  endpoint (the browser cannot see whether a docs bucket is configured). */
+export type DocumentRejectionReason =
+  | "unsupported_type"
+  | "too_large"
+  | "too_small"
+  | "no_documents_store";
+
+export type DocumentUploadPlan =
+  | { tier: "git"; kind: "pdf" | "html"; ext: "pdf" | "html" }
+  | { tier: "bucket"; kind: "pdf" | "html"; ext: "pdf" | "html" }
+  | { tier: "rejected"; reason: DocumentRejectionReason };
+
+/** Pure tier routing. The bucket tier's lower bound is exactly the git cap, so
+ *  there is no size that falls through both. */
+export function planDocumentUpload(file: { name: string; size: number; type: string }): DocumentUploadPlan {
+  // `file.type` is an arbitrary string, so the const map is widened for the
+  // lookup rather than indexed with a cast that TS would reject.
+  const ext = (DOCUMENT_MIME_TO_EXT as Record<string, "pdf" | "html" | undefined>)[file.type];
+  if (!ext) return { tier: "rejected", reason: "unsupported_type" };
+  if (file.size <= 0) return { tier: "rejected", reason: "too_small" };
+  if (file.size > DOCUMENT_BUCKET_MAX_BYTES) return { tier: "rejected", reason: "too_large" };
+  if (file.size <= DOCUMENT_GIT_MAX_BYTES) return { tier: "git", kind: ext, ext };
+  return { tier: "bucket", kind: ext, ext };
+}
+
+/** Human copy for every rejection code, client- or server-originated. Never
+ *  falls back to the media pipeline's generic size copy (an oversized PDF
+ *  today gets "…is larger than the NMB media limit.", which names the wrong
+ *  limit and no fix). */
+export function documentRejectionMessage(reason: DocumentRejectionReason, filename: string): string {
+  switch (reason) {
+    case "unsupported_type":
+      return `"${filename}" — only PDF and HTML documents can be uploaded.`;
+    case "too_large":
+      return `"${filename}" is larger than the 200MB document limit.`;
+    case "too_small":
+      return `"${filename}" is empty.`;
+    case "no_documents_store":
+      return `"${filename}" is over 2.5MB, and document storage isn't set up on this site yet.`;
+  }
+}
+
+/**
+ * Repo path for a git-tier document, from the RAW file name. The layout itself
+ * lives once in schemas/documents (S1), which takes an already-sanitized stem;
+ * this wrapper only adds `sanitizeMediaName`, so the two can never drift. The
+ * extension comes from the explicit pdf/html map — never mimeToExt's "bin".
+ */
+export function documentGitPath(originalName: string, hash: string, ext: "pdf" | "html"): string {
+  return documentGitPathFromSlug(sanitizeMediaName(originalName), hash, ext);
+}

package/src/lib/documents.ts

@@ -0,0 +1,138 @@
+import type { LoadedSection } from "./loader";
+import type { Section } from "../schemas/sections";
+import type { SiteIndex, SectionMeta } from "../schemas/site-config";
+import type { DocumentManifest } from "../schemas/documents";
+import { documentFileUrl } from "../schemas/documents";
+import { getContainerChildren } from "./container-ops";
+import { audiencePasses } from "./pages";
+
+// The gated URL has exactly ONE definition, in schemas/documents (S1). This is
+// a re-export so `@/lib/documents` consumers get it without a second spelling.
+export { documentFileUrl };
+
+/**
+ * One `document` section, joined against the document manifest and filtered to
+ * what THIS requester may see. Derived per request — never persisted, never
+ * written back into index.json or nav.json.
+ */
+export interface SiteDocument {
+  sectionId: string;
+  /** Manifest key. Carried so the overlay can build the ?download=1 URL with
+   *  documentFileUrl(), and so the editor can key a staged blob URL by id. */
+  documentId: string;
+  title: string;
+  filename: string;
+  size: number;
+  kind: "pdf" | "html";
+  /** The auth-gated route. Append `?download=1` for an attachment response. */
+  url: string;
+  /** Mirrors content.showInDocumentsNav — generateSiteNav filters on it, while
+   *  the overlay and the rows need the unfiltered list (an unflagged document
+   *  is still openable from its own row). */
+  showInDocumentsNav: boolean;
+}
+
+interface DocumentSectionContent {
+  title?: string;
+  doc?: { documentId?: string };
+  showInDocumentsNav?: boolean;
+}
+
+/**
+ * Filename without its extension. The document row and the overlay's top bar
+ * render `content.title || filenameStem(entry.filename)` — a DISPLAY fallback,
+ * not a write. (SettingsForm.handleFieldChange is per-key and cannot set a
+ * sibling field, so "auto-fill title on pick" would need cross-field machinery
+ * for the same visible result.)
+ */
+export function filenameStem(filename: string): string {
+  const dot = filename.lastIndexOf(".");
+  return dot > 0 ? filename.slice(0, dot) : filename;
+}
+
+/** Compact byte size for the row's `filename · size` line. */
+export function formatDocSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value >= 100 ? Math.round(value) : Number(value.toFixed(1))} ${units[unit]}`;
+}
+
+/**
+ * Every document the requester may see, in page order.
+ *
+ * Viewer mode mirrors viewer-page.ts exactly: the owning page must be live and
+ * audience-passing, AND the section's own meta must be live and audience-
+ * passing. Editors see everything on the draft. A document with no manifest
+ * entry is excluded in BOTH modes — there are no bytes to serve and no
+ * filename/size to render; the editor's row derives its "file missing" state
+ * from that absence.
+ *
+ * Documents nested one level inside a container count too, and are emitted right
+ * after their container's own position. A child has no meta of its own and never
+ * appears in `page.order`, so both gates read the PARENT's meta and the PARENT's
+ * page; the emitted `sectionId` is the CHILD's — that is what `DocumentRow`
+ * matches and what `#doc=` deep links carry. Depth 1 only: `MAX_BLOCK_DEPTH`
+ * makes anything deeper unrepresentable on write and on load.
+ *
+ * This is one half of a documented mirror. `referencedByVisibleSection` (the
+ * gated file route) applies the same gates with the same recursion — change one,
+ * change the other, or a document becomes listable but unservable (or worse).
+ */
+export function deriveSiteDocuments(opts: {
+  index: SiteIndex;
+  sections: LoadedSection[];
+  manifest: DocumentManifest;
+  mode: "viewer" | "editor";
+  audience: string | null;
+}): SiteDocument[] {
+  const { index, sections, manifest, mode, audience } = opts;
+
+  const pageBySectionId = new Map<string, SiteIndex["pages"][number]>();
+  for (const page of index.pages) for (const id of page.order) pageBySectionId.set(id, page);
+
+  const out: SiteDocument[] = [];
+  const seen = new Set<string>();
+
+  /** `candidate` supplies the id and the body; `owner` (itself, or the container
+   *  it sits in) supplies the meta and the page. */
+  const consider = (candidate: Section, ownerId: string, meta: SectionMeta) => {
+    if (candidate.type !== "document" || !candidate.id) return;
+    const content = candidate.content as DocumentSectionContent;
+    const documentId = content.doc?.documentId ?? "";
+    const entry = documentId ? manifest[documentId] : undefined;
+    if (!entry) return;
+
+    if (mode === "viewer") {
+      const page = pageBySectionId.get(ownerId);
+      if (!page || page.status !== "live" || !audiencePasses(page.access, audience)) return;
+      if (meta.status !== "live" || !audiencePasses(meta.access, audience)) return;
+    }
+
+    if (seen.has(candidate.id)) return;
+    seen.add(candidate.id);
+
+    out.push({
+      sectionId: candidate.id,
+      documentId,
+      title: content.title?.trim() || filenameStem(entry.filename),
+      filename: entry.filename,
+      size: entry.size,
+      kind: entry.kind,
+      url: documentFileUrl(documentId, entry.filename),
+      showInDocumentsNav: content.showInDocumentsNav !== false,
+    });
+  };
+
+  for (const { section, meta } of sections) {
+    consider(section, section.id, meta);
+    for (const child of getContainerChildren(section)) consider(child, section.id, meta);
+  }
+  return out;
+}

package/src/lib/index-ops.ts

@@ -188,6 +188,22 @@ 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(", ");
 
 /**

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/media-folders.ts

@@ -13,6 +13,15 @@ export interface FolderUploadPlan {
   fileTargets: { file: File; folderId: string | null }[];
 }
 
+/**
+ * The library's Documents pseudo-folder. UI-only: it is NEVER a `folders` entry
+ * (they round-trip to disk verbatim, and no MediaItem can point at it), so
+ * every `currentFolderId` consumer that reads `folders` must special-case it.
+ * Cannot collide with a real `f_`-prefixed id; distinct from the nav's
+ * `__documents__` group id.
+ */
+export const DOCUMENTS_FOLDER_ID = "__documents-folder__";
+
 /** Display-folder id. NOT related to MediaItem.folder (the git storage dir). */
 export function createFolderId(): string {
   const bytes = new Uint8Array(6);

package/src/lib/nav.ts

@@ -3,6 +3,7 @@ import { getSection, type SectionRegistry } from "./registry";
 import { audiencePasses, homePage, pageDisplayTitle } from "./pages";
 import { navEntries } from "./nav-tree";
 import type { SiteIndex } from "../schemas/site-config";
+import type { SiteDocument } from "./documents";
 
 export interface NavItem {
   href: string;
@@ -102,7 +103,30 @@ export interface GroupNavItem {
   pages: PageNavItem[];
 }
 
-export type SiteNavEntry = ({ kind: "page" } & PageNavItem) | GroupNavItem;
+/** A launcher entry for one document section. NOT a PageNavItem: the editor's
+ *  page rendering turns hrefs into pageSelectEvent buttons, which would
+ *  dead-end here. */
+export interface DocNavItem {
+  kind: "doc";
+  sectionId: string;
+  title: string;
+  url: string;
+}
+
+/** The synthetic, never-persisted "Documents" group. GroupNavItem.pages is
+ *  PageNavItem[], so the doc group is its own entry kind rather than a reuse. */
+export interface DocGroupNavItem {
+  kind: "doc-group";
+  id: string;
+  label: string;
+  docs: DocNavItem[];
+}
+
+/** Id of the synthetic group. Generated page-group ids never collide with it,
+ *  and it is never written to nav.json. */
+export const DOCUMENTS_GROUP_ID = "__documents__";
+
+export type SiteNavEntry = ({ kind: "page" } & PageNavItem) | GroupNavItem | DocGroupNavItem;
 
 export interface SiteNav {
   /** The authored tree: loose pages and groups, in nav order. */
@@ -123,8 +147,15 @@ export function generateSiteNav(opts: {
   mode: "viewer" | "editor";
   audience: string | null;
   registry?: SectionRegistry;
+  /** Pre-derived and already requester-filtered (deriveSiteDocuments). This
+   *  function cannot see SITE-WIDE section content — activeSections carries at
+   *  most the current page's sections, and EditorShell's two history call
+   *  sites pass activeSections: [] outright — so the list is always supplied
+   *  by the caller. Callers without one (history views) pass nothing and
+   *  render no group. */
+  documents?: SiteDocument[];
 }): SiteNav {
-  const { index, activeSections, activePageId, mode, audience, registry } = opts;
+  const { index, activeSections, activePageId, mode, audience, registry, documents } = opts;
   const active = activePageId ?? homePage(index).id;
   const byId = new Map(index.pages.map((p) => [p.id, p]));
 
@@ -163,6 +194,19 @@ export function generateSiteNav(opts: {
     });
   }
 
+  // Derived, never persisted: the Documents group lives only in this view model,
+  // so nav.json is never written, reconcileNav never sees it, and the Pages
+  // modal's positional drag indexing is untouched.
+  const navDocs = (documents ?? []).filter((d) => d.showInDocumentsNav);
+  if (navDocs.length > 0) {
+    entries.push({
+      kind: "doc-group",
+      id: DOCUMENTS_GROUP_ID,
+      label: "Documents",
+      docs: navDocs.map((d) => ({ kind: "doc" as const, sectionId: d.sectionId, title: d.title, url: d.url })),
+    });
+  }
+
   if (mode === "editor") {
     return {
       entries,

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,