ketatlas 0.1.0

package/bin/server.js

@@ -0,0 +1,93 @@
+import { createServer } from "node:http";
+import { realpath, stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { resolve, relative, extname, sep } from "node:path";
+const types = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".woff2": "font/woff2",
+  ".md": "text/plain; charset=utf-8",
+};
+const within = (root, path) => {
+  const r = relative(root, path);
+  return r === "" || (!r.startsWith(".." + sep) && r !== ".." && !r.startsWith(sep));
+};
+/** Local static preview only. Resolves symlinks before checking the root boundary. */
+export async function serve(
+  directory,
+  { port = 4178, host = "127.0.0.1", viewer, packageRoot } = {},
+) {
+  const root = await realpath(resolve(directory));
+  if (!(await stat(root)).isDirectory()) throw new Error("Serve root must be a directory.");
+  const server = createServer(async (req, res) => {
+    const fail = (status, message) => {
+      res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(message);
+    };
+    if (!["GET", "HEAD"].includes(req.method)) return fail(405, "Method not allowed");
+    try {
+      const pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+      if (
+        pathname.includes("\0") ||
+        pathname.includes("\\") ||
+        pathname.split("/").some((part) => part.startsWith("."))
+      )
+        return fail(404, "Not found");
+      if (viewer && pathname === "/") {
+        res.writeHead(200, {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-cache",
+        });
+        res.end(req.method === "HEAD" ? undefined : viewer);
+        return;
+      }
+      let requestRoot = root,
+        requestPath = pathname;
+      if (viewer && pathname.startsWith("/__ketatlas__/")) {
+        requestPath = pathname.slice("/__ketatlas__".length);
+        if (!["src", "styles", "assets"].includes(requestPath.split("/")[1]))
+          return fail(404, "Not found");
+        requestRoot = packageRoot;
+      }
+      let path = resolve(requestRoot, "." + requestPath);
+      if (!within(requestRoot, path)) return fail(404, "Not found");
+      path = await realpath(path);
+      if (!within(requestRoot, path)) return fail(404, "Not found");
+      let info = await stat(path);
+      if (info.isDirectory()) {
+        if (!pathname.endsWith("/")) {
+          res.writeHead(301, { Location: encodeURI(pathname) + "/" });
+          res.end();
+          return;
+        }
+        path = await realpath(resolve(path, "index.html"));
+        if (!within(requestRoot, path)) return fail(404, "Not found");
+        info = await stat(path);
+      }
+      if (!info.isFile()) return fail(404, "Not found");
+      res.writeHead(200, {
+        "Content-Type": types[extname(path)] || "application/octet-stream",
+        "Content-Length": info.size,
+        "Cache-Control": "no-cache",
+        "X-Content-Type-Options": "nosniff",
+      });
+      if (req.method === "HEAD") return res.end();
+      const stream = createReadStream(path);
+      stream.on("error", () => res.destroy());
+      stream.pipe(res);
+    } catch {
+      fail(404, "Not found");
+    }
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  return server;
+}

package/bin/viewer.js

@@ -0,0 +1,20 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+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";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export async function serveAtlas(file, options = {}) {
+  const absolute = await realpath(resolve(file));
+  if (!(await stat(absolute)).isFile()) throw new Error("Expected an atlas JSON file.");
+  const config = JSON.parse(await readFile(absolute, "utf8"));
+  const result = validateAtlas(config);
+  if (!result.valid) throw new AtlasValidationError(result);
+  const root = await realpath(resolve(options.root || dirname(absolute))),
+    rel = relative(root, absolute);
+  if (rel === ".." || rel.startsWith(".." + sep) || rel.startsWith(sep))
+    throw new Error("The JSON file must be inside --root.");
+  const configURL = "/" + rel.split(sep).map(encodeURIComponent).join("/");
+  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});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 });
+}

package/docs/architecture.md

@@ -0,0 +1,57 @@
+# Architecture
+
+KetAtlas is a static browser viewer plus a Node.js command-line toolkit. There is no database, account service, application backend, or runtime npm dependency.
+
+```text
+atlas.json + screen HTML
+        │
+        ├── 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
+```
+
+## Ownership
+
+| Directory         | Responsibility                                                |
+| ----------------- | ------------------------------------------------------------- |
+| `src/config.js`   | DOM-free validation and normalization.                        |
+| `src/layout.js`   | Pure grid sizing and edge routes.                             |
+| `src/index.js`    | Mounting, camera, input, iframe lifecycle and public API.     |
+| `src/template.js` | English viewer shell.                                         |
+| `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.          |
+| `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.    |
+| `tests/`          | Pure logic, CLI/server, browser and installation tests.       |
+
+## Layout and performance
+
+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.
+
+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.
+
+## Isolation and lifecycle
+
+Each mount owns a Shadow DOM subtree, event handlers, a camera, an observer, and an iframe pool. IDs and SVG markers are scoped to that subtree. `destroy()` removes the subtree, disconnects the observer, cancels scheduled painting and closes dialogs. Host CSS and unrelated content are not rewritten.
+
+URL synchronization is opt-in. The CLI enables it; an embedded map does not take ownership of the host URL by default.
+
+## Design provenance
+
+The default theme uses Inter and KetJS's canonical tokens and primitives. `prepare-assets` reads exact source files from a pinned KetJS revision, flattens imports, and emits two bundles: a regular document bundle and a Shadow DOM bundle. The only selector adaptation is `:root` → `:host`; values are unchanged.
+
+`assets/design-system.lock.json` records upstream hashes and generated output hashes. `npm run prepack` verifies them and checks that viewer CSS consumes existing tokens without redefining `--kv-*` values. Upstream capability changes belong in KetJS before changing this pin.
+
+## 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.

package/docs/authoring.md

@@ -0,0 +1,49 @@
+# 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.
+
+## 1. Create a starting point
+
+```sh
+ketatlas scaffold ./customer-journeys --template basic
+ketatlas serve ./customer-journeys/atlas.json
+```
+
+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.
+
+For a desktop page:
+
+```json
+{
+  "id": "dashboard",
+  "title": "Team dashboard",
+  "url": "./screens/dashboard.html",
+  "viewport": { "width": 1440, "height": 900 }
+}
+```
+
+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.
+
+## 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"`.
+
+A repeated screen gets a different node ID but the same `screen` reference. Add a node URL override when it represents a different state. Use process notes for actions outside a UI, so a step does not need a fake screenshot.
+
+## 4. Review from start to outcome
+
+Click a node to highlight incoming/outgoing arrows and follow a next-step button. Drag the canvas, use the minimap, or press F to fit the flow. Press 0 to return to its start. Opening the actual HTML tests the prototype's own behavior; the arrow graph is not an automated user-action script.
+
+## 5. Audit before sharing
+
+```sh
+ketatlas audit ./customer-journeys/atlas.json --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.
+
+The built-in audit finds structural and local-file issues. Add browser E2E tests for your interactive screens, especially forms, navigation, and errors. A design reference is not evidence of an implemented production flow.

package/docs/cli.md

@@ -0,0 +1,70 @@
+# CLI reference
+
+Use `ketatlas` after installing the package, `node /path/to/ketatlas/bin/ketatlas.js` from a checkout, or the npx forms in the [README](../README.md).
+
+## Scaffold
+
+```sh
+ketatlas scaffold ./journeys
+ketatlas scaffold ./approvals --template web
+ketatlas scaffold ./operations --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.
+
+## 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 .
+```
+
+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.
+
+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.
+
+`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
+```
+
+Audit checks:
+
+- Required fields, types, version, valid IDs and unknown properties.
+- Duplicate IDs, missing screen references, invalid edge endpoints, start/end references, and grid collisions.
+- Nodes unreachable from the chosen start, reported as warnings. Cycles and recovery paths are allowed.
+- 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.
+
+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.
+
+Exit codes:
+
+| Code | Meaning                                                                         |
+| ---- | ------------------------------------------------------------------------------- |
+| `0`  | Passed; warnings are allowed unless `--strict` is present.                      |
+| `1`  | Invalid input, missing resources, command failure, or warnings with `--strict`. |
+
+`--json` writes a machine-readable report to stdout. `--output` additionally writes the report to a new file and refuses to overwrite an existing one. The report has `valid`, `summary`, `errors`, `warnings`, `file`, `root`, and `scope`. `valid` reflects errors; with `--strict`, also check the exit code or warnings array.
+
+## Validate and version
+
+```sh
+ketatlas validate ./atlas.json
+ketatlas --version
+ketatlas --help
+```
+
+`validate` checks configuration and graph references only. It is also available as `validateAtlas(data)` in JavaScript. JSON Schema supports editor completion; graph-reference and URL safety checks belong to the runtime validator and audit.

package/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration reference
+
+The [JSON Schema](../schema.json) defines version 1. A generated project contains `ketatlas.schema.json` and references it using `$schema`. The CLI rejects unknown fields so misspellings do not silently change the layout.
+
+## Atlas
+
+| Field         | Required | Default / meaning                                                  |
+| ------------- | -------- | ------------------------------------------------------------------ |
+| `version`     | Yes      | Must be `1`.                                                       |
+| `title`       | Yes      | Project name in the viewer header.                                 |
+| `description` | No       | Project description for tooling; not rendered as a separate panel. |
+| `viewport`    | No       | `{ "width": 390, "height": 844 }`.                                 |
+| `screens`     | No       | Reusable screen definitions; `[]` supports screenless processes.   |
+| `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.
+
+## Screen
+
+| Field         | Required | Meaning                                                               |
+| ------------- | -------- | --------------------------------------------------------------------- |
+| `id`          | Yes      | Unique across the atlas.                                              |
+| `title`       | Yes      | Human-readable screen name.                                           |
+| `url`         | Yes      | Relative URL or HTTP(S) URL for actual HTML.                          |
+| `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`.                       |
+
+The declared viewport determines the iframe's actual layout size. Canvas thumbnails preserve its aspect ratio. Opening a screen uses that same layout size and scales the full frame to the available width without side padding.
+
+## Flow
+
+`id` and `title` are required. `group` and `description` are optional. `nodes` must be nonempty. `edges` is required; use `[]` for a single step. `start` defaults to the first node. `ends` defaults to nodes without outgoing edges; set it explicitly when an outcome also has a return path.
+
+Flow IDs are unique across the atlas. Node IDs are local to a flow. IDs use letters, digits, dots, underscores and hyphens, beginning with a letter or digit.
+
+## Node
+
+```json
+{
+  "id": "retry",
+  "screen": "sign-in",
+  "title": "Session expired",
+  "url": "./screens/sign-in.html?state=expired",
+  "column": 1,
+  "row": 1
+}
+```
+
+`id` is required. A node with `screen` references the registry and defaults to type `screen`. Its optional `title`, `description` and `url` override that screen for this occurrence only.
+
+A node without `screen` defaults to `note` and requires a title. Use `type: "external"` to mark a handoff. These nodes show text rather than an iframe; an optional URL becomes an **Open reference** link in the selected-node panel.
+
+`column` defaults to the node's index in the array and `row` to `0`. Both accept integers from 0 to 100. Two nodes cannot share a cell within one flow. Set columns explicitly on branch nodes; this is a deterministic grid, not automatic graph layout.
+
+## Edge
+
+```json
+{ "from": "verify", "to": "retry", "label": "Code expired", "kind": "conditional" }
+```
+
+`from`, `to` and a nonempty `label` are required. Endpoints reference node IDs in the same flow. `kind` is `primary` (default), `conditional`, or `recovery`. Arrows are orthogonal and labels describe the action or condition.
+
+Cross-flow edges are not part of version 1. Reuse the destination screen in another flow, or add an external/note handoff to explain the boundary. Start and outcome markers express authored intent; clicking them does not invoke a backend operation.

package/docs/integration.md

@@ -0,0 +1,108 @@
+# Integration and API
+
+Use the CLI for a standalone map. Use the JavaScript API when a map belongs inside a documentation portal or another application.
+
+## Plain HTML
+
+Copy the package's `src/`, `styles/`, and `assets/` directories together into a public `vendor/ketatlas/` directory. No build output is required.
+
+```html
+<div id="map" style="height: 800px"></div>
+<script type="module">
+  import { loadAtlas } from "./vendor/ketatlas/src/index.js";
+  const atlas = await loadAtlas(document.querySelector("#map"), "./atlas.json");
+</script>
+```
+
+Serve over HTTP. ES modules and JSON fetch do not support opening the page directly through `file://`. The viewer requires a container with an explicit height (minimum 480px).
+
+## Bundled applications
+
+Install the package and copy `styles/` and `assets/` to the same public directory. For example:
+
+```sh
+npm install ketatlas
+mkdir -p public/ketatlas
+cp -R node_modules/ketatlas/styles node_modules/ketatlas/assets public/ketatlas/
+```
+
+Before an npm release, install from the repository or an archive produced by `npm pack`. When JavaScript is bundled, provide `assetBaseURL` because dynamic stylesheet URLs cannot be inferred by every bundler.
+
+React lifecycle example:
+
+```jsx
+import { useEffect, useRef } from "react";
+import { createAtlas } from "ketatlas";
+
+export function WorkflowMap({ config }) {
+  const container = useRef(null);
+  useEffect(() => {
+    const atlas = createAtlas(container.current, config, {
+      baseURL: new URL("/planning/atlas.json", location.href).href,
+      assetBaseURL: "/ketatlas/",
+    });
+    atlas.ready.catch(console.error);
+    return () => atlas.destroy();
+  }, [config]);
+  return <div ref={container} style={{ height: 800 }} />;
+}
+```
+
+The browser implementation has no React dependency. Instantiate it after mount; do not call `createAtlas` during server-side rendering. Replace a config by destroying and recreating the instance. Input data is cloned before layout and is never mutated.
+
+## Functions
+
+- `createAtlas(container, config, options?)` returns an instance immediately. `await instance.ready` before measuring or navigating it.
+- `loadAtlas(container, url, options?)` fetches JSON and resolves to a ready instance. Relative screen URLs resolve against the JSON response URL, including redirects.
+- `validateAtlas(unknown)` returns `{ valid, errors, warnings }` without requiring a DOM.
+- Invalid configuration throws `AtlasValidationError` during mounting, with an `errors` array containing `{ path, message }` entries.
+
+## Options
+
+| Option             | Default                                    | Purpose                                                                         |
+| ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| `baseURL`          | Page URL; JSON response URL in `loadAtlas` | Resolve screen and node URLs.                                                   |
+| `assetBaseURL`     | Package directory                          | Public directory containing `styles/` and `assets/`; must end in `/`.           |
+| `initialFlow`      | First flow                                 | Initial flow ID.                                                                |
+| `theme`            | `light`                                    | `light` or `dark`.                                                              |
+| `syncUrl`          | `false`                                    | Read/write `flow`/`screen` URL parameters. Enable for only one viewer per page. |
+| `maxPreviews`      | `24`                                       | Maximum mounted canvas iframes, from 1 to 64. The open inspector may add one.   |
+| `previewThreshold` | `0.3`                                      | Below this zoom, canvas cards use placeholders.                                 |
+| `sandbox`          | `allow-scripts allow-forms`                | Space-separated iframe sandbox permissions.                                     |
+| `signal`           | None                                       | AbortSignal for the `loadAtlas` JSON request.                                   |
+
+All UI is English. Labels in project data are rendered as text. Shadow DOM keeps viewer CSS and click handling isolated from the host document. Fonts are registered with one document stylesheet per asset URL; the stylesheet is retained for reuse after teardown.
+
+## Instance methods
+
+| Method                      | Behavior                                                                           |
+| --------------------------- | ---------------------------------------------------------------------------------- |
+| `goToFlow(id)`              | Select a flow and return to its start. Clears the search.                          |
+| `focusNode(flowId, nodeId)` | Select and focus a node.                                                           |
+| `openNode(flowId, nodeId)`  | Open a screen's interactive preview; note nodes open their details.                |
+| `fit()`                     | Fit the current flow.                                                              |
+| `zoomTo(number)`            | Zoom, clamped to 0.18–2.2.                                                         |
+| `getState()`                | Snapshot of flow ID, selected node ID, zoom, pan and counts.                       |
+| `destroy()`                 | Remove the owned viewer, frames, observers and animation work. Safe to call twice. |
+
+Unknown IDs passed to navigation methods throw `RangeError`. Methods after teardown throw, except `getState()` and `destroy()`.
+
+## Events
+
+Listen on the instance's `element` or its containing element. Events bubble and include a `detail` object.
+
+- `ketatlas:flowchange`: `{ flowId }`.
+- `ketatlas:select`: `{ flowId, nodeId }`.
+- `ketatlas:previewopen`: `{ flowId, nodeId, screenId }`.
+- `ketatlas:viewportchange`: `{ x, y, z }`, emitted during canvas painting.
+- `ketatlas:previewerror`: `{ nodeId, url }`, when an iframe reports a load error. Browsers do not reliably report blocked framing or HTTP errors through this event.
+
+These are viewer events. KetAtlas does not inspect or synchronize navigation inside the iframe. Its title remains the screen that was opened; use your own prototype's navigation to continue.
+
+## 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.
+
+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.
+
+The viewer uses native dialog, Shadow DOM, ResizeObserver, container queries and modern CSS. Chromium is covered by the browser suite. Other modern engines should be qualified against your host application before promising support.

package/docs/migration.md

@@ -0,0 +1,35 @@
+# Migrating the KétSuite mobile map
+
+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
+
+| Original mobile reference                  | KetAtlas                                         |
+| ------------------------------------------ | ------------------------------------------------ |
+| `window.MOBILE_SCREENS`                    | `screens` array in `atlas.json`.                 |
+| `screen.label`                             | `screen.title`.                                  |
+| `index.html?screen=ID&state=STATE&embed=1` | Explicit `screen.url` or node `url` override.    |
+| `screen.sourceStatus`                      | Optional `screen.badge`, e.g. `DOC` or `TARGET`. |
+| `window.MOBILE_FLOWS`                      | `flows` array.                                   |
+| `node.key`                                 | `node.id` (string).                              |
+| `node.screenId`                            | `node.screen`.                                   |
+| `node.col` / `node.row`                    | `node.column` / `node.row`.                      |
+| `node.caption`                             | `node.title`.                                    |
+| `node.kind: "external"`                    | `node.type: "external"`.                         |
+| `flow.end`                                 | `flow.ends`.                                     |
+| `edge.tone: "main"`                        | `edge.kind: "primary"`.                          |
+| `edge.tone: "branch"`                      | `edge.kind: "conditional"`.                      |
+| `edge.tone: "recovery"`                    | `edge.kind: "recovery"`.                         |
+
+Keep the existing screen IDs. Give repeated states unique node IDs, but reuse the screen reference. Materialize the old `state` field into the preview URL rather than teaching the framework about mobile-specific states.
+
+## Migration sequence
+
+1. Export the screen and flow registries into the version 1 JSON contract above.
+2. Keep existing HTML screens in the mobile project. Set relative URLs against the new JSON location and use the clean `embed=1` route.
+3. Set the default viewport to 390 × 844. Keep DOC/TARGET source labels if useful to reviewers.
+4. Run `ketatlas audit atlas.json --root <project-root>` and resolve diagnostics.
+5. Run `ketatlas serve atlas.json --root <project-root>` and compare the existing 22 journeys, 108 screen IDs, and 162 edges against the exported graph.
+6. Re-run the project's browser interactions under the iframe sandbox. Only enable additional sandbox permissions for trusted HTML when its behavior requires them.
+
+KetAtlas UI is English. Vietnamese business labels inside the project's configuration and HTML can remain Vietnamese.

package/docs/releasing.md

@@ -0,0 +1,40 @@
+# Releasing KetAtlas
+
+The npm package name and executable are both **ketatlas**. The package is ESM, includes TypeScript declarations, and ships the CLI, viewer modules, styles, fonts, licenses, schema and templates. Development dependencies, examples, test results and the sibling mobile project are not required at runtime.
+
+## Verify the exact package
+
+```sh
+npm ci
+npx playwright install chromium
+npm run check
+npm run test:package
+npm run format:check
+npm pack --dry-run
+```
+
+The package test creates a real archive, invokes its CLI through `npm exec` without a registry lookup, scaffolds a project outside the repository, audits it, and starts its JSON viewer. This catches missing files and accidental reliance on a maintainer checkout.
+
+## Publish
+
+An npm release is an explicit maintainer action. Confirm npm ownership of the unscoped `ketatlas` name and authenticate with an account allowed to publish it. Do not put credentials in repository files.
+
+For interactive publishing, [configure two-factor authentication on your npm account](https://docs.npmjs.com/configuring-two-factor-authentication/) and complete the verification requested during publication. A successful `npm whoami` confirms login but does not guarantee that publishing authentication requirements are met. Keep recovery codes and credentials private.
+
+```sh
+npm whoami
+npm publish --access public
+```
+
+Bump `package.json` and `package-lock.json` together before subsequent releases, record the change in `CHANGELOG.md`, and tag the released commit. A Git push alone does not publish npm. The CI workflow verifies pushes and pull requests; it does not publish automatically.
+
+After publishing, verify the registry distribution outside the checkout:
+
+```sh
+npx ketatlas@0.1.0 --version
+npx ketatlas@0.1.0 scaffold /tmp/ketatlas-release-check
+npx ketatlas@0.1.0 audit /tmp/ketatlas-release-check/atlas.json --strict
+npx ketatlas@0.1.0 serve /tmp/ketatlas-release-check/atlas.json
+```
+
+Before publication, use `npx --yes --package=github:ketvietlab/ketatlas ketatlas ...` or a local `.tgz` archive. Pin a commit or released version for reproducible team workflows.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "ketatlas",
+  "version": "0.1.0",
+  "description": "Interactive HTML maps for screens, workflows, and user journeys.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ketvietlab/ketatlas.git"
+  },
+  "homepage": "https://github.com/ketvietlab/ketatlas#readme",
+  "bugs": "https://github.com/ketvietlab/ketatlas/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./schema.json": "./schema.json"
+  },
+  "bin": {
+    "ketatlas": "bin/ketatlas.js"
+  },
+  "files": [
+    "src",
+    "styles",
+    "assets",
+    "bin",
+    "schema.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "templates",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev": "node bin/ketatlas.js serve examples/atlas.json --root . --port 4178",
+    "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",
+    "check": "npm run validate && npm test && npm run test:e2e",
+    "format": "prettier --write src styles/ketatlas.css bin scripts docs examples starter templates tests '*.md' '*.json' .github/workflows",
+    "format:check": "prettier --check src styles/ketatlas.css bin scripts docs examples starter templates 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/prepare-templates.mjs",
+    "test:package": "node tests/package.mjs"
+  },
+  "devDependencies": {
+    "@fontsource-variable/inter": "5.3.0",
+    "ajv": "8.18.0",
+    "lucide-static": "1.40.0",
+    "playwright": "1.62.1",
+    "prettier": "3.6.2"
+  }
+}