@drawnagency/primitives 0.1.81 → 0.1.82

package/src/components/shell/DocInspector.tsx

@@ -21,7 +21,7 @@ function thumbSrc(imageId: string, item: MediaItem | undefined): string | null {
 
 export interface DocInspectorProps {
   document: DocumentOptions;
-  selection: { kind: "cover" } | { kind: "chunk"; chunkId: string; title: string };
+  selection: { kind: "cover" } | { kind: "chunk"; chunkId: string; title: string; depth?: number };
   warnings: string[]; // warningsByChunk for the selected chunk
   onUpdateCover: (patch: Partial<DocumentOptions["cover"]>) => void;
   onUpdateMeta: (patch: Partial<DocumentOptions["meta"]>) => void;
@@ -84,6 +84,7 @@ export function DocInspector({
           key={selection.chunkId}
           chunkId={selection.chunkId}
           title={selection.title}
+          depth={selection.depth}
           doc={doc}
           warnings={warnings}
           onUpdateSection={onUpdateSection}
@@ -153,12 +154,14 @@ function CoverPanel({
 function ChunkPanel({
   chunkId,
   title,
+  depth,
   doc,
   warnings,
   onUpdateSection,
 }: {
   chunkId: string;
   title: string;
+  depth?: number;
   doc: DocumentOptions;
   warnings: string[];
   onUpdateSection: (chunkId: string, patch: Record<string, unknown>) => void;
@@ -177,6 +180,22 @@ function ChunkPanel({
         label="Include in document"
       />
 
+      {/* Only parent sections own the boundary setting — a sub-page can't
+          split further, and its entry would be inert anyway (harvest reads
+          splitAt from parent ids only). */}
+      {(depth ?? 0) === 0 ? (
+        <Select
+          className="mb-4"
+          label="Split pages at"
+          value={settings.splitAt}
+          options={[
+            { value: "none", label: "Off" },
+            { value: "sub_heading", label: "Sub-headings" },
+          ]}
+          onChange={(splitAt) => onUpdateSection(chunkId, { splitAt })}
+        />
+      ) : null}
+
       {/* Image placement is linked, not independent (Drew, 2026-07-19): text
           left → images right of the column, text top → images below full
           width. One control drives both fields. */}
@@ -237,6 +256,16 @@ function ChunkPanel({
             options={[2, 3, 4].map((n) => ({ value: String(n), label: String(n) }))}
             onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, columns: Number(v) } })}
           />
+          <Select
+            className="mb-4"
+            label="Image fit"
+            value={layout.fit}
+            options={[
+              { value: "cover", label: "Crop" },
+              { value: "contain", label: "Contain" },
+            ]}
+            onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, fit: v } })}
+          />
         </>
       ) : (
         <>
@@ -250,6 +279,22 @@ function ChunkPanel({
             ]}
             onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, flow: v } })}
           />
+          {/* Rows count only drives the rows flow; "auto" keeps the greedy
+              target-height fill. Mirrors Columns, which only drives columns. */}
+          {layout.flow === "rows" ? (
+            <Select
+              className="mb-4"
+              label="Rows"
+              value={String(layout.rows)}
+              options={[
+                { value: "auto", label: "Auto" },
+                ...[1, 2, 3, 4].map((n) => ({ value: String(n), label: String(n) })),
+              ]}
+              onChange={(v) =>
+                onUpdateSection(chunkId, { imageLayout: { ...layout, rows: v === "auto" ? "auto" : Number(v) } })
+              }
+            />
+          ) : null}
           {/* Column count only drives the columns flow (layoutRows never reads
               it) — hide it when irrelevant. */}
           {layout.flow === "columns" ? (

package/src/components/shell/DocumentEditorOverlay.tsx

@@ -110,7 +110,7 @@ export function DocumentEditorOverlay({
   const selection: DocInspectorProps["selection"] = useMemo(() => {
     if (selectedChunkId === null) return { kind: "cover" };
     const chunk = chunks.find((c) => c.id === selectedChunkId);
-    return { kind: "chunk", chunkId: selectedChunkId, title: chunk?.title ?? selectedChunkId };
+    return { kind: "chunk", chunkId: selectedChunkId, title: chunk?.title ?? selectedChunkId, depth: chunk?.depth };
   }, [selectedChunkId, chunks]);
 
   const warnings = selectedChunkId ? warningsByChunk[selectedChunkId] ?? [] : [];

package/src/document/components/DocRail.tsx

@@ -13,7 +13,7 @@ const PAGE_H = 1056;
 export type RailEntry =
   | { kind: "cover" }
   | { kind: "page"; page: DerivedPage }
-  | { kind: "ghost"; chunkId: string; title: string; reason: "excluded" | "empty" };
+  | { kind: "ghost"; chunkId: string; title: string; reason: "excluded" | "empty"; depth?: 1 };
 
 export function entryId(entry: RailEntry): string {
   if (entry.kind === "cover") return "cover";
@@ -21,12 +21,16 @@ export function entryId(entry: RailEntry): string {
   return `ghost:${entry.chunkId}`;
 }
 
+// Rail nesting: sub-pages sit one step in per depth, continuations one more.
+const INDENT = ["", "pl-4", "pl-8"];
+const indentClass = (level: number) => INDENT[Math.min(level, INDENT.length - 1)] || undefined;
+
 function ThumbButton({
   id,
   selectedId,
   scale,
   label,
-  indent,
+  indentLevel,
   onSelect,
   children,
 }: {
@@ -34,12 +38,12 @@ function ThumbButton({
   selectedId: string;
   scale: number;
   label: string;
-  indent?: boolean;
+  indentLevel?: number;
   onSelect: (id: string) => void;
   children: ReactNode;
 }) {
   return (
-    <li className={indent ? "pl-4" : undefined}>
+    <li className={indentClass(indentLevel ?? 0)}>
       <button
         type="button"
         onClick={() => onSelect(id)}
@@ -128,7 +132,7 @@ export function DocRail({
                 selectedId={selectedId}
                 scale={scale}
                 label={entry.page.title}
-                indent={entry.page.cont}
+                indentLevel={(entry.page.depth ?? 0) + (entry.page.cont ? 1 : 0)}
                 onSelect={onSelect}
               >
                 <DocSectionPage page={entry.page} meta={meta} host={host} />
@@ -136,7 +140,7 @@ export function DocRail({
             );
           }
           return (
-            <li key={id}>
+            <li key={id} className={indentClass(entry.depth ?? 0)}>
               <button
                 type="button"
                 onClick={() => onSelect(id)}

package/src/document/components/DocSectionPage.tsx

@@ -12,7 +12,10 @@ const inch = (v: number) => `${v}in`;
 export function DocSectionPage({ page, meta, host }: { page: DerivedPage; meta: DocMeta; host: DocHost }) {
   return (
     <DocPage meta={meta}>
-      <h2 className="pdoc-title">{page.title}</h2>
+      <h2 className="pdoc-title">
+        {page.kicker ? <span className="pdoc-kicker" aria-hidden="true">{page.kicker}</span> : null}
+        {page.title}
+      </h2>
       {page.textRegion ? (
         <div
           className="pdoc-text"

package/src/document/components/DocViewer.tsx

@@ -74,7 +74,7 @@ export function DocViewer({
       const empty = chunk.textBlocks.length === 0 && chunk.images.length === 0;
       if (s.excluded || empty) {
         if (mode === "edit") {
-          list.push({ kind: "ghost", chunkId: chunk.id, title: chunk.title, reason: s.excluded ? "excluded" : "empty" });
+          list.push({ kind: "ghost", chunkId: chunk.id, title: chunk.title, reason: s.excluded ? "excluded" : "empty", depth: chunk.depth });
         }
       } else {
         for (const page of pages.filter((p) => p.chunkId === chunk.id)) list.push({ kind: "page", page });

package/src/document/components/measure.tsx

@@ -39,8 +39,9 @@ function signatureFor(chunks: Chunk[], settingsMap: Record<string, SectionSettin
 export function useTextMeasurements(
   chunks: Chunk[],
   settingsMap: Record<string, SectionSettings>,
-): { heights: Record<string, number[]> | null } {
+): { heights: Record<string, number[]> | null; textWidths: Record<string, number> | null } {
   const [heights, setHeights] = useState<Record<string, number[]> | null>(null);
+  const [textWidths, setTextWidths] = useState<Record<string, number> | null>(null);
   const [fontsReady, setFontsReady] = useState(false);
 
   // jsdom (tests) has no document.fonts — optional-chain so this resolves
@@ -65,10 +66,12 @@ export function useTextMeasurements(
     if (!fontsReady) return;
     const containers: HTMLDivElement[] = [];
     const next: Record<string, number[]> = {};
+    const nextW: Record<string, number> = {};
 
     for (const chunk of chunks) {
       if (chunk.textBlocks.length === 0) {
         next[chunk.id] = [];
+        nextW[chunk.id] = 0;
         continue;
       }
       const container = document.createElement("div");
@@ -78,6 +81,7 @@ export function useTextMeasurements(
       containers.push(container);
 
       const measured: number[] = [];
+      let wMax = 0;
       for (const block of chunk.textBlocks) {
         const wrapper = document.createElement("div");
         wrapper.className = blockClassName(block);
@@ -86,13 +90,21 @@ export function useTextMeasurements(
         } else {
           wrapper.innerHTML = block.html;
         }
+        // max-content + max-width:100% = shrink-to-fit capped at the column:
+        // wrapping blocks report the full cap (same wrap as before -> heights
+        // unchanged); short blocks report their natural width.
+        wrapper.style.width = "max-content";
+        wrapper.style.maxWidth = "100%";
         container.appendChild(wrapper);
         measured.push(wrapper.offsetHeight / PX_PER_IN);
+        wMax = Math.max(wMax, wrapper.getBoundingClientRect().width / PX_PER_IN);
       }
       next[chunk.id] = measured;
+      nextW[chunk.id] = wMax;
     }
 
     setHeights(next);
+    setTextWidths(nextW);
     return () => {
       for (const container of containers) container.remove();
     };
@@ -101,5 +113,5 @@ export function useTextMeasurements(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [signature, fontsReady]);
 
-  return { heights };
+  return { heights, textWidths };
 }

package/src/document/components/useDocPages.ts

@@ -1,8 +1,8 @@
 import { useMemo } from "react";
 import { harvest } from "../engine/harvest";
-import { paginateChunk, type DerivedPage } from "../engine/paginate";
+import { DOC_GEOM, paginateChunk, type DerivedPage } from "../engine/paginate";
 import { settingsFor, type SectionSettings } from "../engine/settings";
-import type { Chunk, DocSourceContent } from "../engine/types";
+import type { Chunk, DocSourceContent, SplitAt } from "../engine/types";
 import { useTextMeasurements } from "./measure";
 
 export function useDocPages(input: {
@@ -11,9 +11,27 @@ export function useDocPages(input: {
 }): { chunks: Chunk[]; pages: DerivedPage[]; measuring: boolean; warningsByChunk: Record<string, string[]> } {
   const { source, sections } = input;
 
+  // splitAt drives harvesting, so chunks must re-derive when it changes — but
+  // ONLY then. Keying on a JSON signature of just the non-default splitAt
+  // entries keeps chunk identities stable across unrelated settings edits
+  // (exclude, layout), which would otherwise churn measurement and onDocState.
+  const splitSig = useMemo(() => {
+    const m: Record<string, SplitAt> = {};
+    for (const id of Object.keys(sections ?? {})) {
+      const v = settingsFor(sections, id).splitAt;
+      if (v !== "none") m[id] = v;
+    }
+    return JSON.stringify(m);
+  }, [sections]);
+
+  const splitAtFor = useMemo(() => {
+    const m = JSON.parse(splitSig) as Record<string, SplitAt>;
+    return (id: string) => m[id] ?? "none";
+  }, [splitSig]);
+
   const chunks = useMemo(
-    () => (source ? harvest(source.sections, source.pageTitle, source.images) : []),
-    [source],
+    () => (source ? harvest(source.sections, source.pageTitle, source.images, splitAtFor) : []),
+    [source, splitAtFor],
   );
 
   const settingsMap = useMemo(() => {
@@ -22,7 +40,7 @@ export function useDocPages(input: {
     return map;
   }, [chunks, sections]);
 
-  const { heights } = useTextMeasurements(chunks, settingsMap);
+  const { heights, textWidths } = 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
@@ -36,9 +54,9 @@ export function useDocPages(input: {
     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 ?? []);
+      return paginateChunk(c, settingsMap[c.id], h ?? [], DOC_GEOM, textWidths?.[c.id]);
     });
-  }, [chunks, settingsMap, heights]);
+  }, [chunks, settingsMap, heights, textWidths]);
 
   // 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.

package/src/document/engine/harvest.ts

@@ -1,5 +1,5 @@
 import { splitProseBlocks } from "./blocks";
-import { PREAMBLE_ID, type Chunk, type DocImage, type DocSectionInput } from "./types";
+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).
@@ -61,20 +61,35 @@ export function harvest(
   sections: DocSectionInput[],
   pageTitle: string,
   imagesById: Record<string, DocImage>,
+  splitAtFor: (chunkId: string) => SplitAt = () => "none",
 ): Chunk[] {
   const chunks: Chunk[] = [];
-  let current: Chunk = { id: PREAMBLE_ID, title: pageTitle, textBlocks: [], images: [] };
-  let preamble = current;
+  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") {
-      current = { id: section.id, title: str(asRecord(section.content).heading), textBlocks: [], images: [] };
+      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);
     }
   }
 
-  const preambleHasContent = preamble.textBlocks.length > 0 || preamble.images.length > 0;
-  return preambleHasContent ? [preamble, ...chunks] : chunks;
+  // 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

@@ -11,6 +11,7 @@ export interface MasonryOpts {
   bodyHIn: number;
   gapIn: number;
   targetRowHeightIn: number;
+  rows?: "auto" | 1 | 2 | 3 | 4;
 }
 
 export interface MasonryBox<T extends Sized = Sized> {
@@ -57,6 +58,68 @@ function layoutRows<T extends Sized>(images: T[], o: MasonryOpts, fits: ("cover"
   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;
@@ -84,6 +147,6 @@ export function layoutMasonryPage<T extends Sized>(
     const r = layoutColumns(images, o, fits);
     return { boxes: r.boxes, used: r.used };
   }
-  const r = layoutRows(images, o, fits);
+  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

@@ -9,6 +9,7 @@ export interface DocGeom {
   gapIn: number;
   leftColWIn: number;
   colGutterIn: number;
+  minTextColIn: number;
   minImageRegionIn: number;
   masonryTargetRowIn: number;
   topTextMaxFraction: number;
@@ -22,6 +23,7 @@ export const DOC_GEOM: DocGeom = {
   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
@@ -42,6 +44,9 @@ export interface DerivedPage {
   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[];
@@ -69,7 +74,7 @@ function fitImages(
         yIn: region.yIn + r * (cellH + geom.gapIn),
         wIn: cellW,
         hIn: cellH,
-        fit: "cover" as const,
+        fit: layout.fit,
       };
     });
     return { boxes, used };
@@ -78,6 +83,7 @@ function fitImages(
   const r = layoutMasonryPage(images, {
     mode: layout.flow,
     columns: layout.columns,
+    rows: layout.rows,
     bodyWIn: region.wIn,
     bodyHIn: region.hIn,
     gapIn: geom.gapIn,
@@ -99,6 +105,7 @@ export function paginateChunk(
   settings: SectionSettings,
   textHeightsIn: number[],
   geom: DocGeom = DOC_GEOM,
+  naturalTextWIn?: number,
 ): DerivedPage[] {
   if (settings.excluded) return [];
   if (chunk.textBlocks.length !== textHeightsIn.length) {
@@ -106,6 +113,15 @@ export function paginateChunk(
   }
   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;
@@ -114,7 +130,7 @@ export function paginateChunk(
   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;
+    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.
@@ -158,9 +174,9 @@ export function paginateChunk(
     let region: Region;
     if (settings.textPlacement === "leftColumn" && settings.imagePlacement === "right" && placed.length > 0) {
       region = {
-        xIn: geom.leftColWIn + geom.colGutterIn,
+        xIn: colWIn + geom.colGutterIn,
         yIn: top,
-        wIn: geom.bodyWIn - geom.leftColWIn - geom.colGutterIn,
+        wIn: geom.bodyWIn - colWIn - geom.colGutterIn,
         hIn: geom.bodyHIn - top,
       };
     } else {
@@ -185,6 +201,8 @@ export function paginateChunk(
         chunkId: chunk.id,
         title: cont ? `${chunk.title} Cont.` : chunk.title,
         cont,
+        kicker: chunk.kicker,
+        depth: chunk.depth,
         textBlocks: placed,
         textRegion,
         imageBoxes: boxes,
@@ -198,6 +216,8 @@ export function paginateChunk(
       chunkId: chunk.id,
       title: cont ? `${chunk.title} Cont.` : chunk.title,
       cont,
+      kicker: chunk.kicker,
+      depth: chunk.depth,
       textBlocks: placed,
       textRegion,
       imageBoxes: boxes,

package/src/document/engine/settings.ts

@@ -12,12 +12,18 @@ export const sectionSettingsSchema = z.object({
   // 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"),
@@ -25,9 +31,14 @@ export const sectionSettingsSchema = z.object({
         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 }),
+    .default({ mode: "masonry", flow: "rows", columns: 3, rows: "auto" }),
 });
 
 export type SectionSettings = z.infer<typeof sectionSettingsSchema>;

package/src/document/engine/types.ts

@@ -7,6 +7,11 @@
 
 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
@@ -39,12 +44,17 @@ 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.
+// 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; // link_heading section id, or PREAMBLE_ID
+  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 {

package/src/document/styles/document.css

@@ -178,6 +178,15 @@
   margin: 0;
   height: 0.9in; /* = DOC_GEOM.titleBandIn; keep in sync */
 }
+/* Sub-page context line inside the title band (uppercase inherits from
+   .pdoc-title). Sized to sit with the title within the fixed 0.9in band. */
+.pdoc-kicker {
+  display: block;
+  font-size: 9pt;
+  letter-spacing: 0.12em;
+  color: #999999;
+  margin-bottom: 0.05in;
+}
 .pdoc-text { position: absolute; }
 .pdoc-h2, .pdoc-h3 {
   font-family: "Kapra Neue Expanded", Helvetica, Arial, sans-serif;