@drawnagency/primitives 0.1.79 → 0.1.81

package/src/document/components/DocSectionPage.tsx

@@ -0,0 +1,45 @@
+import type { DocImage, DocMeta } from "../engine/types";
+import type { DerivedPage } from "../engine/paginate";
+import { DocPage } from "./DocPage";
+
+export interface DocHost {
+  imageSrc: (image: DocImage, variant: "preview" | "print") => string;
+  variant: "preview" | "print";
+}
+
+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>
+      {page.textRegion ? (
+        <div
+          className="pdoc-text"
+          style={{ left: inch(page.textRegion.xIn), top: inch(page.textRegion.yIn), width: inch(page.textRegion.wIn) }}
+        >
+          {page.textBlocks.map((b, i) => {
+            const spacing = i > 0 ? { marginTop: inch(0.15) } : undefined;
+            if (b.kind === "heading") {
+              return b.level === 2 ? (
+                <h3 key={i} className="pdoc-h2" style={spacing}>{b.text}</h3>
+              ) : (
+                <h4 key={i} className="pdoc-h3" style={spacing}>{b.text}</h4>
+              );
+            }
+            return <div key={i} className="pdoc-prose" style={spacing} dangerouslySetInnerHTML={{ __html: b.html }} />;
+          })}
+        </div>
+      ) : null}
+      {page.imageBoxes.map((box, i) => (
+        <div
+          key={`${box.image.imageId}-${i}`}
+          className="pdoc-img"
+          style={{ left: inch(box.xIn), top: inch(box.yIn), width: inch(box.wIn), height: inch(box.hIn) }}
+        >
+          <img src={host.imageSrc(box.image, host.variant)} alt={box.image.alt} style={{ objectFit: box.fit }} />
+        </div>
+      ))}
+    </DocPage>
+  );
+}

package/src/document/components/DocViewer.tsx

@@ -0,0 +1,285 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import type { DocumentOptions } from "../engine/settings";
+import { settingsFor } from "../engine/settings";
+import type { Chunk, DocImage, DocSourceContent } from "../engine/types";
+import { DocCoverPage } from "./DocCoverPage";
+import { DocRail, entryId, type RailEntry } from "./DocRail";
+import { DocSectionPage, type DocHost } from "./DocSectionPage";
+import { useDocPages } from "./useDocPages";
+
+// 17in @96dpi = 1632×1056; the canvas scales the real page to fit its width.
+const PAGE_W = 1632;
+const PAGE_H = 1056;
+
+export interface DocViewerProps {
+  source: DocSourceContent | null;
+  document: DocumentOptions; // { enabled, meta, cover, sections } — PageSchema.document shape
+  host: DocHost;
+  mode: "present" | "edit";
+  // edit mode only:
+  selectedChunkId?: string | null;
+  onSelectChunk?: (chunkId: string | null) => void; // null = cover selected
+  onClose?: () => void; // present mode: close control
+  // Optional pagination-state hook (present mode unaffected — the present route
+  // never passes it). Fires, identity-guarded, whenever the internal useDocPages
+  // output changes, so a host (the edit overlay) can reuse this single pass for
+  // its inspector titles/warnings instead of running a second useDocPages.
+  onDocState?: (state: { chunks: Chunk[]; warningsByChunk: Record<string, string[]> }) => void;
+}
+
+// Rail-entry id → the chunk it belongs to (null for the cover).
+function chunkIdOf(id: string): string | null {
+  if (id === "cover") return null;
+  if (id.startsWith("ghost:")) return id.slice("ghost:".length);
+  if (id.includes("#")) return id.slice(0, id.lastIndexOf("#"));
+  return id;
+}
+
+export function DocViewer({
+  source,
+  document: doc,
+  host,
+  mode,
+  selectedChunkId,
+  onSelectChunk,
+  onClose,
+  onDocState,
+}: DocViewerProps) {
+  const { chunks, pages, measuring, warningsByChunk } = useDocPages({ source, sections: doc.sections });
+  const [activeId, setActiveId] = useState<string>("cover");
+  const [railOpen, setRailOpen] = useState(true);
+
+  // Resolve the cover's media-library image once here; missing id or missing
+  // source entry (deleted image) both degrade to null → solid cover.
+  const coverImage: DocImage | null = doc.cover.imageId ? (source?.images[doc.cover.imageId] ?? null) : null;
+
+  // Publish the pagination output to an optional host, guarded so it only fires
+  // when the memoized chunks/warnings identities actually change (and reading
+  // onDocState via a ref so an unstable callback identity can't cause a loop).
+  const onDocStateRef = useRef(onDocState);
+  onDocStateRef.current = onDocState;
+  const lastEmitRef = useRef<{ chunks: Chunk[]; warningsByChunk: Record<string, string[]> } | null>(null);
+  useEffect(() => {
+    if (lastEmitRef.current?.chunks === chunks && lastEmitRef.current?.warningsByChunk === warningsByChunk) return;
+    lastEmitRef.current = { chunks, warningsByChunk };
+    onDocStateRef.current?.({ chunks, warningsByChunk });
+  }, [chunks, warningsByChunk]);
+
+  // Present mode: excluded/empty chunks are simply absent. Edit mode: they
+  // surface as ghost entries (excluded takes priority over empty).
+  const entries: RailEntry[] = useMemo(() => {
+    const list: RailEntry[] = [{ kind: "cover" }];
+    for (const chunk of chunks) {
+      const s = settingsFor(doc.sections, chunk.id);
+      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" });
+        }
+      } else {
+        for (const page of pages.filter((p) => p.chunkId === chunk.id)) list.push({ kind: "page", page });
+      }
+    }
+    return list;
+  }, [chunks, pages, doc.sections, mode]);
+
+  const selectEntry = useCallback(
+    (id: string) => {
+      setActiveId(id);
+      if (mode === "edit") onSelectChunk?.(chunkIdOf(id));
+    },
+    [mode, onSelectChunk],
+  );
+
+  // Stale active-entry guard: if the active entry vanished (chunk excluded, page
+  // count shrank), re-point to the matching ghost or the cover. Guarded on
+  // !measuring so transient empty-`pages` frames during layout don't churn it.
+  useEffect(() => {
+    if (measuring) return;
+    if (entries.some((e) => entryId(e) === activeId)) return;
+    const chunkId = chunkIdOf(activeId);
+    const ghost = entries.find((e) => e.kind === "ghost" && e.chunkId === chunkId);
+    setActiveId(ghost ? entryId(ghost) : "cover");
+  }, [entries, activeId, measuring]);
+
+  // Controlled selection (edit): follow an externally-driven selectedChunkId.
+  // Undefined means uncontrolled — the viewer owns selection outright.
+  useEffect(() => {
+    if (mode !== "edit" || selectedChunkId === undefined) return;
+    if (chunkIdOf(activeId) === selectedChunkId) return;
+    if (selectedChunkId === null) {
+      setActiveId("cover");
+      return;
+    }
+    const match = entries.find(
+      (e) =>
+        (e.kind === "page" && e.page.chunkId === selectedChunkId) ||
+        (e.kind === "ghost" && e.chunkId === selectedChunkId),
+    );
+    if (match) setActiveId(entryId(match));
+  }, [selectedChunkId, mode, entries, activeId]);
+
+  // Arrow-key paging on `window`. Ignores events targeting form fields, clamps
+  // at the ends, preventDefault only when it consumes the key, listener removed
+  // on unmount. A ref keeps the handler reading the live active id without
+  // resubscribing on every step.
+  const activeIdRef = useRef(activeId);
+  activeIdRef.current = activeId;
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      const t = e.target as HTMLElement | null;
+      if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.tagName === "SELECT" || t.isContentEditable)) return;
+      let dir = 0;
+      if (e.key === "ArrowRight" || e.key === "ArrowDown") dir = 1;
+      else if (e.key === "ArrowLeft" || e.key === "ArrowUp") dir = -1;
+      else return;
+      e.preventDefault();
+      const ids = entries.map(entryId);
+      const cur = Math.max(0, ids.indexOf(activeIdRef.current));
+      const next = Math.min(ids.length - 1, Math.max(0, cur + dir));
+      if (ids[next] !== activeIdRef.current) selectEntry(ids[next]);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [entries, selectEntry]);
+
+  const active = entries.find((e) => entryId(e) === activeId) ?? null;
+
+  return (
+    // min-w-0 (here and on the rail/canvas row): without it these flex items
+    // refuse to shrink below their content width, and opening the rail shoves
+    // the overlay's inspector off the right edge instead of narrowing the
+    // canvas.
+    <div className="flex h-full min-h-0 min-w-0 flex-1 flex-col">
+      {mode === "present" ? (
+        <div className="flex items-center justify-between border-b border-base-200 bg-base px-4 py-2">
+          <span className="text-sm font-medium text-base-contrast">{source?.pageTitle ?? "Document"}</span>
+          {onClose ? (
+            <button
+              type="button"
+              aria-label="Close"
+              onClick={onClose}
+              className="rounded border border-base-200 px-3 py-1 text-xs font-medium text-base-contrast hover:bg-base-accent/30"
+            >
+              ✕
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+      <div className="flex min-h-0 min-w-0 flex-1">
+        {railOpen ? (
+          <DocRail
+            entries={entries}
+            selectedId={activeId}
+            meta={doc.meta}
+            cover={doc.cover}
+            coverImage={coverImage}
+            host={host}
+            onSelect={selectEntry}
+            onCollapse={() => setRailOpen(false)}
+          />
+        ) : (
+          <div className="flex w-10 shrink-0 flex-col border-r border-neutral-200 bg-neutral-50">
+            <button
+              type="button"
+              aria-label="Expand page rail"
+              onClick={() => setRailOpen(true)}
+              className="px-2 py-3 text-lg leading-none text-neutral-500 hover:text-neutral-800"
+            >
+              ›
+            </button>
+          </div>
+        )}
+        <DocCanvas
+          active={active}
+          cover={doc.cover}
+          coverImage={coverImage}
+          meta={doc.meta}
+          host={host}
+          measuring={measuring}
+          noContent={chunks.length === 0}
+        />
+      </div>
+    </div>
+  );
+}
+
+function DocCanvas({
+  active,
+  cover,
+  coverImage,
+  meta,
+  host,
+  measuring,
+  noContent,
+}: {
+  active: RailEntry | null;
+  cover: DocumentOptions["cover"];
+  coverImage: DocImage | null;
+  meta: DocumentOptions["meta"];
+  host: DocHost;
+  measuring: boolean;
+  noContent: boolean;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState(0.4);
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      const available = el.clientWidth - 48;
+      setScale(Math.min(0.75, Math.max(0.15, available / PAGE_W)));
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const note = (text: string) => <p className="mt-24 text-sm text-neutral-400">{text}</p>;
+
+  let body: ReactNode;
+  if (active?.kind === "cover") {
+    body = noContent ? (
+      <div className="flex flex-col items-center gap-4">
+        <Scaled scale={scale}>
+          <DocCoverPage cover={cover} meta={meta} image={coverImage} host={host} />
+        </Scaled>
+        <p className="text-sm text-neutral-400">This page has no displayable content.</p>
+      </div>
+    ) : (
+      <Scaled scale={scale}>
+        <DocCoverPage cover={cover} meta={meta} image={coverImage} host={host} />
+      </Scaled>
+    );
+  } else if (active?.kind === "page") {
+    body = (
+      <Scaled scale={scale}>
+        <DocSectionPage page={active.page} meta={meta} host={host} />
+      </Scaled>
+    );
+  } else if (active?.kind === "ghost") {
+    body = note(active.reason === "excluded" ? "Excluded — re-include from the inspector" : "No displayable content");
+  } else {
+    // Active id resolved to nothing — its page is still being measured.
+    body = measuring ? note("Laying out…") : note("This page has no displayable content.");
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="doc-canvas"
+      className="flex flex-1 items-start justify-center overflow-auto bg-neutral-100 p-6"
+    >
+      {body}
+    </div>
+  );
+}
+
+function Scaled({ scale, children }: { scale: number; children: ReactNode }) {
+  return (
+    <div className="shrink-0 overflow-hidden shadow-lg" style={{ width: PAGE_W * scale, height: PAGE_H * scale }}>
+      <div className="origin-top-left" style={{ transform: `scale(${scale})`, width: PAGE_W, height: PAGE_H }}>
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/document/components/Wordmark.tsx

@@ -0,0 +1,18 @@
+// Drawn script wordmark. Path data copied verbatim from
+// ~/drawn/frontend/src/components/shell/Logo.astro — do not edit paths by hand.
+export function Wordmark({ className }: { className?: string }) {
+  return (
+    <svg
+      viewBox="0 0 360 154.474"
+      fill="currentColor"
+      role="img"
+      aria-label="Drawn"
+      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M93.211 18.436c-2.177.868 2.024 1.375 6.374 5.14 3.913 3.392 5.542 6.526 8.126 5.794l.084-.019c15.002-4.018 30.605-4.343 45.642-3.985 37.577.895 76.5 13.868 127.052 10.736 52.074-3.226 64.063-33.293 64.423-35.34.335-1.903-4.473.223-6.71 1.341-2.461 1.23-12.375 22.056-56.817 24.605-54.58 3.13-76.949-13.42-127.948-16.105-24.157-1.272-44.308 1.912-60.225 7.832ZM353.301 104.05c-3.497-.813-8.22-.393-14.355 3.083a42.817 42.817 0 0 0-1.464.863l-.646.396c-.153.094-.302.192-.452.286-.185.121-.375.239-.56.36-.158.1-.315.202-.47.305-.18.119-.36.234-.539.354-.177.118-.353.235-.53.35l-.557.373c-.113.076-.23.15-.344.225-2.209 1.475-4.596 3.046-7.903 4.822l-.002-.001c-.178.093-.354.189-.534.285-.25.132-.504.264-.764.398-.28.145-.574.292-.87.442-.268.133-.537.269-.817.403-.32.16-.653.319-.988.477-.282.136-.561.27-.857.407a124.187 124.187 0 0 1-4.258 1.882c-22.372 9.426-46.637 12.894-83.75 9.349-37.286-3.562-76.22-13.87-126.593-10.74-51.887 3.228-63.837 33.296-64.195 35.346-.336 1.898 4.455-.225 6.685-1.345 2.45-1.228 12.332-22.055 56.612-24.603 54.385-3.132 84.076 13.469 131.52 17.447 34.494 2.89 59.914-3.453 77.117-14.422 3.42-2.183 6.945-4.758 10.342-7.353.093-.067.176-.134.264-.202.111-.085.217-.168.329-.25.563-.434 1.122-.87 1.68-1.302.098-.077.2-.152.3-.23 1.027-.8 2.038-1.593 3.021-2.37 2.518-1.98 4.866-3.835 6.939-5.395l.823-.614.382-.28c.344-.251.675-.49.999-.718a42.728 42.728 0 0 1 1.547-1.058c.07-.047.14-.084.206-.13.31-.197.608-.379.89-.544.094-.054.189-.11.281-.16a12.3 12.3 0 0 1 .933-.486c4.427-2.017 8.968-2.27 9.22 1.837.124 2.074-1.999 4.029-5.691 4.449-2.565.292-6.454.442-9.699-.803-.026-.012-.048-.012-.077-.023-.5-.17-1.841 1.036-2.762 2-.922.966-2.05 1.673-1.084 2.163 4.29 2.29 8.832 3.056 11.611 3.137 8.07.221 14.336-1.887 15.567-8.04.93-4.653-1.559-9.227-6.507-10.371Z" />
+      <path d="M340.048 55.675c-3.094-2.81-8.125-2.34-11.568-2.069-5.92.466-11.54 3.713-15.45 6.582-.477-3.394-1.684-5.828-3.908-6.64-6.393-2.34-11.45 2.035-16.42 5.387-1.95 1.254-4.322-4.012-5.878-4.895-1.55-.882-4.995-1.347-7.803.126-4.404 2.305-7.465 5.91-7.21 8.136.257 2.297 4.149 4.28 4.065 6.879-.13 4.019-2.04 7.87-4.668 13.225-1.998 4.068-4.108 7.762-6.38 10.711-1.537 1.954-3.631 4.144-6.278 5.748-.514.277-1.04.496-1.57.685-3.299.82-4.712-3.26-3.843-8.882 1.006-6.444 9.235-29.756 9.738-30.966.502-1.21-.382-1.121-2.396-1.49-2.015-.37-6.724-.041-8.45.241-1.727.279-5.21 15.477-7.354 22.253-2.143 6.778-5.96 14.898-8.942 17.284-2.568 2.058-4.896 3.11-7.137 2.31-6.262-2.243-2.25-19.315 1.117-28.63 3.801-10.515 9.353-20.009 6.934-19.91-5.368.224-11.976 2.01-13.28 4.058-2.33 3.673-8.074 21.308-9.999 26.677-1.072 2.989-1.506 6.316-1.412 9.579-1.124.544-6.17 6.036-12.888 5.767-7.49-.303 4.697-29.98 5.369-31.32.67-1.342-11.354-1.567-12.026-.222-.668 1.34-6.037 31.487-20.409 31.487-10.457 0-5.145-25.45 7.604-34.614 10.985-7.9 25.36-2.188 26.924-2.862 1.565-.668 4.17-9.668 4.17-10.786s-4.698-1.119-18.792-.222c-14.09.893-21.92 7.38-30.195 20.69-8.278 13.31-10.068 26.73-19.412 26.73-9.22 0-1.169-18.788 3.082-27.738 4.248-8.946 6.937-17.895 5.592-19.907-1.343-2.014-16.332-.46-17.673-1.58-1.344-1.119 1.121-3.12.45-4.913-.67-1.787-10.515-1.787-14.205 0-1.887.916-2.185 3.287-2.021 5.893 1.254 7.163 1.232 14.979-.318 22.603.064.302.197.384.438.138 2.586-2.63 8.876-11.227 9.55-12.12.669-.897 8.836-.71 9.239.043.645 1.203-6.796 17.224-8.723 22.59-3.61 10.057-2.573 16.894 2.973 20.234 4.967 2.996 9.777 2.584 16.73-1.624 6.977-4.222 9.599-6.526 9.599-6.526s0 14.087 15.437 14.087c11.406 0 14.089-8.048 14.089-8.048s1.797 10.698 12.414 9.087c6.176-.937 11.652-9.47 13.41-12.763 1.045 6.066 3.97 11.25 8.174 12.625 5.887 1.922 13.06.388 19.818-4.645a15.195 15.195 0 0 0 2.495-2.362c2.356 5.703 5.865 9.538 9.681 10.008 19.478 2.399 28.458-19.807 33.299-34.217.993-2.955 1.71-5.846 2.654-9.364.268-1.007 1.183-2.504 2.994-2.939 4.188-.933 7.848-1.282 8.583.371 3.784 8.503-13.171 43.36-10.747 43.36 3.3 0 10.047-1.037 12.48-4.353 4.145-5.64 10.948-25.812 11.45-39.149 2.636-2.101 5.458-3.664 8.179-3.883 9.395-.757 6.167 14.162 3.22 22.537-4.906 13.966-3.351 22.982.632 28.735.709.9 1.775-.014 3.49-.917 1.718-.906 2.7-1.413 2.527-2.26-.011-.062-.019-.12-.029-.183-1.323-5.592 3.407-13.519 7.318-24.085 3.762-10.158 7.001-24.749 1.465-29.782ZM46.09 89.63c1.282-2.736 2.616-5.56 4.002-8.468C56.528 67.684 66.09 53.946 75.049 46.32a80.636 80.636 0 0 1 14.747-9.98c.07-.044.148-.092.221-.132 1.173-.631 1.17-1.394-.013-3.301-1.354-2.185-3.87-4.955-8.296-7.144-1.703-.842-3.224-.362-4.618.396-4.817 2.932-9.012 6.161-12.569 9.6C46.448 53.23 37.23 76.32 33.231 88.318l-1.407 4.22c-.406 1.22-.8 2.397-1.185 3.546l-.149.437c-.38 1.13-.748 2.214-1.11 3.27-.008.02-.014.043-.022.061-.993 2.89-1.932 5.525-2.846 7.885h-.01c-.22.568-.44 1.153-.66 1.689l-.006.015a79.329 79.329 0 0 1-1.105 2.609 51.44 51.44 0 0 1-1.022 2.16l-.106.22c-2.926 5.805-5.963 8.77-10.193 8.77-8.5 0-6.377-11.156 6.71-15.516a18.611 18.611 0 0 1 3.791-.83c.064-.01.118-.024.188-.035 1.761-.268 1.54-1.49 2.059-3.246.376-1.273 1.282-2.543-.193-2.404a57.899 57.899 0 0 0-6.293 1.147c-23.152 5.477-24.366 25.123-11.446 28.413 9.656 2.457 17.26-3.099 23.006-11.475.24-.356.493-.743.75-1.154.084-.132.173-.28.26-.42.177-.29.354-.584.54-.901.102-.175.208-.362.313-.545.176-.305.355-.623.537-.95.11-.198.22-.393.33-.598.198-.364.4-.74.604-1.122.098-.188.197-.368.294-.557.304-.578.614-1.173.93-1.796.028-.052.055-.112.083-.164l.337-.668c1.406-2.791 2.94-5.988 4.603-9.504 1.64-3.475 3.4-7.248 5.277-11.245Z" />
+      <path d="M79.206 111.375c35.531-11.52 39.87-52.054 28.828-74.15a34.694 34.694 0 0 0-2.573-4.302c-4.379-6.306-10.605-10.865-17.802-14.027-5.346-2.35-11.22-3.94-17.254-4.914C43.94 9.708 6.14 18.749 5.74 39.95 5.354 60.374 30.548 57.9 32.533 58.025c2.247.14 1.678-1.678-.67-4.028-2.35-2.347-7.946-7.147-7.382-15.433.844-12.415 17.78-22.482 44.612-18.03 3.758.625 6.956 1.438 9.75 2.425 8.204 2.907 12.703 7.418 16.072 13.73a55.714 55.714 0 0 1 2.154 4.559c8.11 19.313-4.926 52.567-24.438 59.737-14.466 5.317-21.625 3.08-29.713 1.281-1.304-.287-1.495 1.185-2.543 3.446-1.047 2.264-2.092 3.906-1.052 4.293 9.395 3.44 20.77 7.563 39.883 1.37Z" />
+    </svg>
+  );
+}

package/src/document/components/measure.tsx

@@ -0,0 +1,105 @@
+import { useEffect, useLayoutEffect, useState } from "react";
+import { DOC_GEOM } from "../engine/paginate";
+import type { SectionSettings } from "../engine/settings";
+import type { Chunk, TextBlock } from "../engine/types";
+
+const PX_PER_IN = 96;
+
+function widthInFor(settings: SectionSettings | undefined): number {
+  return settings?.textPlacement === "leftColumn" ? DOC_GEOM.leftColWIn : DOC_GEOM.bodyWIn;
+}
+
+function blockClassName(block: TextBlock): string {
+  if (block.kind === "heading") return block.level === 2 ? "pdoc-h2" : "pdoc-h3";
+  return "pdoc-prose";
+}
+
+// Content that affects a block's measured height, serialized so the
+// re-measure effect can key on structural equality rather than object
+// identity (chunks are re-derived on every harvest() call). JSON-encoded —
+// hand-joined delimiters can occur verbatim in content, letting two different
+// block lists collide and the re-measure effect never fire.
+function signatureFor(chunks: Chunk[], settingsMap: Record<string, SectionSettings>): string {
+  return JSON.stringify(
+    chunks.map((c) => [
+      c.id,
+      widthInFor(settingsMap[c.id]),
+      c.textBlocks.map((b) => (b.kind === "heading" ? ["h", b.level, b.text] : ["p", b.html])),
+    ]),
+  );
+}
+
+// Measures every text block of every chunk by rendering it into a hidden,
+// fixed-position container at the chunk's real text width with the real
+// pdoc-* classes (see document.css `.pdoc-measure`) — plain DOM nodes, not a
+// React subtree, since measurement needs no reconciliation or events, only
+// the browser's own layout of the real markup shape. Blocks get no CSS
+// margins (pagination owns inter-block spacing via `gapIn`), so a wrapper's
+// offsetHeight is the whole truth.
+export function useTextMeasurements(
+  chunks: Chunk[],
+  settingsMap: Record<string, SectionSettings>,
+): { heights: Record<string, number[]> | null } {
+  const [heights, setHeights] = useState<Record<string, number[]> | null>(null);
+  const [fontsReady, setFontsReady] = useState(false);
+
+  // jsdom (tests) has no document.fonts — optional-chain so this resolves
+  // immediately there instead of hanging measurement forever.
+  useEffect(() => {
+    let cancelled = false;
+    const markReady = () => {
+      if (!cancelled) setFontsReady(true);
+    };
+    // A rejected `fonts.ready` (e.g. a font failing to load) must not wedge
+    // `measuring` true forever — fall back to treating fonts as ready so
+    // measurement still runs with whatever's loaded.
+    Promise.resolve(document.fonts?.ready).then(markReady).catch(markReady);
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const signature = signatureFor(chunks, settingsMap);
+
+  useLayoutEffect(() => {
+    if (!fontsReady) return;
+    const containers: HTMLDivElement[] = [];
+    const next: Record<string, number[]> = {};
+
+    for (const chunk of chunks) {
+      if (chunk.textBlocks.length === 0) {
+        next[chunk.id] = [];
+        continue;
+      }
+      const container = document.createElement("div");
+      container.className = "pdoc-measure";
+      container.style.width = `${widthInFor(settingsMap[chunk.id])}in`;
+      document.body.appendChild(container);
+      containers.push(container);
+
+      const measured: number[] = [];
+      for (const block of chunk.textBlocks) {
+        const wrapper = document.createElement("div");
+        wrapper.className = blockClassName(block);
+        if (block.kind === "heading") {
+          wrapper.textContent = block.text;
+        } else {
+          wrapper.innerHTML = block.html;
+        }
+        container.appendChild(wrapper);
+        measured.push(wrapper.offsetHeight / PX_PER_IN);
+      }
+      next[chunk.id] = measured;
+    }
+
+    setHeights(next);
+    return () => {
+      for (const container of containers) container.remove();
+    };
+    // Re-measure only when chunk/width content actually changes, or once
+    // fonts finish loading (font swap changes heights).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [signature, fontsReady]);
+
+  return { heights };
+}

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;
+}