@drawnagency/primitives 0.1.98 → 0.1.100

package/src/components/shell/EditorShell.tsx

@@ -9,6 +9,7 @@ import type { Section, SectionContent } from "../../schemas/sections";
 import type { SiteIndex, SiteConfig, Page } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 import type { MediaManifest } from "../../media/types";
+import type { DocumentManifest } from "../../schemas/documents";
 import type { QueueItem } from "../../media/queue";
 import { composePreviewImage, PREVIEW_COMPOSE_VERSION } from "../../media/compose-preview";
 import { derivePreviewInputs, servedPreviewSize } from "../../media/preview-inputs";
@@ -30,7 +31,7 @@ import { EditorModal } from "./EditorModal";
 import { SiteSettingsModal } from "./SiteSettingsModal";
 import ChatWidget from "../chat/ChatWidget";
 import { MediaLibraryModal } from "./MediaLibraryModal";
-import { MediaLibraryContext } from "./MediaLibraryContext";
+import { MediaLibraryContext, type LibraryKind } from "./MediaLibraryContext";
 import { ProcessingIndicator } from "./ProcessingIndicator";
 import { SectionSkeleton } from "./SectionSkeleton";
 import { SectionTypePicker } from "./SectionTypePicker";
@@ -89,11 +90,13 @@ import { useBuildStatus } from "../../hooks/useBuildStatus";
 import { useMediaPipeline } from "../../hooks/useMediaPipeline";
 import { formatTimestamp } from "../../lib/timestamp";
 import { generateSiteNav } from "../../lib/nav";
+import { deriveSiteDocuments, type SiteDocument } from "../../lib/documents";
+import { setSiteDocuments, closeDocFile } from "../docfile/doc-file-state";
 import { pagesInNavOrder, moveNavEntry, addGroup, renameGroup, setGroupStartCollapsed, deleteGroup, type NavLocation } from "../../lib/nav-tree";
 import { siteNavChangeEvent, pageSelectEvent, darkModeEvent, siteNameChangeEvent, historySelectEvent, historyRestoreEvent, historyRestoreFailedEvent, editorDirtyEvent } from "../../lib/events";
 import {
   homePage, pageById, pageBySlug, pageDisplayTitle, addSectionToPage, removeSectionFromPages,
-  reorderSectionInPage, audiencePasses,
+  reorderVisibleSectionInPage, audiencePasses,
   setHomePage, setPageArchived, setPageFields, setPageAudience, setPageDocument, deletePage, addPage,
   moveSection as moveSectionReducer,
 } from "../../lib/pages";
@@ -137,6 +140,13 @@ interface SavedContent {
   changedSectionIds: string[];
   mainIndex: SiteIndex;
   mediaManifest?: MediaManifest;
+  /** The document sidecar. Optional: absent until the storage track adds it to
+   *  /api/content, and absent on any site with no documents. */
+  documentManifest?: DocumentManifest;
+  /** Indexed ids whose section file exists on the branch but is not valid JSON.
+   *  Their bodies are absent from `sections` while their index slots survive —
+   *  the editor must surface them, not silently render around them. */
+  unparseableSectionIds: string[];
 }
 
 interface Props {
@@ -192,9 +202,16 @@ export default function EditorShell({
   const [dirtySectionIds, setDirtySectionIds] = useState<Set<string>>(new Set());
   const [siteConfig, setSiteConfig] = useState<SiteConfig | null>(null);
   const [mediaManifest, setMediaManifest] = useState<MediaManifest>({ images: {}, folders: {} });
+  // null = /api/content has not resolved yet. Distinct from {} (loaded, no
+  // documents): U6's registry publish skips null so document rows keep the
+  // overlay island's SSR seed instead of flashing "File missing" on mount.
+  const [documentManifest, setDocumentManifest] = useState<DocumentManifest | null>(null);
   const [showMediaLibrary, setShowMediaLibrary] = useState(false);
   const [mediaModalMode, setMediaModalMode] = useState<"select" | "manage">("manage");
   const [mediaSelectCallback, setMediaSelectCallback] = useState<((id: string) => void) | null>(null);
+  // Kind filter for the current select-mode open (null = the historical
+  // image/animated/video picker). Consumed by MediaLibraryModal.
+  const [mediaSelectKinds, setMediaSelectKinds] = useState<ReadonlyArray<LibraryKind> | null>(null);
   const [deletedSections, setDeletedSections] = useState<Set<string>>(new Set());
   // Ref mirror so the debounced Dexie flush can persist the deletion set. Without
   // it the snapshot records the index minus the deleted sections but not the
@@ -235,6 +252,15 @@ export default function EditorShell({
   // Surfaces useMediaPipeline's onUploadNotice (e.g. "N files already exist
   // and were left where they are" on dedup skip) in the media library modal.
   const [uploadNotice, setUploadNotice] = useState<string | null>(null);
+  // Indexed ids whose file on the branch is not valid JSON (from /api/content).
+  // Their bodies can't render or be edited, but they hold their page-order slot
+  // — surfaced as a persistent banner so a "missing" section isn't mistaken for
+  // a deleted one and repaired by data loss.
+  const [unparseableSectionIds, setUnparseableSectionIds] = useState<string[]>([]);
+  // Non-fatal warnings from the last successful save (e.g. nav.json replacement
+  // declined by the degraded-nav guard) — without a surface, the save reads as
+  // fully landed when part of it was refused.
+  const [saveWarnings, setSaveWarnings] = useState<string[]>([]);
   const [activePageId, setActivePageId] = useState<string | null>(null);
   const [movingSectionId, setMovingSectionId] = useState<string | null>(null);
   // Set by recoverConflict when a rebase surfaces overlapping edits; drives the
@@ -397,6 +423,8 @@ export default function EditorShell({
     siteConfig,
     mediaManifest,
     setMediaManifest,
+    documentManifest: documentManifest ?? {},
+    setDocumentManifest: (next) => setDocumentManifest((prev) => typeof next === "function" ? next(prev ?? {}) : next),
     sections,
     setSections,
     setLocalChangesExist,
@@ -428,6 +456,8 @@ export default function EditorShell({
       changedSectionIds: (data.changedSectionIds ?? []) as string[],
       mainIndex: (data.mainIndex ?? data.index) as SiteIndex,
       mediaManifest: data.mediaManifest as MediaManifest | undefined,
+      documentManifest: data.documentManifest as DocumentManifest | undefined,
+      unparseableSectionIds: (data.unparseableSectionIds ?? []) as string[],
     };
   }, []);
 
@@ -440,6 +470,7 @@ export default function EditorShell({
   const recoverConflict = useCallback(async (): Promise<boolean> => {
     try {
       const remote = await fetchSavedContent();
+      setUnparseableSectionIds(remote.unparseableSectionIds);
       const dirtyRows = await getDirtySectionRows();
       const dirtyIds = new Set(dirtyRows.map((r) => r.sectionId));
 
@@ -771,6 +802,7 @@ export default function EditorShell({
     siteConfig,
     sections,
     deletedSectionIds: Array.from(deletedSections),
+    onSaveWarnings: setSaveWarnings,
     onSuccess: (savedSectionIds: string[], { editToken, sentDeletedIds }) => {
       // Generation-guarded post-save clears: any edit made WHILE the save was
       // in flight (generation > the token captured at save begin) was NOT
@@ -805,6 +837,22 @@ export default function EditorShell({
     },
     mediaManifest,
     mediaManifestRef,
+    documentManifest: documentManifest ?? {},
+    pendingDocuments: mediaPipeline.pendingDocuments,
+    onDocumentsPublished: (ids) => { void mediaPipeline.publishDocuments(ids); },
+    pendingDocumentDeletions: mediaPipeline.pendingDocumentDeletions,
+    // Fires only for ids the commit actually carried — a failed save leaves the
+    // pending list intact for the retry.
+    onDocumentsDeleted: (ids) => {
+      const doomed = new Set(ids);
+      setDocumentManifest((prev) => {
+        if (prev === null) return prev;
+        const next = { ...prev };
+        for (const id of doomed) delete next[id];
+        return next;
+      });
+      mediaPipeline.setPendingDocumentDeletions((prev) => prev.filter((id) => !doomed.has(id)));
+    },
     manifestDirty: mediaPipeline.manifestDirty,
     clearManifestDirty: () => mediaPipeline.setManifestDirty(false),
     pendingMediaItems: mediaPipeline.pendingMediaItems,
@@ -874,18 +922,61 @@ export default function EditorShell({
     hasLocalChanges: localChangesExist,
   });
 
-  // Push the current SiteNav (active page + its headings) to the Navigation island.
+  // The live draft's documents. Editor mode: no audience filtering — an editor
+  // sees every document, including drafts and gated ones.
+  //
+  // Documents STAGED this session are merged on top of the committed manifest
+  // and their gated URL is swapped for the local blob URL. That substitution is
+  // the entire pre-save preview mechanism (reconciliation decision 3): the row
+  // and the pane render whatever `url` the registry holds, so neither of them
+  // needs MediaLibraryContext — which the viewer path does not provide at all.
+  // null until /api/content resolves (C3's state contract): publishing a list
+  // derived from a not-yet-loaded manifest would overwrite the overlay island's
+  // SSR seed with [] and flash every document row to "File missing".
+  const siteDocuments = useMemo<SiteDocument[] | null>(() => {
+    if (documentManifest === null) return null;
+    const pending = mediaPipeline.pendingDocuments;
+    const merged: DocumentManifest = {
+      ...documentManifest,
+      ...Object.fromEntries(pending.map((d) => [d.id, d.entry])),
+    };
+    // Deletions are pending until a save commits them, so `documentManifest`
+    // still holds them — this consumption point is where they disappear.
+    for (const id of mediaPipeline.pendingDocumentDeletions) delete merged[id];
+    const localUrls = mediaPipeline.pendingDocumentUrls;
+    return deriveSiteDocuments({
+      index: siteIndex, sections, manifest: merged, mode: "editor", audience: null,
+    }).map((doc) => {
+      const localUrl = localUrls[doc.documentId];
+      return localUrl ? { ...doc, url: localUrl } : doc;
+    });
+  }, [siteIndex, sections, documentManifest, mediaPipeline.pendingDocuments, mediaPipeline.pendingDocumentUrls, mediaPipeline.pendingDocumentDeletions]);
+
+  // Publish to the doc-file registry so the DocFileOverlay island (a separate
+  // island, mounted by the edit route) and every document row track the draft
+  // rather than the build-time SSR list.
+  useEffect(() => {
+    if (siteDocuments !== null) setSiteDocuments(siteDocuments);
+  }, [siteDocuments]);
+
+  // Push the current SiteNav (active page + its headings + the Documents group)
+  // to the Navigation island.
   useEffect(() => {
     if (!resolvedActivePage) return;
     const nav = generateSiteNav({
       index: siteIndex, activeSections, activePageId: resolvedActivePage.id, mode: "editor", audience: null,
+      documents: siteDocuments ?? [],
     });
     siteNavChangeEvent.dispatch(nav);
-  }, [siteIndex, activeSections, resolvedActivePage]);
+  }, [siteIndex, activeSections, resolvedActivePage, siteDocuments]);
 
   const goToPage = useCallback((pageId: string) => {
     const page = pageById(siteIndexRef.current, pageId);
     if (!page) return;
+    // Client-side page switching pushes state without a hashchange, so a stale
+    // #doc fragment would survive and the pane would hang over the new page.
+    // The atom clears the fragment and closes.
+    closeDocFile();
     setActivePageId(pageId);
     if (typeof window !== "undefined") {
       const path = page.slug === "" ? "/edit" : `/edit/${page.slug}`;
@@ -1012,10 +1103,12 @@ export default function EditorShell({
           loadedManifest = data.mediaManifest;
           await persistMediaManifest(loadedManifest);
         }
+        setDocumentManifest(data.documentManifest ?? {});
         setSavedSha(data.savedBranchSha);
         setMainSha(headSha);
         setChangedSectionIds(new Set(data.changedSectionIds));
         setMainIndex(data.mainIndex);
+        setUnparseableSectionIds(data.unparseableSectionIds);
       }
 
       if (cancelled) return;
@@ -1072,6 +1165,11 @@ export default function EditorShell({
     return () => { cancelled = true; };
   }, [headSha, draftHeadSha, siteId, applySiteConfigPreview, fetchSavedContent]);
 
+  useEffect(() => {
+    void mediaPipeline.hydratePendingDocuments();
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- one-shot restore of last session's staged documents
+  }, []);
+
   // --- Recovery handlers ---
 
   const handleRestore = useCallback(async () => {
@@ -1271,11 +1369,16 @@ export default function EditorShell({
   const onReorderSections = useCallback(
     (fromIndex: number, toIndex: number) => {
       if (!resolvedActivePage) return;
-      setSiteIndex((prev) => reorderSectionInPage(prev, resolvedActivePage.id, fromIndex, toIndex));
+      // Consumers emit indices into activeSections — page.order FILTERED to
+      // loadable bodies. Resolve through ids so a filtered-out section
+      // (unparseable file, schema miss) can't shift the splice onto the wrong
+      // entry and move a different section than the one dragged.
+      const visibleIds = activeSections.map((s) => s.section.id);
+      setSiteIndex((prev) => reorderVisibleSectionInPage(prev, resolvedActivePage.id, visibleIds, fromIndex, toIndex));
       persistence.markIndexDirty();
       setLocalChangesExist(true);
     },
-    [persistence, resolvedActivePage],
+    [persistence, resolvedActivePage, activeSections],
   );
 
   const onBlockMove = useMemo(
@@ -1603,9 +1706,10 @@ export default function EditorShell({
       <EditorModalProvider>
         <MediaLibraryContext.Provider value={{
           ...mediaPipeline.contextValue,
-          openSelectModal: (onSelect) => {
+          openSelectModal: (onSelect, opts) => {
             setMediaModalMode("select");
             setMediaSelectCallback(() => onSelect);
+            setMediaSelectKinds(opts?.kinds ?? null);
             setShowMediaLibrary(true);
           },
           reportRejectedUploads: (files) => setRejectedUploads(files),
@@ -1720,6 +1824,24 @@ export default function EditorShell({
             </div>
           )}
 
+          {unparseableSectionIds.length > 0 && (
+            <div className="sticky top-2 z-30 mx-auto w-full max-w-3xl px-4">
+              <UploadRejectionAlert
+                message={`${unparseableSectionIds.length} section file${unparseableSectionIds.length === 1 ? "" : "s"} on this site cannot be read (${unparseableSectionIds.join(", ")}). Damaged sections keep their place on the page and are not deleted by saving — repair the file to restore them.`}
+                onDismiss={() => setUnparseableSectionIds([])}
+              />
+            </div>
+          )}
+
+          {saveWarnings.length > 0 && (
+            <div className="sticky top-2 z-30 mx-auto w-full max-w-3xl px-4">
+              <UploadRejectionAlert
+                message={saveWarnings.join(" ")}
+                onDismiss={() => setSaveWarnings([])}
+              />
+            </div>
+          )}
+
           {remoteNotice && (
             <div
               role="status"
@@ -1815,6 +1937,7 @@ export default function EditorShell({
             onClose={() => {
               setShowMediaLibrary(false);
               setMediaSelectCallback(null);
+              setMediaSelectKinds(null);
             }}
             title="Media Library"
             size="large"
@@ -1828,17 +1951,34 @@ export default function EditorShell({
                 ...Object.values(mediaManifest.images),
                 ...mediaPipeline.pendingMediaItems,
               ].filter((item) => !mediaPipeline.pendingDeletions.includes(item.id) && !item.hidden)}
+              documents={Object.entries({
+                ...documentManifest,
+                ...Object.fromEntries(mediaPipeline.pendingDocuments.map((d) => [d.id, d.entry])),
+              })
+                // Deleted-but-unsaved documents stay in the manifest until the
+                // save commits them; the library must not offer them again.
+                .filter(([id]) => !mediaPipeline.pendingDocumentDeletions.includes(id))
+                .map(([id, entry]) => ({
+                  id,
+                  filename: entry.filename,
+                  size: entry.size,
+                  kind: entry.kind,
+                }))}
+              kinds={mediaModalMode === "manage" ? undefined : (mediaSelectKinds ?? undefined)}
               onSelect={(id) => {
                 if (mediaSelectCallback) {
                   mediaSelectCallback(id);
                 }
                 setShowMediaLibrary(false);
                 setMediaSelectCallback(null);
+                setMediaSelectKinds(null);
               }}
               onUpload={mediaPipeline.handleMediaUpload}
               onDelete={mediaPipeline.handleMediaDelete}
+              onDeleteDocuments={(ids) => { void mediaPipeline.handleDocumentDelete(ids); }}
               onAltChange={mediaPipeline.handleMediaAltChange}
               referenceCountMap={mediaPipeline.referenceCountMap}
+              documentReferenceCountMap={mediaPipeline.documentReferenceCountMap}
               localUrlMap={mediaPipeline.pendingLocalUrls}
               maxFileSize={siteConfig?.media.maxFileSize}
               uploadProgress={mediaPipeline.uploadProgress}
@@ -1983,7 +2123,8 @@ function HistoryWatcher({
           siteConfig: data.siteConfig,
         });
         siteNavChangeEvent.dispatch(
-          generateSiteNav({ index: data.index, activeSections: [], activePageId: null, mode: "editor", audience: null }),
+          // History views hold no document manifest for that commit — no group.
+          generateSiteNav({ index: data.index, activeSections: [], activePageId: null, mode: "editor", audience: null, documents: [] }),
         );
       } catch (err) {
         console.error("Failed to load historical content:", err);
@@ -2034,7 +2175,10 @@ function HistoryOrEditorContent({
       wasInHistory.current = false;
       if (index.pages.length > 0) {
         siteNavChangeEvent.dispatch(
-          generateSiteNav({ index, activeSections, activePageId, mode: "editor", audience: null }),
+          // Leaving history: the live nav effect re-dispatches with the current
+          // document list on the next render, so this one deliberately omits it
+          // rather than briefly showing a stale group.
+          generateSiteNav({ index, activeSections, activePageId, mode: "editor", audience: null, documents: [] }),
         );
       }
     }
@@ -2046,7 +2190,7 @@ function HistoryOrEditorContent({
     if (!historyState || !historyPage) return;
     if (!historyPageId) setHistoryPageId(historyPage.id);
     siteNavChangeEvent.dispatch(
-      generateSiteNav({ index: historyState.index, activeSections: [], activePageId: historyPage.id, mode: "editor", audience: null }),
+      generateSiteNav({ index: historyState.index, activeSections: [], activePageId: historyPage.id, mode: "editor", audience: null, documents: [] }),
     );
   }, [historyState, historyPage?.id]);
 

package/src/components/shell/MediaBreadcrumb.tsx

@@ -2,7 +2,7 @@ import { Fragment, useRef } from "react";
 import { ChevronRight } from "lucide-react";
 import { cn } from "../../lib/cn";
 import type { MediaFolder, MediaItem } from "../../media/types";
-import { folderPathIds } from "../../lib/media-folders";
+import { DOCUMENTS_FOLDER_ID, folderPathIds } from "../../lib/media-folders";
 import { useFolderDropTarget } from "../../hooks/useMediaFolderDnd";
 import type { MediaFolderDndBindings } from "./MediaFolderTree";
 
@@ -55,6 +55,19 @@ function Segment({
 
 export function MediaBreadcrumb({ folders, currentFolderId, onNavigate, dnd }: MediaBreadcrumbProps) {
   if (currentFolderId === null) return null;
+
+  // The Documents pseudo-folder has no `folders` entry, so the path helpers
+  // return nothing for it — its crumb is static, and always a leaf.
+  if (currentFolderId === DOCUMENTS_FOLDER_ID) {
+    return (
+      <div className="flex flex-wrap items-center gap-0.5">
+        <Segment label="All media" target={null} onNavigate={onNavigate} dnd={dnd} isCurrent={false} />
+        <ChevronRight size={12} className="shrink-0 text-base-contrast-light" />
+        <Segment label="Documents" target={DOCUMENTS_FOLDER_ID} onNavigate={onNavigate} dnd={dnd} isCurrent />
+      </div>
+    );
+  }
+
   const pathIds = folderPathIds(folders, currentFolderId);
 
   return (

package/src/components/shell/MediaFolderTile.tsx

@@ -17,11 +17,13 @@ export interface MediaFolderTileProps {
   dnd?: MediaFolderDndBindings;
   /** Optional accessible label override for the root element (e.g. "Open folder Logos"). */
   ariaLabel?: string;
+  /** Glyph override — the Documents pseudo-folder uses a file icon. */
+  icon?: React.ReactNode;
 }
 
 
 export function MediaFolderTile({
-  id, name, count, onOpen, manage, onRename, onDeleteRequest, dnd, ariaLabel,
+  id, name, count, onOpen, manage, onRename, onDeleteRequest, dnd, ariaLabel, icon,
 }: MediaFolderTileProps) {
   const [menuOpen, setMenuOpen] = useState(false);
   const [renaming, setRenaming] = useState(false);
@@ -80,7 +82,7 @@ export function MediaFolderTile({
         drop.isDropTarget && "border-primary ring-2 ring-primary ring-inset",
       )}
     >
-      <Folder size={16} className="shrink-0 text-base-contrast-light" />
+      {icon ?? <Folder size={16} className="shrink-0 text-base-contrast-light" />}
       {renaming ? (
         <input
           autoFocus

package/src/components/shell/MediaFolderTree.tsx

@@ -1,8 +1,8 @@
 import { useRef } from "react";
-import { ChevronRight, Folder, LayoutGrid } from "lucide-react";
+import { ChevronRight, FileText, Folder, LayoutGrid } from "lucide-react";
 import { cn } from "../../lib/cn";
 import type { MediaFolder, MediaItem } from "../../media/types";
-import { buildFolderTree, type FolderTreeNode } from "../../lib/media-folders";
+import { buildFolderTree, DOCUMENTS_FOLDER_ID, type FolderTreeNode } from "../../lib/media-folders";
 import { useFolderDropTarget } from "../../hooks/useMediaFolderDnd";
 
 export interface MediaFolderDndBindings {
@@ -22,6 +22,9 @@ export interface MediaFolderTreeProps {
   onExpand: (id: string) => void;
   onToggleExpand: (id: string) => void;
   dnd?: MediaFolderDndBindings;
+  /** Documents pseudo-folder row. Omitted (or 0) renders no row; it is never a
+   *  drop target — nothing can be moved into it. */
+  documentCount?: number;
 }
 
 
@@ -99,7 +102,7 @@ function TreeRow({
 }
 
 export function MediaFolderTree(props: MediaFolderTreeProps) {
-  const { folders, totalCount, currentFolderId, onNavigate, dnd } = props;
+  const { folders, totalCount, currentFolderId, onNavigate, dnd, documentCount = 0 } = props;
   const tree = buildFolderTree(folders);
   const root = useRowDropTarget(null, dnd);
 
@@ -119,6 +122,20 @@ export function MediaFolderTree(props: MediaFolderTreeProps) {
           <span className="shrink-0 text-xs text-base-contrast-light">{totalCount}</span>
         )}
       </div>
+      {documentCount > 0 && (
+        <div
+          role="button"
+          tabIndex={0}
+          aria-label="Documents"
+          onClick={() => onNavigate(DOCUMENTS_FOLDER_ID)}
+          onKeyDown={(e) => { if (e.key === "Enter") onNavigate(DOCUMENTS_FOLDER_ID); }}
+          className={rowClass(currentFolderId === DOCUMENTS_FOLDER_ID, false)}
+        >
+          <FileText size={14} className="shrink-0 text-base-contrast-light" />
+          <span className="min-w-0 flex-1 truncate">Documents</span>
+          <span className="shrink-0 text-xs text-base-contrast-light">{documentCount}</span>
+        </div>
+      )}
       {tree.map((node) => (
         <TreeRow key={node.id} node={node} depth={0} props={props} />
       ))}

package/src/components/shell/MediaLibraryContext.tsx

@@ -1,9 +1,22 @@
 import { createContext, useContext } from "react";
 import type { MediaManifest, MediaItem } from "../../media/types";
 import type { SiteConfig } from "../../schemas/site-config";
+import type { DocumentManifest, DocumentManifestEntry } from "../../schemas/documents";
+
+/** Kinds the media library can be filtered to when opened as a picker. */
+export type LibraryKind = "image" | "animated" | "video" | "document";
+
+/** A document staged locally this session — bytes (git tier) or bucket object
+ *  already PUT — that is not yet in the committed document manifest. */
+export interface PendingDocument {
+  id: string;
+  entry: DocumentManifestEntry;
+}
 
 export interface MediaLibraryContextValue {
-  openSelectModal: (onSelect: (imageId: string) => void) => void;
+  /** `opts.kinds` restricts the picker; omitted keeps the historical
+   *  image/animated/video behavior for every pre-existing call site. */
+  openSelectModal: (onSelect: (imageId: string) => void, opts?: { kinds?: ReadonlyArray<LibraryKind> }) => void;
   uploadFile: (file: File) => void;
   uploadFileWithCallback: (file: File, onComplete: (imageId: string) => void, opts?: { hidden?: boolean }) => string;
   reportRejectedUploads: (files: { name: string; reason: "size" | "type" }[]) => void;
@@ -11,6 +24,10 @@ export interface MediaLibraryContextValue {
   pendingItems: MediaItem[];
   pendingLocalUrls: Record<string, string>;
   siteConfig: SiteConfig | null;
+  /** Sidecar document manifest. Optional: viewer-side and test contexts
+   *  predate documents and must keep compiling. */
+  documentManifest?: DocumentManifest;
+  pendingDocuments?: PendingDocument[];
 }
 
 export const MediaLibraryContext = createContext<MediaLibraryContextValue | null>(null);