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

package/dist/{index-wchtvxvw.js → index-v5mp7a6q.js}

@@ -29,6 +29,19 @@ async function gitEntryKind(dir) {
     return "none";
   }
 }
+async function looksLikeRepo(dir) {
+  const kind = await gitEntryKind(dir);
+  if (kind === "none")
+    return false;
+  if (kind === "file")
+    return true;
+  try {
+    await stat(path.join(dir, ".git", "HEAD"));
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function findEnclosingRepoDir(folderPath) {
   const home = path.resolve(os.homedir());
   let dir = path.resolve(folderPath);
@@ -39,7 +52,7 @@ async function findEnclosingRepoDir(folderPath) {
     dir = parent;
     if (dir === home)
       return;
-    if (await gitEntryKind(dir) !== "none")
+    if (await looksLikeRepo(dir))
       return dir;
   }
   return;

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export type { PlatformAdapter, FileStat, FileWriteResult } from "./platform.ts";
 export { inspectImage } from "./lib/image-inspect.ts";
 export type { ImageInfo, ColorSpace } from "./lib/image-inspect.ts";
 export { checkCss } from "./lib/printsafe.ts";
+export { BUILD_DIAGNOSTIC_CODES } from "./engine/compiler/build.ts";
+export type { BuildDiagnostic, BuildDiagnosticCode } from "./engine/compiler/build.ts";
 export type { PrintSafeWarning } from "./lib/printsafe.ts";
-export { ruleRemoteUrls, ruleRiskyProps, rulePagedjsCrashSelectors, ruleSyntax, } from "./lib/printsafe.ts";
+export { ruleRemoteUrls, ruleRiskyProps, ruleSyntax, } from "./lib/printsafe.ts";
 export type { GutterpressPlugin, GutterpressPluginExport, GutterpressPluginMetadata, } from "./lib/markdown/plugins.ts";

package/dist/index.js

@@ -8,7 +8,6 @@ import {
   AUTO_SYNC_MIN_MINUTES,
   BUILT_IN_TEMPLATE_IDS,
   BUILT_IN_THEME_IDS,
-  BuildError,
   FileTokenStore,
   GITHUB_HOST,
   GenericTokenAuthProvider,
@@ -21,6 +20,7 @@ import {
   RECOMMENDED_PLUGINS,
   RepoNeedsRecoveryError,
   SNIPPETS_DIR,
+  STALE_LOCK_MIN_AGE_MS,
   SYNC_SNAPSHOT_MESSAGE,
   TARGETS,
   TARGET_IDS,
@@ -33,11 +33,9 @@ import {
   autoSnapshotDelayMs,
   autoSyncDelayMs,
   buildPreflightDiagnostics,
-  buildRecoveryContext,
   checkCss,
   checkToolAvailability,
   classifyFromHealth,
-  classifyGitError,
   cloneRepository,
   connectGenericHost,
   connectPublishProvider,
@@ -66,9 +64,11 @@ import {
   inspectRepo,
   isAppHeartbeatFresh,
   isGitInternalPath,
+  isLikelyRepoCorruption,
   isRepoNeedsRecoveryError,
   isSshRemoteUrl,
   isUnbornRepo,
+  keepImageVersion,
   knownForgeTokenUrl,
   listBuiltInTemplates,
   listBuiltInThemes,
@@ -87,7 +87,6 @@ import {
   log,
   migrateUrlCredential,
   normalizeForgeHost,
-  onlineCopyPath,
   openPath,
   parseRemoteOrigin,
   preflightStructuralReason,
@@ -99,25 +98,24 @@ import {
   pullChanges,
   pushChanges,
   readAppHeartbeat,
+  readImageVersion,
   readManifestFields,
   readProjectProvenance,
   readPublishSettings,
   readSnippet,
   readThemeCss,
-  recover,
   redactCredential,
   removeAppHeartbeat,
   removeProjectTheme,
+  repairRepo,
   reportMissingTools,
   resolveActiveStyles,
   resolveBuiltInTheme,
   resolveCheckSelectors,
   resolveConfig,
-  resolveConflicts,
   resolveGitHubClientId,
   resolvePublishRequest,
   revertTheme,
-  rulePagedjsCrashSelectors,
   ruleRemoteUrls,
   ruleRiskyProps,
   ruleSyntax,
@@ -142,7 +140,15 @@ import {
   validateProjectPlugins,
   verifyRepoReadable,
   writeAppHeartbeat
-} from "./index-bynn850m.js";
+} from "./index-s416qpdv.js";
+import {
+  BUILD_DIAGNOSTIC_CODES
+} from "./index-a4kr77td.js";
+import {
+  BuildError,
+  DEFAULT_PRINT_OPTS,
+  readyProbeExpr
+} from "./index-mvehxh0e.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,
@@ -152,15 +158,14 @@ import {
   resolveLogger,
   restoreVersionWithBackup,
   shortOid
-} from "./index-yzrh708h.js";
+} from "./index-mdefp0y5.js";
 import {
   capabilitiesFor,
   detectProjectSource,
   findEnclosingRepoDir,
   repoRootForSource,
   repoSubPath
-} from "./index-wchtvxvw.js";
-import"./index-yja077f6.js";
+} from "./index-v5mp7a6q.js";
 import"./index-37x76zdn.js";
 export {
   writeAppHeartbeat,
@@ -188,13 +193,11 @@ export {
   ruleSyntax,
   ruleRiskyProps,
   ruleRemoteUrls,
-  rulePagedjsCrashSelectors,
   revertTheme,
   restoreVersionWithBackup,
   resolvePublishRequest,
   resolveLogger,
   resolveGitHubClientId,
-  resolveConflicts,
   resolveConfig,
   resolveCheckSelectors,
   resolveBuiltInTheme,
@@ -202,15 +205,17 @@ export {
   reportMissingTools,
   repoSubPath,
   repoRootForSource,
+  repairRepo,
   removeProjectTheme,
   removeAppHeartbeat,
   redactCredential,
-  recover,
+  readyProbeExpr,
   readThemeCss,
   readSnippet,
   readPublishSettings,
   readProjectProvenance,
   readManifestFields,
+  readImageVersion,
   readAppHeartbeat,
   pushChanges,
   pullChanges,
@@ -223,7 +228,6 @@ export {
   preflightStructuralReason,
   parseRemoteOrigin,
   openPath,
-  onlineCopyPath,
   normalizeForgeHost,
   migrateUrlCredential,
   log,
@@ -242,10 +246,12 @@ export {
   listBuiltInThemes,
   listBuiltInTemplates,
   knownForgeTokenUrl,
+  keepImageVersion,
   isUnbornRepo,
   isSshRemoteUrl,
   isRepoNeedsRecoveryError,
   isNoChangesError,
+  isLikelyRepoCorruption,
   isGitInternalPath,
   isAppHeartbeatFresh,
   inspectRepo,
@@ -276,12 +282,10 @@ export {
   connectPublishProvider,
   connectGenericHost,
   cloneRepository,
-  classifyGitError,
   classifyFromHealth,
   checkToolAvailability,
   checkCss,
   capabilitiesFor,
-  buildRecoveryContext,
   buildPreflightDiagnostics,
   autoSyncDelayMs,
   autoSnapshotDelayMs,
@@ -294,6 +298,7 @@ export {
   TARGET_IDS,
   TARGETS,
   SYNC_SNAPSHOT_MESSAGE,
+  STALE_LOCK_MIN_AGE_MS,
   SNIPPETS_DIR,
   RepoNeedsRecoveryError,
   RESTORE_BACKUP_MESSAGE,
@@ -308,9 +313,11 @@ export {
   GenericTokenAuthProvider,
   GITHUB_HOST,
   FileTokenStore,
+  DEFAULT_PRINT_OPTS,
   BuildError,
   BUILT_IN_THEME_IDS,
   BUILT_IN_TEMPLATE_IDS,
+  BUILD_DIAGNOSTIC_CODES,
   AUTO_SYNC_MIN_MINUTES,
   AUTO_SYNC_MAX_MINUTES,
   AUTO_SYNC_DEFAULT_MINUTES,

package/dist/lib/asset-inline.d.ts

@@ -31,6 +31,17 @@ export interface InlineStylesResult {
     /** Non-fatal notices (e.g. a remote `url()` left untouched). */
     warnings: string[];
 }
+/**
+ * A rendered destination that must not be resolved against the book's
+ * filesystem. Shared by validation and asset planning so schemes cannot be
+ * ignored by one path but staged as bogus files by the other.
+ *
+ * `file:` is deliberately excluded: author-supplied file URLs must reach the
+ * relative/containment policy and fail loudly, never bypass it as a remote
+ * resource. Empty, fragment-only, and query-only references fetch no distinct
+ * book asset and are ignored.
+ */
+export declare function isNonFilesystemRef(url: string): boolean;
 /**
  * Decode percent-escapes so `my%20photo.png` resolves to `my photo.png`.
  * Falls back to the raw string for a literal `%` in a filename.
@@ -89,4 +100,29 @@ export declare function collectStyleDependencies(projectDir: string, stylePaths:
 export declare function planImageCopies(projectDir: string, refs: Iterable<string>): Promise<{
     copies: AssetCopy[];
     errors: string[];
+    destinations: Map<string, string>;
 }>;
+/**
+ * Inline every `--gp-shape:url("…")` style-attribute value in rendered book
+ * HTML as a data: URI, reading the referenced file relative to `baseDir`
+ * (the staged book directory, where `planImageCopies` already landed it).
+ *
+ * Why this exists: `shape-outside` READS PIXELS, so unlike `<img>` rendering
+ * it requires CORS-clean image data. The print path loads the staged
+ * `book.html` via `file://`, where every file is an opaque origin — a
+ * file-path shape silently degrades to the margin box (MEASURED, Chromium
+ * 141: identical fixture wraps over http:// and does nothing over file://),
+ * while the http-served preview shows the shape. That is a
+ * preview-vs-print divergence, the exact failure class the parity gate
+ * exists to prevent — and it depends on browser launch flags we do not
+ * control on every host (Electron's export window enforces web security).
+ * A data: URI is same-origin everywhere, so staging — which already inlines
+ * fonts as data: URIs — makes the print input origin-independent.
+ *
+ * The value matched is exactly what `images.ts` emits after markdown-it's
+ * attribute escaping: `--gp-shape:url(&quot;<src>&quot;)`. Remote and data:
+ * URLs, files that escape `baseDir`, and unreadable files are left
+ * untouched — the shape then falls back to the margin box, the same
+ * behavior as an image that fails to load.
+ */
+export declare function inlineShapeUrls(html: string, baseDir: string): Promise<string>;

package/dist/lib/browser-pool.d.ts

@@ -1,4 +1,7 @@
 import type { Browser } from "puppeteer-core";
+/** Hard ceiling for navigation + rendering. Large books need this budget; it
+ *  is also the puppeteer protocolTimeout for the pooled browser. */
+export declare const RENDER_TIMEOUT_MS: number;
 /**
  * Start the Chromium launch in the background without awaiting it, so the cold
  * start overlaps with other build work. Safe to call repeatedly; only the first
@@ -10,6 +13,21 @@ export declare function prewarmBrowser(timeoutMs: number): void;
  * across renders in the same process.
  */
 export declare function getBrowser(timeoutMs: number): Promise<Browser>;
+/**
+ * Get the shared browser and open a fresh page on it, tolerating a browser
+ * that died between the last health check and this call (e.g. a CI runner
+ * that OOM-kills Chromium under memory pressure, or the pooled instance's own
+ * devtools connection dropping): `browser.newPage()` on a disconnected
+ * browser rejects with a websocket/"Connection ended"-shaped error rather
+ * than triggering the `disconnected` listener in time to save this caller.
+ * One retry after dropping the stale pool entry converts that into a clean
+ * relaunch instead of a hard failure — the same shape of resilience
+ * `getBrowser`/`prewarmBrowser` already give a launch that fails outright.
+ */
+export declare function getBrowserPage(timeoutMs: number): Promise<{
+    browser: Browser;
+    page: Awaited<ReturnType<Browser["newPage"]>>;
+}>;
 /**
  * Close the shared browser. A one-shot CLI build calls this when done so the
  * process can exit; a preview/watch server calls it on shutdown.

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

@@ -37,7 +37,7 @@ export declare const EXIT_CODES: {
  * Deliberately dependency-free and in its own module: consumers that only need
  * the error type (e.g. `utils/file-utils.ts`, used by the preview server) must
  * NOT drag in `build-runner.ts`'s whole pipeline graph (markdown rendering,
- * ghostscript, paged.js, the browser pool) just to reference an Error class.
+ * Ghostscript, native pagination, the browser pool) just to reference an Error class.
  * `build-runner.ts` re-exports this so existing `import { BuildError } from
  * "./build-runner"` call sites keep working.
  *

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

@@ -1,5 +1,4 @@
 import type { BuildFormat } from "./build-runner";
-import type { PdfRenderer } from "./pagination";
 /**
  * Probe for every tool this build will actually spawn, BEFORE the pipeline
  * starts running for real. Fails fast with one error that lists every
@@ -16,14 +15,48 @@ import type { PdfRenderer } from "./pagination";
  * stampCreator) and needs no system tool at all.
  * qpdf is REQUIRED for pdfx + stripAnnotations (default true).
  */
+/**
+ * Does this build render in the POOLED/external Chromium? The one rule,
+ * defined once: HTML builds never paginate here; an injected `engineBrowser`
+ * (the desktop's Electron host) replaces the pool. Every caller that gates
+ * preflight, prewarm, or the milestone check derives from THIS predicate.
+ */
+export declare function rendersInPooledChromium(format: BuildFormat, opts: {
+    engineBrowser?: unknown;
+}): boolean;
 export declare function preflightBuildTools(format: BuildFormat, opts: {
     stripAnnotations?: boolean;
-    pdfRenderer?: PdfRenderer;
+    engineBrowser?: unknown;
 }, config: {
     pdfx: {
         stripAnnotations: boolean;
     };
 }): Promise<void>;
+/**
+ * Native engine only: verify the browser-pool's Chromium meets
+ * `engine/shared/cdp.ts`'s `REQUIRED_MILESTONE`, with an early, actionable
+ * error instead of the late, cryptic one `connectChromium` throws from deep
+ * inside `buildNativePdf` (reached only after quality gates + the markdown
+ * render have already run). `preflightBuildTools`'s presence check
+ * (`resolveChromiumExecutable`) doesn't catch a resolved-but-too-old binary —
+ * this does.
+ *
+ * Deliberately NOT called from `preflightBuildTools` itself: that would
+ * force `runBuild` to await a full Chromium cold start (~1-2s) BEFORE
+ * lint/validate even start, defeating the whole point of `prewarmBrowser()`
+ * firing in parallel with them. Call this instead right after quality gates
+ * finish and before rendering — by then the prewarmed browser is usually
+ * already warm, and any quality-gate failure (the common case) never pays
+ * this cost at all. Reuses `getBrowser()` (the same cached instance
+ * `buildNativePdf`'s `connectChromium` will reuse), so this is one cold
+ * start, not two.
+ *
+ * Not reached by the desktop: it injects its own `engineBrowser` (Electron's
+ * bundled Chromium, 148 as of Electron 42.1.0 = `REQUIRED_MILESTONE`), which
+ * `runBuild` skips this check for and `buildNativePdf` milestone-checks
+ * directly instead. This is the pooled/external-Chromium path only.
+ */
+export declare function verifyNativeChromiumMilestone(): Promise<void>;
 export interface Gates {
     lint: boolean;
     preValidate: boolean;

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

@@ -1,8 +1,11 @@
 import { resolveConfig } from "./manifest";
+import { RENDER_TIMEOUT_MS } from "./browser-pool";
 import { BuildError } from "./build-error";
+import type { BuildDiagnostic } from "../engine/compiler/build.ts";
+import type { Browser as EngineBrowser, Session as EngineSession } from "../engine/shared/cdp.ts";
 import { type Gates } from "./build-preflight";
-import { type PdfRenderer, type PdfRenderInput } from "./pagination";
-export type { PdfRenderer, PdfRenderInput };
+export { RENDER_TIMEOUT_MS };
+export type { EngineBrowser, EngineSession };
 export type BuildFormat = "html" | "pdf" | "pdfx";
 export type PdfxFlavor = "x1a" | "x3";
 export { BuildError };
@@ -19,12 +22,6 @@ export interface BuildRunnerOptions {
     skipLint?: boolean;
     skipPreValidate?: boolean;
     skipPostValidate?: boolean;
-    /**
-     * Optional PDF renderer override. When provided, the build uses it instead of
-     * launching Chromium via puppeteer, and the Chromium preflight is skipped.
-     * The Electron desktop injects one backed by `webContents.printToPDF`.
-     */
-    pdfRenderer?: PdfRenderer;
     /**
      * Keep the pooled headless browser alive after the build returns. A one-shot
      * CLI build leaves this false so the process can exit; a long-lived
@@ -34,6 +31,24 @@ export interface BuildRunnerOptions {
      */
     keepBrowserAlive?: boolean;
     rawArgs: Record<string, unknown>;
+    /**
+     * CLI `--engine` override. Paged.js has been removed — the native engine is
+     * the only engine — so this is a deprecated no-op accepted for backward
+     * compatibility only: `"paged"` triggers a one-line warning
+     * (`manifest.ts`'s resolution) and the build proceeds natively regardless.
+     */
+    engine?: "paged" | "native";
+    /**
+     * Optional injected engine-Chromium factory for native builds
+     * (`engine.ts`'s `buildNativePdf`). When omitted (the CLI's default), the
+     * native engine attaches to `browser-pool.ts`'s pooled external Chromium,
+     * and the usual Chromium preflight / milestone check apply. When supplied
+     * (the desktop, over its own Electron `BrowserWindow` — see
+     * `packages/desktop/electron`'s engine-browser module), it is used
+     * instead, no external Chromium is required, and both of those checks are
+     * skipped.
+     */
+    engineBrowser?: () => Promise<EngineBrowser>;
 }
 export interface BuildRunnerResult {
     outDir: string;
@@ -47,6 +62,12 @@ export interface BuildRunnerResult {
     pdfPath: string | null;
     /** As {@link htmlPath}: `null` when nothing but the artifact was published. */
     fingerprintPath: string | null;
+    /**
+     * Author-facing print-quality findings from the render (native engine only
+     * — Paged.js has no equivalent audit). Empty for a clean build. The desktop
+     * maps these into the Problems panel; the CLI logs them.
+     */
+    diagnostics: BuildDiagnostic[];
 }
 export interface SplitOutPath {
     outDir?: string;
@@ -131,6 +152,13 @@ export interface BuildContext {
     workDir: string;
     /** What to do with `workDir` once the build succeeds. */
     target: PublishTarget;
+    /**
+     * Exact layout-marker findings already printed by pre-build validation.
+     * Render-time parsing consults this set so only true duplicates disappear;
+     * a disabled/failed/skipped marker check never suppresses a legitimate
+     * warning from the final render path.
+     */
+    prevalidatedLayoutWarningKeys: Set<string>;
 }
 /**
  * Stage 1 — load the manifest, merge CLI overrides into the resolved config,
@@ -145,7 +173,7 @@ export declare function resolveBuildContext(opts: BuildRunnerOptions): Promise<B
  * 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: markdown-it-paged computes typed, line-numbered
+ * 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
@@ -164,18 +192,18 @@ export declare function renderBook(ctx: BuildContext): Promise<string>;
 export declare function resolveIccProfile(icc: string, manifestDir: string, explicitIccPath: string | undefined): Promise<string>;
 /**
  * Orchestrate a build: resolve the context, mkdir the output, preflight tools
- * (non-html), pre-warm the browser when this build will paginate in Chromium,
+ * (non-html), pre-warm the browser when this build will render in Chromium,
  * run the quality gates, render the book, then hand off to the per-format output
- * strategy for pagination + finalize. The heavy lifting lives in the named
- * stages + strategies above (plus ./build-preflight, ./build-staging, and
- * ./pagination); this reads as the pipeline it is.
+ * strategy for rendering + finalize. The heavy lifting lives in the named
+ * stages + strategies above (plus ./build-preflight and ./build-staging);
+ * this reads as the pipeline it is.
  *
  * Everything from the prewarm decision onward runs inside a try/finally that
  * closes the pooled browser (unless `keepBrowserAlive` is set) — finding #50:
  * previously the close only happened on the success tail (inside
- * `finalizeBuild`), so a prewarmed Chromium leaked whenever a quality gate,
- * the render, or pagination itself threw. `closeBrowser()` is a no-op if
- * nothing was launched (including the injected-renderer path, which never
- * uses the pool), so it is safe to call unconditionally here.
+ * `finalizeBuild`), so a prewarmed Chromium leaked whenever a quality gate or
+ * the render itself threw. `closeBrowser()` is a no-op if nothing was
+ * launched (including the injected-`engineBrowser` path, which never uses
+ * the pool), so it is safe to call unconditionally here.
  */
 export declare function runBuild(opts: BuildRunnerOptions): Promise<BuildRunnerResult>;

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

@@ -1,61 +1,15 @@
 /**
- * HTML string-rewriting for the shippable artifact: turns the raw
- * serialized-paginated DOM that pagination produces into the static desktop HTML
- * (or the runtime-pagination fallback). Pure string/fs transforms — no browser.
- *
- * The former `stagePaginationInput` is GONE. It copied `book.html` plus every
- * asset directory into a temp dir purely so relative URLs would resolve against
- * some root, which cost a second full copy of every asset per build and made the
- * staged tree a second place assets could go missing. `book.html` is now
- * self-contained (CSS and fonts inlined by `lib/asset-inline.ts`), so the
- * pagination pass serves `outDir` directly with in-memory overlays for the
- * engine — see `createStaticFileServer`'s `overlays` in `./pagination.ts`.
+ * `--format html`: ship the self-contained `book.html` (already fully
+ * inlined — see `lib/asset-inline.ts`) alongside a copy of the native engine's
+ * viewer bundle, with one `<script src="engine/gutterpress-viewer.js">`
+ * injected before `</head>`. The viewer paginates the document in the
+ * browser on load — no headless Chromium at build time, no DOM
+ * serialization (see the "Not snapshotting the viewer's fragmented DOM" note
+ * in the migration plan).
  */
+export declare function shipViewerHtml(htmlFile: string, outDir: string): Promise<void>;
 /**
- * Remove the Paged.js pagination ENGINE from an already-paginated, serialized
- * document so the browser renders the static pages as-is and never re-paginates.
- * Strips (a) the polyfill `<script src>` and (b) the inline break-inside handler.
- * Navigation toolbar scripts are NOT touched — they only scroll between pages
- * that already exist, which is not DOM-pagination.
- */
-export declare function stripPaginationRuntime(html: string): string;
-/**
- * Rewrite the build's ephemeral pagination origin back to document-relative
- * URLs.
- *
- * Paged.js absolutizes every non-`data:` CSS `url()` against the sheet's origin
- * (`replaceUrls`, paged.polyfill.js), so the serialized document comes back
- * pointing at `http://127.0.0.1:<port>/…` — a port that dies with the build.
- * Left alone, a shipped `book.html` references a dead origin for every
- * content-addressed image.
- *
- * The leading slash is stripped along with the origin ON PURPOSE: `book.html`
- * sits at the artifact root, so `assets/x.png` is correct and `/assets/x.png`
- * would break any deployment under a subpath (GitHub Pages project sites).
- */
-export declare function stripPaginationOrigin(html: string): string;
-/**
- * Inject the navigation-only toolbar scripts (page nav, zoom, view modes) into
- * the static document head. These read the pre-rendered `.pagedjs_page`
- * elements; they do not paginate.
- */
-export declare function injectNavigationScripts(html: string): string;
-/**
- * Turn a raw serialized paginated document into the shippable static desktop
- * `book.html`: copy the navigation toolbar scripts, strip the pagination engine
- * and the build's ephemeral origin, wire the nav scripts, and write the file.
- * Shared by the HTML format and the PDF unification path.
- */
-export declare function finalizeStaticBook(rawSerializedHtml: string, htmlFile: string, outDir: string): Promise<void>;
-/**
- * Fallback for `--format html` when no headless browser is available: ship the
- * Paged.js polyfill + nav scripts so the BROWSER paginates at load time (the
- * pre-SSG behavior). Slower at runtime and not pre-paginated, but it works with
- * no Chromium at build.
- */
-export declare function shipRuntimePaginatedHtml(htmlFile: string, outDir: string): Promise<void>;
-/**
- * Create a unique scratch directory under the OS temp dir. Now used ONLY for
+ * Create a unique scratch directory under the OS temp dir. Used only for
  * PDF/X intermediates (`raw.pdf`, Ghostscript work files) — never for staging
  * assets. Must not be resolved against `process.cwd()`: `runBuild` is exported
  * and called by the desktop host, so writing scratch dirs into the caller's

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

@@ -41,5 +41,13 @@ export declare function parseFormat(raw: unknown, opts: {
 }): BuildFormat;
 /** Parse `--pdfx-flavor`, which is only valid alongside `--format pdfx`. */
 export declare function parsePdfxFlavor(raw: unknown, format: BuildFormat): PdfxFlavor | undefined;
+/**
+ * Parse `--engine`, shared by `build` and `preview`. Paged.js has been
+ * removed — the native engine is the only engine — so this flag is now an
+ * accepted-but-ignored no-op: `--engine paged` produces a one-line warning
+ * (`manifest.ts`'s resolution) and the build proceeds natively regardless.
+ * `undefined` means "not passed".
+ */
+export declare function parseEngine(raw: unknown): "paged" | "native" | undefined;
 /** Parse `--port`, defaulting to {@link NETWORK.DEFAULT_PORT} (0 = OS-assigned). */
 export declare function resolvePort(raw: unknown): number;

package/dist/lib/desktop.d.ts

@@ -5,8 +5,8 @@
  * 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 Paged.js polyfill and the
- * pagedjs-interface/bridge scripts injected — no toolbar.
+ * now produces a "naked" book.html with Gutterpress's native live-viewer and
+ * preview-interface/bridge scripts injected — no toolbar.
  *
  * Power users who want a hosted UI launch the desktop app or write their
  * own iframe wrapper around book.html.

package/dist/lib/embedded-assets.d.ts

@@ -1,5 +1,5 @@
 /**
- * Embedded preview assets (favicon, manifest schema, paged.js polyfill,
+ * Embedded preview assets (favicon, manifest schema, native engine bundles,
  * iframe interface + cross-origin bridge).
  *
  * `with { type: "file" }` imports are the canonical embedding mechanism for

package/dist/lib/engine.d.ts

@@ -0,0 +1,33 @@
+import { type BuildDiagnostic } from "../engine/compiler/build.ts";
+import { type Browser as EngineBrowser } from "../engine/shared/cdp.ts";
+export type { EngineBrowser };
+/** The subset of `BuildOptions` that has a manifest/CLI source today (B.12). */
+export interface NativePdfOptions {
+    title?: string;
+    author?: string;
+    signature?: number;
+}
+/**
+ * Render `htmlFile` to `outPdf` via the Gutterpress engine. No HTTP staging,
+ * no Paged.js polyfill — but the pooled/pre-warmed Chromium IS reused (see
+ * module doc comment): this module never launches or closes a browser itself.
+ *
+ * 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.
+ *
+ * `getEngineBrowser` is an optional injected factory, mirroring the
+ * engine-browser injection seam in `build-runner.ts`: when omitted (the CLI's
+ * default), this module gets `browser-pool.ts`'s pooled
+ * puppeteer browser and attaches `cdp.ts`'s `connectChromium()` to it, same as
+ * always. When supplied (the desktop, over its own Electron `BrowserWindow` —
+ * see `packages/desktop/electron`'s engine-browser module), that browser is
+ * used directly instead — no pooled/external Chromium involved at all. Either
+ * way this function owns closing whatever browser it ends up with: the pooled
+ * path because `connectChromium`'s close only drops OUR websocket (never the
+ * pool), and the injected path because the desktop hands over a browser built
+ * fresh for exactly this one build (`newPage()` -> one window per build), so
+ * nothing else is going to close it.
+ */
+export declare function buildNativePdf(htmlFile: string, outPdf: string, options?: NativePdfOptions, getEngineBrowser?: () => Promise<EngineBrowser>): Promise<BuildDiagnostic[]>;