konpeki 0.3.0 → 0.4.0

package/skills/konpeki/floor.md

@@ -0,0 +1,76 @@
+# Authoring floor
+
+Read this immediately before writing or revising HTML. These are the rules
+agents break when working from habit. Each has an ID. `inspect` reports the
+`(inspect)` rules as diagnostics under the same code, and `render` prints the
+`(review)` rules as the checklist for looking at the page.
+
+Fix every floor warning or justify keeping it in your final report. An opt-out
+attribute such as `data-kp-allow="label-above-headline"` needs that
+justification too.
+
+## Bans
+
+No brief, theme or habit earns these back.
+
+- `label-above-headline` (inspect): No label, kicker, eyebrow or metadata line
+  above a headline or section heading. Put the product, date, series or source
+  in the headline, the supporting line, a caption or the footer. Running heads
+  repeated across multi-page print are exempt. A label the brief requires, such
+  as Before/After, sits outside the headline's column.
+- `stranded-word` (inspect): No headline line holds one stranded word after a
+  fuller line, including the line before a `<br>`. Reword it or change its
+  measure; break with `<br>` only where the meaning divides. Never shrink type
+  to fit.
+- `restated-takeaway` (review): State the takeaway once: a subtitle, caption,
+  callout or note adds evidence, a qualification or a next step, never the
+  headline in other words.
+- `slogan-copy` (review): No slogan contrasts ("Not a feature. A platform.",
+  "a signal, not proof") and no chains of em dashes. Keep a "not X" clause only
+  where it corrects a likely misreading, such as concentrations, not emissions.
+- `decorative-container` (review): No panel, card, badge or pill unless it marks
+  a distinct object, state or contrasting field, and never a panel inside a
+  panel. Use space, alignment and rules first.
+- `honest-encoding` (review): Amount bars start at zero, arrows point the true
+  direction, and nothing implies causal, temporal or quantitative meaning the
+  source lacks. Colour never carries meaning alone; pair it with a label, shape
+  or position.
+
+## Defaults
+
+The brief or a theme's `NOTES.md` may override these, explicitly.
+
+- `headline-first` (review): Reading starts with the headline, and the headline
+  states the claim. "Cold starts fell 62%" is a claim; "Q3 results" is a topic.
+- `one-focus` (review): Accent marks the headline and at most one other element:
+  the main claim, path or data point. Everything else uses ink, muted ink or
+  categorical colour.
+- `format-budget` (review): Fit content to the viewing size: a link card holds a
+  headline, one supporting line and a date, and a slide holds one idea. Full
+  detail belongs on the one-pager or report.
+- `grouping` (review): Space shows grouping: an item sits closer to what it
+  qualifies than to the next subject, and true peers share size, weight and
+  treatment. New edges align with existing ones.
+- `page-footer` (review): Keep page-level source notes and page numbers together
+  in a reserved footer, clear of body content. Reserve that space in the first
+  layout, not after filling the page. Do not pin the page number independently
+  while leaving its source note in body flow. Citations that explain a specific
+  figure or claim still belong beside that content.
+- `diagram-economy` (review): A diagram uses at most three box styles, each with
+  a meaning. Arrowheads scale with the stroke (`markerUnits="strokeWidth"`) and
+  stay clear of labels.
+
+## Verify
+
+`inspect` enforces these as errors or warnings; read the diagnostic message.
+
+- `small-text` (inspect): Text is at least 24 CSS px on screen presets and 11 on
+  A4. These are floors for small print, not sizes for body text.
+- `low-contrast` (inspect): Text contrast is at least 4.5:1, or 3:1 for large
+  text, including nested roles and code on contrasting fields.
+- `text-overflow`, `clipped-text`, `text-overlap`, `page-overflow` (inspect):
+  Nothing leaves the page, hides behind a clip or collides. Recompose; do not
+  hide, truncate or shrink required copy.
+- `font-fallback` (inspect): Every glyph comes from a loaded webfont, whether
+  Google-hosted, local, or embedded. Supply the required subsets, weights, and
+  styles; do not rely on installed-font fallback or synthesized faces.

package/skills/konpeki/references/cover.md

@@ -0,0 +1,27 @@
+# Cover or social graphic
+
+Use for a cover, thumbnail, link preview, announcement image, or social graphic.
+Apply the [shared guidance](../SKILL.md#before-authoring) and the
+[authoring floor](../floor.md); this is not a miniature document.
+
+- Use the requested destination dimensions and crop. If none are supplied for
+  a general link-preview cover, start with the theme's `link` preset. Square,
+  portrait, and other ratios are equally valid for their intended channels.
+- Make the main subject or message recognizable at thumbnail size. Let imagery
+  lead when it communicates the subject; do not require a large slogan on every
+  cover. Keep supporting copy short without stripping essential qualifications.
+- A deliberate headline break may improve composition. Check the actual words
+  and font rather than fixing a line count or inserting breaks into every label.
+- Keep essential text, faces, logos, and marks clear of the expected crop and
+  platform overlays. Do not invent universal safe-area numbers; use the brief's
+  placement requirements or verify the destination when placement is critical.
+- Use supplied or approved imagery and preserve its meaning. Do not stretch
+  images, crop away evidence, or imply an unverified product interface is real.
+- For mixed compositions, use [text with visuals](patterns.md#text-with-visuals)
+  to choose the image role, crop, text region, and any edge or contrast treatment.
+  Do not add badges, eyebrows, metadata, or a call to action simply because other
+  covers contain them.
+
+Inspect both the full-resolution export and a reduced preview at the intended
+viewing size. Verify the headline remains legible and essential details survive
+the expected crop. Export PNG at the requested size; PDF is optional if requested.

package/skills/konpeki/references/long-document.md

@@ -0,0 +1,40 @@
+# Multi-page long document
+
+Use for reports, essays, field guides, proposals, and other sustained reading.
+Apply the [shared guidance](../SKILL.md#before-authoring) and the
+[authoring floor](../floor.md), not slide-density conventions.
+
+- Start with the theme's portrait `a4` preset for an unspecified printable
+  document; honor Letter or other destination sizes. Keep margins, body
+  typography, and heading levels consistent across pages.
+- Test the page structure before filling the document: a short page and a dense
+  page, both with multiline source notes. Apply the floor's `page-footer` rule.
+  A flex-column page with non-shrinking body and footer, and `margin-top: auto`
+  on the footer, puts spare space above it rather than between its parts.
+  Check the same bottom margin and body clearance on both pages; neither may
+  rely on hiding overflow or shrinking text. Then reuse that structure.
+- Organize the argument into sections before dividing it into pages. Use normal
+  HTML text flow within each page, not separately positioned lines or sentences.
+  Choose line measure and leading for continuous reading at the delivered size.
+- Author every page explicitly. Konpeki will not flow an overflowing paragraph
+  into a new page; CSS print-break hints do not replace `data-page` boundaries.
+  Measure real text with the loaded fonts before deciding where to split it.
+- Keep headings with their opening paragraph and captions with their figures.
+  Avoid isolated first or last lines and stranded short list items. Split a long
+  paragraph only at a readable boundary, preserving its wording and punctuation.
+- Keep complete table rows together. When a table spans pages, repeat its
+  column headings and make units and continuation clear. Do not silently drop
+  rows, references, or qualifications to meet a page count.
+- Use page numbers for navigation. Add running titles or a contents page only
+  when the length and structure warrant them. Keep footnotes and citations with
+  the claims they qualify; essential evidence is not decorative footer clutter.
+- On revision, recheck the following pages: a changed paragraph can alter the
+  best page breaks even when the edited page no longer overflows.
+
+Inspect every PDF page, including the final page, for continuity, uneven density,
+awkward breaks, missing text, and footer grouping and clearance. Compare page
+endings across the document; a detached footer can pass overflow checks. Review
+text extraction order when searchable or accessible reading is part of delivery.
+
+The footer check comes from the VulcanBench SWE-v4 report: its source note floated
+above an independently pinned page number despite passing overflow inspection.

package/skills/konpeki/references/one-pager.md

@@ -0,0 +1,27 @@
+# One-pager or card
+
+Use for a bounded brief, summary, reference sheet, invitation, or information
+card. Apply the [shared guidance](../SKILL.md#before-authoring) and the
+[authoring floor](../floor.md). A résumé or presentation slide uses its own guide
+even when it contains only one page.
+
+- Deliver one explicit page. Use the `a4` preset for an unspecified printable
+  one-pager; for a card, choose dimensions for its destination. Landscape, portrait,
+  square, and custom sizes are all valid; do not force cards into a slide ratio.
+- Establish the page's reader task: understand a proposal, compare options,
+  recall information, or act on an invitation. Let that task determine emphasis
+  and section order instead of imposing a fixed number of content blocks.
+- Retain the evidence needed to interpret the main message. A headline, a
+  prominent number, and a call to action are not sufficient if scope, units,
+  conditions, or supporting facts have disappeared.
+- Use columns for genuinely parallel or scannable material. Use flowing prose
+  for an argument. Do not turn every paragraph into an equally prominent card.
+- Add contact details or a next action only when the brief calls for them.
+  Keep them findable without giving boilerplate the same weight as the content.
+- Treat the one-page limit as an editorial constraint, not permission to use
+  tiny type. Condense repetition and recompose; if required content still cannot
+  fit legibly, surface that conflict rather than adding a second page silently.
+
+Check the whole page at its intended print or display size, including small cards.
+Whitespace should reveal hierarchy, not leave essential copy crowded into one
+corner while a decorative region consumes the page.

package/skills/konpeki/references/patterns.md

@@ -0,0 +1,118 @@
+# Content and visual patterns
+
+Read only the sections that occur in the work, after the
+[shared guidance](../SKILL.md#before-authoring) and [authoring floor](../floor.md).
+Choose by the audience's question, not a favorite layout. Plain text or an image
+may be enough. Infer the form without asking the user to choose a diagram taxonomy;
+preserve an explicitly requested form unless a change is agreed.
+
+## Text with visuals
+
+Use when text shares a composition with photography, screenshots, illustrations,
+charts, diagrams, or other graphic elements, in any output format.
+
+- Decide the visual's role: evidence, explanation, main subject, or atmosphere.
+  A chart remains evidence even when it looks decorative. A screenshot may
+  contain text the reader needs to read; budget for that at delivery size.
+  Keep supporting text that adds meaning, not a caption just to fill a region.
+- Plan the crop, focal subject, and text region together before filling the
+  page. Keep text clear of faces, subjects, meaningful details, and data marks.
+  Do not finish the visual and squeeze required copy into the remaining space.
+- Use side-by-side regions when text and visual explain each other and both
+  remain readable. Stack them when the format is narrow or the visual needs
+  full width. Overlay text when the image has a suitable text region or its
+  atmosphere should fill the composition. These are choices, not fixed templates.
+- For two columns, give text the claim and interpretation, and the visual the
+  evidence or explanation; avoid repetition. Allocate width for readable visual
+  details and a useful text measure, not an automatic 50/50 split. Align meaningful
+  anchors such as the headline and plot area, accounting for whitespace inside
+  an image. Keep captions, units, legends, and sources with their visual. Recompose
+  into stacked regions rather than squeezing both columns in a narrow format.
+- First find a readable text region through placement: beside the visual or
+  in quiet image space. Add an opaque field over an image only when needed for
+  required text, not to demonstrate a treatment. Separate regions need not be
+  cards, and white is only one field color. Set its ink explicitly, including
+  nested type roles; a contrast field should not obscure meaningful content.
+- Use local darkening or lightening to support text when the image can retain
+  its meaning. Use an edge gradient or mask when an atmospheric image needs to
+  blend into the surrounding field; a clean edge is equally valid. Apply the
+  effect to the image or a separate overlay, never to the text or a shared
+  parent. Do not use text shadows as a substitute for a readable region.
+- Keep informational visuals intact. Do not fade chart marks or axes, hide
+  screenshot details, or turn a meaningful diagram into background texture.
+  Place explanations near what they qualify, with clearance from marks and
+  labels. Preserve aspect ratio and meaningful relative scale; identify crops
+  and alterations when they could change how evidence is interpreted.
+- Review the final crop at delivery size and reduced size, not just enlarged.
+  Include captions, sources, and qualifications in that review. Check local
+  contrast under every line, subject visibility, effect boundaries, and whether
+  the visual still communicates its purpose. Solid-color contrast checks cannot
+  establish readability over images, gradients, or masks.
+
+## Charts and quantities
+
+- Choose the encoding for the question: comparison, change over time,
+  distribution, or parts of a whole. Preserve units, denominators, time windows,
+  uncertainty, missing values, and sources.
+- Apply the floor's `honest-encoding` rule. Make scales explicit; distinguish
+  a truncated axis from a complete magnitude. Keep scales consistent across
+  charts meant to be compared.
+- Derive mark lengths, areas, and positions from the supplied values, not visual
+  guesses. For parts or branches, reconcile totals and explain any remainder.
+- Keep labels near their marks and give annotations clearance from marks and
+  axes. Do not turn uncertain or illustrative data into apparently measured
+  precision.
+
+## Tables
+
+- Use a table for exact lookup or repeated attributes, not merely to position
+  unrelated paragraphs. Name columns and units; align comparable numbers and
+  use consistent precision. Distinguish zero, unavailable, and not applicable.
+- Align short row labels with the first line of multiline descriptions. Let
+  rows grow with content; do not hide a long cell to maintain equal heights.
+- Use rules or fills when they clarify rows, groups, or totals. A table-ending
+  rule belongs to the table, not the page footer. Keep notes clear of that rule.
+- On continued tables, preserve complete rows and repeat the information needed
+  to interpret the next page.
+
+## Comparisons and decisions
+
+- Compare options against the same criteria, units, and scope. Preserve material
+  drawbacks and unknowns; do not invent scores to create a neat ranking.
+- Align corresponding rows or measures so the reader need not reconstruct the
+  mapping. Different evidence lengths do not require identical box heights.
+- Make a recommendation distinguishable from the evidence. Keep its conditions
+  near it rather than presenting a conditional choice as universally best.
+
+## Processes and sequences
+
+- Show inputs, actors or steps, outcomes, and meaningful blockers. Label branches
+  and return paths; pending is not approved and retrying is not completed.
+- Use arrows only for supported direction, dependency, or order. Preserve message
+  order and named participants when time is the story. Label asynchronous work,
+  failure paths, and guarded transitions when those distinctions matter.
+- Give every connector an identifiable source and destination. Route it clear
+  of labels and unrelated nodes; near-touches must not imply junctions. Useful
+  elbows are preferable to diagonal fans or detached endpoints. Check arrowheads
+  and shafts at delivery size, not just coordinate bounds.
+
+## Systems and hierarchies
+
+- Name entities, connections, and meaningful boundaries. Use enclosure only for
+  actual containment, ownership, or scope; proximity alone must not invent one.
+- Keep parent-child meaning consistent. Use a system map rather than a tree
+  when shared ownership or cross-links are central to the explanation.
+- Label connection meaning and direction. A static dependency map is not an
+  execution trace; use a sequence when event order is the reader's question.
+- Preserve specialized notation when requested. Draw it directly in HTML/SVG;
+  do not invent a component schema or convert every relationship to one box type.
+
+## Annotated details
+
+- Retain enough context to locate the detail. Put labels near the relevant
+  evidence and make crops or mockups explicit.
+- Verify what the artifact actually demonstrates; do not add unsupported
+  specifications or measurements. An annotation should clarify, not obscure.
+
+Inspect the rendered pattern: are relationships, quantities, and labels clear
+without narration? Browser overflow checks cannot establish their truth.

package/skills/konpeki/references/resume.md

@@ -0,0 +1,28 @@
+# Résumé
+
+Use for a résumé or CV, even when it is a single page. Apply the
+[shared guidance](../SKILL.md#before-authoring) and the
+[authoring floor](../floor.md); do not treat it as a marketing slide or a generic card.
+
+- Start with the theme's portrait `a4` preset; use Letter or another size when
+  the destination calls for it. Let relevant supplied experience determine
+  length rather than assuming every résumé must fit one page.
+- Make the person's name, contact details, and relevant experience easy to scan.
+  Choose section order for the candidate and role; do not manufacture a summary,
+  project, award, or skills section merely to fill a template.
+- Keep organization, role, dates, and location unambiguous. Use consistent date
+  formatting and clear chronology; align dates without detaching them from the
+  role they describe.
+- Write concise evidence-led accomplishments from supplied facts. Never invent
+  metrics, seniority, qualifications, or causal claims. Preserve materially
+  different roles rather than merging them to make the layout cleaner.
+- Start with a simple reading order and flowing text. Use additional columns
+  only when they remain readable and extract in the intended order. Avoid
+  skill-rating bars and icon-only contact information.
+- Keep a role heading with its first accomplishment. Prefer breaks between
+  roles or sections; if an entry must continue, make that continuation clear.
+  Remove low-value repetition before reducing type to meet a page limit.
+
+Inspect the PDF at normal reading size. Check contact text, links, dates,
+selectable text, and extraction order. Do not claim ATS compatibility from
+appearance or a clean overflow report alone.

package/skills/konpeki/references/slides.md

@@ -0,0 +1,28 @@
+# Landscape slides
+
+Use for presentation pages or a deck, including a single slide. Apply the
+[shared guidance](../SKILL.md#before-authoring) and the
+[authoring floor](../floor.md); the brief overrides format defaults below.
+
+- Start with the theme's 16:9 `presentation` preset when the destination
+  supplies no size. Honor a requested ratio and keep deck dimensions consistent
+  unless a mixed-size deliverable is intentional.
+- Build a reading sequence: each page advances the explanation rather than
+  repeating the previous page's conclusion. Do not impose a fixed opening,
+  agenda, or closing-page formula on every brief.
+- Give a page one main point and enough evidence to support it. A takeaway
+  headline is useful; a giant headline that displaces the explanation is not.
+- Compose for viewing at a distance. Start with the preset's resolved type
+  roles, then check the intended view; the small-text floor is not a body-copy
+  target. Keep sources, units, and caveats legible too.
+- Prefer short, coherent text groups over document-length paragraphs. Use a
+  diagram, chart, image, or comparison when it carries the explanation; do not
+  require a visual on every page or flatten every idea into matching cards.
+- When content exceeds a page, redistribute it into a meaningful sequence
+  rather than shrinking everything. Respect an explicit page-count constraint.
+- Keep recurring type, margins, and semantic colors consistent while varying
+  composition when the content changes. A title page need not dictate every page.
+
+Review the deck at fitted size and in reading order. Check that comparisons use
+the same criteria and scales, and that each page remains understandable without
+presenter notes. Konpeki delivers static pages, not a presentation player.

package/skills/konpeki/scripts/ensure-runtime.mjs

@@ -1,23 +1,22 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // A copied skill must resolve a known runtime, not follow repo-relative links.
-const version = "0.3.0";
-const probeDocument = fileURLToPath(new URL("../assets/blank.json", import.meta.url));
+const version = "0.4.0";
+const probeDocument = fileURLToPath(new URL("../assets/blank.html", import.meta.url));
 function runtime(root) {
   try {
     const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
     if (pkg.name !== "konpeki" || pkg.version !== version) return;
     const cli = join(root, pkg.bin.konpeki);
     const sourceCLI = join(root, "bin/konpeki.mjs");
-    if (!["AGENTS.md", "AUTHORING.md", "composition/README.md", "design/README.md", "docs/workflow.md"]
+    if (!["AUTHORING.md", "html/README.md", "theme.css", "theme-base.css"]
       .every(path => existsSync(join(root, path)))) return;
     // The development checkout runs TypeScript directly on the pinned Node.
-    for (const candidate of new Set([cli, sourceCLI])) {
+    for (const candidate of [sourceCLI, cli]) {
       if (!existsSync(candidate)) continue;
       const probe = spawnSync(process.execPath, [candidate, "validate", probeDocument], {
         stdio: "ignore",
@@ -33,35 +32,15 @@ function runtime(root) {
 try {
   if (Number(process.versions.node.split(".")[0]) < 24)
     throw new Error("Konpeki needs Node.js 24+. Use your host's approved toolchain setup, then retry.");
-  if (process.argv.slice(2).some(arg => arg !== "--install"))
-    throw new Error("Usage: node ensure-runtime.mjs [--install]");
+  if (process.argv.length > 2) throw new Error("Usage: node ensure-runtime.mjs");
   let workspace;
   try {
     workspace = dirname(createRequire(join(process.cwd(), "package.json")).resolve("konpeki/package.json"));
   } catch {}
   const bundled = fileURLToPath(new URL("../../../", import.meta.url));
-  const cacheBase = process.platform === "win32"
-    ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
-    : process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
-  const cache = resolve(cacheBase, "konpeki", version);
-  const cachedRoot = join(cache, "node_modules", "konpeki");
-  let found = (workspace && runtime(workspace)) || runtime(bundled) || runtime(cachedRoot);
-  if (!found) {
-    if (!process.argv.includes("--install"))
-      throw new Error(`Konpeki ${version} is not installed. After the host approves installation, rerun with --install. This uses a user cache and leaves project dependencies unchanged.`);
-    mkdirSync(cache, { recursive: true });
-    // Explicit local prefix prevents npm from walking up into an ancestor project.
-    // Resolve "." from the absolute cwd; no user path enters Windows shell text.
-    const result = spawnSync("npm", ["install", "--prefix=.", "--global=false", "--save-exact", "--no-audit", "--no-fund", `konpeki@${version}`], {
-      cwd: cache,
-      stdio: ["inherit", 2, 2],
-      shell: process.platform === "win32",
-    });
-    if (result.error || result.status !== 0)
-      throw new Error("Konpeki installation failed. Check npm/network access and retry; the runtime is not ready.");
-    found = runtime(cachedRoot);
-    if (!found) throw new Error("The installed Konpeki runtime is incomplete or incompatible.");
-  }
+  const found = (workspace && runtime(workspace)) || runtime(bundled);
+  if (!found)
+    throw new Error("Konpeki 0.4.0 is required. Check availability with npm view konpeki@0.4.0 version, then install that exact version in this workspace. If unavailable, use a locally packed tarball or prepared checkout. The 0.3.x runtime is incompatible. See SETUP.md.");
   console.log(JSON.stringify(found));
 } catch (error) {
   console.error(error.message);

package/skills/konpeki/scripts/prepare-document.mjs

@@ -1,15 +1,15 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { constants, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 try {
   const [cli, input, ...extra] = process.argv.slice(2);
-  if (!cli || !input || extra.length)
-    throw new Error("Usage: node prepare-document.mjs <cli> <composition.json>");
-  const compositionPath = resolve(input);
+  if (!cli || !input || extra.length) throw new Error("Usage: node prepare-document.mjs <cli> <document.html>");
+  if (!/\.html?$/i.test(input)) throw new Error("Use an .html document path.");
+  const documentPath = resolve(input);
   function validate(path) {
-    // Use the published JS CLI, not TypeScript imports from node_modules.
+    // Use the supplied CLI, not internal TypeScript imports from node_modules.
     const result = spawnSync(process.execPath, [cli, "validate", path], {
       stdio: ["ignore", 2, 2],
     });
@@ -17,23 +17,34 @@ try {
       throw new Error("Document validation failed; existing files were not changed.");
   }
   let created = false;
-  if (!existsSync(compositionPath)) {
-    if (existsSync(`${compositionPath}.review.json`))
-      throw new Error("Review data exists without its composition. Restore the document or choose a new path.");
-    const template = fileURLToPath(new URL("../assets/blank.json", import.meta.url));
+  if (!existsSync(documentPath)) {
+    const template = fileURLToPath(new URL("../assets/blank.html", import.meta.url));
     validate(template);
     const blank = readFileSync(template);
-    mkdirSync(dirname(compositionPath), { recursive: true });
+    const root = resolve(dirname(cli), "..");
+    const assets = new Map([["theme.css", join(root, "theme.css")], ["theme-base.css", join(root, "theme-base.css")]]);
+    // Preflight every asset before writing any: never replace an author's
+    // adapted stylesheet in a shared folder.
+    for (const [asset, source] of assets) {
+      const destination = join(dirname(documentPath), asset);
+      if (existsSync(destination) && !readFileSync(destination).equals(readFileSync(source)))
+        throw new Error(`Existing asset differs: ${destination}. Use a new directory; existing files were not changed.`);
+    }
+    mkdirSync(dirname(documentPath), { recursive: true });
+    for (const [asset, source] of assets) {
+      try { copyFileSync(source, join(dirname(documentPath), asset), constants.COPYFILE_EXCL); }
+      catch (error) { if (error.code !== "EEXIST") throw error; }
+    }
     try {
-      writeFileSync(compositionPath, blank, { flag: "wx" });
+      writeFileSync(documentPath, blank, { flag: "wx" });
       created = true;
     } catch (error) {
       // Another initializer may have created it; reopen, never replace it.
       if (error.code !== "EEXIST") throw error;
     }
   }
-  validate(compositionPath);
-  console.log(JSON.stringify({ compositionPath, created }));
+  validate(documentPath);
+  console.log(JSON.stringify({ documentPath, created }));
 } catch (error) {
   console.error(error.message);
   process.exitCode = 1;

package/src/components/PageBoard.tsx

@@ -0,0 +1,156 @@
+import { useEffect, useId, useRef, useState, type ReactNode, type RefObject } from "react";
+import { layoutPages } from "../lib/page-board.ts";
+
+export type PageBoardControls = {
+  goTo: (id: string, fit?: boolean) => void;
+  pan: (x: number, y: number) => void;
+  zoom: (factor: number) => void;
+  stopZoom: () => void;
+};
+
+export function PageBoard<Page extends { id: string; name: string; canvas: { width: number; height: number } }>({ draft, children, controls, onActivePage }: {
+  draft: { pages: Page[] }; children: (page: Page, index: number) => ReactNode;
+  controls: RefObject<PageBoardControls | null>; onActivePage: (id: string) => void;
+}) {
+  const root = useRef<HTMLDivElement>(null);
+  const content = useRef<HTMLDivElement>(null);
+  const [space, setSpace] = useState({ width: 0, height: 0 });
+  const marker = useId();
+  useEffect(() => {
+    const viewport = root.current!.closest<HTMLElement>(".workspace")!;
+    const observer = new ResizeObserver(() => {
+      const help = viewport.querySelector<HTMLElement>(".board-help");
+      const footer = help ? help.offsetHeight + parseFloat(getComputedStyle(help).marginTop) : 0;
+      const top = root.current!.getBoundingClientRect().top - viewport.getBoundingClientRect().top + viewport.scrollTop;
+      const padding = getComputedStyle(viewport);
+      const width = viewport.clientWidth - parseFloat(padding.paddingLeft) - parseFloat(padding.paddingRight);
+      const height = Math.max(0, viewport.clientHeight - top - parseFloat(padding.paddingBottom) - footer);
+      setSpace(current => current.width === width && current.height === height ? current : { width, height });
+    });
+    observer.observe(root.current!);
+    observer.observe(viewport);
+    return () => observer.disconnect();
+  }, []);
+  useEffect(() => {
+    const viewport = root.current!.closest<HTMLElement>(".workspace")!;
+    const reducedMotion = matchMedia("(prefers-reduced-motion: reduce)");
+    let scale = 1, goal = 1, gestureScale: number | undefined;
+    let frame = 0, lastTime = 0, x = 0, y = 0, smooth = true;
+    let anchorX = 0, anchorY = 0;
+    function activePage() {
+      const center = viewport.getBoundingClientRect().left + viewport.clientWidth / 2;
+      const pages = Array.from(root.current!.querySelectorAll<HTMLElement>(".board-page"));
+      const page = pages.reduce<HTMLElement | undefined>((nearest, page) => {
+        const rect = page.getBoundingClientRect(), previous = nearest?.getBoundingClientRect();
+        return !previous || Math.abs(rect.left + rect.width / 2 - center) < Math.abs(previous.left + previous.width / 2 - center) ? page : nearest;
+      }, undefined);
+      if (page?.dataset.page) onActivePage(page.dataset.page);
+    }
+    function stopZoom() {
+      cancelAnimationFrame(frame); frame = 0; goal = scale;
+      if (content.current) delete content.current.dataset.zooming;
+    }
+    function animate(time: number) {
+      frame = 0;
+      const board = content.current;
+      if (!board) return;
+      const distance = Math.log(goal / scale);
+      const fraction = smooth && !reducedMotion.matches ? 1 - Math.exp(-Math.min(time - lastTime, 64) / 40) : 1;
+      const next = Math.abs(distance) < .002 ? goal : scale * Math.exp(distance * fraction);
+      lastTime = time;
+      // Keep view-only zoom out of React. Retain the original anchor across
+      // frames so integer scroll rounding cannot accumulate into pointer drift.
+      board.style.zoom = String(next);
+      const after = board.getBoundingClientRect();
+      viewport.scrollLeft += after.left + anchorX * next - x;
+      viewport.scrollTop += after.top + anchorY * next - y;
+      scale = next;
+      activePage();
+      if (scale !== goal) frame = requestAnimationFrame(animate);
+      else delete board.dataset.zooming;
+    }
+    function zoomAt(next: number, clientX: number, clientY: number, ease: boolean) {
+      if (!content.current) return;
+      const bounds = content.current.getBoundingClientRect();
+      anchorX = (clientX - bounds.left) / scale;
+      anchorY = (clientY - bounds.top) / scale;
+      goal = Math.min(4, Math.max(.1, next));
+      x = clientX; y = clientY; smooth = ease;
+      content.current.dataset.zooming = "true";
+      if (!frame) { lastTime = performance.now(); frame = requestAnimationFrame(animate); }
+    }
+    controls.current = {
+      stopZoom,
+      goTo(id, fit = false) {
+        const page = root.current!.querySelector<HTMLElement>(`.board-page[data-page="${CSS.escape(id)}"]`);
+        if (!page || !content.current) return;
+        stopZoom();
+        if (fit) { scale = goal = 1; content.current.style.zoom = "1"; }
+        const rect = page.getBoundingClientRect(), bounds = viewport.getBoundingClientRect();
+        viewport.scrollLeft += rect.left + rect.width / 2 - bounds.left - viewport.clientWidth / 2;
+        viewport.scrollTop += rect.top + rect.height / 2 - bounds.top - viewport.clientHeight / 2;
+        onActivePage(id);
+      },
+      pan(dx, dy) { stopZoom(); viewport.scrollLeft += dx; viewport.scrollTop += dy; activePage(); },
+      zoom(factor) {
+        const bounds = viewport.getBoundingClientRect();
+        zoomAt(goal * factor, bounds.left + viewport.clientWidth / 2, bounds.top + viewport.clientHeight / 2, true);
+      },
+    };
+    function wheel(event: WheelEvent) {
+      // Floating review panels own their scrolling, not the canvas beneath them.
+      if ((event.target as Element).closest(".revision-notes,dialog")) return;
+      if (!event.ctrlKey && !event.metaKey) {
+        // A fitted row has no vertical travel. Let a plain mouse wheel navigate
+        // it, while preserving native two-axis panning when zoomed in.
+        if (!event.deltaX && viewport.scrollHeight <= viewport.clientHeight + 1 && viewport.scrollWidth > viewport.clientWidth) {
+          event.preventDefault();
+          const unit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.clientWidth : 1;
+          viewport.scrollLeft += event.deltaY * unit;
+        }
+        return;
+      }
+      event.preventDefault();
+      if (gestureScale !== undefined) return; // Safari can emit both event families.
+      const unit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? viewport.clientHeight : 1;
+      zoomAt(goal * Math.exp(-event.deltaY * unit * .004), event.clientX, event.clientY, true);
+    }
+    function gesture(event: Event) {
+      const pinch = event as Event & { scale: number; clientX: number; clientY: number };
+      event.preventDefault();
+      if (event.type === "gesturestart") gestureScale = goal;
+      else if (event.type === "gestureend") gestureScale = undefined;
+      else if (gestureScale !== undefined) zoomAt(gestureScale * pinch.scale, pinch.clientX, pinch.clientY, false);
+    }
+    const observer = new ResizeObserver(activePage);
+    observer.observe(root.current!);
+    observer.observe(viewport);
+    viewport.addEventListener("scroll", activePage);
+    viewport.addEventListener("wheel", wheel, { passive: false });
+    for (const type of ["gesturestart", "gesturechange", "gestureend"]) viewport.addEventListener(type, gesture, { passive: false });
+    return () => {
+      cancelAnimationFrame(frame);
+      controls.current = null;
+      observer.disconnect();
+      viewport.removeEventListener("scroll", activePage);
+      viewport.removeEventListener("wheel", wheel);
+      for (const type of ["gesturestart", "gesturechange", "gestureend"]) viewport.removeEventListener(type, gesture);
+    };
+  }, [controls, onActivePage]);
+  const layout = layoutPages(draft.pages.map(page => page.canvas), space.width, space.height);
+  return <div ref={root} className="page-board" style={{ minHeight: space.height }} aria-label="All pages in reading order">
+    {space.width > 0 && <div ref={content} className="page-board-content" style={{ width: layout.width, height: layout.height, zoom: 1 }}>
+      <svg className="page-order" width={layout.width} height={layout.height} aria-hidden="true">
+        <defs><marker id={marker} markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M1 1 7 4 1 7" /></marker></defs>
+        {layout.arrows.map((path, index) => <path key={draft.pages[index].id} data-from={draft.pages[index].id} data-to={draft.pages[index + 1].id} d={path} markerEnd={`url(#${marker})`} />)}
+      </svg>
+      {draft.pages.map((page, index) => {
+        const box = layout.pages[index];
+        return <article key={page.id} className="board-page" data-page={page.id} aria-label={`Page ${index + 1}: ${page.name}`}
+          style={{ left: box.x, top: box.y - 32, width: box.width }}>
+          {children(page, index)}
+        </article>;
+      })}
+    </div>}
+  </div>;
+}