@drawnagency/primitives 0.1.99 → 0.1.101

package/src/lib/documents.ts

@@ -0,0 +1,138 @@
+import type { LoadedSection } from "./loader";
+import type { Section } from "../schemas/sections";
+import type { SiteIndex, SectionMeta } from "../schemas/site-config";
+import type { DocumentManifest } from "../schemas/documents";
+import { documentFileUrl } from "../schemas/documents";
+import { getContainerChildren } from "./container-ops";
+import { audiencePasses } from "./pages";
+
+// The gated URL has exactly ONE definition, in schemas/documents (S1). This is
+// a re-export so `@/lib/documents` consumers get it without a second spelling.
+export { documentFileUrl };
+
+/**
+ * One `document` section, joined against the document manifest and filtered to
+ * what THIS requester may see. Derived per request — never persisted, never
+ * written back into index.json or nav.json.
+ */
+export interface SiteDocument {
+  sectionId: string;
+  /** Manifest key. Carried so the overlay can build the ?download=1 URL with
+   *  documentFileUrl(), and so the editor can key a staged blob URL by id. */
+  documentId: string;
+  title: string;
+  filename: string;
+  size: number;
+  kind: "pdf" | "html";
+  /** The auth-gated route. Append `?download=1` for an attachment response. */
+  url: string;
+  /** Mirrors content.showInDocumentsNav — generateSiteNav filters on it, while
+   *  the overlay and the rows need the unfiltered list (an unflagged document
+   *  is still openable from its own row). */
+  showInDocumentsNav: boolean;
+}
+
+interface DocumentSectionContent {
+  title?: string;
+  doc?: { documentId?: string };
+  showInDocumentsNav?: boolean;
+}
+
+/**
+ * Filename without its extension. The document row and the overlay's top bar
+ * render `content.title || filenameStem(entry.filename)` — a DISPLAY fallback,
+ * not a write. (SettingsForm.handleFieldChange is per-key and cannot set a
+ * sibling field, so "auto-fill title on pick" would need cross-field machinery
+ * for the same visible result.)
+ */
+export function filenameStem(filename: string): string {
+  const dot = filename.lastIndexOf(".");
+  return dot > 0 ? filename.slice(0, dot) : filename;
+}
+
+/** Compact byte size for the row's `filename · size` line. */
+export function formatDocSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value >= 100 ? Math.round(value) : Number(value.toFixed(1))} ${units[unit]}`;
+}
+
+/**
+ * Every document the requester may see, in page order.
+ *
+ * Viewer mode mirrors viewer-page.ts exactly: the owning page must be live and
+ * audience-passing, AND the section's own meta must be live and audience-
+ * passing. Editors see everything on the draft. A document with no manifest
+ * entry is excluded in BOTH modes — there are no bytes to serve and no
+ * filename/size to render; the editor's row derives its "file missing" state
+ * from that absence.
+ *
+ * Documents nested one level inside a container count too, and are emitted right
+ * after their container's own position. A child has no meta of its own and never
+ * appears in `page.order`, so both gates read the PARENT's meta and the PARENT's
+ * page; the emitted `sectionId` is the CHILD's — that is what `DocumentRow`
+ * matches and what `#doc=` deep links carry. Depth 1 only: `MAX_BLOCK_DEPTH`
+ * makes anything deeper unrepresentable on write and on load.
+ *
+ * This is one half of a documented mirror. `referencedByVisibleSection` (the
+ * gated file route) applies the same gates with the same recursion — change one,
+ * change the other, or a document becomes listable but unservable (or worse).
+ */
+export function deriveSiteDocuments(opts: {
+  index: SiteIndex;
+  sections: LoadedSection[];
+  manifest: DocumentManifest;
+  mode: "viewer" | "editor";
+  audience: string | null;
+}): SiteDocument[] {
+  const { index, sections, manifest, mode, audience } = opts;
+
+  const pageBySectionId = new Map<string, SiteIndex["pages"][number]>();
+  for (const page of index.pages) for (const id of page.order) pageBySectionId.set(id, page);
+
+  const out: SiteDocument[] = [];
+  const seen = new Set<string>();
+
+  /** `candidate` supplies the id and the body; `owner` (itself, or the container
+   *  it sits in) supplies the meta and the page. */
+  const consider = (candidate: Section, ownerId: string, meta: SectionMeta) => {
+    if (candidate.type !== "document" || !candidate.id) return;
+    const content = candidate.content as DocumentSectionContent;
+    const documentId = content.doc?.documentId ?? "";
+    const entry = documentId ? manifest[documentId] : undefined;
+    if (!entry) return;
+
+    if (mode === "viewer") {
+      const page = pageBySectionId.get(ownerId);
+      if (!page || page.status !== "live" || !audiencePasses(page.access, audience)) return;
+      if (meta.status !== "live" || !audiencePasses(meta.access, audience)) return;
+    }
+
+    if (seen.has(candidate.id)) return;
+    seen.add(candidate.id);
+
+    out.push({
+      sectionId: candidate.id,
+      documentId,
+      title: content.title?.trim() || filenameStem(entry.filename),
+      filename: entry.filename,
+      size: entry.size,
+      kind: entry.kind,
+      url: documentFileUrl(documentId, entry.filename),
+      showInDocumentsNav: content.showInDocumentsNav !== false,
+    });
+  };
+
+  for (const { section, meta } of sections) {
+    consider(section, section.id, meta);
+    for (const child of getContainerChildren(section)) consider(child, section.id, meta);
+  }
+  return out;
+}

package/src/lib/media-folders.ts

@@ -13,6 +13,15 @@ export interface FolderUploadPlan {
   fileTargets: { file: File; folderId: string | null }[];
 }
 
+/**
+ * The library's Documents pseudo-folder. UI-only: it is NEVER a `folders` entry
+ * (they round-trip to disk verbatim, and no MediaItem can point at it), so
+ * every `currentFolderId` consumer that reads `folders` must special-case it.
+ * Cannot collide with a real `f_`-prefixed id; distinct from the nav's
+ * `__documents__` group id.
+ */
+export const DOCUMENTS_FOLDER_ID = "__documents-folder__";
+
 /** Display-folder id. NOT related to MediaItem.folder (the git storage dir). */
 export function createFolderId(): string {
   const bytes = new Uint8Array(6);

package/src/lib/nav.ts

@@ -3,6 +3,7 @@ import { getSection, type SectionRegistry } from "./registry";
 import { audiencePasses, homePage, pageDisplayTitle } from "./pages";
 import { navEntries } from "./nav-tree";
 import type { SiteIndex } from "../schemas/site-config";
+import type { SiteDocument } from "./documents";
 
 export interface NavItem {
   href: string;
@@ -102,7 +103,30 @@ export interface GroupNavItem {
   pages: PageNavItem[];
 }
 
-export type SiteNavEntry = ({ kind: "page" } & PageNavItem) | GroupNavItem;
+/** A launcher entry for one document section. NOT a PageNavItem: the editor's
+ *  page rendering turns hrefs into pageSelectEvent buttons, which would
+ *  dead-end here. */
+export interface DocNavItem {
+  kind: "doc";
+  sectionId: string;
+  title: string;
+  url: string;
+}
+
+/** The synthetic, never-persisted "Documents" group. GroupNavItem.pages is
+ *  PageNavItem[], so the doc group is its own entry kind rather than a reuse. */
+export interface DocGroupNavItem {
+  kind: "doc-group";
+  id: string;
+  label: string;
+  docs: DocNavItem[];
+}
+
+/** Id of the synthetic group. Generated page-group ids never collide with it,
+ *  and it is never written to nav.json. */
+export const DOCUMENTS_GROUP_ID = "__documents__";
+
+export type SiteNavEntry = ({ kind: "page" } & PageNavItem) | GroupNavItem | DocGroupNavItem;
 
 export interface SiteNav {
   /** The authored tree: loose pages and groups, in nav order. */
@@ -123,8 +147,15 @@ export function generateSiteNav(opts: {
   mode: "viewer" | "editor";
   audience: string | null;
   registry?: SectionRegistry;
+  /** Pre-derived and already requester-filtered (deriveSiteDocuments). This
+   *  function cannot see SITE-WIDE section content — activeSections carries at
+   *  most the current page's sections, and EditorShell's two history call
+   *  sites pass activeSections: [] outright — so the list is always supplied
+   *  by the caller. Callers without one (history views) pass nothing and
+   *  render no group. */
+  documents?: SiteDocument[];
 }): SiteNav {
-  const { index, activeSections, activePageId, mode, audience, registry } = opts;
+  const { index, activeSections, activePageId, mode, audience, registry, documents } = opts;
   const active = activePageId ?? homePage(index).id;
   const byId = new Map(index.pages.map((p) => [p.id, p]));
 
@@ -163,6 +194,19 @@ export function generateSiteNav(opts: {
     });
   }
 
+  // Derived, never persisted: the Documents group lives only in this view model,
+  // so nav.json is never written, reconcileNav never sees it, and the Pages
+  // modal's positional drag indexing is untouched.
+  const navDocs = (documents ?? []).filter((d) => d.showInDocumentsNav);
+  if (navDocs.length > 0) {
+    entries.push({
+      kind: "doc-group",
+      id: DOCUMENTS_GROUP_ID,
+      label: "Documents",
+      docs: navDocs.map((d) => ({ kind: "doc" as const, sectionId: d.sectionId, title: d.title, url: d.url })),
+    });
+  }
+
   if (mode === "editor") {
     return {
       entries,

package/src/lib/platform-broker.ts

@@ -7,6 +7,21 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * A broker call that reached apps/admin and got a non-2xx back. The `status` is
+ * carried so callers can distinguish a MISSING endpoint (404/405/501 — the
+ * stale-admin window, where the client site has been upgraded ahead of the
+ * platform) from a real auth or config failure. Without it every such case
+ * surfaces as an opaque 500 the editor cannot act on. `status` is null when the
+ * request never got a response at all.
+ */
+export class PlatformBrokerError extends Error {
+  constructor(public readonly status: number | null, message: string) {
+    super(message);
+    this.name = "PlatformBrokerError";
+  }
+}
+
 /** True when this runtime should broker privileged ops through the platform. */
 export function isPlatformMode(): boolean {
   return Boolean(env("PLATFORM_API_URL") && env("PLATFORM_API_KEY"));
@@ -60,15 +75,15 @@ export async function platformBroker<T = unknown>(
     }
 
     if (res.status >= 500 && !isLast) {
-      lastError = new Error(`Platform broker error (${res.status})`);
+      lastError = new PlatformBrokerError(res.status, `Platform broker error (${res.status})`);
       await sleep(RETRY_BASE_MS * 2 ** attempt);
       continue;
     }
 
-    throw new Error(`Platform broker error (${res.status}): ${await res.text()}`);
+    throw new PlatformBrokerError(res.status, `Platform broker error (${res.status}): ${await res.text()}`);
   }
 
-  throw lastError instanceof Error ? lastError : new Error("Platform broker unreachable");
+  throw lastError instanceof Error ? lastError : new PlatformBrokerError(null, "Platform broker unreachable");
 }
 
 /**

package/src/lib/registry.ts

@@ -62,6 +62,15 @@ export type SettingsFieldDef =
       label: string;
       default: VideoSource;
       target?: "content" | "options";
+    }
+  | {
+      /** Opens the media library filtered to documents (PDF/HTML). The renderer
+       *  lives in SettingsForm; an unrendered kind falls through its `default`
+       *  arm, so this type can land ahead of the field component. */
+      type: "document-source";
+      label: string;
+      default: { documentId: string };
+      target?: "content" | "options";
     };
 
 export type SettingsSchema = Record<string, SettingsFieldDef>;

package/src/lib/save-chunks.ts

@@ -51,3 +51,45 @@ export function packUploads(uploads: MediaUploadPayload[], budget = SAVE_CHUNK_B
   if (current.length > 0) chunks.push(current);
   return { chunks, oversized };
 }
+
+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 function documentUploadSizeBytes(upload: DocumentUploadPayload): number {
+  return upload.base64.length + upload.path.length + 576;
+}
+
+/** 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 function packDocumentUploads(
+  uploads: DocumentUploadPayload[],
+  budget = SAVE_CHUNK_BUDGET_BYTES,
+): { chunks: DocumentUploadPayload[][]; oversized: DocumentUploadPayload[] } {
+  const chunks: DocumentUploadPayload[][] = [];
+  const oversized: DocumentUploadPayload[] = [];
+  let current: DocumentUploadPayload[] = [];
+  let currentBytes = 0;
+
+  for (const upload of uploads) {
+    const size = documentUploadSizeBytes(upload);
+    if (size > budget) {
+      oversized.push(upload);
+      continue;
+    }
+    if (current.length > 0 && currentBytes + size > budget) {
+      chunks.push(current);
+      current = [];
+      currentBytes = 0;
+    }
+    current.push(upload);
+    currentBytes += size;
+  }
+  if (current.length > 0) chunks.push(current);
+  return { chunks, oversized };
+}

package/src/lib/scroll-lock.ts

@@ -0,0 +1,27 @@
+/**
+ * Refcounted body-scroll lock.
+ *
+ * EditorModal and ChatPanel each save/restore `body.style.overflow` themselves,
+ * which collides when two lockers overlap — the first to release restores
+ * "hidden" as if it were the resting value, or unlocks the page under a still-
+ * open surface. The doc overlay and the mobile chat sheet CAN be open at the
+ * same time, so this one counts.
+ */
+let depth = 0;
+let previousOverflow = "";
+
+export function lockBodyScroll(): () => void {
+  if (typeof document === "undefined") return () => {};
+  if (depth === 0) {
+    previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+  }
+  depth++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    depth--;
+    if (depth === 0) document.body.style.overflow = previousOverflow;
+  };
+}

package/src/schemas/documents.ts

@@ -0,0 +1,82 @@
+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 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 const DOCUMENT_GIT_MAX_BYTES = 2_621_440;
+
+/** Bucket-tier cap. Its lower bound is DOCUMENT_GIT_MAX_BYTES — no dead zone. */
+export const DOCUMENT_BUCKET_MAX_BYTES = 209_715_200;
+
+/**
+ * The only two accepted upload types, and the ONLY source of a document's file
+ * extension — never the media pipeline's `?? "bin"` fallback.
+ */
+export const DOCUMENT_MIME_TO_EXT = {
+  "application/pdf": "pdf",
+  "text/html": "html",
+} as const;
+
+/** Reverse of DOCUMENT_MIME_TO_EXT, for setting Content-Type when serving. */
+export const DOCUMENT_KIND_TO_MIME = {
+  pdf: "application/pdf",
+  html: "text/html",
+} as const;
+
+export const DocumentManifestEntrySchema = z.object({
+  filename: z.string(),
+  size: z.number().int().positive(),
+  kind: z.enum(["pdf", "html"]),
+  storage: z.enum(["git", "bucket"]),
+  /** git: repo path under assets/documents/…; bucket: site-relative object key. */
+  path: z.string(),
+});
+
+export const DocumentManifestSchema = z.record(z.string(), DocumentManifestEntrySchema);
+
+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 function documentFileUrl(
+  documentId: string,
+  filename: string,
+  opts: { download?: boolean } = {},
+): string {
+  const base = `/api/document-file/${documentId}/${encodeURIComponent(filename)}`;
+  return opts.download ? `${base}?download=1` : base;
+}
+
+/** Git-tier repo path. `slugName` comes from sanitizeMediaName(file.name). */
+export function documentGitPath(slugName: string, hash: string, kind: "pdf" | "html"): string {
+  return `assets/documents/${slugName}-${hash}/original.${kind}`;
+}
+
+/**
+ * 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 function documentBucketPath(documentId: string, kind: "pdf" | "html"): string {
+  return `documents/${documentId}/original.${kind}`;
+}

package/src/schemas/index.ts

@@ -7,3 +7,4 @@ export * from "./audience";
 export * from "./media-grid-options";
 export * from "./auth";
 export * from "./link";
+export * from "./documents";

package/src/storage/index.ts

@@ -1,2 +1,2 @@
-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";

package/src/storage/types.ts

@@ -135,19 +135,73 @@ export 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<{ uploadUrl: string; 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<{ path: string; size: number; 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 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 }>>;
+}