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

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

@@ -0,0 +1,155 @@
+/**
+ * Shared synthesis policy — the single implementation both renderers consume.
+ *
+ * The compiler and the viewer must produce the same book from the same CSS, so
+ * every rule that DECIDES something (where blank pages go, which string value a
+ * page shows) lives here as a pure function. The renderers differ only in how
+ * they measure (client rects vs the PDF's /Dests) and how they apply (DOM
+ * spacers vs DOM spacers via the agent) — never in policy. This is what keeps
+ * "every compiler-side synthesis needs a viewer-side twin" from rotting: there
+ * is no twin, there is one function.
+ */
+/** `break-before` values Chromium treats as a plain page break but shouldn't. */
+export declare const RECTO_VERSO_VALUES: RegExp;
+export declare function isRectoVersoBreak(decl: {
+    prop: string;
+    value: string;
+}): boolean;
+export declare function wantsRecto(value: string): boolean;
+export interface RectoSite {
+    /** 1-based page the element landed on in a clean (spacer-free) layout */
+    page: number;
+    /** true = must start on a right-hand page; false = left-hand */
+    wantsRecto: boolean;
+}
+/**
+ * Which sites need a blank page inserted before them.
+ *
+ * Pure and analytic: a blank page shifts every later page by exactly one and
+ * changes no content, so the whole set follows from one clean measurement —
+ * walk the sites in document order carrying the count of blanks inserted so
+ * far. (Toggling spacers one measure-pass at a time oscillates instead: the
+ * spacer fixes the parity, the next pass sees it fixed and removes it.)
+ *
+ * Page 1 is a recto; recto pages are odd.
+ */
+export declare function planRectoBlanks(sites: RectoSite[]): boolean[];
+export type StringWhich = "first" | "start" | "last" | "first-except";
+export interface StringEntry {
+    /** 1-based page the assignment lands on */
+    page: number;
+    value: string;
+}
+export declare function parseWhich(raw: string | undefined): StringWhich;
+/**
+ * The value `string(name, which)` shows on `page`, per CSS GCPM §2.4:
+ *
+ * - `first` — the value of the first assignment on the page; if none, the
+ *   entry value (what was in effect at the top of the page).
+ * - `start` — the entry value: the value in effect at the START of the page
+ *   (assignments on the page itself don't count).
+ * - `last` — the value of the last assignment on the page; if none, the entry
+ *   value.
+ * - `first-except` — empty on pages where an assignment happens (the chapter
+ *   opener), the entry value elsewhere. The classic "no running head on the
+ *   opener" behaviour.
+ *
+ * `entries` must be sorted by page; multiple entries on one page keep document
+ * order.
+ */
+export declare function stringValueAt(entries: StringEntry[], page: number, which?: StringWhich): string;
+/**
+ * One symbol per page for a `@counter-style { system: fixed }` map — the
+ * compiler's whole running-heads mechanism is `stringValueAt` sampled at every
+ * page (verified in s3).
+ */
+export declare function stringSymbols(entries: StringEntry[], pageCount: number, which?: StringWhich): string[];
+/** CSS-escape a string for use inside a double-quoted `symbols:` list. */
+export declare function cssQuote(s: string): string;
+/** Stable generated counter-style name for a (string name, which) pair. */
+export declare function counterStyleName(name: string, which: StringWhich): string;
+export interface PageCounterReset {
+    /** 1-based page (after recto/verso blank insertion) the reset takes effect on */
+    page: number;
+    /** the value `counter-reset: page N` sets */
+    start: number;
+}
+/**
+ * One numeric `counter(page)` value per page, honoring `counter-reset: page N`
+ * restarts the author declared in content flow.
+ *
+ * Native Chromium print ignores this restart entirely (ENGINE.md §8: the
+ * element sits on page 3, the margin box still reads 3) — front-matter (roman)
+ * → body (arabic from 1) is therefore not expressible in the author's content,
+ * so the compiler replays the restart as a fixed per-page value list, the same
+ * trick `stringSymbols` uses for `string()`. Formatting (`lower-roman` front
+ * matter vs decimal body) is a separate, per-`@page`-context concern the
+ * caller applies with `formatCounter` — this function only fixes the NUMBER,
+ * so one map serves every context regardless of which style each requests.
+ *
+ * Pure and analytic, like `planRectoBlanks`: one pass, no fixpoint. A blank
+ * page inserted before a restart site shifts `page` by exactly one, which is
+ * why `page` must be the FINAL (post-blank) page number — the caller resolves
+ * that the same way it resolves every other measured page (`ENGINE.md` §6).
+ *
+ * Multiple resets on the same page keep the LAST one in `resets` order,
+ * matching `counter-reset`'s own last-write-wins cascade. `resets` need not be
+ * pre-sorted.
+ */
+export declare function pageCounterValues(resets: PageCounterReset[], pageCount: number): number[];
+/**
+ * `resetSites` (id + declared start) -> `pageCounterValues`'s input shape,
+ * resolved against a measured id->page map. Both the compiler's folio-CSS
+ * synthesis (`counterStyleCss`) and its `target-counter()` resolution
+ * (`applySynthesis`) need this same resets->values step — one function, so
+ * a page's own folio and a cross-reference TO that page can never disagree
+ * (F2/F3). Returns `null` when the document declares no restart, so a
+ * caller can fall back to the raw physical page number.
+ */
+export declare function restartedPageValues(resetSites: Array<{
+    id: string;
+    start: number;
+}>, pageMap: Record<string, number>, pageCount: number): number[] | null;
+/**
+ * A 1-based PHYSICAL page number -> the folio it actually prints, honoring a
+ * `counter-reset: page N` restart (F3: `target-counter(attr(href), page)`
+ * must resolve to the SAME folio the target page's own margin box prints,
+ * not the raw physical page). `pageValues` is the array `pageCounterValues`
+ * (or `restartedPageValues`) produced; `null` means no restart is in play.
+ */
+export declare function toFolioPage(physicalPage: number, pageValues: number[] | null): number;
+/**
+ * Marker pair wrapping a pending leader inside generated content. Private-use
+ * codepoints so author text can never collide; the glue string sits between
+ * them. Both renderers replace the marker with a measured run of glue.
+ */
+export declare const LEADER_START = "\uE000";
+export declare const LEADER_END = "\uE001";
+export declare function leaderMarker(glue: string): string;
+export declare const LEADER_RE: RegExp;
+/**
+ * How many glue repetitions fill `gapPx`. One short of the exact quotient so
+ * the line can never overflow by a rounding error — measured on print output:
+ * numbers land 1–2 glue-widths from the content edge, nothing wraps.
+ */
+export declare function leaderFillCount(gapPx: number, gluePx: number): number;
+/**
+ * CSS that makes Gutterpress's computed text win over the author's own rule.
+ *
+ * Gutterpress resolves `target-counter()` / `target-text()` / `leader()` into a
+ * `data-gp-after|before` attribute and renders it with `content: attr(…)`.
+ *
+ * The pinned engine PARSES `target-counter()` (and `CSS.supports()` reports it
+ * as supported) but computes the whole `content` value to `none` — nothing
+ * renders. So the author's declaration SURVIVES the cascade, and
+ * `a.xref::after` (0,1,1) outranks a bare `[data-gp-after]::after` (0,1,0):
+ * a lower-specificity override loses to the author's empty value and the
+ * cross-reference silently disappears.
+ *
+ * The fix is to out-specify the author on their own terms: reuse their selector
+ * and add Gutterpress's attribute to it, so the override is strictly more specific
+ * than the rule it must beat, whatever that rule looks like. The bare rules are
+ * kept as a fallback for content Gutterpress generates on elements no author selector
+ * mentions.
+ */
+export declare function generatedContentCss(selectors: Iterable<string>): string;

package/dist/engine-eng4xh2q.js

@@ -0,0 +1,41 @@
+import {
+  RENDER_TIMEOUT_MS,
+  assertMilestone,
+  build,
+  connectChromium,
+  getBrowser
+} from "./cli-yp3p0sf2.js";
+import"./cli-c41yr7he.js";
+import {
+  BuildError
+} from "./cli-46ycxe6r.js";
+import"./cli-37x76zdn.js";
+
+// src/lib/engine.ts
+import { writeFile } from "node:fs/promises";
+async function buildNativePdf(htmlFile, outPdf, options = {}, getEngineBrowser) {
+  let result;
+  try {
+    const engineBrowser = getEngineBrowser ? await getEngineBrowser() : await connectChromium((await getBrowser(RENDER_TIMEOUT_MS)).wsEndpoint());
+    if (getEngineBrowser) {
+      try {
+        assertMilestone(engineBrowser.version, "(host-supplied browser)");
+      } catch (e) {
+        await engineBrowser.close();
+        throw e;
+      }
+    }
+    try {
+      result = await build({ input: htmlFile, browser: engineBrowser, ...options });
+    } finally {
+      await engineBrowser.close();
+    }
+  } catch (err) {
+    throw new BuildError(`--engine native failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  await writeFile(outPdf, result.bytes);
+  return result.diagnostics;
+}
+export {
+  buildNativePdf
+};

package/dist/engine-q5skhgms.js

@@ -0,0 +1,40 @@
+import {
+  build
+} from "./index-a4kr77td.js";
+import {
+  BuildError,
+  RENDER_TIMEOUT_MS,
+  assertMilestone,
+  connectChromium,
+  getBrowser
+} from "./index-mvehxh0e.js";
+import"./index-37x76zdn.js";
+
+// src/lib/engine.ts
+import { writeFile } from "node:fs/promises";
+async function buildNativePdf(htmlFile, outPdf, options = {}, getEngineBrowser) {
+  let result;
+  try {
+    const engineBrowser = getEngineBrowser ? await getEngineBrowser() : await connectChromium((await getBrowser(RENDER_TIMEOUT_MS)).wsEndpoint());
+    if (getEngineBrowser) {
+      try {
+        assertMilestone(engineBrowser.version, "(host-supplied browser)");
+      } catch (e) {
+        await engineBrowser.close();
+        throw e;
+      }
+    }
+    try {
+      result = await build({ input: htmlFile, browser: engineBrowser, ...options });
+    } finally {
+      await engineBrowser.close();
+    }
+  } catch (err) {
+    throw new BuildError(`--engine native failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  await writeFile(outPdf, result.bytes);
+  return result.diagnostics;
+}
+export {
+  buildNativePdf
+};