@fugood/bricks-ctor 2.24.8 → 2.24.10

package/compile/index.ts

@@ -4,9 +4,9 @@ import upperFirst from 'lodash/upperFirst'
 import snakeCase from 'lodash/snakeCase'
 import omit from 'lodash/omit'
 import { parse as parseAST } from 'acorn'
-import type { ExportNamedDeclaration, FunctionDeclaration } from 'acorn'
+import type { BlockStatement, 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'
@@ -97,17 +97,28 @@ const compileProperty = (property, errorReference: string, result = {}) => {
 const compileScriptCalculationCode = (code = '') => {
   try {
     const program = parseAST(code, { sourceType: 'module', ecmaVersion: 2020 })
-    // export function main() { ... }
-    const declarationBody = (
-      (program.body[0] as ExportNamedDeclaration).declaration as FunctionDeclaration
-    )?.body
-    return escodegen.generate(declarationBody, {
-      format: {
-        indent: { style: '  ' },
-        semicolons: false,
+    // The stored config holds the bare function body, which codegen re-wraps as
+    // `export function main() { <code> }`. Unwrap it back to that body here.
+    let block = ((program.body[0] as ExportNamedDeclaration).declaration as FunctionDeclaration)
+      ?.body as BlockStatement | undefined
+    if (!block) return code || ''
+    // Earlier versions emitted the whole BlockStatement (braces included), so every
+    // compile -> codegen round-trip nested the body in one more `{ }`. Emit the inner
+    // statements instead, collapsing any wrapper blocks previous round-trips added so
+    // existing over-wrapped sandboxes heal on the next compile.
+    while (block.body.length === 1 && block.body[0].type === 'BlockStatement') {
+      block = block.body[0] as BlockStatement
+    }
+    return escodegen.generate(
+      { type: 'Program', body: block.body },
+      {
+        format: {
+          indent: { style: '  ' },
+          semicolons: false,
+        },
+        comment: true,
       },
-      comment: true,
-    })
+    )
   } catch {
     return code || ''
   }
@@ -181,10 +192,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 +500,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 +589,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 +611,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 +741,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 +1441,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.8",
+  "version": "2.24.10",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.8",
+    "@fugood/bricks-cli": "^2.24.10",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",

package/skills/bricks-ctor/references/architecture-patterns.md

@@ -25,6 +25,7 @@ The primary way to orchestrate multi-step flows. A single event can contain an a
 - Use `waitAsync: true` to await async actions before the next step
 - Use `dataParams` + `mapping` to pass event data downstream
 - This is the "glue" that wires generators, state, and UI together
+- For Generator result UI: await Generator, write done/version Data; route/current Data stays identity.
 
 Sequential `PROPERTY_BANK` / `PROPERTY_BANK_EXPRESSION` actions in one chain read the data values that existed when the chain started. If a later action needs to read what an earlier action wrote, set `waitAsync: true` on the earlier action.
 

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

@@ -87,6 +87,17 @@ const triggerCalc: EventAction = {
 - 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.
@@ -220,6 +231,8 @@ const appendHistory: DataCalculationScript = {
 | `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` |

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/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')
@@ -80,41 +81,13 @@ type CodexMcpConfig = {
   mcp_servers: Record<string, typeof codexProjectMcpServer | typeof projectMcpServer>
 }
 
-// Claude Code and AGENTS.md projects both use the shared project .mcp.json file.
-const defaultMcpConfig = {
-  mcpServers: {
-    'bricks-ctor': projectMcpServer,
-  },
-}
-
-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}`)
-}
-
 const hasClaudeCode = await exists(`${cwd}/CLAUDE.md`)
 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) => {
@@ -282,18 +255,25 @@ if (hasAgentsMd) {
   }
 
   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'] = codexProjectMcpServer
-        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

@@ -1,8 +1,9 @@
-import { readdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { dirname, 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())
@@ -90,7 +86,11 @@ const branchName = isModule
   ? 'BRICKS_PROJECT_try-pull-module'
   : 'BRICKS_PROJECT_try-pull-application'
 
+let landingBranch = ''
 if (isGitRepo && !force) {
+  landingBranch = (await sh`cd ${cwd} && git branch --show-current`.text()).trim()
+  if (!landingBranch) throw new Error('Cannot pull from a detached HEAD')
+
   console.log(`Checking commit ${baseCommitId}...`)
   const found = (await sh`cd ${cwd} && git rev-list -1 ${baseCommitId}`.nothrow().text())
     .trim()
@@ -104,8 +104,8 @@ if (isGitRepo && !force) {
 
   // When the base commit isn't reachable in this clone (server stored a
   // nanoid, or the commit was pruned), fall back to forking from current
-  // HEAD. The downstream merge into main collapses both paths into the
-  // same result, just with different merge bases.
+  // HEAD. The downstream merge into the starting branch collapses both paths
+  // into the same result, just with different merge bases.
   if (found) {
     await sh`cd ${cwd} && git checkout -b ${branchName} ${baseCommitId}`.nothrow()
   } else {
@@ -147,7 +147,9 @@ await Promise.all(
       const result = await format(file.name, file.input, oxfmtConfig)
       content = result.code
     }
-    return writeFile(`${cwd}/${file.name}`, content)
+    const target = join(cwd, file.name)
+    await mkdir(dirname(target), { recursive: true })
+    return writeFile(target, content)
   }),
 )
 
@@ -164,11 +166,11 @@ if (isGitRepo) {
     await sh`cd ${cwd} && git ${commitArgs}`
   }
   if (!force) {
-    // Land the pulled commits on main with a single 3-way merge using
+    // Land the pulled commits on the starting branch with a single 3-way merge using
     // baseCommit as the merge base. The user doesn't have to manage a side
-    // branch, and conflicts (if any) land in the working tree on main where
+    // branch, and conflicts (if any) land in the working tree on the starting branch where
     // auto-compile surfaces them as typecheck errors to resolve in-place.
-    await sh`cd ${cwd} && git checkout main`
+    await sh`cd ${cwd} && git checkout ${landingBranch}`
     const mergeResult = await sh`cd ${cwd} && git merge ${branchName} --no-edit`.nothrow()
     if (mergeResult.exitCode !== 0) {
       // Conflict markers are in the working tree — commit them so the tree
@@ -178,7 +180,7 @@ if (isGitRepo) {
       await sh`cd ${cwd} && git add .`
       const conflictArgs = await buildCommitArgs(
         cwd,
-        ['chore(project): merge with conflicts (resolve in main)'],
+        [`chore(project): merge with conflicts (resolve in ${landingBranch})`],
         ['--no-verify'],
       )
       await sh`cd ${cwd} && git ${conflictArgs}`

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/bricks/Sketch.d.ts

@@ -191,9 +191,11 @@ Default property:
     /* A stroke was just committed (drawn or added programmatically) */
     onStrokeEnd?: Array<EventAction<string & keyof TemplateEventPropsMap['Sketch']['onStrokeEnd']>>
     /* The canvas was cleared */
-    onClear?: Array<EventAction>
+    onClear?: Array<EventAction<string & keyof TemplateEventPropsMap['Sketch']['onClear']>>
     /* Sketch state changed (any commit, undo, redo, clear, or import) */
-    onStateChange?: Array<EventAction>
+    onStateChange?: Array<
+      EventAction<string & keyof TemplateEventPropsMap['Sketch']['onStateChange']>
+    >
     /* Active tool changed */
     onToolChange?: Array<
       EventAction<string & keyof TemplateEventPropsMap['Sketch']['onToolChange']>

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/generators/Tick.d.ts

@@ -33,7 +33,7 @@ Default property:
   property?: {
     /* Start tick on generator initialized */
     init?: boolean | DataLink
-    /* Interval of second for countdown */
+    /* Tick interval in milliseconds for countdown */
     interval?: number | DataLink
     /* Initial value of countdown */
     countdownStartValue?: number | DataLink

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/data.ts

@@ -85,7 +85,7 @@ type SystemDataName =
 type SystemDataInfo = {
   name: SystemDataName
   id: string
-  type: 'string' | 'number' | 'bool' | 'boolean' | 'array' | 'object' | 'any'
+  type: Data['type']
   title?: string
   description?: string
   schema?: object

package/utils/event-props.ts

@@ -142,7 +142,9 @@ export const templateEventPropsMap = {
     },
   },
   Sketch: {
-    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number' },
+    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number', BRICK_SKETCH_STATE: '{}' },
+    onClear: { BRICK_SKETCH_STATE: '{}' },
+    onStateChange: { BRICK_SKETCH_STATE: '{}' },
     onToolChange: { BRICK_SKETCH_TOOL: 'string' },
     onExportImage: { BRICK_SKETCH_IMAGE_URI: 'string' },
   },

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]) })}`
 }