gutterpress 0.9.0-alpha.2 → 0.10.0-alpha.4

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

@@ -2,12 +2,18 @@ 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 `markdown-it-paged` (ARCH finding #4).
- * Mirrors the shape `markdown-it-paged.js`'s `warn()` pushes onto
- * `env.layoutWarnings` — see that file's header comment for the 8 warning
- * `type`s (`ambiguous_marker_token`, `section_without_page`, `nested_spread`,
+ * One author-mistake warning emitted by Gutterpress's marker parser (ARCH finding #4).
+ * 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`,
+ * `extra_bare_marker_token`, `unknown_marker`, `nested_spread`,
  * `continue_without_section`, `spread_without_pages`, `spread_eof_close`,
- * `page_outside_spread`, `implicit_page`).
+ * `page_outside_spread`, `pin_outside_page`).
+ *
+ * `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.
  */
 export interface LayoutWarning {
     line: number;
@@ -28,9 +34,9 @@ export interface AssembleBookHtmlOptions {
      * Inlining is what makes a stylesheet's location irrelevant to the output, so
      * themes (`themes/<id>/theme.css`) and shared design systems
      * (`../design-guide/styles/guide.css`) need no copying, no flattening and no
-     * destination indirection. It is also what Paged.js does to the document
-     * anyway — it deletes every `<link>`/`<style>` and re-emits the CSS inline —
-     * so a `<link>` never survived the render path to begin with.
+     * destination indirection. The assembled document therefore has one
+     * deterministic CSS payload, with no output-relative stylesheet links to
+     * relocate or lose during staging.
      */
     projectCss?: string;
     title?: string;
@@ -43,10 +49,12 @@ export interface AssembleBookHtmlOptions {
      * output is unaffected.
      */
     wrapChapters?: boolean;
+    /** Add a layout-neutral source-file id to source-mapped preview blocks. */
+    annotateSourceChapters?: boolean;
     /**
      * ARCH finding #4: per-chapter callback receiving any `env.layoutWarnings`
-     * `markdown-it-paged` computed while rendering `file` (only called when
-     * that chapter produced at least one). `file` is the same canonical
+     * 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

package/dist/lib/markdown/gp-pin-scope.d.ts

@@ -0,0 +1 @@
+export default function gpPinScope(md: any): void;

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

@@ -0,0 +1,125 @@
+/**
+ * GUTTERPRESS_CSS — the `gp-*` author vocabulary.
+ *
+ * This is Gutterpress's broad author-vocabulary stylesheet. The separate
+ * `MARKER_CSS` block owns only the `.page`/`.spread`/`.section`/`.chapter`
+ * structure emitted by Gutterpress's marker parser; this file owns the `gp-*`
+ * classes authors apply to content. Keeping the two core blocks separate makes
+ * that ownership boundary explicit without implying an external plugin.
+ *
+ * Injected by assemble.ts immediately AFTER `MARKER_CSS` and BEFORE user plugin
+ * and project CSS, so the cascade order is: marker layout primitives ->
+ * Gutterpress vocabulary -> plugin CSS -> the author's stylesheets last. An
+ * author overriding a `gp-*` class at equal specificity still wins.
+ *
+ * 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
+ * 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.
+ *
+ *   .gp-left      — floats left, text wraps.
+ *   .gp-right     — floats right, text wraps.
+ *   .gp-center    — centers a block element.
+ *   .gp-full      — fills the page's content width.
+ *   .gp-small     — width 25% of the column. Sizes compose with any
+ *   .gp-medium    — width 50%.        position (including .gp-pin, where
+ *   .gp-large     — width 75%.        the % resolves against the page box).
+ *   .gp-tight     — float/shape clearance 0.5em (sets --gp-gap; default 1em).
+ *   .gp-loose     — float/shape clearance 2em (sets --gp-gap).
+ *   .gp-shape     — wraps text to a floated image's alpha silhouette
+ *                   (shape-outside; the pipeline mirrors the src into
+ *                   --gp-shape because CSS url() contexts can't read
+ *                   attr()). Floats only; inert elsewhere.
+ *   .gp-pin       — pins within the nearest @page/@spread container;
+ *                   centered on both axes unless combined with the edge
+ *                   modifiers .gp-top/.gp-bottom/.gp-left/.gp-right.
+ *   .gp-bleed     — forces its own page (break-before) and spans it
+ *                   edge-to-edge horizontally. This does NOT cancel the
+ *                   top/bottom margins, extend past the trim into printer
+ *                   bleed overage, or remove headers/footers — none of
+ *                   that is implemented.
+ *
+ *                   The mechanism is a named page: the rule below assigns the
+ *                   element's page to `@page gp-full-bleed`, which has zero
+ *                   side margins, so the page's own CONTENT box IS the sheet
+ *                   and a plain `width: 100%` already reaches both edges —
+ *                   with no shrink-to-fit trigger, because nothing out-dents
+ *                   past the content box. MEASURED (Chromium 148, 6x4in
+ *                   sheet, 0.75in margins): the earlier mechanism (a negative
+ *                   out-dent of the real page margins, inherited from the
+ *                   Paged.js era, where the polyfill published them as
+ *                   `--pagedjs-margin-left/right`) shrank the WHOLE document
+ *                   ~10% under native print (text run 204.4pt -> 182.9pt),
+ *                   because the shrink-to-fit trigger is the page CONTENT
+ *                   box, not the sheet — that failure mode is why the named
+ *                   page exists. Paged.js has since been removed
+ *                   (native-only-migration-plan.md Phase 6), so the out-dent
+ *                   (whose custom properties nothing sets any more, making it
+ *                   a permanent no-op) went with it.
+ *
+ *                   KNOWN GAP: on the bleed page, native's running head/folio
+ *                   move onto the trim line (margin boxes are positioned by
+ *                   the page's own margins, which are now zero on this named
+ *                   page). This is not fixed in core — see
+ *                   docs/native-engine-styling-guide.md §9 for the one-line
+ *                   author remedy (`@top-center { content: none }` etc. on
+ *                   `@page gp-full-bleed`).
+ *
+ *                   A standalone `![Art](x.jpg){.gp-bleed}` markdown image
+ *                   is rendered as `<p><img class="gp-bleed"></p>` — a
+ *                   naked markdown-it standalone-image wrap, not something
+ *                   this plugin controls. The `<p>`'s UA default vertical
+ *                   margin sits above/below an image sized to the page's
+ *                   full content box, overflows the box by that margin, and
+ *                   on native print pushes the whole page onto a spurious
+ *                   extra sheet, which then renders BLANK (the art landed on
+ *                   the sheet after). MEASURED (300dpi, 6x9in sheet, a
+ *                   4-source-file fixture book): with the paragraph margin
+ *                   left at UA default, native emits 8pp with page 6 fully
+ *                   blank (0 dark pixels of 540,000 sampled); zeroing the
+ *                   wrapping paragraph's margin below gives the intended
+ *                   7pp with the art bleeding edge-to-edge on page 6. Scoped
+ *                   to `:only-child` so a `.gp-bleed` image sharing a
+ *                   paragraph with other inline content keeps its margin.
+ *
+ * Rule ORDER within the gp-* block is the contract: flow positions → sizes
+ * → spacing → .gp-pin → pin-edge modifiers. Everything is flat 0-1-0
+ * specificity, so combining classes resolves by source order: a later flow
+ * position wins (left < right < center < full < bleed); an explicit size's
+ * max-width:100% lifts the floats' 50% cap; .gp-pin's margin:0 /
+ * max-width:100% beat the float declarations; the edge modifiers beat
+ * .gp-pin's center defaults.
+ *
+ * .gp-pin semantics, stated honestly: it pins within its @page/@spread
+ * CONTAINER, not "the sheet edge". A .page div that fragments across
+ * several printed sheets is ONE containing block, so align-self:end is the
+ * end of the run. For the single-page layouts pin is meant for (title
+ * pages, chapter openers, watermark pages) the two are the same thing. A
+ * .gp-pin outside any @page/@spread resolves against the document canvas
+ * and can print on a completely different sheet — the gp_pin_scope_check
+ * core rule below warns at parse time (`pin_outside_page`), and the
+ * compiler's engine.abspos.leak diagnostic catches the raw-HTML cases the
+ * token walk can't see.
+ *
+ * Pin CSS mechanics (all three are load-bearing, verified by
+ * paged-css-image-pin.test.ts): `inset: 0` is REQUIRED — abspos
+ * self-alignment aligns within the inset-modified containing block, and
+ * with auto insets that collapses to the static-position rectangle, where
+ * alignment does nothing. The center defaults must be EXPLICIT — `normal`
+ * alignment behaves as `start` for abspos replaced elements, not center.
+ * And `justify-self` on .gp-left/.gp-right does double duty (flow float +
+ * pin edge) because self-alignment does not apply to in-flow floats — it is
+ * inert until .gp-pin makes the element abspos. If Chrome ever ships
+ * block-level self-alignment for in-flow boxes, a non-floated element
+ * 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/* 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), the same mechanism\n       that clips a .gp-bleed plate back to the wrapper's width.\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";

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

@@ -15,11 +15,37 @@ import type MarkdownIt from "markdown-it";
  * author's own folder layout is the layout that ships. Paths are emitted
  * verbatim; the build resolves them against the project root, which is the
  * frame `book.html` is served from.
+ *
+ * One render-time ADDITION (not a src rewrite): an image carrying the
+ * `.gp-shape` class gets an inline `--gp-shape: url("<src>")` custom
+ * property, mirroring the src byte-for-byte. MARKER_CSS's `img.gp-shape`
+ * rule reads it for `shape-outside` — CSS cannot reference an element's own
+ * src in a url() context (attr() is blocked there), so the pipeline is the
+ * only place the mirror can happen. Authors only ever type the class.
+ * Raw-HTML `<img>` tags are not touched — `.gp-shape` is a markdown-image
+ * feature; raw HTML authors write the style attribute themselves.
  */
 /** Env slot the rule appends to. Absent when nothing referenced an image. */
 export interface ImageRefEnv {
     imageRefs?: string[];
 }
+/**
+ * Extract URL candidates with the same important boundaries as the HTML
+ * Standard's srcset parser.
+ *
+ * A comma is legal inside a URL (most visibly in `data:image/...,...`), so a
+ * `split(",")` invents bogus local assets from payload text. The browser first
+ * consumes a URL through ASCII whitespace, then parses descriptors until the
+ * candidate-separating comma. A trailing comma on a descriptor-less URL is
+ * the separator and is removed; earlier commas remain part of the URL.
+ */
+export interface SrcsetUrlCandidate {
+    url: string;
+    /** Half-open offsets of the URL itself (separators/descriptors excluded). */
+    start: number;
+    end: number;
+}
+export declare function parseSrcsetUrlCandidates(input: string): SrcsetUrlCandidate[];
 export declare function registerImageRule(md: MarkdownIt): void;
 /**
  * Collect local image references from raw HTML in rendered output.

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

@@ -39,10 +39,12 @@ export declare function renderChapters(inputDir: string, opts?: {
     pluginCss?: string;
     /** Wrap each source file for incremental preview pagination. */
     wrapChapters?: boolean;
+    /** Add source-file ids to source-mapped preview blocks without wrappers. */
+    annotateSourceChapters?: boolean;
     /**
      * ARCH finding #4: per-chapter author-mistake warnings computed by
-     * markdown-it-paged (`env.layoutWarnings`), forwarded straight through
-     * from {@link assembleBookHtml}. See that option's docstring — omitting
+     * Gutterpress's marker parser (`env.layoutWarnings`), forwarded straight
+     * through from {@link assembleBookHtml}. See that option's docstring — omitting
      * it is fully backward compatible.
      */
     onChapterWarnings?: (file: string, warnings: LayoutWarning[]) => void;

package/dist/lib/markdown/inline-source.d.ts

@@ -0,0 +1,10 @@
+import type MarkdownIt from "markdown-it";
+export declare const SOURCE_TOKEN_ATTR = "data-gp-source-token";
+export declare const SOURCE_OCCURRENCE_ATTR = "data-gp-source-occurrence";
+/**
+ * Attach the exact source token and its literal occurrence to rendered
+ * Markdown images and links. The Markdown parser remains the sole syntax
+ * authority; desktop menus consume these coordinates instead of reparsing or
+ * guessing from DOM src/text values.
+ */
+export declare function registerInlineSourceMetadata(md: MarkdownIt): void;

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

@@ -0,0 +1,32 @@
+export default function plugin(md: any, pluginOptions?: {}): void;
+/**
+ * The minimal CSS the DOM this module emits requires. Author utility
+ * vocabulary lives in gutterpress-css.ts — see the ownership note above.
+ * Consumers should inject this into <head> after their user stylesheets so
+ * the layout contract (page/section/column breaks) wins at equal specificity.
+ *
+ * `.page`/`.spread` are given `position: relative` so they are the containing
+ * block for any abspos descendant: a mispinned `bottom: 0` now fails LOCALLY
+ * on its own page instead of resolving against the document canvas and
+ * painting on the last page of the book.
+ *
+ * The break/orphan rules below (`break-after` on headings, image sizing,
+ * first-child glue) are all `:where()` so they carry zero specificity —
+ * author CSS at any specificity wins outright, reusing this same
+ * after-author injection point.
+ *
+ * `vertical-align: bottom` on a lone image is a print-correctness rule, not
+ * cosmetics. An `<img>` in a `<p>` is inline-level, so its line box adds
+ * half-leading/descender space UNDER the image: an image sized to exactly the
+ * page content box (a book capping art at `page-height - margins`, or art that
+ * naturally fills the page) produces a paragraph a few px TALLER than the box
+ * it was sized to fit. MEASURED (Chromium 148, field guide chapter 1, 10in
+ * content box): a 956px image made a 963.59px paragraph — a 3.6px overflow
+ * that pushed the enclosing named-page wrapper's bottom edge onto the NEXT
+ * sheet, so Chromium named that sheet after the PREVIOUS page name and the new
+ * template's running head and folio silently vanished. `vertical-align:
+ * bottom` collapses the line box onto the image, keeping the image inline (so
+ * `text-align: center` still centers it — `display: block` would not).
+ *
+ */
+export const MARKER_CSS: "\n/* The UA default of 8px body margin is a screen affordance with no meaning\n   in paged media, and engines disagree about it: a polyfill that treats the\n   page div as the page box drops it, native print keeps it. Left in place it\n   insets EVERY page's content by 8px per side, and -- measured, 300dpi,\n   6x4in sheet -- it is what stops a full-width block from reaching the\n   paper: it lands at 0.080..5.917in of a 6in sheet instead of\n   0.000..6.000in, because width:100% resolves against the BODY content box,\n   not the page's. Zeroing it here (first in the cascade) makes the two\n   agree. Authors who want a body margin still just declare one. */\nbody { margin: 0; }\n\n.gp-page-break { break-before: page; }\n.page { break-before: page; }\n.spread { break-before: page; }\n:where(.page, .spread) { position: relative; }\n.gp-column-break { break-after: column; height: 0; font-size: 0; line-height: 0; visibility: hidden; }\n\n:where(h1,h2,h3,h4,h5,h6) { break-after: avoid; }\n:where(img, svg, video) { max-width: 100%; }\n:where(p > img:only-child, figure > img) { width: fit-content; max-width: 100%; height: auto; vertical-align: bottom; }\n:where(.section, figure) > :where(:first-child) { break-before: avoid; }\n\n";

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

@@ -2,8 +2,8 @@
  * Pure (node-free) markdown rendering core.
  *
  * §1/§8 / ADR 0004: this module imports ONLY pure JS — markdown-it and its
- * plugins, the inlined `markdown-it-paged.js`, and the node-free leveled
- * logger (console-only). It contains NO `node:*`,
+ * 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
  * `bun build --compile` CLI binary alike.
@@ -79,7 +79,12 @@ export declare const BUILTIN_OPTIONAL_PLUGINS: Record<string, GutterpressPlugin>
  *
  * Built-in pipeline (runs before any user plugins):
  *   markdown-it-attrs → markdown-it-footnote → markdown-it-deflist →
- *   markdown-it-source-map → markdown-it-paged
+ *   markdown-it-source-map → Gutterpress markers
+ *
+ * The `source_range` core rule (source-range.ts, `data-source-range`) is
+ * registered LAST — after any custom (manifest) plugins — so it always sees
+ * the final token stream. It is additive alongside `markdown-it-source-map`'s
+ * `data-source-line`, whose coverage (level-0 blocks only) is unchanged.
  *
  * markdown-it-deflist adds the standard (PHP Markdown Extra / Pandoc)
  * definition-list syntax — `Term` / `: definition` — emitting plain

package/dist/lib/markdown/source-range.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `source_range` — pure (node-free) markdown-it core rule.
+ *
+ * Annotates every open block-level token (`*_open`, nesting === 1) and every
+ * self-closing block token with a usable range (`fence`, `hr`, `html_block`,
+ * plus this project's own `layout_page_break` / `layout_column_break`) with
+ * `data-source-range="<start>:<end>"` — markdown-it's own `token.map`
+ * semantics verbatim: 0-based line index, half-open `[start, end)`.
+ *
+ * Range source, in priority order:
+ *   1. `token.map` — ordinary markdown blocks (paragraphs, headings, list
+ *      items, blockquotes, table rows, fences, footnote definitions, …).
+ *   2. `token.meta.line` — the 1-based marker line threaded onto
+ *      `layout_*_open` / `layout_page_break` / `layout_column_break` tokens
+ *      by `markdown-it-paged.js` (see that file's header and the
+ *      `t.meta = …` assignment sites). Converted to the same half-open
+ *      convention as `[line - 1, line)`.
+ *
+ * Both sources are rejected unless `Number.isFinite` — a malformed/missing
+ * line (the `@continue`-drops-`__line` bug class) must skip the token, not
+ * silently resolve to a `NaN`-derived or whole-document range. This is the
+ * exact "fail wrong" this primitive exists to prevent downstream (see
+ * `docs/inline-editing-plan.md` §1 principle 3, §2.6, ADR 0009).
+ *
+ * This rule is registered UNCONDITIONALLY, after any custom (manifest)
+ * plugins have been applied — see `renderer.ts` — so it sees the final
+ * token stream regardless of what plugins are or are not configured, and so
+ * a user plugin's own core rules (which may add/rewrite tokens) are
+ * annotated too.
+ *
+ * `state.tokens` is already ONE FLAT array covering every block nesting
+ * depth (list items inside blockquotes, table rows, nested `@section`s, …) —
+ * markdown-it's block-level parser never nests these via `token.children`,
+ * so a single pass over `state.tokens` reaches every nesting level with no
+ * recursion. `token.children` exists only on `inline` tokens, holding
+ * text-level marks (`strong_open`, `em_open`, `link_open`, `code_inline`,
+ * …); those carry no usable per-token `map` and are deliberately NOT
+ * walked here — annotating them would do nothing (their own attrs are
+ * never rendered; `Renderer.renderInline` renders only their children) and
+ * would blur the intentional "one range per block" contract this primitive
+ * promises consumers.
+ *
+ * Idempotency: uses `token.attrSet` (not `attrPush`) so a token re-rendered
+ * on a shared `MarkdownIt` instance gets its attribute overwritten, never
+ * duplicated.
+ *
+ * Deliberate gap (locked in by a negative test, see `renderer.test.ts`):
+ * raw HTML blocks (`html_block`) DO retain `token.map` and so DO get
+ * `data-source-range` set here — but markdown-it's own `html_block`
+ * renderer rule (`return token.content`) discards `token.attrs` entirely,
+ * so the attribute never reaches rendered output. Overriding that renderer
+ * rule to wrap raw HTML in a synthetic element was rejected (own blast
+ * radius); see `docs/inline-editing-plan.md` §2.6.
+ */
+import type { RuleCore } from "markdown-it/lib/parser_core.mjs";
+/** The attribute this rule writes. Exported so tests/consumers don't hardcode the string. */
+export declare const SOURCE_RANGE_ATTR = "data-source-range";
+export declare const SOURCE_CHAPTER_ATTR = "data-chapter-src";
+/** The core rule itself — registered via `md.core.ruler.push("source_range", sourceRangeRule)` in renderer.ts. */
+export declare const sourceRangeRule: RuleCore;
+export default sourceRangeRule;

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

@@ -0,0 +1,52 @@
+/**
+ * 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
+ * (`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 fix is NOT to substitute something invisible. A silently-blank image
+ * is how a missing illustration ships to print. This paints an unmistakable
+ * magenta/black checkerboard: the build completes, the author is warned by
+ * path, and the hole is impossible to miss when flipping through the PDF.
+ *
+ * FORMAT: a hand-encoded PNG, because the alternative — embedding a fixture
+ * file — cannot adapt its dimensions, and a wrongly-shaped placeholder
+ * distorts the surrounding layout while the author is trying to judge it.
+ * PNG is the only format written. The staging pipeline writes it to the
+ * dedicated `.png` path returned by {@link placeholderOutputPath} and rewrites
+ * every rendered reference to that path, so a missing `.jpg`/`.webp`/etc. can
+ * never turn this loud fallback into a browser broken-image icon.
+ */
+/**
+ * Collision-resistant, output-relative path for a missing image's PNG.
+ *
+ * Keeping placeholders under one engine-owned directory avoids overwriting an
+ * author's real file (which an appended `.missing.png` sibling name could do),
+ * while hashing the original output path keeps repeat references deterministic.
+ */
+export declare function placeholderOutputPath(missingOutputPath: string): string;
+/**
+ * Rewrite missing local image URLs in rendered HTML to their real PNG paths.
+ *
+ * Covers ordinary `src`, every `srcset` candidate, and CSS `url()` tokens in
+ * actual `<style>` blocks / `style` attributes. The structural boundary is
+ * load-bearing: prose examples and scripts may legitimately contain the same
+ * `url("missing.jpg")` text and must remain byte-for-byte authored. The CSS
+ * pass is required for `.gp-shape`: its mirrored `--gp-shape` URL must point
+ * at the same staged PNG before `inlineShapeUrls()` reads and embeds it.
+ */
+export declare function rewriteMissingImageReferences(html: string, replacements: ReadonlyMap<string, string>): string;
+/**
+ * Encode a checkerboard PNG of `width`×`height` at `cell` pixels per square.
+ * Truecolor (8-bit RGB, no alpha) with filter byte 0 per scanline — the
+ * simplest encoding that every decoder handles, and small enough that the
+ * deflate cost is irrelevant next to a book build.
+ */
+export declare function placeholderPng(width?: number, height?: number, cell?: number): Uint8Array;

package/dist/lib/presets.d.ts

@@ -8,7 +8,7 @@ import type { ResolvedConfig } from "../schema/manifest.types";
  * Every preset value is overridable from the manifest, leaf by leaf
  * (resolveConfig's mergeShape; precedence cli > manifest > target > preset).
  */
-export interface VendorPreset extends Omit<ResolvedConfig, "title" | "authors" | "targets" | "page"> {
+export interface VendorPreset extends Omit<ResolvedConfig, "title" | "authors" | "targets" | "page" | "engine"> {
     /**
      * Base page geometry in points, or `null` for `custom` — the one preset
      * with no built-in trim, which therefore REQUIRES the manifest to supply

package/dist/lib/printsafe.d.ts

@@ -1,7 +1,7 @@
 export declare const ruleRemoteUrls = "printsafe/no-remote-urls";
 export declare const ruleRiskyProps = "printsafe/no-risky-print-effects";
-export declare const rulePagedjsCrashSelectors = "printsafe/no-pagedjs-crash-selectors";
 export declare const ruleSyntax = "printsafe/syntax-error";
+export declare const rulePageContainment = "printsafe/page-containment";
 export interface PrintSafeWarning {
     rule: string;
     severity: "error" | "warning";
@@ -11,7 +11,6 @@ export interface PrintSafeWarning {
 }
 /**
  * Run print-safety checks against a CSS string. Returns one warning per finding
- * (errors for remote URLs / crash-prone selectors / syntax errors; warnings for
- * risky print effects).
+ * (errors for remote URLs / syntax errors; warnings for risky print effects).
  */
 export declare function checkCss(css: string, from?: string): PrintSafeWarning[];

package/dist/lib/remote-auth/converge-merge.d.ts

@@ -0,0 +1,48 @@
+import type { GitCache, ImageClash } from "./sync-types.ts";
+export type { ImageClash };
+export interface ConvergeResult {
+    /** The branch tip after the merge (the merge commit, or the ff/no-op tip). */
+    oid: string;
+    /**
+     * Files whose text now contains BOTH versions inside git conflict markers —
+     * the writer should blend these. Empty when everything merged cleanly.
+     */
+    combinedFiles: string[];
+    /** Clashing images (newer version kept) for the non-blocking picker. */
+    imageClashes: ImageClash[];
+}
+/** Snapshot message for the equalization commit (driver-unreachable cases). */
+export declare const CONVERGE_PREPARE_MESSAGE = "Getting your changes ready to combine with the online version";
+/** Snapshot message for the post-merge restore commit (newer-wins/edits). */
+export declare const CONVERGE_RESTORE_MESSAGE = "Kept the newest version of files that can't be combined";
+/** The merge commit message (same wording the old sync used). */
+export declare const CONVERGE_MERGE_MESSAGE = "Combined your changes with the online version";
+/**
+ * diff3 merge that NEVER reports a conflict: clean hunks merge exactly like
+ * git's default driver; clashing hunks keep BOTH versions inside standard
+ * git conflict markers. Exported for tests.
+ */
+export declare function mergeWithMarkers(baseContent: string, ourContent: string, theirContent: string): string;
+/**
+ * Merge `theirs` into `branch` so that the merge ALWAYS lands, applying the
+ * fixed converge policy documented in the module header. The working tree is
+ * synced to the result. Caller holds the repo lock and passes its
+ * function-scoped object cache.
+ *
+ * Throws only for genuinely unmergeable situations that the caller maps to a
+ * plain error outcome (e.g. unrelated histories when `allowUnrelated` is
+ * false — a wrong online address must not silently splice two books).
+ */
+export declare function convergeMerge(params: {
+    dir: string;
+    cache: GitCache;
+    branch: string;
+    theirs: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    authorName?: string;
+    authorEmail?: string;
+    allowUnrelatedHistories?: boolean;
+}): Promise<ConvergeResult>;

package/dist/lib/remote-auth/image-clash.d.ts

@@ -0,0 +1,17 @@
+/** Read one version's exact bytes by BLOB oid. */
+export declare function readImageVersion(options: {
+    projectDir: string;
+    oid: string;
+}): Promise<Uint8Array>;
+/**
+ * Keep a specific version of a clashing image: write the blob's exact bytes
+ * to the file and snapshot. Serialized on the per-repo lock like every other
+ * mutating operation.
+ */
+export declare function keepImageVersion(options: {
+    projectDir: string;
+    path: string;
+    oid: string;
+    authorName?: string;
+    authorEmail?: string;
+}): Promise<void>;