@drawnagency/primitives 0.1.99 → 0.1.101

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,18 @@ 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,
+    // Direct document upload, for the `document` section's empty-state drop
+    // zone. Deliberately not routed through enqueueFile: that gate keys off the
+    // MIME type, so a file the drop zone means as a document but the browser
+    // typed as something else would silently become an image.
+    uploadDocument: documents.uploadDocument,
+  }), [handleMediaUpload, enqueueFile, mediaManifest, pendingMediaItems, pendingLocalUrls, siteConfig, documentManifest, documents.pendingDocuments, documents.uploadDocument]);
 
   return {
     processingItems,
@@ -684,6 +810,9 @@ export function useMediaPipeline({
     uploadProgress,
     handleMediaUpload,
     handleMediaDelete,
+    handleDocumentDelete,
+    pendingDocumentDeletions,
+    setPendingDocumentDeletions,
     handleMediaAltChange,
     handleFolderCreate,
     handleFolderRename,
@@ -692,7 +821,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 { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
 
 interface SectionRow {
   sectionId: string;
@@ -49,6 +50,11 @@ interface ContentCacheRow {
   savedBranchSha?: string | null;
   changedSectionIds?: string[];
   mainIndex?: SiteIndex | null;
+  // The document sidecar at this sha. Optional for rows written by older
+  // packages; readers fall back to {} (same posture as the fetch path's
+  // `data.documentManifest ?? {}`). Without this, a cache-hit editor load left
+  // documentManifest null and the whole documents feature dead for the session.
+  documentManifest?: DocumentManifest | null;
 }
 
 interface MediaManifestRow {
@@ -70,6 +76,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 +105,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 +208,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",
+    });
   }
 }
 
@@ -450,7 +483,7 @@ export async function cacheContent(
   sections: LoadedSection[],
   index: SiteIndex,
   siteConfig: Record<string, unknown>,
-  diff?: { savedBranchSha: string | null; changedSectionIds: string[]; mainIndex: SiteIndex | null },
+  diff?: { savedBranchSha: string | null; changedSectionIds: string[]; mainIndex: SiteIndex | null; documentManifest?: DocumentManifest },
 ): Promise<void> {
   const now = new Date().toISOString();
   await getDb().contentCache.put({
@@ -463,6 +496,7 @@ export async function cacheContent(
     savedBranchSha: diff?.savedBranchSha ?? null,
     changedSectionIds: diff?.changedSectionIds ?? [],
     mainIndex: diff?.mainIndex ?? null,
+    documentManifest: diff?.documentManifest ?? null,
   });
 }
 
@@ -474,6 +508,7 @@ export async function getCachedContent(): Promise<{
   savedBranchSha: string | null;
   changedSectionIds: string[];
   mainIndex: SiteIndex | null;
+  documentManifest: DocumentManifest;
 } | null> {
   const row = await getDb().contentCache.get("current");
   if (!row) return null;
@@ -487,6 +522,10 @@ export async function getCachedContent(): Promise<{
     // No stored mainIndex (e.g. legacy or post-publish cache) means "no draft",
     // so the published index equals the current index.
     mainIndex: row.mainIndex ?? row.index,
+    // Legacy row (pre-documents package): {} matches the fetch path's posture.
+    // The narrow stale edge — an old row at a sha that DOES hold a manifest —
+    // heals on the next fresh load or save.
+    documentManifest: row.documentManifest ?? {},
   };
 }
 
@@ -593,3 +632,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);
+}