@fugood/bricks-project 2.25.0-beta.5 → 2.25.0-beta.50

package/skills/bricks-ctor/references/data-calculation.md

@@ -0,0 +1,239 @@
+# Data Calculation (JS Sandbox)
+
+Transform and compute Data Bank values using JavaScript scripts. Calcs are for **pure data transformation only** — see [Architecture Patterns](architecture-patterns.md) for the pattern selection guide.
+
+| If you need to... | Use instead |
+|---|---|
+| Call an LLM / AI model | Generator (Assistant, LLM, HTTP) |
+| Sequence multiple actions | Event Action Chain |
+| Set a data value directly | PROPERTY_BANK system action |
+| Compute a simple expression | PROPERTY_BANK_EXPRESSION |
+| Transform/format/parse data | Data Calculation (correct use) |
+
+## Authoring Contract
+
+```typescript
+import { makeId } from 'bricks-ctor'
+import { readFile } from 'node:fs/promises'
+
+const calculation: DataCalculationScript = {
+  __typename: 'DataCalculationScript',
+  id: makeId('property_bank_calc'),
+  title: 'Format Price',
+  description: 'Formats price with currency symbol',
+  note: '',
+  triggerMode: 'auto', // 'auto' (default) | 'manual'
+  enableAsync: false,
+  // Inline code for short scripts...
+  code: `
+    const price = inputs.price || 0
+    const currency = inputs.currency || 'USD'
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency,
+    }).format(price)
+  `,
+  // ...or load from a file (preferred for longer scripts):
+  // code: await readFile(new URL('./format-price.sandbox.js', import.meta.url), 'utf8'),
+  inputs: [
+    { key: 'price', data: () => priceData, trigger: true },
+    { key: 'currency', data: () => currencyData, trigger: false },
+  ],
+  output: () => formattedPriceData,
+  outputs: [], // Additional named outputs (see Multiple Outputs)
+  error: null, // or () => errorData for error handling
+}
+```
+
+### Field Rules (defaults and constraints)
+
+- `trigger` **defaults to `false` when omitted** — always set it explicitly. A calc whose inputs are all non-trigger never auto-runs.
+- `triggerMode` defaults to `'auto'` when omitted.
+- `output` receives the **whole return value**. `outputs` entries extract fields by key from a returned object — `key` is a lodash-get path, so deep paths like `'user.name'` work. `output`, `outputs`, and `error` can be combined.
+- `error` receives the error **message string** when the script throws. Both extraction steps run on every execution: a success overwrites the error Data, a failure overwrites the output Data(s) — don't expect stale values to persist.
+- **Auto mode rejects the same Data in both `inputs` and `output`/`outputs`/`error`** — compile fails with `Not allow duplicate set property id between inputs / outputs / output / error`. Manual mode allows the overlap (self-referential updates, see Recipes).
+- `.sandbox.js` files use an `export function main() { ... }` wrapper — compile unwraps it. Raw statements also work, but the wrapper keeps linters happy since script bodies use top-level `return`.
+
+## Trigger Modes
+
+| Mode | Description |
+|------|-------------|
+| `auto` | Run on every write to a `trigger: true` input (even if the value is unchanged) |
+| `manual` | Never auto-runs; only via `PROPERTY_BANK_COMMAND` action. Allows the same Data as both input and output |
+
+Use `manual` to prevent circular dependencies, for explicit control, or when an output must feed back into an input.
+
+## Triggering via PROPERTY_BANK_COMMAND
+
+`input` references a Data that is an input of the target calc — the system runs the calc(s) that data feeds into. It does NOT reference the DataCalculation itself.
+
+- **Manual calc**: ANY input works — `trigger` flags are ignored for manual-mode calcs.
+- **Auto calc**: only `trigger: true` inputs work; commanding a `trigger: false` input is a silent no-op.
+
+```typescript
+const triggerCalc: EventAction = {
+  handler: 'system',
+  action: {
+    __actionName: 'PROPERTY_BANK_COMMAND',
+    parent: 'System',
+    dataParams: [
+      { input: () => priceData }, // Reference to an input Data of the calc
+    ],
+  },
+}
+```
+
+- When the same chain **writes a calc input first** (e.g. `PROPERTY_BANK` setting `dLastButton`) then issues `PROPERTY_BANK_COMMAND`, set `waitAsync: true` on the write so the calc reads the new value rather than the pre-chain snapshot. See [Event Action Chains](architecture-patterns.md#event-action-chains-priority-2).
+- When a **later action reads the calc's outputs**, set `waitAsync: true` on the `PROPERTY_BANK_COMMAND` action itself — it awaits the full calc chain including output writes.
+- A dataParam's `value` acts as an execution gate: `{ input: () => d, value: false }` skips that trigger (combine with `mapping` for conditional runs).
+
+## Script Sandbox
+
+Scripts run in `use strict` mode as a function body — top-level `return` returns the calc result. No `fetch`, `XMLHttpRequest`, or `require` in any mode: I/O belongs to Generators.
+
+### Built-in Globals
+
+| Global | Description |
+|--------|-------------|
+| `inputs` | Object with input values (keyed by input `key`) |
+| `console` | `{ log, error, warn, info }` — output is only visible in DevTools debug sessions; production is a no-op |
+| `Platform` | `{ OS, isTV, isPad, isVision, isElectron }` |
+| `TextEncoder`, `TextDecoder` | Text encoding/decoding |
+| `Buffer` | Node.js Buffer (without `allocUnsafe`/`allocUnsafeSlow`) |
+| `btoa`, `atob` | Base64 encoding/decoding |
+
+### Async Mode
+
+Sync mode (default) has **no `Promise`, timers, or `await`**. Enable `enableAsync: true` to unlock:
+
+- `Promise`, `setTimeout`, `setInterval`, `setImmediate`, `clearTimeout`, `clearInterval`, `clearImmediate`, `requestAnimationFrame`
+- Full lodash (sync mode omits `debounce`, `delay`, `defer`)
+- `await` at the top level of the script
+
+```typescript
+code: `
+  const result = await new Promise((resolve) => {
+    setTimeout(() => resolve(inputs.value * 2), 100)
+  })
+  return result
+`,
+enableAsync: true,
+```
+
+### Runtime Environment
+
+| Platform | Engine |
+|----------|--------|
+| Android | Hermes engine sandbox |
+| iOS | JavaScriptCore sandbox |
+| Electron desktop | Web Worker (V8) |
+| Web preview / Simulator | Web Worker (V8) |
+
+Simulator (Path 1) runs scripts on V8 while devices run Hermes/JSC — engine-sensitive code (date parsing, Intl, regex features) can pass in the Simulator and fail on device.
+
+### Available Libraries
+
+All exposed as globals. No network/file-download capability in any of them.
+
+| Global | Library | Notes |
+|--------|---------|-------|
+| `_`, `lodash` | lodash | Sync mode omits `debounce`/`delay`/`defer` |
+| `voca` | voca | String manipulation |
+| `invariant` | invariant | Assertions |
+| `json5` | json5 | JSON5 parsing |
+| `qs` | qs | Query string parsing |
+| `url` | node-url | URL parsing |
+| `bytes` | bytes | Byte parsing/formatting |
+| `ms` | ms | Millisecond conversion |
+| `base45` | base45 | Base45 encoding |
+| `iconv` | iconv-lite | Character encoding |
+| `math`, `mathjs` | mathjs | Math library |
+| `chroma` | chroma-js | Color manipulation |
+| `moment` | moment | Date/time; auto parseFormat for string args |
+| `nanoid` | nanoid | Unique ID generation |
+| `md5` | md5 | MD5 hashing |
+| `crypto` | crypto-browserify | Crypto functions |
+| `kjurJWS` | jsrsasign | JWT/JWS signing (`KJUR.jws.JWS`) |
+| `coseVerify` | cose-js | COSE verification (sync) |
+| `fflate` | fflate | `{ zlibSync, unzlibSync, gzipSync, gunzipSync, compressSync, decompressSync, strFromU8 }` |
+| `cbor` | cbor | `{ encode, decode, decodeFirstSync, decodeAllSync, addSemanticType }` |
+| `fs` | (in-repo fs-compat) | File system; no download/upload methods |
+| `parseDocument` | officeparser (in-repo fork) | Office document parsing (async) |
+| `TurndownService` | turndown | HTML to Markdown |
+| `OpenCC` | opencc-js | Chinese conversion `{ Converter, ConverterFactory, CustomConverter, Locale }` |
+| `TOON` | @toon-format/toon | TOON format parsing |
+
+## Recipes
+
+### Multiple Outputs
+
+Return an object; each `outputs` entry extracts its `key`:
+
+```typescript
+outputs: [
+  { key: 'total', data: () => totalData },
+  { key: 'tax', data: () => taxData },
+  { key: 'subtotal', data: () => subtotalData },
+],
+output: null,
+error: null,
+code: `
+  const subtotal = inputs.price * inputs.quantity
+  const tax = subtotal * 0.1
+  const total = subtotal + tax
+  return { total, tax, subtotal }
+`,
+```
+
+### Manual Self-Referential Update
+
+When an update is too complex for `PROPERTY_BANK_EXPRESSION` and must read its own previous value — manual mode allows the same Data as input and output:
+
+```typescript
+const appendHistory: DataCalculationScript = {
+  __typename: 'DataCalculationScript',
+  id: makeId('property_bank_calc'),
+  title: 'Append History Entry',
+  triggerMode: 'manual',
+  enableAsync: false,
+  code: `
+    const history = Array.isArray(inputs.history) ? inputs.history : []
+    return [...history, { entry: inputs.entry, at: moment().toISOString() }].slice(-50)
+  `,
+  inputs: [
+    { key: 'history', data: () => historyData, trigger: true },
+    { key: 'entry', data: () => entryData, trigger: true },
+  ],
+  output: () => historyData, // same Data as input — manual mode only
+  outputs: [],
+  error: null,
+}
+// Run it from an event chain: PROPERTY_BANK writes entryData (waitAsync: true),
+// then PROPERTY_BANK_COMMAND with input: () => entryData.
+```
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Calc never auto-runs | `trigger` omitted on inputs (defaults to `false`) | Set `trigger: true` explicitly |
+| `PROPERTY_BANK_COMMAND` does nothing | Auto calc + `trigger: false` input, or `input` doesn't reference an input Data of the calc | Command a `trigger: true` input (auto) or any input (manual) |
+| Compile error `Not allow duplicate set property id...` | Auto mode with same Data as input and output | Use `triggerMode: 'manual'`, or split into separate Data |
+| Calc reads stale value written earlier in the same chain | Missing `waitAsync: true` on the preceding write | Set `waitAsync: true` on the write action |
+| Works in Simulator, fails on device | V8 vs Hermes/JSC engine difference | Verify on device (Path 2); avoid engine-sensitive parsing |
+| `console.log` shows nothing | Console only emits during DevTools debug sessions | Attach DevTools, or write debug values to an output Data |
+| `Promise`/`setTimeout` undefined, or `Async mode is required` error | `enableAsync: false` | Set `enableAsync: true` |
+
+## Best Practices
+
+1. **Avoid circular deps**: Set non-triggering inputs (`trigger: false`) or use `manual` mode
+2. **Error handling**: Always set `error` output for scripts that might fail
+3. **Keep scripts pure**: Avoid side effects, return computed values
+4. **Debounce rapid updates**: Use `manual` mode + timer for high-frequency inputs (auto calcs re-run on every write, even unchanged)
+
+## Anti-Patterns (AVOID)
+
+See [Architecture Patterns](architecture-patterns.md) for the full pattern selection guide.
+
+### Using Data Calc as an orchestrator
+Scripts that manage state machines, control UI flow, or coordinate multi-step processes belong in Event Action Chains. Symptoms: if/else on "what happens next", mirror `dFooResult` outputs that copy back to `dFoo` via `valueChange`, or a `dLastInput` field set-then-cleared to force an auto calc. See the "user-driven state machine" recipe in [Architecture Patterns](architecture-patterns.md).

package/skills/bricks-ctor/references/simulator.md

@@ -0,0 +1,132 @@
+# Simulator
+
+What the Simulator can and can't faithfully reproduce — so a passing Simulator run means what you think it means. This is the fidelity companion to Path 1 in [Verification Toolchain](verification-toolchain.md); read that for how to *drive* the Simulator (compile, screenshot, Automations).
+
+## What it is
+
+- The default Path 1 target: it renders your compiled project on your computer, with no device required.
+- It runs in Chromium/Electron — a browser-class runtime, not the device runtime. Two consequences to design verification around: it has a browser's capabilities and limits (below), and its JavaScript engine differs from the device's (iOS runs JSC, Android runs Hermes), so engine-specific behavior won't surface here.
+
+A Simulator screenshot proves **layout, navigation, Standby Transitions, Data wiring, and generator/Automation wiring**. It does *not* prove anything that depends on real hardware, real models, or capabilities the preview runtime lacks.
+
+## Automation screenshots
+
+`match_screenshot` stores Simulator automation artifacts at the project level:
+
+```text
+.bricks/automation_screenshots/
+  last/
+  failed/
+  diff/
+```
+
+There is no application-id subdirectory; in CTOR the project is the application. Generated project `.gitignore` files exclude this directory.
+
+When a `match_screenshot` baseline is missing or updated, the baseline goes under `last/`. When a screenshot mismatch occurs, the current capture goes under `failed/` and the pixel diff goes under `diff/`. File names follow `<screenshotName>+local+<timestamp>.png`.
+
+In CTOR Desktop, `simulator_invoke` reports any automation screenshot files created or changed by the invocation in an `Automation screenshots:` section. It still separately reports the ordinary preview capture at `.bricks/simulator-screenshot.jpg`.
+
+## What the Simulator can't reproduce
+
+Because it runs in a browser-class preview rather than on device hardware, the Simulator cannot exercise these — a green run says nothing about them. Verify on a real device (Path 2):
+
+| Area | In the Simulator |
+|------|------------------|
+| BLE (Central / Peripheral), Video Streaming | Not available |
+| Raw network sockets — UDP, TCP, TCP Server, MQTT Broker | Not available (also why Buttress LAN discovery is a no-op — see [Buttress](buttress.md)) |
+| Android Intent | Not available (Android-only) |
+| On-device database **persistence** (SQLite / Vector Store) | Not available — both run in-memory in the Simulator (see caveats below), so data never survives a reload |
+| GGML Text-to-Speech | No vocoder in the preview — use an ONNX TTS model to hear speech |
+
+These work, but with browser caveats:
+
+| Area | Caveat |
+|------|--------|
+| Serial Port | Works via WebSerial — requires browser support and a user gesture |
+| WebView / WebCrawler | Subject to browser CORS — a load/fetch that works on device may be blocked |
+| On-device AI (LLM / STT / VAD / Vector Store / Reranker) | Runs **single-threaded** — far slower than the device, not representative of real latency. Also subject to the model fallbacks below |
+| On-device database (SQLite — `GENERATOR_SQLITE`) | Runs for real on the in-memory WASM `sqlite-vec` build — `execute` / `query` / `transaction` / batch all work. `storageType: file` is transparently treated as in-memory, so nothing persists across reloads (see above) |
+| Scene3D / Sketch / WebRTC | Supported |
+
+Feature availability also varies across the device platforms themselves (iOS / tvOS / Android / the desktop OSes). When a deployment targets a specific platform's capability, confirm it on that platform.
+
+## Network security
+
+The Simulator blocks insecure connections from `applicationPreview` by default: `http://` and `ws://` requests fail, while `https://` and `wss://` are allowed. The Simulator internally allows its own preview host when running the development preview.
+
+Generated projects include this project-level setting:
+
+```json
+{
+  "allowedInsecureHosts": []
+}
+```
+
+Add explicit entries only when you deliberately need to test an insecure endpoint in the Simulator. A bare `host:port` allows both `http://` and `ws://` for that host:
+
+```json
+{
+  "allowedInsecureHosts": ["localhost:8080"]
+}
+```
+
+Use a URL form when only one insecure protocol should be allowed:
+
+```json
+{
+  "allowedInsecureHosts": ["http://localhost:8080"]
+}
+```
+
+In that example, `http://localhost:8080` is allowed and `ws://localhost:8080` remains blocked.
+
+Prefer HTTPS/WSS for anything that is not local development.
+
+## Feature fallbacks — what the Simulator fakes
+
+So that camera and AI features are usable without device permissions, multi-gigabyte downloads, API keys, or a remote inference backend, the Simulator **transparently substitutes a lightweight stand-in** for a few bricks/generators. The config you author is untouched — only the Simulator's runtime behavior differs. **A fallback render proves wiring and layout, not the real feature.**
+
+| Brick / Generator | In the Simulator | Does NOT prove |
+|-------------------|------------------|----------------|
+| Camera (`BRICK_CAMERA`) | A 3D mock canvas, no camera permission prompt. `takePicture` snapshots the canvas; recording produces a placeholder clip | Real camera feed, focus, recording, permission flow |
+| Maps (`BRICK_MAPS`) | A real interactive map on free OpenStreetMap-based tiles — no Google Maps API key needed. Markers, path polyline, the six themes / map types (approximated with free tile sets + CSS tints), and the zoom / pan / navigate / focus / reset / fit actions all work | Google / Apple Maps rendering, exact `customMapStyle` / theme styling (approximated), traffic / buildings / indoors layers, real device geolocation |
+| Thermal Printer (`GENERATOR_THERMAL_PRINTER`) | A simulated printer — `init` / `checkStatus` / `scan` fake per-driver status and discovered devices (ESC/POS, Star, TSC, Castles); `print` renders an approximate on-screen receipt. A bottom-left bubble shows live status with a fault toggle to exercise error wiring. Print results can be exported as PNG via `bricks-cli` (see below) | Real device connection, actual paper output, exact native driver status codes |
+| LLM (`GENERATOR_LLM`) | Swapped to a tiny local stand-in model | Output quality / latency of your real model |
+| Reranker — GGML (`GENERATOR_RERANKER`) | Swapped to a small local multilingual reranker model | Ranking quality / latency of your real model |
+| Speech-to-Text — GGML (`GENERATOR_SPEECH_INFERENCE`) | Swapped to a tiny local model | Accuracy / latency of your real model |
+| Speech-to-Text — ONNX (`GENERATOR_ONNX_STT`) | Swapped to a tiny whisper model | Accuracy / latency of your real model |
+| Text-to-Speech — ONNX (`GENERATOR_TTS`) | Swapped to a tiny VITS model (no vocoder or speaker embedding) | Voice / quality / latency of your real model |
+| Vector Store (`GENERATOR_VECTOR_STORE`) | Runs with a tiny local embedding model — an OpenAI-source config works **without a key** | Real embeddings / dimensions / recall (and no persistence — see above) |
+| Buttress (all generators) | **Disabled** — there is no remote inference backend in the Simulator | The Buttress offload path — see [Buttress](buttress.md) |
+| MLX LLM (`GENERATOR_MLX_LLM`) | Runs as authored, except Buttress is disabled | The MLX / Buttress path |
+
+These swaps make the AI generators runnable in the Simulator for wiring checks — validate real models, quality, and latency on a device (Path 2).
+
+### Inspecting simulated thermal printer print results
+
+With the Simulator running (CDP at `localhost:19852`, see [Verification Toolchain](verification-toolchain.md)), `bricks-cli` can read the simulated printers and export a print result as a PNG image — no need to open the bubble popover or screenshot the whole window:
+
+```bash
+# Printers + print history (newest first; shows the --index value per result)
+bricks devtools simulator thermal-printer list -p 19852
+bricks devtools simulator thermal-printer list -p 19852 -j --commands   # full print payloads as JSON
+
+# Render one print result to PNG (defaults: the only printer, --index 0 = latest)
+bricks devtools simulator thermal-printer print-result -p 19852 -o receipt.png
+bricks devtools simulator thermal-printer print-result -p 19852 --index 1 --scale 2 -o older.png
+```
+
+The PNG is the same approximate receipt the on-screen preview shows (rendered from the print payload). It proves the payload wiring — content, ordering, alignment, barcode/QR/image presence — not pixel-exact native raster output. Print history is in-memory (up to 10 per printer) and clears on preview reload.
+
+### Running the real implementation instead
+
+Each substituted brick/generator can be switched back to its real implementation per item: open the **gear (Simulator settings)** in the editor's preview toolbar, uncheck the item, and **Apply**. Apply persists the choice and reloads the preview so it takes effect (a plain refresh won't). Use this to, e.g., point a Vector Store at a real API key in the preview, or render the real Google/Apple Maps brick (which needs a Maps API key on web). The browser limits above still apply, and **Buttress stays disabled regardless** — there's no backend for it here.
+
+The Thermal Printer is the exception: it has no real web implementation to switch to (the native drivers can't run in a browser), so it is **always simulated** and is not in the gear list.
+
+## Enough vs. escalate
+
+- **Simulator is enough for:** layout, navigation, Standby Transitions, Data wiring, Automation / state-machine happy paths, and confirming a generator fires and handles its events.
+- **Escalate to a real device for:** anything in the "can't reproduce" tables, real camera / peripherals / payment / identity, real model quality & latency, multi-device Local Sync, on-device persistence, the Buttress offload path, and engine-specific behavior.
+
+The full Path 1/2/3 decision rule lives in [Verification Toolchain](verification-toolchain.md).

package/skills/bricks-ctor/references/source-editing-tools.md

@@ -0,0 +1,81 @@
+# MCP Source-Editing Tools
+
+The project-local `bricks-ctor` MCP server exposes tools that edit `subspaces/**` via
+surgical AST edits, keeping files in the standard generated style. Prefer them over
+hand-editing entry files; they validate references, manage imports, compile-verify, and
+record every operation in `.bricks/edits.jsonl`.
+
+## Entry tools (bricks.ts / generators.ts / canvases.ts / data.ts / animations.ts)
+
+| Tool | Purpose |
+|------|---------|
+| `new_entry` | Create a standard entry skeleton (`file`, `type`, `templateKey`, `alias`, optional initial `set`/`events`) |
+| `edit_entry` | Set/unset dotted paths on an entry: `title`, `property.url`, `outlets.response`, `value`, `switches[0].property.text`, … |
+| `edit_events` | Add/remove/replace/move/clear EventAction items in `events.<eventKey>` |
+| `edit_canvas_items` | Add/replace/remove/move brick items on a Canvas `items` array (frames need numeric x/y/width/height) |
+| `edit_switches` | Add/replace/remove/move switches (id, title, conds, override, disabled, break) |
+| `remove_entry` | Delete an entry; cascades same-subspace references by default, `strict: true` refuses and lists sites |
+
+Addressing: `{ file, entry }` (export const name) is primary; `id` works as a global
+fallback (omit `file`). `edit_entry`/`edit_events` accept a `switch` parameter (switch id
+or index) to edit the facets inside one switch — `edit_switches` owns only the array and
+the conds/override shell.
+
+### Event actions
+
+```jsonc
+{
+  "handler": "system",            // or { "ref": "brickOrGeneratorRef" } or { "subspace": "SUBSPACE_id" }
+  "name": "CHANGE_CANVAS",
+  "params": { "canvasId": { "ref": "mainCanvas" } },   // template params, OR:
+  "dataParams": { "someData": 5 },                      // PROPERTY_BANK-style params
+  "waitAsync": false
+}
+```
+
+System actions derive their `as SystemAction...` cast automatically; entity-action casts
+are added only when passed via `cast`. The compiled source form
+`{ handler, action: { name, params: [...], dataParams: [...] }, waitAsync }` is also
+accepted, and `{ "expr": "<raw EventAction>" }` is the escape hatch for shapes the
+structured form cannot express. Handler refs must resolve to a brick or generator.
+`PROPERTY_BANK_EXPRESSION` expressions are validated against the runtime fold rules at
+edit time: only expression statements, simple `const`/`let` declarations, and a final
+return inside a zero-arg IIFE evaluate — no `if`/`for`/`while` (use ternaries, or a
+DataCalculationScript for branching logic).
+
+## Data-calc tools (DataCalculationScript only)
+
+| Tool | Purpose |
+|------|---------|
+| `new_data_calc` | Create `data-calc/data-calculation-{slug}.ts` + `.sandbox.js`, regenerate `data-calc/index.ts`, wire a minimal subspace root |
+| `edit_data_calc` | Set/unset scalar fields, `output`/`error` refs, replace whole `inputs`/`outputs`, or rewrite the sandbox `code` |
+| `edit_data_calc_io` | Add/remove/replace/clear single `inputs`/`outputs` items (input keys unique; output keys may repeat for fan-out) |
+| `remove_data_calc` | Delete the calc `.ts` + its sandbox file and regenerate the index |
+
+Addressing: `{ file }` or `{ subspace, calc }` where `calc` is alias, id, or filename
+slug (subspace defaults to `subspace-0`). Code is canonicalized to the sandbox file form
+(`export function main() { ... }` — wrapped automatically, `async` added when the body
+uses top-level `await`). `DataCalculationMap` (visual node graph) is out of scope and
+returns `fallback_recommended`.
+
+## Value grammar (everywhere a value appears)
+
+| You pass | Emits |
+|----------|-------|
+| JSON scalar/array/object | literal |
+| `{ "link": "dataRefOrAlias" }` | `linkData(() => data.dX)` (property data-links) |
+| `{ "ref": "idOrAliasOrVarName", "subspace"?: 1 }` | `() => namespace.varName` getter |
+| `{ "expr": "raw TypeScript" }` | spliced verbatim |
+
+References resolve by var name, id, or alias within the target subspace and fail loudly
+when missing or ambiguous — this doubles as reference validation.
+
+## Verification and audit
+
+- Every call compile-verifies by default and returns `verify.configChange` — the minimal
+  compiled-config delta (path-keyed set/unset ops). Skip with per-call `verify: false`
+  or `BRICKS_CTOR_MCP_EDIT_VERIFY=0` when batching, then finish with the `compile` tool.
+- All operations append to `.bricks/edits.jsonl` (gitignored) with inputs, outcomes, and
+  touched sites.
+- Non-standard files or entries (hand-written shapes the AST editor cannot safely
+  rewrite) return `fallback_recommended` — use plain file edits for those cases only.

package/skills/bricks-ctor/references/verification-toolchain.md

@@ -0,0 +1,200 @@
+# Verification Toolchain
+
+Three runtime targets, one decision rule. Verify against the cheapest path that proves what you need to prove.
+
+## Definition of done — the hard gate
+
+Before the agent is allowed to claim work is complete, **all** of the following must be true:
+
+1. **Compile clean.** Latest source passes `compile` with no errors.
+2. **Every Canvas screenshot captured.** A rendered screenshot of every Canvas in the deliverable, captured via the available preview tool (`responseImage: true` when the selected model supports vision) at the target hardware resolution and orientation. Canvases gated behind events are reached via Automation runs (`testId` / `testTitleLike` with `brick_press` / `wait_until_canvas_change` cases). Single-Canvas Subspaces still require a captured screenshot.
+3. **Every screenshot reviewed by the agent.** The agent must read each captured screenshot back through the host's image-reading capability — saving the file is not the same as seeing it. The model that produced the Canvas must also have seen the rendered result, or the verification gate has not passed.
+4. **Reference comparison report.** If the user supplied any reference material (Figma / website / HTML / screenshot / PDF / brand book / competitor), produce a short delta report per Canvas:
+   - What matches the reference.
+   - What intentionally diverges, and why (deployment constraint, BRICKS-runtime semantic, system commitment).
+   - What unintentionally diverges, and the planned fix.
+5. **Path appropriate to deployment executed.** Path 1 by default. Path 2 (on-device) when the deployment depends on real hardware behaviour, or whenever the brief touches payment, identity, peripherals, or LocalSync.
+6. **Console clean.** No 404s on media, no Data-key-undefined warnings, no Generator init failures, no React-style warnings — every console line is either zero or accept-with-a-comment.
+
+What does **not** count as done:
+
+- A single hero-Canvas screenshot.
+- "Looks roughly like the reference" with no per-Canvas comparison.
+- "Compiled successfully" with no rendered preview.
+- A claim of done with no screenshots in evidence.
+- Captured screenshots saved to disk but never read back by the agent.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.
+
+## Path 1 — Simulator (no device required)
+
+The default loop. Always available; deterministic; no device wear; safe for side-effecting flows because nothing real fires.
+
+Before trusting a Simulator screenshot, know what it can and can't reproduce: it runs in the Electron preview (a browser-class runtime, not the device — and not the device's JS engine), can't exercise hardware/peripheral features (BLE, printers, raw sockets, SQLite, …), and substitutes fallbacks for Camera and the AI generators (LLM/STT/Vector Store) with Buttress disabled. See [Simulator](simulator.md) for the fidelity boundaries and the per-item gear to run the real implementation — it's what tells you when a green run is enough vs. when to escalate to Path 2.
+
+`bun update-app` and `bun deploy-app` publish to the BRICKS portal. The local preview reads `.bricks/build/application-config.json` (produced by `compile`) directly.
+
+### Compile tool
+
+Typecheck + compile the project. Gate every iteration on this; everything below assumes a clean compile.
+
+Agent invocation: call the MCP tool `compile` exposed by the `bricks-ctor` MCP server registered for the project. No arguments.
+
+### Simulator tool
+
+Use the preview implementation exposed by the current harness:
+
+- **CTOR Desktop agent session:** use `simulator_invoke`. CTOR Desktop disables the `bricks-ctor` MCP `simulator` tool and routes screenshots/automation through the desktop preview pane instead. If the user already opened the simulator pane, `simulator_invoke` should reuse it rather than start a separate preview.
+- **Pure `bricks-ctor` project / other agent harness:** use the `bricks-ctor` MCP `simulator` tool when `simulator_invoke` is not available.
+
+Both forms are the same verification primitive: launch or reuse Electron preview, take a screenshot, and optionally run a named Automation test by id or partial title. Do not hard-code one tool name into the workflow; choose the available preview tool for the environment.
+
+Common arguments:
+- `delay` (ms before screenshot) — default is harness-specific: usually 3000 for a fresh/standalone preview; CTOR Desktop may capture immediately when its preview already has a settled latest config. Increase if Standby Transitions are still in flight.
+- `width`, `height` — screenshot dimensions in px.
+- `responseImage: true` — return the screenshot as image content when the selected model supports vision. If vision is unavailable, save the screenshot and report the path.
+- `testId` or `testTitleLike` — run a project Automation before the screenshot. Use `testTitleLike` for fuzzy matches (case-insensitive partial title).
+
+Returns text log + saved screenshot path + image content when supported.
+
+### `bun invoke-simulator` (project script)
+
+Sustained dev session — watches `subspaces/`, recompiles on save, exposes CDP at `localhost:19852` (configurable via `--cdp-port`), writes `.bricks/devtools.json` with port/pid for downstream tooling.
+
+Useful flags:
+- `--screenshot` + `--screenshot-delay/width/height/path` — drive screenshot capture without keeping the window open.
+- `--show-menu` — surface the Electron menu (debugging).
+- `--test-id` / `--test-title-like` — run an Automation in this preview.
+- `--no-keep-open` — exit after one screenshot.
+- `--no-cdp` — disable CDP server (rare; default is to expose it).
+- `--clear-cache` — reset cached state between runs.
+
+For ad-hoc CDP inspection against this local preview, connect any CDP client to `localhost:19852` — Chrome DevTools front-end works directly. For an agent-friendly CLI over CDP (screenshot, brick tree/query, input emulation, storage reads, runtime eval, network capture), the `bricks-cli` skill documents the `bricks devtools` command surface — read that skill if it is installed in this workspace. If it is not installed, run `bricks --help` and `bricks devtools --help`; the CLI's own help output is authoritative.
+
+To inspect Data / Property Bank or storage state, prefer the dedicated `bricks devtools storage` subcommands — `storage data-bank get <S_xxxx>` (saved Data values), `storage system persist|memory`, `storage system get <key>` — over hand-written `runtime eval`. Reach for `runtime eval` only for *live* store internals that aren't persisted to a data bank (e.g. a current transient value: `runtime eval "system.data.property('S_xxxx', '<alias>')"`); don't reverse-engineer the `system.*` globals.
+
+### Project Automations
+
+E2E tests authored in TypeScript inside the project (`AutomationTest` / `TestCase`). Test cases include:
+
+- `brick_press` — synthesize a press on a Brick.
+- `wait_until_canvas_change` — assert navigation.
+- `assert_property` — assert a Data value equals expected.
+- `wait_property_update` — wait for a Data value to change.
+- `match_screenshot` — visual regression with stored reference image.
+
+Trigger types: `launch` (runs on app start), `anytime` (manual), `cron` (scheduled).
+
+Important: the automation map id must be `'AUTOMATION_MAP_DEFAULT'` (not a generated id) — the preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
+
+Run a single test from the agent: call the available preview tool (`simulator_invoke` in CTOR Desktop, otherwise `bricks-ctor` MCP `preview`) with `testId` or `testTitleLike`.
+
+## Path 2 — Real device with DevTools enabled
+
+Required when the deployment depends on hardware behaviour the Electron preview cannot reproduce: physical orientation/DPI, real touch hardware (IR overlays, multi-touch), peripherals (camera, BLE, MQTT, NFC, payment, printer, sensors), watchdog cycles on the actual launcher build, fleet-managed reboot semantics, LocalSync across multiple devices, the actual color/luminance of the panel.
+
+**Always Path 2** when the brief touches: payment, identity capture, real-time peripheral data, multi-device LocalSync, certified hardware.
+
+### One-time manual setup (the agent cannot do this)
+
+Ask the user to:
+
+1. On the device, open **Settings** → advanced settings.
+2. Toggle **Chrome DevTools** on. The device starts a DevTools server on the local network on port `19851` (auto-increments if taken).
+3. Confirm **Enable LAN Discovery** is on (default) so the device is discoverable.
+4. Note the device passcode if displayed.
+
+Requires BRICKS Foundation **≥ 2.24** for CDP commands.
+
+### Endpoints exposed once enabled
+
+| Endpoint | URL shape | Use |
+|---|---|---|
+| Web UI | `http://<ip>:19851` | DevTools landing in a browser |
+| CDP | `http://<ip>:19851/devtools-frontend/inspector.html?ws=<ip>:19851/ws/<passcode>` | Chrome DevTools front-end |
+| MCP | `http://<ip>:19851/mcp` | MCP endpoint (Bearer-token auth with passcode) |
+| MCP SSE | `http://<ip>:19851/sse` | Same, SSE transport |
+| Info | `http://<ip>:19851/devtools/info` | Device / server metadata |
+
+### Driving the device
+
+Once DevTools is on, ask the user how they want to drive the verification — Chrome DevTools front-end, an MCP client they already run, or screenshot export from their own tooling — and follow their lead. Capture every Canvas screenshot through whichever path the user picks; the verification gate is about the evidence, not the tool.
+
+For agent-driven CDP/MCP work against the device (`bricks devtools …` with `-a <ip> --passcode <pc>`, plus bridging the device MCP endpoint into an MCP client), the same `bricks-cli` skill referenced in Path 1 covers the on-device case — read it if installed. If not installed, run `bricks --help` and `bricks devtools --help` for the authoritative command listing.
+
+### Running real-device Automations from an agent
+
+There is no `bricks devtools automation` subcommand. Use the DevTools runtime helpers exposed inside the app:
+
+```bash
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "Object.getOwnPropertyNames(automation).sort()" -j
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "automation.list()" -j
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "automation.run('<TEST_id>', { updateScreenshot: false })" --await -j
+```
+
+`automation.run()` starts the device-side run and may return `null`; treat that as accepted, not as a pass/fail result. Wait for the run timeout/window, then verify completion through the app's own state and a screenshot. For app state, use live runtime reads such as:
+
+```bash
+bricks devtools runtime eval -a <ip> -p 19851 --passcode <pc> "JSON.stringify({ result: system.data.property('<S_xxxx>', '<resultAlias>')?.value })" -j
+bricks devtools screenshot -a <ip> -p 19851 --passcode <pc> -o /tmp/device-automation.png
+```
+
+In CTOR Desktop sandboxed sessions, keep these as separate simple commands. Avoid multi-line shell scripts, `for` loops, brace expansion, and command substitution around `bricks devtools`; those can stay sandboxed and lose LAN/device access. After `bun update-app` or a device refresh, the DevTools socket may briefly drop, so wait and probe with one screenshot or one `runtime eval` before running the automation.
+
+### Real-device side-effects warning
+
+Real devices fire real peripherals. Payment terminals charge. MQTT broadcasts on shared topics. BLE advertises to bystanders. Use a **staging** device for verification cycles; never iterate on a production-deployed device unless the user explicitly approves.
+
+## Path 3 — Remote debugging via BRICKS Controller (off-LAN)
+
+Out of scope for the standard verification loop. It exists for ops scenarios where the device is not on the same network. If the user asks for it, point them at the BRICKS Controller documentation rather than attempting it as part of verification.
+
+## Decision rule
+
+```
+default Path 1.
+
+if deployment depends on:
+   physical orientation / DPI / touch HW / peripherals /
+   watchdog on real launcher / LocalSync / certified hardware
+→ escalate to Path 2 before declaring done.
+
+if brief touches payment, identity, peripherals, LocalSync
+→ Path 2 is mandatory, not optional.
+
+if user is off-LAN
+→ Path 3 (out of scope here).
+```
+
+## What to actually verify (per shape)
+
+### Static signage (single-canvas glance loop)
+- Path 1 screenshot captures the loop frame.
+- Watch one full rotation in `bun invoke-simulator` to see all queue items.
+- Cut network mid-loop; confirm cached media plays.
+- Path 2 only if the panel is OLED / has burn-in concerns or specific color profile.
+
+### Multi-canvas state machine (kiosk)
+- Path 1: Automation walking the happy path with `brick_press` + `wait_until_canvas_change` + `assert_property` + `match_screenshot` per Canvas.
+- Cancel + inactivity reset paths verified as Automations.
+- Watchdog reset: kill the runtime, restart, confirm boot Canvas resets transient flow Data.
+- Path 2 mandatory if payment / identity is in the flow — fire a real test transaction on staging hardware.
+
+### Subspace-driven composition
+- Path 1: open the Subspace standalone if the preview supports it; verify in isolation.
+- Embedded test: walk the host's flow; assert Outlets fire as expected via `wait_property_update`.
+- Re-mount test: cause the host to re-bind the Subspace; confirm internal state resets.
+
+### Generator-driven reactive
+- Path 1: drive the source by writing to Data from the runtime (whatever CDP path the user prefers); observe Brick re-render.
+- Throttle / firehose tests: write 100 updates rapidly; confirm the canvas doesn't choke (frame budget intact).
+- Disconnect: simulate source disconnect; confirm UI surfaces stale state, not blank.
+- Threshold transitions: cross every Switch boundary; confirm visual reaction.
+- Path 2 mandatory if the source is a real peripheral — Electron cannot fake the timing or the failure modes.
+
+### Multi-device LocalSync
+- Path 2 mandatory. Two devices on the same LAN with DevTools on. Drive one, observe the other.
+
+## Browser / runtime log discipline
+
+Throughout: the DevTools console must be clean. 404s on media, "Data key not defined" warnings, Generator init failures, React-style warnings — every one is a defect or accept-with-comment. Don't ship around them.