{"_id":"@ambitresearch/genie-viewer","_rev":"2-c66c655b71331710f6f79ca89dcae989","name":"@ambitresearch/genie-viewer","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.1":{"name":"@ambitresearch/genie-viewer","version":"0.1.1","author":{"name":"Roshan Gautam"},"license":"MIT","_id":"@ambitresearch/genie-viewer@0.1.1","maintainers":[{"name":"roshang","email":"contact@roshangautam.net"}],"homepage":"https://github.com/ambitresearch/genie#readme","bugs":{"url":"https://github.com/ambitresearch/genie/issues"},"bin":{"genie-viewer":"dist/cli.js"},"dist":{"shasum":"71ad60e6235eee91d84e78f0cfe1a01a8d3e9144","tarball":"https://registry.npmjs.org/@ambitresearch/genie-viewer/-/genie-viewer-0.1.1.tgz","fileCount":18,"integrity":"sha512-O8ttoohHwtI21mjKmmf0/261/HwDsbFRQFnakEu1vtiWEcaU+9xZUIf+Km6drPRYQ2XjhQaEKQ4cGGOE72NHQQ==","signatures":[{"sig":"MEUCIQDH+kMeNrJErdDa3WlDdVW/oIDmMIQRPEUal2FdocS5AAIgERjJSKEOM/Y+ktjC5n+EtfGzY6r3IcRguuA4HUnS4Fs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ambitresearch%2fgenie-viewer@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":79041},"main":"./dist/index.js","type":"module","_from":"file:artifacts/viewer/ambitresearch-genie-viewer-0.1.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=22"},"scripts":{"dev":"tsx watch src/cli.ts","build":"tsc -p tsconfig.json","serve":"vite","test:a11y":"vitest run --root ../.. --config vitest.config.ts packages/viewer/test/a11y.test.ts","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"roshang","email":"contact@roshangautam.net"},"_resolved":"/home/runner/work/genie/genie/artifacts/viewer/ambitresearch-genie-viewer-0.1.1.tgz","_integrity":"sha512-O8ttoohHwtI21mjKmmf0/261/HwDsbFRQFnakEu1vtiWEcaU+9xZUIf+Km6drPRYQ2XjhQaEKQ4cGGOE72NHQQ==","repository":{"url":"git+https://github.com/ambitresearch/genie.git","type":"git","directory":"packages/viewer"},"_npmVersion":"11.16.0","description":"genie preview viewer — Vite-backed UI-kit grid (M4). Multi-page dev config (M4-02): each components/**/preview.html is a Vite entry point.","directories":{},"_nodeVersion":"24.18.0","dependencies":{"ws":"^8.21.0","open":"^11.0.0","vite":"^8.1.3","commander":"^15.0.0","fast-glob":"^3.3.3"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"jsdom":"^25.0.1","chokidar":"^3.6.0","@types/ws":"^8.18.1","playwright":"^1.61.1","@types/node":"^26.0.0","@types/jsdom":"^21.1.7","@axe-core/playwright":"4.12.1"},"_npmOperationalInternal":{"tmp":"tmp/genie-viewer_0.1.1_1784584600564_0.41001448606259117","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@ambitresearch/genie-viewer","version":"0.2.0","type":"module","description":"genie preview viewer — Vite-backed UI-kit grid (M4). Multi-page dev config (M4-02): each components/**/preview.html is a Vite entry point.","repository":{"type":"git","url":"git+https://github.com/ambitresearch/genie.git","directory":"packages/viewer"},"publishConfig":{"access":"public","provenance":true},"bin":{"genie-viewer":"dist/cli.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"dev":"tsx watch src/cli.ts","serve":"vite","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test:a11y":"vitest run --root ../.. --config vitest.config.ts packages/viewer/test/a11y.test.ts","test:contrast":"vitest run --root ../.. --config vitest.config.ts --outputFile.junit=reports/junit-browse-contrast.xml packages/viewer/test/browse-contrast.test.ts"},"dependencies":{"commander":"^15.0.0","fast-glob":"^3.3.3","open":"^11.0.0","vite":"^8.1.3","ws":"^8.21.0"},"engines":{"node":">=22.19.0 <23 || >=24.4.1"},"license":"MIT","author":{"name":"Roshan Gautam"},"devDependencies":{"@axe-core/playwright":"4.12.1","@types/jsdom":"^21.1.7","@types/node":"^26.0.0","@types/ws":"^8.18.1","axe-core":"4.12.1","chokidar":"^3.6.0","jsdom":"^25.0.1","playwright":"^1.61.1"},"_id":"@ambitresearch/genie-viewer@0.2.0","bugs":{"url":"https://github.com/ambitresearch/genie/issues"},"homepage":"https://github.com/ambitresearch/genie#readme","_integrity":"sha512-+mwE1ZTV9/cxhQ/0lSI0TKk7U8BT81nOk93HRZ14eEmrrtYTuOSFmI1UcR3mv4U/fqHJgOFfC+JZ2MPxFNvweQ==","_resolved":"/home/runner/work/genie/genie/artifacts/viewer/ambitresearch-genie-viewer-0.2.0.tgz","_from":"file:artifacts/viewer/ambitresearch-genie-viewer-0.2.0.tgz","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-+mwE1ZTV9/cxhQ/0lSI0TKk7U8BT81nOk93HRZ14eEmrrtYTuOSFmI1UcR3mv4U/fqHJgOFfC+JZ2MPxFNvweQ==","shasum":"22475c9733eb868e90a735e4c84e40bde8d0c2ed","tarball":"https://registry.npmjs.org/@ambitresearch/genie-viewer/-/genie-viewer-0.2.0.tgz","fileCount":18,"unpackedSize":80083,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ambitresearch%2fgenie-viewer@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDXfHJmyVkAaxlC6cOO9xb8PlvDbdK0DNpGpPmLa3xP5QIgXoNNmZW4zdfqua/lUbKoZd0gQKMB0XoYgI3smtKsdWo="}]},"_npmUser":{"name":"roshang","email":"contact@roshangautam.net"},"directories":{},"maintainers":[{"name":"roshang","email":"contact@roshangautam.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/genie-viewer_0.2.0_1785270109862_0.6303097466500138"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T21:56:40.320Z","modified":"2026-07-28T20:21:50.364Z","0.1.1":"2026-07-20T21:56:40.708Z","0.2.0":"2026-07-28T20:21:50.020Z"},"bugs":{"url":"https://github.com/ambitresearch/genie/issues"},"author":{"name":"Roshan Gautam"},"license":"MIT","homepage":"https://github.com/ambitresearch/genie#readme","repository":{"type":"git","url":"git+https://github.com/ambitresearch/genie.git","directory":"packages/viewer"},"description":"genie preview viewer — Vite-backed UI-kit grid (M4). Multi-page dev config (M4-02): each components/**/preview.html is a Vite entry point.","maintainers":[{"name":"roshang","email":"contact@roshangautam.net"}],"readme":"# @ambitresearch/genie-viewer\n\nVite-backed live preview + UI-kit browser for genie. Watches a kit directory\n(`.genie/manifest.json` + `components/`) and renders the same cards genie's\nMCP tools produce, in a grid, with per-card HMR. See the public\n[Developer Guide](../../docs/developer/architecture.md) for the system context.\n\n## Status: Generate shell + live grid\n\nThis package ships the `genie-viewer` CLI — it boots the Vite **multi-page dev\nserver** against a kit directory (every `components/**/*.html` preview is its own\nentry point), prints the preview URL, opens your browser, and stops cleanly on\nCtrl-C. The shared shell provides Generate, Browse, and Review; Generate is\nhost-driven and therefore read-only in this standalone CLI vehicle. The grid\nrenderer and per-card HMR refresh are wired end to end under Browse.\n\n| Milestone           | Adds                                                     |\n| ------------------- | -------------------------------------------------------- |\n| M4-01               | package scaffold, CLI arg-parsing, usage/version         |\n| M4-02               | Vite multi-page config — one entry per component preview |\n| M4-08               | dev-server boot: URL print, port fallback, open, Ctrl-C  |\n| M4-03               | iframe grid renderer                                     |\n| M4-04 (this change) | WebSocket + trusted `postMessage` per-card HMR           |\n| M4-05…M4-10         | Embedded delivery, accessibility, and E2E verification   |\n\nSee the public [Developer Guide](../../docs/developer/) for architecture and\ncontribution guidance.\n\n## Quickstart\n\n```bash\n# Boot a live preview of a synced kit (opens your browser at the URL):\nnpx @ambitresearch/genie-viewer ui_kits/acme\n#   Preview: http://127.0.0.1:5173\n\n# Pick a port (falls back to the next free one, with a warning, if it's taken):\nnpx @ambitresearch/genie-viewer ui_kits/acme --port 5180\n\n# Headless / CI — print the URL but don't open a browser:\nnpx @ambitresearch/genie-viewer ui_kits/acme --no-open\n```\n\nPress **Ctrl-C** to stop: the watcher and dev server shut down within a second.\n\n> **The kit must be synced first.** `genie-viewer` refuses a directory without a\n> `.genie/manifest.json` (the client-side compiler's output) and exits non-zero,\n> pointing you at running the genie MCP server against the kit first. That\n> manifest is the signal the kit has cards to render.\n\n## Usage\n\n```bash\nnpx @ambitresearch/genie-viewer <kit-dir> [--port N] [--no-open]\n```\n\n```\nUsage: genie-viewer <kit-dir> [--port N]\n\nVite-backed UI-kit preview grid.\nBoots a live preview of <kit-dir> — every components/**/*.html preview as a\ncard — prints the URL, and opens your browser. Ctrl-C stops it cleanly.\n\nArguments:\n  kit-dir        path to the UI kit directory to preview\n\nOptions:\n  -v, --version  print the version and exit\n  --port <n>     dev server port (default: 5173)\n  --open         open the preview in the system browser (default: true)\n  --no-open      do not open a browser\n  -h, --help     display help for command\n```\n\n## Serving a kit directly (without the CLI)\n\nThe Vite config (`vite.config.ts` → [`src/config.ts`](src/config.ts)) serves a\nkit directory as a **multi-page app**: the kit's root `index.html` is the\nalways-present entry, and every `components/**/*.html` preview becomes its own\nVite entry point (globbed with `fast-glob`), hot-reloaded independently. The\nCLI above wraps this; to drive Vite yourself (e.g. debugging the config):\n\n```bash\n# Point the serve script at a kit (set GENIE_KIT_ROOT — see note below):\nGENIE_KIT_ROOT=/path/to/kit pnpm --filter @ambitresearch/genie-viewer serve\n\n# ...with an explicit port too:\nGENIE_KIT_ROOT=/path/to/kit GENIE_VIEWER_PORT=5180 pnpm --filter @ambitresearch/genie-viewer serve\n```\n\n> **Why `GENIE_KIT_ROOT` is required here:** the kit root defaults to\n> `process.cwd()`, but `pnpm --filter @ambitresearch/genie-viewer` runs the script with the\n> working directory set to the _viewer package_ (`packages/viewer`), not the\n> directory you invoked it from — so without `GENIE_KIT_ROOT` it would try to\n> serve the package dir (which has no kit `index.html`). Only a bare `vite`\n> launched from _inside_ a kit picks that kit up via the cwd default. The\n> `genie-viewer` CLI passes the `<kit-dir>` argument through for you, so you\n> won't set this by hand.\n\nBehaviour (the config's acceptance criteria):\n\n| Aspect       | Behaviour                                                            |\n| ------------ | -------------------------------------------------------------------- |\n| Entries      | root `index.html` + one per `components/**/*.html` preview           |\n| Host / port  | `127.0.0.1:5173` (loopback only, no LAN exposure); port via `--port` |\n| Build target | ES2022                                                               |\n| Kit statics  | `tokens/`, `styles.css`, `_vendor/` served at their kit-root paths   |\n| HTML caching | `Cache-Control: no-store` on HTML responses (never a stale card)     |\n| Routing      | `appType: \"mpa\"` — a missing card 404s, no SPA index fallback        |\n| HMR          | one matching iframe reload; Vite's competing HTML client is removed  |\n\nThe config lives in a pure `createViewerConfig({ root, port })` factory so it\ncan be snapshot-tested without booting a server (`src/config.test.ts`); the\nroot `vite.config.ts` is a thin env-reading shim over it.\n\n## Development\n\n```bash\npnpm --filter @ambitresearch/genie-viewer build       # tsc → dist/\npnpm --filter @ambitresearch/genie-viewer typecheck   # tsc --noEmit\npnpm --filter @ambitresearch/genie-viewer dev         # tsx watch src/cli.ts\npnpm --filter @ambitresearch/genie-viewer serve       # vite (multi-page kit dev server)\n```\n\nTests live alongside sources (`src/**/*.test.ts`) and run via the workspace\nroot's `pnpm test` (vitest).\n\n## Release verification\n\nReleases include npm provenance plus signed tarballs and SBOMs. After installing the\npackage, run `npm audit signatures` to check its registry signature and provenance. For\nrelease downloads, use `cosign verify-blob` with the adjacent `.sig` bundle.\n\nThe [supply-chain verification guide](https://github.com/ambitresearch/genie/blob/main/docs/supply-chain.md#verifying-a-release)\ncontains the complete certificate identity and issuer commands.\n","readmeFilename":"README.md"}