ketatlas 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — Initial scaffold
+
+- Standalone `ketatlas scaffold`, `serve <atlas.json>`, `audit`, and `validate` commands.
+- Basic, web and screenless process templates with a local configuration schema.
+- English HTML viewer with pan, zoom, touch pinch, search, minimap, labelled arrows and interactive previews.
+- Mobile and desktop viewport sizes, repeated screen states and process/external nodes.
+- Isolated JavaScript embedding API, lifecycle methods, events and TypeScript declarations.
+- Canonical KetJS design system with pinned provenance and offline assets.
+- Static audits, CLI/server tests, browser evidence and packed-install verification.
+
+This entry describes the source version; it does not confirm publication to npm.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KETVIET JSC, Vietnam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,10 @@
+# Third-party notices
+
+KetAtlas is maintained by KETVIET JSC under the MIT license.
+
+- The viewer originated from KétSuite's HTML flow-map prototype, then was extracted into this independent package. No mobile app code or business data is bundled.
+- Default tokens and UI primitives: `@ketvietlab/design-system` from [KetJS](https://github.com/ketvietlab/ketjs), MIT. Exact source revision and file hashes are recorded in `assets/design-system.lock.json`. Generated output only adapts root selectors to a Shadow DOM host; token values are unchanged. See `assets/KETJS-LICENSE`.
+- Inter Variable: `@fontsource-variable/inter` 5.3.0, SIL Open Font License. See `assets/INTER-LICENSE`.
+- Icons: Lucide 1.40.0, ISC. See `assets/LUCIDE-LICENSE`.
+
+The default theme and these notices are included in generated projects and npm archives.

package/README.md

@@ -0,0 +1,130 @@
+# KetAtlas
+
+**Scaffold, serve, and audit interactive HTML 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.
+
+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.
+
+## Start from this repository
+
+```sh
+git clone git@github.com:ketvietlab/ketatlas.git
+cd ketatlas
+npm ci
+npm run dev
+```
+
+Open **http://127.0.0.1:4178**. The playground includes mobile sign-in, a desktop approval flow, and a fulfilment process.
+
+Create your own project:
+
+```sh
+node bin/ketatlas.js scaffold ../my-atlas
+node bin/ketatlas.js serve ../my-atlas/atlas.json
+node bin/ketatlas.js audit ../my-atlas/atlas.json --strict
+```
+
+No wrapper HTML is needed. Edit `atlas.json` and the files under `screens/`, then refresh the browser.
+
+## Run through npx
+
+Run immediately from a local checkout, including before the first push or npm release:
+
+```sh
+npx --yes --package ~/dev/ketatlas ketatlas scaffold my-atlas
+npx --yes --package ~/dev/ketatlas ketatlas serve my-atlas/atlas.json
+npx --yes --package ~/dev/ketatlas ketatlas audit my-atlas/atlas.json --strict
+```
+
+Replace `~/dev/ketatlas` with your checkout path. This uses the local package, not an npm registry release.
+
+Once the source has been pushed to GitHub, run without cloning it yourself:
+
+```sh
+npx --yes --package=github:ketvietlab/ketatlas ketatlas scaffold my-atlas
+npx --yes --package=github:ketvietlab/ketatlas ketatlas serve my-atlas/atlas.json
+npx --yes --package=github:ketvietlab/ketatlas ketatlas audit my-atlas/atlas.json
+```
+
+After `ketatlas` has been published to npm, the short form is:
+
+```sh
+npx ketatlas scaffold my-atlas --template web
+npx ketatlas serve my-atlas/atlas.json
+npx ketatlas audit my-atlas/atlas.json --strict
+```
+
+The repository does not imply an npm release. Package installation is tested from the actual `.tgz` archive; release instructions are in [Releasing](docs/releasing.md).
+
+## One file describes the journey
+
+```json
+{
+  "version": 1,
+  "title": "Customer onboarding",
+  "screens": [
+    { "id": "welcome", "title": "Welcome", "url": "./screens/welcome.html" },
+    { "id": "home", "title": "Workspace", "url": "./screens/home.html" }
+  ],
+  "flows": [
+    {
+      "id": "onboarding",
+      "title": "Join a workspace",
+      "nodes": [
+        { "id": "start", "screen": "welcome" },
+        { "id": "finish", "screen": "home" }
+      ],
+      "edges": [{ "from": "start", "to": "finish", "label": "Continue" }]
+    }
+  ]
+}
+```
+
+URLs resolve relative to the JSON file. Nodes default to a left-to-right row. Set `column` and `row` for branches; set each screen's `viewport` for mobile or desktop dimensions. Reuse a screen in many flows without duplicating its HTML.
+
+## Commands
+
+| Command                 | Purpose                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `scaffold <directory>`  | Create a project from `basic`, `web`, or `process`. Refuses to overwrite existing content. |
+| `serve <atlas.json>`    | Start the viewer and serve local screens. Defaults to port 4178 on localhost.              |
+| `audit <atlas.json>`    | Check configuration, reachability, local files, and literal HTML/CSS references.           |
+| `validate <atlas.json>` | Validate configuration only, without reading screen files.                                 |
+
+Use `--help` for options, `--root` when assets live above the JSON directory, and `audit --json` for CI reports. [Full CLI reference →](docs/cli.md)
+
+## Embed it in an existing page
+
+```js
+import { loadAtlas } from "/vendor/ketatlas/src/index.js";
+
+const atlas = await loadAtlas(document.querySelector("#map"), "./atlas.json");
+atlas.goToFlow("onboarding");
+// When the host page unmounts:
+// atlas.destroy();
+```
+
+Give the container a height. Ship `src/`, `styles/`, and `assets/` together. Shadow DOM isolates viewer styles and events; multiple viewers can coexist. For React or bundled applications, see [Integration](docs/integration.md).
+
+## Explore and contribute
+
+- [Authoring guide](docs/authoring.md): screens, processes, branching, reuse, and viewport sizes.
+- [Configuration reference](docs/configuration.md): schema and defaults.
+- [CLI and audit](docs/cli.md): commands, exit codes, and audit boundaries.
+- [Integration and API](docs/integration.md): lifecycle, events, embedding, and styling.
+- [Architecture](docs/architecture.md): package boundaries and design provenance.
+- [Migration from the mobile map](docs/migration.md): explicit field mapping.
+- [Contributing](CONTRIBUTING.md) and [releasing](docs/releasing.md).
+
+```sh
+npm run validate
+npm test
+npx playwright install chromium
+npm run test:e2e
+npm run test:package
+```
+
+Audit is static analysis. It does not execute product code or prove that native apps, external services, or embedded pages behave correctly. Arrows describe the authored workflow; the embedded HTML retains its own interactions.
+
+MIT · [Third-party notices](NOTICE.md).

package/assets/INTER-LICENSE

@@ -0,0 +1,93 @@
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter) Inter-Italic[opsz,wght].ttf: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/KETJS-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KETVIET JSC, Vietnam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/LUCIDE-LICENSE

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/design-system.lock.json

@@ -0,0 +1,56 @@
+{
+  "source": "@ketvietlab/design-system",
+  "repository": "https://github.com/ketvietlab/ketjs",
+  "revision": "fab9de5d5814e96f2e04ced806b6bef487cf9662",
+  "transform": "Flatten imports. Adapt :root to :host in the Shadow DOM bundle. Preserve all token values.",
+  "fontSource": "@fontsource-variable/inter@5.3.0",
+  "iconSource": "lucide-static@1.40.0",
+  "sources": [
+    {
+      "path": "packages/design-system/src/styles.css",
+      "sha256": "d93ffcad19de960a8652067b6be872bcbc963fba5e605770cb35d9577c48d803"
+    },
+    {
+      "path": "packages/design-system/src/foundations/tokens.css",
+      "sha256": "b940bdde82f0df2e54aec6c168915561281531aa903dfdf55d7585112921055e"
+    },
+    {
+      "path": "packages/design-system/src/foundations/reset.css",
+      "sha256": "bf993c7526bdb7654bbf25f661eac65c579ac11a17bd189bc4e07e9ff8ba9349"
+    },
+    {
+      "path": "packages/design-system/src/primitives/primitives.css",
+      "sha256": "1a102a816369f10fd126ea03fbbb1172c9923afc4af89951d32ba9403a1698db"
+    },
+    {
+      "path": "packages/design-system/src/primitives/navigation.css",
+      "sha256": "1375592dced6468752607ec513d0f85df5fdacc69f681bf4f01677bddd2167c7"
+    },
+    {
+      "path": "packages/design-system/src/primitives/progress.css",
+      "sha256": "3b8436da7884d30a180588a474e77dfd8237f2346e2fad7718d1e5295b8cc8dc"
+    },
+    {
+      "path": "packages/design-system/src/layouts/layouts.css",
+      "sha256": "905db294d479c9db83059cb43f1ee7ea79573c04824fde378e923610052399f2"
+    },
+    {
+      "path": "packages/design-system/src/layouts/shell.css",
+      "sha256": "4dc89488b74022e999c9a1591650ef37826640302c8929074170c0eeddb318ec"
+    },
+    {
+      "path": "packages/design-system/src/patterns/patterns.css",
+      "sha256": "7444dcc6336ab8bb60ca2ca6809d0fd919f09108db36020c5f3500d752e29f57"
+    }
+  ],
+  "outputs": {
+    "styles/design-system.css": "ecc93e327cf006190bef28485d15aedf2f84087c80f5eb6e3594be00ac253a5c",
+    "styles/design-system.document.css": "d095a063da527933a96dd415ebf960b4e5f9e882ad5b806493aac9141490840e",
+    "src/icons.js": "44791ce0a1400d0bd6f628816935372ab02ace3e981b099ed1c157f6f13422bb",
+    "assets/KETJS-LICENSE": "21a04c5b7aa12b45dfefe506cae70ffb2f22961e3bd89d9edcbcaad57e86956c",
+    "assets/INTER-LICENSE": "3b0a5fca3d17942cde889069889dedbbbd075e9b599968c82a95f4d944e9b345",
+    "assets/LUCIDE-LICENSE": "b495047bd93a9b06913511076f504daba17d5bbeb3e0650f3bb53a4220329c57",
+    "assets/inter-latin-wght-normal.woff2": "3100e775e8616cd2611beecfa23a4263d7037586789b43f035236a2e6fbd4c62",
+    "assets/inter-vietnamese-wght-normal.woff2": "5c66f9e07e90c6d4ac4922cc68d60de26c17b1858e677fb5e603fce3952b3ff2"
+  }
+}

package/bin/audit.js

@@ -0,0 +1,116 @@
+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";
+const within = (root, path) => {
+  const r = relative(root, path);
+  return r === "" || (!r.startsWith(".." + sep) && r !== ".." && !r.startsWith(sep));
+};
+export async function auditAtlas(file, { root: rootOption } = {}) {
+  const absolute = await realpath(resolve(file));
+  const root = await realpath(resolve(rootOption || dirname(absolute)));
+  let config;
+  try {
+    config = JSON.parse(await readFile(absolute, "utf8"));
+  } catch (error) {
+    return {
+      valid: false,
+      file: absolute,
+      root,
+      summary: { flows: 0, screens: 0, nodes: 0, edges: 0, localFiles: 0, remoteUrls: 0 },
+      errors: [{ path: "$", message: error.message }],
+      warnings: [],
+      scope: "Invalid JSON; no resources inspected.",
+    };
+  }
+  const result = validateAtlas(config);
+  const errors = [...result.errors],
+    warnings = [...result.warnings],
+    checked = new Set(),
+    remote = new Set();
+  if (!within(root, absolute))
+    errors.push({ path: "file", message: "The atlas JSON must be inside the serve root." });
+  async function inspect(value, from, label) {
+    if (
+      !value ||
+      value.startsWith("#") ||
+      value.startsWith("data:") ||
+      value.startsWith("mailto:") ||
+      value.startsWith("tel:")
+    )
+      return;
+    if (/^(https?:)?\/\//i.test(value)) {
+      remote.add(value);
+      return;
+    }
+    let target;
+    try {
+      const url = value.startsWith("/")
+        ? new URL("." + value, pathToFileURL(root + sep))
+        : new URL(value, pathToFileURL(from));
+      if (url.protocol !== "file:") return;
+      target = await realpath(fileURLToPath(url));
+      if (!within(root, target))
+        throw new Error("Asset is outside the serve root; move it or use --root.");
+      const rel = relative(root, target);
+      if (rel.split(sep).some((part) => part.startsWith(".")))
+        throw new Error("Dotfiles are not served.");
+      if (!(await stat(target)).isFile()) throw new Error("Expected a file.");
+    } catch (e) {
+      errors.push({
+        path: label,
+        message: `Cannot serve ${value}: ${e.code === "ENOENT" ? "file not found" : e.message}`,
+      });
+      return;
+    }
+    if (checked.has(target)) return;
+    checked.add(target);
+    const extension = extname(target).toLowerCase();
+    if (![".html", ".css"].includes(extension)) return;
+    const content = await readFile(target, "utf8");
+    if (extension === ".html") {
+      if (!/<meta\b[^>]*name\s*=\s*["']viewport["']/i.test(content))
+        warnings.push({
+          path: relative(root, target),
+          message: "No viewport meta tag; narrow previews may use a desktop layout.",
+        });
+      // Literal HTML resource URLs only. JS-generated URLs need browser verification.
+      for (const match of content.matchAll(
+        /<(?:script|link|img|iframe|source)\b[^>]*?\b(?:src|href)\s*=\s*["']([^"']+)["']/gi,
+      ))
+        await inspect(match[1], target, relative(root, target));
+      for (const match of content.matchAll(/<a\b[^>]*?\bhref\s*=\s*["']([^"']+)["']/gi))
+        await inspect(match[1], target, relative(root, target));
+    } else {
+      for (const match of content.matchAll(
+        /(?:url\(\s*["']?([^\s"')]+)["']?\s*\)|@import\s+["']([^"']+)["'])/gi,
+      ))
+        await inspect(match[1] || match[2], target, relative(root, target));
+    }
+  }
+  if (result.valid) {
+    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 url of remote)
+    warnings.push({ path: "remote", message: `Remote URL not fetched: ${url}` });
+  const flows = Array.isArray(config?.flows) ? config.flows : [];
+  return {
+    valid: errors.length === 0,
+    file: absolute,
+    root,
+    summary: {
+      flows: flows.length,
+      screens: Array.isArray(config?.screens) ? config.screens.length : 0,
+      nodes: flows.reduce((n, f) => n + (Array.isArray(f?.nodes) ? f.nodes.length : 0), 0),
+      edges: flows.reduce((n, f) => n + (Array.isArray(f?.edges) ? f.edges.length : 0), 0),
+      localFiles: checked.size,
+      remoteUrls: remote.size,
+    },
+    errors,
+    warnings,
+    scope:
+      "Static configuration and literal local HTML/CSS references. JavaScript behavior and remote embedding policies are not executed.",
+  };
+}

package/bin/ketatlas.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { readFile, readdir, mkdir, cp, writeFile, stat } from "node:fs/promises";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateAtlas } from "../src/config.js";
+import { serve } from "./server.js";
+import { serveAtlas } from "./viewer.js";
+import { auditAtlas } from "./audit.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const help = `KetAtlas — scaffold, serve, and audit HTML workflow maps
+
+  ketatlas scaffold <directory> [--template basic|web|process]
+  ketatlas serve <atlas.json> [--port 4178] [--root directory]
+  ketatlas audit <atlas.json> [--root directory] [--json] [--strict]
+  ketatlas validate <atlas.json>
+  ketatlas --version
+
+Examples:
+  npx ketatlas scaffold my-atlas
+  npx ketatlas serve my-atlas/atlas.json
+  npx ketatlas audit my-atlas/atlas.json --strict
+
+Serve binds to 127.0.0.1. No HTML wrapper, build, account, or backend required.
+`;
+function parse(args, allowed) {
+  const options = {},
+    positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (!(key in allowed)) throw new Error(`Unknown option: ${arg}`);
+      if (allowed[key] === "boolean") options[key] = true;
+      else {
+        const value = args[++i];
+        if (!value || value.startsWith("--")) throw new Error(`Missing value for ${arg}`);
+        options[key] = value;
+      }
+    } else positionals.push(arg);
+  }
+  if (positionals.length !== 1)
+    throw new Error("Expected one file or directory. Run ketatlas --help.");
+  return { target: positionals[0], options };
+}
+async function main(args) {
+  const [command, ...rest] = args;
+  if (!command || ["--help", "-h", "help"].includes(command) || rest.includes("--help")) {
+    console.log(help);
+    return;
+  }
+  if (command === "--version") {
+    console.log(JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")).version);
+    return;
+  }
+  if (command === "scaffold" || command === "init") {
+    const { target, options } = parse(rest, { template: "string" }),
+      template = options.template || "basic";
+    if (!["basic", "web", "process"].includes(template))
+      throw new Error("Templates: basic, web, process.");
+    const destination = resolve(target);
+    let existing;
+    try {
+      existing = await readdir(destination);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    if (existing?.length)
+      throw new Error("Destination is not empty. Choose an empty or new directory.");
+    await mkdir(destination, { recursive: true });
+    const source = join(packageRoot, "templates", template);
+    for (const name of await readdir(source))
+      await cp(join(source, name), join(destination, name), {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+      });
+    console.log(
+      `Created ${destination}\n\nNext: npx ketatlas serve "${join(destination, "atlas.json")}"\nEdit atlas.json to make it yours.`,
+    );
+    return;
+  }
+  if (command === "audit") {
+    const { target, options } = parse(rest, {
+      root: "string",
+      json: "boolean",
+      strict: "boolean",
+      output: "string",
+    });
+    const report = await auditAtlas(target, options),
+      pass = report.valid && (!options.strict || report.warnings.length === 0);
+    if (options.output)
+      await writeFile(resolve(options.output), JSON.stringify(report, null, 2) + "\n", {
+        flag: "wx",
+      });
+    if (options.json) console.log(JSON.stringify(report, null, 2));
+    else {
+      for (const issue of report.errors) console.error(`ERROR ${issue.path}: ${issue.message}`);
+      for (const issue of report.warnings) console.warn(`WARN ${issue.path}: ${issue.message}`);
+      console.log(
+        `${pass ? "PASS" : "FAIL"} · ${report.summary.flows} flows · ${report.summary.screens} screens · ${report.summary.localFiles} local files\n${report.scope}`,
+      );
+    }
+    if (!pass) process.exitCode = 1;
+    return;
+  }
+  if (command === "validate") {
+    const { target } = parse(rest, {}),
+      config = JSON.parse(await readFile(resolve(target), "utf8")),
+      result = validateAtlas(config);
+    for (const issue of result.errors) console.error(`ERROR ${issue.path}: ${issue.message}`);
+    for (const issue of result.warnings) console.warn(`WARN ${issue.path}: ${issue.message}`);
+    if (!result.valid) {
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      `Valid atlas: ${config.flows.length} flows, ${config.screens?.length || 0} screens.`,
+    );
+    return;
+  }
+  if (command === "serve") {
+    const { target, options } = parse(rest, { port: "string", root: "string" }),
+      port = Number(options.port || 4178);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+      throw new Error("Port must be 1–65535.");
+    const directory = (await stat(resolve(target))).isDirectory();
+    if (directory && options.root)
+      throw new Error("--root is only needed when serving an atlas JSON file.");
+    const server = directory
+      ? await serve(target, { port })
+      : await serveAtlas(target, { port, root: options.root });
+    console.log(
+      `KetAtlas: http://127.0.0.1:${server.address().port}\nServing ${resolve(target)}\nPress Ctrl+C to stop.`,
+    );
+    const close = () => {
+      server.close();
+      server.closeAllConnections();
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}. Run ketatlas --help.`);
+}
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`KetAtlas: ${error.message}`);
+  process.exitCode = 1;
+});