npm - @markbrutx/promptbook-viewer - Versions diffs - 0.1.0 - Mend

@markbrutx/promptbook-viewer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/LICENSE +21 -0
package/README.md +38 -0
package/dist/index.d.ts +6 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +3 -0
package/dist/index.js.map +1 -0
package/dist/server/annotations.d.ts +30 -0
package/dist/server/annotations.d.ts.map +1 -0
package/dist/server/annotations.js +62 -0
package/dist/server/annotations.js.map +1 -0
package/dist/server/api.d.ts +16 -0
package/dist/server/api.d.ts.map +1 -0
package/dist/server/api.js +134 -0
package/dist/server/api.js.map +1 -0
package/dist/server/book-source.d.ts +20 -0
package/dist/server/book-source.d.ts.map +1 -0
package/dist/server/book-source.js +32 -0
package/dist/server/book-source.js.map +1 -0
package/dist/server/responses.d.ts +12 -0
package/dist/server/responses.d.ts.map +1 -0
package/dist/server/responses.js +106 -0
package/dist/server/responses.js.map +1 -0
package/dist/server/segments.d.ts +12 -0
package/dist/server/segments.d.ts.map +1 -0
package/dist/server/segments.js +24 -0
package/dist/server/segments.js.map +1 -0
package/dist/server/server.d.ts +24 -0
package/dist/server/server.d.ts.map +1 -0
package/dist/server/server.js +71 -0
package/dist/server/server.js.map +1 -0
package/dist/server/static.d.ts +8 -0
package/dist/server/static.d.ts.map +1 -0
package/dist/server/static.js +55 -0
package/dist/server/static.js.map +1 -0
package/dist/server/used-in.d.ts +9 -0
package/dist/server/used-in.d.ts.map +1 -0
package/dist/server/used-in.js +19 -0
package/dist/server/used-in.js.map +1 -0
package/dist/shared/types.d.ts +113 -0
package/dist/shared/types.d.ts.map +1 -0
package/dist/shared/types.js +2 -0
package/dist/shared/types.js.map +1 -0
package/dist/web/assets/index-B2Wxtb-f.css +1 -0
package/dist/web/assets/index-C8f_6lr_.js +51 -0
package/dist/web/index.html +13 -0
package/package.json +47 -0
package/src/index.ts +19 -0
package/src/server/annotations.ts +96 -0
package/src/server/api.ts +164 -0
package/src/server/book-source.ts +54 -0
package/src/server/responses.ts +127 -0
package/src/server/segments.ts +26 -0
package/src/server/server.ts +96 -0
package/src/server/static.ts +60 -0
package/src/server/used-in.ts +23 -0
package/src/shared/types.ts +137 -0
package/src/web/App.tsx +307 -0
package/src/web/annotations.ts +58 -0
package/src/web/api.ts +44 -0
package/src/web/colors.ts +21 -0
package/src/web/components/Addons.tsx +109 -0
package/src/web/components/Canvas.tsx +180 -0
package/src/web/components/CodePromptView.tsx +87 -0
package/src/web/components/Controls.tsx +71 -0
package/src/web/components/Diff.tsx +30 -0
package/src/web/components/FragmentView.tsx +54 -0
package/src/web/components/Sidebar.tsx +178 -0
package/src/web/diff.ts +51 -0
package/src/web/env.d.ts +3 -0
package/src/web/format.ts +8 -0
package/src/web/index.html +12 -0
package/src/web/main.tsx +15 -0
package/src/web/selection.ts +5 -0
package/src/web/styles.css +484 -0
package/src/web/tree.ts +134 -0
package/src/web/types.ts +17 -0

package/dist/web/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>promptbook viewer</title>
+    <script type="module" crossorigin src="/assets/index-C8f_6lr_.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B2Wxtb-f.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,47 @@
+{
+  "name": "@markbrutx/promptbook-viewer",
+  "version": "0.1.0",
+  "description": "Storybook-for-prompts: a local web app that renders a prompts folder via @markbrutx/promptbook-core.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json && vite build",
+    "typecheck": "tsgo --noEmit -p tsconfig.json && tsgo --noEmit -p tsconfig.web.json",
+    "test": "vitest --run",
+    "check": "biome check ."
+  },
+  "dependencies": {
+    "@markbrutx/promptbook-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/node": "^20.14.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@typescript/native-preview": "latest",
+    "@vitejs/plugin-react": "^4.7.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.6"
+  }
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,19 @@
+export type { AnnotateInput, AnnotationStore } from "./server/annotations.js";
+export { createAnnotationStore } from "./server/annotations.js";
+export type { Viewer, ViewerOptions } from "./server/server.js";
+export { startViewer } from "./server/server.js";
+export type {
+  AnnotateRequest,
+  Annotation,
+  AnnotationsResponse,
+  BookResponse,
+  CompositionSummary,
+  FragmentSummary,
+  LintResponse,
+  ResolveResponse,
+  RuleSummary,
+  Segment,
+  UsedInReference,
+  UsedInResponse,
+  VariantSummary,
+} from "./shared/types.js";

package/src/server/annotations.ts ADDED Viewed

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Annotation, AnnotationAnchor, AnnotationTarget, Context } from "@markbrutx/promptbook-core";
+import {
+  ANNOTATION_QUEUE_DIR,
+  ANNOTATION_QUEUE_FILE,
+  parseInbox,
+  serializeAnnotationLine,
+  serializeInbox,
+} from "@markbrutx/promptbook-core";
+/** The flat body the viewer posts; the store expands it into an {@link Annotation}. */
+export interface AnnotateInput {
+  /** Composition the variant was assembled from (omit for a fragment target). */
+  prompt?: string;
+  /** Context the variant was resolved under (kept with `prompt`). */
+  context?: Context;
+  fragmentId: string;
+  anchorText: string;
+  comment: string;
+  offset?: number;
+  /** Source file of the fragment, when annotating a fragment directly. */
+  sourceFile?: string;
+}
+/** The append-safe queue under `<promptsDir>/.annotations/inbox.jsonl`. */
+export interface AnnotationStore {
+  /** Append a new open annotation and return it. */
+  append(input: AnnotateInput): Promise<Annotation>;
+  /** Open annotations in queue order (oldest first). */
+  list(): Promise<Annotation[]>;
+  /** Remove one annotation by id; resolves to whether it existed. */
+  remove(id: string): Promise<boolean>;
+}
+/** Expand the posted body into a full annotation (id + timestamp added here). */
+function buildAnnotation(input: AnnotateInput): Annotation {
+  const target: AnnotationTarget =
+    input.prompt !== undefined
+      ? { prompt: input.prompt, context: input.context ?? {} }
+      : { fragmentId: input.fragmentId, ...(input.sourceFile ? { sourceFile: input.sourceFile } : {}) };
+  const anchor: AnnotationAnchor = {
+    fragmentId: input.fragmentId,
+    anchorText: input.anchorText,
+    ...(input.offset !== undefined ? { offset: input.offset } : {}),
+  };
+  return {
+    id: randomUUID(),
+    createdAt: new Date().toISOString(),
+    target,
+    anchor,
+    comment: input.comment,
+    status: "open",
+  };
+}
+/**
+ * File-backed annotation queue. Appends are line-atomic (one JSONL line);
+ * removals rewrite the file. A missing queue simply reads as empty. This is the
+ * viewer's only write surface — `@markbrutx/promptbook-core` stays read-only.
+ */
+export function createAnnotationStore(promptsDir: string): AnnotationStore {
+  const dir = join(promptsDir, ANNOTATION_QUEUE_DIR);
+  const file = join(dir, ANNOTATION_QUEUE_FILE);
+  const readAll = async (): Promise<Annotation[]> => {
+    try {
+      return parseInbox(await readFile(file, "utf8"));
+    } catch {
+      return [];
+    }
+  };
+  return {
+    async append(input) {
+      const annotation = buildAnnotation(input);
+      await mkdir(dir, { recursive: true });
+      await appendFile(file, serializeAnnotationLine(annotation));
+      return annotation;
+    },
+    async list() {
+      return (await readAll()).filter((annotation) => annotation.status === "open");
+    },
+    async remove(id) {
+      const all = await readAll();
+      const next = all.filter((annotation) => annotation.id !== id);
+      if (next.length === all.length) {
+        return false;
+      }
+      // The dir/file already exist (an annotation was present), so no mkdir.
+      await writeFile(file, serializeInbox(next));
+      return true;
+    },
+  };
+}

package/src/server/api.ts ADDED Viewed

@@ -0,0 +1,164 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Context } from "@markbrutx/promptbook-core";
+import type { AnnotateRequest, ResolveRequest } from "../shared/types.js";
+import { type AnnotateInput, createAnnotationStore } from "./annotations.js";
+import type { BookSource } from "./book-source.js";
+import {
+  buildBookResponse,
+  buildLintResponse,
+  buildResolveResponse,
+  buildUsedInResponse,
+} from "./responses.js";
+import { serveStatic } from "./static.js";
+export interface RequestHandlerOptions {
+  source: BookSource;
+  promptsDir: string;
+  /** Directory of the built web bundle (dist/web). */
+  webRoot: string;
+}
+/** A request handler plus the hook the folder watcher uses to push reloads. */
+export interface RequestHandler {
+  handle(req: IncomingMessage, res: ServerResponse): void;
+  /** Invalidate the cached book and notify connected clients to refetch. */
+  notifyReload(): void;
+}
+function sendJson(res: ServerResponse, status: number, payload: unknown): void {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(body);
+}
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (raw === "") {
+    return {};
+  }
+  return JSON.parse(raw);
+}
+function asResolveRequest(body: unknown): { prompt: string; context: Context } {
+  const data = (body ?? {}) as Partial<ResolveRequest>;
+  if (typeof data.prompt !== "string" || data.prompt === "") {
+    throw new Error('request body must include a "prompt" name');
+  }
+  return { prompt: data.prompt, context: data.context ?? {} };
+}
+function asAnnotateRequest(body: unknown): AnnotateInput {
+  const data = (body ?? {}) as Partial<AnnotateRequest>;
+  if (typeof data.fragmentId !== "string" || data.fragmentId === "") {
+    throw new Error('request body must include a "fragmentId"');
+  }
+  if (typeof data.anchorText !== "string" || data.anchorText === "") {
+    throw new Error('request body must include "anchorText"');
+  }
+  if (typeof data.comment !== "string" || data.comment.trim() === "") {
+    throw new Error('request body must include a non-empty "comment"');
+  }
+  const input: AnnotateInput = {
+    fragmentId: data.fragmentId,
+    anchorText: data.anchorText,
+    comment: data.comment,
+  };
+  if (typeof data.prompt === "string" && data.prompt !== "") {
+    input.prompt = data.prompt;
+    input.context = data.context ?? {};
+  }
+  if (typeof data.offset === "number") {
+    input.offset = data.offset;
+  }
+  if (typeof data.sourceFile === "string") {
+    input.sourceFile = data.sourceFile;
+  }
+  return input;
+}
+export function createRequestHandler(options: RequestHandlerOptions): RequestHandler {
+  const { source, promptsDir, webRoot } = options;
+  const sseClients = new Set<ServerResponse>();
+  const annotations = createAnnotationStore(promptsDir);
+  const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+    try {
+      if (path === "/api/book" && method === "GET") {
+        sendJson(res, 200, buildBookResponse(await source.get(), promptsDir));
+        return;
+      }
+      if (path === "/api/resolve" && method === "POST") {
+        const { prompt, context } = asResolveRequest(await readJsonBody(req));
+        sendJson(res, 200, buildResolveResponse(await source.get(), prompt, context));
+        return;
+      }
+      if (path === "/api/lint" && method === "POST") {
+        const { prompt, context } = asResolveRequest(await readJsonBody(req));
+        sendJson(res, 200, buildLintResponse(await source.get(), prompt, context));
+        return;
+      }
+      if (path.startsWith("/api/used-in/") && method === "GET") {
+        const id = decodeURIComponent(path.slice("/api/used-in/".length));
+        sendJson(res, 200, buildUsedInResponse(await source.get(), id));
+        return;
+      }
+      if (path === "/api/annotate" && method === "POST") {
+        const annotation = await annotations.append(asAnnotateRequest(await readJsonBody(req)));
+        sendJson(res, 200, annotation);
+        return;
+      }
+      if (path === "/api/annotations" && method === "GET") {
+        sendJson(res, 200, { annotations: await annotations.list() });
+        return;
+      }
+      if (path.startsWith("/api/annotations/") && method === "DELETE") {
+        const id = decodeURIComponent(path.slice("/api/annotations/".length));
+        const removed = await annotations.remove(id);
+        sendJson(res, removed ? 200 : 404, { id, removed });
+        return;
+      }
+      if (path === "/api/events" && method === "GET") {
+        addSseClient(res);
+        return;
+      }
+      if (path.startsWith("/api/")) {
+        sendJson(res, 404, { error: `unknown route ${method} ${path}` });
+        return;
+      }
+      await serveStatic(res, webRoot, path);
+    } catch (error) {
+      sendJson(res, 400, { error: (error as Error).message });
+    }
+  };
+  function addSseClient(res: ServerResponse): void {
+    res.writeHead(200, {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      connection: "keep-alive",
+    });
+    res.write(": connected\n\n");
+    sseClients.add(res);
+    res.on("close", () => sseClients.delete(res));
+  }
+  return {
+    handle(req, res) {
+      void handle(req, res);
+    },
+    notifyReload() {
+      source.invalidate();
+      for (const client of sseClients) {
+        client.write("event: reload\ndata: {}\n\n");
+      }
+    },
+  };
+}

package/src/server/book-source.ts ADDED Viewed

@@ -0,0 +1,54 @@
+import type { Fixture, FsAdapter, PromptBook } from "@markbrutx/promptbook-core";
+import { loadFixtures, loadPrompts } from "@markbrutx/promptbook-core";
+/** A loaded prompts folder plus the fixtures that supply named variants. */
+export interface LoadedFolder {
+  book: PromptBook;
+  fixtures: Fixture[];
+}
+/**
+ * Caches the loaded folder and reloads lazily after {@link invalidate}. The
+ * server wires a folder watcher to `invalidate` for hot-reload; tests can call
+ * it directly. Reads are serialized so a burst of requests during a reload
+ * shares one load.
+ */
+export interface BookSource {
+  /** Current folder contents, reloading first if it was invalidated. */
+  get(): Promise<LoadedFolder>;
+  /** Mark the cache stale; the next {@link get} reloads from disk. */
+  invalidate(): void;
+}
+/** Fixtures are optional: a folder without a `fixtures/` dir simply has none. */
+async function safeLoadFixtures(promptsDir: string, fs?: FsAdapter): Promise<Fixture[]> {
+  try {
+    return await loadFixtures(promptsDir, fs);
+  } catch {
+    return [];
+  }
+}
+export function createBookSource(promptsDir: string, fs?: FsAdapter): BookSource {
+  let cached: Promise<LoadedFolder> | undefined;
+  const load = async (): Promise<LoadedFolder> => {
+    const [book, fixtures] = await Promise.all([
+      loadPrompts(promptsDir, fs),
+      safeLoadFixtures(promptsDir, fs),
+    ]);
+    return { book, fixtures };
+  };
+  return {
+    get() {
+      if (cached === undefined) {
+        cached = load();
+      }
+      return cached;
+    },
+    invalidate() {
+      cached = undefined;
+    },
+  };
+}

package/src/server/responses.ts ADDED Viewed

@@ -0,0 +1,127 @@
+import { relative, sep } from "node:path";
+import type { CodePrompt, Composition, Context, Rule } from "@markbrutx/promptbook-core";
+import { estimateTokensByChars, lint, resolveBook } from "@markbrutx/promptbook-core";
+import type {
+  BookResponse,
+  CodePromptSummary,
+  CompositionSummary,
+  LintResponse,
+  ResolveResponse,
+  RuleSummary,
+  UsedInResponse,
+  VariantSummary,
+} from "../shared/types.js";
+import type { LoadedFolder } from "./book-source.js";
+import { deriveSegments } from "./segments.js";
+import { usedIn } from "./used-in.js";
+/** Path relative to the prompts folder, normalized to forward slashes. */
+function relativeSource(promptsDir: string, sourceFile: string): string {
+  const rel = relative(promptsDir, sourceFile);
+  return (rel === "" ? sourceFile : rel).split(sep).join("/");
+}
+/** Drop undefined action fields so the wire shape stays minimal. */
+function summarizeRule(rule: Rule): RuleSummary {
+  const summary: RuleSummary = { index: rule.index, when: rule.when, action: rule.action };
+  if (rule.add !== undefined) summary.add = rule.add;
+  if (rule.after !== undefined) summary.after = rule.after;
+  if (rule.replace !== undefined) summary.replace = rule.replace;
+  if (rule.forbid !== undefined) summary.forbid = rule.forbid;
+  if (rule.order !== undefined) summary.order = rule.order;
+  return summary;
+}
+/** Group fixtures by the composition they target, for variant lookup. */
+function variantsByPrompt(folder: LoadedFolder): Map<string, VariantSummary[]> {
+  const byPrompt = new Map<string, VariantSummary[]>();
+  for (const fixture of folder.fixtures) {
+    const list = byPrompt.get(fixture.prompt) ?? [];
+    list.push({ name: fixture.name, context: fixture.context ?? {} });
+    byPrompt.set(fixture.prompt, list);
+  }
+  for (const list of byPrompt.values()) {
+    list.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  return byPrompt;
+}
+/** Project a code-prompt to the wire shape, relativizing its manifest path. */
+function summarizeCodePrompt(promptsDir: string, codePrompt: CodePrompt): CodePromptSummary {
+  const summary: CodePromptSummary = {
+    name: codePrompt.name,
+    samples: codePrompt.samples.map((s) => ({
+      label: s.label,
+      ...(s.context !== undefined ? { context: s.context } : {}),
+      output: s.output,
+    })),
+    sourceFile: relativeSource(promptsDir, codePrompt.sourceFile),
+  };
+  if (codePrompt.description !== undefined) summary.description = codePrompt.description;
+  return summary;
+}
+function summarizeComposition(
+  variants: VariantSummary[],
+  promptsDir: string,
+  c: Composition,
+): CompositionSummary {
+  const summary: CompositionSummary = {
+    name: c.name,
+    base: c.base,
+    rules: c.rules.map(summarizeRule),
+    sourceFile: relativeSource(promptsDir, c.sourceFile),
+    variants,
+  };
+  if (c.order !== undefined) summary.order = c.order;
+  return summary;
+}
+/** Build the `GET /api/book` payload: compositions + fragments + warnings. */
+export function buildBookResponse(folder: LoadedFolder, promptsDir: string): BookResponse {
+  const { book } = folder;
+  const variants = variantsByPrompt(folder);
+  const compositions = [...book.compositions.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => summarizeComposition(variants.get(c.name) ?? [], promptsDir, c));
+  const codePrompts = [...book.codePrompts.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => summarizeCodePrompt(promptsDir, c));
+  const fragments = [...book.fragments.values()]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((f) => ({
+      id: f.id,
+      ...(f.kind !== undefined ? { kind: f.kind } : {}),
+      tags: f.tags ?? [],
+      body: f.body,
+      sourceFile: relativeSource(promptsDir, f.sourceFile),
+    }));
+  return { compositions, codePrompts, fragments, warnings: book.warnings };
+}
+/** Resolve a variant and attach the colored segments. Throws on unknown prompt. */
+export function buildResolveResponse(
+  folder: LoadedFolder,
+  prompt: string,
+  context: Context,
+): ResolveResponse {
+  const { text, trace } = resolveBook(folder.book, prompt, context);
+  return { text, trace, segments: deriveSegments(folder.book, trace.finalOrder, context) };
+}
+/** Lint a resolved variant and estimate its token count. Throws on unknown prompt. */
+export function buildLintResponse(folder: LoadedFolder, prompt: string, context: Context): LintResponse {
+  const result = resolveBook(folder.book, prompt, context);
+  const report = lint({ book: folder.book, result });
+  return {
+    findings: report.findings,
+    errorCount: report.errorCount,
+    warningCount: report.warningCount,
+    tokens: estimateTokensByChars(result.text),
+  };
+}
+/** List the compositions/rules that reference a fragment id. */
+export function buildUsedInResponse(folder: LoadedFolder, fragmentId: string): UsedInResponse {
+  return { fragmentId, references: usedIn(folder.book, fragmentId) };
+}

package/src/server/segments.ts ADDED Viewed

@@ -0,0 +1,26 @@
+import type { Context, PromptBook } from "@markbrutx/promptbook-core";
+import { interpolate } from "@markbrutx/promptbook-core";
+import type { Segment } from "../shared/types.js";
+/**
+ * Re-derive the per-fragment slices of an assembled prompt for coloring.
+ *
+ * `resolveBook` joins the interpolated bodies of `trace.finalOrder` with
+ * `"\n\n"`. Running the same interpolation over the same ids reproduces those
+ * parts exactly, so `segments.map(s => s.text).join("\n\n")` is byte-identical
+ * to the resolved `text`. This is asserted in the tests.
+ */
+export function deriveSegments(book: PromptBook, finalOrder: string[], context: Context): Segment[] {
+  const segments: Segment[] = [];
+  for (const fragmentId of finalOrder) {
+    const fragment = book.fragments.get(fragmentId);
+    if (fragment === undefined) {
+      continue;
+    }
+    segments.push({
+      fragmentId,
+      text: interpolate(fragment.body, context, () => {}),
+    });
+  }
+  return segments;
+}

package/src/server/server.ts ADDED Viewed

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { type FSWatcher, watch } from "node:fs";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import type { FsAdapter } from "@markbrutx/promptbook-core";
+import { createRequestHandler } from "./api.js";
+import { createBookSource } from "./book-source.js";
+export interface ViewerOptions {
+  /** Folder containing `fragments/`, `rules/` and optional `fixtures/`. */
+  promptsDir: string;
+  /** Port to listen on; 0 (default) picks a free port. */
+  port?: number;
+  /** Open the URL in the default browser once listening. Default false. */
+  open?: boolean;
+  /** Filesystem adapter forwarded to the core loader (defaults to Node fs). */
+  fs?: FsAdapter;
+}
+/** A running viewer: its URL, the bound port, and a shutdown hook. */
+export interface Viewer {
+  url: string;
+  port: number;
+  close(): Promise<void>;
+}
+/** Best-effort: open `url` in the OS default browser; never throws. */
+function openBrowser(url: string): void {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(command, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // opening a browser is a convenience, not a requirement
+  }
+}
+/** Watch the prompts folder and call `onChange` (debounced) on any edit. */
+function watchFolder(promptsDir: string, onChange: () => void): FSWatcher | undefined {
+  try {
+    let timer: NodeJS.Timeout | undefined;
+    const watcher = watch(promptsDir, { recursive: true }, () => {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(onChange, 50);
+    });
+    watcher.on("error", () => {});
+    return watcher;
+  } catch {
+    return undefined;
+  }
+}
+/**
+ * Start the viewer server: serves the built web bundle and the `/api/*` routes
+ * over a prompts folder, hot-reloading on folder edits. Render-only; no model
+ * calls. Resolves once the server is listening.
+ */
+export async function startViewer(options: ViewerOptions): Promise<Viewer> {
+  const { promptsDir, port = 0, open = false, fs } = options;
+  const webRoot = fileURLToPath(new URL("../web", import.meta.url));
+  const source = createBookSource(promptsDir, fs);
+  const handler = createRequestHandler({ source, promptsDir, webRoot });
+  const server = createServer((req, res) => handler.handle(req, res));
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  const boundPort = typeof address === "object" && address !== null ? address.port : port;
+  const url = `http://localhost:${boundPort}`;
+  const watcher = watchFolder(promptsDir, () => handler.notifyReload());
+  if (open) {
+    openBrowser(url);
+  }
+  return {
+    url,
+    port: boundPort,
+    close() {
+      watcher?.close();
+      return new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}