gutterpress 0.0.0

package/dist/platform.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Platform abstraction contract (GitHub #41).
+ *
+ * The desktop talks to its host through ONE seam so that the app code never
+ * branches on `electron` vs `web` directly. Today the only host is Electron
+ * (IPC + native dialogs). When the PWA lands (0.6.0, #...), a `WebAdapter`
+ * backed by the File System Access API drops in behind the same interface and
+ * the app code does not change.
+ *
+ * This module is **types only** — it is imported by the browser SPA via
+ * `import type`, so it must never pull in a Node runtime dependency.
+ *
+ * Canonical home: `gutterpress`. The desktop re-exports these types
+ * from `src/lib/platform/` and implements them in `electron-adapter.ts` /
+ * `web-adapter.ts`. Keep the implementations in lockstep with this contract.
+ */
+/**
+ * The narrow set of capabilities whose implementation genuinely differs between
+ * a desktop (Electron) host and a browser (PWA) host: native dialogs, raw file
+ * IO, filesystem watching, and OS-keychain-backed secrets.
+ *
+ * Host RPC services that are *also* host-divergent (preview/build/doctor/prefs/
+ * updater) are modelled separately as {@link HostServices} so this primitive
+ * surface stays small and easy to reason about. The full thing the app consumes
+ * is {@link Platform} = `PlatformAdapter & HostServices`.
+ */
+/**
+ * Filesystem metadata for a single path (GitHub #44 — external-edit detection).
+ * `mtimeMs` is the modification time in epoch milliseconds; `exists` is `false`
+ * (with `mtimeMs`/`size` = 0) when the path is absent rather than throwing, so
+ * the editor can distinguish "deleted out from under us" from a read error.
+ */
+export interface FileStat {
+    mtimeMs: number;
+    size: number;
+    exists: boolean;
+}
+/**
+ * Result of a successful {@link PlatformAdapter.writeFile} (GitHub #44). Carries
+ * the post-write modification time so the editor can record the on-disk baseline
+ * mtime without a follow-up `statFile` round-trip — this is what lets
+ * external-edit detection suppress the self-echo of our own debounced save.
+ */
+export interface FileWriteResult {
+    mtimeMs: number;
+}
+export interface PlatformAdapter {
+    /** Which host backs this adapter. Lets the rare unavoidable branch be explicit. */
+    readonly platform: "electron" | "web";
+    /**
+     * Prompt the user to choose a project folder.
+     * @returns the absolute path, or `null` if the user cancelled.
+     * Electron: native directory dialog. Web: File System Access API.
+     */
+    openFolder(): Promise<string | null>;
+    /**
+     * Read a UTF-8 text file by absolute path.
+     * Editor seam for #38/#39 — no current consumer in 0.4.0.
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Write a UTF-8 text file by absolute path, creating/overwriting it.
+     * Resolves with the post-write {@link FileWriteResult} (`{ mtimeMs }`) so the
+     * editor (#44) can record the on-disk baseline mtime; callers that ignore the
+     * value are unaffected (additive widening — was `Promise<void>`).
+     */
+    writeFile(path: string, content: string): Promise<FileWriteResult>;
+    /**
+     * List the immediate entries of a directory (single level, no recursion).
+     * @returns each entry's `name`, absolute `path`, and whether it `isDir`.
+     * Editor seam for #38 (file-tree sidebar). Electron: `node:fs/promises`
+     * `readdir`. Web: File System Access API (0.6.0).
+     */
+    listDir(path: string): Promise<Array<{
+        name: string;
+        path: string;
+        isDir: boolean;
+    }>>;
+    /**
+     * Stat a file by absolute path (GitHub #44). Used by the editor to confirm a
+     * `watchFolder` event reflects a real on-disk change (mtime moved) versus the
+     * self-echo of our own `writeFile`. Resolves with `exists: false` rather than
+     * rejecting when the path is absent. Web throws until 0.6.0 (FS Access API).
+     */
+    statFile(path: string): Promise<FileStat>;
+    /**
+     * Watch a folder for changes, invoking `cb` on each change.
+     * @returns an unsubscribe function.
+     * Web has no general recursive-watch primitive — `WebAdapter` throws here
+     * until 0.6.0. Electron wiring lands with the in-app editor (#38).
+     */
+    watchFolder(path: string, cb: () => void): () => void;
+    /**
+     * Read a secret by key (e.g. a GitHub token). Lands with #12.
+     * Electron: OS keychain via `safeStorage`. Web: encrypted localStorage.
+     */
+    getSecret(key: string): Promise<string | null>;
+    /** Store a secret by key. Lands with #12. */
+    setSecret(key: string, value: string): Promise<void>;
+}

package/dist/plugin-wf2cbmwc.js

@@ -0,0 +1,129 @@
+import {
+  addNpmPlugin,
+  parseNpmPluginSpec
+} from "./cli-7ykx7pp0.js";
+import"./cli-h7phg3ka.js";
+import {
+  EXIT_CODES,
+  UsageError,
+  rejectExtraPositionals,
+  rejectUnknownFlags
+} from "./cli-hvqjs342.js";
+import"./cli-5bxx0c4y.js";
+import"./cli-1tyj4bk3.js";
+import"./cli-yja077f6.js";
+import"./cli-37x76zdn.js";
+
+// src/commands/plugin.ts
+import { defineCommand } from "citty";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+var pluginAddArgs = {
+  package: {
+    type: "positional",
+    description: "npm package name, optionally followed by @version or @dist-tag",
+    required: true
+  },
+  dir: {
+    type: "positional",
+    description: "Project directory (defaults to the current directory)",
+    required: false
+  },
+  export: {
+    type: "string",
+    description: "Named module export to use as the plugin function",
+    required: false
+  }
+};
+var parentArgs = {};
+function exitForUsage(error) {
+  if (error instanceof UsageError) {
+    console.error(error.message);
+    process.exit(error.exitCode);
+  }
+  throw error;
+}
+function rejectParentFlags(rawArgs) {
+  if (rawArgs[0] === "add" || rawArgs[0] === undefined || !rawArgs[0].startsWith("-")) {
+    return;
+  }
+  try {
+    rejectUnknownFlags(rawArgs, parentArgs, "plugin");
+  } catch (error) {
+    exitForUsage(error);
+  }
+}
+var add = defineCommand({
+  meta: {
+    name: "add",
+    description: "Download, verify, and vendor an npm markdown-it plugin"
+  },
+  args: pluginAddArgs,
+  async run({ args, rawArgs }) {
+    try {
+      rejectUnknownFlags(rawArgs, pluginAddArgs, "plugin add");
+      rejectExtraPositionals(args._, 2, "plugin add");
+    } catch (error) {
+      exitForUsage(error);
+    }
+    const projectDir = path.resolve(typeof args.dir === "string" && args.dir ? args.dir : process.cwd());
+    const packageSpec = String(args.package);
+    const exportName = typeof args.export === "string" ? args.export.trim() : undefined;
+    try {
+      try {
+        parseNpmPluginSpec(packageSpec);
+      } catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+      }
+      if (typeof args.export === "string" && !exportName) {
+        throw new UsageError("gutterpress plugin add: --export requires a non-empty name");
+      }
+      let projectInfo;
+      try {
+        projectInfo = await stat(projectDir);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          throw new UsageError(`Project directory does not exist: ${projectDir}`);
+        }
+        throw error;
+      }
+      if (!projectInfo.isDirectory()) {
+        throw new UsageError(`Project path is not a directory: ${projectDir}`);
+      }
+    } catch (error) {
+      exitForUsage(error);
+    }
+    try {
+      const installed = await addNpmPlugin(projectDir, packageSpec, exportName);
+      if (installed.version) {
+        console.log(`Installed ${installed.ref}@${installed.version}`);
+        console.log(`  project: ${projectDir}`);
+        console.log("  vendored under: plugins/npm");
+        console.log("  manifest: exact version pinned");
+        for (const warning of installed.warnings ?? [])
+          console.warn(`Warning: ${warning}`);
+      } else {
+        console.log(`Enabled bundled plugin ${installed.ref}`);
+        console.log(`  project: ${projectDir}`);
+      }
+    } catch (error) {
+      console.error(`Could not install plugin: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(EXIT_CODES.PIPELINE);
+    }
+  }
+});
+var plugin_default = defineCommand({
+  meta: {
+    name: "plugin",
+    description: "Manage project markdown-it plugins"
+  },
+  args: parentArgs,
+  setup({ rawArgs }) {
+    rejectParentFlags(rawArgs);
+  },
+  subCommands: { add }
+});
+export {
+  pluginAddArgs,
+  plugin_default as default
+};

package/dist/preflight-tg4mpz1h.js

@@ -0,0 +1,222 @@
+import {
+  executeValidation,
+  reportMissingTools
+} from "./cli-7ykx7pp0.js";
+import {
+  log
+} from "./cli-h7phg3ka.js";
+import {
+  EXIT_CODES,
+  UsageError,
+  rejectExtraPositionals,
+  rejectUnknownFlags
+} from "./cli-hvqjs342.js";
+import"./cli-5bxx0c4y.js";
+import"./cli-1tyj4bk3.js";
+import"./cli-yja077f6.js";
+import"./cli-37x76zdn.js";
+
+// src/commands/preflight.ts
+import { defineCommand } from "citty";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+function computeStatus(errors, warnings, missingTools, skippedRequired) {
+  if (errors > 0 || skippedRequired)
+    return "NO-GO";
+  if (warnings > 0 || missingTools > 0)
+    return "FIX";
+  return "GO";
+}
+function severityRank(severity) {
+  if (severity === "error")
+    return 0;
+  if (severity === "warning")
+    return 1;
+  return 2;
+}
+function buildRequiredChecks(execution) {
+  if (execution.profile !== "dtrpg")
+    return [];
+  const requiredIds = [
+    "pdf.structure.qpdf",
+    "pdf.print.pdfx-markers",
+    "pdf.print.pdfx-metadata",
+    "pdf.print.embedded-fonts"
+  ];
+  const skipped = new Set(execution.tools.skippedChecks);
+  const failed = new Set(execution.report.errors.map((item) => item.checkId));
+  const passed = new Set(execution.report.passed);
+  return requiredIds.map((id) => {
+    if (skipped.has(id))
+      return { id, status: "skipped" };
+    if (failed.has(id))
+      return { id, status: "fail" };
+    if (passed.has(id))
+      return { id, status: "pass" };
+    return { id, status: "fail" };
+  });
+}
+function buildPreflightPayload(execution) {
+  const sortedIssues = [...execution.report.results].sort((a, b) => {
+    const severityCmp = severityRank(a.severity) - severityRank(b.severity);
+    if (severityCmp !== 0)
+      return severityCmp;
+    const checkCmp = a.checkId.localeCompare(b.checkId);
+    if (checkCmp !== 0)
+      return checkCmp;
+    const fileCmp = (a.file ?? "").localeCompare(b.file ?? "");
+    if (fileCmp !== 0)
+      return fileCmp;
+    const lineCmp = (a.line ?? 0) - (b.line ?? 0);
+    if (lineCmp !== 0)
+      return lineCmp;
+    const colCmp = (a.column ?? 0) - (b.column ?? 0);
+    if (colCmp !== 0)
+      return colCmp;
+    return a.message.localeCompare(b.message);
+  }).map((item) => ({
+    checkId: item.checkId,
+    severity: item.severity,
+    message: item.message,
+    file: item.file,
+    line: item.line,
+    column: item.column
+  }));
+  const requiredChecks = buildRequiredChecks(execution);
+  const skippedRequired = requiredChecks.some((check) => check.status === "skipped");
+  return {
+    schemaVersion: 1,
+    profile: execution.profile ?? null,
+    status: computeStatus(execution.report.summary.errors, execution.report.summary.warnings, execution.tools.missing.length, skippedRequired),
+    pdf: execution.context.pdfPath ?? "",
+    summary: { ...execution.report.summary },
+    tools: {
+      missing: [...execution.tools.missing].sort((a, b) => a.localeCompare(b)),
+      skippedChecks: [...execution.tools.skippedChecks].sort((a, b) => a.localeCompare(b))
+    },
+    requiredChecks,
+    issues: sortedIssues
+  };
+}
+function toPreflightMarkdown(payload) {
+  const lines = [];
+  lines.push("# gutterpress preflight");
+  lines.push("");
+  lines.push(`- Status: **${payload.status}**`);
+  lines.push(`- Profile: ${payload.profile ?? "none"}`);
+  lines.push(`- PDF: ${payload.pdf}`);
+  lines.push(`- Summary: ${payload.summary.errors} error(s), ${payload.summary.warnings} warning(s), ${payload.summary.passed}/${payload.summary.total} checks passed`);
+  if (payload.tools.missing.length > 0) {
+    lines.push("");
+    lines.push("## Missing Tools");
+    for (const tool of payload.tools.missing) {
+      lines.push(`- ${tool}`);
+    }
+  }
+  if (payload.requiredChecks.length > 0) {
+    lines.push("");
+    lines.push("## Required Checks");
+    for (const check of payload.requiredChecks) {
+      lines.push(`- ${check.id}: ${check.status}`);
+    }
+  }
+  if (payload.issues.length > 0) {
+    lines.push("");
+    lines.push("## Issues");
+    for (const issue of payload.issues) {
+      lines.push(`- [${issue.severity}] ${issue.checkId}: ${issue.message}`);
+    }
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function defaultReportName(pdfPath) {
+  const ext = extname(pdfPath);
+  const base = ext ? basename(pdfPath, ext) : basename(pdfPath);
+  return `${base}.preflight`;
+}
+var preflightArgs = {
+  dir: {
+    type: "positional",
+    description: "Project directory (default: cwd). Sets the pre-build source directory unless --input is also given.",
+    required: false
+  },
+  pdf: {
+    type: "string",
+    description: "Path to the PDF file to preflight",
+    required: true
+  },
+  input: {
+    type: "string",
+    description: "Optional source directory for pre-build checks (overrides the positional directory)"
+  },
+  manifest: {
+    type: "string",
+    description: "Path to manifest.yaml"
+  },
+  profile: {
+    type: "string",
+    description: "Validation profile lock (currently: dtrpg)"
+  },
+  "report-dir": {
+    type: "string",
+    description: "Output directory for preflight reports"
+  },
+  name: {
+    type: "string",
+    description: "Base filename for report outputs"
+  }
+};
+var preflight_default = defineCommand({
+  meta: {
+    name: "preflight",
+    description: "Run deterministic print preflight for a built PDF"
+  },
+  args: preflightArgs,
+  async run({ args, rawArgs }) {
+    const positionalDir = typeof args.dir === "string" ? args.dir : undefined;
+    const inputFlag = typeof args.input === "string" ? args.input : undefined;
+    const input = inputFlag ?? positionalDir;
+    let execution;
+    try {
+      rejectUnknownFlags(rawArgs, preflightArgs, "preflight");
+      rejectExtraPositionals(args._, 1, "preflight");
+      execution = await executeValidation({
+        manifest: typeof args.manifest === "string" ? args.manifest : undefined,
+        pdf: typeof args.pdf === "string" ? args.pdf : undefined,
+        input,
+        phase: "post-build",
+        profile: typeof args.profile === "string" ? args.profile : undefined
+      });
+    } catch (error) {
+      log.error(error instanceof Error ? error.message : String(error));
+      process.exit(error instanceof UsageError ? error.exitCode : EXIT_CODES.USAGE);
+    }
+    if (!execution)
+      return;
+    reportMissingTools(execution.tools);
+    const payload = buildPreflightPayload(execution);
+    const pdfPath = execution.context.pdfPath;
+    const reportDir = resolve(typeof args["report-dir"] === "string" ? args["report-dir"] : dirname(pdfPath));
+    const baseName = typeof args.name === "string" && args.name.trim().length > 0 ? args.name.trim() : defaultReportName(pdfPath);
+    const jsonPath = join(reportDir, `${baseName}.json`);
+    const markdownPath = join(reportDir, `${baseName}.md`);
+    await mkdir(reportDir, { recursive: true });
+    await writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+    await writeFile(markdownPath, toPreflightMarkdown(payload), "utf8");
+    log.info(`Preflight status: ${payload.status}`);
+    log.info(`JSON report: ${jsonPath}`);
+    log.info(`Markdown report: ${markdownPath}`);
+    if (payload.status === "NO-GO") {
+      process.exit(EXIT_CODES.FINDINGS);
+    }
+  }
+});
+export {
+  toPreflightMarkdown,
+  preflightArgs,
+  preflight_default as default,
+  buildPreflightPayload
+};

package/dist/preview/file-watcher.d.ts

@@ -0,0 +1,174 @@
+/**
+ * File watcher setup and management for preview server
+ *
+ * Handles watching input files and triggering rebuilds on changes.
+ * Uses the simplified markdown pipeline (renderChapters from lib/markdown).
+ */
+import { type FSWatcher } from 'chokidar';
+import type { ServerState } from './server-context';
+import type { ResolvedPluginConfig } from '../schema/manifest.types';
+/**
+ * Whether the double-buffered preview shell is active. The historical env name
+ * is retained because users may already set it; chapter splicing is gone and
+ * every source change now performs a full-document pagination.
+ */
+export declare function incrementalPreviewEnabled(): boolean;
+/**
+ * Shared preview render path. renderChapters() does all Markdown, CSS, and
+ * Paged.js-slot work.
+ *
+ * Named `renderPreviewBook` (ARCH finding #53) to distinguish it from
+ * build-runner.ts's `renderBook` — same name, different module, and a
+ * genuinely different contract: this one is degrade-and-report (a plugin the
+ * author enabled but hasn't installed yet is skipped with a loud warning so
+ * the rest of the live preview still renders); build-runner.ts's is
+ * fail-fast, because a final artifact must never silently drop a plugin.
+ * Both preambles now share {@link loadPluginsWithCss}.
+ */
+export declare function renderPreviewBook(inputPath: string, config: {
+    title?: string;
+    styles?: string[];
+    plugins?: ResolvedPluginConfig[];
+}, opts: {
+    files: string[] | null;
+    wrapChapters: boolean;
+}): Promise<string>;
+/**
+ * Rewrite rendered book HTML for the live preview. Injects, in order:
+ *   1. pagedjs-interface.js — defines window.previewAPI for in-iframe controls
+ *   2. pagedjs-bridge.js    — postMessage bridge for cross-origin toolbar (desktop)
+ *   3. BREAK_INSIDE_HANDLER — polyfill for break-inside: avoid
+ *   4. Paged.js polyfill itself, served directly from the process-wide
+ *      embedded-assets dir by the HTTP server (see http-server.ts route
+ *      for /vendor/*). We no longer copy it into the per-project tempDir
+ *      because:
+ *        - The polyfill is 904 KB and copying it per open is wasted IO
+ *          (one of the worst-case Defender scan targets on Windows).
+ *        - The per-process extracted copy is identical across opens so
+ *          serving it from a stable disk path lets the OS file-cache
+ *          and Defender hash-cache stay warm across sessions.
+ *
+ * PAGINATION FIDELITY: this injects NO page-break rule. It used to add
+ * `<style>.gutterpress-chapter{break-before:page}</style>` whenever the incremental
+ * preview was on (i.e. by default), which started EVERY source file on a new
+ * page in the live view. `gutterpress build` emits no such rule — assembleBookHtml
+ * in lib/markdown/assemble.ts concatenates source files flat into <body> and
+ * breaks only where project CSS or a markdown-it-paged marker says to — so any
+ * project that splits one chapter across several source files previewed with
+ * different page boundaries than the PDF it built. Preview and build now take
+ * their breaks from exactly the same rules.
+ *
+ * Chapter identity is attached to existing source-mapped blocks. No wrapper or
+ * preview-only CSS is emitted, so selectors see exactly the same document tree
+ * as the build.
+ */
+export declare function injectPreviewScripts(html: string): string;
+/**
+ * Generate HTML from markdown and write book.html to the temp directory.
+ * The desktop's iframe loads `book.html` via a relative URL — same name in
+ * dev and in published static-site builds.
+ *
+ * Empty `inputPath` writes a static placeholder — the desktop app (packages/desktop)
+ * supplies a real path via its own folder picker.
+ */
+export declare function generateAndWriteHtml(inputPath: string, tempDir: string, config: {
+    title?: string;
+    styles?: string[];
+    source?: {
+        files?: string[] | null;
+    };
+    plugins?: ResolvedPluginConfig[];
+}): Promise<void>;
+/**
+ * Chokidar 5's `ignored` matcher (regex or function) is tested against the
+ * fully-qualified, forward-slash-normalized ABSOLUTE path — never a path
+ * relative to whatever root was passed to `watch()` (see chokidar's internal
+ * `matchPatterns`/`normalizePath`, which run before any matcher, function or
+ * regex, ever sees the string). The previous `ignored: /(^|[\/\\])\../`
+ * therefore matched a dot segment ANYWHERE in that absolute path — including
+ * every ANCESTOR directory of the project, not just the project's own dot
+ * files/dirs. A project rooted under a dot-prefixed parent (e.g.
+ * `~/.local/share/gutterpress/books/mybook`, or any `~/.config/...` tree) had
+ * every single path rejected by this rule, which silently disabled the
+ * watcher entirely — no error, just a preview that never picked up an edit.
+ *
+ * The fix: strip the (normalized) watch root off the front of the path
+ * first, and apply the dotfile rule only to what's left — i.e. to the
+ * PROJECT's own files/dirs, regardless of which ancestor directories the
+ * project itself happens to live under.
+ */
+export declare function isDotPathUnderRoot(candidatePath: string, root: string): boolean;
+/**
+ * Whether the watcher should ignore a path.
+ *
+ * IN-PROJECT paths get the dotfile rule ({@link isDotPathUnderRoot}) — a
+ * project's own `.git/`, `.DS_Store`, editor swap files, and so on are noise.
+ *
+ * A path OUTSIDE the project is only ever seen because it is a DECLARED
+ * external dependency the manifest named explicitly (see
+ * {@link externalWatchTargets}); it is never ignored. Running the dotfile rule
+ * on it would test every ANCESTOR segment of its absolute path — so a shared
+ * foundation checked out under, say, `~/.local/share/books/shared/` would be
+ * silently dropped, which is the exact failure mode the in-project rule was
+ * rewritten to avoid.
+ */
+export declare function isIgnoredWatchPath(candidatePath: string, projectRoot: string): boolean;
+/**
+ * External watcher roots may be broader than one dependency when a declared
+ * file or its parent directory does not exist yet. Traverse only paths that are
+ * either a desired file or one of its ancestors; this keeps a nearest-existing
+ * ancestor watch from scanning unrelated sibling trees such as `.git/`.
+ */
+export declare function isExternalWatchCandidate(candidatePath: string, targets: Iterable<string>): boolean;
+/** Directories chokidar must subscribe to for exact external file targets. */
+export declare function externalWatchRoots(targets: Iterable<string>): Promise<string[]>;
+/**
+ * Everything the book reads from OUTSIDE its own folder — absolute paths,
+ * deduped. The project watch root covers in-book files; this is what it can't
+ * see.
+ *
+ * A multi-book repository keeps its shared foundation next to the books
+ * (`shared/styles/publisher-components.css`, `shared/plugins/components.js`)
+ * and each book's manifest points at it directly: a `styles:` entry is a path
+ * to READ (asset-inline.ts inlines it; nothing is staged or copied) and an
+ * authored plugin `path:` resolves against the manifest directory. Both may sit
+ * above the book root.
+ *
+ * The stylesheet side is the DEPENDENCY CLOSURE, not just the declared entry —
+ * `collectStyleDependencies` follows each active stylesheet's `@import` chain
+ * and every local `url()` it references. A shared theme's
+ * `url("../../fonts/Publisher.woff2")` is a file a design tool can replace
+ * without touching one line of CSS; watching only `theme.css` would leave the
+ * preview stale after that swap with nothing downstream to correct it. The
+ * closure is computed from ALL active stylesheets, including in-book ones,
+ * because a local stylesheet can reference a shared font just as easily — only
+ * the results that land outside the book are added here.
+ *
+ * Watching is per-FILE, never per-directory, so the set stays exact and cannot
+ * accidentally pull a large sibling tree into the watcher.
+ */
+export declare function externalWatchTargets(projectDir: string, config: {
+    styles?: string[];
+    plugins?: ResolvedPluginConfig[];
+}): Promise<string[]>;
+/**
+ * Create and configure a file watcher for the project's input directory plus
+ * the book's declared external dependencies (see {@link externalWatchTargets}).
+ *
+ * Nothing is mirrored anywhere: the old external-asset-root watching (a sibling
+ * `../_shared` directory copied under its own name into the temp dir) went away
+ * with `copyAssets` and the manifest's `source.assets` field it depended on.
+ * The project is served straight from disk and stylesheets are inlined at
+ * render time, so an external dependency needs watching, not staging.
+ */
+export declare function createFileWatcher(state: ServerState): FSWatcher;
+/**
+ * Start file watching if not disabled via options. No-input mode skips the
+ * watcher entirely (nothing to watch yet) — restartPreview wires up a
+ * watcher once the user picks a directory through the desktop.
+ */
+export declare function startFileWatcher(state: ServerState): void;
+/**
+ * Stop the file watcher and clean up resources
+ */
+export declare function stopFileWatcher(state: ServerState): Promise<void>;

package/dist/preview/http-server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Node.js-compatible preview HTTP server with WebSocket-based live reload.
+ *
+ * Uses node:http + the `ws` package in place of Bun.serve so this module
+ * runs under both Bun (dev / compiled binary) and Node.js (Electron in-process).
+ *
+ * This module deliberately avoids any bundler runtime (vite/rollup/esbuild)
+ * — see ADR `docs/adr/0001-no-bundlers-at-runtime.md`.
+ */
+import type { ServerState } from './server-context.ts';
+/**
+ * Public handle for the running preview server.
+ */
+export interface PreviewServer {
+    /** Port the server is listening on. */
+    port: number;
+    /** Stop the server and close all connections. */
+    close(): Promise<void>;
+    /**
+     * Broadcast a `{ type: "full-reload" }` message to every connected HMR
+     * client. Safe to call after `close()` (no-op).
+     */
+    broadcastReload(): void;
+}
+export declare function isPortAvailable(port: number, host?: string): Promise<boolean>;
+/**
+ * Find the next available port starting from `startPort`.
+ *
+ * @throws {UsageError} If the start port itself is invalid.
+ * @throws {BuildError} If valid ports are exhausted or the host cannot bind.
+ */
+export declare function findAvailablePort(startPort: number, host?: string): Promise<number>;
+/**
+ * Create and start a preview HTTP+WebSocket server.
+ *
+ * `book.html` — the one file gutterpress generates — is served from
+ * `state.tempDir`. Everything else a served page can ask for (an `<img src>`
+ * at its authored project-relative path, or any other project file) is
+ * served DIRECTLY from `state.currentInputPath`, the real project directory,
+ * not a copy of it — see lifecycle.ts's `initializePreviewDirectories` for
+ * why. This is what makes preview asset resolution identical to the build's
+ * BY CONSTRUCTION: both resolve a reference against the same real project
+ * tree, so a path that works in one works in the other.
+ */
+export declare function createPreviewServer(state: ServerState, port: number): Promise<PreviewServer>;