ketatlas 0.2.5 → 0.4.0

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,10 +36,14 @@ 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 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 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
 
 Save this template as `mockup-brief.md`, fill in the relevant fields, and ask: **“Use the KetAtlas skill to implement mockup-brief.md.”** The brief stays Markdown; do not add its planning fields to `atlas.json`.
@@ -52,7 +56,8 @@ Save this template as `mockup-brief.md`, fill in the relevant fields, and ask: *
 - Output directory:
 - Target platforms and viewport sizes:
 - Product content language:
-- Design system, existing HTML, and reference files/URLs:
+- Design system choice (Auto/Két/Carbon/Primer/Fluent 2/none/custom source):
+- 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:
@@ -60,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.”**
@@ -76,10 +83,13 @@ For an existing prototype, ask the agent to reuse its HTML and add or update the
 ## Review the result
 
 ```sh
-npx ketatlas serve ./tasks/mobile/atlas.json
-npx ketatlas audit ./tasks/mobile/atlas.json --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 works with the published `ketatlas@0.1.1` format; the skill itself can be distributed through GitHub without waiting for a new npm release.
+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,25 +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
-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 JSON, a schema, HTML/CSS/JavaScript mock screens, assets, and documentation. They do not need a Node package, lockfile, development dependencies, viewer implementation, or build/test scripts to scaffold, 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
 
@@ -32,7 +41,7 @@ The package owns the CLI, viewer, validation, and framework verification. A prod
 | `src/index.d.ts`  | Public TypeScript declarations.                               |
 | `styles/`         | Viewer layout and generated canonical design-system bundles.  |
 | `assets/`         | Local fonts, licenses and provenance manifest.                |
-| `bin/`            | Scaffold, JSON serving, validation and static audit.          |
+| `bin/`            | Bundle discovery, scaffold, serving, validation and audit.    |
 | `templates/`      | Self-contained starting projects included in the npm package. |
 | `examples/`       | Maintainer playground with mobile, web and process flows.     |
 | `scripts/`        | Reproducible assets, templates, schema and package checks.    |
@@ -42,9 +51,9 @@ The package owns the CLI, viewer, validation, and framework verification. A prod
 
 Flows are stacked on one canvas. A row and column grow to fit their largest node, so mobile and desktop aspect ratios can coexist. The layout respects authored grid positions. Arrows use orthogonal routes and a small lane offset; this is not an obstacle-avoiding graph-layout engine. Use nearby grid cells and concise labels for readable large diagrams.
 
-Camera changes use an animation frame and a CSS transform. 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.
+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
 
@@ -60,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,19 +1,19 @@
 # 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
 
 ```sh
-ketatlas scaffold ./customer-journeys --template basic
-ketatlas serve ./customer-journeys/atlas.json
+ketatlas scaffold ./customer-journeys.ketatlas --template basic
+ketatlas serve ./customer-journeys.ketatlas
 ```
 
 Open a card with a double-click. The preview is actual HTML; links and JavaScript inside it can work independently of the map. Edit those files before adding more nodes.
 
 ## 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"`.
@@ -41,7 +79,7 @@ Click a node to highlight incoming/outgoing arrows and follow a next-step button
 ## 5. Audit before sharing
 
 ```sh
-ketatlas audit ./customer-journeys/atlas.json --strict
+ketatlas audit ./customer-journeys.ketatlas --strict
 ```
 
 Keep the JSON and screens in your project's repository. Review changes in pull requests. Share the directory or run the same serve command in the recipient's checkout. No hosted account or service state is required.

package/docs/cli.md

@@ -1,44 +1,64 @@
 # CLI reference
 
-Install once with `npm install --global ketatlas@0.1.1`, or prefix commands with `npx --yes ketatlas@0.1.1`. No dependency installation is required in the consumer directory. `node /path/to/ketatlas/bin/ketatlas.js` is also available to framework maintainers.
+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
 
 ```sh
-ketatlas scaffold ./journeys
-ketatlas scaffold ./approvals --template web
-ketatlas scaffold ./operations --template process
+ketatlas scaffold ./journeys.ketatlas
+ketatlas scaffold ./approvals.ketatlas --template web
+ketatlas scaffold ./operations.ketatlas --template process
 ```
 
 `basic` is the default: two interactive mobile pages and one flow. `web` contains desktop purchase approval pages. `process` contains notes and an external handoff, without HTML screens. Every template includes a local JSON Schema for editor completion and a README. Product HTML and its styles belong to the new project.
 
-`init` is an alias for `scaffold`. The destination must be missing or empty. Existing files are never overwritten; there is no `--force` flag.
+`init` is an alias for `scaffold`. The destination must end in `.ketatlas` and be missing or empty. Existing files are never overwritten; there is no `--force` flag.
+
+## Discover bundles
+
+```sh
+ketatlas discover .
+ketatlas discover . --json
+```
+
+Discovery walks the selected workspace for exact `*.ketatlas/atlas.json` bundles. It skips dependency, generated, cache, Git and vendor directories; it does not parse unrelated JSON. The JSON report contains `version`, `root`, `atlases`, and `errors`, including each atlas title, path, directory, screens and flow count. Invalid bundle manifests are reported and produce exit code 1.
+
+Legacy manifest paths remain valid command arguments, but discovery intentionally ignores them. Migrate a self-contained legacy directory by renaming it to `<name>.ketatlas`; see the bundled skill for mixed-directory migration safeguards.
 
 ## Serve a JSON file
 
 ```sh
-ketatlas serve ./tasks/onboarding/atlas.json
-ketatlas serve ./tasks/onboarding/atlas.json --port 4180
-ketatlas serve ./tasks/onboarding/atlas.json --root .
+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 .
 ```
 
-The tool supplies the viewer page. It validates the JSON at startup, serves your files, and mounts the atlas at `/`. The default file root is the JSON file's directory. Choose `--root` when a relative URL points to a sibling directory outside that default root. The JSON must be inside the selected root.
+The tool supplies the viewer page. It validates the JSON at startup, serves your files, and mounts the atlas at `/`. Passing a `.ketatlas` directory resolves its `atlas.json` and uses the bundle as the file root. Explicit legacy JSON paths still support `--root` when a relative URL points outside the manifest directory.
 
 Open the printed localhost URL. Changes appear after refreshing; there is no hot reload or authoring server state. Use `?flow=your-flow-id` or `?screen=your-screen-id` to open a specific part of the map. An unknown ID falls back to the first flow.
 
 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
 
 ```sh
-ketatlas audit ./atlas.json
-ketatlas audit ./atlas.json --root .. --strict
-ketatlas audit ./atlas.json --json
-ketatlas audit ./atlas.json --json --output audit-report.json
+ketatlas audit ./tasks/onboarding.ketatlas
+ketatlas audit ./tasks/onboarding.ketatlas --strict
+ketatlas audit ./tasks/onboarding.ketatlas --json
+ketatlas audit ./tasks/onboarding.ketatlas --json --output audit-report.json
 ```
 
 Audit checks:
@@ -49,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:
 
@@ -64,7 +85,7 @@ Exit codes:
 ## Validate and version
 
 ```sh
-ketatlas validate ./atlas.json
+ketatlas validate ./tasks/onboarding.ketatlas
 ketatlas --version
 ketatlas --help
 ```
@@ -73,4 +94,4 @@ ketatlas --help
 
 ## Screen progress
 
-`progress <atlas.json> --json` reads the progress record, content revision and unique-screen summary. `--init` creates a missing sidecar. `--set <screen-id> --record <record.json> --expect <revision>` replaces one record with conflict detection. `serve <atlas.json> --read-only` disables local progress writes. See [Screen progress](progress.md) for examples and persistence rules.
+`progress <bundle|atlas.json> --json` reads the progress record, content revision and unique-screen summary. `--init` creates a missing sidecar. `--set <screen-id> --record <record.json> --expect <revision>` replaces one record with conflict detection. `serve <bundle|atlas.json> --read-only` disables local progress writes. See [Screen progress](progress.md) for examples and persistence rules.

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,24 @@
 # 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`.
+
+The CLI continues to accept a direct legacy JSON path so migration can be audited before and after the move. Discovery intentionally reports only the standard bundle pattern.
+
 The original mobile map remains in its project. KetAtlas does not copy its business data or change the mobile repository. The extraction generalizes the viewer; project migration is a separate configuration change.
 
 ## Field mapping

package/docs/progress.md

@@ -71,11 +71,11 @@ Evidence kinds are `pr`, `test`, `release`, `reference`. Required fields: `id`,
 ## Editing locally and from agents
 
 ```sh
-npx --yes ketatlas@0.2.5 serve atlas.json
-npx --yes ketatlas@0.2.5 serve atlas.json --read-only
-npx --yes ketatlas@0.2.5 progress atlas.json --init
-npx --yes ketatlas@0.2.5 progress atlas.json --json
-npx --yes ketatlas@0.2.5 progress atlas.json --set sign-in --record record.json --expect REVISION_FROM_READ
+npx --yes ketatlas serve ./account-access.ketatlas
+npx --yes ketatlas serve ./account-access.ketatlas --read-only
+npx --yes ketatlas progress ./account-access.ketatlas --init
+npx --yes ketatlas progress ./account-access.ketatlas --json
+npx --yes ketatlas progress ./account-access.ketatlas --set sign-in --record record.json --expect REVISION_FROM_READ
 ```
 
 `--init` explicitly creates Unassessed records and refuses an existing progress file. `--set` replaces one complete screen record; preserve existing checklist IDs, evidence and state references. Read the revision with `--json` first. Do not retry a stale revision by blindly substituting a new one: reload and reconcile changes. `updatedAt` is stamped on successful record writes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ketatlas",
-  "version": "0.2.5",
-  "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
+}