ketatlas 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0
+
+- Add an opt-in two-port native renderer contract: KetAtlas serves the viewer while the declared React, Vue, KetJS, or other framework server owns screen HTML, assets, and same-origin behavior.
+- Add `atlas.renderer.json`, its public schema, command-array validation, readiness checks, predictable renderer shutdown, and route-aware static audit.
+- Add `screenBaseURL` to the browser API so screen routes can resolve on a different origin while external references continue to resolve beside `atlas.json`.
+- Require the bundled agent skill to use the product's real framework and design-system components, share presenters/styles across atlases, and keep business data outside presentation components.
+
+## 0.3.0
+
+- Standardize discoverable projects as `<name>.ketatlas/atlas.json` bundles, add `discover`, accept bundle directories in Atlas commands, and teach the bundled skill to backfill legacy projects safely.
+- Accelerate drag, wheel, keyboard and pinch camera controls while preserving pointer-anchored zoom.
+- Require agents to confirm a design system before visual mockup work, with Auto defaulting to Két Design System and explicit Carbon, Primer, Fluent 2, no-system, and custom-source options.
+
 ## 0.2.5
 
 - Show separate Checks and Implemented percentage badges per workflow. Implemented includes Verified screens; project verification remains separate on the top bar. Display a dash for Checks when no checklist is recorded.

package/README.md

@@ -1,14 +1,17 @@
 # KetAtlas
 
-**Scaffold, serve, and audit interactive HTML workflow maps.**
+**Scaffold, serve, and audit interactive framework-native workflow maps.**
 
-Turn a JSON file and your existing HTML screens into a canvas you can drag, zoom, and explore. Connect screens with labelled arrows, model decisions and recovery paths, and open the real HTML to try a step. The same tool supports mobile screens, web pages, and processes with no screens at all.
+Turn a JSON file and screens from your existing HTML, React, Vue, KetJS, or other framework into a canvas you can drag, zoom, and explore. Connect screens with labelled arrows, model decisions and recovery paths, and open the real rendered page to try a step. The same tool supports mobile screens, web pages, and processes with no screens at all.
 
-KetAtlas has an English UI, zero runtime npm dependencies, and no build step. Node.js **22+** is needed for the CLI. Viewers use native ES modules and run on an HTTP server.
+KetAtlas has an English UI and zero runtime npm dependencies. Node.js **22+** is needed for the CLI. Static projects need no build step. Framework-native projects reuse their product's own server and dependencies; KetAtlas supervises it on a separate localhost port.
 
 ## Demo
 
-See a mobile workflow map in action: explore connected screens and try the HTML prototype.
+Open the live map at **[atlas.ketsuite.com](https://atlas.ketsuite.com)**: drag, zoom, follow the
+labelled arrows, and open a real HTML prototype from any screen. Nothing to install.
+
+The same map recorded as a video, for a quick look:
 
 https://github.com/user-attachments/assets/13f24fc8-7b8e-4bda-9e02-364c120ee163
 
@@ -17,25 +20,26 @@ https://github.com/user-attachments/assets/13f24fc8-7b8e-4bda-9e02-364c120ee163
 [KetAtlas is available on npm](https://www.npmjs.com/package/ketatlas). Use Node.js 22+ and run it from any directory:
 
 ```sh
-npx --yes ketatlas@0.2.5 scaffold my-atlas --template web
-npx --yes ketatlas@0.2.5 serve my-atlas/atlas.json
-npx --yes ketatlas@0.2.5 audit my-atlas/atlas.json --strict
+npx --yes ketatlas scaffold my-atlas.ketatlas --template web
+npx --yes ketatlas discover . --json
+npx --yes ketatlas serve my-atlas.ketatlas
+npx --yes ketatlas audit my-atlas.ketatlas --strict
 ```
 
 Or install the CLI once for your user account:
 
 ```sh
-npm install --global ketatlas@0.2.5
-ketatlas scaffold my-atlas
-ketatlas serve my-atlas/atlas.json
-ketatlas audit my-atlas/atlas.json --strict
+npm install --global ketatlas
+ketatlas scaffold my-atlas.ketatlas
+ketatlas serve my-atlas.ketatlas
+ketatlas audit my-atlas.ketatlas --strict
 ```
 
-The consumer folder contains `atlas.json`, its schema, product HTML/CSS/JavaScript, local assets, and documentation. It needs no `package.json`, lockfile, `node_modules`, build step, or copy of the viewer. The CLI supplies scaffold, serving, and static audit from its own installation. `audit` leaves project files unchanged unless an output file is explicitly requested. Viewing with `serve` does not write; explicit **Save progress** writes the sibling progress file. Use `--read-only` to disable editing.
+The consumer bundle is named `<name>.ketatlas/` and contains `atlas.json`, its schema, documentation, and either static screen assets or an `atlas.renderer.json` sidecar. The stable directory suffix lets desktop tools discover atlases without parsing unrelated JSON. A bundle needs no KetAtlas package manifest, lockfile, `node_modules`, build step, or copy of the viewer. Framework dependencies and reusable UI stay in the product workspace, where multiple atlases can share one set of presenters, components, fixtures, and styles. The CLI supplies discovery, serving, validation, and audit. `audit` leaves project files unchanged unless an output file is explicitly requested. Viewing with `serve` does not write; explicit **Save progress** writes the sibling progress file. Use `--read-only` to disable editing.
 
-Pin the version in run commands or the global installation for reproducible team workflows. Product scripts implement mock screen interactions; they are authored content, not a local installation of KetAtlas. Framework tooling and tests stay in the KetAtlas repository.
+Pin the version in run commands or the global installation for reproducible team workflows. Product scripts implement mock screen interactions; they are authored content, not a local installation of KetAtlas. A native renderer reuses the product's framework tooling and shared UI source rather than copying markup into each atlas.
 
-Edit the JSON and screen files, then refresh the browser. The default viewer address is **http://127.0.0.1:4178**.
+Edit the JSON and product screen source, then refresh the browser. The default viewer address is **http://127.0.0.1:4178**.
 
 ## Create mockups with an agent
 
@@ -45,7 +49,31 @@ Install the KetAtlas skill in your product project:
 npx skills add ketvietlab/ketatlas --skill ketatlas
 ```
 
-Ask your agent to use the skill with a product brief: requested flows, target platforms, design references, and output directory. The agent creates actual HTML screens, a version 1 `atlas.json`, and run instructions, then audits the result.
+Ask your agent to use the skill with a product brief: requested flows, target platforms, design references, and output directory. The agent creates native framework routes (or static HTML for a static product), a version 1 `atlas.json`, and run instructions, then audits the result.
+
+## Render with the product framework
+
+KetAtlas 0.4.0 keeps the viewer and product renderer separate. Put `atlas.renderer.json` beside `atlas.json` when screens come from a framework:
+
+```json
+{
+  "$schema": "https://unpkg.com/ketatlas@0.4.0/renderer.schema.json",
+  "version": 1,
+  "framework": "vue",
+  "command": ["npm", "run", "atlas:serve", "--", "--host", "{host}", "--port", "{port}"],
+  "cwd": "../..",
+  "readyPath": "/__atlas/ready",
+  "screenBasePath": "/__atlas/orders/"
+}
+```
+
+Then run:
+
+```sh
+npx --yes ketatlas@0.4.0 serve ./tasks/orders.ketatlas --renderer --port 60550 --html-port 60551
+```
+
+The first port serves the map and progress API. The second is owned by the declared React/Vue/KetJS/etc. server and serves screen routes. `--renderer` is explicit because it executes the local command array. Static projects continue to use the one-port command without this flag. See [Native renderers](docs/authoring.md#framework-native-screens).
 
 See [Agent mockups](docs/agent-mockups.md) for installation options, a ready-to-use request, and a reusable brief template. Agents without skill support can read the [single skill file](skills/ketatlas/SKILL.md) directly.
 
@@ -81,12 +109,13 @@ Open **Screens** to filter screen progress, review blockers and edit acceptance
 
 ## Commands
 
-| Command                 | Purpose                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------ |
-| `scaffold <directory>`  | Create a project from `basic`, `web`, or `process`. Refuses to overwrite existing content. |
-| `serve <atlas.json>`    | Start the viewer and serve local screens. Defaults to port 4178 on localhost.              |
-| `audit <atlas.json>`    | Check configuration, reachability, local files, and literal HTML/CSS references.           |
-| `validate <atlas.json>` | Validate configuration only, without reading screen files.                                 |
+| Command                    | Purpose                                                                          |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `scaffold <name.ketatlas>` | Create a bundle from `basic`, `web`, or `process`. Refuses existing content.     |
+| `discover <directory>`     | Find valid `*.ketatlas/atlas.json` bundles and report invalid bundles.           |
+| `serve <bundle\|json>`     | Start the viewer; optionally supervise a native renderer on a second port.       |
+| `audit <bundle\|json>`     | Check configuration, reachability, local files, and literal HTML/CSS references. |
+| `validate <bundle\|json>`  | Validate configuration only, without reading screen files.                       |
 
 Use `--help` for options, `--root` when assets live above the JSON directory, and `audit --json` for CI reports. [Full CLI reference →](docs/cli.md)
 
@@ -114,7 +143,7 @@ npm ci
 npm run dev
 ```
 
-The playground includes mobile sign-in, desktop approval, and a fulfilment process. These development dependencies are not required in consumer projects. To try an unpublished checkout, use `npx --yes --package ~/dev/ketatlas ketatlas serve /path/to/my-atlas/atlas.json`.
+The playground includes mobile sign-in, desktop approval, and a fulfilment process. These development dependencies are not required in consumer projects. To try an unpublished checkout, use `npx --yes --package ~/dev/ketatlas ketatlas serve /path/to/my-atlas.ketatlas`.
 
 Stable version increases merged into `develop` are automatically published after CI verifies the package. See [Releasing](docs/releasing.md).
 

package/bin/audit.js

@@ -3,6 +3,7 @@ import { readFile, realpath, stat } from "node:fs/promises";
 import { resolve, dirname, relative, sep, extname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { validateAtlas } from "../src/config.js";
+import { readRendererConfig, rendererFileName } from "./renderer.js";
 const within = (root, path) => {
   const r = relative(root, path);
   return r === "" || (!r.startsWith(".." + sep) && r !== ".." && !r.startsWith(sep));
@@ -29,6 +30,12 @@ export async function auditAtlas(file, { root: rootOption } = {}) {
     warnings = [...result.warnings],
     checked = new Set(),
     remote = new Set();
+  let renderer;
+  try {
+    renderer = await readRendererConfig(resolve(dirname(absolute), rendererFileName));
+  } catch (error) {
+    if (error.code !== "ENOENT") errors.push({ path: rendererFileName, message: error.message });
+  }
   if (!within(root, absolute))
     errors.push({ path: "file", message: "The atlas JSON must be inside the serve root." });
   async function inspect(value, from, label) {
@@ -90,9 +97,12 @@ export async function auditAtlas(file, { root: rootOption } = {}) {
     }
   }
   if (result.valid) {
-    for (const s of config.screens || []) await inspect(s.url, absolute, `screen:${s.id}`);
+    if (!renderer)
+      for (const s of config.screens || []) await inspect(s.url, absolute, `screen:${s.id}`);
     for (const f of config.flows)
-      for (const n of f.nodes) if (n.url) await inspect(n.url, absolute, `node:${f.id}/${n.id}`);
+      for (const n of f.nodes)
+        if (n.url && (!renderer || (n.type || (n.screen ? "screen" : "note")) !== "screen"))
+          await inspect(n.url, absolute, `node:${f.id}/${n.id}`);
   }
   if (result.valid) {
     try {
@@ -118,7 +128,8 @@ export async function auditAtlas(file, { root: rootOption } = {}) {
     },
     errors,
     warnings,
-    scope:
-      "Static configuration and literal local HTML/CSS references. JavaScript behavior and remote embedding policies are not executed.",
+    scope: renderer
+      ? `Configuration and ${renderer.data.framework} renderer contract. The renderer command, routes, JavaScript behavior and embedding are not executed.`
+      : "Static configuration and literal local HTML/CSS references. JavaScript behavior and remote embedding policies are not executed.",
   };
 }

package/bin/discovery.js

@@ -0,0 +1,90 @@
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { validateAtlas } from "../src/config.js";
+
+export const atlasDirectorySuffix = ".ketatlas";
+export const atlasManifestName = "atlas.json";
+
+const excludedDirectories = new Set([
+  ".git",
+  ".cache",
+  ".next",
+  ".venv",
+  "build",
+  "dist",
+  "node_modules",
+  "vendor",
+]);
+
+export function isAtlasDirectory(path) {
+  return basename(resolve(path)).toLowerCase().endsWith(atlasDirectorySuffix);
+}
+
+export function requireAtlasDirectory(path) {
+  const destination = resolve(path);
+  if (!isAtlasDirectory(destination))
+    throw new Error(`Atlas directories must end in ${atlasDirectorySuffix}.`);
+  return destination;
+}
+
+export async function resolveAtlasFile(target) {
+  const absolute = resolve(target);
+  const info = await stat(absolute);
+  if (!info.isDirectory()) return absolute;
+  if (!isAtlasDirectory(absolute))
+    throw new Error(`Atlas directories must end in ${atlasDirectorySuffix}.`);
+  return join(absolute, atlasManifestName);
+}
+
+async function describe(directory) {
+  const path = join(directory, atlasManifestName);
+  let config;
+  try {
+    config = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    return { error: { path, message: error.message } };
+  }
+  const validation = validateAtlas(config);
+  if (!validation.valid)
+    return {
+      error: {
+        path,
+        message: validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join("; "),
+      },
+    };
+  return {
+    atlas: {
+      path,
+      directory,
+      title: config.title,
+      screens: (config.screens || []).map(({ id, title, url }) => ({ id, title, url })),
+      flowCount: config.flows.length,
+    },
+  };
+}
+
+export async function discoverAtlases(root) {
+  const workspace = await realpath(resolve(root));
+  if (!(await stat(workspace)).isDirectory())
+    throw new Error("Discovery root must be a directory.");
+  const atlases = [],
+    errors = [],
+    directories = [workspace];
+  while (directories.length) {
+    const directory = directories.pop();
+    if (isAtlasDirectory(directory)) {
+      const result = await describe(directory);
+      if (result.atlas) atlases.push(result.atlas);
+      else errors.push(result.error);
+      continue;
+    }
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() || excludedDirectories.has(entry.name))
+        continue;
+      directories.push(join(directory, entry.name));
+    }
+  }
+  atlases.sort((a, b) => a.path.localeCompare(b.path));
+  errors.sort((a, b) => a.path.localeCompare(b.path));
+  return { version: 1, root: workspace, atlases, errors };
+}

package/bin/ketatlas.js

@@ -8,23 +8,31 @@ import { validateAtlas } from "../src/config.js";
 import { serve } from "./server.js";
 import { serveAtlas } from "./viewer.js";
 import { auditAtlas } from "./audit.js";
+import {
+  discoverAtlases,
+  isAtlasDirectory,
+  requireAtlasDirectory,
+  resolveAtlasFile,
+} from "./discovery.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const help = `KetAtlas — scaffold, serve, and audit HTML workflow maps
+const help = `KetAtlas — scaffold, serve, and audit framework-native workflow maps
 
-  ketatlas scaffold <directory> [--template basic|web|process]
-  ketatlas serve <atlas.json> [--port 4178] [--root directory]
-  ketatlas audit <atlas.json> [--root directory] [--json] [--strict]
-  ketatlas validate <atlas.json>
-  ketatlas progress <atlas.json> [--json] [--init]
-  ketatlas progress <atlas.json> --set <screen-id> --record <record.json> --expect <revision>
+  ketatlas scaffold <name.ketatlas> [--template basic|web|process]
+  ketatlas discover <directory> [--json]
+  ketatlas serve <name.ketatlas|atlas.json> [--port 4178] [--root directory] [--renderer] [--html-port 4179]
+  ketatlas audit <name.ketatlas|atlas.json> [--root directory] [--json] [--strict]
+  ketatlas validate <name.ketatlas|atlas.json>
+  ketatlas progress <name.ketatlas|atlas.json> [--json] [--init]
+  ketatlas progress <name.ketatlas|atlas.json> --set <screen-id> --record <record.json> --expect <revision>
   ketatlas --version
 
 Examples:
-  npx ketatlas scaffold my-atlas
-  npx ketatlas serve my-atlas/atlas.json
-  npx ketatlas audit my-atlas/atlas.json --strict
+  npx ketatlas scaffold my-atlas.ketatlas
+  npx ketatlas discover . --json
+  npx ketatlas serve my-atlas.ketatlas
+  npx ketatlas audit my-atlas.ketatlas --strict
 
-Serve binds to 127.0.0.1. No HTML wrapper, build, account, or backend required.
+Serve binds to 127.0.0.1. Static screens need no build; --renderer starts the project's declared framework server.
 `;
 function parse(args, allowed) {
   const options = {},
@@ -61,7 +69,7 @@ async function main(args) {
       template = options.template || "basic";
     if (!["basic", "web", "process"].includes(template))
       throw new Error("Templates: basic, web, process.");
-    const destination = resolve(target);
+    const destination = requireAtlasDirectory(target);
     let existing;
     try {
       existing = await readdir(destination);
@@ -79,10 +87,25 @@ async function main(args) {
         errorOnExist: true,
       });
     console.log(
-      `Created ${destination}\n\nNext: npx ketatlas serve "${join(destination, "atlas.json")}"\nEdit atlas.json to make it yours.`,
+      `Created ${destination}\n\nNext: npx ketatlas serve "${destination}"\nEdit atlas.json to make it yours.`,
     );
     return;
   }
+  if (command === "discover") {
+    const { target, options } = parse(rest, { json: "boolean" }),
+      result = await discoverAtlases(target);
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      for (const atlas of result.atlases)
+        console.log(`${atlas.title}\t${atlas.path}\t${atlas.screens.length} screens`);
+      for (const error of result.errors) console.error(`ERROR ${error.path}: ${error.message}`);
+      console.log(
+        `${result.atlases.length} atlas${result.atlases.length === 1 ? "" : "es"} in ${result.root}`,
+      );
+    }
+    if (result.errors.length) process.exitCode = 1;
+    return;
+  }
   if (command === "audit") {
     const { target, options } = parse(rest, {
       root: "string",
@@ -90,7 +113,7 @@ async function main(args) {
       strict: "boolean",
       output: "string",
     });
-    const report = await auditAtlas(target, options),
+    const report = await auditAtlas(await resolveAtlasFile(target), options),
       pass = report.valid && (!options.strict || report.warnings.length === 0);
     if (options.output)
       await writeFile(resolve(options.output), JSON.stringify(report, null, 2) + "\n", {
@@ -109,7 +132,7 @@ async function main(args) {
   }
   if (command === "validate") {
     const { target } = parse(rest, {}),
-      config = JSON.parse(await readFile(resolve(target), "utf8")),
+      config = JSON.parse(await readFile(await resolveAtlasFile(target), "utf8")),
       result = validateAtlas(config);
     for (const issue of result.errors) console.error(`ERROR ${issue.path}: ${issue.message}`);
     for (const issue of result.warnings) console.warn(`WARN ${issue.path}: ${issue.message}`);
@@ -130,7 +153,7 @@ async function main(args) {
       record: "string",
       expect: "string",
     });
-    const file = resolve(target),
+    const file = await resolveAtlasFile(target),
       atlas = JSON.parse(await readFile(file, "utf8"));
     const valid = validateAtlas(atlas);
     if (!valid.valid) throw new Error(valid.errors.map((e) => e.message).join("; "));
@@ -173,22 +196,37 @@ async function main(args) {
         port: "string",
         root: "string",
         "read-only": "boolean",
+        renderer: "boolean",
+        "html-port": "string",
       }),
-      port = Number(options.port || 4178);
+      port = Number(options.port || 4178),
+      htmlPort = Number(options["html-port"] || (port < 65535 ? port + 1 : 0));
     if (!Number.isInteger(port) || port < 1 || port > 65535)
       throw new Error("Port must be 1–65535.");
+    if (options.renderer && (!Number.isInteger(htmlPort) || htmlPort < 1 || htmlPort > 65535))
+      throw new Error("HTML port must be 1–65535.");
+    if (options.renderer && htmlPort === port)
+      throw new Error("Viewer and HTML ports must be different.");
     const directory = (await stat(resolve(target))).isDirectory();
     if (directory && options.root)
       throw new Error("--root is only needed when serving an atlas JSON file.");
-    const server = directory
-      ? await serve(target, { port })
-      : await serveAtlas(target, { port, root: options.root, readOnly: options["read-only"] });
+    const server =
+      directory && !isAtlasDirectory(target)
+        ? await serve(target, { port })
+        : await serveAtlas(await resolveAtlasFile(target), {
+            port,
+            root: options.root,
+            readOnly: options["read-only"],
+            renderer: options.renderer,
+            htmlPort,
+          });
     console.log(
-      `KetAtlas: http://127.0.0.1:${server.address().port}\nServing ${resolve(target)}\nPress Ctrl+C to stop.`,
+      `KetAtlas: http://127.0.0.1:${server.address().port}${server.htmlOrigin ? `\nHTML: ${server.htmlOrigin}` : ""}\nServing ${resolve(target)}\nPress Ctrl+C to stop.`,
     );
-    const close = () => {
+    const close = async () => {
       server.close();
       server.closeAllConnections();
+      await server.closeRenderer?.();
     };
     process.once("SIGINT", close);
     process.once("SIGTERM", close);

package/bin/renderer.js

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+
+export const rendererFileName = "atlas.renderer.json";
+
+export function validateRendererConfig(input) {
+  const errors = [];
+  const error = (path, message) => errors.push({ path, message });
+  if (!object(input))
+    return {
+      valid: false,
+      errors: [{ path: "$", message: "Expected a renderer object." }],
+    };
+  for (const key of Object.keys(input))
+    if (
+      ![
+        "$schema",
+        "version",
+        "framework",
+        "command",
+        "cwd",
+        "readyPath",
+        "screenBasePath",
+        "readyTimeoutMs",
+      ].includes(key)
+    )
+      error(key, "Unknown property.");
+  if (input.version !== 1) error("version", "Expected version: 1.");
+  if (!text(input.framework)) error("framework", "Expected a non-empty framework name.");
+  if (!Array.isArray(input.command) || input.command.length === 0)
+    error("command", "Expected a non-empty command array.");
+  else
+    for (const [index, value] of input.command.entries())
+      if (!text(value)) error(`command[${index}]`, "Expected a non-empty argument.");
+  if (input.$schema !== undefined && typeof input.$schema !== "string")
+    error("$schema", "Expected text.");
+  if (input.cwd !== undefined && !text(input.cwd)) error("cwd", "Expected a directory path.");
+  for (const key of ["readyPath", "screenBasePath"])
+    if (input[key] !== undefined && (!text(input[key]) || !input[key].startsWith("/")))
+      error(key, "Expected an origin-relative path beginning with /.");
+  if (input.screenBasePath !== undefined && !input.screenBasePath.endsWith("/"))
+    error("screenBasePath", "Expected a path ending with /.");
+  if (
+    input.readyTimeoutMs !== undefined &&
+    (!Number.isInteger(input.readyTimeoutMs) ||
+      input.readyTimeoutMs < 100 ||
+      input.readyTimeoutMs > 120000)
+  )
+    error("readyTimeoutMs", "Expected an integer from 100 to 120000.");
+  return { valid: errors.length === 0, errors };
+}
+
+export class RendererValidationError extends Error {
+  constructor(result) {
+    super(result.errors.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
+    this.name = "RendererValidationError";
+    this.errors = result.errors;
+  }
+}
+
+export async function readRendererConfig(file) {
+  const absolute = await realpath(resolve(file));
+  if (!(await stat(absolute)).isFile()) throw new Error("Expected a renderer JSON file.");
+  const data = JSON.parse(await readFile(absolute, "utf8"));
+  const result = validateRendererConfig(data);
+  if (!result.valid) throw new RendererValidationError(result);
+  const directory = dirname(absolute);
+  const cwd = await realpath(resolve(directory, data.cwd || "."));
+  if (!(await stat(cwd)).isDirectory()) throw new Error("Renderer cwd must be a directory.");
+  return {
+    file: absolute,
+    directory,
+    cwd,
+    data: {
+      ...data,
+      cwd: data.cwd || ".",
+      readyPath: data.readyPath || "/",
+      screenBasePath: data.screenBasePath || "/",
+      readyTimeoutMs: data.readyTimeoutMs || 15000,
+    },
+  };
+}
+
+const reservePort = (host) =>
+  new Promise((resolvePort, reject) => {
+    const probe = createServer();
+    probe.once("error", reject);
+    probe.listen(0, host, () => {
+      const port = probe.address().port;
+      probe.close((error) => (error ? reject(error) : resolvePort(port)));
+    });
+  });
+
+function originPath(origin, value, name) {
+  const url = new URL(value, origin);
+  if (url.origin !== origin) throw new Error(`${name} must stay on the renderer origin.`);
+  return url.href;
+}
+
+function terminate(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    if (process.platform === "win32") child.kill("SIGTERM");
+    else process.kill(-child.pid, "SIGTERM");
+  } catch {}
+}
+
+async function stop(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  terminate(child);
+  await Promise.race([
+    new Promise((done) => child.once("exit", done)),
+    new Promise((done) => setTimeout(done, 2000)),
+  ]);
+  if (child.exitCode === null && child.signalCode === null) {
+    try {
+      if (process.platform === "win32") child.kill("SIGKILL");
+      else process.kill(-child.pid, "SIGKILL");
+    } catch {}
+  }
+}
+
+export async function startRenderer(file, options = {}) {
+  const config = await readRendererConfig(file);
+  const host = options.host || "127.0.0.1";
+  const port = options.port || (await reservePort(host));
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    throw new Error("HTML port must be 1–65535.");
+  const values = {
+    host,
+    port: String(port),
+    atlasDirectory: config.directory,
+  };
+  const replace = (value) =>
+    value.replace(/\{(host|port|atlasDirectory)\}/g, (_, key) => values[key]);
+  const command = config.data.command.map(replace);
+  const origin = `http://${host}:${port}`;
+  const readyURL = originPath(origin, config.data.readyPath, "readyPath");
+  const screenBaseURL = originPath(origin, config.data.screenBasePath, "screenBasePath");
+  const child = spawn(command[0], command.slice(1), {
+    cwd: config.cwd,
+    detached: process.platform !== "win32",
+    env: {
+      ...process.env,
+      KETATLAS_HOST: host,
+      KETATLAS_HTML_PORT: String(port),
+      KETATLAS_PROJECT_DIR: config.directory,
+    },
+    stdio: options.stdio || "inherit",
+  });
+  let spawnError;
+  child.once("error", (error) => {
+    spawnError = error;
+  });
+  const started = Date.now();
+  while (Date.now() - started < config.data.readyTimeoutMs) {
+    if (spawnError) throw spawnError;
+    if (child.exitCode !== null || child.signalCode !== null)
+      throw new Error(`Renderer exited before ${readyURL} became ready.`);
+    try {
+      const response = await fetch(readyURL, { signal: AbortSignal.timeout(1000) });
+      if (response.ok) {
+        let closed = false;
+        return {
+          child,
+          config,
+          origin,
+          readyURL,
+          screenBaseURL,
+          async close() {
+            if (closed) return;
+            closed = true;
+            await stop(child);
+          },
+        };
+      }
+    } catch {}
+    await new Promise((done) => setTimeout(done, 100));
+  }
+  await stop(child);
+  throw new Error(
+    `Renderer did not become ready at ${readyURL} within ${config.data.readyTimeoutMs}ms.`,
+  );
+}