An AI agent skill that turns any subject into a 3D film or app
Add quick prototype and live embed modes
Nguyen Xuan An830a23fcc04a
diff --git a/README.md b/README.mdindex df15ea7..9284a3b 100644--- a/README.md+++ b/README.md@@ -13,12 +13,17 @@ This skill has your agent turn questionslike these into a 3D world you can watch or click through. The world is built from researched facts and from modelsmade to real dimensions.-It has two modes:+It has four modes:- **Live app**: a three.js app with a dashboard around a 3D world of the place. A seeded simulation moves the units andthe numbers. The agent records a 30 s film by driving the app with real clicks on a virtual clock.- **Documentary film**: a 2 to 4 minute film of an event, told in order. It is built from a sourced fact file, a map,block-built scenes and flat glowing figures. Captions are timed for reading, and the score changes with the story.+- **Quick prototype**: a live app in one pass from three.js primitives, with no Blender. Use it when you need something+ to show your leads this week.+- **Live embed**: the 3D view as a web component (`<viz3d-world>`) or an iframe page that goes into the dashboard or+ product you already have. It reads your real data from REST, Server-Sent Events, WebSocket or a CSV export through a+ field mapping file, so a new feed needs no code change. Tokens stay on your backend.There are four looks: toy isometric, point-cloud survey, photoreal terrain and dark documentary.@@ -54,17 +59,32 @@ Ask for what you want to see, for example:- "Visualize how a container port works."- "Show how a city metro keeps its trains apart."- "Make a documentary-style 3D film of the 1906 San Francisco earthquake."+- "Make a quick 3D prototype of our warehouse for Monday's leadership review. Here is last week's CSV export."+- "Put a live 3D view of our fleet in our ops dashboard. The feed is at /api/fleet/events."The agent writes a topic file first, then builds the models, then the app or the film. It checks its own film oncontact sheets before it shows you anything.+For a live embed, the agent builds a web component and an iframe page. Put the component in any page and point it at+your feed:++```html+<script type="module" src="/viz3d-world.js"></script>+<viz3d-world source="https://ops.example.internal/events" mapping="/mapping.json" chrome="panel"></viz3d-world>+```++`mapping.json` links your field names and status codes to the 3D view, so a new feed needs no code change. For a tool+that only takes a URL, use `embed.html?source=...` in an iframe. To test without your real system, the skill's+`scripts/mock-feed.mjs` replays a JSONL file as a live feed.+### What you need- Node 20 or later, with Playwright and Chromium for recording.- ffmpeg on your PATH.- A GPU that runs WebGL2 at 1080p.-- [Blender](https://www.blender.org/download/) 5.x is optional. It gives much better models. Without it the skill builds- the models in three.js and tells you the quality is lower.+- [Blender](https://www.blender.org/download/) 5.x is optional. It gives much better models for the full live app and+ the documentary. Without it the skill builds the models in three.js and tells you the quality is lower. Quick+ prototypes and embeds never need it.The skill asks before it downloads anything, such as elevation data, map data or reference images.diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md b/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.mdindex e1c91bb..7640481 100644--- a/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/SKILL.md@@ -1,6 +1,6 @@---name: visualize-in-3d-description: Make things that are hard to picture visible as a 3D world people can watch or play with - an operation (airport, data center, port, factory, hospital), a system, an event spreading over real land (wildfire, flood), or a story in time (a historical event, a case). Builds a live three.js app with a dashboard and a 30 s film, or a shot-by-shot documentary film, with models made in Blender from real references (or in three.js when Blender is missing). Use for "visualize how X works", "show this event on a 3D map", "a live 3D dashboard of how X runs", "a documentary-style 3D explainer".+description: Make things that are hard to picture visible as a 3D world people can watch or play with - an operation (airport, data center, port, factory, hospital), a system, an event spreading over real land (wildfire, flood), or a story in time (a historical event, a case). Builds a live three.js app with a dashboard and a 30 s film, or a shot-by-shot documentary film, with models made in Blender from real references (or in three.js when Blender is missing), a quick no-Blender prototype for a leadership demo, or a component that embeds in an existing dashboard or product and runs on live company data. Use for "visualize how X works", "show this event on a 3D map", "a live 3D dashboard of how X runs", "a documentary-style 3D explainer", "a quick 3D prototype to show leadership", "put a live 3D view of our operation in our dashboard".license: MIT---@@ -9,7 +9,7 @@ license: MITSome things are hard to understand from text, tables or a long video: how an airport turns a plane around in 45minutes, what an ER does with ten arrivals at once, where a data center's power goes, how a warehouse ships an order,how a case unfolded across a county, why a reactor exploded at 01:23. This skill turns them into a 3D world you can-watch or click through, so the parts, the order and the cause can be seen at a glance. Two modes share one toolkit (models from real references, a+watch or click through, so the parts, the order and the cause can be seen at a glance. Four modes share one toolkit (models from real references, adeterministic virtual clock, contact-sheet checks):- **Live app**: a system or an operation. A real dashboard around a 3D world, a seeded simulation moving units and@@ -17,6 +17,11 @@ deterministic virtual clock, contact-sheet checks):- **Documentary film**: an event, a case or a piece of history told in order. A fact file, a map, block-built sceneswith flat glowing figures, captions timed for reading, sound and a score by section. See`references/documentary.md`.+- **Quick prototype**: a one-pass live app built from three.js primitives, with no Blender, for a demo to leaders+ after about an hour of agent time. See `references/live-embed.md`.+- **Live embed**: the live app as a web component or an iframe page inside an existing dashboard or product. It runs+ on the company's real data through an adapter (REST, SSE, WebSocket or CSV) and a field mapping. See+ `references/live-embed.md`.Pick the look in `references/looks.md` (toy isometric, point-cloud survey, photoreal terrain, dark documentary).Paths use `{{WORK_DIR}}` for the folder where projects live (the current directory unless the user names one) and@@ -24,7 +29,7 @@ Paths use `{{WORK_DIR}}` for the folder where projects live (the current directo## Before you start-1. **Blender:** run `blender --version` (or look for it in the usual install folder). If it is missing, tell the user+1. **Blender** (skip this for a quick prototype or an embed, which use primitives unless the user asks for Blender): run `blender --version` (or look for it in the usual install folder). If it is missing, tell the userit gives much better models and is a free download from blender.org, and ask whether to wait for the install orgo on without it. Without Blender, build the models in three.js as `references/no-blender.md` describes and sayin the report that model quality is lower.diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md b/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.mdnew file mode 100644index 0000000..29d9a3a--- /dev/null+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/references/live-embed.md@@ -0,0 +1,130 @@+# Quick prototypes and live embeds++Two needs that the full live app does not cover. Read the section that matches the request.++- **Quick prototype**: a 3D view to show leaders this week, on a machine with no Blender, in about an hour of agent+ time. One pass, models from primitives in three.js, seeded or sample data.+- **Live embed**: the 3D view goes into a dashboard or product that already exists and runs on the company's real+ data. A data adapter, a field mapping, and a component that any page can drop in.++A prototype can grow into an embed: both use the same data model and the same adapter interface, so the swap from+seeded data to a real feed is a config change.++## Quick prototype++Skip Pass 1 and do not ask about Blender. Build everything in one pass in `{{FOLDER}}/app` with the Pass 2 stack+(Vite, React, React Three Fiber, drei, postprocessing with N8AO) and these cuts:++1. **One site, one process.** The topic file lists one site, four KPIs and three to five stages. Leave out the site+ switcher and the film unless the user asks.+2. **A primitive kit, not an asset pack.** One file `src/kit.jsx` with parametric parts at real size: `Box`, `Slab`+ (floor with a 3 cm bevel), `Rack`, `Conveyor`, `Tank`, `Pipe`, `Vehicle` (body, cab, four wheels), `Person`+ (capsule, 1.75 m), `Building` (walls with window strips, no roof so the inside shows), `Path` (a swept strip along+ points). Each takes dimensions and a colour. Build every main asset from the kit against its reference sheet+ (`real-objects.md`): proportions and part count still matter.+3. **The look carries the quality.** Toy isometric from `looks.md`: soft shadows, N8AO, a warm key light, a ground+ with real materials, flat colours from one palette. Clean primitives under good light read as a design choice.+4. **Data the leaders recognise.** Ask for a sample export (CSV or JSON) and its field names. With a sample, map it+ as in "Field mapping" below. Without one, seed a simulation with the real counts and rates from the topic research.+5. **Done when** the overview, a clicked unit with its card and each stage preset look right in screenshots, it runs+ at 60 fps, and `npm run build` gives a static folder that opens from any web server.++Budget about 60 tool calls. Report the URL to run it, the screenshots, and what a full build adds (Blender models,+film, more sites).++## Live embed++### Data model and adapters++All data enters through one adapter interface, so the view never knows where it comes from:++```js+// src/data/adapter.js+// connect(handlers) starts the feed and returns a function that stops it.+// handlers.snapshot(state) replaces the whole state; handlers.event(event) applies one change.+// handlers.status({ state: 'live' | 'stale' | 'offline', lastUpdate }) drives the status mark.+```++Ship these adapters, chosen by a `source` URL or option:++| Source | Adapter | Notes |+|---|---|---|+| `sim:` | seeded simulation | Default, and the only source for the film and the checks |+| `https://…/snapshot.json` | polling REST | Poll every 2-10 s with `If-None-Match`; back off on errors |+| `https://…/events` (SSE) or `wss://…` | stream | Reconnect with backoff; ask for a fresh snapshot after a reconnect |+| `file:` or a dropped `.csv` | CSV | One row per unit or per event; for leaders with only a spreadsheet export |++State has one shape for every source: `sites`, `units` (id, type, site, position or a place name, status, fields),+`tasks`, `events` and `kpis`. The 3D view and the dashboard both read it.++### Field mapping++Put the link between the company's fields and the state in `public/mapping.json`, so a new feed or a renamed column+needs no code change:++```json+{+ "unit": { "id": "asset_id", "type": "asset_class", "status": "state", "position": ["lon", "lat"] },+ "status": { "RUN": "working", "IDLE": "waiting", "FAULT": "blocked" },+ "units": { "speed": "km/h -> m/s" },+ "places": { "Dock 4": [112, 0, -38] }+}+```++Places map names to world positions when the feed has no coordinates. Unknown statuses and types show as a grey+"unknown" mark and are listed in the status panel; they never crash the view.++### Motion between updates++A real feed updates every 1 to 10 s, but motion must stay smooth. Move each unit toward its last reported position+along its path at its reported or measured speed. Extrapolate for at most two update intervals, then hold. A unit with+no update for five intervals fades and shows "stale". The status mark (an icon per state: live, stale, offline) and+"updated 4 s ago" sit in the top bar. Seconds and rates on the KPI cards come from the data, never from the frame rate.++### The component++Build two outputs from the same code with `vite build --lib` and a second entry:++- **Web component** `dist/viz3d-world.js` for any page, React, Vue or plain HTML:++ ```html+ <script type="module" src="/viz3d-world.js"></script>+ <viz3d-world source="https://ops.example.internal/events" mapping="/mapping.json" chrome="panel" theme="auto"></viz3d-world>+ ```++- **Iframe page** `dist/embed.html?source=…&chrome=…` for dashboard tools that only take a URL (BI tools, internal+ portals, wikis). It talks to the host with `postMessage`: in `viz3d:select`, `viz3d:site`, `viz3d:stage`,+ `viz3d:theme`; out `viz3d:ready`, `viz3d:selected`, `viz3d:kpis`. Check `event.origin` against an allow list.++`chrome` picks how much of the dashboard comes along: `full` (top bar, KPI cards, detail card, timeline), `panel`+(the 3D view with pins, the detail card and the stage bar, for a host that has its own KPI cards) or `none` (the 3D+view and pins only).++Rules for living inside someone else's page:++- Render inside a shadow root and leak no global styles. Inherit the host's font. Read colours from the host's CSS+ variables (`--viz3d-bg`, `--viz3d-fg`, `--viz3d-accent`, `--viz3d-ok`, `--viz3d-warn`, `--viz3d-bad`) with the look's+ palette as the fallback, and follow `prefers-color-scheme` when `theme="auto"`.+- Size from the element with a `ResizeObserver`; never assume the window. Cap the pixel ratio at 1.5.+- Stop rendering when the element is off screen (`IntersectionObserver`) or the tab is hidden. Dispose every+ geometry, texture and the renderer when the element is removed, so a host that mounts it twice does not leak.+- Keyboard shortcuts work only while the element has focus.+- Without WebGL, show the same data as a table with the status marks.++### Security++The component is read-only. It never holds a secret: tokens and API keys stay on the host's backend, which proxies+the feed or signs a short-lived URL. Never put credentials in `mapping.json`, the bundle or a query string. Personal+data (driver names, patient names) is shown only when the feed already sends it to that page's users.++### Checks++1. Run `node {{SKILL_DIR}}/scripts/mock-feed.mjs --port 8787 --file sample.jsonl` (it replays a JSONL file of records+ with a `t` field as SSE at `/events` and the latest state at `/snapshot.json`), point the component at it, and+ screenshot it live.+2. Stop the mock feed: the mark turns stale, then offline, and the view keeps the last state. Start it again: it+ recovers without a reload.+3. Put the component in a plain host page twice, at 1200x700 and 600x400, in light and dark host themes. Look at each+ screenshot for clipped UI, wrong colours and text that wraps.+4. Unmount and mount it ten times and check that the WebGL context count and memory stay flat.+5. Record a film of the host page with the component inside, driven by `sim:` on the virtual clock (`film.md`).diff --git a/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/mock-feed.mjs b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/mock-feed.mjsnew file mode 100644index 0000000..2218584--- /dev/null+++ b/plugins/visualize-in-3d/skills/visualize-in-3d/scripts/mock-feed.mjs@@ -0,0 +1,79 @@+#!/usr/bin/env node+// A mock live feed for testing an embedded view without the company's real system.+// It replays a JSONL file (one JSON record per line, each with a `t` field in seconds and an `id`) in real time:+// GET /events Server-Sent Events, one `data:` line per record, looping at the end of the file+// GET /snapshot.json the latest record of every id so far+// Usage: node mock-feed.mjs --file sample.jsonl [--port 8787] [--speed 1]+import { createServer } from 'node:http';+import { readFileSync } from 'node:fs';++function readOption(name, fallback) {+ const index = process.argv.indexOf(`--${name}`);+ return index === -1 ? fallback : process.argv[index + 1];+}++const filePath = readOption('file', null);+const port = Number(readOption('port', 8787));+const speed = Number(readOption('speed', 1));+if (!filePath) {+ console.error('Usage: node mock-feed.mjs --file sample.jsonl [--port 8787] [--speed 1]');+ process.exit(1);+}++const records = readFileSync(filePath, 'utf8')+ .split(/\r?\n/)+ .filter(line => line.trim())+ .map(line => JSON.parse(line))+ .sort((first, second) => first.t - second.t);+if (records.length === 0) {+ console.error(`No records in ${filePath}`);+ process.exit(1);+}+const loopLength = records[records.length - 1].t + 1;++const latestById = new Map();+const listeners = new Set();+const startedAt = Date.now();+let nextIndex = 0;+let loopCount = 0;++function tick() {+ const elapsed = ((Date.now() - startedAt) / 1000) * speed;+ while (true) {+ const record = records[nextIndex];+ const recordTime = record.t + loopCount * loopLength;+ if (recordTime > elapsed) break;+ const sent = { ...record, t: Math.round(recordTime * 1000) / 1000 };+ latestById.set(String(record.id), sent);+ const line = `data: ${JSON.stringify(sent)}\n\n`;+ for (const response of listeners) response.write(line);+ nextIndex += 1;+ if (nextIndex === records.length) {+ nextIndex = 0;+ loopCount += 1;+ }+ }+}+setInterval(tick, 50);++const corsHeaders = { 'Access-Control-Allow-Origin': '*', 'Cache-Control': 'no-store' };++createServer((request, response) => {+ const path = new URL(request.url, 'http://localhost').pathname;+ if (path === '/events') {+ response.writeHead(200, { ...corsHeaders, 'Content-Type': 'text/event-stream', Connection: 'keep-alive' });+ response.write(': connected\n\n');+ listeners.add(response);+ request.on('close', () => listeners.delete(response));+ return;+ }+ if (path === '/snapshot.json') {+ response.writeHead(200, { ...corsHeaders, 'Content-Type': 'application/json' });+ response.end(JSON.stringify({ updatedAt: Date.now(), records: [...latestById.values()] }));+ return;+ }+ response.writeHead(404, corsHeaders);+ response.end('Not found. Use /events or /snapshot.json');+}).listen(port, () => {+ console.log(`Mock feed: ${records.length} records from ${filePath} at http://localhost:${port}/events and /snapshot.json`);+});