@drawnagency/primitives 0.1.99 → 0.1.101

package/dist/schemas/index.js

@@ -3,7 +3,7 @@ import {
   AudienceNameSchema,
   MediaGridOptionsSchema,
   slugifyAudienceName
-} from "../chunk-FOY5TF7D.js";
+} from "../chunk-ZDQ3TT47.js";
 import {
   AudienceSchema,
   RoleSchema,
@@ -16,6 +16,18 @@ import {
   LinkValueSchema,
   isSafeHref
 } from "../chunk-PZJL2S3Z.js";
+import {
+  DOCUMENT_BUCKET_MAX_BYTES,
+  DOCUMENT_GIT_MAX_BYTES,
+  DOCUMENT_KIND_TO_MIME,
+  DOCUMENT_MANIFEST_PATH,
+  DOCUMENT_MIME_TO_EXT,
+  DocumentManifestEntrySchema,
+  DocumentManifestSchema,
+  documentBucketPath,
+  documentFileUrl,
+  documentGitPath
+} from "../chunk-BS5AQHZG.js";
 import {
   NavEntrySchema,
   NavFileSchema
@@ -58,6 +70,13 @@ export {
   ChatbotConfigSchema,
   ChatbotTaskSchema,
   DEFAULT_LINK,
+  DOCUMENT_BUCKET_MAX_BYTES,
+  DOCUMENT_GIT_MAX_BYTES,
+  DOCUMENT_KIND_TO_MIME,
+  DOCUMENT_MANIFEST_PATH,
+  DOCUMENT_MIME_TO_EXT,
+  DocumentManifestEntrySchema,
+  DocumentManifestSchema,
   FontNameSchema,
   HexColorSchema,
   ImageManifestSchema,
@@ -84,6 +103,9 @@ export {
   StatusSchema,
   TextLineSchema,
   VariantSchema,
+  documentBucketPath,
+  documentFileUrl,
+  documentGitPath,
   getSectionContentSchema,
   getSectionSchema,
   isSafeHref,

package/dist/storage/index.d.ts

@@ -1,3 +1,3 @@
-export type { StorageProvider, FileWrite, AssetStore } from "./types";
-export { StorageConflictError, IdempotencyLookupUnavailableError, ASSET_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";
+export type { StorageProvider, FileWrite, AssetStore, DocumentStore } from "./types";
+export { StorageConflictError, IdempotencyLookupUnavailableError, ASSET_CACHE_CONTROL, DOCUMENT_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,iCAAiC,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,iCAAiC,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC"}

package/dist/storage/index.js

@@ -1,14 +1,16 @@
 import {
   ASSET_CACHE_CONTROL,
+  DOCUMENT_CACHE_CONTROL,
   IDEMPOTENCY_KEY_RE,
   IDEMPOTENCY_TRAILER,
   IdempotencyLookupUnavailableError,
   StorageConflictError,
   withIdempotencyTrailer
-} from "../chunk-FAZFADJK.js";
+} from "../chunk-3TO4RRHY.js";
 import "../chunk-JSBRDJBE.js";
 export {
   ASSET_CACHE_CONTROL,
+  DOCUMENT_CACHE_CONTROL,
   IDEMPOTENCY_KEY_RE,
   IDEMPOTENCY_TRAILER,
   IdempotencyLookupUnavailableError,

package/dist/storage/types.d.ts

@@ -111,9 +111,18 @@ export declare const ASSET_CACHE_CONTROL = "max-age=31536000, immutable";
  * can slot in. All paths are SITE-RELATIVE ("media/{hash}/original.mp4") —
  * implementations prepend the tenant prefix ("sites/{siteId}/") themselves so
  * a caller can never address another tenant's objects.
+ *
+ * This bucket is PUBLIC: an object's URL is statically derivable from the
+ * bucket's public base, so `createUploadUrl` returns it once at upload time
+ * (built locally in standalone mode, brokered from the admin app's env in
+ * platform mode) and the media manifest stores that absolute URL. Rendering
+ * reads the manifest — nothing on the read path re-derives a URL.
  */
 export interface AssetStore {
-    /** Mint a signed direct-upload URL for the browser (PUT). */
+    /**
+     * Mint a signed direct-upload URL for the browser (PUT), along with the
+     * object's permanent public URL for the caller to persist.
+     */
     createUploadUrl(path: string, opts: {
         contentType: string;
     }): Promise<{
@@ -121,8 +130,6 @@ export interface AssetStore {
         path: string;
         publicUrl: string;
     }>;
-    /** Deterministic public CDN URL for an object (no network call). */
-    getPublicUrl(path: string): string;
     delete(paths: string[]): Promise<void>;
     /** Recursive listing under a site-relative prefix. */
     list(prefix: string): Promise<{
@@ -131,4 +138,53 @@ export interface AssetStore {
         updatedAt: string;
     }[]>;
 }
+/**
+ * `Cache-Control` every DOCUMENT upload must set. Deliberately NOT
+ * ASSET_CACHE_CONTROL: documents live in a PRIVATE bucket reachable only
+ * through short-lived presigned GETs, and a shared cache keyed on the full
+ * signed URL would otherwise retain the bytes for a year after the signature
+ * expired. `private` keeps the copy in the requesting browser only.
+ */
+export declare const DOCUMENT_CACHE_CONTROL = "private, max-age=31536000, immutable";
+/**
+ * Optional PRIVATE document store — a second bucket with no public domain.
+ *
+ * Deliberately not an AssetStore: the assets bucket is public by configuration
+ * at R2_PUBLIC_BASE (videos depend on it), so a signed GET there would protect
+ * nothing and hosted HTML would render unsandboxed on a sibling origin. Hence
+ * the asymmetry with AssetStore — an asset has a permanent public URL handed
+ * back by `createUploadUrl`, while a document has no durable URL at all: every
+ * read is a short-lived signed GET from `createDownloadUrl`, minted only after
+ * the gated route has authorized the requester.
+ *
+ * Paths are SITE-RELATIVE ("documents/{hash}/original.pdf"); implementations
+ * prepend the tenant prefix themselves so a caller can never address another
+ * tenant's objects.
+ */
+export interface DocumentStore {
+    /** Mint a signed direct-upload URL for the browser (PUT). */
+    createUploadUrl(path: string, opts: {
+        contentType: string;
+    }): Promise<{
+        uploadUrl: string;
+        path: string;
+    }>;
+    /**
+     * Mint a short-lived signed GET. `downloadFilename`, when given, signs
+     * `response-content-disposition: attachment` into the URL — R2 sends no
+     * Content-Disposition of its own, so this is the only way ?download=1 can
+     * force a download on the bucket tier.
+     */
+    createDownloadUrl(path: string, opts: {
+        expiresInSeconds: number;
+        downloadFilename?: string;
+    }): Promise<string>;
+    delete(paths: string[]): Promise<void>;
+    /** Recursive listing under a site-relative prefix. */
+    list(prefix: string): Promise<Array<{
+        path: string;
+        size: number;
+        updatedAt: string;
+    }>>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,cAAc,EAAE,MAAM,GAAG,IAAI;gBAA7B,cAAc,EAAE,MAAM,GAAG,IAAI;CAI1D;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CACR,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,EAIf,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GACxC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9B,YAAY,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE7C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,0BAA0B,CAAC,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;aAC5B,KAAK,CAAC,EAAE,OAAO;gBAAf,KAAK,CAAC,EAAE,OAAO,YAAA;CAI9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAA6B,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,gCAAgC,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnE,oEAAoE;IACpE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CACpF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,cAAc,EAAE,MAAM,GAAG,IAAI;gBAA7B,cAAc,EAAE,MAAM,GAAG,IAAI;CAI1D;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CACR,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,EAIf,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GACxC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9B,YAAY,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE7C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,0BAA0B,CAAC,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,iCAAkC,SAAQ,KAAK;aAC5B,KAAK,CAAC,EAAE,OAAO;gBAAf,KAAK,CAAC,EAAE,OAAO,YAAA;CAI9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAA6B,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,gCAAgC,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CACpF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,yCAAyC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,iBAAiB,CACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACzF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawnagency/primitives",
-  "version": "0.1.99",
+  "version": "0.1.101",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -24,6 +24,10 @@
       "types": "./dist/schemas/link.d.ts",
       "default": "./dist/schemas/link.js"
     },
+    "./schemas/documents": {
+      "types": "./dist/schemas/documents.d.ts",
+      "default": "./dist/schemas/documents.js"
+    },
     "./lib": {
       "types": "./dist/lib/index.d.ts",
       "default": "./dist/lib/index.js"

package/src/components/chat/ChatPanel.tsx

@@ -4,6 +4,7 @@ import { ArrowDown, ChevronDown, ChevronRight, History, Pin, PinOff, SquarePen,
 import { cn } from "../../lib/cn";
 import { ensureSanitizer, sanitizeHtml } from "../../lib/sanitize";
 import { resolveThinkingPhrases } from "../../lib/chatbot";
+import { lockBodyScroll } from "../../lib/scroll-lock";
 import { loadHistory, upsertConversation, setConversationPinned, removeConversation, type StoredConversation } from "./chat-history";
 import { Select } from "../shared/Select";
 import { IconButton } from "../shared/IconButton";
@@ -299,9 +300,7 @@ export default function ChatPanel({ open, closing, animateEnter, onClose, siteNa
   // The open sheet is modal: the page behind it must not scroll.
   useEffect(() => {
     if (mode !== "sheet" || !open) return;
-    const prev = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    return () => { document.body.style.overflow = prev; };
+    return lockBodyScroll();
   }, [mode, open]);
 
   // Explicit-open focus: composer on desktop, the panel itself on the sheet
@@ -487,7 +486,9 @@ export default function ChatPanel({ open, closing, animateEnter, onClose, siteNa
           // width, so the panel always tucks below it — the toolbar never
           // moves during the open/close slide.
           mode === "docked" && cn(
-            "fixed right-0 bottom-0 z-40 w-[var(--chat-w)] border-l border-base-200",
+            // bp-chat-panel is a STABLE hook, not styling: base.css pins the
+            // docked panel to the 120rem band edge under html.bp-doc-open.
+            "bp-chat-panel fixed right-0 bottom-0 z-40 w-[var(--chat-w)] border-l border-base-200",
             variant === "editor" ? "top-16" : "top-16 xl:top-0",
             "motion-safe:transition-transform motion-safe:duration-300",
             open ? "translate-x-0" : "translate-x-full",

package/src/components/docfile/DocFileOverlay.tsx

@@ -0,0 +1,54 @@
+import { lazy, Suspense, useEffect, useState } from "react";
+import type { SiteDocument } from "../../lib/documents";
+import {
+  subscribeDocFile,
+  subscribeSiteDocuments,
+  getSiteDocuments,
+  seedSiteDocuments,
+  closeDocFile,
+  isDocDesktop,
+} from "./doc-file-state";
+
+const DocFilePane = lazy(() => import("./DocFilePane"));
+
+/**
+ * One mount per page, rendered into the Layout `chrome` slot (OUTSIDE <main>:
+ * the chat dock's band-shift transform would re-anchor a position:fixed
+ * descendant). `documents` is the requester-filtered SSR list — on /edit it is
+ * initial state only; EditorShell republishes the live draft list.
+ */
+export default function DocFileOverlay({
+  documents,
+  editor = false,
+}: { documents: SiteDocument[]; editor?: boolean }) {
+  const [docs, setDocs] = useState<SiteDocument[] | null>(null);
+  const [openId, setOpenId] = useState<string | null>(null);
+
+  useEffect(() => {
+    seedSiteDocuments(documents);
+    setDocs(getSiteDocuments());
+    return subscribeSiteDocuments(setDocs);
+  }, [documents]);
+
+  useEffect(() => subscribeDocFile(setOpenId), []);
+
+  const doc = openId && docs ? (docs.find((d) => d.sectionId === openId) ?? null) : null;
+
+  // Below the desktop breakpoint a PDF goes to the OS viewer. The row already
+  // short-circuits, but a Documents-nav entry lands here, so the guard belongs
+  // at the pane too.
+  useEffect(() => {
+    if (!doc || doc.kind !== "pdf" || isDocDesktop()) return;
+    window.open(doc.url, "_blank", "noopener,noreferrer");
+    closeDocFile();
+  }, [doc]);
+
+  if (!doc) return null;
+  if (doc.kind === "pdf" && !isDocDesktop()) return null;
+
+  return (
+    <Suspense fallback={null}>
+      <DocFilePane doc={doc} onClose={closeDocFile} editor={editor} />
+    </Suspense>
+  );
+}

package/src/components/docfile/DocFilePane.tsx

@@ -0,0 +1,133 @@
+import { useEffect, useRef, useState } from "react";
+import { Download, X } from "lucide-react";
+import type { SiteDocument } from "../../lib/documents";
+import { documentFileUrl } from "../../schemas/documents";
+import { lockBodyScroll } from "../../lib/scroll-lock";
+
+/** How long a frame may sit on "loading" before we offer a retry. */
+const LOAD_TIMEOUT_MS = 15_000;
+
+/**
+ * The solid stage: an opaque, flat, bordered pane between the nav edge and the
+ * chat edge. Geometry lives in base.css (.doc-file-pane) because it is calc()
+ * against doc mode's own 120rem stage band — the band the nav and chat are
+ * pinned to under html.bp-doc-open (NOT the page's 80rem --layout-max-width
+ * band, which doc mode never touches). z-30 — above unpositioned page content,
+ * BELOW the nav and docked chat (z-40) and the mobile nav header / chat sheet
+ * (z-50), so all chrome stays reachable. `editor` adds top clearance for the
+ * edit route's always-fixed h-16 toolbar.
+ */
+export default function DocFilePane({
+  doc,
+  onClose,
+  editor = false,
+}: { doc: SiteDocument; onClose: () => void; editor?: boolean }) {
+  const [attempt, setAttempt] = useState(0);
+  const [state, setState] = useState<"loading" | "ready" | "error">("loading");
+  const frameRef = useRef<HTMLIFrameElement | null>(null);
+
+  useEffect(() => lockBodyScroll(), []);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      e.preventDefault();
+      onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  useEffect(() => {
+    setState("loading");
+    const timer = setTimeout(() => setState((s) => (s === "loading" ? "error" : s)), LOAD_TIMEOUT_MS);
+    return () => clearTimeout(timer);
+  }, [attempt, doc.url]);
+
+  // Natively, not via an onError prop: React registers a non-delegated `error`
+  // listener for <img>/<image> but for <iframe> only `load` (react-dom
+  // setInitialProperties), and `error` does not bubble — so an onError prop on
+  // an iframe is never called. Browsers rarely fire it either, which is what
+  // LOAD_TIMEOUT_MS is for; this covers the cases that do.
+  useEffect(() => {
+    const frame = frameRef.current;
+    if (!frame) return;
+    const onError = () => setState("error");
+    frame.addEventListener("error", onError);
+    return () => frame.removeEventListener("error", onError);
+  }, [attempt, doc.url]);
+
+  return (
+    <div
+      role="dialog"
+      aria-label={doc.title}
+      data-testid="doc-file-pane"
+      className={`doc-file-pane${editor ? " doc-file-pane--editor" : ""} fixed z-30 flex flex-col overflow-hidden rounded-outer border border-base-200 bg-base`}
+    >
+      <div className="flex shrink-0 items-center justify-between gap-3 border-b border-base-200 px-4 py-2">
+        <div className="flex min-w-0 items-baseline gap-2">
+          <span className="truncate text-sm font-medium text-base-contrast">{doc.title}</span>
+          <span className="truncate font-mono text-xs text-base-contrast/70">{doc.filename}</span>
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          <a
+            // Built by documentFileUrl's `download` option, never by appending
+            // a query string: `doc.url` is a blob: URL for a document staged
+            // this session, and "blob:…?download=1" resolves to nothing. A blob
+            // URL is already directly downloadable, so it passes through.
+            href={
+              doc.url.startsWith("blob:")
+                ? doc.url
+                : documentFileUrl(doc.documentId, doc.filename, { download: true })
+            }
+            download={doc.filename}
+            aria-label={`Download ${doc.filename}`}
+            className="cursor-pointer rounded-inner p-1.5 text-base-contrast/60 transition-colors hover:text-primary"
+          >
+            <Download size={16} aria-hidden="true" />
+          </a>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close document"
+            className="cursor-pointer rounded-inner p-1.5 text-base-contrast/60 transition-colors hover:text-primary"
+          >
+            <X size={16} aria-hidden="true" />
+          </button>
+        </div>
+      </div>
+
+      {state === "error" ? (
+        <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-3 p-6 text-center">
+          <p className="text-sm text-base-contrast">Couldn't load document.</p>
+          <button
+            type="button"
+            onClick={() => setAttempt((n) => n + 1)}
+            className="cursor-pointer rounded-inner border border-base-200 px-3 py-1.5 text-sm text-base-contrast transition-colors hover:text-primary"
+          >
+            Retry
+          </button>
+        </div>
+      ) : (
+        <iframe
+          key={attempt}
+          ref={frameRef}
+          // PDF open-parameters hide the native viewer's toolbar/side panel in
+          // Chromium so the pane's own top bar is the only chrome; Firefox and
+          // Safari ignore them harmlessly. A client-side fragment: it survives
+          // the gated route's 302 and works on pre-save blob: URLs too.
+          src={doc.kind === "pdf" ? `${doc.url}#toolbar=0&navpanes=0` : doc.url}
+          title={doc.title}
+          // Opaque origin for authored HTML: no portal cookies, storage or
+          // parent DOM. The ATTRIBUTE applies regardless of origin, so
+          // containment survives the bucket tier's 302 to a presigned R2 GET,
+          // where no CSP header comes back. PDFs get the browser's native
+          // viewer, which a sandbox would break.
+          sandbox={doc.kind === "html" ? "allow-scripts" : undefined}
+          onLoad={() => setState("ready")}
+          className="min-h-0 w-full flex-1 border-0 bg-base"
+        />
+      )}
+    </div>
+  );
+}

package/src/components/docfile/doc-file-state.ts

@@ -0,0 +1,208 @@
+import type { SiteDocument } from "../../lib/documents";
+import { createEvent } from "../../lib/events";
+
+/** Toggled on <html> while a document is open (the chat's class mechanism). */
+export const DOC_OPEN_CLASS = "bp-doc-open";
+
+/** Held on <html> for a beat after close. bp-doc-open's `transition: left`
+ *  rule leaves WITH the class, so without this the nav sidebar snaps home
+ *  instead of gliding back the way it glided out — this class carries the
+ *  same transition while the sidebar makes the return trip. */
+export const DOC_CLOSING_CLASS = "bp-doc-closing";
+
+/** Slightly longer than the 300ms CSS ease so the class outlives the glide. */
+const DOC_CLOSING_MS = 350;
+
+/** The one breakpoint the doc feature keys off: at or above it the overlay
+ *  gets the desktop stage; below it a PDF goes to the OS viewer instead (iOS
+ *  Safari cannot scroll an iframed PDF, Android Chrome forces a download).
+ *  1024px — the SAME breakpoint as U5's desktop CSS block and the width where
+ *  the nav sidebar exists at all. Deliberately NOT the chat's 768px dock query:
+ *  keying JS at 768 while the pane's desktop rules start at 1024 would give
+ *  768–1023px viewers framed PDFs inside the mobile pane geometry, under a
+ *  docked chat. */
+export const DOC_DESKTOP_QUERY = "(min-width: 1024px)";
+
+/** Cross-island open request. Islands that would rather not import this module
+ *  can dispatch it instead; applying an already-current value is a no-op, so
+ *  the dispatch-listen pair cannot loop. */
+export const docFileOpenEvent = createEvent<{ sectionId: string | null }>("bp-doc-file-open");
+
+interface DocFileStore {
+  open: string | null;
+  /** null = not seeded yet. Distinct from [] (seeded, no documents) — a row
+   *  that hydrates before the overlay must not flash "file missing". */
+  docs: SiteDocument[] | null;
+  openListeners: Set<(id: string | null) => void>;
+  docsListeners: Set<(docs: SiteDocument[] | null) => void>;
+  teardown: (() => void) | null;
+  closingTimer: ReturnType<typeof setTimeout> | null;
+}
+
+// Symbol-keyed on globalThis for the same reason the section registry is: the
+// bundler may hand two islands two copies of this module, and a split store
+// would let the nav open a document the overlay never hears about.
+const STORE_KEY = Symbol.for("@drawnagency/primitives/doc-file-state");
+const g = globalThis as unknown as Record<symbol, DocFileStore | undefined>;
+
+function store(): DocFileStore {
+  let s = g[STORE_KEY];
+  if (!s) {
+    s = { open: null, docs: null, openListeners: new Set(), docsListeners: new Set(), teardown: null, closingTimer: null };
+    g[STORE_KEY] = s;
+  }
+  return s;
+}
+
+export function isDocDesktop(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return true;
+  return window.matchMedia(DOC_DESKTOP_QUERY).matches;
+}
+
+function readHash(): string | null {
+  if (typeof window === "undefined") return null;
+  const match = /^#doc=(.+)$/.exec(window.location.hash);
+  if (!match) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+function apply(sectionId: string | null): void {
+  const s = store();
+  if (s.open === sectionId) return;
+  const wasOpen = s.open !== null;
+  s.open = sectionId;
+  if (typeof document !== "undefined") {
+    const root = document.documentElement;
+    root.classList.toggle(DOC_OPEN_CLASS, sectionId !== null);
+    // A reopen during the return glide cancels the closing state outright.
+    if (s.closingTimer !== null) {
+      clearTimeout(s.closingTimer);
+      s.closingTimer = null;
+      root.classList.remove(DOC_CLOSING_CLASS);
+    }
+    if (sectionId === null && wasOpen) {
+      root.classList.add(DOC_CLOSING_CLASS);
+      s.closingTimer = setTimeout(() => {
+        root.classList.remove(DOC_CLOSING_CLASS);
+        s.closingTimer = null;
+      }, DOC_CLOSING_MS);
+    }
+  }
+  for (const listener of [...s.openListeners]) listener(sectionId);
+}
+
+function syncFromHash(): void {
+  const next = readHash();
+  // "Ignores hash writes that still contain its own value" — a same-value
+  // write (e.g. a repeated nav click on the already-open document) must not
+  // re-notify. NOTE the one hash writer that CAN silently stomp #doc is a nav
+  // HEADING click (useActiveHeadings' setActiveSection does a replaceState —
+  // click-driven, not scroll-driven, so the scroll lock does not prevent it);
+  // U3 closes the overlay in handleHeadingNav before that write happens.
+  if (next === store().open) return;
+  apply(next);
+}
+
+export function openDocFile(sectionId: string): void {
+  if (typeof window !== "undefined") {
+    const hash = `#doc=${encodeURIComponent(sectionId)}`;
+    if (window.location.hash !== hash) {
+      // pushState so Back closes the overlay. It fires no hashchange, which is
+      // why the atom — not the hash — is the store.
+      window.history.pushState(null, "", hash);
+    }
+  }
+  apply(sectionId);
+  docFileOpenEvent.dispatch({ sectionId });
+}
+
+export function closeDocFile(): void {
+  if (typeof window !== "undefined" && readHash() !== null) {
+    // replaceState, never history.back(): back() races the editor's own
+    // pushState in goToPage and is unobservable in jsdom. The cost is that Back
+    // after a manual close returns to an identical URL — invisible to the user.
+    const { pathname, search } = window.location;
+    window.history.replaceState(null, "", `${pathname}${search}`);
+  }
+  apply(null);
+  docFileOpenEvent.dispatch({ sectionId: null });
+}
+
+export function getOpenDocFile(): string | null {
+  return store().open;
+}
+
+export function subscribeDocFile(cb: (sectionId: string | null) => void): () => void {
+  const s = store();
+  s.openListeners.add(cb);
+  if (!s.teardown && typeof window !== "undefined") {
+    const onHash = () => syncFromHash();
+    const onPop = () => syncFromHash();
+    const onRequest = (detail: { sectionId: string | null }) => {
+      // The already-current check must come FIRST and cover null too: this
+      // listener also hears the event openDocFile/closeDocFile dispatch
+      // themselves, and an unguarded close would re-close → re-dispatch →
+      // recurse until the stack blew (jsdom swallows listener throws, so the
+      // suite only surfaced it as an unhandled RangeError).
+      if (detail.sectionId === s.open) return;
+      if (detail.sectionId === null) closeDocFile();
+      else openDocFile(detail.sectionId);
+    };
+    window.addEventListener("hashchange", onHash);
+    window.addEventListener("popstate", onPop);
+    const unlistenRequest = docFileOpenEvent.listen(onRequest);
+    s.teardown = () => {
+      window.removeEventListener("hashchange", onHash);
+      window.removeEventListener("popstate", onPop);
+      unlistenRequest();
+    };
+    // Deep link: the hash is an INPUT, read once when the first listener wires up.
+    syncFromHash();
+  }
+  return () => {
+    s.openListeners.delete(cb);
+    if (s.openListeners.size === 0 && s.teardown) {
+      s.teardown();
+      s.teardown = null;
+    }
+  };
+}
+
+/** Authoritative publish — the editor's live draft list. */
+export function setSiteDocuments(docs: SiteDocument[]): void {
+  const s = store();
+  s.docs = docs;
+  for (const listener of [...s.docsListeners]) listener(docs);
+}
+
+/** First-writer-wins publish for the SSR-derived list, so an island that mounts
+ *  after the editor has already published cannot clobber the live list. */
+export function seedSiteDocuments(docs: SiteDocument[]): void {
+  if (store().docs !== null) return;
+  setSiteDocuments(docs);
+}
+
+export function getSiteDocuments(): SiteDocument[] | null {
+  return store().docs;
+}
+
+export function subscribeSiteDocuments(cb: (docs: SiteDocument[] | null) => void): () => void {
+  const s = store();
+  s.docsListeners.add(cb);
+  return () => { s.docsListeners.delete(cb); };
+}
+
+/** Test-only: drop the store and any window wiring (mirrors clearRegistry). */
+export function resetDocFileState(): void {
+  const s = g[STORE_KEY];
+  if (s?.teardown) s.teardown();
+  if (s?.closingTimer) clearTimeout(s.closingTimer);
+  if (typeof document !== "undefined") {
+    document.documentElement.classList.remove(DOC_OPEN_CLASS, DOC_CLOSING_CLASS);
+  }
+  g[STORE_KEY] = undefined;
+}

package/src/components/editor/SettingsForm.tsx

@@ -6,6 +6,7 @@ import { Checkbox } from "../shared/Checkbox";
 import { FormLabel } from "../shared/FormLabel";
 import { LinkField } from "../shared/LinkField";
 import { VideoSourceField } from "../shared/VideoSourceField";
+import { DocumentSourceField, type DocumentRef } from "../shared/DocumentSourceField";
 import { Tabs } from "../shared/Tabs";
 import type { LinkValue } from "../../schemas/link";
 import type { VideoSource } from "../sections/Video/VideoBlock";
@@ -174,6 +175,15 @@ function renderField(
         />
       );
 
+    case "document-source":
+      return (
+        <DocumentSourceField
+          key={key}
+          value={value as DocumentRef | undefined}
+          onChange={(v) => handleFieldChange(key, v)}
+        />
+      );
+
     default:
       return null;
   }