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

package/dist/engine/compiler/build.d.ts

@@ -0,0 +1,139 @@
+import { type Browser } from "../shared/cdp.ts";
+import { type GcpmModel } from "../shared/gcpm-extract.ts";
+import { type Tier2Output } from "./tier2.ts";
+import { type PostprocessResult } from "./postprocess.ts";
+/**
+ * Codes are stable identifiers a UI can map to a plain-language label; the
+ * set is closed here so a surface's label table can be asserted complete
+ * against it rather than drifting silently as checks are added.
+ */
+export type BuildDiagnosticCode = "engine.width.overflow" | "engine.width.intrinsic" | "engine.xref.broken" | "engine.abspos.leak" | "engine.layer.trapped" | "engine.multicol.dead-column" | "engine.content.overheight" | "engine.image.low-dpi";
+export declare const BUILD_DIAGNOSTIC_CODES: readonly BuildDiagnosticCode[];
+export interface BuildDiagnostic {
+    code: BuildDiagnosticCode;
+    severity: "warning" | "info";
+    /** Plain-language, already naming the offending element. */
+    message: string;
+}
+export interface BuildOptions {
+    input: string;
+    output?: string;
+    signature?: number;
+    marks?: boolean;
+    slugPt?: number;
+    bleedPt?: number;
+    title?: string;
+    author?: string;
+    maxPasses?: number;
+    /** raster resolution below which the audit warns; 0 disables. Default 300. */
+    dpiFloor?: number;
+    /** downgrade the pre-print width check from a build error to a warning */
+    allowShrink?: boolean;
+    /** reuse a warm browser (dev server) */
+    browser?: Browser;
+    onProgress?: (msg: string) => void;
+}
+export interface BuildResult {
+    bytes: Uint8Array;
+    tier: 1 | 2 | 3;
+    passes: number;
+    pageCount: number;
+    genCss: string;
+    geometry: Tier2Output["geometry"];
+    /**
+     * Engine-internal reasons (which tier ran, why tier 3 did not converge) —
+     * developer-facing, printed by the engine dev CLI. Author-facing findings
+     * live in {@link BuildResult.diagnostics}, never here: one finding, one
+     * channel.
+     */
+    notes: string[];
+    /**
+     * Author-facing print-quality findings, carried to whatever surface the
+     * caller has — the desktop's Problems panel, the CLI's build output. Each
+     * carries a stable `code` so a surface can label it in plain language
+     * without parsing the message.
+     */
+    diagnostics: BuildDiagnostic[];
+    post: PostprocessResult;
+    /** id -> 1-based page, the measurement channel's output (print/Chromium) */
+    pageMap: Record<string, number>;
+    converged: boolean;
+    /** how many times Page.printToPDF actually ran (§10: 1 in the common case) */
+    prints: number;
+    /**
+     * §10's predict-then-verify guess, read straight from the in-browser
+     * viewer (`fragmentDocument()`) against the SAME target ids as
+     * {@link BuildResult.pageMap} — i.e. the desktop preview's own
+     * fragmenter's opinion of where each id landed. `null` when Tier 3 never
+     * ran (no `needsMeasure` reason), so there is nothing to predict.
+     * Exposed for the native-vs-print parity gate
+     * (`scripts/native-parity-gate.ts`) — not consumed elsewhere.
+     */
+    predicted: {
+        pageMap: Record<string, number>;
+        pageCount: number;
+    } | null;
+    /**
+     * The deterministic device-pixel viewport (`sheetViewport`, §"deterministic
+     * viewport = the sheet") this build pinned Chromium to. A caller that wants
+     * to mount its OWN extra viewer page against the same document (the
+     * native-vs-print parity gate's page-count check on a Tier-1/2 book, where
+     * {@link BuildResult.predicted} is `null`) needs this to reproduce the same
+     * fragmentation the build measured — an unpinned viewport free-sizes off
+     * whatever window the browser happens to have open.
+     */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * `counter-reset: page N` sites (id + declared start), resolved against
+     * measured page numbers — the input `restartedPageValues()` needs to
+     * convert either {@link BuildResult.pageMap} or
+     * {@link BuildResult.predicted} into resolved `target-counter()` values
+     * the same way {@link BuildResult.pageMap}'s own synthesis did.
+     */
+    resetSites: Array<{
+        id: string;
+        start: number;
+    }>;
+}
+export declare function build(opts: BuildOptions): Promise<BuildResult>;
+/**
+ * Bare-fragment xref hrefs (`#foo`) among `sites` whose target id never
+ * resolved to an element, i.e. is absent from `resolved` (the id -> text map
+ * `targetTexts` only populates for ids it actually found). Non-bare hrefs
+ * (`other.html#x`, `https://…`) are the author linking elsewhere on purpose —
+ * skipped by construction, since only `#...` hrefs are compared. Deduped by
+ * href, first-seen order — one typo'd target should not produce a note per
+ * link site.
+ */
+export declare function findBrokenXrefRefs(sites: Array<{
+    href: string;
+}>, resolved: Record<string, string>): string[];
+export declare function mapSignature(map: Record<string, number>, pageCount: number): string;
+/**
+ * Per-page running strings, without touching page names.
+ *
+ * `string-set`/`string()` is unimplemented in Chromium, so the value a margin
+ * box should show changes page by page with nothing in CSS to express it. The
+ * fix is a generated `@counter-style { system: fixed; symbols: … }` with one
+ * symbol per page, consumed as `counter(page, gp-<name>)` — verified in S3.
+ * Rendering stays inside Chromium with the document's own fonts, and the
+ * author's `@page` rules are never renamed or rewritten.
+ *
+ * Every page context is emitted with its FULLY RESOLVED content, including the
+ * suppressions (`content: none`). That is not defensive style: Chromium does
+ * not apply page-selector specificity ACROSS stylesheets, so an `@page :left {
+ * @top-center { content: none } }` in the author's sheet does not beat a plain
+ * `@page { @top-center { … } }` in the generated sheet — the head would be
+ * drawn twice. Resolving here removes the dependency entirely.
+ */
+export declare function counterStyleCss(model: GcpmModel, sources: Array<{
+    name: string;
+    id: string;
+    text: string;
+}>, pageMap: Record<string, number>, pageCount: number, resetSites?: Array<{
+    id: string;
+    start: number;
+}>, hasBlank?: boolean): string;

package/dist/engine/compiler/postprocess.d.ts

@@ -0,0 +1,23 @@
+import type { PageTrim } from "./tier2.ts";
+export interface PostprocessOptions {
+    geometry: PageTrim;
+    /** append blank pages until pageCount % signature === 0 */
+    signature?: number;
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string[];
+    /** draw crop marks even if CSS didn't ask */
+    marks?: boolean;
+}
+export interface PostprocessResult {
+    bytes: Uint8Array;
+    pageCount: number;
+    padded: number;
+    boxes: {
+        media: number[];
+        bleed: number[];
+        trim: number[];
+    };
+}
+export declare function postprocess(input: Uint8Array, opts: PostprocessOptions): Promise<PostprocessResult>;

package/dist/engine/compiler/tier2.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Tier 2 (§8) — compile-time synthesis, no measurement.
+ *
+ * Emits `gp.gen.css` (an inspectable build artifact; the author's files are
+ * never modified) plus the DOM hooks it needs:
+ *
+ *  - running headers at CHAPTER granularity: when a `string-set` source also
+ *    starts a named-page run, each run gets a generated named page whose
+ *    margin-box `content` is the literal heading text — standard CSS Chromium
+ *    executes natively, one pass, no measurement.
+ *  - `bleed` / `marks`: rewrite `size` to trim + 2×bleed (+ 2×slug), shift
+ *    margins so content stays put relative to trim, and compensate margin-box
+ *    insets so headers/footers don't drift into the bleed.
+ */
+import { type Declarations, type GcpmModel } from "../shared/gcpm-extract.ts";
+export declare const DEFAULT_SLUG_PT = 18;
+export interface PageTrim {
+    /** trim size (author's `size`) in pt */
+    trim: {
+        width: number;
+        height: number;
+    };
+    /** printed media size in pt (trim + 2*bleed + 2*slug) */
+    media: {
+        width: number;
+        height: number;
+    };
+    bleed: number;
+    slug: number;
+    marks: string[];
+}
+export interface Tier2Input {
+    model: GcpmModel;
+    /** finishing options; CSS values win when both exist (§10) */
+    marks?: boolean;
+    slugPt?: number;
+    bleedPt?: number;
+}
+export interface Tier2Output {
+    css: string;
+    geometry: PageTrim;
+    /** true when the document uses constructs that need Tier 3 */
+    needsTier3: boolean;
+    notes: string[];
+}
+/** Which pages does the document need running strings on, and can Tier 2 do it? */
+export declare function classify(model: GcpmModel): {
+    tier2Strings: string[];
+    tier3Strings: string[];
+    tier3Reasons: string[];
+};
+/** Pseudo-pages the author actually used, e.g. ["left", "right", "blank"]. */
+export declare function pseudoVariants(model: GcpmModel): string[];
+/** String names referenced by a `string()` in some margin box. */
+export declare function consumedStrings(model: GcpmModel): Set<string>;
+export declare function pageGeometry(model: GcpmModel, opts: Tier2Input): PageTrim;
+/**
+ * The emitted page margin for one side.
+ *
+ * Normally the authored margin plus the bleed+slug the compiler added to the
+ * page size, so content stays where the author put it RELATIVE TO TRIM.
+ *
+ * A zero authored margin is different in kind: it means "content fills the
+ * page", and inflating it would put a white border exactly where the author
+ * asked for full-bleed art — the one thing bleed exists for. Chromium clips
+ * content to the content box (measured: nothing paints outside it, not even
+ * `html { background }`), so a bleeding page must have a content box that
+ * REACHES the bleed area. Emitting the slug alone makes the content box
+ * exactly the bleed box: art fills it, crop marks stay clear.
+ */
+export declare function bleedMargin(authored: number, g: PageTrim): number;
+/**
+ * Shift a margin box's content back toward the trim box by `inset` pt, so the
+ * bleed/slug the compiler added to the page size does not push running heads
+ * and folios outward.
+ */
+export declare function marginBoxInset(name: string, inset: number): Declarations;
+export declare function synthesize(input: Tier2Input): Tier2Output;

package/dist/engine/shared/cdp.d.ts

@@ -0,0 +1,104 @@
+export declare function findChromium(): string;
+/**
+ * Gutterpress targets exactly one engine.
+ *
+ * THE 151 INCIDENT: Chromium's Paged Media behaviour is not stable across
+ * milestones, and it changed once in a way that produced NO error. 151 began
+ * PARSING `target-counter()` while still computing it to `none`. Before 151,
+ * an unsupported `target-counter()` declaration was dropped by the cascade
+ * (invalid at parse time), so Gutterpress's `generatedContentCss()` override, which
+ * targets the SAME property on the SAME selector, was the only rule left
+ * standing. At 151, the author's declaration started parsing as valid — so
+ * it stayed in the cascade, and on equal specificity, source order (the
+ * author's stylesheet loads after Gutterpress's) let it win. Every cross-reference
+ * in the document disappeared, quietly.
+ *
+ * WHY THE FLOOR MOVED BACK TO 148 (measured, not assumed): the fix was never
+ * "run on 151" — it was `generatedContentCss()` OUT-SPECIFYING the author's
+ * selector, which wins the cascade whether the author's declaration is
+ * dropped (pre-151 regime) or retained (151+ regime). That was already
+ * verified by a RENDER PROBE (below) that reads back
+ * `getComputedStyle(el, '::after').content` instead of trusting
+ * `CSS.supports` — i.e. the thing that actually defends against this class of
+ * silent-content-loss regression is the probe, not the milestone pin. Measured
+ * 148 vs 151 head-to-head: the spike suite differs in exactly 2 checks (both
+ * assertions ABOUT Chromium's parse-vs-drop behaviour, now written to accept
+ * either regime — see spike/native-engine s0/s2), the parity gate output is
+ * byte-identical, and real 34pp/53pp book builds produce identical page counts
+ * and sizes on both milestones. So 151 was a *floor for the incident's
+ * discovery*, not a requirement of the fix. It is pinned rather than probed —
+ * running on anything below 148 is still an error rather than a guess — but
+ * 148 is the honestly-supported floor because it's also what Electron's
+ * bundled Chromium ships (42.1.0 → 148.0.7778.97 as of 2026-08-08), and the
+ * desktop app needs to drive its own Chromium for native-engine PDF export
+ * (see packages/desktop/electron's engine-browser module). Raising or
+ * lowering this floor again means re-running `bun run spikes` and treating
+ * every changed measurement as a finding, same as before.
+ */
+export declare const REQUIRED_MILESTONE = 148;
+/**
+ * Refuse to paginate on a browser below the floor. The invariant belongs to
+ * the `Browser` CONTRACT, not to any one way of obtaining a browser — the
+ * launch/connect paths and the host-injected path (an Electron
+ * `EngineBrowser`, `lib/engine.ts`) must enforce the identical rule with the
+ * identical message, or the two drift (they already had once).
+ */
+export declare function assertMilestone(product: string, origin: string, hint?: string): void;
+/**
+ * The document-settled probe both hosts run before measuring or printing:
+ * fonts ready, any pending `gp:ready` handshake, then two rAFs so layout
+ * settles after the font swap. ONE definition — the Electron host
+ * (packages/desktop/electron/engine-browser.ts) evaluates the same
+ * expression, and a drift between hosts would be an invisible divergence in
+ * when "ready" means ready.
+ */
+export declare function readyProbeExpr(timeoutMs: number): string;
+/**
+ * The print-quality contract both hosts pass to their print call: tagged PDF
+ * + document outline (named destinations — Tier 3 and the parity gate read
+ * them back) + CSS page size + backgrounds. ONE object, spread by both
+ * `SessionImpl.printToPDF` and the Electron host's `printToPDF`.
+ */
+export declare const DEFAULT_PRINT_OPTS: {
+    readonly printBackground: true;
+    readonly preferCSSPageSize: true;
+    readonly generateTaggedPDF: true;
+    readonly generateDocumentOutline: true;
+};
+export interface Browser {
+    wsUrl: string;
+    version: string;
+    milestone: number;
+    newPage(): Promise<Session>;
+    close(): Promise<void>;
+}
+/** One CDP connection multiplexed over sessionIds (flat mode). */
+export interface Session {
+    send<T = any>(method: string, params?: object): Promise<T>;
+    on(event: string, fn: (params: any) => void): () => void;
+    /** Convenience: Runtime.evaluate with awaitPromise + value return. */
+    evaluate<T = any>(expression: string): Promise<T>;
+    setContent(html: string, baseUrl?: string): Promise<void>;
+    navigate(url: string): Promise<void>;
+    /** Wait for fonts + optional `gp:ready`, per §6 of the proposal. */
+    waitForReady(timeoutMs?: number): Promise<void>;
+    printToPDF(opts?: Record<string, unknown>): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+export declare function launchChromium(opts?: {
+    headless?: boolean;
+    args?: string[];
+}): Promise<Browser>;
+/**
+ * Attach to an ALREADY-RUNNING Chromium (a pooled/pre-warmed browser owned by
+ * the caller, e.g. `browser-pool.ts`'s puppeteer instance via
+ * `browser.wsEndpoint()`) instead of spawning a new process.
+ *
+ * Deliberately the mirror image of `launchChromium`: same version pin, same
+ * `Session`/`newPage` machinery (`checkMilestoneAndWrap`, shared below), but
+ * `close()` only drops OUR websocket connection — it never sends
+ * `Browser.close`, kills a process, or removes a profile dir, because this
+ * function didn't create any of those. Ownership of the underlying browser's
+ * lifecycle stays entirely with whoever handed us `wsUrl`.
+ */
+export declare function connectChromium(wsUrl: string): Promise<Browser>;

package/dist/engine/shared/content-value.d.ts

@@ -0,0 +1,64 @@
+export type ContentPart = {
+    type: "literal";
+    value: string;
+} | {
+    type: "counter";
+    name: string;
+    style: string;
+} | {
+    type: "string";
+    name: string;
+    which: string;
+} | {
+    type: "target-counter";
+    url: string;
+    counter: string;
+    style: string;
+} | {
+    type: "target-text";
+    url: string;
+    which: string;
+} | {
+    type: "leader";
+    glue: string;
+} | {
+    type: "attr";
+    name: string;
+    as?: string;
+} | {
+    type: "content";
+    which: string;
+} | {
+    type: "keyword";
+    value: string;
+};
+export interface EvalContext {
+    /** 1-based page number of the page being rendered */
+    page?: number;
+    /** total page count */
+    pages?: number;
+    /** named string lookup, GCPM `string(name, which)` */
+    strings?: (name: string, which: string) => string | undefined;
+    /** `target-counter(url, page)` -> 1-based page of the target */
+    targetPage?: (url: string) => number | undefined;
+    /** `target-text(url)` -> text of the target */
+    targetText?: (url: string, which: string) => string | undefined;
+    /** the element the declaration hangs off (for attr()/content()) */
+    attr?: (name: string) => string | undefined;
+    /**
+     * leader() support: return placeholder text for a leader with this glue
+     * string (the renderers insert a marker here and later replace it with a
+     * measured run of glue). Absent = leaders render as nothing.
+     */
+    leader?: (glue: string) => string;
+    text?: string;
+}
+export declare function parseContent(value: string): ContentPart[];
+export declare function unquote(s: string): string;
+/** `attr(href url)` inside target-counter() -> the element's href. */
+export declare function resolveUrlArg(arg: string, ctx: EvalContext): string;
+export declare function formatCounter(n: number, style?: string): string;
+export declare function evaluateContent(parts: ContentPart[], ctx: EvalContext): string;
+export declare function evaluate(value: string, ctx: EvalContext): string;
+/** Does this content value need Tier 3 (measurement)? */
+export declare function needsMeasurement(value: string): boolean;

package/dist/engine/shared/gcpm-extract.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `gcpm-extract` (§9) — the ONLY piece of Gutterpress that reads CSS, and it never
+ * rewrites the author's files.
+ *
+ * Scope is deliberately narrow: `@page` blocks (incl. margin at-rules and the
+ * `bleed`/`marks` descriptors CSSOM drops) plus the four GCPM constructs
+ * Chromium doesn't implement — `string-set`, `string()`, `target-counter()` /
+ * `target-text()`, and `leader()`. It is NOT a general CSS parser; if general
+ * parsing ever feels necessary, the design has drifted (§1).
+ */
+export interface Declarations {
+    [prop: string]: string;
+}
+export interface PageRule {
+    /** named page, e.g. `@page chapter:first` -> "chapter" */
+    name?: string;
+    /** pseudo-pages in source order, e.g. ["first"] or ["left"] */
+    pseudos: string[];
+    decls: Declarations;
+    /** "@top-center" -> { content: '...' } */
+    marginBoxes: Record<string, Declarations>;
+    raw: string;
+}
+export interface StringSetDecl {
+    selector: string;
+    /** string name, e.g. "chapter-title" */
+    name: string;
+    /** raw value expression, e.g. "content()" or '"§ " content(text)' */
+    value: string;
+}
+export interface PageAssignment {
+    selector: string;
+    page: string;
+}
+export interface BreakDecl {
+    selector: string;
+    prop: "break-before" | "break-after" | "break-inside";
+    value: string;
+}
+export interface XrefDecl {
+    /** selector the generated content hangs off, e.g. "a.xref::after" */
+    selector: string;
+    /** raw content value */
+    content: string;
+    fn: "target-counter" | "target-text" | "leader" | "string";
+}
+export interface CounterResetDecl {
+    /** selector the reset hangs off, e.g. ".page-chapter-start" */
+    selector: string;
+    /** the value `counter-reset: page N` sets */
+    start: number;
+}
+export interface Length {
+    value: number;
+    unit: string;
+}
+export interface PageGeometry {
+    /** trim size in pt */
+    width: number;
+    height: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    bleed: number;
+    marks: string[];
+}
+export interface GcpmModel {
+    pageRules: PageRule[];
+    stringSets: StringSetDecl[];
+    pageAssignments: PageAssignment[];
+    breaks: BreakDecl[];
+    xrefs: XrefDecl[];
+    /** `counter-reset: page N` declarations — native print ignores this restart (ENGINE.md §8) */
+    counterResets: CounterResetDecl[];
+    /** page names referenced by either `@page name` or a `page:` assignment */
+    pageNames: string[];
+    warnings: string[];
+}
+export declare const MARGIN_BOX_NAMES: readonly ["top-left-corner", "top-left", "top-center", "top-right", "top-right-corner", "bottom-left-corner", "bottom-left", "bottom-center", "bottom-right", "bottom-right-corner", "left-top", "left-middle", "left-bottom", "right-top", "right-middle", "right-bottom"];
+/** Parse a declaration list (no nested blocks) into a map; last wins. */
+export declare function parseDeclarations(body: string): Declarations;
+/**
+ * The raw bodies of `@media print` blocks. The viewer re-injects these as
+ * screen styles: the preview must render the print stylesheet, and the browser
+ * won't apply print-media rules on screen (verified: `break-before` computes to
+ * `auto` until print emulation is on, which a plain document can't switch on).
+ */
+export declare function mediaPrintBodies(css: string): string[];
+export declare function extract(css: string): GcpmModel;
+export declare function splitTopLevel(s: string, sep: string): string[];
+export declare function toPt(value: string): number | undefined;
+/** Named page sizes (CSS Paged Media §5.1), portrait, in pt. */
+export declare const PAGE_SIZES: Record<string, [number, number]>;
+export declare function parseSize(value: string): {
+    width: number;
+    height: number;
+} | undefined;
+export declare function parseMargin(value: string): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/**
+ * Resolve the cascade of `@page` rules that apply to a given page context.
+ * Later rules win; specificity follows the spec's simplified order
+ * (unnamed < named, no-pseudo < pseudo).
+ */
+export declare function resolvePage(model: GcpmModel, ctx?: {
+    name?: string;
+    pseudos?: string[];
+}): {
+    decls: Declarations;
+    marginBoxes: Record<string, Declarations>;
+    geometry: PageGeometry;
+};

package/dist/engine/shared/margin-box-support.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Declarations Chromium accepts syntactically in `@page` margin boxes but
+ * silently drops in native print. These were measured with deliberately
+ * visible values (`rotate(-12deg)`, `6px 6px 0 #c00`) and are documented in
+ * docs/engine-history/ENGINE.md §8.
+ *
+ * Keep the viewer and print-safety linter on this one contract: preview must
+ * omit the same effects native PDF omits, while every other declaration is
+ * handed to Chromium normally instead of guessing at a narrower allowlist.
+ */
+export declare const MARGIN_BOX_IGNORED_PROPERTIES: ReadonlySet<string>;
+export declare function isIgnoredMarginBoxProperty(property: string): boolean;

package/dist/engine/shared/pdf-inspect.d.ts

@@ -0,0 +1,24 @@
+export declare const PT_PER_IN = 72;
+export interface PageBoxes {
+    media: number[];
+    crop?: number[];
+    bleed?: number[];
+    trim?: number[];
+}
+export interface PdfFacts {
+    pageCount: number;
+    boxes: PageBoxes[];
+    /** destination anchor name -> zero-based page index (from link annotations) */
+    linkTargets: Record<string, number>;
+    /** named destinations (/Dests name tree) -> zero-based page index */
+    namedDests: Record<string, number>;
+    /** outline title -> zero-based page index */
+    outline: Array<{
+        title: string;
+        page: number;
+    }>;
+}
+export declare function inspectPdf(bytes: Uint8Array): Promise<PdfFacts>;
+/** Extract per-page text as a rough sanity channel (not used for measurement). */
+export declare function ptToIn(pt: number): number;
+export declare function boxesEqual(a: number[] | undefined, b: number[], tol?: number): boolean;