gutterpress 0.11.10-alpha.2 → 0.11.10-alpha.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +24 -46
  2. package/dist/api/index.d.ts +1 -1
  3. package/dist/api/index.js +10 -6
  4. package/dist/{build-dfpvvhys.js → build-npxq1tvm.js} +7 -6
  5. package/dist/cdp-jg95s674.js +15 -0
  6. package/dist/cdp-smdx6mr3.js +16 -0
  7. package/dist/{cli-d8rdk1y7.js → cli-30j93gzt.js} +11 -335
  8. package/dist/{cli-pfczdbyd.js → cli-5qr3z0qa.js} +10 -404
  9. package/dist/{cli-c41yr7he.js → cli-7fkhgtfn.js} +3 -1
  10. package/dist/{cli-k2hwrp7s.js → cli-97bdz5k0.js} +1 -4
  11. package/dist/cli-kkzka31p.js +261 -0
  12. package/dist/{cli-p679pvce.js → cli-vbzkkcbv.js} +2 -2
  13. package/dist/{cli-4xksazfr.js → cli-z8ye91f0.js} +283 -1142
  14. package/dist/cli.js +12 -14
  15. package/dist/{doctor-hheax5yc.js → doctor-ykr6gtpv.js} +3 -3
  16. package/dist/engine/shared/cdp.d.ts +23 -19
  17. package/dist/engine-3gwctsty.js +24 -0
  18. package/dist/engine-mwshptgf.js +25 -0
  19. package/dist/{ext-q5024j6v.js → ext-bna9nr3v.js} +7 -6
  20. package/dist/{index-1a4rx87v.js → index-322fxk25.js} +344 -1130
  21. package/dist/{index-kqftehgy.js → index-dzp0hc2c.js} +4 -2
  22. package/dist/{index-fnhak0nh.js → index-qf7y4d85.js} +10 -404
  23. package/dist/index-r4wvy5v3.js +267 -0
  24. package/dist/{index-t43k5rq1.js → index-rzm1phg0.js} +23 -356
  25. package/dist/index.d.ts +0 -1
  26. package/dist/index.js +12 -87
  27. package/dist/lib/build-error.d.ts +4 -5
  28. package/dist/lib/build-preflight.d.ts +1 -35
  29. package/dist/lib/build-runner.d.ts +27 -44
  30. package/dist/lib/chromium.d.ts +5 -1
  31. package/dist/lib/engine.d.ts +3 -18
  32. package/dist/lib/extension-manager.d.ts +2 -2
  33. package/dist/lib/extension-manifest.d.ts +1 -1
  34. package/dist/lib/markdown/assemble.d.ts +2 -9
  35. package/dist/lib/markdown/index.d.ts +2 -4
  36. package/dist/lib/markdown/plugins.d.ts +0 -3
  37. package/dist/lib/npm-plugin-installer.d.ts +6 -1
  38. package/dist/lib/plugin-vendor.d.ts +10 -78
  39. package/dist/lib/source-provider.d.ts +1 -1
  40. package/dist/lib/validation-exec.d.ts +5 -6
  41. package/dist/{new-6xm4tdxb.js → new-0hv3nwqj.js} +9 -8
  42. package/dist/{preflight-ezt8rvg3.js → preflight-pk0k25fm.js} +7 -6
  43. package/dist/preview/file-watcher.d.ts +4 -43
  44. package/dist/preview/http-server.d.ts +1 -3
  45. package/dist/{preview-hehs46dd.js → preview-8b1fn59h.js} +7 -6
  46. package/dist/{preview-shell-gqnc5xxe.js → preview-shell-tqndvhbx.js} +5 -7
  47. package/dist/{publish-ha505ejq.js → publish-ba5h76tz.js} +7 -6
  48. package/dist/render.d.ts +1 -1
  49. package/dist/render.js +1 -9
  50. package/dist/{source-provider-ta09wegv.js → source-provider-pzmz0br9.js} +1 -1
  51. package/dist/{source-provider-7c2ww3bz.js → source-provider-qbthnmqw.js} +1 -1
  52. package/dist/{validate-je56vdbj.js → validate-4rq2r5b3.js} +7 -6
  53. package/package.json +1 -4
  54. package/dist/audit-v9594a72.js +0 -69
  55. package/dist/engine-qtfrfbpk.js +0 -41
  56. package/dist/engine-trte2tg2.js +0 -40
  57. package/dist/lib/browser-pool.d.ts +0 -35
  58. package/dist/lib/lint-runner.d.ts +0 -29
  59. package/dist/lint-tbywt66a.js +0 -68
package/dist/index.d.ts CHANGED
@@ -10,7 +10,6 @@
10
10
  */
11
11
  export * from "./api/index.ts";
12
12
  export { log } from "./utils/logger.ts";
13
- export { runLint } from "./lib/lint-runner.ts";
14
13
  export { openPath } from "./lib/open-path.ts";
15
14
  export { executeAndReport, executeValidation } from "./lib/validation-exec.ts";
16
15
  export type { ValidationExecutionResult } from "./lib/validation-exec.ts";
package/dist/index.js CHANGED
@@ -7,6 +7,7 @@ import {
7
7
  BUILT_IN_STYLE_SET_IDS,
8
8
  BUILT_IN_TEMPLATE_IDS,
9
9
  BUNDLED_EXTENSIONS,
10
+ DEFAULT_NPM_REGISTRY,
10
11
  EXTENSIONS_DIR,
11
12
  EXTENSION_KINDS,
12
13
  EXTENSION_MANIFEST_FILENAME,
@@ -84,8 +85,8 @@ import {
84
85
  listSnippets,
85
86
  loadManifest,
86
87
  loadManifestWithPath,
87
- loadPluginsWithCss,
88
88
  log,
89
+ npmRegistryUrl,
89
90
  openPath,
90
91
  parseExtensionSpecifier,
91
92
  parseRemoteOrigin,
@@ -118,7 +119,6 @@ import {
118
119
  resolvePublishFormat,
119
120
  resolvePublishRequest,
120
121
  revokeGoogleCredential,
121
- rulePageContainment,
122
122
  ruleRemoteUrls,
123
123
  ruleRiskyProps,
124
124
  ruleSyntax,
@@ -144,18 +144,20 @@ import {
144
144
  syncProject,
145
145
  testRemoteAccess,
146
146
  validateProjectExtensions
147
- } from "./index-1a4rx87v.js";
147
+ } from "./index-322fxk25.js";
148
148
  import {
149
149
  BUILD_DIAGNOSTIC_CODES
150
- } from "./index-kqftehgy.js";
150
+ } from "./index-dzp0hc2c.js";
151
+ import {
152
+ BuildError
153
+ } from "./index-r4wvy5v3.js";
151
154
  import {
152
- BuildError,
153
155
  DEFAULT_PRINT_OPTS,
156
+ assertMilestone,
154
157
  readyProbeExpr
155
- } from "./index-t43k5rq1.js";
158
+ } from "./index-rzm1phg0.js";
156
159
  import {
157
160
  AUTO_SNAPSHOT_MESSAGE,
158
- DEFAULT_NPM_REGISTRY,
159
161
  HISTORY_PAGE_LIMIT,
160
162
  PLUGINS_DIR,
161
163
  RESTORE_BACKUP_MESSAGE,
@@ -163,13 +165,12 @@ import {
163
165
  countUnversionedChanges,
164
166
  isNoChangesError,
165
167
  listLocalBranches,
166
- npmRegistryUrl,
167
168
  providerFor,
168
169
  resolveLogger,
169
170
  restoreVersionWithBackup,
170
171
  switchBranch,
171
172
  whenGitIdle
172
- } from "./index-fnhak0nh.js";
173
+ } from "./index-qf7y4d85.js";
173
174
  import {
174
175
  capabilitiesFor,
175
176
  detectProjectSource,
@@ -177,83 +178,7 @@ import {
177
178
  repoRootForSource,
178
179
  repoSubPath
179
180
  } from "./index-v5mp7a6q.js";
180
- import {
181
- __require
182
- } from "./index-37x76zdn.js";
183
- // src/lib/lint-runner.ts
184
- import { resolve } from "node:path";
185
- import { readFile } from "node:fs/promises";
186
- async function runLint(opts = {}) {
187
- const { glob } = await import("glob");
188
- const { manifest, manifestDir } = await loadManifestWithPath(opts.manifest, {
189
- explicit: opts.manifest !== undefined
190
- });
191
- const resolved = resolveConfig({}, manifest);
192
- let files;
193
- if (opts.files) {
194
- files = await glob([opts.files], { nodir: true, ignore: ["**/*.min.css"] });
195
- } else {
196
- const relStyles = await resolveActiveStyles(manifestDir, resolved.styles);
197
- const projectFiles = relStyles.map((rel) => resolve(manifestDir, rel));
198
- let pluginStylePaths = opts.pluginStylePaths;
199
- if (pluginStylePaths === undefined) {
200
- ({ pluginStylePaths } = await loadPluginsWithCss(resolved.extensions, manifestDir, (ref, err) => log.warn(`Skipping plugin "${ref}" for lint — ${err.message}`)));
201
- }
202
- files = [...projectFiles, ...pluginStylePaths].filter((f) => !f.endsWith(".min.css"));
203
- }
204
- if (files.length === 0) {
205
- log.warn("No CSS files found to lint");
206
- return { ok: true, riskyCount: 0, containmentCount: 0, filesLinted: 0 };
207
- }
208
- log.info(`Linting ${files.length} CSS file(s)`);
209
- let errorCount = 0;
210
- let riskyCount = 0;
211
- let containmentCount = 0;
212
- let linted = 0;
213
- for (const file of files) {
214
- let css;
215
- try {
216
- css = await readFile(file, "utf8");
217
- } catch (err) {
218
- log.error(` ${file}`);
219
- log.error(` cannot read stylesheet: ${err instanceof Error ? err.message : String(err)}`);
220
- errorCount++;
221
- continue;
222
- }
223
- linted++;
224
- const warnings = checkCss(css, file);
225
- const errors = warnings.filter((w) => w.severity === "error");
226
- const risky = warnings.filter((w) => w.rule === ruleRiskyProps);
227
- const containment = warnings.filter((w) => w.rule === rulePageContainment);
228
- riskyCount += risky.length;
229
- containmentCount += containment.length;
230
- if (errors.length > 0) {
231
- log.error(` ${file}`);
232
- for (const w of errors) {
233
- log.error(` ${w.line}:${w.column} ${w.message} (${w.rule})`);
234
- }
235
- errorCount += errors.length;
236
- }
237
- const nonErrorWarnings = [...risky, ...containment].sort((a, b) => a.line - b.line);
238
- if (nonErrorWarnings.length > 0) {
239
- log.warn(` ${file}`);
240
- for (const w of nonErrorWarnings) {
241
- log.warn(` ${w.line}:${w.column} ${w.message} (${w.rule})`);
242
- }
243
- }
244
- }
245
- if (errorCount > 0) {
246
- log.error("CSS lint errors found");
247
- return { ok: false, riskyCount, containmentCount, filesLinted: linted };
248
- }
249
- const totalWarnings = riskyCount + containmentCount;
250
- if (totalWarnings > 0) {
251
- log.warn(`${totalWarnings} print-safety warning(s): ${riskyCount} risky effect(s), ${containmentCount} page-containment`);
252
- } else {
253
- log.success("CSS lint passed");
254
- }
255
- return { ok: true, riskyCount, containmentCount, filesLinted: linted };
256
- }
181
+ import"./index-37x76zdn.js";
257
182
  export {
258
183
  whenGitIdle,
259
184
  validateProjectExtensions,
@@ -277,7 +202,6 @@ export {
277
202
  sanitizeCloneFolderName,
278
203
  sameExtension,
279
204
  runPublish,
280
- runLint,
281
205
  runChecks,
282
206
  runBuild,
283
207
  ruleSyntax,
@@ -380,6 +304,7 @@ export {
380
304
  capabilitiesFor,
381
305
  autoSyncDelayMs,
382
306
  autoSnapshotDelayMs,
307
+ assertMilestone,
383
308
  assertExtensionContained,
384
309
  adoptFolder,
385
310
  addExtension,
@@ -1,15 +1,14 @@
1
1
  /**
2
2
  * The CLI's exit-code contract (UX finding M47) — ONE place the numbers are
3
3
  * defined. Every command's process exit code means the same thing across
4
- * `build`/`preview`/`lint`/`validate`/`preflight`/`audit`/`repair`/`publish`/
5
- * `new`, so CI can branch on it without parsing output:
4
+ * `build`/`preview`/`validate`/`preflight`/`publish`/`ext`/`new`/`doctor`,
5
+ * so CI can branch on it without parsing output:
6
6
  *
7
7
  * 0 OK — clean run, nothing to fix.
8
8
  * 1 FINDINGS — the command completed but reported findings/validation
9
- * failures (validate/preflight/audit findings, a build's
9
+ * failures (validate/preflight findings, a build's
10
10
  * quality-gate rejection). The invocation itself was fine;
11
- * the content wasn't. Standalone `gutterpress lint` uses this
12
- * code for CSS lint failures too. `gutterpress build`'s CSS
11
+ * the content wasn't. `gutterpress build`'s CSS
13
12
  * print-safety check (`source.stylelint`) now runs as one
14
13
  * of pre-build validation's checks (#272 — one CSS gate,
15
14
  * not two) and fails the build through this same code; the
@@ -15,15 +15,6 @@ import type { BuildFormat } from "./build-runner";
15
15
  * stampCreator) and needs no system tool at all.
16
16
  * qpdf is REQUIRED for pdfx + stripAnnotations (default true).
17
17
  */
18
- /**
19
- * Does this build render in the POOLED/external Chromium? The one rule,
20
- * defined once: HTML builds never paginate here; an injected `engineBrowser`
21
- * (the desktop's Electron host) replaces the pool. Every caller that gates
22
- * preflight, prewarm, or the milestone check derives from THIS predicate.
23
- */
24
- export declare function rendersInPooledChromium(format: BuildFormat, opts: {
25
- engineBrowser?: unknown;
26
- }): boolean;
27
18
  export declare function preflightBuildTools(format: BuildFormat, opts: {
28
19
  stripAnnotations?: boolean;
29
20
  engineBrowser?: unknown;
@@ -32,37 +23,12 @@ export declare function preflightBuildTools(format: BuildFormat, opts: {
32
23
  stripAnnotations: boolean;
33
24
  };
34
25
  }): Promise<void>;
35
- /**
36
- * Native engine only: verify the browser-pool's Chromium meets
37
- * `engine/shared/cdp.ts`'s `REQUIRED_MILESTONE`, with an early, actionable
38
- * error instead of the late, cryptic one `connectChromium` throws from deep
39
- * inside `buildNativePdf` (reached only after quality gates + the markdown
40
- * render have already run). `preflightBuildTools`'s presence check
41
- * (`resolveChromiumExecutable`) doesn't catch a resolved-but-too-old binary —
42
- * this does.
43
- *
44
- * Deliberately NOT called from `preflightBuildTools` itself: that would
45
- * force `runBuild` to await a full Chromium cold start (~1-2s) BEFORE
46
- * lint/validate even start, defeating the whole point of `prewarmBrowser()`
47
- * firing in parallel with them. Call this instead right after quality gates
48
- * finish and before rendering — by then the prewarmed browser is usually
49
- * already warm, and any quality-gate failure (the common case) never pays
50
- * this cost at all. Reuses `getBrowser()` (the same cached instance
51
- * `buildNativePdf`'s `connectChromium` will reuse), so this is one cold
52
- * start, not two.
53
- *
54
- * Not reached by the desktop: it injects its own `engineBrowser` (Electron's
55
- * bundled Chromium, 148 as of Electron 42.1.0 = `REQUIRED_MILESTONE`), which
56
- * `runBuild` skips this check for and `buildNativePdf` milestone-checks
57
- * directly instead. This is the pooled/external-Chromium path only.
58
- */
59
- export declare function verifyNativeChromiumMilestone(): Promise<void>;
60
26
  export interface Gates {
61
27
  /**
62
28
  * Disable the `source.stylelint` check (CSS print-safety: remote urls,
63
29
  * risky print effects, page-containment) for this run, without touching
64
30
  * `preValidate` itself (#272 — one CSS gate, not two: this used to be a
65
- * whole second gate, `runLint`, that duplicated `source.stylelint`'s own
31
+ * whole second gate, a separate lint-runner, that duplicated `source.stylelint`'s own
66
32
  * `checkCss` pass one phase later). `true` when `--skip-lint` was passed or
67
33
  * `config.lint.enabled === false`; consulted only when `preValidate` is
68
34
  * also true — with `preValidate` off, no pre-build check (CSS included)
@@ -1,11 +1,9 @@
1
1
  import { resolveConfig } from "./manifest";
2
2
  import { type LoadedPluginsWithCss } from "./markdown/plugins";
3
- import { RENDER_TIMEOUT_MS } from "./browser-pool";
4
3
  import { BuildError } from "./build-error";
5
4
  import type { BuildDiagnostic } from "../engine/compiler/build.ts";
6
5
  import type { Browser as EngineBrowser, Session as EngineSession } from "../engine/shared/cdp.ts";
7
6
  import { type Gates } from "./build-preflight";
8
- export { RENDER_TIMEOUT_MS };
9
7
  export type { EngineBrowser, EngineSession };
10
8
  export type BuildFormat = "html" | "pdf" | "pdfx";
11
9
  export type PdfxFlavor = "x1a" | "x3";
@@ -22,7 +20,7 @@ export interface BuildRunnerOptions {
22
20
  stripAnnotations?: boolean;
23
21
  /**
24
22
  * Skip the CSS print-safety check (#272 — one CSS gate, not two). This used
25
- * to gate a separate `runLint` pass; it now disables just the
23
+ * to gate a separate lint-runner pass (since deleted); it now disables just the
26
24
  * `source.stylelint` check inside pre-build validation (see
27
25
  * {@link computeGates}'s `skipStylelint`). Has no effect when
28
26
  * `skipPreValidate` is also set — pre-build validation, CSS check
@@ -38,24 +36,17 @@ export interface BuildRunnerOptions {
38
36
  * diagnostic — this buys an eyes-open build, not a clean one.
39
37
  */
40
38
  allowShrink?: boolean;
41
- /**
42
- * Keep the pooled headless browser alive after the build returns. A one-shot
43
- * CLI build leaves this false so the process can exit; a long-lived
44
- * preview/watch server sets it true so the browser stays warm across rebuilds
45
- * (every rebuild then skips the ~1–2s Chromium launch). The server owns
46
- * `closeBrowser()` on shutdown.
47
- */
48
- keepBrowserAlive?: boolean;
49
39
  rawArgs: Record<string, unknown>;
50
40
  /**
51
- * Optional injected engine-Chromium factory for native builds
52
- * (`engine.ts`'s `buildNativePdf`). When omitted (the CLI's default), the
53
- * native engine attaches to `browser-pool.ts`'s pooled external Chromium,
54
- * and the usual Chromium preflight / milestone check apply. When supplied
55
- * (the desktop, over its own Electron `BrowserWindow` — see
56
- * `packages/desktop/electron`'s engine-browser module), it is used
57
- * instead, no external Chromium is required, and both of those checks are
58
- * skipped.
41
+ * Optional injected engine-browser factory for native (pdf/pdfx) builds.
42
+ * When omitted (the CLI's default), `runBuild` launches the system Chromium
43
+ * through `engine/shared/cdp.ts`'s `launchChromium()` — the one launcher,
44
+ * which resolves the binary via `lib/chromium.ts` and enforces the engine's
45
+ * milestone floor. When supplied (the desktop, over its own Electron
46
+ * `BrowserWindow` — see `packages/desktop/electron`'s engine-browser
47
+ * module), it is called in `launchChromium`'s place: no external Chromium
48
+ * is required or looked for. Either way `runBuild` owns the browser it
49
+ * obtains and closes it when the build ends.
59
50
  */
60
51
  engineBrowser?: () => Promise<EngineBrowser>;
61
52
  }
@@ -184,20 +175,9 @@ export interface BuildContext {
184
175
  * gets the SAME resolved `{ plugins, pluginCss, pluginStylePaths }` back,
185
176
  * whichever of them runs first.
186
177
  *
187
- * Before this, `runQualityGates`'s lint gate and `renderBook` each called
188
- * `loadPluginsWithCss` independently for the identical manifest. For an
189
- * npm-vendored plugin, EVERY load re-runs `verifyVendoredPlugin` ->
190
- * `computeVendorTreeDigest` (plugin-vendor.ts) — a recursive walk of the
191
- * vendored tree plus a full read-and-SHA-256 of every file, with no cache
192
- * anywhere in that module BY DESIGN (the digest exists to detect tampering
193
- * with the vendored tree; a cache keyed on anything less than the file
194
- * contents themselves — e.g. the receipt's mtime — would not notice an
195
- * edited vendored file). A `gutterpress build` with the lint gate on
196
- * therefore paid that cost twice for no reason: same manifest, same
197
- * `renderDir` anchor (see that field's doc comment — the two call sites'
198
- * base dirs were the historical risk here, and they are now provably the
199
- * same value), same plugin list. Memoizing the ONE load on the context
200
- * removes the duplicate work without caching anything security-relevant.
178
+ * One load means one answer: the validation gate checks exactly the plugin
179
+ * stylesheets the render will use, and a plugin that fails to load aborts
180
+ * the build at the first stage that needs it rather than partway through.
201
181
  */
202
182
  plugins: LoadedPluginsWithCss | null;
203
183
  }
@@ -276,18 +256,21 @@ export declare function resolveIccProfile(icc: string, manifestDir: string, expl
276
256
  export declare function publishToDirectory(workDir: string, targetDir: string, format: BuildFormat, artifactName: string | null): Promise<void>;
277
257
  /**
278
258
  * Orchestrate a build: resolve the context, mkdir the output, preflight tools
279
- * (non-html), pre-warm the browser when this build will render in Chromium,
280
- * run the quality gates, render the book, then hand off to the per-format output
281
- * strategy for rendering + finalize. The heavy lifting lives in the named
282
- * stages + strategies above (plus ./build-preflight and ./build-staging);
283
- * this reads as the pipeline it is.
259
+ * (non-html), start the engine browser when this build will render in
260
+ * Chromium, run the quality gates, render the book, then hand off to the
261
+ * per-format output strategy for rendering + finalize. The heavy lifting
262
+ * lives in the named stages + strategies above (plus ./build-preflight and
263
+ * ./build-staging); this reads as the pipeline it is.
284
264
  *
285
- * Everything from the prewarm decision onward runs inside a try/finally that
286
- * closes the pooled browser (unless `keepBrowserAlive` is set) — finding #50:
265
+ * The browser is this function's to own: there is ONE launcher
266
+ * (`engine/shared/cdp.ts`'s `launchChromium`, or the host's injected
267
+ * `engineBrowser` factory in its place), it is started un-awaited so the
268
+ * ~1–2s Chromium cold start overlaps lint + validation + markdown render, it
269
+ * is awaited right before rendering (so a missing or too-old Chromium fails
270
+ * there, with the launcher's own message, rather than deep inside the engine),
271
+ * and it is closed in a `finally` that runs on every exit — finding #50:
287
272
  * previously the close only happened on the success tail (inside
288
- * `finalizeBuild`), so a prewarmed Chromium leaked whenever a quality gate or
289
- * the render itself threw. `closeBrowser()` is a no-op if nothing was
290
- * launched (including the injected-`engineBrowser` path, which never uses
291
- * the pool), so it is safe to call unconditionally here.
273
+ * `finalizeBuild`), so a pre-launched Chromium leaked whenever a quality gate
274
+ * or the render itself threw.
292
275
  */
293
276
  export declare function runBuild(opts: BuildRunnerOptions): Promise<BuildRunnerResult>;
@@ -2,13 +2,17 @@
2
2
  * Returns the path to a system Chrome/Chromium binary, or undefined if none found.
3
3
  *
4
4
  * Resolution order:
5
- * 1. CHROMIUM_PATH / PUPPETEER_EXECUTABLE_PATH env vars
5
+ * 1. CHROMIUM_PATH env var (PUPPETEER_EXECUTABLE_PATH is a deprecated alias)
6
6
  * 2. Hard-coded standard install paths (Chrome / Edge / Brave / Chromium
7
7
  * on Linux, macOS, Windows)
8
8
  * 3. PATH probe via `which` / `where.exe` for common binary names
9
9
  * (catches Scoop, Chocolatey, Homebrew, portable installs, and any
10
10
  * Chromium variant the user added to PATH manually)
11
11
  *
12
+ * This is the ONE resolver: the launcher (`engine/shared/cdp.ts`'s
13
+ * `launchChromium`), the build preflight, the fingerprint and `doctor` all
14
+ * use it, so the binary they report is the binary that runs.
15
+ *
12
16
  * Prefer requireChromiumExecutable() for build paths that cannot continue
13
17
  * without it — it surfaces a multi-line install-instructions error.
14
18
  */
@@ -1,5 +1,5 @@
1
1
  import { type BuildDiagnostic } from "../engine/compiler/build.ts";
2
- import { type Browser as EngineBrowser } from "../engine/shared/cdp.ts";
2
+ import type { Browser as EngineBrowser } from "../engine/shared/cdp.ts";
3
3
  export type { EngineBrowser };
4
4
  /** The subset of `BuildOptions` that has a manifest/CLI source today (B.12). */
5
5
  export interface NativePdfOptions {
@@ -17,26 +17,11 @@ export interface NativePdfOptions {
17
17
  allowShrink?: boolean;
18
18
  }
19
19
  /**
20
- * Render `htmlFile` to `outPdf` via the Gutterpress engine. No HTTP staging —
21
- * but the pooled/pre-warmed Chromium IS reused (see module doc comment): this
22
- * module never launches or closes a browser itself.
20
+ * Render `htmlFile` to `outPdf` via the Gutterpress engine on `browser`.
23
21
  *
24
22
  * Returns the build's author-facing diagnostics so the caller can surface
25
23
  * them (the desktop Problems panel, the CLI's own output). Dropping them here
26
24
  * is what made the engine's print-quality audits invisible in every real
27
25
  * build path — they only ever reached the engine dev CLI.
28
- *
29
- * `getEngineBrowser` is an optional injected factory, mirroring the
30
- * engine-browser injection seam in `build-runner.ts`: when omitted (the CLI's
31
- * default), this module gets `browser-pool.ts`'s pooled
32
- * puppeteer browser and attaches `cdp.ts`'s `connectChromium()` to it, same as
33
- * always. When supplied (the desktop, over its own Electron `BrowserWindow` —
34
- * see `packages/desktop/electron`'s engine-browser module), that browser is
35
- * used directly instead — no pooled/external Chromium involved at all. Either
36
- * way this function owns closing whatever browser it ends up with: the pooled
37
- * path because `connectChromium`'s close only drops OUR websocket (never the
38
- * pool), and the injected path because the desktop hands over a browser built
39
- * fresh for exactly this one build (`newPage()` -> one window per build), so
40
- * nothing else is going to close it.
41
26
  */
42
- export declare function buildNativePdf(htmlFile: string, outPdf: string, options?: NativePdfOptions, getEngineBrowser?: () => Promise<EngineBrowser>): Promise<BuildDiagnostic[]>;
27
+ export declare function buildNativePdf(htmlFile: string, outPdf: string, options: NativePdfOptions, browser: EngineBrowser): Promise<BuildDiagnostic[]>;
@@ -138,8 +138,8 @@ export interface AddExtensionOptions extends NpmPluginInstallOptions {
138
138
  * - a bundled name is written as-is;
139
139
  * - a path (`./x`, `../x`, or absolute) is load-tested and written relative
140
140
  * to the project, referenced in place;
141
- * - an npm specifier (`name`, `name@version`) is downloaded, verified,
142
- * vendored with a receipt, load-tested, and written back as
141
+ * - an npm specifier (`name`, `name@version`) is downloaded,
142
+ * integrity-checked, vendored, load-tested, and written back as
143
143
  * `name@<exact version>`. On any failure the vendor tree is rolled back.
144
144
  *
145
145
  * Idempotent: adding what is already listed re-pins/updates that entry.
@@ -29,7 +29,7 @@ export interface ExtensionMetadata {
29
29
  * npm's own convention. See {@link extensionEntry} for the entry rule
30
30
  * (`gutterpress.markdown` wins when present). NOT used for an npm-installed
31
31
  * package: the installer resolves that entry with full `exports` semantics
32
- * (`npm-plugin-installer.ts`'s `resolvePackageEntry`), and it is never
32
+ * (`plugin-vendor.ts`'s `resolvePackageEntry`), and it is never
33
33
  * re-derived from `main` here.
34
34
  */
35
35
  main?: string;
@@ -72,8 +72,8 @@ export interface AssembleBookHtmlOptions {
72
72
  * Chromium reaches an `@page`-only `url()` lazily, during the print, and the
73
73
  * print path CDP drives never waits for a pending resource — so the sheet
74
74
  * comes back with its background colour alone, no error, a valid PDF of
75
- * blank paper (docs/known-limitations.md §3; mechanism in
76
- * PR #187's `docs/analysis/why-page-background-drops.md`).
75
+ * blank paper (docs/known-limitations.md §3; mechanism analysis in
76
+ * PR #187).
77
77
  *
78
78
  * What the preload buys is that the fetch STARTS during document load
79
79
  * instead of during the print. That is not a timing guarantee: a response
@@ -110,13 +110,6 @@ export interface AssembleBookHtmlOptions {
110
110
  title?: string;
111
111
  plugins?: LoadedPlugin[];
112
112
  pluginCss?: string;
113
- /**
114
- * Wrap each source file in `<div class="gutterpress-chapter"
115
- * data-chapter-src="<file>">`. Used only by incremental preview so one
116
- * source can be paginated and replaced independently. Off by default; build
117
- * output is unaffected.
118
- */
119
- wrapChapters?: boolean;
120
113
  /** Add a layout-neutral source-file id to source-mapped preview blocks. */
121
114
  annotateSourceChapters?: boolean;
122
115
  /**
@@ -5,8 +5,8 @@ export type { LayoutWarning } from "./assemble";
5
5
  /**
6
6
  * THE canonical "which markdown files make up this book, and in what order?"
7
7
  * resolver — markdown's counterpart to `resolveActiveStyles` (style-resolver.ts).
8
- * Both `renderChapters` below AND validation/lint (validation-exec.ts,
9
- * lint-runner.ts) call this, so what gets checked is always what gets rendered
8
+ * Both `renderChapters` below AND validation (validation-exec.ts) call this,
9
+ * so what gets checked is always what gets rendered
10
10
  * (2026-07-28 duplication audit — those two used to each re-derive their own
11
11
  * recursive-glob approximation of "the book's markdown files" instead of
12
12
  * calling this):
@@ -44,8 +44,6 @@ export declare function renderChapters(inputDir: string, opts?: {
44
44
  * wrapped in its own cascade layer — see the block below.
45
45
  */
46
46
  pluginStyles?: PluginStyleGroup[];
47
- /** Wrap each source file for incremental preview pagination. */
48
- wrapChapters?: boolean;
49
47
  /** Add source-file ids to source-mapped preview blocks without wrappers. */
50
48
  annotateSourceChapters?: boolean;
51
49
  /**
@@ -4,9 +4,6 @@ export type { GutterpressMarkerDeclaration, GutterpressMarkerLabel, GutterpressM
4
4
  export { applyPlugins, collectPluginCss, collectPluginStylePaths, collectPluginStyleGroups } from "./renderer";
5
5
  export type { PluginStyleGroup } from "./renderer";
6
6
  import { type PluginStyleGroup } from "./renderer";
7
- /** Test-only mutation seam between snapshot completion and snapshot verification. */
8
- export declare function __setVendorSnapshotHookForTests(hook?: (sourceRoot: string, snapshotRoot: string) => void | Promise<void>): void;
9
- export declare function clearVendoredPluginResolver(baseDir: string, packageName: string, version: string): void;
10
7
  /** Test-only: reset the path-plugin cache between test cases. */
11
8
  export declare function __resetPathPluginCacheForTests(): void;
12
9
  export declare function loadPlugin(config: ResolvedExtensionConfig, baseDir: string): Promise<LoadedPlugin>;
@@ -24,7 +24,12 @@ export interface InstalledNpmPlugin {
24
24
  backupRoot: string | null;
25
25
  warnings: string[];
26
26
  }
27
- /** Download and publish a fresh, receipt-backed vendor tree. Never reuses bytes. */
27
+ /**
28
+ * Download and publish a fresh vendor tree for one npm plugin. Never reuses
29
+ * bytes: a same-version reinstall downloads again and replaces the tree (the
30
+ * previous one is held as a backup until the manifest commits — see
31
+ * {@link finalizeNpmPluginInstall} / {@link rollbackNpmPluginInstall}).
32
+ */
28
33
  export declare function installNpmPlugin(projectDirInput: string, packageSpec: string, options?: NpmPluginInstallOptions): Promise<InstalledNpmPlugin>;
29
34
  /** Finish a successful vendor+manifest transaction. */
30
35
  export declare function finalizeNpmPluginInstall(installed: InstalledNpmPlugin): Promise<void>;
@@ -1,81 +1,16 @@
1
1
  /** Project-relative folder shared by local and vendored npm plugins. */
2
2
  export declare const PLUGINS_DIR = "plugins";
3
3
  export declare const VENDORED_NPM_DIR = "npm";
4
- export declare const VENDOR_RECEIPT_FILE = ".gutterpress-install.json";
5
- export declare const VENDOR_RECEIPT_VERSION = 2;
6
4
  export interface ParsedNpmPluginSpec {
7
5
  name: string;
8
6
  /** Exact version, semver range, or dist-tag requested after the package name. */
9
7
  selector?: string;
10
8
  }
11
- export interface VendorPackageReceipt {
12
- /** POSIX path relative to the versioned install root. */
13
- path: string;
14
- name: string;
15
- version: string;
16
- tarball: string;
17
- integrity: string;
18
- /** True only for old registry entries that offered no SHA-256-or-stronger SRI. */
19
- legacySha1: boolean;
20
- /** ESM/import-condition package entry, when the package exposes one. */
21
- entry?: string;
22
- /** CommonJS/require-condition package entry, when different or available. */
23
- requireEntry?: string;
24
- /** Declared production dependency/required-peer name -> package receipt path. */
25
- dependencies: Record<string, string>;
26
- }
27
- export interface VendorSkippedDependency {
28
- from: string;
29
- name: string;
30
- selector: string;
31
- kind: "optional" | "optional-peer";
32
- reason: string;
33
- }
34
- export interface VendorReceipt {
35
- schemaVersion: typeof VENDOR_RECEIPT_VERSION;
36
- root: {
37
- name: string;
38
- version: string;
39
- packagePath: string;
40
- /** POSIX path relative to the versioned install root. */
41
- entry: string;
42
- format: "module" | "commonjs";
43
- };
44
- packages: VendorPackageReceipt[];
45
- skipped: VendorSkippedDependency[];
46
- tree: {
47
- algorithm: "sha256";
48
- digest: string;
49
- files: number;
50
- bytes: number;
51
- };
52
- }
53
- export interface VerifiedVendorPlugin {
54
- installRoot: string;
55
- entryPath: string;
56
- format: "module" | "commonjs";
57
- packages: VerifiedVendorPackage[];
58
- receipt: VendorReceipt;
59
- }
60
- export interface VerifiedVendorPackage {
61
- path: string;
62
- name: string;
63
- packageDir: string;
64
- manifest: Record<string, unknown>;
65
- entryPath?: string;
66
- requireEntryPath?: string;
67
- dependencies: Record<string, string>;
68
- }
69
9
  export interface PackageResolutionTarget {
70
10
  target: string;
71
11
  /** Export-map targets are exact; legacy targets use Node-style fallbacks. */
72
12
  exact: boolean;
73
13
  }
74
- export interface VendorTreeDigest {
75
- digest: string;
76
- files: number;
77
- bytes: number;
78
- }
79
14
  export declare function isValidNpmPackageName(name: string): boolean;
80
15
  /** Parse `name`, `name@selector`, `@scope/name`, or `@scope/name@selector`. */
81
16
  export declare function parseNpmPluginSpec(input: string): ParsedNpmPluginSpec;
@@ -85,23 +20,20 @@ export declare function vendoredNpmPluginRoot(projectDir: string, name: string,
85
20
  /** npm-compatible package location within a versioned vendor root. */
86
21
  export declare function vendoredNpmPluginPackageDir(installRoot: string, name: string): string;
87
22
  export declare function toPosixPath(value: string): string;
88
- export declare function packageEntryFormat(manifest: Record<string, unknown>, relativeEntry: string): "module" | "commonjs";
89
23
  /** Reject names that alias, fail, or escape on supported Windows filesystems. */
90
24
  export declare function assertWindowsSafeRelativePath(relative: string): void;
91
25
  /** Canonical key for case-insensitive, Unicode-normalizing Windows aliases. */
92
26
  export declare function windowsPathKey(relative: string): string;
93
- /** Resolve export conditions/patterns without consulting any ambient filesystem. */
94
27
  export declare function packageResolutionTargets(manifest: Record<string, unknown>, subpath: string, condition: "import" | "require"): PackageResolutionTarget[];
95
- /** Resolve a package's import entry without Node/Bun package-name resolution. */
96
- export declare function resolvePackageEntry(packageDir: string, packageJson?: Record<string, unknown>, condition?: "import" | "require"): Promise<string>;
97
- /** SHA-256 every contained regular file and its canonical relative path. */
98
- export declare function computeVendorTreeDigest(root: string): Promise<VendorTreeDigest>;
99
- /** Resolve a vendor root without trusting lexical project containment. */
100
- export declare function resolveVendoredPluginInstallRoot(projectDir: string, expectedName: string, expectedVersion: string): Promise<string | null>;
28
+ export declare function safePackageTarget(target: string): string | null;
101
29
  /**
102
- * Verify a schema-v2 receipt and the complete contained tree. `null` means no
103
- * new-format marker exists, so an exact version may still be legacy metadata.
104
- * A present but invalid marker is always a hard failure, never a global-cache
105
- * fallback.
30
+ * Resolve a package's entry module (POSIX path relative to `packageDir`) from
31
+ * its own `package.json` — `exports` (the `import` condition, else `require`:
32
+ * a dynamic `import()` loads a CommonJS entry just as well), else `module`/
33
+ * `main`, else the `index.*` fallbacks — without consulting Node/Bun
34
+ * package-name resolution, so it works on a folder that is not on any module
35
+ * path. The entry must be a regular file contained in the package.
106
36
  */
107
- export declare function verifyVendoredPlugin(projectDir: string, expectedName: string, expectedVersion: string): Promise<VerifiedVendorPlugin | null>;
37
+ export declare function resolvePackageEntry(packageDir: string, packageJson?: Record<string, unknown>): Promise<string>;
38
+ /** Resolve a vendor root without trusting lexical project containment. */
39
+ export declare function resolveVendoredPluginInstallRoot(projectDir: string, expectedName: string, expectedVersion: string): Promise<string | null>;
@@ -202,7 +202,7 @@ export interface UnversionedChanges {
202
202
  /**
203
203
  * Files of THIS book (its folder inside the repo) that changed since the
204
204
  * last version — writer work only: app-written files (the vendored plugin
205
- * folder and its install receipt) are not counted.
205
+ * folder) are not counted.
206
206
  */
207
207
  changedFiles: number;
208
208
  /**