@drawnagency/primitives 0.1.99 → 0.1.100

package/dist/lib/save-chunks.d.ts

@@ -25,4 +25,19 @@ export interface PackedUploads {
  *  for the caller to reject with a per-file error. Items are never split
  *  across chunks (the manifest may only reference fully-committed items). */
 export declare function packUploads(uploads: MediaUploadPayload[], budget?: number): PackedUploads;
+export interface DocumentUploadPayload {
+    id: string;
+    path: string;
+    base64: string;
+}
+/** Approximate serialized size of one document upload — base64 dominates; the
+ *  allowance covers JSON keys, quoting, and the manifest entry riding along. */
+export declare function documentUploadSizeBytes(upload: DocumentUploadPayload): number;
+/** Greedy in-order packing of document uploads. A 2.5MiB document base64s to
+ *  ~3.4MB, so two never share a request — hence chunking rather than one blob
+ *  request. Documents are never packed with sections/index. */
+export declare function packDocumentUploads(uploads: DocumentUploadPayload[], budget?: number): {
+    chunks: DocumentUploadPayload[][];
+    oversized: DocumentUploadPayload[];
+};
 //# sourceMappingURL=save-chunks.d.ts.map

package/dist/lib/save-chunks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"save-chunks.d.ts","sourceRoot":"","sources":["../../src/lib/save-chunks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAkB,CAAC;AAEvD;6EAC6E;AAC7E,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,kBAAkB,EAAE,EAAE,CAAC;IAC/B,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;;6EAG6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,MAAM,SAA0B,GAAG,aAAa,CAsB1G"}
+{"version":3,"file":"save-chunks.d.ts","sourceRoot":"","sources":["../../src/lib/save-chunks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAkB,CAAC;AAEvD;6EAC6E;AAC7E,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,kBAAkB,EAAE,EAAE,CAAC;IAC/B,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;;6EAG6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,MAAM,SAA0B,GAAG,aAAa,CAsB1G;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;gFACgF;AAChF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAE7E;AAED;;+DAE+D;AAC/D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,qBAAqB,EAAE,EAChC,MAAM,SAA0B,GAC/B;IAAE,MAAM,EAAE,qBAAqB,EAAE,EAAE,CAAC;IAAC,SAAS,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAsB3E"}

package/dist/lib/scroll-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function lockBodyScroll(): () => void;
+//# sourceMappingURL=scroll-lock.d.ts.map

package/dist/lib/scroll-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-lock.d.ts","sourceRoot":"","sources":["../../src/lib/scroll-lock.ts"],"names":[],"mappings":"AAYA,wBAAgB,cAAc,IAAI,MAAM,IAAI,CAc3C"}

package/dist/schemas/documents.d.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+/**
+ * Document metadata lives in its OWN file, not in image-manifest.json.
+ *
+ * The image manifest is hard-`.parse`d on every page load across five routes,
+ * its remote-merge guard fails open on parse failure, and the authoring CLI
+ * parse-catch-WRITES it — so one entry a stale package version cannot
+ * represent means whole-site 500s or a wiped manifest. A sidecar is simply
+ * absent from an older writer's file list and survives untouched. Same
+ * structural answer as nav.json; do not "simplify" this back into either
+ * index.json or image-manifest.json.
+ */
+export declare const DOCUMENT_MANIFEST_PATH = "src/content/document-manifest.json";
+/**
+ * Git-tier cap. 2.5 MiB base64-encodes to ~3.4 MB, inside the 4 MB post-base64
+ * chunk budget with envelope headroom.
+ */
+export declare const DOCUMENT_GIT_MAX_BYTES = 2621440;
+/** Bucket-tier cap. Its lower bound is DOCUMENT_GIT_MAX_BYTES — no dead zone. */
+export declare const DOCUMENT_BUCKET_MAX_BYTES = 209715200;
+/**
+ * The only two accepted upload types, and the ONLY source of a document's file
+ * extension — never the media pipeline's `?? "bin"` fallback.
+ */
+export declare const DOCUMENT_MIME_TO_EXT: {
+    readonly "application/pdf": "pdf";
+    readonly "text/html": "html";
+};
+/** Reverse of DOCUMENT_MIME_TO_EXT, for setting Content-Type when serving. */
+export declare const DOCUMENT_KIND_TO_MIME: {
+    readonly pdf: "application/pdf";
+    readonly html: "text/html";
+};
+export declare const DocumentManifestEntrySchema: z.ZodObject<{
+    filename: z.ZodString;
+    size: z.ZodNumber;
+    kind: z.ZodEnum<{
+        pdf: "pdf";
+        html: "html";
+    }>;
+    storage: z.ZodEnum<{
+        git: "git";
+        bucket: "bucket";
+    }>;
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare const DocumentManifestSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    filename: z.ZodString;
+    size: z.ZodNumber;
+    kind: z.ZodEnum<{
+        pdf: "pdf";
+        html: "html";
+    }>;
+    storage: z.ZodEnum<{
+        git: "git";
+        bucket: "bucket";
+    }>;
+    path: z.ZodString;
+}, z.core.$strip>>;
+export type DocumentManifest = z.infer<typeof DocumentManifestSchema>;
+export type DocumentManifestEntry = z.infer<typeof DocumentManifestEntrySchema>;
+/**
+ * The gated URL for a document, at BOTH storage tiers. Single-sourced here so
+ * the section row, the overlay, the nav group and the tests cannot drift — a
+ * bucket-tier document is still fetched through this route, which authorizes
+ * the requester and only then 302s to a short-lived presigned GET.
+ */
+export declare function documentFileUrl(documentId: string, filename: string, opts?: {
+    download?: boolean;
+}): string;
+/** Git-tier repo path. `slugName` comes from sanitizeMediaName(file.name). */
+export declare function documentGitPath(slugName: string, hash: string, kind: "pdf" | "html"): string;
+/**
+ * Bucket-tier object key, SITE-RELATIVE — the store prepends the tenant prefix,
+ * so this is also the form stored in the manifest, matched by the delete
+ * broker's regex, and compared by the publish-time GC. The id is the 32-hex
+ * `documentId` minted by upload-intent, never the client's content hash.
+ */
+export declare function documentBucketPath(documentId: string, kind: "pdf" | "html"): string;
+//# sourceMappingURL=documents.d.ts.map

package/dist/schemas/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/schemas/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,uCAAuC,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAEhD,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,YAAc,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;CAGvB,CAAC;AAEX,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB;;;CAGxB,CAAC;AAEX,eAAO,MAAM,2BAA2B;;;;;;;;;;;;iBAOtC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;kBAAoD,CAAC;AAExF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,MAAM,CAGR;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAE5F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAEnF"}

package/dist/schemas/documents.js

@@ -0,0 +1,25 @@
+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 "../chunk-JSBRDJBE.js";
+export {
+  DOCUMENT_BUCKET_MAX_BYTES,
+  DOCUMENT_GIT_MAX_BYTES,
+  DOCUMENT_KIND_TO_MIME,
+  DOCUMENT_MANIFEST_PATH,
+  DOCUMENT_MIME_TO_EXT,
+  DocumentManifestEntrySchema,
+  DocumentManifestSchema,
+  documentBucketPath,
+  documentFileUrl,
+  documentGitPath
+};

package/dist/schemas/index.d.ts

@@ -7,4 +7,5 @@ export * from "./audience";
 export * from "./media-grid-options";
 export * from "./auth";
 export * from "./link";
+export * from "./documents";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}

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

@@ -131,4 +131,51 @@ 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
+ * no `getPublicUrl` here at all — every read is a short-lived signed GET,
+ * 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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawnagency/primitives",
-  "version": "0.1.99",
+  "version": "0.1.100",
   "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,129 @@
+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}
+          src={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>
+  );
+}