ketatlas 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

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
 
@@ -32,11 +35,11 @@ ketatlas serve my-atlas.ketatlas
 ketatlas audit my-atlas.ketatlas --strict
 ```
 
-The consumer bundle is named `<name>.ketatlas/` and contains `atlas.json`, its schema, product HTML/CSS/JavaScript, local assets, and documentation. The stable directory suffix lets desktop tools discover atlases without parsing unrelated JSON. A bundle needs no `package.json`, lockfile, `node_modules`, build step, or copy of the viewer. The CLI supplies scaffold, discovery, 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
 
@@ -46,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.
 
@@ -86,7 +113,7 @@ Open **Screens** to filter screen progress, review blockers and edit acceptance
 | -------------------------- | -------------------------------------------------------------------------------- |
 | `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 and serve local screens. Defaults to port 4178 on localhost.    |
+| `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.                       |
 

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/ketatlas.js

@@ -15,11 +15,11 @@ import {
   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 <name.ketatlas> [--template basic|web|process]
   ketatlas discover <directory> [--json]
-  ketatlas serve <name.ketatlas|atlas.json> [--port 4178] [--root directory]
+  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]
@@ -32,7 +32,7 @@ Examples:
   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 = {},
@@ -196,10 +196,17 @@ 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.");
@@ -210,13 +217,16 @@ async function main(args) {
             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.`,
+  );
+}

package/bin/viewer.js

@@ -5,6 +5,7 @@ import { resolve, dirname, relative, sep } from "node:path";
 import { validateAtlas, AtlasValidationError } from "../src/config.js";
 import { serve } from "./server.js";
 import { fileURLToPath } from "node:url";
+import { rendererFileName, startRenderer } from "./renderer.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 export async function serveAtlas(file, options = {}) {
   const absolute = await realpath(resolve(file));
@@ -18,11 +19,42 @@ export async function serveAtlas(file, options = {}) {
     throw new Error("The JSON file must be inside --root.");
   const configURL = "/" + rel.split(sep).map(encodeURIComponent).join("/");
   const token = randomBytes(24).toString("hex");
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>KetAtlas</title><style>html,body{margin:0;height:100%}#atlas{height:100dvh}#error{font:16px system-ui;padding:24px;white-space:pre-wrap}</style></head><body><main id="atlas"></main><pre id="error" hidden></pre><script type="module">import {loadAtlas} from '/__ketatlas__/src/index.js';try{window.atlas=await loadAtlas(document.querySelector('#atlas'),${JSON.stringify(configURL).replaceAll("<", "\\u003c")},{syncUrl:true,progressEndpoint:"/__ketatlas__/progress",progressToken:${JSON.stringify(token)}});document.title=${JSON.stringify(config.title).replaceAll("<", "\\u003c")}+' · KetAtlas';}catch(error){const el=document.querySelector('#error');el.hidden=false;el.textContent=error.message;}</script></body></html>`;
-  return serve(root, {
-    ...options,
-    viewer: html,
-    packageRoot,
-    handler: progressHandler(absolute, absolute, token, !options.readOnly),
-  });
+  let renderer;
+  if (options.renderer) {
+    const rendererFile = resolve(options.rendererFile || dirname(absolute), rendererFileName);
+    const htmlPort =
+      options.htmlPort ?? (options.port && options.port < 65535 ? options.port + 1 : 0);
+    renderer = await startRenderer(rendererFile, {
+      host: options.host,
+      port: htmlPort,
+      stdio: options.rendererStdio,
+    });
+  }
+  const loadOptions = {
+    syncUrl: true,
+    progressEndpoint: "/__ketatlas__/progress",
+    progressToken: token,
+    ...(renderer
+      ? {
+          screenBaseURL: renderer.screenBaseURL,
+          sandbox: "allow-scripts allow-forms allow-same-origin",
+        }
+      : {}),
+  };
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>KetAtlas</title><style>html,body{margin:0;height:100%}#atlas{height:100dvh}#error{font:16px system-ui;padding:24px;white-space:pre-wrap}</style></head><body><main id="atlas"></main><pre id="error" hidden></pre><script type="module">import {loadAtlas} from '/__ketatlas__/src/index.js';try{window.atlas=await loadAtlas(document.querySelector('#atlas'),${JSON.stringify(configURL).replaceAll("<", "\\u003c")},${JSON.stringify(loadOptions).replaceAll("<", "\\u003c")});document.title=${JSON.stringify(config.title).replaceAll("<", "\\u003c")}+' · KetAtlas';}catch(error){const el=document.querySelector('#error');el.hidden=false;el.textContent=error.message;}</script></body></html>`;
+  try {
+    const server = await serve(root, {
+      ...options,
+      viewer: html,
+      packageRoot,
+      handler: progressHandler(absolute, absolute, token, !options.readOnly),
+    });
+    server.renderer = renderer;
+    server.htmlOrigin = renderer?.origin;
+    server.closeRenderer = () => renderer?.close();
+    return server;
+  } catch (error) {
+    await renderer?.close();
+    throw error;
+  }
 }

package/docs/agent-mockups.md

@@ -1,6 +1,6 @@
 # Create mockups with an agent
 
-Give an agent the KetAtlas skill and a product brief. The agent produces real HTML screens plus `atlas.json`; KetAtlas opens those files as an interactive workflow map. The brief describes the product, while the generated JSON schema and CLI audit check the output format.
+Give an agent the KetAtlas skill and a product brief. The agent produces native framework screen routes (or static HTML for a static product) plus `atlas.json`; KetAtlas opens them as an interactive workflow map. The brief describes the product, while the schemas and CLI audit check the output contracts.
 
 ## Install the skill once
 
@@ -26,7 +26,7 @@ If the agent does not support skill installation, attach that file or ask it to
 For a short request, invoke the skill and include the product, target, design reference, and flows:
 
 ```text
-Use $ketatlas to create one shared HTML mobile prototype for Northstar Tasks
+Use $ketatlas to create one shared React mobile prototype for Northstar Tasks
 in ./tasks/mobile. Use 390 × 844 screens, English product copy, and the design
 system in ./design-system. Include sign-in, password recovery, task list,
 task details, and task completion. Map entry points, actions, outcomes, and
@@ -36,11 +36,13 @@ and preview the result. Return the serve command and verification results.
 
 `$ketatlas` is the explicit skill invocation in Codex. In other agents, use that agent's skill selector or explicitly ask it to use the installed KetAtlas skill. Keep the same product brief.
 
-The deliverable is a `<name>.ketatlas/` bundle containing data and product screen assets: JSON/schema, HTML/CSS/JavaScript, local assets, and documentation. Do not add a package manifest, lockfile, node_modules, or copied viewer/test tooling to make the atlas runnable. Use a global KetAtlas installation or a version-pinned npx command. Browser checks can use the agent's existing tooling outside the atlas folder.
+The deliverable is a `<name>.ketatlas/` bundle containing JSON/schema, documentation, and either static screen assets or `atlas.renderer.json`. Do not add a package manifest, lockfile, node_modules, or copied viewer/test tooling inside the bundle. Native React/Vue/KetJS/etc. routes reuse the product's existing framework package and shared UI source outside the atlas folder. Use `ketatlas@0.4.0` for this contract. Browser checks can use the agent's existing tooling outside the atlas folder.
 
 The agent should infer routine details and record assumptions. Provide an exact list when “all screens” means a defined inventory, so missing coverage can be checked against a source.
 
-Before it creates or edits visual screens, the skill asks for one design-system choice: Auto (Két Design System), Két Design System, Carbon, GitHub Primer, Microsoft Fluent 2, no design system, or a repository URL/local path. A design system already named in the request counts as the answer. Auto uses [Két Design System](https://github.com/ketvietlab/ketjs/tree/develop/packages/design-system). The agent inspects and uses the selected system's actual tokens, components, assets, and patterns, then records the source and integration strategy in the atlas README.
+Before it creates or edits visual screens, the skill asks for one design-system choice: Auto (Két Design System), Két Design System, Carbon, GitHub Primer, Microsoft Fluent 2, no design system, or a repository URL/local path. A design system already named in the request counts as the answer. Auto uses [Két Design System](https://github.com/ketvietlab/ketjs/tree/develop/packages/design-system). The agent inspects its actual tokens, components, assets, patterns, and framework, then renders with that framework instead of duplicating markup. An incorrect canonical component is fixed at its source before Atlas work continues.
+
+For several atlases in one workspace, the agent creates or reuses one shared framework module for screen presenters, design-system composition, fixture factories, route helpers, and styles. Individual bundles keep flow/state declarations and namespaced screen paths; they do not copy UI code from one another. Production routes and Atlas fixture routes call the same presenter so the mock and built product do not become two visual sources of truth.
 
 ## Use a saved brief for larger projects
 
@@ -55,7 +57,7 @@ Save this template as `mockup-brief.md`, fill in the relevant fields, and ask: *
 - Target platforms and viewport sizes:
 - Product content language:
 - Design system choice (Auto/Két/Carbon/Primer/Fluent 2/none/custom source):
-- Existing HTML and reference files/URLs:
+- Existing application/framework and reference files/URLs:
 - Requested flows and screen inventory:
 - Relevant loading, empty, validation, error, and recovery states:
 - Interactions to demonstrate and synthetic demo inputs:
@@ -63,15 +65,17 @@ Save this template as `mockup-brief.md`, fill in the relevant fields, and ask: *
 
 ## Expected delivery
 
-Create actual HTML screens and one KetAtlas version 1 atlas.json. Reuse
-screens and styles across flows. Set explicit flow starts, outcomes, and
-labelled transitions. Each named screen state must open directly.
+Create native framework routes, or static HTML only for a static product,
+and one KetAtlas version 1 atlas.json. Reuse shared presenters and styles
+across flows and atlases. Set explicit flow starts, outcomes, and labelled
+transitions. Each named screen state must open directly.
 
 Use the generated ketatlas.schema.json. Run KetAtlas audit, test the
 important interactions in the viewer when browser automation is available,
 and report results or limitations. Include a README with run commands,
-flow coverage, demo inputs, and assumptions. Keep the output free of package
-manifests, lockfiles, local dependencies, and copied viewer/test tooling.
+flow coverage, demo inputs, and assumptions. Keep the atlas bundle free of
+package manifests, lockfiles, local dependencies, duplicated component/style
+implementations, and copied viewer/test tooling.
 ```
 
 For an existing prototype, ask the agent to reuse its HTML and add or update the atlas instead of rebuilding it. For later changes, name the flow or screen IDs to preserve, for example: **“Add an expired-code recovery branch to sign-in; keep existing screen IDs and audit the updated project.”**
@@ -79,11 +83,13 @@ For an existing prototype, ask the agent to reuse its HTML and add or update the
 ## Review the result
 
 ```sh
-npx ketatlas discover . --json
-npx ketatlas serve ./tasks/mobile.ketatlas
-npx ketatlas audit ./tasks/mobile.ketatlas --strict
+npx --yes ketatlas@0.4.0 discover . --json
+npx --yes ketatlas@0.4.0 serve ./tasks/mobile.ketatlas --renderer --port 60550 --html-port 60551
+npx --yes ketatlas@0.4.0 audit ./tasks/mobile.ketatlas --strict
 ```
 
+For a genuinely static project, omit `atlas.renderer.json`, `--renderer`, and `--html-port`.
+
 Check the delivered flow coverage against the brief. Open **Try this screen** to test the actual HTML. A successful audit confirms structural and local-file checks, not visual quality, full product coverage, or working production integrations. Intentional remote URLs require separate verification and produce strict-audit warnings.
 
 The skill lives in this repository so teams can review and evolve it alongside the schema and CLI. It also backfills legacy atlas directories into the discoverable bundle pattern before extending them.

package/docs/architecture.md

@@ -1,26 +1,34 @@
 # Architecture
 
-KetAtlas is a static browser viewer plus a Node.js command-line toolkit. There is no database, account service or runtime npm dependency. The localhost CLI has a narrow, protected API to read and save the progress sidecar; static hosting remains read-only.
+KetAtlas is a browser viewer plus a Node.js command-line orchestrator. There is no database, account service or runtime npm dependency. Static screens can still use the built-in file server. Framework-native screens run through the product's own server on a second loopback origin, preserving the component implementation as the single source of truth. The localhost CLI has a narrow, protected API to read and save the progress sidecar; static hosting remains read-only.
 
 ```text
-<name>.ketatlas/atlas.json + screen HTML
+<name>.ketatlas/atlas.json
         │
         ├── discover → workspace bundle catalog
         ├── validate / audit → diagnostics and CI exit code
-        │
-        └── serve → built-in viewer page
-                       │
-                       ├── config validation + URL resolution
-                       ├── deterministic grid layout
-                       ├── Shadow DOM shell + SVG edges
-                       └── lazy HTML iframes + interactive inspector
+        └── serve → viewer/control origin
+                       ├── config validation + deterministic map
+                       ├── progress API + Shadow DOM viewer
+                       └── lazy iframes
+                              ├── static files on the viewer origin, or
+                              └── native framework renderer origin
+                                      └── shared presenters + Atlas fixtures
 ```
 
 ## Consumer boundary
 
-KetAtlas is installed globally or executed through npx. Consumers provide a `<name>.ketatlas/` bundle containing JSON, a schema, HTML/CSS/JavaScript mock screens, assets, and documentation. The suffix is the discovery boundary: tools inspect only its direct `atlas.json`, not arbitrary workspace JSON. Consumers do not need a Node package, lockfile, development dependencies, viewer implementation, or build/test scripts to scaffold, discover, serve, or audit a map.
+KetAtlas is installed globally or executed through npx. Consumers provide a `<name>.ketatlas/` bundle containing JSON, a schema, documentation, and either static mock screens or `atlas.renderer.json`. The suffix is the discovery boundary: tools inspect only its direct `atlas.json`, not arbitrary workspace JSON. Consumers do not need a KetAtlas package, lockfile, development dependencies, viewer implementation, or build/test scripts. A native renderer deliberately reuses the product's existing framework package and lockfile outside the bundle.
+
+The package owns the CLI, viewer, validation, renderer supervision, and contract verification. The product owns screen markup, components, styles, fixtures, and framework tests. Static audit does not execute renderer commands or simulate product interactions. Agent browser checks can run through external tooling without adding a test harness to the delivered atlas folder.
+
+## Native renderer boundary
+
+`atlas.renderer.json` declares a framework label, an argv array, a working directory, readiness route, and screen base path. It is separate from `atlas.json`: workflow format version 1 remains framework-neutral. `serve --renderer` is required to execute the command, making local code execution explicit. KetAtlas substitutes host/port tokens, waits for a 2xx readiness response, and terminates the renderer with the viewer.
+
+The viewer and renderer use different loopback origins. Relative screen and screen-node URLs resolve against `screenBasePath` on the renderer origin. Relative external/note references still resolve beside `atlas.json`. Renderer iframes receive `allow-same-origin` because the separate origin prevents access to the viewer while enabling native module loading, assets, storage, and same-origin requests.
 
-The package owns the CLI, viewer, validation, and framework verification. A product may have its own application tests elsewhere; those are independent of the map format. Static audit does not simulate product interactions. Agent browser checks can run through external tooling without adding a test harness to the delivered atlas folder.
+Multiple atlases should share one framework renderer source. Shared design-system compositions, presenters, fixture factories, and styles live in one product module; each atlas selects namespaced routes through `screenBasePath` and owns only its flow/state declarations. The core does not define a component DSL or translate component trees.
 
 ## Ownership
 
@@ -45,7 +53,7 @@ Flows are stacked on one canvas. A row and column grow to fit their largest node
 
 Camera changes use an animation frame and a CSS transform. Drag, wheel, keyboard and pinch input use shared accelerated motion constants while zoom remains anchored under the pointer. Only the nearest visible screen cards receive iframes, up to the configured cap. Below the preview threshold, all cards show placeholders. This limits embedded-page cost; every node and edge still has a DOM element. There is no claim of unlimited graph size.
 
-The inspector reuses the same screen URL at its declared viewport dimensions, with no extra side padding. Its iframe is removed when closed. Reopening a screen loads a fresh instance; editing a prototype is not persistent business state.
+The inspector reuses the same screen URL at its declared viewport dimensions, with no extra side padding. Its iframe is removed when closed. Reopening a screen loads a fresh instance; editing a prototype is not persistent business state. Framework rendering and business simulation remain inside the renderer, never the viewer.
 
 ## Isolation and lifecycle
 
@@ -61,7 +69,7 @@ The default theme uses Inter and KetJS's canonical tokens and primitives. `prepa
 
 ## Version 1 boundaries
 
-KetAtlas is a viewer and authoring toolkit, not a visual graph editor. Users edit JSON and HTML in their normal tools. It does not record a graph by watching clicks, synthesize screens, calculate backend permissions, or execute the arrow graph as an automated test. Cross-flow edges, collaborative editing and browser-based project audits are outside the current contract.
+KetAtlas is a viewer and authoring toolkit, not a visual graph editor. Users edit JSON and product framework source in their normal tools. It does not record a graph by watching clicks, synthesize screens, translate React/Vue/KetJS components, calculate backend permissions, or execute the arrow graph as an automated test. Cross-flow edges, collaborative editing and browser-based project audits are outside the current contract.
 
 ## Delivery tracking
 

package/docs/authoring.md

@@ -1,6 +1,6 @@
 # Authoring a useful atlas
 
-Start with a user goal: sign in, approve a purchase, or deliver an order. Give each flow one clear start and a small number of outcomes. Screen files can come from an existing prototype; KetAtlas does not require a particular frontend framework.
+Start with a user goal: sign in, approve a purchase, or deliver an order. Give each flow one clear start and a small number of outcomes. Screen routes come from the product's actual framework; static HTML remains supported for products that are truly static.
 
 ## 1. Create a starting point
 
@@ -13,7 +13,7 @@ Open a card with a double-click. The preview is actual HTML; links and JavaScrip
 
 ## 2. Register your screens
 
-Add each reusable screen once in `screens`. Use paths relative to `atlas.json`, including query parameters for prototype states. A React/Vite prototype can expose its own embedded routes through an HTTP URL, provided it permits iframe embedding. Audit reports remote URLs for separate verification.
+Add each reusable screen once in `screens`. Use relative paths, including query parameters for prototype states. Static paths resolve beside `atlas.json`; framework paths resolve beneath the native renderer's `screenBasePath`.
 
 For a desktop page:
 
@@ -28,6 +28,44 @@ For a desktop page:
 
 HTML should include a viewport meta tag. Avoid adding a second device frame, reviewer sidebar or fixed outer margin inside the page being embedded; point to its clean preview route instead.
 
+## Framework-native screens
+
+Use the same implementation framework as the product and design system. React screens stay React, Vue screens stay Vue, and KetJS server components render through KetJS. Do not reproduce component output with copied HTML, string templates, DOM post-processing, or a parallel Atlas component format.
+
+Keep one presentation path:
+
+```text
+business loader ─┐
+                 ├─ shared screen presenter ─ design-system components/styles
+Atlas fixture ───┘
+```
+
+The business loader supplies real data, permissions, and actions. The Atlas route supplies a deterministic fixture selected by its route/query state. Both call the same presenter. If several atlases need the same shell, field, table, or layout, move that composition and its styles into one shared product module rather than copying it between bundles.
+
+Place this sidecar beside `atlas.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/ketatlas@0.4.0/renderer.schema.json",
+  "version": 1,
+  "framework": "ketjs",
+  "command": ["npm", "run", "atlas:serve", "--", "--host", "{host}", "--port", "{port}"],
+  "cwd": "../..",
+  "readyPath": "/__atlas/ready",
+  "screenBasePath": "/__atlas/customer-care/"
+}
+```
+
+Commands are argv arrays and do not run through a shell. `cwd` is relative to the bundle. The command may use `{host}`, `{port}`, and `{atlasDirectory}`; the same values are also available through `KETATLAS_HOST`, `KETATLAS_HTML_PORT`, and `KETATLAS_PROJECT_DIR`. `readyPath` must return 2xx. `screenBasePath` must start and end with `/`.
+
+Run the two origins explicitly:
+
+```sh
+npx --yes ketatlas@0.4.0 serve ./customer-journeys.ketatlas --renderer --port 60550 --html-port 60551
+```
+
+The first origin owns only the map and progress API. The second origin owns HTML, framework modules, styles, assets, and screen-side requests. Audit validates the renderer contract and graph without executing the command; browser verification must exercise the combined result.
+
 ## 3. Connect actions and decisions
 
 Use short labels such as **Submit request**, **Permission missing**, and **Try again**. Put the main journey on row 0, with explicit columns. Place recovery states on row 1 and give their arrows `kind: "recovery"`.

package/docs/cli.md

@@ -2,7 +2,7 @@
 
 Install once with `npm install --global ketatlas`, or prefix commands with `npx --yes ketatlas`. No dependency installation is required in the consumer directory. `node /path/to/ketatlas/bin/ketatlas.js` is also available to framework maintainers.
 
-A consumer keeps only its JSON/schema, product HTML/CSS/JavaScript, assets, and documentation. The package manifest, lockfile, development scripts, and browser test dependencies belong to the tool. Normal `serve`, `validate`, and `audit` calls do not create files in the consumer; `audit --output` is an explicit exception.
+A consumer keeps its JSON/schema, documentation, and either static product assets or a native renderer sidecar. KetAtlas package files and browser test dependencies belong to the tool; framework package files remain in the product workspace. Normal `serve`, `validate`, and `audit` calls do not create files in the consumer; `audit --output` is an explicit exception.
 
 ## Scaffold
 
@@ -32,6 +32,7 @@ Legacy manifest paths remain valid command arguments, but discovery intentionall
 ```sh
 ketatlas serve ./tasks/onboarding.ketatlas
 ketatlas serve ./tasks/onboarding.ketatlas --port 4180
+ketatlas serve ./tasks/onboarding.ketatlas --renderer --port 60550 --html-port 60551
 ketatlas serve ./legacy/atlas.json --root .
 ```
 
@@ -41,6 +42,14 @@ Open the printed localhost URL. Changes appear after refreshing; there is no hot
 
 The `/__ketatlas__/` route is reserved for viewer assets. Dotfiles and paths resolving outside the file root, including symlink escapes, are not served. Only GET/HEAD are supported. The server binds to `127.0.0.1`; it is a local preview server, not a production application server.
 
+### Native renderer mode
+
+`--renderer` reads `atlas.renderer.json` beside the manifest and executes its command array without a shell. This is opt-in because the project controls the command. The renderer gets `KETATLAS_HOST`, `KETATLAS_HTML_PORT`, and `KETATLAS_PROJECT_DIR`; command arguments can also use `{host}`, `{port}`, and `{atlasDirectory}` placeholders.
+
+`--port` selects the viewer/control origin. `--html-port` selects the separate framework renderer origin and defaults to the following port. The ports must differ. KetAtlas waits for the configured `readyPath`, resolves relative screen URLs beneath `screenBasePath`, prints both origins, and terminates the renderer when the viewer receives SIGINT or SIGTERM.
+
+The second origin lets trusted React/Vue/KetJS routes load their own modules, styles, assets, and same-origin requests while remaining isolated from the viewer origin. A shared product renderer can serve namespaced routes for several atlas bundles so they reuse the same presenters and styles.
+
 `serve <directory>` also works as a plain static preview for an existing HTML integration. JSON mode is recommended for project planning.
 
 ## Audit
@@ -60,8 +69,9 @@ Audit checks:
 - Local screen files and node URL overrides, using the same root boundary as the server.
 - Literal resource references in HTML (`src`/`href`), links between HTML pages, and CSS imports/URLs.
 - A viewport meta tag in HTML previews.
+- A colocated native renderer contract when present. Its screen paths are treated as framework routes rather than local files.
 
-Remote URLs are reported but not fetched. Audit does not execute JavaScript, discover dynamic imports/URLs, validate remote CSP or `X-Frame-Options`, simulate user actions, or verify backend/native behavior. Use your project's browser tests for those checks.
+Remote URLs are reported but not fetched. Audit does not execute renderer commands or JavaScript, discover dynamic imports/URLs, validate remote CSP or `X-Frame-Options`, simulate user actions, or verify backend/native behavior. Use the two-port preview and your project's browser tests for those checks.
 
 Exit codes:
 

package/docs/configuration.md

@@ -14,7 +14,26 @@ The [JSON Schema](../schema.json) defines version 1. A generated project contain
 | `flows`       | Yes      | A nonempty array of workflows.                                     |
 | `$schema`     | No       | Schema URL/path for your editor.                                   |
 
-All viewer UI is English. Project titles, descriptions and labels can use any language. Search ignores case and combining accents.
+All viewer UI is English. Project titles, descriptions and labels can use any language. Search ignores case and combining accents. Workflow format version 1 remains framework-neutral; native rendering is declared in a separate sidecar.
+
+## Native renderer sidecar
+
+`atlas.renderer.json` is optional and sits beside `atlas.json`. Its [schema](../renderer.schema.json) has these fields:
+
+| Field            | Required | Default / meaning                                                   |
+| ---------------- | -------- | ------------------------------------------------------------------- |
+| `version`        | Yes      | Renderer contract version; must be `1`.                             |
+| `framework`      | Yes      | Human/tooling label such as `react`, `vue`, or `ketjs`.             |
+| `command`        | Yes      | Nonempty argv array executed directly, without a shell.             |
+| `cwd`            | No       | Working directory relative to the bundle; defaults to `.`.          |
+| `readyPath`      | No       | Origin-relative 2xx readiness route; defaults to `/`.               |
+| `screenBasePath` | No       | Origin-relative screen route prefix ending in `/`; defaults to `/`. |
+| `readyTimeoutMs` | No       | Startup timeout from 100–120000 milliseconds; defaults to 15000.    |
+| `$schema`        | No       | Schema URL/path for editor completion.                              |
+
+The command may interpolate `{host}`, `{port}`, and `{atlasDirectory}`. The corresponding environment values are `KETATLAS_HOST`, `KETATLAS_HTML_PORT`, and `KETATLAS_PROJECT_DIR`. The sidecar changes relative resolution for registered screens and screen-node URL overrides only; note/external references remain relative to `atlas.json`.
+
+`audit` validates a discovered sidecar without running it. `serve --renderer` explicitly authorizes command execution and starts the framework on `--html-port`.
 
 ## Screen
 
@@ -22,7 +41,7 @@ All viewer UI is English. Project titles, descriptions and labels can use any la
 | ------------- | -------- | --------------------------------------------------------------------- |
 | `id`          | Yes      | Unique across the atlas.                                              |
 | `title`       | Yes      | Human-readable screen name.                                           |
-| `url`         | Yes      | Relative URL or HTTP(S) URL for actual HTML.                          |
+| `url`         | Yes      | Relative or HTTP(S) URL for the actual rendered page.                 |
 | `viewport`    | No       | Overrides the atlas viewport. Both dimensions are integers, 160–4096. |
 | `description` | No       | Context inherited by its nodes.                                       |
 | `badge`       | No       | Small card footer label; defaults to `Preview`.                       |

package/docs/integration.md

@@ -62,6 +62,7 @@ The browser implementation has no React dependency. Instantiate it after mount;
 | Option             | Default                                    | Purpose                                                                         |
 | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
 | `baseURL`          | Page URL; JSON response URL in `loadAtlas` | Resolve screen and node URLs.                                                   |
+| `screenBaseURL`    | `baseURL`                                  | Resolve registered screens and screen-node URL overrides on another origin.     |
 | `assetBaseURL`     | Package directory                          | Public directory containing `styles/` and `assets/`; must end in `/`.           |
 | `initialFlow`      | First flow                                 | Initial flow ID.                                                                |
 | `theme`            | `light`                                    | `light` or `dark`.                                                              |
@@ -101,7 +102,9 @@ These are viewer events. KetAtlas does not inspect or synchronize navigation ins
 
 ## Embedding behavior
 
-Iframe previews are sandboxed. Scripts and forms work by default, but the page has an opaque origin: authenticated fetch, storage, some module imports, and other same-origin features can require additional permissions. Only add `allow-same-origin` for trusted prototypes. Combining it with scripts on a same-origin page weakens sandbox isolation.
+Iframe previews are sandboxed. Scripts and forms work by default, but a static page has an opaque origin: authenticated fetch, storage, some module imports, and other same-origin features can require additional permissions. Only add `allow-same-origin` for trusted prototypes. Combining it with scripts on a same-origin page weakens sandbox isolation.
+
+The CLI's native renderer mode uses `screenBaseURL` and adds `allow-same-origin` automatically. Its HTML server is a separate loopback origin from the viewer, so framework routes can use native modules and same-origin resources without gaining same-origin access to the viewer/control page.
 
 Remote pages can reject framing using CSP or `X-Frame-Options`. KetAtlas cannot override that. Use a permitted embedded route or the **Open in new tab** action. Test links/forms with the default sandbox before sharing a project.
 

package/docs/migration.md

@@ -1,5 +1,18 @@
 # Migrating the KétSuite mobile map
 
+## From copied HTML to a 0.4 native renderer
+
+Version 0.4 does not require static projects to change. When an atlas copied or reconstructed markup from a React, Vue, KetJS, or other framework, remove that duplicate implementation instead:
+
+1. Extract one shared screen presenter in the product's framework and compose canonical design-system components there.
+2. Keep business loaders and Atlas fixtures separate; pass both into the same presenter shape.
+3. Reuse that presenter and its styles across all atlases in the workspace.
+4. Add namespaced Atlas routes and `atlas.renderer.json` beside each manifest.
+5. Change screen URLs to paths relative to the declared `screenBasePath`.
+6. Run `ketatlas@0.4.0 audit`, then use `serve --renderer` and verify both origins in a browser.
+
+Do not migrate to a JSON component tree or another generated HTML layer. The framework component remains the screen source of truth.
+
 ## Bundle layout backfill
 
 Current projects use `<name>.ketatlas/atlas.json`. For a legacy self-contained Atlas directory, rename the whole directory so relative screen, style and asset URLs remain unchanged. When `atlas.json` shares a directory with unrelated application code, create a sibling `<name>.ketatlas` bundle, move only Atlas-owned files, and update relative URLs for resources that intentionally remain outside it. Keep one canonical manifest, then run `ketatlas discover <workspace> --json`, `ketatlas validate <name>.ketatlas`, and `ketatlas audit <name>.ketatlas --strict`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ketatlas",
-  "version": "0.3.0",
-  "description": "Interactive HTML maps for screens, workflows, and user journeys.",
+  "version": "0.4.0",
+  "description": "Interactive framework-native maps for screens, workflows, and user journeys.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,8 @@
       "import": "./src/index.js"
     },
     "./schema.json": "./schema.json",
-    "./progress.schema.json": "./progress.schema.json"
+    "./progress.schema.json": "./progress.schema.json",
+    "./renderer.schema.json": "./renderer.schema.json"
   },
   "bin": {
     "ketatlas": "bin/ketatlas.js"
@@ -37,19 +38,21 @@
     "skills",
     "docs",
     "CHANGELOG.md",
-    "progress.schema.json"
+    "progress.schema.json",
+    "renderer.schema.json"
   ],
   "scripts": {
     "dev": "node bin/ketatlas.js serve examples/atlas.json --root . --port 4178",
+    "build:demo": "node scripts/build-demo.mjs",
     "validate": "node bin/ketatlas.js audit examples/atlas.json --root . && node bin/ketatlas.js audit templates/basic/atlas.json && node bin/ketatlas.js audit templates/web/atlas.json && node bin/ketatlas.js audit templates/process/atlas.json",
     "test": "node --test tests/*.test.js",
-    "test:e2e": "node tests/browser.mjs && node tests/progress-browser.mjs",
+    "test:e2e": "node tests/browser.mjs && node tests/progress-browser.mjs && node tests/renderer-browser.mjs",
     "check": "npm run validate && npm test && npm run test:e2e",
     "format": "prettier --write src styles/ketatlas.css bin scripts docs examples starter templates skills tests '*.md' '*.json' .github/workflows",
     "format:check": "prettier --check src styles/ketatlas.css bin scripts docs examples starter templates skills tests '*.md' '*.json' .github/workflows",
     "prepare:assets": "node scripts/prepare-assets.mjs",
     "prepack": "node scripts/verify-assets.mjs",
-    "prepare:templates": "node scripts/schema.mjs && node scripts/progress-schema.mjs && node scripts/prepare-templates.mjs",
+    "prepare:templates": "node scripts/schema.mjs && node scripts/progress-schema.mjs && node scripts/renderer-schema.mjs && node scripts/prepare-templates.mjs",
     "test:package": "node tests/package.mjs"
   },
   "devDependencies": {

package/renderer.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "KetAtlas native renderer configuration",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "framework": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "command": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "\\S"
+      }
+    },
+    "cwd": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "readyPath": {
+      "type": "string",
+      "pattern": "^/"
+    },
+    "screenBasePath": {
+      "type": "string",
+      "pattern": "^/.*/$|^/$"
+    },
+    "readyTimeoutMs": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 120000
+    }
+  },
+  "required": ["version", "framework", "command"],
+  "additionalProperties": false
+}

package/skills/ketatlas/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ketatlas
-description: Create or update interactive HTML mockups and workflow maps in KetAtlas format. Use when a user requests KetAtlas output, an atlas.json project, or draggable flows connecting real HTML screens; also use to scaffold, serve, or audit an existing atlas.
+description: Create or update interactive framework-native mockups and workflow maps in KetAtlas format. Use when a user requests KetAtlas output, an atlas.json project, or draggable flows connecting screens rendered by HTML, React, Vue, KetJS, or another product framework; also use to scaffold, serve, or audit an existing atlas.
 ---
 
 # KetAtlas
 
-Deliver an editable `<name>.ketatlas/` bundle containing actual HTML screens and a version 1 `atlas.json` that `npx ketatlas serve` can open. KetAtlas supplies the draggable viewer; the agent authors the product mockups and their flow graph. A screenshot gallery or a Mermaid diagram alone is not this deliverable.
+Deliver an editable `<name>.ketatlas/` bundle with a version 1 `atlas.json` that `npx ketatlas@0.4.0 serve` can open. KetAtlas supplies the draggable viewer; the selected product framework owns screen rendering. A screenshot gallery or a Mermaid diagram alone is not this deliverable.
 
 ## Read the brief and choose the scope
 
@@ -32,25 +32,68 @@ Before scaffolding or editing visual screens, ask the user to choose a design sy
 
 Do not start visual screen implementation until the user answers. If the user explicitly delegates the choice to the agent, treat that as **Auto**. This selection prompt is still required for an existing atlas; its documented/current system may be offered as the likely choice. A request that already names a system or supplies a design-system source counts as an answer and must not be asked again.
 
-Inspect the selected source, its usage documentation, tokens, components, icons, and relevant product patterns before mocking. Reuse its actual public assets and composition patterns when available; do not merely imitate its color palette. Replace incompatible starter styling rather than layering multiple design systems. For one shared iOS/Android prototype, create one HTML implementation with reusable styles and states unless separate variants were requested.
+Inspect the selected source, its usage documentation, tokens, components, icons, relevant product patterns, and implementation framework before mocking. Reuse its actual public components, assets, and composition patterns when available; do not merely imitate its color palette. Replace incompatible starter styling rather than layering multiple design systems. For one shared iOS/Android prototype, create one framework implementation with reusable presenters and states unless separate variants were requested.
 
-Prefer a local adapter descriptor with `schemaVersion: "ketatlas.design-system-adapter.v1"` when the selected design system provides one. Discover it from the user-supplied path, a repository `design-system.atlas.json`, or the package's documented `./atlas/profile.json` export. Read the descriptor before using its assets or commands; do not assume capabilities it does not declare. If there is no adapter, use the design system through its documented HTML/CSS interface and record that no reproducible adapter lock is available.
+Prefer a local adapter descriptor with `schemaVersion: "ketatlas.design-system-adapter.v1"` when the selected design system provides one. Discover it from the user-supplied path, a repository `design-system.atlas.json`, or the package's documented `./atlas/profile.json` export. Read the descriptor before using its assets or commands; do not assume capabilities it does not declare. If there is no adapter, use the design system through its documented native framework interface and record that no reproducible adapter lock is available.
 
 For Két Design System, prefer the descriptor exported at `@ketvietlab/design-system/atlas/profile.json` and its declared `ket-design-system-atlas` materializer. Read that descriptor for asset names, root attributes, slots, hooks, and state ownership instead of hard-coding them.
 
-Keep the atlas self-contained and dependency-free. Do not add a consumer package installation or custom bundler just to use a design system. Materialize or copy permitted static assets only when the selected source supports it, preserve required notices, and do not rely on remote runtime assets when the requested mockup must work offline. Record the selected system, source URL/path, pinned version or commit when known, adapter/asset strategy, and any license or fidelity limitation in the bundle README.
+## Use the product's native framework
+
+Inspect the product and selected design-system source before choosing how screens render. Match their implementation framework exactly:
+
+- React components render through the product's React runtime and routes.
+- Vue components render through the product's Vue runtime and routes.
+- KetJS server components render on a KetJS server. Do not reconstruct their output with client-side DOM builders or handwritten HTML strings.
+- Apply the equivalent rule to any other declared framework. Use static HTML only when the product is actually static HTML, no framework exists, or the user explicitly requests static HTML.
+
+Choose the existing product framework first. If there is no product implementation yet, use the selected design system's canonical framework. If neither declares a framework, static HTML is the fallback. Preserve the rendering model as well as the library name: server components must render on their server, while client components remain native client components. If the product and design system require incompatible frameworks and no documented adapter exists, pause for a design-system/framework decision instead of translating either implementation.
+
+Do not create a second component representation for Atlas. In particular, do not translate framework components into a KetAtlas-specific component JSON DSL, duplicate their markup in `screens/`, or imitate them with local CSS. Fix an incorrect canonical design-system component or adapter at its source before continuing; do not hide the mismatch in an Atlas-only override.
+
+Separate screen presentation from business behavior. A screen presenter receives a deterministic view model and composes the real design-system components. Atlas routes call that presenter with fixtures; production routes call the same presenter with real data, permissions, and actions. Atlas may select fixture states through routes or query parameters, but it does not own product markup.
+
+When a workspace contains multiple atlases, put reusable presenters, component compositions, fixture factories, tokens, and Atlas route helpers in one shared framework module outside the individual `.ketatlas` bundles. Each bundle owns only its flow graph, per-atlas fixture/state declarations, renderer sidecar, and documentation. Never copy shared component or style files from one atlas to another. Prefer one native renderer application that exposes namespaced `screenBasePath` routes for all atlases.
+
+Keep static atlas bundles self-contained and dependency-free. For framework-native atlases, reuse the product's existing package manifest, lockfile, framework server, and shared UI source outside the atlas bundle; do not add another package installation or bundler inside `.ketatlas`. Materialize or copy permitted assets only for a genuinely static product. Record the selected system, implementation framework, shared module location, source URL/path, pinned version or commit when known, adapter strategy, and any license or fidelity limitation in the bundle README.
+
+### Declare the native renderer
+
+Place `atlas.renderer.json` beside `atlas.json`. This sidecar is the executable renderer contract and does not change the version 1 workflow schema. Use an argument array, never a shell command string:
+
+```json
+{
+  "$schema": "https://unpkg.com/ketatlas@0.4.0/renderer.schema.json",
+  "version": 1,
+  "framework": "react",
+  "command": ["npm", "run", "atlas:serve", "--", "--host", "{host}", "--port", "{port}"],
+  "cwd": "../..",
+  "readyPath": "/__atlas/ready",
+  "screenBasePath": "/__atlas/customer-care/"
+}
+```
+
+`cwd` is relative to the bundle. KetAtlas substitutes `{host}`, `{port}`, and `{atlasDirectory}` and also provides `KETATLAS_HOST`, `KETATLAS_HTML_PORT`, and `KETATLAS_PROJECT_DIR`. `readyPath` must return HTTP 2xx when the framework server is ready. `screenBasePath` is origin-relative and ends in `/`; screen URLs in `atlas.json` resolve beneath it. Multiple atlases may use the same command and shared renderer source while choosing different namespaced base paths.
+
+Start the viewer and HTML renderer on separate loopback ports:
+
+```sh
+npx --yes ketatlas@0.4.0 serve ./tasks/mockups.ketatlas --renderer --port 60550 --html-port 60551
+```
+
+`--renderer` is an explicit trust boundary because it executes the declared local command. The viewer remains on the first port; framework HTML, scripts, styles, assets, and same-origin requests stay on the second. Do not proxy or rebuild framework output in the viewer process.
 
 ## Scaffold or extend
 
 Node.js 22 or newer is required. For a new, empty destination:
 
 ```sh
-npx --yes ketatlas scaffold ./tasks/mockups.ketatlas --template basic
+npx --yes ketatlas@0.4.0 scaffold ./tasks/mockups.ketatlas --template basic
 ```
 
 Choose `basic` for mobile, `web` for desktop, or `process` for steps without UI. These are starting examples, not required product flows. Replace their sample content with the requested product.
 
-For an existing atlas, read and edit its JSON and screen files directly. Preserve useful IDs and URLs; scaffold refuses a nonempty directory and has no `--force` option. Pin the CLI version in the README commands or use a global installation. A consumer atlas does not need a local package installation.
+For an existing atlas, read its JSON, renderer contract, and referenced framework source or static screen files. Preserve useful IDs and URLs; scaffold refuses a nonempty directory and has no `--force` option. Pin the CLI version in the README commands or use a global installation. A consumer atlas does not need a local KetAtlas installation.
 
 ### Backfill legacy projects
 
@@ -75,7 +118,9 @@ tasks/mockups.ketatlas/
   README.md                Run commands, flow coverage, assumptions, verification
 ```
 
-Keep product assets inside the served directory when practical. Deliver JSON/schema, screen HTML/CSS/JavaScript, assets, and documentation. Do not scaffold a `package.json`, lockfile, `node_modules`, asset build scripts, or a copied viewer/test harness in the atlas folder just to use KetAtlas. The installed CLI supplies scaffold, serve, validate, and audit. Browser verification can use the agent's external tooling. Preserve unrelated application tooling when extending an existing repository.
+A framework-native bundle replaces `screens/` and copied styles with `atlas.renderer.json`; its actual routes, shared presenters, fixtures, and styles stay in the product's framework source. Multiple bundles should point to the same shared renderer module instead of growing parallel component implementations.
+
+For static mode, keep product assets inside the served directory when practical. For native mode, deliver JSON/schema, `atlas.renderer.json`, per-atlas fixtures or declarations, and documentation while changing shared framework source in its owning product module. Do not scaffold a `package.json`, lockfile, `node_modules`, asset build scripts, or a copied viewer/test harness in the atlas folder just to use KetAtlas. The installed CLI supplies scaffold, serve, validate, and audit. Browser verification can use the agent's external tooling. Preserve unrelated application tooling when extending an existing repository.
 
 Do not create a wrapper viewer or a custom canvas: `serve ./tasks/mockups.ketatlas` provides it.
 
@@ -97,7 +142,7 @@ Core rules:
 - Set `column` and `row` explicitly for branches. Both are integers from 0 to 100; no two nodes in a flow share a cell. This is a grid, not an automatic graph layout engine.
 - Set the atlas `viewport` or a screen override to the intended layout size. The mobile default is 390 × 844; choose desktop dimensions from the brief. Width and height are integers from 160 to 4096.
 
-Example structure, to adapt to the actual product and HTML files:
+Example static structure; for native routes, replace the `.html` paths with paths relative to `screenBasePath`:
 
 ```json
 {
@@ -144,23 +189,25 @@ Example structure, to adapt to the actual product and HTML files:
 
 ## Build the actual screens
 
-Make each screen a complete HTML document with a viewport meta tag and `body { margin: 0; }`. Keep product content padding, but do not wrap the page in a second phone bezel, presentation frame, reviewer sidebar, or outer mockup margin. The iframe is the screen boundary.
+For static HTML mode, make each screen a complete HTML document with a viewport meta tag and `body { margin: 0; }`. For framework-native mode, make every declared screen URL a directly addressable framework route whose response is a complete document at the selected state. Keep product content padding, but do not wrap the page in a second phone bezel, presentation frame, reviewer sidebar, or outer mockup margin. The iframe is the screen boundary.
 
-Use shared CSS/components and deterministic mock data. States referenced by node URLs must render directly when opened or refreshed, without requiring a previous login or click. Implement the relevant buttons, forms, validation feedback, and navigation in HTML/JavaScript: graph arrows do not wire screen interactions automatically.
+Use the shared framework presenters/styles and deterministic fixtures. States referenced by node URLs must render directly when opened or refreshed, without requiring a previous login or click. Implement the relevant buttons, forms, validation feedback, and navigation in the native framework: graph arrows do not wire screen interactions automatically.
 
-The default iframe sandbox allows scripts and forms but gives the page an opaque origin. Prefer ordinary links, classic scripts, inline mock data, URL parameters, and in-memory state for portable prototypes. Storage, authenticated fetch, and some module imports can fail in this sandbox. Test in **Try this screen**, not just a standalone tab; do not solve a prototype issue by weakening the viewer's sandbox.
+Static screens use an opaque sandbox by default. Native renderer mode places screens on a distinct origin and enables `allow-same-origin` there so framework modules and same-origin assets work without granting access to the viewer origin. Keep framework routes trusted and loopback-only. Test in **Try this screen**, not just a standalone tab.
 
 ## Validate and hand off
 
 Run from the user's project with the same root for audit and serve:
 
 ```sh
-npx --yes ketatlas discover . --json
-npx --yes ketatlas validate ./tasks/mockups.ketatlas
-npx --yes ketatlas audit ./tasks/mockups.ketatlas --strict
-npx --yes ketatlas serve ./tasks/mockups.ketatlas
+npx --yes ketatlas@0.4.0 discover . --json
+npx --yes ketatlas@0.4.0 validate ./tasks/mockups.ketatlas
+npx --yes ketatlas@0.4.0 audit ./tasks/mockups.ketatlas --strict
+npx --yes ketatlas@0.4.0 serve ./tasks/mockups.ketatlas --renderer --port 60550 --html-port 60551
 ```
 
+Omit `--renderer` and `--html-port` only for a genuinely static atlas. Audit validates a discovered `atlas.renderer.json` and treats screen URLs as framework routes, but deliberately does not execute the command. The browser check must therefore prove the ready route, every requested screen state, framework scripts/styles, and important interactions through the two-port viewer.
+
 Use `--root .` on both audit and serve if screens or assets intentionally live outside the atlas directory but inside the project. Use `--port 4180` or another free port when necessary. Refresh after file edits; there is no hot reload.
 
 For local projects, fix structural errors, missing assets, and unreachable nodes until strict audit passes. Remote screen/assets URLs produce warnings and are not fetched by audit: when those are intentional, run the normal audit, report the warnings, and verify embedding separately rather than claiming a strict pass. With `audit --json --strict`, check the exit status and warnings as well as `valid`.

package/src/config.js

@@ -166,7 +166,7 @@ export class AtlasValidationError extends Error {
     this.errors = result.errors;
   }
 }
-export function normalizeAtlas(input, baseURL) {
+export function normalizeAtlas(input, baseURL, screenBaseURL = baseURL) {
   const result = validateAtlas(input);
   if (!result.valid) throw new AtlasValidationError(result);
   const data = structuredClone(input);
@@ -174,7 +174,7 @@ export function normalizeAtlas(input, baseURL) {
   data.viewport ??= { width: 390, height: 844 };
   data.screens ??= [];
   for (const s of data.screens) {
-    s.url = safeURL(s.url, baseURL);
+    s.url = safeURL(s.url, screenBaseURL);
     s.viewport ??= { ...data.viewport };
   }
   for (const f of data.flows) {
@@ -186,7 +186,7 @@ export function normalizeAtlas(input, baseURL) {
       n.column ??= i;
       n.row ??= 0;
       n.type ??= n.screen ? "screen" : "note";
-      if (n.url) n.url = safeURL(n.url, baseURL);
+      if (n.url) n.url = safeURL(n.url, n.type === "screen" ? screenBaseURL : baseURL);
     });
     f.edges.forEach((edge) => {
       edge.kind ??= "primary";

package/src/index.d.ts

@@ -114,6 +114,8 @@ export interface AtlasOptions {
   progressToken?: string;
   /** Relative screen URLs resolve against this URL. loadAtlas uses the JSON URL by default. */
   baseURL?: string;
+  /** Override only relative screen and screen-node URLs, for a separate framework renderer. */
+  screenBaseURL?: string;
   /** Public directory containing styles/ and assets/, ending in /. Needed when bundling the JS. */
   assetBaseURL?: string;
   initialFlow?: string;

package/src/index.js

@@ -26,7 +26,11 @@ const cameraMotion = Object.freeze({
 export function createAtlas(container, input, options = {}) {
   if (!(container instanceof HTMLElement))
     throw new TypeError("createAtlas requires an HTML element.");
-  const config = normalizeAtlas(input, options.baseURL || document.baseURI);
+  const config = normalizeAtlas(
+    input,
+    options.baseURL || document.baseURI,
+    options.screenBaseURL || options.baseURL || document.baseURI,
+  );
   const progressData = requireProgress(options.progress || emptyProgress(), config);
   const maxPreviews = options.maxPreviews ?? 24,
     previewThreshold = options.previewThreshold ?? 0.3;

package/templates/basic/README.md

@@ -3,12 +3,12 @@
 This directory must keep its `.ketatlas` suffix. Run with Node.js 22 or newer:
 
 ```sh
-npx ketatlas serve .
-npx ketatlas audit . --strict
+npx --yes ketatlas@0.4.0 serve .
+npx --yes ketatlas@0.4.0 audit . --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas and use ketatlas serve .
+This starter is intentionally static. Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. For React, Vue, KetJS, or another framework, use atlas.renderer.json and shared framework presenters instead of copying this static implementation.
 
-Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
+Edit the HTML files in screens/ to replace the sample static product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
 
-Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.
+Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with npx --yes ketatlas@0.4.0 progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.

package/templates/process/README.md

@@ -3,12 +3,12 @@
 This directory must keep its `.ketatlas` suffix. Run with Node.js 22 or newer:
 
 ```sh
-npx ketatlas serve .
-npx ketatlas audit . --strict
+npx --yes ketatlas@0.4.0 serve .
+npx --yes ketatlas@0.4.0 audit . --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas and use ketatlas serve .
+This starter is intentionally static. Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. For React, Vue, KetJS, or another framework, use atlas.renderer.json and shared framework presenters instead of copying this static implementation.
 
 This template models a process without HTML screens. Add a screen registry and screen nodes when needed.
 
-Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.
+Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with npx --yes ketatlas@0.4.0 progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.

package/templates/web/README.md

@@ -3,12 +3,12 @@
 This directory must keep its `.ketatlas` suffix. Run with Node.js 22 or newer:
 
 ```sh
-npx ketatlas serve .
-npx ketatlas audit . --strict
+npx --yes ketatlas@0.4.0 serve .
+npx --yes ketatlas@0.4.0 audit . --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas and use ketatlas serve .
+This starter is intentionally static. Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. For React, Vue, KetJS, or another framework, use atlas.renderer.json and shared framework presenters instead of copying this static implementation.
 
-Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
+Edit the HTML files in screens/ to replace the sample static product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
 
-Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with ketatlas progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.
+Open **Screens** in the viewer to review or edit delivery progress. Saving writes atlas.progress.json beside the workflow; use --read-only to disable editing. You can initialize records with npx --yes ketatlas@0.4.0 progress . --init. Keep this directory in your own project repository. The schema provides editor completion. See https://github.com/ketvietlab/ketatlas for the full API, CLI, and configuration reference.