@fugood/bricks-ctor 2.24.7 → 2.24.9

package/compile/index.ts

@@ -6,7 +6,7 @@ import omit from 'lodash/omit'
 import { parse as parseAST } from 'acorn'
 import type { ExportNamedDeclaration, FunctionDeclaration } from 'acorn'
 import escodegen from 'escodegen'
-import { makeId } from '../utils/id'
+import { makeSeededId } from '../utils/id'
 import { generateCalulationMap } from './util'
 import { templateActionNameMap } from './action-name-map'
 import { templateEventPropsMap } from '../utils/event-props'
@@ -181,10 +181,17 @@ const compileEvents = (
 
       let handlerKey
       let handlerTemplateKey
-      if (handler === 'system' || typeof handler === 'string') {
-        if (handler.startsWith('SUBSPACE_')) handlerKey = handler
-        else handlerKey = handler.toUpperCase()
-        if (handlerKey === 'SYSTEM') handlerTemplateKey = 'SYSTEM'
+      if (typeof handler === 'string') {
+        // Only the literal 'system' handler is normalized to the SYSTEM template key.
+        // SubspaceID (SUBSPACE_*) and ItemBrickID handlers are kept verbatim: the runtime
+        // resolves them case-sensitively (see mapEventMapHandlersWithNewId), so uppercasing
+        // a mixed-case ItemBrickID would break handler-to-item event wiring.
+        if (handler === 'system') {
+          handlerKey = 'SYSTEM'
+          handlerTemplateKey = 'SYSTEM'
+        } else {
+          handlerKey = handler
+        }
       } else if (typeof handler === 'function') {
         let instance = handler()
         if (instance?.id) {
@@ -482,6 +489,7 @@ const preloadTypes = [
   'media-resource-audio',
   'media-resource-file',
   'lottie-file-uri',
+  'rive-file-uri',
   'ggml-model-asset',
   'gguf-model-asset',
   'binary-asset',
@@ -570,7 +578,7 @@ function compileRunArray(run: unknown[]): unknown[] {
 /**
  * Compile typed TestCase to raw format (strips __typename)
  */
-const compileTestCase = (testCase: TestCase) => ({
+export const compileTestCase = (testCase: TestCase) => ({
   id: testCase.id,
   name: testCase.name,
   hide_short_ref: testCase.hideShortRef,
@@ -592,7 +600,10 @@ const compileTestCase = (testCase: TestCase) => ({
       variable: cond.variable,
       operator: cond.operator,
       value: cond.value,
-      jump_to: cond.jump_to,
+      // `jump_to` may be a getter (() => TestCase) for dynamic case ids (the project generator
+      // emits this form). Resolve it to its id like the `run` array does — otherwise the function
+      // is JSON-serialized to nothing and the conditional jump silently vanishes from the config.
+      jump_to: compileRunElement(cond.jump_to),
     }
   }),
 })
@@ -719,7 +730,14 @@ export const compile = async (app: Application) => {
       // validation (root_canvas_id is required before the conditional
       // schema fix is published).
       if (subspace.module?.link) {
-        const placeholderCanvasId = makeId('canvas')
+        // Seed the placeholder id from the (stable) subspace id. `makeId('canvas')` would take
+        // the count-fallback branch (a process-global counter that is never reset), so the
+        // placeholder id depended on how many prior count-fallback ids had been minted — making
+        // it differ between recompiles and breaking compile's byte-stable-output contract
+        // (phantom config-change ops). `makeSeededId` keeps no global state, so identical source
+        // recompiles to an identical id. (`makeId('canvas', alias)` would instead throw
+        // "Duplicate makeId alias" on the second compile in a long-lived process.)
+        const placeholderCanvasId = makeSeededId('canvas', `${subspaceId}:module-placeholder`)
         subspaceMap[subspaceId] = {
           title: subspace.title,
           description: subspace.description,
@@ -1412,12 +1430,7 @@ export const compile = async (app: Application) => {
                 : null,
             }
 
-            Object.assign(
-              calc,
-              generateCalulationMap(calc.script_config, {
-                snapshotMode: process.env.BRICKS_SNAPSHOT_MODE === '1',
-              }),
-            )
+            Object.assign(calc, generateCalulationMap(calc.script_config, dataCalcId))
           }
           map[dataCalcId] = calc
           return map

package/compile/util.ts

@@ -1,4 +1,4 @@
-import { makeId } from '../utils/id'
+import { makeSeededId } from '../utils/id'
 
 type ScriptConfig = {
   title?: string
@@ -18,30 +18,54 @@ const errorMsg = 'Not allow duplicate set property id between inputs / outputs /
 export const validateConfig = (config: ScriptConfig) => {
   // Skip input/output overlap validation in manual mode (allows same data node in both)
   if (config.trigger_mode === 'manual') return
-  if (config.error && config.inputs[config.error]) {
+  // `inputs` is keyed by data-node id with the OBJECT_SET path as the *value*. The overlap
+  // check is "is this id also an input?" — a key-existence question — so test key presence,
+  // not the path's truthiness. An empty path ('' = OBJECT_SET's default "set whole object")
+  // is a legitimate input value that would otherwise slip the overlap guard.
+  const isInput = (id: string) => Object.prototype.hasOwnProperty.call(config.inputs, id)
+  if (config.error && isInput(config.error)) {
     throw new Error(`${errorMsg}. key: error`)
   }
-  if (config.output && config.inputs[config.output]) {
+  if (config.output && isInput(config.output)) {
     throw new Error(`${errorMsg}. key: output`)
   }
-  if (Object.values(config.outputs).some((value) => value.some((id) => config.inputs[id]))) {
+  if (Object.values(config.outputs).some((value) => value.some(isInput))) {
     throw new Error(`${errorMsg}. key: outputs`)
   }
+  // The same data-node id reused across the output-side targets (output / error / outputs)
+  // also collides: generateCalulationMap spreads their node objects last-wins, so the later
+  // one silently overwrites the earlier wiring (e.g. error == output drops the error change
+  // link). The checks above only compare against `inputs`, so guard the output-side pairs
+  // too. (The same id appearing in multiple `outputs` entries is a supported last-wins case
+  // and stays allowed.)
+  if (config.error && config.output && config.error === config.output) {
+    throw new Error(`${errorMsg}. key: error/output`)
+  }
+  const outputsIds = Object.values(config.outputs).flat()
+  if (config.output && outputsIds.includes(config.output)) {
+    throw new Error(`${errorMsg}. key: output/outputs`)
+  }
+  if (config.error && outputsIds.includes(config.error)) {
+    throw new Error(`${errorMsg}. key: error/outputs`)
+  }
 }
 
 const padding = 15
 const layerXInterval = 300
 const layerYInterval = 150
 
-export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMode?: boolean }) => {
+// `calcId` (the owning script calc's stable id) seeds every derived command-node id, so an
+// unchanged calc recompiles to identical ids and editing one calc never shifts another's —
+// keeping the compiled config byte-stable for change detection. See makeSeededId in utils/id.
+export const generateCalulationMap = (config: ScriptConfig, calcId: string) => {
   validateConfig(config)
-  const sandboxId = makeId('property_bank_command', opts)
-  const sandboxErrorId = makeId('property_bank_command', opts)
-  const sandboxResultId = makeId('property_bank_command', opts)
+  const sandboxId = makeSeededId('property_bank_command', `${calcId}:sandbox-run`)
+  const sandboxErrorId = makeSeededId('property_bank_command', `${calcId}:sandbox-error`)
+  const sandboxResultId = makeSeededId('property_bank_command', `${calcId}:sandbox-result`)
 
   const inputs = Object.entries(config.inputs).reduce(
     (acc, [key, value], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:input:${key}`)
       acc.map[key] = {
         type: 'data-node',
         properties: {},
@@ -123,7 +147,7 @@ export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMod
   let y = 0
   const outputs = Object.entries(config.outputs).reduce(
     (acc, [key, pbList], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:output:${key}`)
       acc.commandIdList.push(commandId)
       acc.map[commandId] = {
         type: 'command-node-object',

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.24.7",
+  "version": "2.24.9",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.7",
+    "@fugood/bricks-cli": "^2.24.9",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",

package/skills/bricks-ctor/SKILL.md

@@ -15,7 +15,7 @@ This skill covers advanced BRICKS features not in the main project instructions.
 | [Animation](references/animation.md) | Animation system for brick transforms and opacity |
 | [Standby Transition](references/standby-transition.md) | Canvas enter/exit animations |
 | [Automations](references/automations.md) | E2E testing and scheduled tasks |
-| [Data Calculation](references/data-calculation.md) | JS sandbox libraries (25+ available) |
+| [Data Calculation](references/data-calculation.md) | Wiring contract, trigger semantics, JS sandbox (25+ libraries) |
 | [Local Sync](references/local-sync.md) | LAN device synchronization |
 | [Remote Data Bank](references/remote-data-bank.md) | Cloud data sync and API access |
 | [Media Flow](references/media-flow.md) | Media asset management |

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

@@ -1,13 +1,20 @@
 # Data Calculation (JS Sandbox)
 
-Transform and compute Data Bank values using JavaScript scripts.
+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.
 
-## DataCalculationScript
+| 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) |
 
-JavaScript code executed in a sandbox with access to inputs and outputs.
+## Authoring Contract
 
 ```typescript
 import { makeId } from 'bricks-ctor'
+import { readFile } from 'node:fs/promises'
 
 const calculation: DataCalculationScript = {
   __typename: 'DataCalculationScript',
@@ -15,9 +22,9 @@ const calculation: DataCalculationScript = {
   title: 'Format Price',
   description: 'Formats price with currency symbol',
   note: '',
-  triggerMode: 'auto', // 'auto' | 'manual'
+  triggerMode: 'auto', // 'auto' (default) | 'manual'
   enableAsync: false,
-  // Inline code
+  // Inline code for short scripts...
   code: `
     const price = inputs.price || 0
     const currency = inputs.currency || 'USD'
@@ -26,118 +33,82 @@ const calculation: DataCalculationScript = {
       currency,
     }).format(price)
   `,
-  // Or load from file (preferred for longer scripts)
-  // import { readFile } from 'node:fs/promises'
+  // ...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
+  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 when input values change (with trigger: true) |
-| `manual` | Only run via `PROPERTY_BANK_COMMAND` action |
+| `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
+    ],
+  },
+}
+```
 
-Use `manual` to prevent circular dependencies or for explicit control.
+- 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 Features
+## Script Sandbox
 
-Scripts run in `use strict` mode with a sandboxed set of globals and libraries.
+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 |
-| `console` | `{ log, error, warn, info }` for debugging |
+| `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`) |
+| `Buffer` | Node.js Buffer (without `allocUnsafe`/`allocUnsafeSlow`) |
 | `btoa`, `atob` | Base64 encoding/decoding |
 
-### Available Libraries
-
-**Utility**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [lodash](https://lodash.com) | `_`, `lodash` | Utility (sync: no debounce/delay/defer) |
-| [voca](https://vocajs.com) | `voca` | String manipulation |
-| [invariant](https://github.com/zertosh/invariant) | `invariant` | Assertions |
-
-**Data & Encoding**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [json5](https://github.com/json5/json5) | `json5` | JSON5 parsing |
-| [qs](https://github.com/ljharb/qs) | `qs` | Query string parsing |
-| [url](https://github.com/defunctzombie/node-url) | `url` | URL parsing |
-| [bytes](https://github.com/visionmedia/bytes.js) | `bytes` | Byte parsing/formatting |
-| [ms](https://github.com/vercel/ms) | `ms` | Millisecond conversion |
-| [base45](https://github.com/irony/base45) | `base45` | Base45 encoding |
-| [iconv-lite](https://github.com/ashtuchkin/iconv-lite) | `iconv` | Character encoding |
-
-**Math & Color**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [mathjs](https://mathjs.org) | `math`, `mathjs` | Math library |
-| [chroma-js](https://gka.github.io/chroma.js) | `chroma` | Color manipulation |
-
-**Date/Time**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [moment](https://momentjs.com) | `moment` | Date/time (auto parseFormat) |
-
-**ID & Hash**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [nanoid](https://github.com/ai/nanoid) | `nanoid` | Unique ID generation |
-| [md5](https://github.com/pvorb/node-md5) | `md5` | MD5 hashing |
-
-**Crypto**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [crypto-browserify](https://github.com/crypto-browserify/crypto-browserify) | `crypto` | Crypto functions |
-| [jsrsasign](https://github.com/kjur/jsrsasign) | `kjurJWS` | JWT/JWS signing |
-| [cose-js](https://github.com/erdtman/COSE-JS) | `coseVerify` | COSE verification (sync) |
-
-**Compression**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [fflate](https://github.com/101arrowz/fflate) | `fflate` | `{ zlibSync, unzlibSync, gzipSync, gunzipSync, compressSync, decompressSync, strFromU8 }` |
-| [cbor](https://github.com/hildjj/node-cbor) | `cbor` | `{ encode, decode, decodeFirstSync, decodeAllSync }` |
-
-**File & Document**
-| Library | Global | Description |
-|---------|--------|-------------|
-| fs | `fs` | File system (limited, no download/upload) |
-| [officeparser](https://github.com/nicktang) | `parseDocument` | Office document parsing (async) |
-| [turndown](https://github.com/mixmark-io/turndown) | `TurndownService` | HTML to Markdown |
-| [opencc-js](https://github.com/nk2028/opencc-js) | `OpenCC` | Chinese conversion `{ Converter, ConverterFactory, CustomConverter, Locale }` |
-| [toon-format](https://github.com/nicktang) | `TOON` | TOON format parsing |
-
-### Runtime Environment
-
-| Platform | Engine |
-|----------|--------|
-| Android | Hermes engine sandbox |
-| iOS | JavaScriptCore sandbox |
-
 ### Async Mode
 
-Enable `enableAsync: true` to unlock additional capabilities:
+Sync mode (default) has **no `Promise`, timers, or `await`**. Enable `enableAsync: true` to unlock:
 
-**Additional async globals:**
-- `Promise`, `setTimeout`, `setInterval`, `setImmediate`
-- `clearTimeout`, `clearInterval`, `clearImmediate`
-- `requestAnimationFrame`
-- Full lodash (including `debounce`, `delay`, `defer`)
+- `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: `
@@ -149,14 +120,63 @@ code: `
 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
@@ -165,31 +185,51 @@ code: `
 `,
 ```
 
-## Triggering Manually
+### Manual Self-Referential Update
 
-Use `PROPERTY_BANK_COMMAND` system action to trigger a manual calculation. `input` references a Data that is a trigger input (`trigger: true`) of the target calc — the system runs the calc(s) that data feeds into. It does NOT reference the DataCalculation itself.
+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 triggerCalc: EventAction = {
-  handler: 'system',
-  action: {
-    __actionName: 'PROPERTY_BANK_COMMAND',
-    parent: 'System',
-    dataParams: [
-      { input: () => priceData }, // Reference to a trigger Data input of the calc
-    ],
-  },
+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.
 ```
 
-When the same chain writes a calc input (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).
+## 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
+4. **Debounce rapid updates**: Use `manual` mode + timer for high-frequency inputs (auto calcs re-run on every write, even unchanged)
 
 ## Anti-Patterns (AVOID)
 
@@ -197,13 +237,3 @@ See [Architecture Patterns](architecture-patterns.md) for the full pattern selec
 
 ### 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).
-
-### Quick reference
-
-| 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) |

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

@@ -69,6 +69,8 @@ Useful flags:
 
 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:
@@ -118,6 +120,25 @@ Once DevTools is on, ask the user how they want to drive the verification — Ch
 
 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.

package/skills/bricks-design/SKILL.md

@@ -1,30 +1,20 @@
 ---
 name: bricks-design
 description: >-
-  Visual design discipline for Applications and Subspaces — type,
-  palette, asset acquisition, design language, system commitment,
-  visual rhythm, brand. TRIGGER for visual / aesthetic / system /
-  style / brand-asset work even when the user names the surface in
-  product terms — slideshow / pitch deck / introduction / explainer
-  / storyboard; kiosk / signage / menu board / lobby / reception /
-  wayfinding / retail / hospitality / museum / transit; translate /
-  port / rebuild from Figma / HTML / screenshot / website / PDF /
-  brand book; vague creative brief ("design something for the
-  lobby"); branded scene work; iteration on existing Subspace
-  (rework, redesign, audit visual system, tighten the type / palette
-  / motion / rhythm). For end-to-end briefs (kiosk, dashboard,
-  interactive screen) this skill invokes in parallel with bricks-ux,
-  which carries the interaction / flow / usability layer. SKIP for
-  pure usability / flow / journey / affordance / feedback / recovery
-  / accessibility / multilingual audits — those go to bricks-ux. SKIP
-  for single-Brick or Generator template work
-  (create-brick-or-generator), debugging or refactoring with no
-  design intent, or non-display deliverables (CLI, server, tooling).
-  Encodes architecture truths, performance and complexity guardrails,
-  input-translation rules, visual languages library, Direction
-  Advisor for vague briefs, Media Flow protocol for branded work.
-  Verification toolchain (compile, preview tool selection, on-device DevTools,
-  Path 1/2/3) lives in the bricks-ctor skill.
+  Visual design discipline for Applications and Subspaces — type, palette, asset
+  acquisition, design language, system commitment, visual rhythm, brand. TRIGGER
+  for visual / aesthetic / system / style / brand-asset work even when named in
+  product terms — slideshow, pitch deck, explainer, kiosk, signage, menu board,
+  lobby, wayfinding, retail, museum, transit; translate or rebuild from Figma /
+  HTML / screenshot / website / PDF / brand book; vague creative briefs; branded
+  scenes; rework or audit of an existing Subspace's type / palette / motion /
+  rhythm. For end-to-end briefs invoke in parallel with bricks-ux (interaction /
+  flow layer). SKIP for pure usability / flow / accessibility audits (bricks-
+  ux), single-Brick or Generator template work (create-brick-or-generator),
+  debugging without design intent, or non-display deliverables. Encodes
+  architecture truths, performance guardrails, input-translation rules, visual
+  languages, Direction Advisor, Media Flow protocol; verification toolchain
+  lives in bricks-ctor.
 ---
 
 # BRICKS Design

package/skills/bricks-ux/SKILL.md

@@ -1,26 +1,20 @@
 ---
 name: bricks-ux
 description: >-
-  Interaction design and end-user experience for any Application or
-  Subspace built on Canvases, Bricks, Generators, Data, DataCalculation.
-  TRIGGER on usability / flow / interaction / journey / state /
-  affordance / feedback / recovery / accessibility audits and design
-  work — "audit this flow", "improve usability", "design the wait
-  state", "fix the error path", "make the kiosk usable", "what does the
-  user do when X breaks", "design the QR scan UX", "design the payment
-  flow", "design the mic / listening state", "design the monitor's
-  alarm state", "design for multilingual", "design for low vision",
-  "design idle and attractor states". Also triggers in parallel with
-  visual-design work for end-to-end deliverables (kiosk / signage /
-  dashboard / interactive screen / pitch deck) where the interaction
-  shape matters as much as the look. SKIP for purely visual / aesthetic
-  / system / style / brand-asset / typography / palette work — those
-  are visual design, not interaction design. Encodes a universal
-  user-journey spine, interaction archetypes, pressable composition,
-  monitoring-screen discipline, designed flow states, accessibility,
-  and a tiered UX critique. Hardware floors are deployment-relative;
-  web habits (hover affordances, modal-as-default, scroll, page-submit
-  forms) do not transfer.
+  Interaction design and end-user experience for any Application or Subspace
+  built on Canvases, Bricks, Generators, Data, DataCalculation. TRIGGER on
+  usability / flow / interaction / journey / state / affordance / feedback /
+  recovery / accessibility audits and design work — "audit this flow", "improve
+  usability", "design the wait state", "make the kiosk usable", "design the
+  payment flow", "design idle and attractor states", "design for multilingual /
+  low vision". Also triggers in parallel with visual-design work for end-to-end
+  deliverables (kiosk, signage, dashboard, interactive screen, pitch deck) where
+  interaction shape matters as much as look. SKIP for purely visual / aesthetic
+  / style / brand-asset / typography / palette work — that is bricks-design.
+  Encodes a universal user-journey spine, interaction archetypes, pressable
+  composition, monitoring-screen discipline, designed flow states,
+  accessibility, tiered UX critique; hardware floors are deployment-relative and
+  web habits do not transfer.
 ---
 
 # BRICKS UX

package/tools/_cli-error.ts

@@ -0,0 +1,17 @@
+// Extract a human-readable message from a `bricks ... --json` failure payload.
+//
+// On failure the CLI prints `{ "error": { "message": "..." } }` (or the older
+// `{ "error": "..." }`) to stdout/stderr. Earlier call sites built that message
+// inside the same `try` that wrapped `JSON.parse`, so the `throw` was caught by
+// its own `catch` and replaced with the raw JSON blob — the human-readable
+// message never surfaced. Parsing here, outside any throw, avoids that trap.
+export function extractCliErrorMessage(output: string, fallback: string): string {
+  try {
+    const { error } = JSON.parse(output)
+    const message = error?.message ?? error
+    if (typeof message === 'string' && message) return message
+  } catch {
+    // output is not JSON — fall through to the raw output below
+  }
+  return output || fallback
+}

package/tools/_mcp-config.ts

@@ -0,0 +1,42 @@
+import { readFile, writeFile, stat } from 'fs/promises'
+
+const exists = async (f: string) => {
+  try {
+    await stat(f)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Refresh the `bricks-ctor` entry in a project's `.mcp.json` while preserving every other MCP
+// server the user configured. A malformed `.mcp.json` is left untouched (with a warning)
+// rather than overwritten with the default — clobbering it would silently delete the user's
+// other server entries. This mirrors `setupClaudeAutoMode`'s handling of a malformed
+// `settings.local.json` in postinstall.ts.
+export const handleMcpConfigOverride = async (mcpConfigPath: string, projectMcpServer: object) => {
+  let mcpConfig: { mcpServers: Record<string, unknown> }
+  if (await exists(mcpConfigPath)) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(await readFile(mcpConfigPath, 'utf-8'))
+    } catch {
+      console.warn(`Skipping .mcp.json update; ${mcpConfigPath} is not valid JSON`)
+      return
+    }
+    mcpConfig =
+      parsed && typeof parsed === 'object'
+        ? (parsed as { mcpServers: Record<string, unknown> })
+        : { mcpServers: {} }
+    if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== 'object') {
+      mcpConfig.mcpServers = {}
+    }
+    mcpConfig.mcpServers['bricks-ctor'] = projectMcpServer
+    delete mcpConfig.mcpServers['bricks-project']
+  } else {
+    mcpConfig = { mcpServers: { 'bricks-ctor': projectMcpServer } }
+  }
+
+  await writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`)
+  console.log(`Updated ${mcpConfigPath}`)
+}

package/tools/deploy.ts

@@ -1,6 +1,7 @@
 import { access, readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
+import { extractCliErrorMessage } from './_cli-error'
 import { buildCommitArgs } from './_git-author'
 import { writeLastPushedCommit } from './_last-pushed-commit'
 
@@ -162,12 +163,7 @@ const result = await sh`${args}`.quiet().nothrow()
 
 if (result.exitCode !== 0) {
   const output = result.stderr.toString() || result.stdout.toString()
-  try {
-    const json = JSON.parse(output)
-    throw new Error(json.error || 'Release failed')
-  } catch {
-    throw new Error(output || 'Release failed')
-  }
+  throw new Error(extractCliErrorMessage(output, 'Release failed'))
 }
 
 const output = JSON.parse(result.stdout.toString())

package/tools/mcp-tools/huggingface.ts

@@ -269,6 +269,28 @@ const fetchHFModelDetails = async (modelId: string): Promise<HFModel> => {
 // Example: Mixtral-8x22B-v0.1.IQ3_XS-00001-of-00005.gguf
 const ggufSplitPattern = /-(\d{5})-of-(\d{5})\.gguf$/
 
+export const buildGGUFSplitFiles = (
+  filename: string,
+  splitTotal: string,
+  siblings: HFSibling[],
+): HFSibling[] => {
+  const siblingByFilename = new Map<string, HFSibling>()
+  for (const sibling of siblings) {
+    if (!siblingByFilename.has(sibling.rfilename)) siblingByFilename.set(sibling.rfilename, sibling)
+  }
+
+  return Array.from({ length: Number(splitTotal) }, (_, i) => {
+    const split = String(i + 1).padStart(5, '0')
+    const splitRFilename = filename.replace(ggufSplitPattern, `-${split}-of-${splitTotal}.gguf`)
+    const sibling = siblingByFilename.get(splitRFilename)
+    return {
+      rfilename: splitRFilename,
+      size: sibling?.size,
+      lfs: sibling?.lfs,
+    }
+  })
+}
+
 export function register(server: McpServer) {
   server.tool(
     'huggingface_search',
@@ -657,19 +679,7 @@ export function register(server: McpServer) {
 
         if (isSplit) {
           const [, , splitTotal] = matched!
-          const splitFiles = Array.from({ length: Number(splitTotal) }, (_, i) => {
-            const split = String(i + 1).padStart(5, '0')
-            const splitRFilename = filename.replace(
-              ggufSplitPattern,
-              `-${split}-of-${splitTotal}.gguf`,
-            )
-            const sibling = siblings.find((sb) => sb.rfilename === splitRFilename)
-            return {
-              rfilename: splitRFilename,
-              size: sibling?.size,
-              lfs: sibling?.lfs,
-            }
-          })
+          const splitFiles = buildGGUFSplitFiles(filename, splitTotal, siblings)
 
           const first = splitFiles[0]
           const rest = splitFiles.slice(1)

package/tools/mcp-tools/icons.ts

@@ -36,11 +36,31 @@ const iconList = Object.entries(glyphmap as Record<string, number>).map(([name,
   return { name, code, styles }
 })
 
-const iconFuse = new Fuse(iconList, {
+const fuseOptions = {
   keys: ['name'],
   threshold: 0.3,
   includeScore: true,
-})
+}
+
+const iconFuse = new Fuse(iconList, fuseOptions)
+const iconFuseByStyle = new Map<IconStyle, Fuse<(typeof iconList)[number]>>()
+
+function getStyleFuse(style: IconStyle) {
+  let fuse = iconFuseByStyle.get(style)
+  if (!fuse) {
+    fuse = new Fuse(
+      iconList.filter((icon) => icon.styles.includes(style)),
+      fuseOptions,
+    )
+    iconFuseByStyle.set(style, fuse)
+  }
+  return fuse
+}
+
+export function searchIcons(query: string, limit: number, style?: IconStyle) {
+  if (style) return getStyleFuse(style).search(query, { limit })
+  return iconFuse.search(query, { limit })
+}
 
 export function register(server: McpServer) {
   server.tool(
@@ -54,11 +74,7 @@ export function register(server: McpServer) {
         .describe('Filter by icon style'),
     },
     async ({ query, limit, style }) => {
-      let results = iconFuse.search(query, { limit: style ? limit * 3 : limit })
-
-      if (style) {
-        results = results.filter((r) => r.item.styles.includes(style)).slice(0, limit)
-      }
+      const results = searchIcons(query, limit, style)
 
       const icons = results.map((r) => ({
         name: r.item.name,

package/tools/postinstall.ts

@@ -12,6 +12,7 @@ import {
 } from 'fs/promises'
 import * as path from 'path'
 import TOML from '@iarna/toml'
+import { handleMcpConfigOverride } from './_mcp-config'
 
 const cwd = process.cwd()
 const projectSkillsDir = path.join(cwd, '.bricks', 'skills')
@@ -69,36 +70,15 @@ const projectMcpServer = {
   args: [`${cwd}/node_modules/@fugood/bricks-ctor/tools/mcp-server.ts`],
 }
 
-type CodexMcpConfig = {
-  mcp_servers: Record<string, typeof projectMcpServer>
-}
-
-// Claude Code and AGENTS.md projects both use the shared project .mcp.json file.
-const defaultMcpConfig = {
-  mcpServers: {
-    'bricks-ctor': projectMcpServer,
-  },
+// Codex cancels MCP tool calls it cannot prompt approval for (e.g. `codex exec`),
+// so the project-local server's tools must be pre-approved in its config entry.
+const codexProjectMcpServer = {
+  ...projectMcpServer,
+  default_tools_approval_mode: 'approve',
 }
 
-const handleMcpConfigOverride = async (mcpConfigPath: string) => {
-  let mcpConfig: { mcpServers: Record<string, typeof projectMcpServer> } | null = null
-  if (await exists(mcpConfigPath)) {
-    const configStr = await readFile(mcpConfigPath, 'utf-8')
-    try {
-      mcpConfig = JSON.parse(configStr)
-      if (!mcpConfig?.mcpServers) throw new Error('mcpServers is not defined')
-      mcpConfig.mcpServers['bricks-ctor'] = projectMcpServer
-      delete mcpConfig.mcpServers['bricks-project']
-    } catch {
-      mcpConfig = defaultMcpConfig
-    }
-  } else {
-    mcpConfig = defaultMcpConfig
-  }
-
-  await writeFile(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`)
-
-  console.log(`Updated ${mcpConfigPath}`)
+type CodexMcpConfig = {
+  mcp_servers: Record<string, typeof codexProjectMcpServer | typeof projectMcpServer>
 }
 
 const hasClaudeCode = await exists(`${cwd}/CLAUDE.md`)
@@ -107,7 +87,7 @@ const hasAgentsMd = await exists(`${cwd}/AGENTS.md`)
 if (hasClaudeCode || hasAgentsMd) {
   // Keep the workspace-level JSON MCP config aligned for tools that read .mcp.json.
   const mcpConfigPath = `${cwd}/.mcp.json`
-  await handleMcpConfigOverride(mcpConfigPath)
+  await handleMcpConfigOverride(mcpConfigPath, projectMcpServer)
 }
 
 const copyMissingSkills = async (sourceDir: string, targetDir: string) => {
@@ -196,27 +176,104 @@ if (hasClaudeCode || hasAgentsMd) {
   await setupSkills()
 }
 
+type ClaudeSettings = {
+  autoMode?: {
+    environment?: string[]
+    allow?: string[]
+    soft_deny?: string[]
+    hard_deny?: string[]
+  }
+  [key: string]: unknown
+}
+
+// Trusted infrastructure for auto mode's classifier. `$defaults` keeps the
+// built-in environment (the working repo and its git remotes); the extra
+// entries stop routine syncs to the BRICKS backend from being treated as
+// external exfiltration. See https://code.claude.com/docs/en/auto-mode-config
+const autoModeEnvironment = [
+  '$defaults',
+  'Organization: BRICKS (bricks.tools). Primary use: building BRICKS apps/modules with the bricks CLI and the local bricks-ctor MCP server.',
+  'Trusted internal domains: all *.bricks.tools services — api.bricks.tools (project GraphQL API), bank.bricks.tools (config & asset Bank API), cdn.bricks.tools (asset CDN), plus the control/display/activity services. This project syncs its config and assets to these endpoints.',
+]
+
+// `.claude/settings.local.json` is per-developer local config; keep it untracked.
+const ensureSettingsLocalGitignored = async () => {
+  const gitignorePath = path.join(cwd, '.gitignore')
+  const entry = '.claude/settings.local.json'
+  const coveredBy = new Set([entry, '.claude', '.claude/', '.claude/*', '*.local.json'])
+
+  let content = ''
+  if (await exists(gitignorePath)) {
+    content = await readFile(gitignorePath, 'utf-8')
+    if (content.split('\n').some((line) => coveredBy.has(line.trim()))) return
+  }
+
+  const separator = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n'
+  await writeFile(gitignorePath, `${content}${separator}# Claude Code local settings\n${entry}\n`)
+  console.log(`Added ${entry} to .gitignore`)
+}
+
+// Pre-configure auto mode once, on initial setup. We only seed the classifier's
+// trusted infrastructure — not `permissions.defaultMode: 'auto'`, which Claude
+// Code ignores from project/local settings (a repo can't grant itself auto mode;
+// it only takes effect from ~/.claude/settings.json). An existing autoMode block
+// is left untouched so reinstalls never clobber a developer's customizations.
+const setupClaudeAutoMode = async () => {
+  const settingsPath = path.join(cwd, '.claude', 'settings.local.json')
+
+  let settings: ClaudeSettings = {}
+  if (await exists(settingsPath)) {
+    try {
+      settings = JSON.parse(await readFile(settingsPath, 'utf-8'))
+    } catch {
+      console.warn(`Skipping auto mode setup; ${settingsPath} is not valid JSON`)
+      return
+    }
+    if (settings.autoMode) return
+  }
+
+  settings.autoMode = { environment: autoModeEnvironment }
+
+  await mkdir(path.dirname(settingsPath), { recursive: true })
+  await writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`)
+  console.log(`Set up auto mode in ${settingsPath}`)
+
+  await ensureSettingsLocalGitignored()
+}
+
+if (hasClaudeCode) {
+  // Pre-configure auto mode's trusted infrastructure for Claude Code projects.
+  await setupClaudeAutoMode()
+}
+
 if (hasAgentsMd) {
   // Codex stores its project-local MCP config in .codex/config.toml.
   const defaultCodexMcpConfig = {
     mcp_servers: {
-      'bricks-ctor': projectMcpServer,
+      'bricks-ctor': codexProjectMcpServer,
     },
   }
 
   const handleCodexMcpConfigOverride = async (mcpConfigPath: string) => {
-    let mcpConfig: CodexMcpConfig | null = null
+    let mcpConfig: CodexMcpConfig
     if (await exists(mcpConfigPath)) {
-      const configStr = await readFile(mcpConfigPath, 'utf-8')
+      let parsed: unknown
       try {
-        const parsed = TOML.parse(configStr) as Partial<CodexMcpConfig>
-        if (!parsed?.mcp_servers) throw new Error('mcp_servers is not defined')
-        mcpConfig = { mcp_servers: parsed.mcp_servers }
-        mcpConfig.mcp_servers['bricks-ctor'] = projectMcpServer
-        delete mcpConfig.mcp_servers['bricks-project']
+        parsed = TOML.parse(await readFile(mcpConfigPath, 'utf-8'))
       } catch {
-        mcpConfig = defaultCodexMcpConfig
+        // A malformed config is left untouched (with a warning) rather than overwritten with
+        // the default — clobbering it would silently delete the user's other server entries.
+        // Mirrors handleMcpConfigOverride's handling of a malformed .mcp.json.
+        console.warn(`Skipping .codex/config.toml update; ${mcpConfigPath} is not valid TOML`)
+        return
+      }
+      mcpConfig =
+        parsed && typeof parsed === 'object' ? (parsed as CodexMcpConfig) : { mcp_servers: {} }
+      if (!mcpConfig.mcp_servers || typeof mcpConfig.mcp_servers !== 'object') {
+        mcpConfig.mcp_servers = {}
       }
+      mcpConfig.mcp_servers['bricks-ctor'] = codexProjectMcpServer
+      delete mcpConfig.mcp_servers['bricks-project']
     } else {
       mcpConfig = defaultCodexMcpConfig
     }

package/tools/pull.ts

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { format } from 'oxfmt'
 import { sh } from './_shell'
+import { extractCliErrorMessage } from './_cli-error'
 import { buildCommitArgs } from './_git-author'
 import { readLastPushedCommit, writeLastPushedCommit } from './_last-pushed-commit'
 
@@ -68,12 +69,7 @@ const result = await sh`bricks ${command} project-pull ${app.id} --json`.quiet()
 
 if (result.exitCode !== 0) {
   const output = result.stderr.toString() || result.stdout.toString()
-  try {
-    const json = JSON.parse(output)
-    throw new Error(json.error || 'Pull failed')
-  } catch {
-    throw new Error(output || 'Pull failed')
-  }
+  throw new Error(extractCliErrorMessage(output, 'Pull failed'))
 }
 
 const { files, lastCommitId: serverLastCommitId } = JSON.parse(result.stdout.toString())

package/tools/push-config.ts

@@ -1,6 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
+import { extractCliErrorMessage } from './_cli-error'
 import { buildCommitArgs } from './_git-author'
 import { writeLastPushedCommit } from './_last-pushed-commit'
 
@@ -99,12 +100,7 @@ const result = await sh`${args}`.quiet().nothrow()
 
 if (result.exitCode !== 0) {
   const output = result.stderr.toString() || result.stdout.toString()
-  try {
-    const json = JSON.parse(output)
-    throw new Error(json.error?.message || json.error || 'Update failed')
-  } catch {
-    throw new Error(output || 'Update failed')
-  }
+  throw new Error(extractCliErrorMessage(output, 'Update failed'))
 }
 
 const output = JSON.parse(result.stdout.toString())

package/types/data-calc-command/datetime.d.ts

@@ -22,7 +22,7 @@ export type DataCommandDatetimeDate = DataCommand & {
   outputs?: Array<DataCalcOutput<'result'> /* target: number */>
 }
 
-/* Day — Get day (Sunday is 7) */
+/* Day — Get day of week (0-based: Sunday is 0, Saturday is 6) */
 export type DataCommandDatetimeDay = DataCommand & {
   __commandName: 'DATETIME_DAY'
   inputs?: Array<
@@ -64,7 +64,7 @@ export type DataCommandDatetimeMinute = DataCommand & {
   outputs?: Array<DataCalcOutput<'result'> /* target: number */>
 }
 
-/* Month — Get month (January is 1) */
+/* Month — Get month (0-based: January is 0, December is 11) */
 export type DataCommandDatetimeMonth = DataCommand & {
   __commandName: 'DATETIME_MONTH'
   inputs?: Array<

package/types/data-calc-command/sandbox.d.ts

@@ -18,7 +18,9 @@ export type DataCommandSandboxGetReturnValue = DataCommand & {
 /* Run JS — Run JavaScript code
 
 - Default `use strict`
-- Global functions fetch, XMLHttpRequest, setTimeout, setInterval... are not available.
+- Global functions fetch, XMLHttpRequest are not available.
+- setTimeout, setInterval, Promise... require Enable Async.
+- Built-in globals: Platform, Buffer, btoa/atob, TextEncoder/TextDecoder
 
 ##### Available libraries (global)
 
@@ -43,10 +45,16 @@ export type DataCommandSandboxGetReturnValue = DataCommand & {
 - fflate (Not support async, callback and stream)
 - iconv (Use iconv-lite)
 - OpenCC (Use opencc-js)
+- fs (Limited, no download/upload)
+- parseDocument (Use officeparser, requires Enable Async)
+- TurndownService (Use turndown, HTML to Markdown)
+- TOON (Use toon-format/toon)
 
 Android: Running on the sandbox of Hermes engine
 
-iOS: Running on the sandbox of iOS built-in JavaScriptCore */
+iOS: Running on the sandbox of iOS built-in JavaScriptCore
+
+Desktop / Web: Running on the sandbox of a Web Worker */
 export type DataCommandSandboxRunJavascript = DataCommand & {
   __commandName: 'SANDBOX_RUN_JAVASCRIPT'
   inputs?: Array<

package/utils/calc.ts

@@ -28,6 +28,10 @@ export const generateDataCalculationMapEditorInfo = (
     DataCalculationData | DataCommand,
     Set<DataCalculationData | DataCommand>
   >()
+  const nodeById = new Map<string, DataCalculationData | DataCommand>()
+  for (const node of nodes) {
+    if ('id' in node) nodeById.set(node.id, node)
+  }
 
   // Analyze node connections
   nodes.forEach((node) => {
@@ -48,7 +52,7 @@ export const generateDataCalculationMapEditorInfo = (
             if (!connectedTo.has(node)) {
               connectedTo.set(node, new Set())
             }
-            const sourceNode = nodes.find((n) => 'id' in n && n.id === conn.id)
+            const sourceNode = nodeById.get(conn.id)
             if (sourceNode) {
               connectedTo.get(node)!.add(sourceNode)
             }

package/utils/id.ts

@@ -69,63 +69,65 @@ const makeStableUuid = (type: string, alias?: string) => {
   })
 }
 
-// Make stable ids by default; explicit snapshotMode: false preserves the random escape hatch.
-export const makeId = (type: IdType, aliasOrOpts?: string | IdOptions, opts?: IdOptions) => {
-  if (type === 'subspace') {
-    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
-  }
-
-  const alias = typeof aliasOrOpts === 'string' ? aliasOrOpts : undefined
-  const options = typeof aliasOrOpts === 'string' ? opts : (aliasOrOpts ?? opts)
-
-  let prefix = ''
+const idPrefix = (type: IdType): string => {
   switch (type) {
     case 'animation':
-      prefix = 'ANIMATION_'
-      break
+      return 'ANIMATION_'
     case 'brick':
-      prefix = 'BRICK_'
-      break
+      return 'BRICK_'
     case 'dynamic-brick':
-      prefix = 'DYNAMIC_BRICK_'
-      break
+      return 'DYNAMIC_BRICK_'
     case 'canvas':
-      prefix = 'CANVAS_'
-      break
+      return 'CANVAS_'
     case 'generator':
-      prefix = 'GENERATOR_'
-      break
+      return 'GENERATOR_'
     case 'data':
-      prefix = 'PROPERTY_BANK_DATA_NODE_'
-      break
+      return 'PROPERTY_BANK_DATA_NODE_'
     case 'switch':
-      prefix = 'BRICK_STATE_GROUP_'
-      break
+      return 'BRICK_STATE_GROUP_'
     case 'property_bank_command':
-      prefix = 'PROPERTY_BANK_COMMAND_NODE_'
-      break
+      return 'PROPERTY_BANK_COMMAND_NODE_'
     case 'property_bank_calc':
-      prefix = 'PROPERTY_BANK_COMMAND_MAP_'
-      break
+      return 'PROPERTY_BANK_COMMAND_MAP_'
     case 'automation_map':
-      prefix = 'AUTOMATION_MAP_'
-      break
+      return 'AUTOMATION_MAP_'
     case 'test':
-      prefix = 'TEST_'
-      break
+      return 'TEST_'
     case 'test_case':
-      prefix = 'TEST_CASE_'
-      break
+      return 'TEST_CASE_'
     case 'test_var':
-      prefix = 'TEST_VAR_'
-      break
+      return 'TEST_VAR_'
     default:
+      return ''
+  }
+}
+
+// Make stable ids by default; explicit snapshotMode: false preserves the random escape hatch.
+export const makeId = (type: IdType, aliasOrOpts?: string | IdOptions, opts?: IdOptions) => {
+  if (type === 'subspace') {
+    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
   }
 
+  const alias = typeof aliasOrOpts === 'string' ? aliasOrOpts : undefined
+  const options = typeof aliasOrOpts === 'string' ? opts : (aliasOrOpts ?? opts)
+
   const useCountFallback = aliasOrOpts === undefined && opts === undefined
   const id =
     alias !== undefined || options?.snapshotMode || useCountFallback
       ? makeStableUuid(type, alias)
       : uuid()
-  return `${prefix}${id}`
+  return `${idPrefix(type)}${id}`
+}
+
+// Deterministic id derived solely from a caller-supplied seed. Unlike makeId it keeps no
+// global state — no incrementing counter, no alias registry — so the same (type, seed)
+// always maps to the same id on every compile and in any process. Compiled artifacts seed
+// their ids this way (e.g. generateCalulationMap's command nodes, seeded by their calc id +
+// structural role) so unchanged source recompiles byte-identically and editing one calc
+// never shifts another's ids. The seed must be unique within a single config.
+export const makeSeededId = (type: IdType, seed: string) => {
+  if (type === 'subspace') {
+    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
+  }
+  return `${idPrefix(type)}${uuid({ random: hashToRandomBytes([readApplicationId(), type, seed]) })}`
 }