@fugood/bricks-ctor 2.25.0-beta.6 → 2.25.0-beta.60

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

@@ -0,0 +1,252 @@
+# 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).
+
+## One trigger source per result panel
+
+A panel that shows the result of an async action (Generator HTTP/LLM response, request telemetry) reads from a calc whose **trigger should come from a single source**: either the live async outlet, or a completion marker the action chain writes — not both.
+
+- **Outlet-triggered** (`{ data: () => dResponse, trigger: true }`): the calc reruns as outlets land. Use when each outlet is only written once its value is final.
+- **Marker-triggered**: run the generator with `waitAsync: true`, then write a `done` Data the calc triggers on. Use when several outlets settle separately and the panel must wait for all of them.
+
+Wiring both at once — triggering on the live outlet _and_ gating on a separately-written marker — lets the calc run before the outlets have settled (it renders `undefined`/stale) while the marker path masks it intermittently. A panel that updates "sometimes" usually has two competing triggers: pick one, and order it with `waitAsync` so the trigger fires after the values it reads are written.
+
+Scope the panel's calc to the **single value it derives** (the formatted display string), and write sibling status labels — running/done, progress, selected route — imperatively in the event chain with `PROPERTY_BANK`. A calc rewrites _every_ one of its outputs on each run, so a return that omits a key writes `undefined` to that output Data (see [Field Rules](#field-rules-defaults-and-constraints)): folding status labels into a multi-output result calc resets them to `undefined` on any run that returns only the derived value. If a calc genuinely must drive several outputs, return all of their keys every run.
+
+## 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 |
+| Result/telemetry panel shows `undefined` or stale data intermittently | Calc triggered by two sources at once (live outlet + a separately-written marker) | Trigger from one source — see [One trigger source per result panel](#one-trigger-source-per-result-panel) |
+| Sibling status Data (selected/progress) resets to `undefined` after a calc runs | Multi-output result calc whose return omitted those keys on that run | Scope the calc to one output and write status labels imperatively, or return every output key each run — see [One trigger source per result panel](#one-trigger-source-per-result-panel) |
+| 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/{rules → references}/media-flow.md

@@ -31,6 +31,7 @@ const mediaListGenerator: GeneratorMediaFlow = {
   description: '',
   property: {
     boxId: 'promo-box-id',
+    passcode: 'box-read-only-passcode',
   },
   outlets: {
     files: () => promoFilesData, // Array of file objects
@@ -40,6 +41,12 @@ const mediaListGenerator: GeneratorMediaFlow = {
 }
 ```
 
+When hand-writing `GENERATOR_MEDIA_FLOW`, do not use a bare `boxId`. The editor
+flow creates the required authorization, but manual config must include either
+`property.passcode` from a Media Box passcode or `property.accessToken`.
+Without one, devices cannot read the box and the generator will report an
+authorization error.
+
 ## Property Kinds for Media
 
 Link Data properties to Media Flow for asset selection:

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.