@drawnagency/primitives 0.1.99 → 0.1.100

package/src/hooks/useMediaPipeline.ts

@@ -15,16 +15,21 @@ import {
 import { generateVideoPoster } from "../media/videoPoster";
 import { ASSET_CACHE_CONTROL } from "../storage/types";
 import { tallyImageIds, collectImageIds, clearImageIds, applyLogoDeletion } from "../lib/image-refs";
+import { clearDocumentRefs, tallyDocumentIds } from "../lib/document-refs";
 import {
   createFolderId, uniqueFolderName, effectiveParentId, canMoveFolder,
   descendantFolderIds, itemFolderId, planFolderUpload,
 } from "../lib/media-folders";
 import type { MediaFolder } from "../media/types";
+import { useDocumentUploads } from "./useDocumentUploads";
+import { DOCUMENT_MIME_TO_EXT, type DocumentManifest } from "../schemas/documents";
 
 interface UseMediaPipelineInput {
   siteConfig: SiteConfig | null;
   mediaManifest: MediaManifest;
   setMediaManifest: React.Dispatch<React.SetStateAction<MediaManifest>>;
+  documentManifest: DocumentManifest;
+  setDocumentManifest: React.Dispatch<React.SetStateAction<DocumentManifest>>;
   sections: LoadedSection[];
   setSections: React.Dispatch<React.SetStateAction<LoadedSection[]>>;
   setLocalChangesExist: React.Dispatch<React.SetStateAction<boolean>>;
@@ -47,6 +52,8 @@ export function useMediaPipeline({
   siteConfig,
   mediaManifest,
   setMediaManifest,
+  documentManifest,
+  setDocumentManifest,
   sections,
   setSections,
   setLocalChangesExist,
@@ -60,6 +67,10 @@ export function useMediaPipeline({
   const [pendingMediaItems, setPendingMediaItems] = useState<LibraryMediaItem[]>([]);
   const [pendingLocalUrls, setPendingLocalUrls] = useState<Record<string, string>>({});
   const [pendingDeletions, setPendingDeletions] = useState<string[]>([]);
+  // Committed documents deleted locally, awaiting the save that carries them as
+  // `deletedDocumentIds`. Staged-but-uncommitted documents never land here —
+  // they are simply unstaged.
+  const [pendingDocumentDeletions, setPendingDocumentDeletions] = useState<string[]>([]);
   // Direct-to-bucket large-video PUT progress, keyed by content hash (0..1).
   // Populated by uploadLargeVideo's XHR upload.onprogress, cleared on
   // completion or failure.
@@ -72,6 +83,34 @@ export function useMediaPipeline({
   // dropped when the editor DOES save in the same session.
   const [manifestDirty, setManifestDirty] = useState(false);
 
+  // Read inside the queue effect, whose deps are deliberately narrow — without
+  // the ref the error branch below would close over the first render's handler.
+  const onUploadErrorRef = useRef(onUploadError);
+  onUploadErrorRef.current = onUploadError;
+
+  // Read inside uploadDocument's async body, where a state snapshot taken at
+  // render time would be stale across the hash await.
+  const pendingDocumentDeletionsRef = useRef<string[]>(pendingDocumentDeletions);
+  pendingDocumentDeletionsRef.current = pendingDocumentDeletions;
+
+  /** Re-adding a document that is deleted-but-unsaved un-dooms it rather than
+   *  letting the upload dedup swallow it — the twin of the image pipeline's
+   *  `isDeleted` escape below. The ref is updated eagerly so two re-adds in one
+   *  tick can't both see the id as doomed. */
+  const undeleteDocument = useCallback((id: string) => {
+    if (!pendingDocumentDeletionsRef.current.includes(id)) return;
+    pendingDocumentDeletionsRef.current = pendingDocumentDeletionsRef.current.filter((d) => d !== id);
+    setPendingDocumentDeletions((prev) => prev.filter((d) => d !== id));
+  }, []);
+
+  const documents = useDocumentUploads({
+    documentManifest,
+    setDocumentManifest,
+    setLocalChangesExist,
+    undeleteDocument,
+    onUploadError,
+  });
+
   const queueRef = useRef<ProcessingQueue | null>(null);
   const uploadCallbacksRef = useRef<Map<string, (imageId: string) => void>>(new Map());
   // Display-folder target per in-flight upload, keyed by content hash. Set at
@@ -138,10 +177,22 @@ export function useMediaPipeline({
       onEvent: (event: QueueEvent) => {
         setProcessingItems((prev) => {
           const next = prev.filter((i) => i.id !== event.item.id);
-          if (event.item.state !== "complete") next.push(event.item);
+          // "error" must LEAVE the list too. Keeping it (the old `!== "complete"`
+          // test) is what left a failed item spinning forever in the toolbar.
+          if (event.item.state !== "complete" && event.item.state !== "error") next.push(event.item);
           return next;
         });
 
+        if (event.type === "error") {
+          uploadTargetsRef.current.delete(event.item.hash);
+          hiddenUploadsRef.current.delete(event.item.hash);
+          uploadCallbacksRef.current.delete(event.item.hash);
+          onUploadErrorRef.current?.(
+            `"${event.item.originalName}" couldn't be processed${event.item.error ? ` — ${event.item.error}` : ""}.`,
+          );
+          return;
+        }
+
         if (event.type === "complete" && event.item.result) {
           const result = event.item.result;
           const kind = event.item.kind;
@@ -359,6 +410,14 @@ export function useMediaPipeline({
 
     let alreadyExisting = 0;
     for (const file of files) {
+      // Documents never touch the rasterizer: their bytes must reach the repo
+      // or the bucket untransformed. Branch before every image-shaped gate
+      // below (size cap, hashing, queue.add).
+      if (file.type in DOCUMENT_MIME_TO_EXT) {
+        await documents.uploadDocument(file);
+        continue;
+      }
+
       if (file.size > mediaConfig.maxFileSize) {
         if (file.type === "video/mp4" || file.type === "video/webm") {
           // uploadLargeVideo already guarantees it never throws (see its own
@@ -406,7 +465,7 @@ export function useMediaPipeline({
           : `${alreadyExisting} files already exist in the library and were left where they are.`,
       );
     }
-  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, onUploadNotice, uploadLargeVideo]);
+  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, onUploadNotice, uploadLargeVideo, documents]);
 
   const handleMediaDelete = useCallback(async (ids: string[]) => {
     const idSet = new Set(ids);
@@ -462,6 +521,41 @@ export function useMediaPipeline({
     setLocalChangesExist(true);
   }, [pendingMediaItems, markSectionDirty, setSections, setDirtySectionIds, setLocalChangesExist, siteConfig, onSiteConfigChange]);
 
+  // Document deletion, the twin of handleMediaDelete. It lives here rather than
+  // in useDocumentUploads because the reference-repair pass needs the section
+  // state that hook cannot see; useDocumentUploads owns only the staged-row
+  // cleanup (unstageDocuments).
+  const handleDocumentDelete = useCallback(async (ids: string[]) => {
+    if (ids.length === 0) return;
+    const idSet = new Set(ids);
+    const stagedIds = documents.pendingDocuments.filter((d) => idSet.has(d.id)).map((d) => d.id);
+    // Only a COMMITTED document produces a deletion for the save to carry: a
+    // staged one has no manifest entry on the branch, so recording it would ask
+    // the server to remove something that was never written.
+    const committedIds = ids.filter((id) => id in documentManifest);
+
+    if (stagedIds.length > 0) await documents.unstageDocuments(stagedIds);
+    if (committedIds.length > 0) {
+      // No optimistic documentManifest mutation: the consumption points filter
+      // on this list, and the save co-sends the post-deletion manifest.
+      setPendingDocumentDeletions((prev) => [...prev, ...committedIds.filter((id) => !prev.includes(id))]);
+    }
+
+    setSections((prev) =>
+      prev.map((loaded) => {
+        const { changed, section } = clearDocumentRefs(loaded.section, idSet);
+        if (!changed) return loaded;
+        // A nested hit returns the rewritten CONTAINER — the section that owns
+        // the child's bytes, and so the one that gets dirtied and saved.
+        markSectionDirty(section.id, section as SectionContent);
+        setDirtySectionIds((dirty) => new Set(dirty).add(section.id));
+        return { ...loaded, section };
+      }),
+    );
+
+    setLocalChangesExist(true);
+  }, [documents, documentManifest, markSectionDirty, setSections, setDirtySectionIds, setLocalChangesExist]);
+
   const handleMediaAltChange = useCallback((id: string, alt: string) => {
     setMediaManifest((prev) => {
       const item = prev.images[id];
@@ -608,12 +702,33 @@ export function useMediaPipeline({
     return Object.fromEntries(counts);
   }, [sections, siteConfig]);
 
+  // The document twin of referenceCountMap, feeding the media modal's document
+  // usage pills and its delete confirmation. Unlike images, documents are never
+  // referenced by siteConfig — only by `document` sections, nested ones
+  // included (tallyDocumentIds recurses).
+  const documentReferenceCountMap = useMemo((): Record<string, number> => {
+    const counts = new Map<string, number>();
+    for (const { section } of sections) tallyDocumentIds(section, counts);
+    return Object.fromEntries(counts);
+  }, [sections]);
+
   // --- Unified enqueue ---
 
   const enqueueFile = useCallback((file: File, onComplete?: (imageId: string) => void, opts?: { hidden?: boolean }) => {
     if (!siteConfig) return;
     const mediaConfig = siteConfig.media;
-    if (file.size > mediaConfig.maxFileSize) return;
+    if (file.type in DOCUMENT_MIME_TO_EXT) {
+      void documents.uploadDocument(file, onComplete);
+      return;
+    }
+    if (file.size > mediaConfig.maxFileSize) {
+      // Previously a bare `return` — the file vanished with no spinner, no
+      // error, and no explanation.
+      onUploadError?.(
+        `"${file.name}" is larger than the ${Math.round(mediaConfig.maxFileSize / 1024 / 1024)}MB media limit.`,
+      );
+      return;
+    }
 
     const currentQueue = queueRef.current;
     (async () => {
@@ -645,7 +760,7 @@ export function useMediaPipeline({
         console.error(`[useMediaPipeline] Failed to enqueue file "${file.name}":`, err);
       }
     })();
-  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions]);
+  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, documents]);
 
   // --- Context value ---
 
@@ -669,7 +784,13 @@ export function useMediaPipeline({
     pendingItems: pendingMediaItems,
     pendingLocalUrls: pendingLocalUrls,
     siteConfig,
-  }), [handleMediaUpload, enqueueFile, mediaManifest, pendingMediaItems, pendingLocalUrls, siteConfig]);
+    // Read by useResolvedDocument (DocumentSourceField's entry/missing lookup).
+    // Document blob URLs deliberately do NOT merge into pendingLocalUrls: their
+    // one consumer is the doc-file registry, which U6 feeds straight from the
+    // pipeline's pendingDocumentUrls — a context copy would be dead surface.
+    documentManifest,
+    pendingDocuments: documents.pendingDocuments,
+  }), [handleMediaUpload, enqueueFile, mediaManifest, pendingMediaItems, pendingLocalUrls, siteConfig, documentManifest, documents.pendingDocuments]);
 
   return {
     processingItems,
@@ -684,6 +805,9 @@ export function useMediaPipeline({
     uploadProgress,
     handleMediaUpload,
     handleMediaDelete,
+    handleDocumentDelete,
+    pendingDocumentDeletions,
+    setPendingDocumentDeletions,
     handleMediaAltChange,
     handleFolderCreate,
     handleFolderRename,
@@ -692,7 +816,14 @@ export function useMediaPipeline({
     handleMediaMove,
     handleFolderUpload,
     referenceCountMap,
+    documentReferenceCountMap,
     contextValue,
     enqueueFile,
+    pendingDocuments: documents.pendingDocuments,
+    pendingDocumentUrls: documents.pendingDocumentUrls,
+    documentUploadProgress: documents.documentUploadProgress,
+    uploadDocument: documents.uploadDocument,
+    publishDocuments: documents.publishDocuments,
+    hydratePendingDocuments: documents.hydratePendingDocuments,
   };
 }

package/src/hooks/useResolvedDocument.ts

@@ -0,0 +1,25 @@
+import { useMemo } from "react";
+import { useMediaLibrary } from "../components/shell/MediaLibraryContext";
+import type { DocumentManifestEntry } from "../schemas/documents";
+
+export interface ResolvedDocument {
+  entry: DocumentManifestEntry | null;
+  /** True only when an id WAS requested and nothing backs it — the editor-side
+   *  "file missing" state. No id (unconfigured section) is not missing. */
+  missing: boolean;
+}
+
+/** Document lookup. Deliberately separate from useResolvedMedia: documents are
+ *  zero-variant and dimensionless, never ride resolveManifestReferences, and
+ *  live in the sidecar manifest. */
+export function useResolvedDocument(documentId: string | undefined): ResolvedDocument {
+  const ctx = useMediaLibrary();
+
+  return useMemo(() => {
+    if (!documentId) return { entry: null, missing: false };
+    const committed = ctx?.documentManifest?.[documentId];
+    const pending = ctx?.pendingDocuments?.find((d) => d.id === documentId)?.entry;
+    const entry = committed ?? pending ?? null;
+    return { entry, missing: entry === null };
+  }, [documentId, ctx]);
+}

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/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);