gutterpress 0.11.10 → 0.11.11-alpha.2

package/dist/lib/build-runner.d.ts

@@ -19,9 +19,8 @@ export interface BuildRunnerOptions {
     manifestPath?: string;
     stripAnnotations?: boolean;
     /**
-     * Skip the CSS print-safety check (#272 — one CSS gate, not two). This used
-     * to gate a separate lint-runner pass (since deleted); it now disables just the
-     * `source.stylelint` check inside pre-build validation (see
+     * Skip the CSS print-safety check (#272 — one CSS gate, not two): disables
+     * just the `source.stylelint` check inside pre-build validation (see
      * {@link computeGates}'s `skipStylelint`). Has no effect when
      * `skipPreValidate` is also set — pre-build validation, CSS check
      * included, does not run at all in that case.
@@ -132,17 +131,15 @@ export interface BuildContext {
     inputDir: string;
     /**
      * THE anchor every manifest-relative path resolves against: `styles:`,
-     * `source.files`, authored plugin `path:` entries, and the lint gate's own
-     * stylesheet resolution. Equal to {@link BuildContext.manifestDir}.
+     * `source.files`, authored plugin `path:` entries, and the CSS print-safety
+     * check's stylesheet resolution. Equal to {@link BuildContext.manifestDir}.
      *
-     * These used to resolve against two different roots in one build (2026-07-29
-     * audit): plugins, the lint gate, and the output dir anchored on
-     * `manifestDir`, while `styles:`/`source.files` anchored on `inputDir`. They
-     * are identical in the normative layout (the manifest lives in the book
-     * folder) and diverge only under an explicit `--manifest` pointing outside
-     * `--input` — where the docs are unambiguous that both are manifest-relative,
-     * so the lint gate was checking a different set of stylesheets than the ones
-     * that shipped.
+     * It is NOT `inputDir`. The two are identical in the normative layout (the
+     * manifest lives in the book folder) and diverge only under an explicit
+     * `--manifest` pointing outside `--input` — where the docs are unambiguous
+     * that all of these are manifest-relative. Anchoring any of them on
+     * `inputDir` would check a different set of stylesheets than the ones that
+     * ship.
      */
     renderDir: string;
     outDir: string;
@@ -195,17 +192,12 @@ export declare function resolveBuildContext(opts: BuildRunnerOptions): Promise<B
  * `loadPluginsWithCss` directly, and only the first caller does real work —
  * the other gets the cached result back, whichever stage happens to run
  * first (a test calling {@link renderBook} directly, without going through
- * `runQualityGates`, gets a fresh load here exactly as it would have before
- * this existed).
+ * `runQualityGates`, gets a fresh load here).
  *
- * Fail-fast (no `onError`), matching `renderBook`'s pre-existing behavior:
- * a build/export must never silently omit author-configured formatting (see
- * `loadPlugins`'s doc comment in markdown/plugins.ts on the two failure
- * modes). One consequence: a plugin that fails to load now aborts the build
- * as soon as quality gates start, instead of (as before) the lint gate's own
- * degrade-and-report call warning-and-skipping that same plugin only for
- * `renderBook` to hard-fail on it moments later — the build failed either
- * way, this just stops wasting the lint pass first.
+ * Fail-fast (no `onError`): a build/export must never silently omit
+ * author-configured formatting (see `loadPlugins`'s doc comment in
+ * markdown/plugins.ts on the two failure modes), so a plugin that fails to
+ * load aborts the build as soon as quality gates start.
  *
  * Resolves plugin `path:` entries against `ctx.renderDir`, which is by
  * construction identical to `ctx.manifestDir` for the life of one
@@ -222,13 +214,12 @@ export declare function loadBuildPlugins(ctx: BuildContext): Promise<LoadedPlugi
  * rendered book.html both output strategies then paginate. This is the shared
  * pre-format work; the per-format tails live in the strategies.
  *
- * ARCH finding #4: Gutterpress's marker parser computes typed, line-numbered
- * author-mistake warnings (`env.layoutWarnings`) that every real render path
- * used to discard silently. `renderChaptersToFile`'s `onChapterWarnings`
- * threads them back out here so a final artifact never omits a marker
- * mistake without at least telling the author about it in the build log.
- * Exported (not just for the pipeline) so this stage is unit-testable
- * without driving the full `runBuild` pagination/PDF machinery.
+ * Gutterpress's marker parser computes typed, line-numbered author-mistake
+ * warnings (`env.layoutWarnings`). `renderChaptersToFile`'s
+ * `onChapterWarnings` threads them back out here so a final artifact never
+ * omits a marker mistake without at least telling the author about it in the
+ * build log. Exported (not just for the pipeline) so this stage is
+ * unit-testable without driving the full `runBuild` pagination/PDF machinery.
  */
 export declare function renderBook(ctx: BuildContext): Promise<string>;
 /**
@@ -265,12 +256,10 @@ export declare function publishToDirectory(workDir: string, targetDir: string, f
  * The browser is this function's to own: there is ONE launcher
  * (`engine/shared/cdp.ts`'s `launchChromium`, or the host's injected
  * `engineBrowser` factory in its place), it is started un-awaited so the
- * ~1–2s Chromium cold start overlaps lint + validation + markdown render, it
+ * ~1–2s Chromium cold start overlaps validation + markdown render, it
  * is awaited right before rendering (so a missing or too-old Chromium fails
  * there, with the launcher's own message, rather than deep inside the engine),
- * and it is closed in a `finally` that runs on every exit — finding #50:
- * previously the close only happened on the success tail (inside
- * `finalizeBuild`), so a pre-launched Chromium leaked whenever a quality gate
- * or the render itself threw.
+ * and it is closed in a `finally` that runs on every exit, so a pre-launched
+ * Chromium never leaks when a quality gate or the render itself throws.
  */
 export declare function runBuild(opts: BuildRunnerOptions): Promise<BuildRunnerResult>;

package/dist/lib/build-staging.d.ts

@@ -28,11 +28,9 @@ export interface StagedAssets {
  *
  * THE one implementation: `renderBook` (every real build/export) and the
  * preview/print parity gate both call this, so the gate can never measure a
- * document the build would not have produced. It previously hand-rolled a bare
- * `copyFile` loop, which (a) hard-crashed with a raw `ENOENT` on any book
- * carrying a stale image path — i.e. the tool that enforces preview↔print
- * parity could not run on the real books that need it — and (b) skipped
- * `inlineShapeUrls`, so `.gp-shape` wrapping silently differed from the build.
+ * document the build would not have produced (a hand-rolled `copyFile` loop
+ * in the gate would crash on a stale image path and skip `inlineShapeUrls`,
+ * silently diverging from the build).
  *
  * A missing image is NOT fatal: the same magenta placeholder the build ships
  * (see missing-asset-placeholder.ts) is substituted and every reference

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