gutterpress 0.0.0

package/dist/lib/source-provider.d.ts

@@ -0,0 +1,244 @@
+import type { ProjectCapabilities, ProjectSource } from "./project-source.ts";
+/**
+ * isomorphic-git object cache scoped to ONE operation and released with it.
+ * NEVER hold one in module state: reading any object from a packfile loads
+ * the ENTIRE pack into the cache (multi-GB RSS on large repos). See the
+ * matching note in remote-auth/sync.ts.
+ */
+type GitCache = Record<string, unknown>;
+/** One entry in a project's version history (a Git commit, abstracted). */
+export interface SnapshotEntry {
+    /** Opaque revision id (a commit SHA for the local-git provider). */
+    id: string;
+    /** Author-supplied or auto-generated snapshot message. */
+    message: string;
+    /** Epoch milliseconds the snapshot was taken. */
+    timestamp: number;
+    /** Display name recorded for the snapshot author, if any. */
+    author?: string;
+}
+/** Inputs for initialising local version history on a folder (#25 default). */
+export interface InitVersionHistoryOptions {
+    projectDir: string;
+    authorName?: string;
+    authorEmail?: string;
+    initialMessage?: string;
+}
+/** Inputs for taking a snapshot (commit) of the current working tree. */
+export interface SnapshotOptions {
+    projectDir: string;
+    message: string;
+    authorName?: string;
+    authorEmail?: string;
+    /**
+     * Root of the Git repository the commit goes to. Defaults to `projectDir`.
+     * When the project is a subfolder of a repo, this is the enclosing repo root
+     * (the snapshot commits the whole tree — plain git, no per-folder scoping).
+     */
+    repoRoot?: string;
+    /** Optional log file for debugging snapshot operations. */
+    logFile?: string;
+}
+/**
+ * The git repo directory a project's operations run against. A project IS its
+ * git repo: opening a subfolder of a multi-book repo just opens the repo, and
+ * every operation (snapshot, history, restore, sync) runs on the repo root over
+ * the WHOLE tree — plain git semantics, no per-book scoping. Defensive: older
+ * persisted sources without `repoRoot` fall back to the project path.
+ */
+export declare function gitScopeFor(source: Extract<ProjectSource, {
+    type: "local-git-folder";
+}>): string;
+/** Inputs for restoring the working tree to a prior snapshot. */
+export interface RestoreSnapshotOptions {
+    projectDir: string;
+    id: string;
+}
+/** Paging inputs for {@link SourceProvider.listHistoryPage}. */
+export interface ListHistoryOptions {
+    /** Max entries per page (clamped to [1, 500]; default {@link HISTORY_PAGE_LIMIT}). */
+    limit?: number;
+    /**
+     * Continuation cursor: the `id` of the LAST entry of the previous page.
+     * The returned page starts strictly after it (newest-first order).
+     */
+    before?: string;
+}
+/** One page of version history (see {@link SourceProvider.listHistoryPage}). */
+export interface HistoryPage {
+    entries: SnapshotEntry[];
+    /** True when older entries exist past this page (pass the last id as `before`). */
+    hasMore: boolean;
+}
+/** Default history page size. Bounds the commit walk on huge repositories. */
+export declare const HISTORY_PAGE_LIMIT = 100;
+/**
+ * The version-control operations a project source can perform. Implementations
+ * are selected by `ProjectSource.type` (see {@link providerFor}).
+ */
+export interface SourceProvider {
+    readonly source: ProjectSource;
+    readonly capabilities: ProjectCapabilities;
+    initVersionHistory(options: InitVersionHistoryOptions): Promise<ProjectSource>;
+    snapshot(options: SnapshotOptions): Promise<SnapshotEntry>;
+    /**
+     * Newest-first history, BOUNDED to the default page size. A convenience
+     * wrapper over {@link listHistoryPage} — use that for "load more" paging.
+     */
+    listHistory(projectDir: string): Promise<SnapshotEntry[]>;
+    /** One page of newest-first history with a `before`-cursor continuation. */
+    listHistoryPage(projectDir: string, options?: ListHistoryOptions): Promise<HistoryPage>;
+    restore(options: RestoreSnapshotOptions): Promise<void>;
+}
+export declare const SNAPSHOT_STAGING_MARKER = "gutterpress-snapshot-staging";
+/**
+ * Run `fn` exclusively per resolved project dir (FIFO promise chaining).
+ * Exported for the remote-clone surface (#15) so clone/fetch operations share
+ * the SAME queue as snapshot/restore — ADR 0006 D2 requires one per-repo lock.
+ */
+export declare function withRepoLock<T>(projectDir: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Test-only: current number of live per-repo lock queues. Lets tests assert the
+ * B4 reclamation actually happens (the map returns to empty once every queued
+ * op settles) without exporting the map itself. Same test-hook convention as
+ * plugins.ts's `__resetPathPluginCacheForTests`.
+ */
+export declare function __repoLockQueueSizeForTests(): number;
+/**
+ * Resolve the commit author identity from an optional display name (exported
+ * for the sync surface so merge commits carry the same identity as
+ * snapshots).
+ */
+export declare function gitAuthor(name?: string, email?: string): {
+    name: string;
+    email: string;
+};
+export declare function readGitAuthor(dir: string): Promise<{
+    name?: string;
+    email?: string;
+}>;
+/**
+ * Resolve the author for a commit in `dir`, PER FIELD: caller-supplied →
+ * existing repo config (`user.name` / `user.email`) → the gutterpress default.
+ *
+ * This is the ONE author-resolution rule for every commit gutterpress writes —
+ * snapshots, merge commits, conflict resolutions, and recovery rescue commits
+ * alike. Do NOT call `gitAuthor` directly at a commit site: it skips the repo
+ * config, so a partially configured identity (say a name in Settings, an email
+ * in `.git/config`) would produce one identity for the snapshot and a
+ * different, defaulted one for the merge commit of the SAME sync.
+ */
+export declare function resolveGitAuthor(dir: string, name?: string, email?: string): Promise<{
+    name: string;
+    email: string;
+}>;
+/** Workdir-vs-index differences, as `git add -A` staging lists. */
+export interface WorkdirChanges {
+    /** New or modified files to `git.add`. */
+    adds: string[];
+    /** Deleted files to `git.remove`. */
+    removes: string[];
+}
+/**
+ * List workdir-vs-index differences with the library's `git.walk` over the
+ * `WORKDIR` and `STAGE` walkers — deliberately NO `TREE` (HEAD) walker, so a
+ * snapshot check never reads historical packfiles (multi-GB RSS on large
+ * repos). Whole-tree (a project is its git repo). Honours `.gitignore` for
+ * untracked paths (which also prunes `.git` itself — `isIgnored` always
+ * ignores it), exactly like `statusMatrix` does.
+ */
+export declare function listWorkdirChanges(dir: string, cache?: GitCache): Promise<WorkdirChanges>;
+/**
+ * Apply a {@link WorkdirChanges} diff to the index (`git add -A` semantics).
+ * Exported so callers that already computed a `WorkdirChanges` via
+ * {@link listWorkdirChanges} (e.g. the detached-HEAD recovery handler) can
+ * stage it without re-walking the tree or falling back to `git.statusMatrix`,
+ * which loads whole packfiles into memory on large repos.
+ */
+export declare function stageChanges(dir: string, changes: WorkdirChanges, cache: GitCache): Promise<void>;
+/**
+ * True when the working tree differs from the index (added/modified/deleted
+ * files). Used to skip empty snapshots. Exported (lock-free) for the sync
+ * surface (#15, ADR 0006 D5) — callers outside a lock should prefer the
+ * provider operations.
+ */
+export declare function hasPendingChanges(dir: string, cache?: GitCache): Promise<boolean>;
+/**
+ * True when the working tree has ANY uncommitted change relative to HEAD —
+ * both WORKDIR-vs-STAGE (unstaged edits) AND STAGE-vs-HEAD (staged-but-
+ * uncommitted). This matches `git status --porcelain`'s notion of "dirty".
+ *
+ * Distinct from {@link hasPendingChanges} (WORKDIR-vs-STAGE only, the hot
+ * sync-check path per the sync-simplicity mandate): this is for build
+ * *provenance* — the build fingerprint records whether the tree was clean at
+ * build time, where a `git add`-ed-but-not-committed change must still count
+ * as dirty (the old `git status --porcelain` fingerprint reported it; the
+ * WORKDIR-vs-STAGE-only check silently dropped it).
+ */
+export declare function hasUncommittedChanges(dir: string, cache?: GitCache): Promise<boolean>;
+/**
+ * Lock-free snapshot of the full working tree (stage everything + commit).
+ *
+ * Exported for the sync surface (#15, ADR 0006 D5): `syncProject` holds
+ * the per-repo lock for snapshot → fetch → merge → push as ONE sequence, so it
+ * needs the lock-free internal rather than `provider.snapshot()` (taking the
+ * per-method lock inside the sync lock would deadlock the FIFO queue).
+ * Callers outside a lock should use `providerFor(source).snapshot()`.
+ */
+export declare function snapshotWorkingTreeUnlocked(options: SnapshotOptions): Promise<SnapshotEntry>;
+/**
+ * True for the friendly "nothing new to save" rejection from `snapshot()`.
+ * Exported (RC1-3) so the auto-snapshot scheduler in the desktop host can
+ * swallow the expected clean-tree rejection without string-matching itself.
+ */
+export declare function isNoChangesError(e: unknown): boolean;
+/**
+ * Select the {@link SourceProvider} implementation for a classified source.
+ * `managed-github` (#15/#16) is not implemented yet — it throws if reached.
+ */
+export declare function providerFor(source: ProjectSource): SourceProvider;
+/** Resolve the `.git` directory path for a project (used by callers/tests). */
+export declare function gitDirFor(projectDir: string): string;
+/** Marker written before staging and removed after commit; presence means a prior snapshot may have died after staging. */
+export declare function snapshotStagingMarkerPath(projectDir: string): string;
+/** Inputs for {@link restoreVersionWithBackup}. */
+export interface RestoreVersionOptions {
+    projectDir: string;
+    /** Snapshot id (commit SHA) to restore the working tree to. */
+    id: string;
+    /** Identity recorded on the automatic pre-restore safety snapshot. */
+    authorName?: string;
+    authorEmail?: string;
+}
+/** Result of {@link restoreVersionWithBackup}. */
+export interface RestoreVersionResult {
+    /** The snapshot id the working tree was restored to. */
+    restoredId: string;
+    /**
+     * Id of the automatic safety snapshot taken of the pre-restore state, or
+     * `undefined` when the working tree was already clean (its state is already
+     * the latest snapshot, so no backup was needed).
+     */
+    backupId?: string;
+}
+/** Message recorded on the automatic pre-restore safety snapshot. */
+export declare const RESTORE_BACKUP_MESSAGE = "Automatic backup before restoring an earlier version";
+/**
+ * Message recorded on every host-scheduled automatic snapshot. The desktop's
+ * history UI groups consecutive entries carrying EXACTLY this message, so the
+ * string is a contract — change it only with a matching UI update.
+ */
+export declare const AUTO_SNAPSHOT_MESSAGE = "Automatic snapshot";
+/**
+ * Restore the working tree to a prior snapshot SAFELY (#13): if the current
+ * state has unsaved-to-history changes, an automatic safety snapshot is
+ * committed FIRST, so a restore can never lose work — the pre-restore state
+ * stays reachable through the same View History UI. This is the operation the
+ * desktop's "Restore Version" action calls; the raw `provider.restore()` is the
+ * low-level primitive.
+ *
+ * Pure isomorphic-git via the provider layer (CLAUDE.md §7). Throws when the
+ * folder has no version history.
+ */
+export declare function restoreVersionWithBackup(options: RestoreVersionOptions): Promise<RestoreVersionResult>;
+export {};

package/dist/lib/static-serve.d.ts

@@ -0,0 +1,54 @@
+import http from "node:http";
+/**
+ * Extension -> Content-Type map shared by every localhost static file server
+ * in this package: the build-time pagination server and PDF-render server
+ * (build-runner.ts) and the live preview server (preview/http-server.ts).
+ *
+ * Previously two independent 17-entry tables that had to be edited in lockstep
+ * (finding #17) — a new asset type added to only one would render differently
+ * in preview vs build-time pagination with no error, a silent divergence
+ * class. One table now; add a new extension once.
+ *
+ * That same divergence class recurred once more (2026-07-28 duplication
+ * audit): this table and `asset-inline.ts`'s `MIME_BY_EXT` — a separate table
+ * answering a separate question, "what Content-Type does a data: URI need
+ * when embedding this file inline," vs. this table's "what Content-Type does
+ * an HTTP response need" — had drifted again, missing `.webp`/`.avif` here.
+ * A large (>512KB, over the inliner's threshold) WebP/AVIF image was copied
+ * as a real file and then served as `application/octet-stream` by both
+ * servers above. Added below; if a third image format shows up, add it to
+ * BOTH tables in the same commit (asset-inline.ts is out of scope for this
+ * PR — see docs/reviews/duplication-audit-2026-07-28.md).
+ */
+export declare const STATIC_MIME: Record<string, string>;
+/**
+ * Confine an already-decoded relative path to `root`, guarding against path
+ * traversal (`..` segments, absolute-looking paths escaping via `..`).
+ * Returns `null` if the resolved path escapes `root`.
+ *
+ * Shared by {@link resolveStaticPath} (which decodes a URL pathname first)
+ * AND by callers that already hold a decoded string with no pathname
+ * semantics to strip. Query-string values are NOT dot-segment-normalized by
+ * the WHATWG URL parser the way `url.pathname` is, so any route reading a raw
+ * query value as a filesystem-relative path must run it through this guard.
+ */
+export declare function resolveWithinRoot(relPath: string, root: string): string | null;
+/**
+ * Resolve a request URL pathname to an absolute path inside `root`, guarding
+ * against path traversal (`..`, encoded separators, absolute-looking paths).
+ * Returns `null` if the pathname cannot be decoded or the resolved path
+ * escapes `root` — callers turn that into a 403/404 as fits their route.
+ */
+export declare function resolveStaticPath(urlPathname: string, root: string): string | null;
+/**
+ * Minimal static file responder: read `filePath` and write it to `res` with
+ * the `STATIC_MIME` content-type (falling back to `application/octet-stream`);
+ * 404 on any read failure (missing file, directory, permission error).
+ *
+ * Deliberately minimal — no directory-index fallback, no HTML
+ * post-processing, no cache-control shaping. Callers that need those (the
+ * preview server's HMR-snippet injection + directory `index.html` fallback)
+ * build on top of `resolveStaticPath` + `STATIC_MIME` directly instead of
+ * this helper.
+ */
+export declare function serveFile(filePath: string, res: http.ServerResponse): Promise<void>;

package/dist/lib/style-resolver.d.ts

@@ -0,0 +1,30 @@
+/** One resolvable project stylesheet for the CSS editor's picker. */
+export interface ProjectStyle {
+    /** Absolute path to the `.css` file. */
+    path: string;
+    /** Project-relative, "/"-separated display name (e.g. `themes/dark/theme.css`). */
+    displayName: string;
+    /** True when this stylesheet is in the manifest `styles:` list (the active set). */
+    active: boolean;
+}
+/**
+ * THE canonical "which stylesheet does this project use?" resolver — consumed by
+ * BOTH the renderer (to `<link>` them) and the editor (to edit them), so they
+ * can never disagree. Returns project-relative paths:
+ *   1. the manifest `styles:` list, if it has any entries; else
+ *   2. the first conventional stylesheet the project actually has
+ *      (`FALLBACK_PRIORITY`); else
+ *   3. the first discovered `.css` anywhere we scan (deterministic); else
+ *   4. `[]` — the project has no stylesheet (an honest empty, never a phantom
+ *      link to a missing file).
+ * `manifestStyles` is the manifest's `styles:` value (the caller already has it
+ * resolved); pass `undefined` to have it read from the manifest.
+ */
+export declare function resolveActiveStyles(projectDir: string, manifestStyles?: string[]): Promise<string[]>;
+/**
+ * Resolve a project's editable stylesheets for the picker: the ACTIVE set
+ * (`resolveActiveStyles`, marked `active: true`) followed by the project's OTHER
+ * discovered `.css` files (alphabetical). `projectDir` must be absolute. Returns
+ * `[]` for a project with no stylesheets at all.
+ */
+export declare function listProjectStyles(projectDir: string): Promise<ProjectStyle[]>;

package/dist/lib/theme-import.d.ts

@@ -0,0 +1,70 @@
+import { type PrintSafeWarning } from "./printsafe.ts";
+import { type ThemeInfo } from "./theme-manager.ts";
+/** Reject a raw archive larger than this before unzipping (zip-bomb surface). */
+export declare const MAX_THEME_ARCHIVE_BYTES: number;
+/** Reject an archive whose entries expand past this in total (zip-bomb surface). */
+export declare const MAX_THEME_UNZIPPED_BYTES: number;
+/** A non-fatal issue surfaced to the author after a successful import. */
+export interface ThemeImportWarning {
+    code: "print-safety" | "no-theme-json" | "unnamed-theme" | "extra-files";
+    message: string;
+}
+/** Outcome of a `.zip` / `.css` import: the imported theme + any warnings. */
+export interface ThemeImportResult {
+    theme: ThemeInfo;
+    warnings: ThemeImportWarning[];
+}
+/**
+ * Is this zip entry name unsafe to extract? Rejects absolute paths (posix or
+ * Windows drive), and any `..` segment (zip-slip / path traversal). Callers
+ * ALSO do a resolved-containment check as defense-in-depth.
+ */
+export declare function isUnsafeZipEntryPath(name: string): boolean;
+/**
+ * Locate the theme root inside a zip's entry names: the directory that directly
+ * contains `theme.css`, allowed at the archive root (`""`) or exactly one level
+ * down. Returns the root prefix (`""` for root, or the single sub-directory
+ * name), or `null` when there is no unambiguous theme root (none, or more than
+ * one candidate folder each holding a `theme.css`).
+ */
+export declare function locateThemeRoot(names: string[]): string | null;
+/**
+ * Split print-safety findings into the one that REJECTS the import (a CSS
+ * syntax/parse failure — the stylesheet is unusable) vs. WARN findings the
+ * author should still see (remote URLs, risky print effects, paged.js crash
+ * selectors) that import anyway. The discriminator is the rule id, not
+ * severity: `no-remote-urls`/`no-pagedjs-crash-selectors` are `error`-severity
+ * but the #106 spec still imports them with a warning; only `syntax-error`
+ * refuses.
+ */
+export declare function classifyThemeCssFindings(findings: PrintSafeWarning[]): {
+    reject: PrintSafeWarning | null;
+    warnings: PrintSafeWarning[];
+};
+/**
+ * From a theme folder's relative file paths, return the ones that are neither
+ * `theme.css`/`theme.json` nor a recognized bundled asset (font/image/css).
+ * These trigger a non-fatal "unexpected extra files" warning — the import
+ * still copies the whole folder.
+ */
+export declare function unexpectedThemeFiles(relPaths: string[]): string[];
+/**
+ * Import a theme from a `.zip` package. Unzips in memory (fflate), rejects
+ * unsafe paths and over-cap archives, locates the theme root (at the archive
+ * root or one folder down), extracts just that subtree to a temp folder, and
+ * finalizes via {@link finalizeThemeImport}. Lands the theme in
+ * `themes/<uniqueId>/` (never overwrites an existing theme).
+ */
+export declare function importThemeFromZip(projectDir: string, archive: Uint8Array): Promise<ThemeImportResult>;
+/**
+ * Import a theme from a bare `.css` file by wrapping it into a one-file theme
+ * folder (`theme.css` + a synthesized `theme.json` naming it). REJECTS a CSS
+ * that fails to parse.
+ */
+export declare function importThemeFromCssText(projectDir: string, css: string, name: string): Promise<ThemeImportResult>;
+/**
+ * Import a theme from a local file path, dispatched by extension: `.zip` →
+ * {@link importThemeFromZip}, `.css` → {@link importThemeFromCssText}. The
+ * desktop's host reads the path from a native file picker and calls this.
+ */
+export declare function importThemeFromFile(projectDir: string, filePath: string): Promise<ThemeImportResult>;

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

@@ -0,0 +1,128 @@
+/** Folder (relative to the project root) themes are copied into on apply/import. */
+export declare const THEMES_DIR = "themes";
+/** The built-in themes shipped as embedded assets (ids are folder names). */
+export declare const BUILT_IN_THEME_IDS: readonly ["clean-book", "ttrpg-supplement", "zine", "technical-doc"];
+export type BuiltInThemeId = (typeof BUILT_IN_THEME_IDS)[number];
+/** Parsed `theme.json` metadata (every field optional in the file). */
+export interface ThemeMetadata {
+    name?: string;
+    author?: string;
+    description?: string;
+    /** Optional preview image path (relative to the theme folder). */
+    preview?: string | null;
+}
+/** Author-friendly metadata for one theme (built-in or project). */
+export interface ThemeInfo {
+    /** Stable id (a built-in id, or a slug for imported/applied themes). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Theme author, when known. */
+    author?: string;
+    /** One-line description. */
+    description: string;
+    /** `"builtin"` (embedded) or `"project"` (copied into the project). */
+    kind: "builtin" | "project";
+    /** Optional preview image path relative to the theme folder. */
+    preview?: string | null;
+}
+/** A built-in theme resolved to disk (extracted from the embedded assets). */
+export interface ResolvedTheme {
+    info: ThemeInfo;
+    /** Absolute path to the theme's `theme.css` (in the extracted assets dir). */
+    cssPath: string;
+    /** Absolute path to the theme's folder. */
+    dir: string;
+}
+/** Which theme to apply: a built-in id, or a project theme already on disk. */
+export type ApplyThemeTarget = {
+    kind: "builtin";
+    id: BuiltInThemeId | string;
+} | {
+    kind: "project";
+    id: string;
+};
+/** List the built-in themes (metadata read from the extracted embedded assets). */
+export declare function listBuiltInThemes(): Promise<ThemeInfo[]>;
+/** Resolve a built-in theme to its extracted `theme.css` + parsed metadata. */
+export declare function resolveBuiltInTheme(id: string): Promise<ResolvedTheme>;
+/**
+ * List the themes that live inside the project under `themes/<id>/` (each a
+ * folder with a `theme.css`). Returns `[]` when there is no `themes/` folder.
+ */
+export declare function listProjectThemes(projectDir: string): Promise<ThemeInfo[]>;
+/**
+ * Read the project's currently active theme (the theme whose `theme.css` is in
+ * the manifest `styles:` list AND whose folder exists under `themes/`). Returns
+ * `null` when no theme is applied.
+ */
+export declare function getActiveTheme(projectDir: string): Promise<ThemeInfo | null>;
+/**
+ * Read the project's "previous theme" — the theme active immediately before the
+ * current one (#106). Returns `null` when there is no recorded previous theme,
+ * when its folder no longer exists, or when it is (somehow) already the active
+ * theme. The reference is persisted indefinitely (no timer) in the manifest.
+ */
+export declare function getPreviousTheme(projectDir: string): Promise<ThemeInfo | null>;
+/**
+ * Revert to the previously active theme (#106): re-apply the theme recorded by
+ * {@link getPreviousTheme}. Because {@link applyTheme} itself records the
+ * now-current theme as the new "previous", reverting is a toggle — revert again
+ * returns to where you were. Throws when there is no previous theme to revert to.
+ */
+export declare function revertTheme(projectDir: string): Promise<ThemeInfo>;
+/**
+ * Apply a theme to the project: COPY the theme folder into `themes/<id>/`
+ * (built-in themes are copied out of the embedded assets; project themes are
+ * already present) and wire the manifest so its `theme.css` is the active
+ * stylesheet. Returns the applied {@link ThemeInfo}.
+ *
+ * No-data-loss mandate (UX review M6): a project theme's `theme.css` is the
+ * exact file the Design panel writes token edits into, so re-copying a
+ * built-in over an EXISTING `themes/<id>/` would silently discard every
+ * customization the author made after the first apply. Applying a built-in
+ * therefore never overwrites an existing project theme folder — if one is
+ * already there (customized or not), the built-in is copied into a fresh id
+ * (via the same {@link uniqueThemeId} helper import/folder-import uses) and
+ * THAT becomes active, leaving the original folder untouched. In the normal UI flow the
+ * Appearance grid hides a built-in card once its project copy exists (so this
+ * path isn't reachable by clicking Apply twice); this guard is the
+ * defense-in-depth backstop for any other caller of this function.
+ */
+export declare function applyTheme(projectDir: string, target: ApplyThemeTarget): Promise<ThemeInfo>;
+/**
+ * Import a theme from a local folder by copying it into the project's
+ * `themes/<id>/`. The folder MUST contain a `theme.css`. Metadata comes from
+ * its `theme.json` (synthesised from the folder name when absent). The imported
+ * theme becomes available to {@link applyTheme}; importing does NOT auto-apply.
+ */
+export declare function importThemeFromFolder(projectDir: string, sourceDir: string): Promise<ThemeInfo>;
+/**
+ * Import a theme from a URL using the global `fetch` (bundle-safe — no node http
+ * client). Two shapes are supported:
+ *
+ *   - RAW CSS: a `…/theme.css` (or any `.css`) URL → fetched as the theme's
+ *     `theme.css`; metadata is synthesised from the URL.
+ *   - THEME FOLDER: a base URL (no `.css`) → we fetch `<base>/theme.json`
+ *     (optional) and `<base>/theme.css` (required) to assemble the theme.
+ *
+ * The fetched theme is written into the project's `themes/<id>/`. Bundled fonts
+ * are NOT followed for URL imports (a single CSS file + optional metadata) to
+ * keep the fetch surface small and predictable; authors wanting bundled assets
+ * use folder import.
+ */
+export declare function importThemeFromUrl(projectDir: string, url: string): Promise<ThemeInfo>;
+/**
+ * Read a theme's CSS for previewing. Built-in themes read from the embedded
+ * assets; project themes read from `themes/<id>/theme.css`. Used by the host to
+ * feed the renderer a sample-render thumbnail (the renderer never touches fs).
+ */
+export declare function readThemeCss(projectDir: string | null, source: {
+    kind: "builtin" | "project";
+    id: string;
+}): Promise<string>;
+/**
+ * Remove an imported/applied project theme folder. If it was the active theme,
+ * its `styles:` entry is dropped too. Never touches built-in (embedded) themes.
+ */
+export declare function removeProjectTheme(projectDir: string, id: string): Promise<void>;

package/dist/lib/tool-probe.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cross-platform tool detection helper.
+ *
+ * Wraps the platform's "where is this binary?" command:
+ *   - Windows: where.exe
+ *   - POSIX:   which
+ *
+ * Used in two places in the lib:
+ *   - packages/cli/src/checks/tool-check.ts — the validation gate, decides
+ *     which checks to skip when their backing CLI tool isn't installed.
+ *   - packages/cli/src/lib/chromium.ts — PATH-fallback for Chromium when the
+ *     fixed-path scan misses non-default installs (Scoop, Chocolatey, Brave,
+ *     Vivaldi, Arc, portable installs).
+ *   - packages/cli/src/lib/ghostscript.ts — PATH tier of the shared
+ *     cross-platform Ghostscript resolver.
+ *   - packages/cli/src/lib/build-runner.ts — pre-flight check at the top of
+ *     runBuild so a missing tool becomes an actionable error in 50ms instead
+ *     of a confusing ENOENT 90 seconds into the pipeline.
+ *
+ * One implementation; one place to fix bugs. Spawning goes through
+ * exec.ts's `execCapture`, which also owns the shared, correctly
+ * delimiter-joined `enhancedPath` (this file used to keep its own copy of
+ * that PATH construction, and exec.ts's copy hardcoded `:` — see
+ * docs/reviews 2026-07-10-architecture-critical-review.md, finding #3).
+ */
+/**
+ * Returns true if `tool` is resolvable via the platform's path-probe command.
+ */
+export declare function isToolAvailable(tool: string): Promise<boolean>;
+/**
+ * Returns the absolute path of `tool` if it's resolvable on PATH, or undefined.
+ *
+ * On Windows, where.exe prints one match per line (the first is the highest-
+ * priority match in PATH). On POSIX, which prints exactly one line. We always
+ * return the first line.
+ */
+export declare function findTool(tool: string): Promise<string | undefined>;

package/dist/lib/validation-exec.d.ts

@@ -0,0 +1,47 @@
+import { type OutputFormat } from "../checks/formatter";
+import { type RunnerOptions, type RunnerReport } from "../checks/runner";
+import { type ToolCheckResult } from "../checks/tool-check";
+import type { CheckContext, CheckResult } from "../checks/types";
+import { type ValidationProfile } from "./validation-profile";
+import type { ResolvedConfig } from "../schema/manifest.types";
+import "../checks/register-builtins";
+export interface ValidationExecutionArgs {
+    manifest?: string;
+    pdf?: string;
+    input?: string;
+    category?: string;
+    only?: string;
+    skip?: string;
+    phase?: string;
+    profile?: string;
+}
+export interface ValidationExecutionResult {
+    config: ResolvedConfig;
+    profile?: ValidationProfile;
+    context: CheckContext;
+    runnerOptions: RunnerOptions;
+    tools: ToolCheckResult;
+    report: RunnerReport;
+}
+export declare function executeValidation(args: ValidationExecutionArgs): Promise<ValidationExecutionResult>;
+export interface ReportAndCheckResult {
+    ok: boolean;
+    execution: ValidationExecutionResult;
+}
+/**
+ * Run validation and emit the standard text/json report. Returns ok=false when
+ * the report contains errors so callers can decide how to surface failure
+ * (process.exit for the CLI; throw for the build runner).
+ */
+export declare function executeAndReport(args: ValidationExecutionArgs, format?: OutputFormat): Promise<ReportAndCheckResult>;
+/**
+ * Derive the extra PDF summary lines (Max TAC / Fonts / Rasterized pages) shown
+ * after the standard report in text mode.
+ *
+ * These read the structured `code` / `data` fields on each CheckResult — NOT the
+ * human-readable `message` — so rewording a check message can never silently
+ * break the CLI summary. A line is emitted only when the corresponding check
+ * actually produced a result; a check skipped by missing tools / filters yields
+ * no result and therefore no (misleading) summary line.
+ */
+export declare function buildPdfSummaryLines(results: CheckResult[]): string[];

package/dist/lib/validation-profile.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedConfig } from "../schema/manifest.types";
+export type ValidationProfile = "dtrpg";
+export declare const DTRPG_STRICT_PDF_CHECKS: readonly ["pdf.structure.qpdf", "pdf.print.pdfx-markers", "pdf.print.pdfx-metadata", "pdf.print.embedded-fonts"];
+/**
+ * Fill in the strict PDF checks (structure/PDF-X markers/metadata/embedded
+ * fonts) for any of them the config left unset, without overwriting an
+ * author's explicit choice. ARCH finding #21: replaces the old
+ * `applyDtrpgPdfDefaults` name, which implied a dtrpg-only opt-in even though
+ * `executeValidation` applies it to every PDF validation regardless of
+ * profile/preset — see validation-exec.ts.
+ */
+export declare function applyDefaultPdfStrictChecks(config: ResolvedConfig): ResolvedConfig;
+/**
+ * @deprecated Use {@link applyDefaultPdfStrictChecks} — kept as an alias so
+ * existing call sites keep resolving under the old, dtrpg-branded name.
+ */
+export declare const applyDtrpgPdfDefaults: typeof applyDefaultPdfStrictChecks;
+export declare function applyValidationProfile(config: ResolvedConfig, profile: ValidationProfile): ResolvedConfig;

package/dist/lib/version.d.ts

@@ -0,0 +1,9 @@
+type PackageMeta = {
+    version: string;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+};
+export declare const PACKAGE_META: PackageMeta;
+/** The gutterpress lib version, e.g. `"0.7.1"`. */
+export declare const PACKAGE_VERSION: string;
+export {};