@drawnagency/primitives 0.1.80 → 0.1.81

package/src/document/components/DocRail.tsx

@@ -0,0 +1,160 @@
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import type { DerivedPage } from "../engine/paginate";
+import type { DocCover } from "../engine/settings";
+import type { DocImage, DocMeta } from "../engine/types";
+import { DocCoverPage } from "./DocCoverPage";
+import { DocSectionPage, type DocHost } from "./DocSectionPage";
+
+// 17in @96dpi = 1632px wide; thumbnails render the real page scaled to fill the
+// rail width at a locked 17:11 aspect ratio (mirrors the harness PageRail).
+const PAGE_W = 1632;
+const PAGE_H = 1056;
+
+export type RailEntry =
+  | { kind: "cover" }
+  | { kind: "page"; page: DerivedPage }
+  | { kind: "ghost"; chunkId: string; title: string; reason: "excluded" | "empty" };
+
+export function entryId(entry: RailEntry): string {
+  if (entry.kind === "cover") return "cover";
+  if (entry.kind === "page") return entry.page.id;
+  return `ghost:${entry.chunkId}`;
+}
+
+function ThumbButton({
+  id,
+  selectedId,
+  scale,
+  label,
+  indent,
+  onSelect,
+  children,
+}: {
+  id: string;
+  selectedId: string;
+  scale: number;
+  label: string;
+  indent?: boolean;
+  onSelect: (id: string) => void;
+  children: ReactNode;
+}) {
+  return (
+    <li className={indent ? "pl-4" : undefined}>
+      <button
+        type="button"
+        onClick={() => onSelect(id)}
+        className={`relative block w-full rounded border-2 bg-white ${
+          id === selectedId ? "border-teal-600" : "border-neutral-200 hover:border-neutral-300"
+        }`}
+      >
+        <span className="pointer-events-none block w-full overflow-hidden aspect-[17/11]">
+          <span
+            className="block origin-top-left"
+            style={{ transform: `scale(${scale})`, width: PAGE_W, height: PAGE_H }}
+          >
+            {children}
+          </span>
+        </span>
+        <span className="absolute bottom-0.5 left-1 max-w-[90%] truncate text-[10px] text-neutral-400">
+          {label}
+        </span>
+      </button>
+    </li>
+  );
+}
+
+export function DocRail({
+  entries,
+  selectedId,
+  meta,
+  cover,
+  coverImage,
+  host,
+  onSelect,
+  onCollapse,
+}: {
+  entries: RailEntry[];
+  selectedId: string;
+  meta: DocMeta;
+  cover: DocCover;
+  coverImage?: DocImage | null;
+  host: DocHost;
+  onSelect: (id: string) => void;
+  onCollapse: () => void;
+}) {
+  const listRef = useRef<HTMLOListElement>(null);
+  const [scale, setScale] = useState(0.11);
+  useEffect(() => {
+    const el = listRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const obs = new ResizeObserver(() => {
+      // content width = list width minus the button's 2px border on each side
+      const w = el.clientWidth - 4;
+      if (w > 0) setScale(w / PAGE_W);
+    });
+    obs.observe(el);
+    return () => obs.disconnect();
+  }, []);
+
+  return (
+    <nav
+      data-testid="doc-rail"
+      className="flex w-52 shrink-0 flex-col overflow-y-auto border-r border-neutral-200 bg-neutral-50 p-3"
+    >
+      <button
+        type="button"
+        aria-label="Collapse page rail"
+        onClick={onCollapse}
+        className="mb-2 flex w-full items-center justify-between rounded px-2 py-1.5 text-sm font-medium text-neutral-600 hover:bg-neutral-100 hover:text-neutral-900"
+      >
+        <span>Pages</span>
+        <span aria-hidden="true" className="text-lg leading-none">‹</span>
+      </button>
+      <ol ref={listRef} className="flex flex-col gap-2">
+        {entries.map((entry) => {
+          const id = entryId(entry);
+          if (entry.kind === "cover") {
+            return (
+              <ThumbButton key={id} id={id} selectedId={selectedId} scale={scale} label="Cover" onSelect={onSelect}>
+                <DocCoverPage cover={cover} meta={meta} image={coverImage} host={host} />
+              </ThumbButton>
+            );
+          }
+          if (entry.kind === "page") {
+            return (
+              <ThumbButton
+                key={id}
+                id={id}
+                selectedId={selectedId}
+                scale={scale}
+                label={entry.page.title}
+                indent={entry.page.cont}
+                onSelect={onSelect}
+              >
+                <DocSectionPage page={entry.page} meta={meta} host={host} />
+              </ThumbButton>
+            );
+          }
+          return (
+            <li key={id}>
+              <button
+                type="button"
+                onClick={() => onSelect(id)}
+                className={`flex w-full items-center justify-between gap-2 rounded border px-2 py-2 text-left text-xs ${
+                  id === selectedId
+                    ? "border-teal-600 bg-white"
+                    : "border-dashed border-neutral-300 bg-neutral-50 hover:border-neutral-400"
+                }`}
+              >
+                <span className="truncate text-neutral-400">{entry.title}</span>
+                <span className="shrink-0 rounded bg-neutral-200 px-1 text-[10px] uppercase tracking-wide text-neutral-500">
+                  {entry.reason}
+                </span>
+              </button>
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

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