gutterpress 0.0.0

package/dist/lib/output-paths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Output location + artifact naming, by convention rather than configuration.
+ *
+ * A book builds to `<manifestDir>/dist/<title-slug>/`, and its artifacts are
+ * `<title-slug>-<format>.pdf`. This replaces the manifest's `output.dir` /
+ * `output.filename` / `output.html` block: the slug keeps several books in one
+ * tree apart, and the format is in the artifact name because the extension
+ * cannot tell a PDF from a PDF/X one (they previously shared a single
+ * configured filename, so building both left only the last).
+ *
+ * `--out` remains for per-invocation placement (CI, one-offs).
+ */
+export declare const DIST_DIRNAME = "dist";
+/** The rendered book document. Fixed: the desktop and index.html load it by name. */
+export declare const BOOK_HTML = "book.html";
+/** Slug identifying one book. Falls back to `book` for an unsluggable title. */
+export declare function bookSlug(title: string | undefined): string;
+/**
+ * A book's output directory. Anchored on the MANIFEST's directory, not the CWD,
+ * so building several projects from one working directory cannot collide.
+ */
+export declare function resolveOutputDir(manifestDir: string, title: string | undefined): string;
+export declare function artifactName(title: string | undefined, format: "pdf" | "pdfx"): string;

package/dist/lib/pagedjs-marker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Single source of truth for the Paged.js polyfill `<script>` slot.
+ *
+ * PURE / node-free by design: this module imports nothing (no `node:*`, no `fs`),
+ * so it can be shared by BOTH the pure, browser-usable HTML assembler
+ * (`markdown/assemble.ts`) and the node-side build/preview rewriters
+ * (`build-runner.ts`, `pagedjs.ts`, `preview/file-watcher.ts`).
+ *
+ * The contract between the assembler and every rewriter is the stable
+ * `data-pagedjs-polyfill` MARKER ATTRIBUTE — never a URL, filename, or version
+ * substring. Core emits the marker; the rewriters find/strip/replace it by
+ * attribute. A pagedjs version bump or attribute reorder therefore cannot
+ * silently break the strip/replace passes, and the un-rewritten `book.html`
+ * carries NO network dependency (there is no live CDN URL to leak).
+ */
+/**
+ * Pinned Paged.js version. Bump HERE only — the value is emitted purely as
+ * documentation on the marker tag; matching never depends on it.
+ */
+export declare const PAGEDJS_VERSION = "0.4.3";
+/** Stable marker attribute identifying the Paged.js polyfill script slot. */
+export declare const PAGEDJS_POLYFILL_MARKER = "data-pagedjs-polyfill";
+/**
+ * The polyfill `<script>` slot Gutterpress core emits into `book.html`. Carries the
+ * stable marker (with the intended version as its value, for greppability) and
+ * NO `src` — an un-rewritten `book.html` has zero network dependency. Every
+ * consumer replaces this slot with a locally-vendored polyfill before the book
+ * is ever loaded (build staging, the no-Chromium runtime fallback, live preview).
+ */
+export declare function pagedjsPolyfillTag(version?: string): string;
+/**
+ * Match the polyfill `<script>` slot. Matches EITHER the stable marker attribute
+ * (core output) OR a `paged.polyfill` `src` (legacy CDN / vendored copy that a
+ * staging/patch pass has already swapped in) — so the same matcher works at every
+ * stage of the pipeline. Deliberately matches `paged.polyfill` (the version-
+ * stable FILENAME), never a bare `pagedjs` substring, so the navigation toolbar
+ * scripts (`pagedjs-interface.js` / `pagedjs-bridge.js`) are left untouched.
+ *
+ * Attribute-order tolerant and version-agnostic. Returns a FRESH RegExp per call
+ * so the `g` flag's `lastIndex` is never shared between callers.
+ */
+export declare function pagedjsPolyfillTagRegex(): RegExp;

package/dist/lib/pagedjs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Inline script that polyfills Paged.js's missing break-inside: avoid support.
+ *
+ * Paged.js has an avoidBreakInside() method but never calls it. This handler
+ * intercepts onBreakToken and, when the break lands inside an element with
+ * data-break-inside="avoid", moves the break to before that element.
+ *
+ * Uses a data attribute (not CSS) because source nodes are disconnected from
+ * the DOM when onBreakToken fires, so getComputedStyle returns empty values.
+ *
+ * Must be registered via PagedConfig.before (runs before Paged.js renders).
+ */
+export declare const BREAK_INSIDE_HANDLER: string;
+/**
+ * Inject the Paged.js polyfill + render-complete marker into an HTML STRING.
+ *
+ * Pure so the build can paginate an in-memory copy: the shipped `book.html`
+ * must never carry the polyfill `<script src>` (it is a build-time engine, not
+ * part of the artifact), and the pagination server serves this patched string
+ * as an overlay instead of writing it to disk.
+ */
+export declare function patchHtmlStringForPagedjs(html: string, vendorPath: string): string;
+/**
+ * File-in-place wrapper around {@link patchHtmlStringForPagedjs}.
+ */
+export declare function patchHtmlForPagedjs(htmlPath: string, vendorPath: string): Promise<void>;

package/dist/lib/pagination.d.ts

@@ -0,0 +1,169 @@
+import type { Page } from "puppeteer-core";
+/**
+ * Render/pagination (ARCH finding #9, extracted from build-runner.ts): drives
+ * headless Chromium through Paged.js to fully paginate a staged HTML document,
+ * either printing it to PDF or serializing the paginated DOM to static HTML.
+ * Owns: the embedded static HTTP file server both render paths need (a local
+ * origin so relative asset URLs resolve), the shared navigate+wait+liveness
+ * sequence (`paginateAndCapture`), the default PDF renderer, and build-time
+ * static-HTML pagination. build-runner.ts's two `OutputStrategy` classes call
+ * into this module for the actual pagination work and never touch a puppeteer
+ * `Page` themselves.
+ */
+/** An in-memory response served instead of reading a file from disk. */
+export interface ServerOverlay {
+    body: string | Buffer;
+    contentType: string;
+}
+/**
+ * Start a localhost static file server rooted at `dir`, with optional in-memory
+ * `overlays` keyed by URL path (e.g. `/book.html`).
+ *
+ * Overlays are what let the build paginate WITHOUT staging a second copy of the
+ * project. `outDir` is served directly; the Paged.js-patched `book.html` and the
+ * vendored polyfill are supplied from memory, so the engine never has to be
+ * written into the shipped artifact and no asset is copied twice. This mirrors
+ * the preview server, which has always served `/vendor/*` as a virtual overlay
+ * rather than copying it per project.
+ *
+ * Path-traversal protection, the MIME map, and the actual file response are
+ * the shared `./static-serve` primitives (`resolveStaticPath` + `serveFile`)
+ * also used by preview/http-server.ts — a request that resolves outside `dir`
+ * gets 403; a missing file gets 404 from `serveFile` itself.
+ */
+export declare function createStaticFileServer(dir: string, defaultFile: string, overlays?: Record<string, ServerOverlay>): Promise<{
+    port: number;
+    close: () => Promise<void>;
+}>;
+/** Input handed to a PDF renderer: a URL serving the staged HTML + assets. */
+export interface PdfRenderInput {
+    /** URL of the staged HTML on a local HTTP server (assets resolve relative). */
+    url: string;
+    /** Absolute path the renderer must write the finished PDF to. */
+    outPdf: string;
+    /** Hard ceiling for navigation + pagination + PDF generation. */
+    timeoutMs: number;
+    /**
+     * When set, after printing the PDF the renderer also serializes the
+     * already-paginated DOM (the same DOM it just printed) and writes it to this
+     * path as raw static HTML. Lets ONE pagination pass emit BOTH the PDF and the
+     * static desktop HTML, so screen and PDF come from the same artifact. The
+     * serialize is read-only and runs AFTER `page.pdf()`, so it cannot affect the
+     * PDF. Optional; injected renderers that cannot serialize may ignore it.
+     */
+    captureStaticHtmlTo?: string;
+}
+/**
+ * A PDF renderer drives a browser engine to load `url`, wait for fonts +
+ * Paged.js (`window.__PAGED_RENDERED__ === true`), measure the first
+ * `.pagedjs_page`, and write a borderless PDF at that exact page size to
+ * `outPdf` with backgrounds printed.
+ *
+ * The default ({@link puppeteerPdfRenderer}) drives a system/bundled Chromium.
+ * The Electron desktop injects one backed by its own `webContents.printToPDF`,
+ * so the packaged app needs no external browser (ADR 0002, Phase 4).
+ */
+export type PdfRenderer = (input: PdfRenderInput) => Promise<void>;
+/** Hard ceiling for navigation + pagination + PDF generation. Large books need
+ *  this budget; it is also the puppeteer protocolTimeout for the pooled browser. */
+export declare const RENDER_TIMEOUT_MS: number;
+/** Tracks the last-seen `.pagedjs_page` count and when it last advanced. */
+export interface PaginationLivenessState {
+    count: number;
+    lastAdvanceAt: number;
+}
+export interface PaginationLivenessResult {
+    stalled: boolean;
+    state: PaginationLivenessState;
+}
+/**
+ * Pure stall-detection decision (finding #19), extracted out of the polling
+ * loop below so it is unit-testable with a fake page-count source instead of
+ * a real puppeteer `page`. Given the latest `.pagedjs_page` count poll and the
+ * previously tracked state, decide whether pagination has stalled — the count
+ * has not advanced for at least `stallWindowMs` — and return the updated
+ * state (advancing resets the liveness clock; a flat or regressed count
+ * leaves `lastAdvanceAt` untouched).
+ */
+export declare function evaluatePaginationLiveness(count: number, now: number, state: PaginationLivenessState, stallWindowMs: number): PaginationLivenessResult;
+/**
+ * Drive a puppeteer `page` to fully paginate the document at `url`: set the
+ * viewport + timeouts, navigate (waiting for network idle so vendored assets +
+ * the polyfill load), wait for web fonts, then block until Paged.js signals
+ * `window.__PAGED_RENDERED__ === true`.
+ *
+ * While waiting, a background poller checks the `.pagedjs_page` count every
+ * `STALL_POLL_INTERVAL_MS` and logs it (so a long build visibly advances
+ * instead of sitting silent), and fails fast with a BuildError the moment
+ * `evaluatePaginationLiveness` decides the count has stopped advancing for
+ * `STALL_WINDOW_MS` — instead of a wedged Paged.js run silently consuming the
+ * full `timeoutMs` / `RENDER_TIMEOUT_MS` budget (up to an hour) before anyone
+ * finds out. `timeoutMs` (== `RENDER_TIMEOUT_MS` at every call site) remains
+ * the outer budget for legitimately slow-but-advancing books.
+ *
+ * Policy (owner's call, superseding an earlier "warn and ship partial output"
+ * behavior): pagination either completes — `__PAGED_RENDERED__` fires — or the
+ * build FAILS. A stall (count plateaus, whether at zero or after some pages)
+ * and an outright wait timeout are BOTH treated as an incomplete render and
+ * throw a `BuildError`; neither path falls through to let a caller print/
+ * serialize whatever partial DOM exists. A silently-truncated "successful"
+ * print-ready PDF is worse than a build that fails loudly — non-technical
+ * authors have no way to notice half their book is missing. The stall check
+ * still fails fast (within `stallWindowMs` of the last advance) rather than
+ * waiting out the full `timeoutMs` budget.
+ *
+ * Shared navigate+wait sequence for BOTH render paths. Callers keep their own
+ * tails: the PDF path calls `page.pdf()`; the static-HTML path serializes the
+ * DOM — neither tail runs unless this function returns normally, i.e. unless
+ * pagination actually completed. Per-caller knobs (viewport, timeout,
+ * liveness window) are passed in so behavior is never silently changed;
+ * `livenessConfig` defaults to the production constants and exists as a seam
+ * for tests to shrink the poll/stall windows instead of waiting 60+ real
+ * seconds.
+ */
+export declare function paginateAndCapture(page: Page, url: string, timeoutMs: number, viewport?: {
+    width: number;
+    height: number;
+}, livenessConfig?: {
+    pollIntervalMs: number;
+    stallWindowMs: number;
+}): Promise<void>;
+/**
+ * Close a CSS string value that Paged.js deliberately left unterminated.
+ *
+ * Paged.js's StringSets handler writes its string-set results as inline custom
+ * properties with an OPENING quote and NO closing quote (paged.polyfill.js:
+ * `fragment.style.setProperty(\`--pagedjs-string-first-${name}\`, \`"${…}\`)`).
+ * Live that is harmless: `setProperty` parses each value in isolation and the
+ * CSS tokenizer auto-closes a string token at end-of-value. But the moment the
+ * DOM is SERIALIZED, all four of those properties land in ONE `style` attribute
+ * joined by `;` — and on reparse the first unterminated string swallows the
+ * declarations that follow it (`"1; --pagedjs-string-last-guideSection: "`).
+ * The consumer, `content: "C." var(--pagedjs-string-first-guideSection)`, then
+ * becomes invalid at computed-value time and the footer disappears.
+ *
+ * Given the raw property text, return it with a closing `"` appended when the
+ * string token does not terminate. Rules follow CSS Syntax §4.3.5 "consume a
+ * string token": a backslash escapes the next code point, and a backslash at
+ * end-of-input is dropped (it cannot escape the quote we are about to add).
+ * Values that are already terminated — including ones this function has already
+ * fixed — are returned unchanged, so it is idempotent. Values that are not a
+ * quoted string at all are left alone.
+ */
+export declare function closeUnterminatedCssString(value: string): string;
+/**
+ * Build-time pagination (SSG model): drive headless Chromium to fully paginate
+ * the book with Paged.js, then serialize the resulting already-fragmented DOM
+ * to a static HTML string. Paged.js's polisher injects its layout CSS as
+ * `<style>` elements INTO the DOM, so the serialized markup carries everything
+ * needed to render the pages with NO runtime pagination engine.
+ *
+ * Serves `outDir` itself (images resolve relative to `book.html`, exactly as
+ * they will in the shipped artifact) with the engine supplied as overlays.
+ */
+export declare function paginateToStaticHtml(htmlFile: string): Promise<string>;
+/**
+ * Render `htmlFile` (in its own `outDir`) to a PDF, serving that directory with
+ * the pagination engine supplied as in-memory overlays.
+ */
+export declare function renderHtmlToPdf(htmlFile: string, outPdf: string, renderer?: PdfRenderer, captureStaticHtmlTo?: string): Promise<void>;

package/dist/lib/pdf-inspect.d.ts

@@ -0,0 +1,123 @@
+/**
+ * In-process PDF inspection via unpdf (a serverless-tuned PDF.js build).
+ *
+ * This is the pure-JS replacement for the Poppler suite (pdfinfo, pdffonts,
+ * pdfimages, pdftotext) and the general qpdf inspection used by the post-build
+ * validation checks. It has ZERO system dependency and — unlike raw pdfjs-dist,
+ * whose `legacy` build eagerly evaluates canvas/DOMMatrix code — unpdf bundles
+ * cleanly under `bun build --compile` (verified). See ADR 0002.
+ *
+ * NOT replaced here (still system tools, by design):
+ *   - Ghostscript (gs): ink coverage + PDF/X CMYK conversion — no JS equivalent.
+ *   - qpdf: PDF/X OutputIntent/DOCINFO structure checks (pdfx-*) — needs raw
+ *     catalog/object access pdfjs has no public API for, and qpdf is already
+ *     mandatory whenever PDF/X is produced.
+ *
+ * Fidelity notes (accepted in ADR 0002):
+ *   - Structural integrity (`isLoadable`) is a "does it parse" gate, not a deep
+ *     `qpdf --check` of xref/stream-length integrity.
+ *   - Image DPI requires decoding the image to read its pixel dimensions and is
+ *     therefore best-effort; bleed-box reads fall back to a raw-byte scan because
+ *     pdfjs exposes no TrimBox/BleedBox accessor.
+ *
+ * Loaded documents are cached per path (invalidated on size/mtime change) so a
+ * single validation run parses a large PDF once across all checks.
+ */
+import type { PDFDocumentProxy, PDFPageProxy } from "unpdf/pdfjs";
+/**
+ * Cap on distinct cached documents (audit B3). One validation run touches a
+ * single PDF across ~13 checks (one entry), so this only bounds accumulation
+ * ACROSS runs in a long-lived host (the Electron desktop validating many
+ * projects over a session). Without it, `docCache` grew one never-freed parsed
+ * document per distinct path ever validated. LRU eviction destroys the evicted
+ * document so its decoded pages/fonts/images are released, not just unreferenced.
+ * (Exported so tests derive their eviction fixtures from the real cap.)
+ */
+export declare const DOC_CACHE_MAX = 8;
+/**
+ * Load (and cache) a PDF as a PDF.js document proxy. Returns null if the file
+ * is missing or cannot be parsed at all. Concurrent callers for the same path
+ * share one parse.
+ */
+export declare function loadPdf(path: string): Promise<PDFDocumentProxy | null>;
+/**
+ * Retain the document cache for the duration of a run. The check runner is a
+ * public lib export served by a long-lived host (the desktop), where two runs
+ * CAN overlap — e.g. a Problems-panel lint run and a publish preflight. An
+ * unconditional `clearPdfCache()` at either run's end would destroy documents
+ * the other run is actively reading (getPage/getOperatorList then throw
+ * "Transport destroyed") and would void the eviction grace protecting its
+ * evicted-but-held documents. So each run holds a scope instead: the returned
+ * release function decrements the count and performs the clear only when the
+ * LAST active scope releases. Release is idempotent — extra calls are no-ops.
+ */
+export declare function retainPdfCache(): () => void;
+/**
+ * Destroy and drop every cached document, including evicted ones still inside
+ * their destroy grace (their timers are cancelled). This is the FORCEFUL,
+ * unconditional reclaim — it ignores active retain scopes, so hosts should
+ * prefer `retainPdfCache()` (which clears when the last overlapping run
+ * releases); the check runner uses that scope. Exposed for tests and for
+ * hosts that know no run is in flight.
+ */
+export declare function clearPdfCache(): void;
+/** Test-only introspection: evicted documents still awaiting grace destruction. */
+export declare function pendingGraceDestroyCount(): number;
+/** Page dimensions in PostScript points (1/72") for the given 1-based page. */
+export declare function getPageSize(page: PDFPageProxy): {
+    w: number;
+    h: number;
+};
+/** Number of top-level outline (bookmark) entries; 0 if none. */
+export declare function getOutlineCount(doc: PDFDocumentProxy): Promise<number>;
+/** Page label array, or null when the PDF declares no explicit labels. */
+export declare function getPageLabels(doc: PDFDocumentProxy): Promise<string[] | null>;
+/**
+ * Count link annotations across the whole document. `stopAtFirst` short-circuits
+ * for the boolean "are there any links?" question (TOC-links check).
+ */
+export declare function countLinkAnnotations(doc: PDFDocumentProxy, stopAtFirst?: boolean): Promise<number>;
+interface TextPass {
+    /** Non-whitespace-stripped text per page (index 0 = page 1). */
+    textByPage: string[];
+    /** Every text run's baseline origin, for layout-variance analysis. */
+    positions: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+export declare function getTextPass(doc: PDFDocumentProxy): Promise<TextPass>;
+export interface ImageRef {
+    /** XObject resource name (or "(inline)" for inline images). */
+    name: string;
+    /** Rendered width/height on the page, in points (from the CTM). */
+    placedW: number;
+    placedH: number;
+    /** 1-based page number. */
+    page: number;
+}
+export interface FontRef {
+    name: string;
+    embedded: boolean;
+}
+interface OpPass {
+    imagesByPage: Map<number, ImageRef[]>;
+    fonts: FontRef[];
+}
+export declare function getOpPass(doc: PDFDocumentProxy): Promise<OpPass>;
+/**
+ * Per-image effective DPI = pixel dimension ÷ placed size in inches. Decodes
+ * each image (best-effort). Used only by the opt-in image-resolution check.
+ */
+export declare function getImageResolutions(doc: PDFDocumentProxy): Promise<Array<{
+    page: number;
+    xDpi: number;
+    yDpi: number;
+}>>;
+/**
+ * "Does it parse" gate: load every page. Returns true if the whole document is
+ * traversable. This is NOT a deep xref/stream-length integrity check — it only
+ * catches PDFs that are actually broken/unparseable (ADR 0002).
+ */
+export declare function isLoadable(doc: PDFDocumentProxy): Promise<boolean>;
+export {};

package/dist/lib/pdf-parse.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Read a PDF as a latin1 string for literal ASCII-marker scanning.
+ *
+ * latin1 maps every byte 0x00–0xFF to exactly one char (lossless for binary
+ * data) — never use utf8 here, which mangles non-text bytes. This is the
+ * in-process replacement for the previous `grep -ao <marker> file.pdf` usage
+ * and is a behavioral equivalent, including grep's one limitation: markers that
+ * live inside FlateDecode-compressed streams are not visible to a raw byte
+ * scan. grep had the identical blind spot, so callers see no behavior change.
+ *
+ * Used by the transparency, color-spaces, and bleed checks. All other PDF
+ * inspection now goes through the structured PDF.js reader in pdf-inspect.ts.
+ */
+export declare function readPdfBytes(pdfPath: string): Promise<string>;
+/**
+ * Parse ink coverage from `gs -sDEVICE=inkcov` output.
+ *
+ * Ghostscript has no pure-JS equivalent (it stays a system tool — see ADR 0002),
+ * so the inkcov path remains shell-based here.
+ */
+export declare function parseInkCov(out: string): {
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+    sum: number;
+}[];
+export interface InkCoveragePage {
+    page: number;
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+    tac: number;
+}
+/**
+ * Discriminated result for {@link getPerPageInkCoverage} (finding #51).
+ * Ghostscript failing (crash, corrupt PDF, missing binary, a Windows PATH
+ * mismatch — see finding #3) must be distinguishable from a legitimately
+ * measured, empty-pages result: both used to collapse to the same `[]`,
+ * which let the ink-coverage check silently PASS a book it never actually
+ * measured.
+ */
+export type InkCoverageResult = {
+    ok: true;
+    pages: InkCoveragePage[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Get per-page ink coverage using Ghostscript's inkcov device.
+ * Returns `{ ok: true, pages }` with per-page CMYK coverage (in percentages)
+ * on success, or `{ ok: false, error }` if gs could not be run/parsed —
+ * callers must surface the failure, not treat it as "0 pages measured".
+ */
+export declare function getPerPageInkCoverage(pdfPath: string): Promise<InkCoverageResult>;

package/dist/lib/plugin-manager.d.ts

@@ -0,0 +1,108 @@
+import { type NpmPluginInstallOptions } from "./npm-plugin-installer";
+/** Folder (relative to the project root) imported local plugins are copied to. */
+export { PLUGINS_DIR } from "./plugin-vendor";
+/** How a plugin entry is referenced in the manifest. */
+export type PluginKind = "local" | "npm";
+/** One configured plugin, as surfaced to the manager UI. */
+export interface ProjectPluginEntry {
+    /** Stable reference: the manifest `path` (local) or `name` (npm). */
+    ref: string;
+    /** `"local"` when referenced by file path, `"npm"` when by package name. */
+    kind: PluginKind;
+    /** Per-project enable flag. Absent in the manifest defaults to `true`. */
+    enabled: boolean;
+    /** Exact installed npm version. Absent for local, built-in, and legacy entries. */
+    version?: string;
+    /** Named module export selected as the plugin function. */
+    export?: string;
+    /** Non-fatal install notices, currently used for legacy SHA-1 registry entries. */
+    warnings?: string[];
+}
+interface PluginManagerInstallOptions extends NpmPluginInstallOptions {
+    exportName?: string;
+    __testFailBeforeManifestCommit?: () => void | Promise<void>;
+}
+/** Serialize all plugin filesystem + manifest mutations for one project. */
+export declare function withPluginMutationLock<T>(projectDir: string, mutation: () => Promise<T>): Promise<T>;
+/** Result of attempting to load one configured plugin. */
+export interface PluginValidationResult {
+    ref: string;
+    kind: PluginKind;
+    /** Mirrors the manifest enable flag. Disabled plugins are not load-tested. */
+    enabled: boolean;
+    /** `true` when the plugin loaded OK (or is disabled and skipped). */
+    ok: boolean;
+    /** The loader's fail-fast error message when `ok` is `false`. */
+    error?: string;
+}
+/** A curated markdown feature an author can turn on. */
+export interface RecommendedPlugin {
+    /** The npm package name (also the manifest entry that "Add" writes). */
+    name: string;
+    /** Short, plain-language feature name shown as the row title (the package
+     *  name is demoted to secondary text — a non-technical author shouldn't have
+     *  to read `markdown-it-*` ids to pick a feature). */
+    label: string;
+    /** One-line author-friendly description. */
+    description: string;
+    /**
+     * True when gutterpress ships this plugin (see `BUILTIN_OPTIONAL_PLUGINS`):
+     * "Add" enables it instantly, no install, works offline. All entries below
+     * are built-in — the always-on defaults (attrs/footnote/deflist, applied
+     * unconditionally in renderer.ts) are intentionally NOT listed here, since
+     * recommending the author "add" something already active is pure confusion.
+     */
+    builtin: true;
+}
+/**
+ * Curated, BUILT-IN opt-in markdown features. Each is bundled with gutterpress
+ * (`BUILTIN_OPTIONAL_PLUGINS`), so clicking "Add" writes the manifest entry AND
+ * the feature works immediately — no terminal, no install, offline. This is the
+ * non-technical-author happy path: "turn on a feature → it works".
+ */
+export declare const RECOMMENDED_PLUGINS: RecommendedPlugin[];
+/**
+ * List the project's configured plugins with their per-project enable flag.
+ * Returns `[]` when there is no manifest or no `plugins:` list.
+ *
+ * For object-form entries, the kind is taken from the manifest KEY (`path:` →
+ * local, `name:` → npm) rather than guessing from the value. This correctly
+ * classifies e.g. `path: plugins/foo.js` (no `./` prefix) as local. Scalar
+ * (string) entries fall back to the {@link isLocalRef} heuristic.
+ */
+export declare function listProjectPlugins(projectDir: string): Promise<ProjectPluginEntry[]>;
+/**
+ * Set the per-project enabled flag for the plugin identified by `ref` (its
+ * path or npm name). A string-form entry is normalised to an object entry so
+ * the flag can be attached. Persists to the manifest (preserving comments).
+ * Throws when no entry matches `ref`.
+ */
+export declare function setPluginEnabled(projectDir: string, ref: string, enabled: boolean): Promise<void>;
+/**
+ * Install an npm markdown-it plugin without an external package manager, then
+ * record its exact version in the manifest. Built-in optional plugins remain
+ * offline: adding one only records its bundled package name.
+ */
+export declare function addNpmPlugin(projectDir: string, packageSpec: string, exportName?: string): Promise<ProjectPluginEntry>;
+/** @internal Dependency/fault injection for focused installer tests. */
+export declare function addNpmPluginWithOptions(projectDir: string, packageSpec: string, options?: PluginManagerInstallOptions): Promise<ProjectPluginEntry>;
+/**
+ * Import a local plugin by copying the source file OR folder into the
+ * project's `plugins/` directory and adding a manifest entry that references
+ * the copied path (so the plugin travels with the project). Returns the new
+ * entry. Throws when `sourcePath` does not exist.
+ */
+export declare function addLocalPlugin(projectDir: string, sourcePath: string): Promise<ProjectPluginEntry & {
+    path: string;
+}>;
+/**
+ * Validate every configured plugin by attempting to LOAD it through the
+ * existing lib loader (`loadPlugin`). Disabled plugins are reported as
+ * disabled and NOT load-tested. Loader errors are CAUGHT and surfaced per
+ * plugin (never thrown through) so the UI can flag erroring plugins clearly.
+ *
+ * This reuses the fail-fast loader path verbatim (§5) — including its
+ * "not found / install it" message for unresolvable npm packages — rather than
+ * reimplementing resolution.
+ */
+export declare function validateProjectPlugins(projectDir: string): Promise<PluginValidationResult[]>;

package/dist/lib/plugin-vendor.d.ts

@@ -0,0 +1,107 @@
+/** Project-relative folder shared by local and vendored npm plugins. */
+export declare const PLUGINS_DIR = "plugins";
+export declare const VENDORED_NPM_DIR = "npm";
+export declare const VENDOR_RECEIPT_FILE = ".gutterpress-install.json";
+export declare const VENDOR_RECEIPT_VERSION = 2;
+export interface ParsedNpmPluginSpec {
+    name: string;
+    /** Exact version, semver range, or dist-tag requested after the package name. */
+    selector?: string;
+}
+export interface VendorPackageReceipt {
+    /** POSIX path relative to the versioned install root. */
+    path: string;
+    name: string;
+    version: string;
+    tarball: string;
+    integrity: string;
+    /** True only for old registry entries that offered no SHA-256-or-stronger SRI. */
+    legacySha1: boolean;
+    /** ESM/import-condition package entry, when the package exposes one. */
+    entry?: string;
+    /** CommonJS/require-condition package entry, when different or available. */
+    requireEntry?: string;
+    /** Declared production dependency/required-peer name -> package receipt path. */
+    dependencies: Record<string, string>;
+}
+export interface VendorSkippedDependency {
+    from: string;
+    name: string;
+    selector: string;
+    kind: "optional" | "optional-peer";
+    reason: string;
+}
+export interface VendorReceipt {
+    schemaVersion: typeof VENDOR_RECEIPT_VERSION;
+    root: {
+        name: string;
+        version: string;
+        packagePath: string;
+        /** POSIX path relative to the versioned install root. */
+        entry: string;
+        format: "module" | "commonjs";
+    };
+    packages: VendorPackageReceipt[];
+    skipped: VendorSkippedDependency[];
+    tree: {
+        algorithm: "sha256";
+        digest: string;
+        files: number;
+        bytes: number;
+    };
+}
+export interface VerifiedVendorPlugin {
+    installRoot: string;
+    entryPath: string;
+    format: "module" | "commonjs";
+    packages: VerifiedVendorPackage[];
+    receipt: VendorReceipt;
+}
+export interface VerifiedVendorPackage {
+    path: string;
+    name: string;
+    packageDir: string;
+    manifest: Record<string, unknown>;
+    entryPath?: string;
+    requireEntryPath?: string;
+    dependencies: Record<string, string>;
+}
+export interface PackageResolutionTarget {
+    target: string;
+    /** Export-map targets are exact; legacy targets use Node-style fallbacks. */
+    exact: boolean;
+}
+export interface VendorTreeDigest {
+    digest: string;
+    files: number;
+    bytes: number;
+}
+export declare function isValidNpmPackageName(name: string): boolean;
+/** Parse `name`, `name@selector`, `@scope/name`, or `@scope/name@selector`. */
+export declare function parseNpmPluginSpec(input: string): ParsedNpmPluginSpec;
+export declare function isExactNpmVersion(version: string): boolean;
+/** Root containing one pinned package's private `node_modules` tree. */
+export declare function vendoredNpmPluginRoot(projectDir: string, name: string, version: string): string;
+/** npm-compatible package location within a versioned vendor root. */
+export declare function vendoredNpmPluginPackageDir(installRoot: string, name: string): string;
+export declare function toPosixPath(value: string): string;
+export declare function packageEntryFormat(manifest: Record<string, unknown>, relativeEntry: string): "module" | "commonjs";
+/** Reject names that alias, fail, or escape on supported Windows filesystems. */
+export declare function assertWindowsSafeRelativePath(relative: string): void;
+/** Canonical key for case-insensitive, Unicode-normalizing Windows aliases. */
+export declare function windowsPathKey(relative: string): string;
+/** Resolve export conditions/patterns without consulting any ambient filesystem. */
+export declare function packageResolutionTargets(manifest: Record<string, unknown>, subpath: string, condition: "import" | "require"): PackageResolutionTarget[];
+/** Resolve a package's import entry without Node/Bun package-name resolution. */
+export declare function resolvePackageEntry(packageDir: string, packageJson?: Record<string, unknown>, condition?: "import" | "require"): Promise<string>;
+/** SHA-256 every contained regular file and its canonical relative path. */
+export declare function computeVendorTreeDigest(root: string): Promise<VendorTreeDigest>;
+/** Resolve a vendor root without trusting lexical project containment. */
+export declare function resolveVendoredPluginInstallRoot(projectDir: string, expectedName: string, expectedVersion: string): Promise<string | null>;
+/**
+ * Verify a schema-v2 receipt and the complete contained tree. `null` means no
+ * new-format marker exists, so an exact version may still be legacy metadata.
+ * A present but invalid marker is always a hard failure, never a global-cache
+ * fallback.
+ */
+export declare function verifyVendoredPlugin(projectDir: string, expectedName: string, expectedVersion: string): Promise<VerifiedVendorPlugin | null>;