gutterpress 0.11.11-alpha.1 → 0.11.11-alpha.2

package/dist/lib/cli-args.d.ts

@@ -23,7 +23,7 @@ type CliArgumentDefinitions = Readonly<Record<string, CliArgumentDefinition>>;
  */
 export declare function rejectUnknownFlags(rawArgs: readonly string[], declared: CliArgumentDefinitions, commandName: string): void;
 /**
- * Reject CLI positionals beyond the ones a command declares (UX finding M46).
+ * Reject CLI positionals beyond the ones a command declares.
  *
  * Citty's parser keeps every raw positional token in `args._` even after
  * `type: "positional"` args have claimed their share — it shifts values off a

package/dist/lib/desktop.d.ts

@@ -1,12 +1,6 @@
 /**
- * Output filename constants for the build pipeline.
- *
- * Historically this file also emitted "desktop chrome" (toolbar + folder
- * picker + GH clone modal) into the build output so the directory was a
- * self-hostable site. That chrome was removed 2026-05-18 when the desktop
- * was extracted into packages/desktop (Electron + SvelteKit). The CLI build
- * now produces a "naked" book.html with Gutterpress's native live-viewer and
- * preview-interface/bridge scripts injected — no toolbar.
+ * Output filename constants for the build pipeline. The build emits no
+ * application chrome around book.html — that lives in packages/desktop.
  *
  * Power users who want a hosted UI launch the desktop app or write their
  * own iframe wrapper around book.html.

package/dist/lib/engine.d.ts

@@ -21,7 +21,7 @@ export interface NativePdfOptions {
  *
  * Returns the build's author-facing diagnostics so the caller can surface
  * them (the desktop Problems panel, the CLI's own output). Dropping them here
- * is what made the engine's print-quality audits invisible in every real
- * build path — they only ever reached the engine dev CLI.
+ * would make the engine's print-quality audits invisible in every real build
+ * path.
  */
 export declare function buildNativePdf(htmlFile: string, outPdf: string, options: NativePdfOptions, browser: EngineBrowser): Promise<BuildDiagnostic[]>;

package/dist/lib/exec.d.ts

@@ -11,10 +11,8 @@ export declare const localBin: string;
  * PATH with `localBin` prepended, correctly delimiter-joined. Single source
  * of truth for every spawn in the lib — `run` and `execCapture` below use
  * it, and tool-probe.ts's `isToolAvailable`/`findTool` get it for free by
- * calling `execCapture` instead of keeping their own copy (previously a
- * literal `:` here corrupted PATH on Windows while tool-probe.ts's copy of
- * the same logic used `delimiter` correctly — see docs/reviews
- * 2026-07-10-architecture-critical-review.md, finding #3).
+ * calling `execCapture` instead of keeping their own copy. Joined with
+ * `delimiter`, never a literal `:` (which corrupts PATH on Windows).
  */
 export declare const enhancedPath: string;
 /**
@@ -59,8 +57,7 @@ export interface SpawnCaptureOptions {
  * on settle and `unref()`d so a pending call can never keep the process alive
  * on its own. `execCapture` below and publish's `defaultCommandRunner` are
  * thin adapters over this — do not grow parallel spawn loops elsewhere
- * (previously four copies existed with different bug profiles — see
- * docs/reviews 2026-07-10-architecture-critical-review.md, finding #16).
+ * (separate copies drift into different bug profiles).
  */
 export declare function spawnCapture(cmd: string, args: string[], opts?: SpawnCaptureOptions): Promise<{
     code: number | null;

package/dist/lib/fetch-timeout.d.ts

@@ -1,13 +1,12 @@
 /**
  * Shared network deadline + author-friendly error mapping for the CLI's
  * direct `fetch` call sites (GitHub auth/API, the butler download). ONE copy
- * of the policy, so a fix here reaches every site (the old per-site clones
- * let the dropped-timeout bug below survive in two of three copies):
+ * of the policy, so a fix here reaches every site:
  *
  *  - The deadline is a TOTAL budget (`AbortSignal.timeout` keeps ticking
  *    through any body read done inside `run`), COMPOSED with the caller's
- *    cancellation signal via `AbortSignal.any` — the old
- *    `signal ?? AbortSignal.timeout(...)` pattern silently DROPPED the
+ *    cancellation signal via `AbortSignal.any` — a
+ *    `signal ?? AbortSignal.timeout(...)` pattern would silently DROP the
  *    timeout whenever a caller passed a signal.
  *  - A caller abort ("AbortError") is rethrown untouched, so cancellation
  *    keeps its site-specific handling.

package/dist/lib/ghostscript.d.ts

@@ -67,7 +67,7 @@ type PdfxFlavor = "x1a" | "x3";
  *
  * Uses pdf-lib (pure JS, MIT) rather than Ghostscript, so the plain-PDF build
  * path needs no system tool at all — gs is now required only for PDF/X CMYK
- * conversion (ADR 0002). `updateMetadata: false` keeps pdf-lib from rewriting
+ * conversion. `updateMetadata: false` keeps pdf-lib from rewriting
  * the ModDate/Producer so the only change is the /Creator field.
  */
 export declare function stampCreator(pdfPath: string): Promise<void>;

package/dist/lib/host-policy.d.ts

@@ -17,8 +17,8 @@ export interface AutoSnapshotPolicy {
     /** Master switch — automatic snapshots default ON. */
     autoSnapshot: boolean;
 }
-/** Quiet period before a snapshot fires. Fixed (#274) — no longer a settings
- * knob, so there is nothing left to clamp. */
+/** Quiet period before a snapshot fires. Fixed (#274) — not a settings
+ * knob, so there is nothing to clamp. */
 export declare const AUTO_SNAPSHOT_DEFAULT_MINUTES = 10;
 /** User-facing auto-sync policy (mirrors the desktop's settings group). */
 export interface AutoSyncPolicy {
@@ -52,9 +52,8 @@ export declare const AUTO_SYNC_PUSH_INTERVAL_MINUTES = 15;
  * `null` when automatic snapshots are disabled. Pure — the testable core of
  * the trigger policy (the timer itself lives in the Electron main process).
  *
- * The quiet period is fixed at `AUTO_SNAPSHOT_DEFAULT_MINUTES` (#274 — the
- * minutes field this used to clamp was deleted from the settings schema, so
- * there is nothing left to resolve here beyond the master switch).
+ * The quiet period is fixed at `AUTO_SNAPSHOT_DEFAULT_MINUTES` (#274 — there
+ * is no minutes setting, so nothing to resolve here beyond the master switch).
  * Defensive about persisted settings: a missing policy means "defaults"
  * (enabled, 10 min).
  */
@@ -70,9 +69,8 @@ export declare function autoSnapshotDelayMs(policy: Partial<AutoSnapshotPolicy>
  * the default and is then clamped into [AUTO_SYNC_MIN_MINUTES,
  * AUTO_SYNC_MAX_MINUTES].
  *
- * Note: this is the host orchestrator's ONLY sync trigger — the file-change
- * debounce that used to sit beside it was removed (it could never fire before
- * this interval already had).
+ * Note: this is the host orchestrator's ONLY sync trigger — a file-change
+ * debounce beside it could never fire before this interval already had.
  */
 export declare function autoSyncDelayMs(policy: Partial<AutoSyncPolicy> | undefined): number | null;
 /**

package/dist/lib/image-inspect.d.ts

@@ -1,10 +1,10 @@
 /**
  * Dependency-free raster image header reader — the in-process replacement for
- * ImageMagick `identify` used by the asset checks (Phase 3 of ADR 0002).
+ * ImageMagick `identify` used by the asset checks.
  *
  * Why not `sharp`? sharp is the most capable option but is a native addon whose
  * platform binaries are resolved through `node_modules` at runtime — exactly the
- * pattern that breaks `bun build --compile` (ADR 0001 §1/§3). A small header
+ * pattern that breaks `bun build --compile` (CLAUDE.md §1/§3). A small header
  * parser for the formats print authors actually use (PNG, JPEG, TIFF) keeps a
  * single code path that bundles into the standalone binary AND runs in the
  * Electron desktop, with zero system/native dependency.

package/dist/lib/install-hints.d.ts

@@ -6,9 +6,8 @@
  * This is the single source of truth. `build-preflight.ts` (preflight error),
  * `diagnostics.ts` (desktop Help/About dialog + `gutterpress doctor`), and
  * `chromium.ts` (`requireChromiumExecutable`'s thrown error) all import
- * from here instead of hand-copying the per-platform install commands —
- * previously three diverging copies existed (see
- * docs/reviews/2026-07-10-architecture-critical-review.md, finding #15).
+ * from here instead of hand-copying the per-platform install commands, so
+ * the copies cannot diverge.
  */
 export interface InstallHint {
     /** Human label for the tool, used in "Install <label>:" headers. */

package/dist/lib/manifest-config.d.ts

@@ -22,9 +22,8 @@ export declare function setManifestFields(projectDir: string, updates: ProjectCo
 /**
  * Read the author-facing manifest subset for the Config view's Details section.
  * Loads via the same shared {@link loadManifestDoc} every other manifest reader/
- * writer in this module uses (ARCH finding #25 — this used to re-implement
- * loadManifestDoc's read-and-parse inline) and surfaces empty/absent fields as
- * empty strings so the form inputs are editable.
+ * writer in this module uses and surfaces empty/absent fields as empty
+ * strings so the form inputs are editable.
  */
 export declare function readManifestFields(projectDir: string): Promise<ProjectConfigFields>;
 /**

package/dist/lib/manifest-doc.d.ts

@@ -18,8 +18,7 @@ export declare function ensureSeq(doc: Document.Parsed, key: string): YAMLSeq;
  * plain JS string (as a freshly-constructed `Scalar`'s `.value` or a raw
  * array entry would be).
  *
- * ARCH finding #25: this was two near-duplicate helpers — `unwrapScalar`
- * (manifest-config.ts) and `styleHrefOf` (the theme manager, since retired) — with the same
- * shape-sniffing logic. One implementation here, consumed by both.
+ * One implementation of this shape-sniffing, shared by every manifest
+ * reader (manifest-config.ts, project-templates.ts).
  */
 export declare function scalarString(item: unknown): string | null;

package/dist/lib/manifest.d.ts

@@ -16,16 +16,13 @@ export declare function loadManifest(pathOrDir?: string): Promise<GutterpressMan
 /**
  * Load a recognized manifest and return its contents, directory, and resolved path.
  * Returns an empty manifest, a null path, and the current working directory if none is found —
- * UNLESS `explicit` is set (ARCH finding #12/PR #98): a caller that resolved
+ * UNLESS `explicit` is set (PR #98): a caller that resolved
  * `pathOrDir` from a user-supplied `--manifest` flag (as opposed to a project
  * directory being scanned for a manifest that may legitimately not exist) must
  * pass `{ explicit: true }` so a missing/typo'd path throws instead of
- * silently resolving to an empty manifest. A typo like `--manifest
- * ./typo.yaml` previously fell through to the "no manifest" default AND left
- * `manifestDir` pointing at the nonexistent path itself
- * (`resolve("./typo.yaml")`), so a later `path.resolve(manifestDir,
- * config.output.dir)` could create build output beneath a directory named
- * after the missing file.
+ * silently resolving to an empty manifest whose `manifestDir` is the
+ * nonexistent path itself, which later path resolution would then build
+ * beneath.
  */
 export declare function loadManifestWithPath(pathOrDir?: string, opts?: {
     explicit?: boolean;

package/dist/lib/markdown/assemble.d.ts

@@ -2,7 +2,7 @@ import { type LoadedPlugin } from "./renderer";
 /** Reader injected by the host: resolve a project-root-relative file → its text. */
 export type ReadText = (relPath: string) => Promise<string>;
 /**
- * One author-mistake warning emitted by Gutterpress's marker parser (ARCH finding #4).
+ * One author-mistake warning emitted by Gutterpress's marker parser.
  * Mirrors the shape `markers.js`'s `warn()` pushes onto
  * `env.layoutWarnings` — see that file's header comment for the warning
  * `type`s (`ambiguous_marker_token`, `unrecognized_marker_token`,
@@ -24,10 +24,8 @@ export type ReadText = (relPath: string) => Promise<string>;
  * same type, via a second, unconditional check modeled on `unknown_gp_class`
  * rather than the core-only `scanForMistypedMarkers`.
  *
- * `section_without_page` and `implicit_page` were REMOVED 2026-08-12: a
- * @section with no open @page is valid authoring (audited, 17/17 false
- * positives across two real books), and the `implicitPage` option that
- * produced the latter was unreachable and latently broken.
+ * There is deliberately no `section_without_page`: a @section with no open
+ * @page is valid authoring (17/17 false positives across two real books).
  */
 export interface LayoutWarning {
     line: number;
@@ -113,14 +111,11 @@ export interface AssembleBookHtmlOptions {
     /** Add a layout-neutral source-file id to source-mapped preview blocks. */
     annotateSourceChapters?: boolean;
     /**
-     * ARCH finding #4: per-chapter callback receiving any `env.layoutWarnings`
+     * Per-chapter callback receiving any `env.layoutWarnings`
      * Gutterpress's marker parser computed while rendering `file` (only called
      * when that chapter produced at least one). `file` is the same canonical
      * chapter id used for `data-chapter-src`, so a host can attribute a warning
-     * to the exact source file. Additive/optional — omitting it reproduces the
-     * prior throwaway-env behavior exactly, so this cannot change output for
-     * existing callers (e.g. the desktop's WebAdapter, which still gets a plain
-     * `Promise<string>` back).
+     * to the exact source file. Optional, and it never changes output.
      */
     onChapterWarnings?: (file: string, warnings: LayoutWarning[]) => void;
     /**
@@ -138,8 +133,7 @@ export interface AssembleBookHtmlOptions {
  * Assemble a single `book.html` string from the given markdown files.
  *
  * Pure: every input (the file list, their contents via `readText`, the resolved
- * CSS hrefs) is supplied by the caller. Mirrors the exact `<head>`/body/CSS
- * emission the old `renderChapters` produced, so the CLI output is byte-identical
- * for identical inputs.
+ * CSS hrefs) is supplied by the caller, so the output is byte-identical for
+ * identical inputs.
  */
 export declare function assembleBookHtml(opts: AssembleBookHtmlOptions): Promise<string>;

package/dist/lib/markdown/gutterpress-css.d.ts

@@ -17,16 +17,13 @@
  *
  * Also ships the author-facing `gp-*` image/block vocabulary (CLAUDE.md §0 —
  * a behavior broadly useful to non-technical authors belongs in core, not a
- * project layer; see UX finding M17). markdown-it-attrs is bundled by
+ * project layer). markdown-it-attrs is bundled by
  * default (renderer.ts), so `![Art](x.jpg){.gp-right .gp-small}` already
  * attaches the classes to the rendered `<img>` — these rules are what make
- * them actually do something print-safe. The gp-* vocabulary REPLACED the
- * five pre-vocabulary utility names (.center/.float-left/.float-right/
- * .full-width/.full-bleed), which were removed rather than kept as
- * aliases — one vocabulary, no duplicate way to spell each layout. Books
- * migrate by renaming the classes in their markdown; the desktop editor
- * recognizes the old names when editing an image and rewrites them to the
- * gp-* names in place.
+ * them actually do something print-safe. One vocabulary, no aliases: there
+ * is no duplicate way to spell each layout (the desktop editor rewrites the
+ * pre-gp-* names `.center`/`.float-left`/`.float-right`/`.full-width`/
+ * `.full-bleed` to gp-* names in place when editing an image).
  *
  *   .gp-left      — floats left, text wraps.
  *   .gp-right     — floats right, text wraps.
@@ -136,7 +133,7 @@
  * carrying gp-left could start shifting; that is standards-tracking per
  * CLAUDE.md ("Chrome wins once it ships"), not a bug in the author's book.
  */
-export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* the per-shape decisions the paragraph above deliberately leaves to the\n   author, named instead of left as raw CSS every book was reinventing\n   (2026-09-01 CSS architecture review, findings C1/C7 \u2014 CLAUDE.md \u00A70:\n   \"behavior broadly useful to non-technical authors belongs in core\").\n   Permanent vocabulary, standard properties verbatim \u2014 same rationale as\n   the column/grid runs above. One name each, no aliases:\n     .gp-columns-all       column-span: all      a heading or block that\n                                                  spans every column in the\n                                                  run it sits inside.\n     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across\n                                                  pages \u2014 every page's\n                                                  columns fill instead of\n                                                  only the last one\n                                                  balancing (the dead-column\n                                                  collapse the build's\n                                                  engine.multicol.dead-column\n                                                  warning names this fix\n                                                  for).\n     .gp-columns-balanced  column-fill: balance  a run that fits on ONE\n                                                  page (the CSS initial\n                                                  value \u2014 ragged columns\n                                                  would be wrong here). */\n.gp-columns-all { column-span: all; }\n.gp-columns-flow { column-fill: auto; }\n.gp-columns-balanced { column-fill: balance; }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column/grid vocabulary above (a book reached for\n   these just as often outside a multicol run: keeping a card whole,\n   forcing a section to start a fresh page). Standard properties only \u2014\n   this project is Chromium-only (CLAUDE.md), so there are no legacy\n   page-break-* twins to also emit. One name each. */\n.gp-no-break { break-inside: avoid; }\n.gp-break-before { break-before: page; }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n\n/* GFM-style alert/callout boxes (#237) \u2014 the DOM gfm-alerts.ts emits from\n   \"> [!TYPE]\" blockquote syntax when a project opts into the bundled\n   gutterpress-gfm-alerts feature (BUILTIN_OPTIONAL_PLUGINS, renderer.ts).\n   The plugin is optional and inert by default; these rules are equally\n   inert wherever the classes never appear, exactly like every other\n   utility above, so shipping them costs nothing to a book that has not\n   turned the feature on.\n\n   This is authored-COMPONENT vocabulary, not the @marker structural family\n   (markers.js/MARKER_CSS) \u2014 CLAUDE.md \u00A76 splits the two core CSS blocks by\n   ROLE, and an author-facing box an author invokes via inline syntax is the\n   same role as every other gp-* utility here, not page/chapter/section DOM.\n\n   Deliberately minimal (CLAUDE.md \"thin over capable\" / the issue's own\n   \"a rule and a label\"): a left border plus a bold label, :where()'d to\n   zero specificity so a theme's own (unlayered) rule for any of these\n   classes wins outright regardless of selector weight \u2014 see the\n   cascade-layers note atop this file. Five semantic accent colors (the same\n   NOTE/TIP/IMPORTANT/WARNING/CAUTION hues GitHub's own alerts use \u2014 a\n   long-established, non-proprietary convention, not DC branding) are\n   exposed as :root custom properties, the same author-settable-surface\n   pattern as the --gp-z-* ladder above: a book retints every alert of one\n   type by overriding a single property, no specificity fight required.\n   --gp-alert-color cascades from the type modifier down to .gp-alert-title\n   through ordinary CSS inheritance (the title is always a DOM descendant of\n   the box), so it is set in exactly five places, not ten. */\n:root {\n  --gp-alert-note-color: #0969da;\n  --gp-alert-tip-color: #1a7f37;\n  --gp-alert-important-color: #8250df;\n  --gp-alert-warning-color: #9a6700;\n  --gp-alert-caution-color: #cf222e;\n}\n:where(.gp-alert) {\n  margin: 1em 0;\n  padding: 0.5em 1em;\n  border-left: 0.25em solid var(--gp-alert-color, currentColor);\n}\n:where(.gp-alert-title) {\n  margin: 0 0 0.5em;\n  font-weight: bold;\n  color: var(--gp-alert-color, inherit);\n}\n:where(.gp-alert-note)      { --gp-alert-color: var(--gp-alert-note-color); }\n:where(.gp-alert-tip)       { --gp-alert-color: var(--gp-alert-tip-color); }\n:where(.gp-alert-important) { --gp-alert-color: var(--gp-alert-important-color); }\n:where(.gp-alert-warning)   { --gp-alert-color: var(--gp-alert-warning-color); }\n:where(.gp-alert-caution)   { --gp-alert-color: var(--gp-alert-caution-color); }\n";
+export declare const GUTTERPRESS_CSS = "\n/* gp-* author image/block vocabulary. One vocabulary, gp-* only \u2014 the\n   pre-vocabulary utility names (.center/.float-left/.float-right/\n   .full-width/.full-bleed) were REMOVED when gp-* shipped; books rename\n   the classes in their markdown (see the migration note). Source ORDER is\n   the contract \u2014 see the doctrine comment above. */\n\n/* flow positions */\n.gp-left {\n  float: left;\n  margin: 0 var(--gp-gap, 1em) var(--gp-gap, 1em) 0;\n  max-width: 50%;\n}\n.gp-right {\n  float: right;\n  margin: 0 0 var(--gp-gap, 1em) var(--gp-gap, 1em);\n  max-width: 50%;\n}\n.gp-center {\n  display: block;\n  float: none;\n  margin-left: auto;\n  margin-right: auto;\n  max-width: 100%;\n}\n.gp-full {\n  display: block;\n  float: none;\n  width: 100%;\n  max-width: 100%;\n}\n@page gp-full-bleed { margin-left: 0; margin-right: 0; }\n.gp-bleed {\n  display: block;\n  float: none;\n  break-before: page;\n  page: gp-full-bleed;\n  max-width: none;\n  width: 100%;\n  margin-left: 0;\n  margin-right: 0;\n}\n\n/* sizes \u2014 AFTER the flow positions so max-width:100% lifts the floats' 50%\n   cap at equal specificity */\n.gp-small { width: 25%; max-width: 100%; }\n.gp-medium { width: 50%; max-width: 100%; }\n.gp-large { width: 75%; max-width: 100%; }\n\n/* float clearance presets \u2014 consumed by var(--gp-gap) in the float rules\n   above and by .gp-shape's shape-margin below; --gp-gap itself is\n   author-settable CSS */\n.gp-tight { --gp-gap: 0.5em; }\n.gp-loose { --gp-gap: 2em; }\n\n/* column runs \u2014 plain CSS Multi-column, exposed as author vocabulary so\n   \"put this in two columns\" does not require borrowing a styled container\n   from the book's own component layer. That borrowing is what this exists\n   to prevent: a book whose theme paints .section chrome by default gives\n   every author who opens a section just to start a column run a panel they\n   did not ask for, and the book then needs a reset rule to take it back.\n   With a neutral primitive the author opts into columns and nothing else.\n\n   Permanent vocabulary, not a shim: Chromium implements multicol natively\n   and these rules are the standard properties verbatim, so there is no\n   spec gap here to remove later. Deliberately minimal \u2014 column-fill is\n   NOT set, because the correct value depends on whether the run fragments\n   across pages (auto packs each page's columns; the CSS initial balance is\n   right for a run that fits on one page) and only the author knows which.\n   --gp-column-gap is author-settable. */\n.gp-columns-2 { columns: 2; column-gap: var(--gp-column-gap, 1.5em); }\n.gp-columns-3 { columns: 3; column-gap: var(--gp-column-gap, 1.5em); }\n\n/* the per-shape decisions the paragraph above deliberately leaves to the\n   author, named instead of left as raw CSS every book was reinventing\n   (CLAUDE.md \u00A70: \"behavior broadly useful to non-technical authors belongs\n   in core\").\n   Permanent vocabulary, standard properties verbatim \u2014 same rationale as\n   the column/grid runs above. One name each, no aliases:\n     .gp-columns-all       column-span: all      a heading or block that\n                                                  spans every column in the\n                                                  run it sits inside.\n     .gp-columns-flow      column-fill: auto     a run that FRAGMENTS across\n                                                  pages \u2014 every page's\n                                                  columns fill instead of\n                                                  only the last one\n                                                  balancing (the dead-column\n                                                  collapse the build's\n                                                  engine.multicol.dead-column\n                                                  warning names this fix\n                                                  for).\n     .gp-columns-balanced  column-fill: balance  a run that fits on ONE\n                                                  page (the CSS initial\n                                                  value \u2014 ragged columns\n                                                  would be wrong here). */\n.gp-columns-all { column-span: all; }\n.gp-columns-flow { column-fill: auto; }\n.gp-columns-balanced { column-fill: balance; }\n\n/* grid runs \u2014 the SLOTTED counterpart to the column runs above. Grid places\n   each child into the next cell, across then down (deterministic slots: card\n   layouts, stat blocks, image-plus-caption pairs); columns FLOW one text run\n   down then across. Same neutral-primitive rationale as .gp-columns-*, and\n   permanent vocabulary for the same reason: standard CSS Grid verbatim, no\n   spec gap to remove later. MEASURED (Chromium 151, gp-grid evidence pack):\n   grid rows fragment across sheets with EXACT print/viewer parity \u2014 2- and\n   3-col, unequal item heights, mid-row cuts, multi-sheet overflow,\n   break-inside:avoid, gap geometry \u2014 so a grid taller than the page is safe,\n   no fit-one-page constraint. Two things to know, not fix:\n     - on a min-height page root (MARKER_CSS), default align-content\n       stretches rows apart to fill the page \u2014 identically in both engines.\n       Authors wanting packed rows set align-content: start.\n     - a @page-break / @column-break marker DIRECTLY inside a grid container\n       becomes a grid item and corrupts placement (the one measured parity\n       break); markers.js diagnoses it (break_inside_grid).\n   --gp-grid-gap is author-settable. */\n.gp-grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n.gp-grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gp-grid-gap, 1.5em); }\n\n/* fragmentation controls \u2014 generic pagination utilities for any element,\n   independent of the column/grid vocabulary above (a book reached for\n   these just as often outside a multicol run: keeping a card whole,\n   forcing a section to start a fresh page). Standard properties only \u2014\n   this project is Chromium-only (CLAUDE.md), so there are no legacy\n   page-break-* twins to also emit. One name each. */\n.gp-no-break { break-inside: avoid; }\n.gp-break-before { break-before: page; }\n\n/* shape wrap \u2014 text follows the image's alpha silhouette instead of its\n   rectangular box. shape-outside only applies to floats, so this is inert\n   without .gp-left/.gp-right (and under .gp-pin, which un-floats). The\n   shape URL cannot be written in CSS (url() contexts can't read attr()),\n   so the image renderer rule (images.ts) mirrors the src into an inline\n   --gp-shape:url(...) custom property whenever it sees this class --\n   authors only ever type the class. threshold 0.2 ignores near-transparent\n   anti-aliasing halos; shape-margin shares the float-gap vocabulary. */\nimg.gp-shape {\n  shape-outside: var(--gp-shape);\n  shape-image-threshold: 0.2;\n  shape-margin: var(--gp-gap, 1em);\n}\n\n/* pin \u2014 within the nearest positioned ancestor (.page/.spread, rule above).\n   inset:0 and the explicit centers are load-bearing; see doctrine comment. */\n.gp-pin {\n  position: absolute;\n  inset: 0;\n  align-self: center;\n  justify-self: center;\n  margin: 0;\n  max-width: 100%;\n}\n\n/* pin edge modifiers \u2014 AFTER .gp-pin to beat its center defaults;\n   justify-self is inert on in-flow floats, so gp-left/gp-right safely do\n   double duty as flow float + pin edge */\n.gp-top { align-self: start; }\n.gp-bottom { align-self: end; }\n.gp-left { justify-self: start; }\n.gp-right { justify-self: end; }\n\n/* wrapper-margin neutralization (same pattern and rationale as the\n   .gp-bleed paragraph-margin note in the doctrine comment; for pin, the\n   emptied paragraph would otherwise leave a phantom margin gap in flow) */\n:where(p:has(> img.gp-bleed:only-child)) { margin: 0; }\n:where(p:has(> img.gp-pin:only-child)) { margin: 0; }\n\n/* depth \u2014 a named ladder for z-index, so books stop hand-tuning bare\n   integers. A real book measured 21 z-index declarations using only four\n   distinct values (-1, 0, 1, 2), each written literally at its use site.\n   The custom properties are the author-settable surface (a book needing a\n   deeper stack raises them once); the classes are the shorthand.\n\n   NOT named \"layer\": CSS Paged Media 3 \u00A73.1 already defines \"page layers\"\n   (page background, canvas, borders, contents, margin boxes) and those are\n   parts of the PAGE BOX, not a z-ladder for content. Reusing the word for a\n   different concept would collide with the spec vocabulary this project\n   tracks. The pin EDGE modifiers already own .gp-top/.gp-bottom, so the\n   ladder avoids those words too.\n\n   .gp-behind is the one that earns its place: it puts a pinned image UNDER\n   the page's text, which is otherwise impossible to express without a bare\n   negative z-index. \"Above\" needs no class \u2014 an out-of-flow pin already\n   paints above in-flow content.\n\n   Two things silently defeat .gp-behind, neither visible at the use site:\n     - a stacking context on the .page/.spread ancestor (z-index, isolation,\n       opacity, filter, transform on it traps the negative layer inside).\n       Core keeps .page/.spread at 'position: relative; z-index: auto'\n       precisely so they are not stacking contexts.\n     - a clipping ancestor (overflow other than visible) \u2014 but only where\n       the art actually overhangs that ancestor's clip box on a clipped\n       axis: the overhang is cut off, the same mechanism that clips a\n       .gp-bleed plate back to the wrapper's width. Clipping never reorders\n       layers \u2014 within-bounds art under a clipping .page prints whole and\n       still behind (measured; see the build audit's comment in\n       engine/compiler/build.ts), and a static wrapper's overflow never\n       binds an abspos .gp-pin at all.\n   The build-time engine.layer.trapped audit reports both against the live\n   ancestor chain. printsafe/page-containment is only an early source hint for\n   declarations written directly on .page/.spread. */\n:root {\n  --gp-z-behind: -1;\n  --gp-z-base: 0;\n  --gp-z-raised: 1;\n  --gp-z-front: 2;\n}\n.gp-behind { z-index: var(--gp-z-behind); }\n.gp-base   { z-index: var(--gp-z-base); }\n.gp-raised { z-index: var(--gp-z-raised); }\n.gp-front  { z-index: var(--gp-z-front); }\n\n/* GFM-style alert/callout boxes (#237) \u2014 the DOM gfm-alerts.ts emits from\n   \"> [!TYPE]\" blockquote syntax when a project opts into the bundled\n   gutterpress-gfm-alerts feature (BUILTIN_OPTIONAL_PLUGINS, renderer.ts).\n   The plugin is optional and inert by default; these rules are equally\n   inert wherever the classes never appear, exactly like every other\n   utility above, so shipping them costs nothing to a book that has not\n   turned the feature on.\n\n   This is authored-COMPONENT vocabulary, not the @marker structural family\n   (markers.js/MARKER_CSS) \u2014 CLAUDE.md \u00A76 splits the two core CSS blocks by\n   ROLE, and an author-facing box an author invokes via inline syntax is the\n   same role as every other gp-* utility here, not page/chapter/section DOM.\n\n   Deliberately minimal (CLAUDE.md \"thin over capable\" / the issue's own\n   \"a rule and a label\"): a left border plus a bold label, :where()'d to\n   zero specificity so a theme's own (unlayered) rule for any of these\n   classes wins outright regardless of selector weight \u2014 see the\n   cascade-layers note atop this file. Five semantic accent colors (the same\n   NOTE/TIP/IMPORTANT/WARNING/CAUTION hues GitHub's own alerts use \u2014 a\n   long-established, non-proprietary convention, not DC branding) are\n   exposed as :root custom properties, the same author-settable-surface\n   pattern as the --gp-z-* ladder above: a book retints every alert of one\n   type by overriding a single property, no specificity fight required.\n   --gp-alert-color cascades from the type modifier down to .gp-alert-title\n   through ordinary CSS inheritance (the title is always a DOM descendant of\n   the box), so it is set in exactly five places, not ten. */\n:root {\n  --gp-alert-note-color: #0969da;\n  --gp-alert-tip-color: #1a7f37;\n  --gp-alert-important-color: #8250df;\n  --gp-alert-warning-color: #9a6700;\n  --gp-alert-caution-color: #cf222e;\n}\n:where(.gp-alert) {\n  margin: 1em 0;\n  padding: 0.5em 1em;\n  border-left: 0.25em solid var(--gp-alert-color, currentColor);\n}\n:where(.gp-alert-title) {\n  margin: 0 0 0.5em;\n  font-weight: bold;\n  color: var(--gp-alert-color, inherit);\n}\n:where(.gp-alert-note)      { --gp-alert-color: var(--gp-alert-note-color); }\n:where(.gp-alert-tip)       { --gp-alert-color: var(--gp-alert-tip-color); }\n:where(.gp-alert-important) { --gp-alert-color: var(--gp-alert-important-color); }\n:where(.gp-alert-warning)   { --gp-alert-color: var(--gp-alert-warning-color); }\n:where(.gp-alert-caution)   { --gp-alert-color: var(--gp-alert-caution-color); }\n";
 /**
  * GP_CLASSES — every class an author may legitimately write with a `gp-`
  * prefix: the `.gp-*` selectors in `GUTTERPRESS_CSS` above, the two

package/dist/lib/markdown/images.d.ts

@@ -3,13 +3,6 @@ import type MarkdownIt from "markdown-it";
  * Markdown-it `image` renderer rule that RECORDS every image reference the
  * document emits, on `env.imageRefs`.
  *
- * This replaces the previous `normalizeImageSrc` rewriter, which collapsed
- * `temp/images/…` and `./images/…` to `images/…`. That rewrite had zero
- * producers anywhere in the codebase or its history, and it silently broke any
- * author who kept art in a folder literally named `temp/images/` — the HTML
- * pointed at `images/<file>`, which no code path ever created, and adding the
- * folder to the old `source.assets` list could not fix it.
- *
  * Recording instead of rewriting is what lets the build copy exactly the files
  * the book references (`lib/asset-inline.ts` → `planImageCopies`), so the
  * author's own folder layout is the layout that ships. Paths are emitted

package/dist/lib/markdown/index.d.ts

@@ -6,10 +6,7 @@ export type { LayoutWarning } from "./assemble";
  * THE canonical "which markdown files make up this book, and in what order?"
  * resolver — markdown's counterpart to `resolveActiveStyles` (style-resolver.ts).
  * Both `renderChapters` below AND validation (validation-exec.ts) call this,
- * so what gets checked is always what gets rendered
- * (2026-07-28 duplication audit — those two used to each re-derive their own
- * recursive-glob approximation of "the book's markdown files" instead of
- * calling this):
+ * so what gets checked is always what gets rendered:
  *   1. `configuredFiles` (the manifest `source.files` list), if it has entries,
  *      in that order; else
  *   2. every `.md` file directly inside `inputDir` — NOT recursive, since a
@@ -28,8 +25,8 @@ export declare function resolveActiveMarkdownFiles(inputDir: string, configuredF
  * This is the thin **Node wrapper** around the pure `assembleBookHtml`
  * (`./assemble.ts`): it resolves the CSS list + the file list off disk and
  * supplies a `node:fs/promises`-backed `readText`. The pure assembler owns the
- * markdown→HTML→book.html work, so the browser/PWA WebAdapter can reuse the
- * exact same render path with a File System Access reader (#33).
+ * markdown→HTML→book.html work, so a future browser build can reuse the
+ * exact same render path with its own file reader.
  */
 export declare function renderChapters(inputDir: string, opts?: {
     title?: string;
@@ -47,10 +44,9 @@ export declare function renderChapters(inputDir: string, opts?: {
     /** Add source-file ids to source-mapped preview blocks without wrappers. */
     annotateSourceChapters?: boolean;
     /**
-     * ARCH finding #4: per-chapter author-mistake warnings computed by
-     * Gutterpress's marker parser (`env.layoutWarnings`), forwarded straight
-     * through from {@link assembleBookHtml}. See that option's docstring — omitting
-     * it is fully backward compatible.
+     * Per-chapter author-mistake warnings computed by Gutterpress's marker
+     * parser (`env.layoutWarnings`), forwarded straight through from
+     * {@link assembleBookHtml}. See that option's docstring. Optional.
      */
     onChapterWarnings?: (file: string, warnings: LayoutWarning[]) => void;
     /** See {@link assembleBookHtml}'s option of the same name. */
@@ -76,7 +72,7 @@ export declare function renderChaptersToFile(inputDir: string, outDir: string, o
     plugins?: LoadedPlugin[];
     /** See {@link renderChapters}'s option of the same name. */
     pluginStyles?: PluginStyleGroup[];
-    /** ARCH finding #4 — see {@link renderChapters}'s option of the same name. */
+    /** See {@link renderChapters}'s option of the same name. */
     onChapterWarnings?: (file: string, warnings: LayoutWarning[]) => void;
     /** See {@link renderChapters}'s options of the same names. */
     onImageRefs?: (refs: string[]) => void;

package/dist/lib/markdown/markers.d.ts

@@ -110,10 +110,9 @@ export default function plugin(md: any, pluginOptions?: {}): void;
  * `text-align: center` still centers it — `display: block` would not).
  *
  * #231 — two engine-generic print fixes adopted from a real book's own
- * engine sheet (2026-09-01 CSS architecture review, finding C8), because
- * both are written entirely in terms of core's own published contract and
- * fix a failure every book with big art or a `<figure>` hits, not a
- * DC-brand-specific one:
+ * engine sheet, because both are written entirely in terms of core's own
+ * published contract and fix a failure every book with big art or a
+ * `<figure>` hits, not a DC-brand-specific one:
  *
  *   - A bare markdown placard (`![Alt](art.jpg)`, no class) taller than the
  *     page content box is monolithic replaced content, and the fragmenter

package/dist/lib/markdown/plugins.d.ts

@@ -25,7 +25,7 @@ export declare function loadPlugin(config: ResolvedExtensionConfig, baseDir: str
  *     shows the plugin error with fix instructions).
  *
  * Path plugins are loaded through the mtime cache in `loadPlugin` regardless
- * of mode (finding #5): an edited plugin reloads across renders while an
+ * of mode: an edited plugin reloads across renders while an
  * unedited one is never re-imported, correct in both a one-shot CLI build and
  * the long-lived Electron host.
  */
@@ -50,18 +50,15 @@ export interface LoadedPluginsWithCss {
     pluginStylePaths: string[];
 }
 /**
- * Shared "load plugins -> collect their CSS" preamble (ARCH finding #53).
- * Both real render paths — build/export's fail-fast `renderBook`
- * (build-runner.ts) and the live preview's degrade-and-report
- * `renderPreviewBook` (preview/file-watcher.ts) — did this in lockstep,
- * differing ONLY in whether `onError` was supplied. `onError` presence still
- * selects fail-fast vs degrade-and-report (see {@link loadPlugins}) and the
- * matching path-plugin cache mode; this helper just removes the duplicated
- * wiring around it.
+ * Shared "load plugins -> collect their CSS" preamble for both real render
+ * paths — build/export's fail-fast `renderBook` (build-runner.ts) and the
+ * live preview's degrade-and-report `renderPreviewBook`
+ * (preview/file-watcher.ts), which differ ONLY in whether `onError` is
+ * supplied. `onError` presence selects fail-fast vs degrade-and-report (see
+ * {@link loadPlugins}).
  *
  * A `configs` of `undefined`/empty short-circuits WITHOUT calling
- * `loadPlugins` at all (`plugins: undefined`, `pluginStyles: []`) — matching
- * both call sites' prior behavior of never plugin-loading when the manifest
- * declares no plugins.
+ * `loadPlugins` at all (`plugins: undefined`, `pluginStyles: []`): nothing is
+ * plugin-loaded when the manifest declares no plugins.
  */
 export declare function loadPluginsWithCss(configs: ResolvedExtensionConfig[] | undefined | null, baseDir: string, onError?: (pluginRef: string, error: Error) => void): Promise<LoadedPluginsWithCss>;

package/dist/lib/markdown/renderer.d.ts

@@ -1,11 +1,11 @@
 /**
  * Pure (node-free) markdown rendering core.
  *
- * §1/§8 / ADR 0004: this module imports ONLY pure JS — markdown-it and its
+ * §1/§8: this module imports ONLY pure JS — markdown-it and its
  * plugins, Gutterpress's inlined marker parser (`markers.js`), and the node-free
  * leveled logger (console-only). It contains NO `node:*`,
  * NO `fs`/`path`/`url`, and NO filesystem access, so it can be imported by the
- * browser renderer (the PWA WebAdapter, #33) AND bundled into the
+ * browser AND bundled into the
  * `bun build --compile` CLI binary alike.
  *
  * The plugin *author* types and the markdown-it factory live here (not in
@@ -201,22 +201,18 @@ export declare const BUILTIN_OPTIONAL_PLUGINS: Record<string, GutterpressPlugin>
  * `<dl><dt><dd>`. It is not in CommonMark/markdown-it core; this is the
  * canonical markdown-it plugin for it.
  *
- * Block container syntax (`:::name ... :::`) was removed 2026-05-17 in favor
- * of the @marker family. See docs/migrations/2026-05-removing-container-syntax.md
- * for the migration mapping.
+ * There is no block container syntax (`:::name ... :::`): the @marker family
+ * is the wrapped-block surface. See
+ * docs/migrations/2026-05-removing-container-syntax.md for the mapping.
  *
- * GFM-style `> [!NOTE]` alerts were also moved into the DC plugin on the
- * same date because the emitted classes (dc-alert, dc-vibe-callout, etc.)
- * were DC-branded — core should not leak DC identifiers. #237 (0.10.7)
- * restored a core-owned, unbranded equivalent as an OPT-IN bundled feature —
+ * GFM-style `> [!NOTE]` alerts are an OPT-IN bundled feature (#237) —
  * `gfm-alerts.ts`, registered below as `gutterpress-gfm-alerts` — emitting
  * only the standard GitHub five (NOTE/TIP/IMPORTANT/WARNING/CAUTION) as
  * neutral `gp-alert`/`gp-alert-<type>` structure (see that file's header).
- * This does not re-converge with the DC plugin: DC's branded extra types
- * (`[!DM]`/`[!VIBE]`/`[!ORIGIN]`, etc.) and its own class names stay exactly
- * where they were moved to, layered on top of (or independent from) this
- * primitive. A project using neither plugin still renders `> [!NOTE]` as a
- * literal blockquote, unchanged — this feature is opt-in, not a default.
+ * Core emits no branded identifiers: branded extra types (e.g. DC's
+ * `[!DM]`/`[!VIBE]`/`[!ORIGIN]`) and their class names belong in project
+ * plugins, layered on top of (or independent from) this primitive. A project
+ * using neither renders `> [!NOTE]` as a literal blockquote.
  *
  * #240 — before `gutterpressMarkers` is applied, every loaded plugin's
  * declared `markers` table (if any) is merged into ONE registry via

package/dist/lib/missing-asset-placeholder.d.ts

@@ -1,15 +1,12 @@
 /**
  * A visible stand-in for an image the book references but does not have.
  *
- * WHY THIS EXISTS: a missing image used to abort the whole build
+ * WHY THIS EXISTS: without it, a missing image aborts the whole build
  * (`Could not copy asset … ENOENT`). For a non-technical author that is the
  * worst possible failure mode — one stale image path in a 273-page book and
  * nothing renders at all, with a filesystem error as the only explanation.
  * Worse, it makes the book unbuildable by anyone who does not already have
- * the missing file, which is exactly the state the dc-op-manual field guide
- * was in: two chapters referenced art that exists nowhere in the repo, so
- * every tool and every reviewer had to hand-patch placeholders in to build
- * it at all.
+ * the missing file.
  *
  * The fix is NOT to substitute something invisible. A silently-blank image
  * is how a missing illustration ships to print. This paints an unmistakable

package/dist/lib/output-paths.d.ts

@@ -2,11 +2,10 @@
  * Output location + artifact naming, by convention rather than configuration.
  *
  * A book builds to `<manifestDir>/dist/<title-slug>/`, and its artifacts are
- * `<title-slug>-<format>.pdf`. This replaces the manifest's `output.dir` /
- * `output.filename` / `output.html` block: the slug keeps several books in one
- * tree apart, and the format is in the artifact name because the extension
- * cannot tell a PDF from a PDF/X one (they previously shared a single
- * configured filename, so building both left only the last).
+ * `<title-slug>-<format>.pdf` — a convention, not manifest configuration: the
+ * slug keeps several books in one tree apart, and the format is in the
+ * artifact name because the extension cannot tell a PDF from a PDF/X one (a
+ * shared filename would leave only the last one built).
  *
  * `--out` remains for per-invocation placement (CI, one-offs).
  */

package/dist/lib/pdf-inspect.d.ts

@@ -5,7 +5,7 @@
  * pdfimages, pdftotext) and the general qpdf inspection used by the post-build
  * validation checks. It has ZERO system dependency and — unlike raw pdfjs-dist,
  * whose `legacy` build eagerly evaluates canvas/DOMMatrix code — unpdf bundles
- * cleanly under `bun build --compile` (verified). See ADR 0002.
+ * cleanly under `bun build --compile` (verified).
  *
  * NOT replaced here (still system tools, by design):
  *   - Ghostscript (gs): ink coverage + PDF/X CMYK conversion — no JS equivalent.
@@ -13,7 +13,7 @@
  *     catalog/object access pdfjs has no public API for, and qpdf is already
  *     mandatory whenever PDF/X is produced.
  *
- * Fidelity notes (accepted in ADR 0002):
+ * Fidelity notes (accepted):
  *   - Structural integrity (`isLoadable`) is a "does it parse" gate, not a deep
  *     `qpdf --check` of xref/stream-length integrity.
  *   - Image DPI requires decoding the image to read its pixel dimensions and is
@@ -25,10 +25,10 @@
  */
 import type { PDFDocumentProxy, PDFPageProxy } from "unpdf/pdfjs";
 /**
- * Cap on distinct cached documents (audit B3). One validation run touches a
+ * Cap on distinct cached documents. One validation run touches a
  * single PDF across ~13 checks (one entry), so this only bounds accumulation
  * ACROSS runs in a long-lived host (the Electron desktop validating many
- * projects over a session). Without it, `docCache` grew one never-freed parsed
+ * projects over a session). Without it, `docCache` grows one never-freed parsed
  * document per distinct path ever validated. LRU eviction destroys the evicted
  * document so its decoded pages/fonts/images are released, not just unreferenced.
  * (Exported so tests derive their eviction fixtures from the real cap.)
@@ -146,6 +146,6 @@ export declare function getImageResolutions(doc: PDFDocumentProxy): Promise<Arra
 /**
  * "Does it parse" gate: load every page. Returns true if the whole document is
  * traversable. This is NOT a deep xref/stream-length integrity check — it only
- * catches PDFs that are actually broken/unparseable (ADR 0002).
+ * catches PDFs that are actually broken/unparseable.
  */
 export declare function isLoadable(doc: PDFDocumentProxy): Promise<boolean>;

package/dist/lib/pdf-parse.d.ts

@@ -15,7 +15,7 @@ export declare function readPdfBytes(pdfPath: string): Promise<string>;
 /**
  * Parse ink coverage from `gs -sDEVICE=inkcov` output.
  *
- * Ghostscript has no pure-JS equivalent (it stays a system tool — see ADR 0002),
+ * Ghostscript has no pure-JS equivalent (it stays a system tool),
  * so the inkcov path remains shell-based here.
  */
 export declare function parseInkCov(out: string): {
@@ -34,12 +34,11 @@ interface InkCoveragePage {
     tac: number;
 }
 /**
- * Discriminated result for {@link getPerPageInkCoverage} (finding #51).
- * Ghostscript failing (crash, corrupt PDF, missing binary, a Windows PATH
- * mismatch — see finding #3) must be distinguishable from a legitimately
- * measured, empty-pages result: both used to collapse to the same `[]`,
- * which let the ink-coverage check silently PASS a book it never actually
- * measured.
+ * Discriminated result for {@link getPerPageInkCoverage}. Ghostscript failing
+ * (crash, corrupt PDF, missing binary, a Windows PATH mismatch) must be
+ * distinguishable from a legitimately measured, empty-pages result:
+ * collapsing both to the same `[]` would let the ink-coverage check silently
+ * PASS a book it never actually measured.
  */
 export type InkCoverageResult = {
     ok: true;