@drawnagency/primitives 0.1.80 → 0.1.81

package/src/document/components/useDocPages.ts

@@ -0,0 +1,67 @@
+import { useMemo } from "react";
+import { harvest } from "../engine/harvest";
+import { paginateChunk, type DerivedPage } from "../engine/paginate";
+import { settingsFor, type SectionSettings } from "../engine/settings";
+import type { Chunk, DocSourceContent } from "../engine/types";
+import { useTextMeasurements } from "./measure";
+
+export function useDocPages(input: {
+  source: DocSourceContent | null;
+  sections: Record<string, unknown>;
+}): { chunks: Chunk[]; pages: DerivedPage[]; measuring: boolean; warningsByChunk: Record<string, string[]> } {
+  const { source, sections } = input;
+
+  const chunks = useMemo(
+    () => (source ? harvest(source.sections, source.pageTitle, source.images) : []),
+    [source],
+  );
+
+  const settingsMap = useMemo(() => {
+    const map: Record<string, SectionSettings> = {};
+    for (const c of chunks) map[c.id] = settingsFor(sections, c.id);
+    return map;
+  }, [chunks, sections]);
+
+  const { heights } = useTextMeasurements(chunks, settingsMap);
+
+  // `heights` is state set by an effect, so it always lags one render behind
+  // `chunks`: when `source` changes shape (a block added/removed, a new
+  // section), this memo can run with heights measured for the PREVIOUS chunk
+  // shape. Calling paginateChunk with a stale (mismatched-length) heights
+  // array is its documented throw condition, so each chunk is guarded
+  // independently — a chunk whose current heights aren't in yet contributes
+  // no pages (rather than crash) until the measurement effect catches up.
+  // Zero-text chunks have nothing to measure, so they always paginate.
+  const pages = useMemo(() => {
+    return chunks.flatMap((c) => {
+      const h = heights?.[c.id];
+      if (c.textBlocks.length > 0 && (!h || h.length !== c.textBlocks.length)) return [];
+      return paginateChunk(c, settingsMap[c.id], h ?? []);
+    });
+  }, [chunks, settingsMap, heights]);
+
+  // Mirrors the pages memo's per-chunk guard: still "measuring" until every
+  // non-empty chunk has current heights, not just until `heights` is non-null.
+  const measuring = useMemo(
+    () =>
+      chunks.some((c) => {
+        if (c.textBlocks.length === 0) return false;
+        const h = heights?.[c.id];
+        return !h || h.length !== c.textBlocks.length;
+      }),
+    [chunks, heights],
+  );
+
+  const warningsByChunk = useMemo(() => {
+    const map: Record<string, string[]> = {};
+    for (const c of chunks) {
+      const noContent = c.textBlocks.length === 0 && c.images.length === 0;
+      const pageWarnings = pages.filter((p) => p.chunkId === c.id).flatMap((p) => p.warnings);
+      const warnings = noContent ? ["Section has no content", ...pageWarnings] : pageWarnings;
+      if (warnings.length > 0) map[c.id] = warnings;
+    }
+    return map;
+  }, [chunks, pages]);
+
+  return { chunks, pages, measuring, warningsByChunk };
+}

package/src/document/engine/blocks.ts

@@ -0,0 +1,87 @@
+// Elements that are never allowed to survive into rendered output, wherever
+// they occur (top-level or nested).
+const DISALLOWED_TAGS = new Set([
+  "script",
+  "style",
+  "iframe",
+  "object",
+  "embed",
+  "link",
+  "meta",
+  "base",
+  "form",
+  // Raw-text / escapable-raw-text and declarative elements whose contents are
+  // not parsed as normal markup. Left in place they enable serialize/reparse
+  // (mXSS) bypasses — e.g. an <img onerror> smuggled inside <noscript> text.
+  // Removing the element drops its contents too (including <template> content).
+  "noscript",
+  "xmp",
+  "noembed",
+  "noframes",
+  "plaintext",
+  "template",
+]);
+const DISALLOWED_SELECTOR = Array.from(DISALLOWED_TAGS).join(",");
+
+// Attributes that can carry a URL and therefore need scheme scrutiny.
+const URL_ATTRS = new Set(["href", "src", "xlink:href", "formaction"]);
+
+function isDangerousUrl(attrName: string, rawValue: string): boolean {
+  // Browsers strip ASCII tab/CR/LF anywhere in a URL (and ignore leading
+  // controls) before resolving its scheme, so "jav\tascript:" runs like
+  // "javascript:". Over-stripping here only makes the check more conservative.
+  const value = rawValue.toLowerCase().replace(/[\u0000-\u0020]/g, "");
+  if (value.startsWith("javascript:") || value.startsWith("vbscript:")) return true;
+  if (attrName === "src" && value.startsWith("data:text/html")) return true;
+  return false;
+}
+
+// Defense-in-depth scrub applied at the dangerouslySetInnerHTML/innerHTML
+// boundary. Upstream portal content is sanitized at authoring time, but
+// /print runs in an authed headless browser, so this engine (kept
+// dependency-free — no DOMPurify) removes known-dangerous elements and
+// attributes from the DOM it already parsed, in place.
+function scrubElement(root: Element): void {
+  root.querySelectorAll(DISALLOWED_SELECTOR).forEach((el) => el.remove());
+
+  const elements: Element[] = [root, ...Array.from(root.querySelectorAll("*"))];
+  for (const el of elements) {
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on") || name === "srcdoc") {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+      if (URL_ATTRS.has(name) && isDangerousUrl(name, attr.value)) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+}
+
+// Split sanitized rich-text HTML into atomic top-level blocks. Pagination
+// never splits inside a block — a block that doesn't fit moves wholesale to
+// the next page (spec: "pagination by block measurement").
+export function splitProseBlocks(html: string): string[] {
+  if (!html.trim()) return [];
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const blocks: string[] = [];
+  for (const node of Array.from(doc.body.childNodes)) {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      const el = node as Element;
+      if (DISALLOWED_TAGS.has(el.tagName.toLowerCase())) continue;
+      scrubElement(el);
+      if ((el.textContent ?? "").trim() || el.matches("img") || el.querySelector("img")) {
+        blocks.push(el.outerHTML);
+      }
+    } else if (node.nodeType === Node.TEXT_NODE) {
+      const text = (node.textContent ?? "").trim();
+      if (text) {
+        const p = doc.createElement("p");
+        p.textContent = text;
+        blocks.push(p.outerHTML);
+      }
+    }
+  }
+  return blocks;
+}

package/src/document/engine/harvest.ts

@@ -0,0 +1,80 @@
+import { splitProseBlocks } from "./blocks";
+import { PREAMBLE_ID, type Chunk, type DocImage, type DocSectionInput } from "./types";
+
+// Shape of the fields harvest reads, checked structurally at runtime — the
+// engine must tolerate any future portal section without crashing (allowlist).
+type Loose = Record<string, unknown>;
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+// Normalizes any runtime value (including null/undefined from malformed
+// portal data) into a safe-to-index object so field access never throws.
+function asRecord(v: unknown): Loose {
+  return v && typeof v === "object" ? (v as Loose) : {};
+}
+
+// One section's contribution to the current chunk (containers recurse).
+function harvestInto(
+  target: Chunk,
+  type: string,
+  content: unknown,
+  imagesById: Record<string, DocImage>,
+): void {
+  const c = asRecord(content);
+  switch (type) {
+    case "sub_heading":
+    case "link_heading": // nested (inside a container) — not a boundary here
+      target.textBlocks.push({ kind: "heading", level: 2, text: str(c.heading) });
+      break;
+    case "sub_sub_heading":
+      target.textBlocks.push({ kind: "heading", level: 3, text: str(c.heading) });
+      break;
+    case "prose":
+      for (const html of splitProseBlocks(str(c.body))) {
+        target.textBlocks.push({ kind: "prose", html });
+      }
+      break;
+    case "media": {
+      const ref = asRecord(c.ref);
+      const image = imagesById[str(ref.imageId)];
+      if (image) target.images.push(image);
+      break;
+    }
+    case "container": {
+      const children = Array.isArray(c.children) ? c.children : [];
+      for (const child of children) {
+        const cc = asRecord(child);
+        if (typeof cc.type === "string") {
+          harvestInto(target, cc.type, cc.content, imagesById);
+        }
+      }
+      break;
+    }
+    default:
+      break; // allowlist: video, button, spacer, colors, do/dont, icon list, unknown future types
+  }
+}
+
+export function harvest(
+  sections: DocSectionInput[],
+  pageTitle: string,
+  imagesById: Record<string, DocImage>,
+): Chunk[] {
+  const chunks: Chunk[] = [];
+  let current: Chunk = { id: PREAMBLE_ID, title: pageTitle, textBlocks: [], images: [] };
+  let preamble = current;
+
+  for (const section of sections) {
+    if (section.type === "link_heading") {
+      current = { id: section.id, title: str(asRecord(section.content).heading), textBlocks: [], images: [] };
+      chunks.push(current);
+    } else {
+      harvestInto(current, section.type, section.content, imagesById);
+    }
+  }
+
+  const preambleHasContent = preamble.textBlocks.length > 0 || preamble.images.length > 0;
+  return preambleHasContent ? [preamble, ...chunks] : chunks;
+}

package/src/document/engine/masonry.ts

@@ -0,0 +1,89 @@
+const EPS = 1e-6;
+
+export type MasonryMode = "rows" | "columns";
+
+export type Sized = { width: number; height: number };
+
+export interface MasonryOpts {
+  mode: MasonryMode;
+  columns: 2 | 3 | 4 | 5 | 6;
+  bodyWIn: number;
+  bodyHIn: number;
+  gapIn: number;
+  targetRowHeightIn: number;
+}
+
+export interface MasonryBox<T extends Sized = Sized> {
+  asset: T;
+  xIn: number;
+  yIn: number;
+  wIn: number;
+  hIn: number;
+}
+
+// A "cover" photo is laid out in a SQUARE cell (effective aspect 1) and the
+// image crops to fill it; "contain" (default) uses the photo's natural aspect.
+const effectiveAspect = (im: Sized, fit: "cover" | "contain" | undefined) =>
+  fit === "cover" ? 1 : im.width / im.height;
+
+function layoutRows<T extends Sized>(images: T[], o: MasonryOpts, fits: ("cover" | "contain")[]): { boxes: MasonryBox<T>[]; used: number; endY: number } {
+  const asp = images.map((im, i) => effectiveAspect(im, fits[i]));
+  const boxes: MasonryBox<T>[] = [];
+  let y = 0, i = 0;
+  let used: number | null = null;
+  while (i < images.length) {
+    const row: number[] = []; // indices in this row
+    let natW = 0;
+    while (i + row.length < images.length) {
+      row.push(i + row.length);
+      const gaps = o.gapIn * (row.length - 1);
+      natW = row.reduce((s, idx) => s + asp[idx] * o.targetRowHeightIn, 0) + gaps;
+      if (natW >= o.bodyWIn) break;
+    }
+    const gaps = o.gapIn * (row.length - 1);
+    const sumAspect = row.reduce((s, idx) => s + asp[idx], 0);
+    const isFull = natW >= o.bodyWIn;
+    const rowH = isFull ? (o.bodyWIn - gaps) / sumAspect : o.targetRowHeightIn;
+    if (used === null && y + rowH > o.bodyHIn + EPS && boxes.length > 0) used = boxes.length;
+    let x = 0;
+    for (const idx of row) {
+      const w = asp[idx] * rowH;
+      boxes.push({ asset: images[idx], xIn: x, yIn: y, wIn: w, hIn: rowH });
+      x += w + o.gapIn;
+    }
+    y += rowH + o.gapIn;
+    i += row.length;
+  }
+  return { boxes, used: used ?? images.length, endY: y };
+}
+
+function layoutColumns<T extends Sized>(images: T[], o: MasonryOpts, fits: ("cover" | "contain")[]): { boxes: MasonryBox<T>[]; used: number; colHeights: number[]; colW: number } {
+  const n = o.columns;
+  const colW = (o.bodyWIn - o.gapIn * (n - 1)) / n;
+  const colH = new Array(n).fill(0);
+  const boxes: MasonryBox<T>[] = [];
+  let used: number | null = null;
+  images.forEach((im, idx) => {
+    let c = 0;
+    for (let k = 1; k < n; k++) if (colH[k] < colH[c]) c = k;
+    const y = colH[c];
+    const h = colW / effectiveAspect(im, fits[idx]);
+    if (used === null && y + h > o.bodyHIn + EPS && idx > 0) used = idx;
+    boxes.push({ asset: im, xIn: c * (colW + o.gapIn), yIn: y, wIn: colW, hIn: h });
+    colH[c] = y + h + o.gapIn;
+  });
+  return { boxes, used: used ?? images.length, colHeights: colH, colW };
+}
+
+export function layoutMasonryPage<T extends Sized>(
+  images: T[],
+  o: MasonryOpts,
+  fits: ("cover" | "contain")[] = [],
+): { boxes: MasonryBox<T>[]; used: number } {
+  if (o.mode === "columns") {
+    const r = layoutColumns(images, o, fits);
+    return { boxes: r.boxes, used: r.used };
+  }
+  const r = layoutRows(images, o, fits);
+  return { boxes: r.boxes, used: r.used };
+}

package/src/document/engine/paginate.ts

@@ -0,0 +1,209 @@
+import { layoutMasonryPage } from "./masonry";
+import type { SectionSettings } from "./settings";
+import type { Chunk, DocImage, TextBlock } from "./types";
+
+export interface DocGeom {
+  bodyWIn: number;
+  bodyHIn: number;
+  titleBandIn: number;
+  gapIn: number;
+  leftColWIn: number;
+  colGutterIn: number;
+  minImageRegionIn: number;
+  masonryTargetRowIn: number;
+  topTextMaxFraction: number;
+}
+
+// Mirrors .deck-body in deck.css (17×11 page, top 1.35in, sides/bottom 0.6in).
+export const DOC_GEOM: DocGeom = {
+  bodyWIn: 15.8,
+  bodyHIn: 9.05,
+  titleBandIn: 0.9,
+  gapIn: 0.15,
+  leftColWIn: 4.6,
+  colGutterIn: 0.4,
+  minImageRegionIn: 1.2,
+  masonryTargetRowIn: 2.6,
+  // Top text fills at most this fraction of the body height below the title
+  // band, so a text-heavy top section always leaves ≥ half the page for images.
+  topTextMaxFraction: 0.5,
+};
+
+const EPS = 1e-6;
+
+export interface Region { xIn: number; yIn: number; wIn: number; hIn: number; }
+export interface ImageBox {
+  image: DocImage;
+  xIn: number; yIn: number; wIn: number; hIn: number;
+  fit: "cover" | "contain";
+}
+export interface DerivedPage {
+  id: string;
+  chunkId: string;
+  title: string;
+  cont: boolean;
+  textBlocks: TextBlock[];
+  textRegion: Region | null;
+  imageBoxes: ImageBox[];
+  warnings: string[];
+}
+
+function fitImages(
+  images: DocImage[],
+  layout: SectionSettings["imageLayout"],
+  region: Region,
+  geom: DocGeom,
+): { boxes: ImageBox[]; used: number } {
+  if (images.length === 0 || region.hIn < geom.minImageRegionIn) return { boxes: [], used: 0 };
+
+  if (layout.mode === "grid") {
+    const used = Math.min(layout.rows * layout.columns, images.length);
+    const cellW = (region.wIn - (layout.columns - 1) * geom.gapIn) / layout.columns;
+    const cellH = (region.hIn - (layout.rows - 1) * geom.gapIn) / layout.rows;
+    const boxes = images.slice(0, used).map((image, i) => {
+      const r = Math.floor(i / layout.columns);
+      const c = i % layout.columns;
+      return {
+        image,
+        xIn: region.xIn + c * (cellW + geom.gapIn),
+        yIn: region.yIn + r * (cellH + geom.gapIn),
+        wIn: cellW,
+        hIn: cellH,
+        fit: "cover" as const,
+      };
+    });
+    return { boxes, used };
+  }
+
+  const r = layoutMasonryPage(images, {
+    mode: layout.flow,
+    columns: layout.columns,
+    bodyWIn: region.wIn,
+    bodyHIn: region.hIn,
+    gapIn: geom.gapIn,
+    targetRowHeightIn: geom.masonryTargetRowIn,
+  });
+  const boxes = r.boxes.slice(0, r.used).map((b) => ({
+    image: b.asset,
+    xIn: region.xIn + b.xIn,
+    yIn: region.yIn + b.yIn,
+    wIn: b.wIn,
+    hIn: b.hIn,
+    fit: "contain" as const,
+  }));
+  return { boxes, used: r.used };
+}
+
+export function paginateChunk(
+  chunk: Chunk,
+  settings: SectionSettings,
+  textHeightsIn: number[],
+  geom: DocGeom = DOC_GEOM,
+): DerivedPage[] {
+  if (settings.excluded) return [];
+  if (chunk.textBlocks.length !== textHeightsIn.length) {
+    throw new Error("paginateChunk: textHeightsIn must match chunk.textBlocks");
+  }
+  if (chunk.textBlocks.length === 0 && chunk.images.length === 0) return [];
+
+  const pages: DerivedPage[] = [];
+  let ti = 0;
+  let ii = 0;
+  const top = geom.titleBandIn;
+
+  while (ti < chunk.textBlocks.length || ii < chunk.images.length) {
+    const cont = pages.length > 0;
+    const warnings: string[] = [];
+    const textW = settings.textPlacement === "top" ? geom.bodyWIn : geom.leftColWIn;
+
+    // 1. Greedy text fill. Top text is capped at half the body so a text-heavy
+    // section still leaves room for images below; leftColumn keeps full height.
+    const capY =
+      settings.textPlacement === "top"
+        ? geom.titleBandIn + (geom.bodyHIn - geom.titleBandIn) * geom.topTextMaxFraction
+        : geom.bodyHIn;
+    const placed: TextBlock[] = [];
+    let textEnd = top;
+    while (ti < chunk.textBlocks.length) {
+      const h = textHeightsIn[ti];
+      const yAfter = placed.length === 0 ? top + h : textEnd + geom.gapIn + h;
+      if (yAfter <= capY + EPS) {
+        placed.push(chunk.textBlocks[ti]);
+        textEnd = yAfter;
+        ti++;
+      } else if (placed.length === 0) {
+        // Oversize block: it gets the page, clipped at the cap (masonry-notice style).
+        placed.push(chunk.textBlocks[ti]);
+        textEnd = capY;
+        ti++;
+        warnings.push("A text block is taller than the page and was clipped.");
+        break;
+      } else {
+        break;
+      }
+    }
+
+    // dropTextOverflow: on the FIRST page only, discard any text that didn't fit
+    // rather than flowing it onto Cont. pages. Images still paginate as usual.
+    if (!cont && settings.dropTextOverflow && ti < chunk.textBlocks.length) {
+      const dropped = chunk.textBlocks.length - ti;
+      ti = chunk.textBlocks.length;
+      warnings.push(`${dropped} text block(s) hidden (overflow dropped)`);
+    }
+    const textRegion: Region | null =
+      placed.length > 0 ? { xIn: 0, yIn: top, wIn: textW, hIn: textEnd - top } : null;
+
+    // 2. Image region. leftColumn+right runs beside the text; every other
+    // case — and any page whose text is exhausted — is full width below it.
+    let region: Region;
+    if (settings.textPlacement === "leftColumn" && settings.imagePlacement === "right" && placed.length > 0) {
+      region = {
+        xIn: geom.leftColWIn + geom.colGutterIn,
+        yIn: top,
+        wIn: geom.bodyWIn - geom.leftColWIn - geom.colGutterIn,
+        hIn: geom.bodyHIn - top,
+      };
+    } else {
+      const startY = placed.length > 0 ? textEnd + geom.gapIn : top;
+      region = { xIn: 0, yIn: startY, wIn: geom.bodyWIn, hIn: Math.max(0, geom.bodyHIn - startY) };
+    }
+
+    // 3. Fit images into the region.
+    const { boxes, used } = fitImages(chunk.images.slice(ii), settings.imageLayout, region, geom);
+    ii += used;
+    if (boxes.some((b) => b.yIn + b.hIn > region.yIn + region.hIn + 0.01)) {
+      warnings.push("An image overflows the page and is clipped.");
+    }
+
+    // Progress guard: unreachable with sane geometry (a text-free page always
+    // gets the full region, and both fitters place ≥1 there), but a config
+    // mistake must not hang the browser.
+    if (placed.length === 0 && used === 0) {
+      warnings.push("Pagination could not place remaining content.");
+      pages.push({
+        id: `${chunk.id}#${pages.length}`,
+        chunkId: chunk.id,
+        title: cont ? `${chunk.title} Cont.` : chunk.title,
+        cont,
+        textBlocks: placed,
+        textRegion,
+        imageBoxes: boxes,
+        warnings,
+      });
+      break;
+    }
+
+    pages.push({
+      id: `${chunk.id}#${pages.length}`,
+      chunkId: chunk.id,
+      title: cont ? `${chunk.title} Cont.` : chunk.title,
+      cont,
+      textBlocks: placed,
+      textRegion,
+      imageBoxes: boxes,
+      warnings,
+    });
+  }
+
+  return pages;
+}

package/src/document/engine/settings.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+// Presentation settings for one link-heading chunk. This shape is designed as
+// if it were already a portal page's `document` options block — migrating it
+// into the portal later must be a data move, not a redesign.
+export const sectionSettingsSchema = z.object({
+  excluded: z.boolean().default(false),
+  textPlacement: z.enum(["top", "leftColumn"]).default("top"),
+  // "right" is only meaningful with textPlacement "leftColumn"; settingsFor
+  // normalizes the invalid combo.
+  imagePlacement: z.enum(["fullWidth", "right"]).default("fullWidth"),
+  // When true, text that overflows the first page is dropped instead of
+  // flowing onto Cont. pages (images still paginate normally).
+  dropTextOverflow: z.boolean().default(false),
+  imageLayout: z
+    .discriminatedUnion("mode", [
+      z.object({
+        mode: z.literal("grid"),
+        rows: z.union([z.literal(1), z.literal(2), z.literal(3)]).default(2),
+        columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(4),
+      }),
+      z.object({
+        mode: z.literal("masonry"),
+        flow: z.enum(["rows", "columns"]).default("rows"),
+        columns: z
+          .union([z.literal(2), z.literal(3), z.literal(4), z.literal(5), z.literal(6)])
+          .default(3),
+      }),
+    ])
+    .default({ mode: "masonry", flow: "rows", columns: 3 }),
+});
+
+export type SectionSettings = z.infer<typeof sectionSettingsSchema>;
+
+const DEFAULTS: SectionSettings = sectionSettingsSchema.parse({});
+
+// Overlay lookup: unknown/stale/malformed entries fall back to defaults —
+// settings for a deleted portal section must be inert, never fatal.
+export function settingsFor(
+  all: Record<string, unknown> | undefined,
+  chunkId: string,
+): SectionSettings {
+  const raw = all?.[chunkId];
+  const parsed = sectionSettingsSchema.safeParse(raw ?? {});
+  const s = parsed.success ? parsed.data : DEFAULTS;
+  if (s.textPlacement === "top" && s.imagePlacement === "right") {
+    return { ...s, imagePlacement: "fullWidth" };
+  }
+  return s;
+}
+
+const documentMetaSchema = z.object({
+  client: z.string().default(""),
+  project: z.string().default(""),
+  dateLabel: z.string().default(""),
+});
+const documentCoverSchema = z.object({
+  bgColor: z.string().default("#333333"),
+  accentColor: z.string().default("#EB9500"),
+  title: z.string().default(""),
+  label: z.string().default("BRAND GUIDELINES"),
+  date: z.string().default(""),
+  // Media-library image id shown between masthead and title lockup; null = solid cover.
+  imageId: z.string().nullable().default(null),
+});
+
+export const documentOptionsSchema = z.object({
+  enabled: z.boolean().default(false),
+  // `.default({})` doesn't typecheck even though `{}` parses fine at
+  // runtime — zod v4 infers the default's type from the object schema's
+  // required input shape, not its post-default output shape.
+  meta: documentMetaSchema.default(() => documentMetaSchema.parse({})),
+  cover: documentCoverSchema.default(() => documentCoverSchema.parse({})),
+  sections: z.record(z.string(), sectionSettingsSchema).default({}),
+});
+export type DocumentOptions = z.infer<typeof documentOptionsSchema>;
+export type DocCover = DocumentOptions["cover"];

package/src/document/engine/types.ts

@@ -0,0 +1,54 @@
+// Engine-local structural types for portal content. Deliberately NOT imported
+// from the rest of @drawnagency/primitives: the engine's contract is the
+// portal content SHAPE, and staying import-free keeps it portable into its
+// own package later.
+// (The fixture test in tests/document/fixture.test.ts pins the shape against
+// the real primitives schemas so drift is caught.)
+
+export const PREAMBLE_ID = "__preamble";
+
+// Breadcrumb metadata shown in the page chrome. Single definition — the
+// harness carried this shape in two places (deck/DeckPage.tsx's `DeckMeta`
+// and lib/deck/schema.ts's zod-inferred `DeckMeta`); the engine only needs
+// the plain type, not a schema, so it lives here once.
+export interface DocMeta {
+  client: string;
+  project: string;
+  dateLabel: string;
+}
+
+export interface DocSectionInput {
+  id: string;
+  type: string;
+  content: Record<string, unknown>;
+  options?: Record<string, unknown>;
+}
+
+// One displayable image, dimensions + pre-chosen repo filenames baked in by
+// the (scaffolding) fetch layer so the engine never touches the manifest.
+export interface DocImage {
+  imageId: string;
+  width: number;
+  height: number;
+  alt: string;
+  previewFile: string; // e.g. "1080.webp" — editor variant
+  printFile: string;   // e.g. "1920.webp" — print/PDF variant
+}
+
+export type TextBlock =
+  | { kind: "heading"; level: 2 | 3; text: string }
+  | { kind: "prose"; html: string };
+
+// A link-heading chunk: everything between one link_heading and the next.
+export interface Chunk {
+  id: string; // link_heading section id, or PREAMBLE_ID
+  title: string;
+  textBlocks: TextBlock[];
+  images: DocImage[];
+}
+
+export interface DocSourceContent {
+  pageTitle: string;
+  sections: DocSectionInput[];
+  images: Record<string, DocImage>;
+}

package/src/document/index.ts

@@ -0,0 +1,18 @@
+// Public surface of the document engine + components. Sealed subtree: nothing
+// in document/ imports from the rest of primitives (see spec — extraction to
+// @drawnagency/document must stay a directory move).
+export * from "./engine/types";
+export * from "./engine/settings";
+export { splitProseBlocks } from "./engine/blocks";
+export { harvest } from "./engine/harvest";
+export * from "./engine/paginate";
+export { layoutMasonryPage, type MasonryOpts, type MasonryBox, type Sized } from "./engine/masonry";
+
+export { DocPage, type DocMeta } from "./components/DocPage";
+export { DocSectionPage, type DocHost } from "./components/DocSectionPage";
+export { DocCoverPage } from "./components/DocCoverPage";
+export { useDocPages } from "./components/useDocPages";
+
+// Task 3 — shared document shell (presentation + editing).
+export { DocViewer, type DocViewerProps } from "./components/DocViewer";
+export { DocRail, entryId, type RailEntry } from "./components/DocRail";