@drawnagency/primitives 0.1.80 → 0.1.82

package/src/document/engine/harvest.ts

@@ -0,0 +1,95 @@
+import { splitProseBlocks } from "./blocks";
+import { PREAMBLE_ID, type Chunk, type DocImage, type DocSectionInput, type SplitAt } 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>,
+  splitAtFor: (chunkId: string) => SplitAt = () => "none",
+): Chunk[] {
+  const chunks: Chunk[] = [];
+  const preamble: Chunk = { id: PREAMBLE_ID, title: pageTitle, textBlocks: [], images: [] };
+  let parent = preamble; // current top-level chunk — owns the splitAt setting
+  let current = preamble; // chunk receiving harvested content
+  let splitAt = splitAtFor(PREAMBLE_ID);
+
+  for (const section of sections) {
+    const heading = str(asRecord(section.content).heading);
+    if (section.type === "link_heading") {
+      parent = { id: section.id, title: heading, textBlocks: [], images: [] };
+      current = parent;
+      splitAt = splitAtFor(section.id);
+      chunks.push(parent);
+    } else if (section.type === "sub_heading" && splitAt === "sub_heading") {
+      // Promotion: the boundary heading becomes the chunk title, not a TextBlock.
+      current = { id: section.id, title: heading, textBlocks: [], images: [], parentId: parent.id, kicker: parent.title, depth: 1 };
+      chunks.push(current);
+    } else {
+      harvestInto(current, section.type, section.content, imagesById);
+    }
+  }
+
+  // Kept when it has own content OR spawned sub-chunks — an emptied-but-split
+  // preamble must stay selectable (its ghost is the way back to splitAt).
+  const keepPreamble =
+    preamble.textBlocks.length > 0 ||
+    preamble.images.length > 0 ||
+    chunks.some((c) => c.parentId === PREAMBLE_ID);
+  return keepPreamble ? [preamble, ...chunks] : chunks;
+}

package/src/document/engine/masonry.ts

@@ -0,0 +1,152 @@
+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;
+  rows?: "auto" | 1 | 2 | 3 | 4;
+}
+
+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 };
+}
+
+// Forced row count: partition the images into exactly N rows (fewer only if
+// there are fewer images), aspect-balanced, each row scaled to full width —
+// unless the stack would exceed the region height, in which case the whole
+// block scales down uniformly to fit (never up), left-aligned. Unlike
+// layoutRows there is no target height — the row's share of the total aspect
+// determines its height.
+function layoutForcedRows<T extends Sized>(
+  images: T[],
+  o: MasonryOpts,
+  fits: ("cover" | "contain")[],
+  n: number,
+): { boxes: MasonryBox<T>[]; used: number; endY: number } {
+  const asp = images.map((im, i) => effectiveAspect(im, fits[i]));
+  const count = Math.min(n, images.length);
+  // Greedy balance: each row takes images until it reaches the average
+  // aspect-sum of what's left, always leaving >=1 image per remaining row.
+  const rows: number[][] = [];
+  let i = 0;
+  for (let r = 0; r < count; r++) {
+    const remainingRows = count - r;
+    const target = asp.slice(i).reduce((s, a) => s + a, 0) / remainingRows;
+    const row: number[] = [];
+    let sum = 0;
+    while (i < asp.length) {
+      if (row.length > 0) {
+        if (asp.length - (i + 1) < remainingRows - 1) break; // taking i must leave >=1 image per remaining row
+        if (sum >= target - EPS) break;
+      }
+      row.push(i);
+      sum += asp[i];
+      i++;
+    }
+    rows.push(row);
+  }
+
+  // Pass 1: full-width row heights from the aspect math.
+  const rowMeta = rows.map((row) => {
+    const gaps = o.gapIn * (row.length - 1);
+    const sumAspect = row.reduce((s, a) => s + asp[a], 0);
+    return { row, gaps, sumAspect, hIn: (o.bodyWIn - gaps) / sumAspect };
+  });
+  // Pass 2: if the stack exceeds the region, scale everything down uniformly —
+  // natural aspects kept, gaps fixed, block left-aligned. Never upscale.
+  const rowGaps = o.gapIn * (rowMeta.length - 1);
+  const totalH = rowMeta.reduce((s, m) => s + m.hIn, 0);
+  const scale = totalH > 0 ? Math.min(1, Math.max(0, o.bodyHIn - rowGaps) / totalH) : 1;
+
+  const boxes: MasonryBox<T>[] = [];
+  let y = 0;
+  for (const m of rowMeta) {
+    const rowH = m.hIn * scale;
+    let x = 0;
+    for (const idx of m.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;
+  }
+  return { boxes, 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 = typeof o.rows === "number" ? layoutForcedRows(images, o, fits, o.rows) : layoutRows(images, o, fits);
+  return { boxes: r.boxes, used: r.used };
+}

package/src/document/engine/paginate.ts

@@ -0,0 +1,229 @@
+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;
+  minTextColIn: 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,
+  minTextColIn: 1,
+  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;
+  // Sub-chunk context (absent on top-level pages) — see Chunk.
+  kicker?: string;
+  depth?: 1;
+  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: layout.fit,
+      };
+    });
+    return { boxes, used };
+  }
+
+  const r = layoutMasonryPage(images, {
+    mode: layout.flow,
+    columns: layout.columns,
+    rows: layout.rows,
+    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,
+  naturalTextWIn?: number,
+): 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 [];
+
+  // leftColumn shrinks to the widest natural text line (+ slack so sub-pixel
+  // rounding can't re-wrap), floored/capped; absent measurement = legacy fixed
+  // column. The shrunk width is >= every block's natural width by
+  // construction, so measured heights remain valid.
+  const colWIn =
+    naturalTextWIn === undefined
+      ? geom.leftColWIn
+      : Math.min(geom.leftColWIn, Math.max(geom.minTextColIn, naturalTextWIn + 0.05));
+
+  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 : colWIn;
+
+    // 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: colWIn + geom.colGutterIn,
+        yIn: top,
+        wIn: geom.bodyWIn - colWIn - 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,
+        kicker: chunk.kicker,
+        depth: chunk.depth,
+        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,
+      kicker: chunk.kicker,
+      depth: chunk.depth,
+      textBlocks: placed,
+      textRegion,
+      imageBoxes: boxes,
+      warnings,
+    });
+  }
+
+  return pages;
+}

package/src/document/engine/settings.ts

@@ -0,0 +1,88 @@
+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),
+  // Also start new pages at sub-heading boundaries. Only read from PARENT
+  // entries (link_heading ids / __preamble); inert on sub-chunk entries.
+  splitAt: z.enum(["none", "sub_heading"]).default("none"),
+  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),
+        // "cover" crops each image to its cell; "contain" letterboxes the
+        // natural image inside it.
+        fit: z.enum(["cover", "contain"]).default("cover"),
+      }),
+      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),
+        // rows flow only: "auto" = greedy target-height fill (legacy behavior);
+        // 1-4 forces an exact aspect-balanced row count.
+        rows: z
+          .union([z.literal("auto"), z.literal(1), z.literal(2), z.literal(3), z.literal(4)])
+          .default("auto"),
+      }),
+    ])
+    .default({ mode: "masonry", flow: "rows", columns: 3, rows: "auto" }),
+});
+
+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,64 @@
+// 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";
+
+// Page-split boundary level for one parent section. Sub-headings are the
+// deepest deck boundary (internal convention, 2026-07-19) — sub_sub_heading
+// sections always stay in-page as level-3 text blocks.
+export type SplitAt = "none" | "sub_heading";
+
+// 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 page-producing chunk: a link_heading section (or the preamble), or — when
+// the parent's splitAt says so — a sub heading section.
+export interface Chunk {
+  id: string; // boundary heading's section id, or PREAMBLE_ID
+  title: string;
+  textBlocks: TextBlock[];
+  images: DocImage[];
+  // Sub-chunk fields; absent on top-level chunks.
+  parentId?: string;
+  kicker?: string; // masthead context line — the parent link_heading title
+  depth?: 1;
+}
+
+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";