@drawnagency/primitives 0.1.99 → 0.1.100

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

@@ -151,3 +151,49 @@ export interface AssetStore {
   /** 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
+ * 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 }>>;
+}