@fugood/bricks-project 2.24.4 → 2.24.5

package/compile/action-name-map.ts

@@ -782,6 +782,11 @@ export const templateActionNameMap = {
       seed: 'GENERATOR_LLM_SEED',
       typicalP: 'GENERATOR_LLM_TYPICAL_P',
       ignoreEos: 'GENERATOR_LLM_IGNORE_EOS',
+      mtpSpeculativeDecoding: 'GENERATOR_LLM_MTP_SPECULATIVE_DECODING',
+      mtpDraftTokens: 'GENERATOR_LLM_MTP_DRAFT_TOKENS',
+      mtpDraftMinTokens: 'GENERATOR_LLM_MTP_DRAFT_MIN_TOKENS',
+      mtpDraftMinProbability: 'GENERATOR_LLM_MTP_DRAFT_MIN_PROBABILITY',
+      mtpDraftSplitProbability: 'GENERATOR_LLM_MTP_DRAFT_SPLIT_PROBABILITY',
       functionCallEnabled: 'GENERATOR_LLM_FUNCTION_CALL_ENABLED',
       functionCallSchema: 'GENERATOR_LLM_FUNCTION_CALL_SCHEMA',
     },

package/compile/index.ts

@@ -154,11 +154,13 @@ const basicAnimationEvents = ['show', 'standby', 'breatheStart']
 
 const compileAnimations = (
   templateKey: string,
-  animations: { [key: string]: Animation },
+  animations: { [key: string]: Animation | (() => Animation) },
   errorReference: string,
 ) =>
   Object.entries(animations).reduce((acc, [key, animation]) => {
-    const animationId = assertEntryId(animation?.id, 'ANIMATION', errorReference)
+    // Animation events accept either a direct Animation or a getter; unwrap.
+    const resolved = typeof animation === 'function' ? animation() : animation
+    const animationId = assertEntryId(resolved?.id, 'ANIMATION', errorReference)
     acc[convertEventKey(basicAnimationEvents.includes(key) ? 'BRICK' : templateKey, key)] =
       `ANIMATION#${animationId}`
     return acc
@@ -1190,7 +1192,7 @@ export const compile = async (app: Application) => {
             ...compileRemoteUpdate(data.remoteUpdate),
             routing: data.routing,
             schema: data.schema,
-            type: data.type,
+            type: data.type === 'boolean' ? 'bool' : data.type,
             ...compileKind(data.kind),
             value: compileProperty(data.value, `(data: ${dataId}, subspace ${subspaceId})`),
             event_map: compileEvents('PROPERTY_BANK', data.events || {}, {
@@ -1456,5 +1458,7 @@ export const compile = async (app: Application) => {
 
 export const checkConfig = async (configPath: string) => {
   const { sh } = await import('../tools/_shell')
-  await sh`bricks app check-config ${configPath}`
+  // --validate-automation surfaces broken automation_map / test_map refs early,
+  // which catches agent-authored automations that reference deleted bricks.
+  await sh`bricks app check-config --validate-automation ${configPath}`
 }

package/package.json

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

package/package.json.bak

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

package/skills/bricks-ctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bricks-ctor
-description: Advanced BRICKS configuration knowledge. Covers Standby Transition, Automations (E2E testing), Data Calculation (JS sandbox libraries), Local Sync, Remote Data Bank, Media Flow, Buttress (remote inference), and the verification toolchain (compile/preview MCP, on-device DevTools, definition-of-done gate). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, canvas transitions, or verifying project work before declaring done.
+description: Advanced BRICKS configuration knowledge. Covers Standby Transition, Automations (E2E testing), Data Calculation (JS sandbox libraries), Local Sync, Remote Data Bank, Media Flow, Buttress (remote inference), and the verification toolchain (compile, harness-specific preview tool, on-device DevTools, definition-of-done gate). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, canvas transitions, or verifying project work before declaring done.
 ---
 
 # BRICKS Ctor - Advanced Features
@@ -20,7 +20,7 @@ This skill covers advanced BRICKS features not in the main project instructions.
 | [Remote Data Bank](rules/remote-data-bank.md) | Cloud data sync and API access |
 | [Media Flow](rules/media-flow.md) | Media asset management |
 | [Buttress](rules/buttress.md) | Remote inference for AI generators |
-| [Verification Toolchain](rules/verification-toolchain.md) | Definition of done, compile/preview MCP, on-device DevTools, Path 1/2/3 decision rule |
+| [Verification Toolchain](rules/verification-toolchain.md) | Definition of done, compile, preview tool selection, on-device DevTools, Path 1/2/3 decision rule |
 
 ## Quick Reference
 

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

@@ -26,6 +26,8 @@ The primary way to orchestrate multi-step flows. A single event can contain an a
 - Use `dataParams` + `mapping` to pass event data downstream
 - This is the "glue" that wires generators, state, and UI together
 
+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.
+
 ### System Actions (Priority 3)
 Built-in commands for direct state and UI changes.
 - **PROPERTY_BANK**: set data value
@@ -67,3 +69,13 @@ Only actual data derivation maps to Data Calculation:
 
 ### Step 4: Wire with Event Action Chains
 Connect the pieces through events on generators and bricks.
+
+## Recipe: user-driven state machine (calculator, form wizard, picker)
+
+A brief like "state vars X, Y, Z; button A updates X from X+Y; button B resets" is a state machine. The shape:
+
+- Each state variable is its own `Data` entity. Displays read it via `linkData(() => data.dFoo)`.
+- Each button's `onPress` is an Event Action Chain. For every state var that changes, append one `PROPERTY_BANK_EXPRESSION` whose `expression` reads the current state and returns the new value.
+- Use `Data Calculation` only for reusable pure derivations referenced as inputs to those expressions.
+
+A 10-button calculator with 4 state vars is ~10 small chains of 1–4 inline expressions. If you find yourself writing a single auto-mode `DataCalculationScript` that consumes all state vars and emits all-new state through mirror `dFooResult` data — or pinging a `dLastInput` field to force an auto calc to re-run — the chain shape was the right answer.

package/skills/bricks-ctor/rules/automations.md

@@ -118,6 +118,16 @@ const testLoginFlow: AutomationTest = {
 | `match_screenshot`           | `[name, threshold?, maxRetry?]`                  | Screenshot compare   |
 | `delay`                      | `[subspace?, property?, defaultValue?]`          | Delay execution      |
 
+In project TypeScript source, pass entity getters for BRICKS entities:
+
+```typescript
+run: ['brick_press', () => mainSubspace, () => bricks.bSubmitButton]
+run: ['wait_until_canvas_change', () => mainSubspace, () => canvases.cDone, 5000]
+run: ['assert_property', () => mainSubspace, () => data.dStep, 'done']
+```
+
+The compiler resolves these getters to the current generated IDs.
+
 ### execute_action Params
 
 The `params` object in `execute_action` uses **runtime event property keys** from `event-props.ts`, NOT the action config `input` names from type definitions.
@@ -208,6 +218,7 @@ Automations work with Modules. Use Manual Run in Preview mode for module testing
 
 - **Automation map key**: Always use `'AUTOMATION_MAP_DEFAULT'` as the automation map ID (not `makeId()`). The preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
 - **Valid makeId types**: Use `'test'` for AutomationTest, `'test_case'` for TestCase, `'test_var'` for TestVariable. Do NOT use `'automation_test'` or `'automation_test_map'`.
+- **Entity references in run arrays**: Use getter references (`() => subspace`, `() => bricks.bButton`, `() => data.dValue`) in TypeScript source so compile resolves fresh IDs.
 - **handler in execute_action**: Pass the entity's `.id` string (e.g., `bricks.bInput.id`), not a getter function.
 
 ## Best Practices

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

@@ -167,7 +167,7 @@ code: `
 
 ## Triggering Manually
 
-Use `PROPERTY_BANK_COMMAND` system action to trigger a manual calculation:
+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.
 
 ```typescript
 const triggerCalc: EventAction = {
@@ -176,12 +176,14 @@ const triggerCalc: EventAction = {
     __actionName: 'PROPERTY_BANK_COMMAND',
     parent: 'System',
     dataParams: [
-      { input: () => computeTotalCalc }, // Reference to DataCalculation
+      { input: () => priceData }, // Reference to a trigger Data input of the calc
     ],
   },
 }
 ```
 
+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).
+
 ## Best Practices
 
 1. **Avoid circular deps**: Set non-triggering inputs (`trigger: false`) or use `manual` mode
@@ -194,9 +196,7 @@ const triggerCalc: EventAction = {
 See [Architecture Patterns](architecture-patterns.md) for the full pattern selection guide.
 
 ### Using Data Calc as an orchestrator
-Scripts that manage state machines, control UI flow, or coordinate multi-step processes belong in Event Action Chains, not here.
-
-**Symptom**: Script has if/else branches deciding "what happens next" or tracks "current step".
+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
 

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

@@ -7,7 +7,7 @@ Three runtime targets, one decision rule. Verify against the cheapest path that
 Before the agent is allowed to claim work is complete, **all** of the following must be true:
 
 1. **Compile clean.** Latest source passes `compile` with no errors.
-2. **Every Canvas screenshot captured.** A rendered screenshot of every Canvas in the deliverable, captured via `preview` MCP (`responseImage: true`) at the target hardware resolution and orientation. Canvases gated behind events are reached via Automation runs (`testId` / `testTitleLike` with `brick_press` / `wait_until_canvas_change` cases). Single-Canvas Subspaces still require a captured screenshot.
+2. **Every Canvas screenshot captured.** A rendered screenshot of every Canvas in the deliverable, captured via the available preview tool (`responseImage: true` when the selected model supports vision) at the target hardware resolution and orientation. Canvases gated behind events are reached via Automation runs (`testId` / `testTitleLike` with `brick_press` / `wait_until_canvas_change` cases). Single-Canvas Subspaces still require a captured screenshot.
 3. **Every screenshot reviewed by the agent.** The agent must read each captured screenshot back through the host's image-reading capability — saving the file is not the same as seeing it. The model that produced the Canvas must also have seen the rendered result, or the verification gate has not passed.
 4. **Reference comparison report.** If the user supplied any reference material (Figma / website / HTML / screenshot / PDF / brand book / competitor), produce a short delta report per Canvas:
    - What matches the reference.
@@ -30,23 +30,30 @@ If any item is unmet, the work is mid-iteration. Say so explicitly to the user;
 
 The default loop. Always available; deterministic; no device wear; safe for side-effecting flows because nothing real fires.
 
-### `bricks-ctor` MCP — `compile`
+`bun update-app` and `bun deploy-app` publish to the BRICKS portal. The local preview reads `.bricks/build/application-config.json` (produced by `compile`) directly.
+
+### Compile tool
 
 Typecheck + compile the project. Gate every iteration on this; everything below assumes a clean compile.
 
 Agent invocation: call the MCP tool `compile` exposed by the `bricks-ctor` MCP server registered for the project. No arguments.
 
-### `bricks-ctor` MCP — `preview`
+### Preview tool
+
+Use the preview implementation exposed by the current harness:
+
+- **CTOR Desktop agent session:** use `preview_invoke`. CTOR Desktop disables the `bricks-ctor` MCP `preview` tool and routes screenshots/automation through the desktop preview pane instead. If the user already opened the simulator pane, `preview_invoke` should reuse it rather than start a separate preview.
+- **Pure `bricks-ctor` project / other agent harness:** use the `bricks-ctor` MCP `preview` tool when `preview_invoke` is not available.
 
-Launches headless Electron, takes a screenshot, optionally runs a named Automation test by id or partial title.
+Both forms are the same verification primitive: launch or reuse Electron preview, take a screenshot, and optionally run a named Automation test by id or partial title. Do not hard-code one tool name into the workflow; choose the available preview tool for the environment.
 
-Arguments:
-- `delay` (ms before screenshot) — default 3000. Increase if Standby Transitions are still in flight.
+Common arguments:
+- `delay` (ms before screenshot) — default is harness-specific: usually 3000 for a fresh/standalone preview; CTOR Desktop may capture immediately when its preview already has a settled latest config. Increase if Standby Transitions are still in flight.
 - `width`, `height` — screenshot dimensions in px.
-- `responseImage: true` — return base64 jpeg as MCP image content (recommended for visual sanity).
+- `responseImage: true` — return the screenshot as image content when the selected model supports vision. If vision is unavailable, save the screenshot and report the path.
 - `testId` or `testTitleLike` — run a project Automation before the screenshot. Use `testTitleLike` for fuzzy matches (case-insensitive partial title).
 
-Returns text log + (if `responseImage`) base64 image content.
+Returns text log + saved screenshot path + image content when supported.
 
 ### `bun preview` (project script)
 
@@ -76,7 +83,7 @@ Trigger types: `launch` (runs on app start), `anytime` (manual), `cron` (schedul
 
 Important: the automation map id must be `'AUTOMATION_MAP_DEFAULT'` (not a generated id) — the preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
 
-Run a single test from the agent: `bricks-ctor` MCP `preview` with `testId` or `testTitleLike`.
+Run a single test from the agent: call the available preview tool (`preview_invoke` in CTOR Desktop, otherwise `bricks-ctor` MCP `preview`) with `testId` or `testTitleLike`.
 
 ## Path 2 — Real device with DevTools enabled
 

package/skills/bricks-design/SKILL.md

@@ -23,7 +23,7 @@ description: >-
   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 MCP, on-device DevTools,
+  Verification toolchain (compile, preview tool selection, on-device DevTools,
   Path 1/2/3) lives in the bricks-ctor skill.
 ---
 
@@ -84,7 +84,7 @@ The load-bearing laws. Each is unpacked in [`references/architecture-truths.md`]
 6. **Frames are grid units.** Off-grid placement is legal but only ever intentional (overflow effects, anchor-at-origin tricks). It is never a nudge to escape the grid. Bricks fully outside the grid are auto-culled.
 7. **Standby Transition is part of the design language.** Every visible Brick gets an entrance offset (`standbyMode` + `standbyOpacity` + `standbyDelay`); the runtime's auto-tween handles in-flight motion. Snap-cuts are reserved for emphasis (alarm states), never for routine navigation.
 8. **Subspace is a typed module.** Inputs are call-by-value-on-host-change; outlets emit update + value-change events on the host. Extract a Subspace only when the same flow appears 2+ times or when the boundary scopes Data meaningfully — never as a "tidy up" tactic.
-9. **DataCalculation is for derivation only.** Pure inputs → outputs (DataCalculationScript or DataCalculationMap). If your transformation has side effects, navigation, or async I/O, it belongs in an Event Action chain or a Generator. DataCalc orchestrating DataCalc is the wrong primitive.
+9. **DataCalculation is for derivation, not orchestration.** Inputs → outputs via DataCalculationScript or DataCalculationMap. Keep scripts pure by default; `enableAsync: true` (Promise / timers / async libs) and Map `FILE_*` commands are available when derivation genuinely needs them. Network calls, navigation, and DataCalc-triggers-DataCalc fanout belong in Event Action chains or Generators.
 10. **No scroll, no overflow, no responsive reflow.** Frames are fixed; what doesn't fit doesn't show. Design within the Canvas; don't import web habits.
 
 ## Commit to a design language

package/skills/bricks-design/references/architecture-truths.md

@@ -96,19 +96,26 @@ A Subspace is a self-contained mini-Application: own Canvases, own Bricks, own G
 
 **Failure mode:** Subspaces with leaky contracts (every host Data exposed as a Prop). Tighten the contract; if you can't, the boundary is wrong.
 
-## 9. DataCalculation is for derivation only
+## 9. DataCalculation is for derivation, not orchestration
 
-Two flavours: `DataCalculationScript` (a JS function with named inputs / outputs) and `DataCalculationMap` (a node-graph of `DataCommand`s with sandbox primitives — string, math, collection, datetime, color, etc.). Both are pure transformations: inputs → outputs.
+Two flavours:
+
+- **`DataCalculationScript`** — a sandboxed JS function with named inputs / outputs. Default is sync + pure; opt into async with `enableAsync: true`, which unlocks `Promise`, `setTimeout` / `setInterval` / `setImmediate`, `requestAnimationFrame`, and the full lodash surface (`debounce`, `delay`, `defer`). Bundled libraries include lodash, voca, mathjs, chroma, moment, json5, qs, url, bytes, ms, base45, iconv, nanoid, md5, crypto-browserify, jsrsasign (JWS), cose-js, fflate (gzip/zlib), cbor, fs (limited; no download/upload), officeparser, turndown, opencc-js, toon-format. Runs on Hermes (Android) and JavaScriptCore (iOS) — keep that in mind for engine pitfalls.
+- **`DataCalculationMap`** — a node-graph of `DataCommand`s spanning these categories: `COLLECTION`, `COLOR`, `CONSTANT`, `DATETIME`, `FILE` (file-system ops: `READ` / `WRITE` / `APPEND` / `MKDIR` / `COPY_FILE` / `MOVE_FILE` / `UNLINK` / `EXISTS` / `STAT` / etc.), `ITERATEE`, `LOGICTYPE`, `MATH`, `OBJECT`, `SANDBOX` (`SANDBOX_RUN_JAVASCRIPT` runs a script node inside the graph), `STRING`.
+
+Derivation is the intent. Purity is a strong default and the right framing for the common case, but it is a best practice — not a hard runtime restriction. `enableAsync` and `FILE_*` exist because some derivation work (document parsing, decompression, signing, reading a cached file) genuinely needs them.
 
 **Use it for**:
 - Format conversion (date → human-readable, currency → localized string).
 - Combining Data values into a derived display value.
 - Reductions / iterations over a collection.
 - Boolean conditions feeding a Switch.
+- Async derivation pipelines: decode → decompress → parse → verify (cbor, fflate, cose-js, officeparser, turndown).
+- Reading cached files written earlier in the flow (Map `FILE_*` commands or Script `fs`).
 
 **Triggering**: `triggerMode: 'auto'` re-runs on input change (watch for circular dependencies); `'manual'` only runs on `PROPERTY_BANK_COMMAND` action.
 
-**Do not use** for orchestration, side effects, navigation, async I/O, network calls, or anything that should be in an Event Action chain or a Generator. A DataCalc that triggers DataCalc that triggers DataCalc is an orchestration system in the wrong primitive — promote to event chains.
+**Do not use** for orchestration, navigation, network calls (no `fetch` / XHR in the sandbox — that's a Generator's job), or anything that should be in an Event Action chain or a Generator. A DataCalc that triggers DataCalc that triggers DataCalc is an orchestration system in the wrong primitive — promote to event chains. `enableAsync` and `FILE_*` are tools for derivation, not a licence to smuggle flow control into the calc layer.
 
 **Failure mode:** spinning up a Generator just to do a string concat or unit conversion. That's a DataCalc job; the inverse misuse is just as common.
 

package/skills/bricks-design/references/variations-and-tweaks.md

@@ -57,7 +57,7 @@ Use when variations share most of the Brick tree but differ on a chunk that can'
 - Each variant Subspace imports the shared module and overrides only the variant-specific chunk.
 - Bricks reused by reference, not duplicated.
 
-**Comparison surface:** screenshot per variant via preview MCP, assembled in chat.
+**Comparison surface:** screenshot per variant via the available preview tool, assembled in chat.
 
 **Token cost:** 1 shared module + N small variant Subspaces.
 

package/tools/_shell.ts

@@ -29,6 +29,7 @@ class Sh implements PromiseLike<ShResult> {
   private _cwd: string | undefined
   private _mode: Mode = 'default'
   private _throw = true
+  private _env: NodeJS.ProcessEnv | undefined
   private _promise: Promise<ShResult> | null = null
 
   constructor(private readonly args: string[]) {}
@@ -48,6 +49,11 @@ class Sh implements PromiseLike<ShResult> {
     return this
   }
 
+  env(extra: NodeJS.ProcessEnv): this {
+    this._env = { ...this._env, ...extra }
+    return this
+  }
+
   async text(): Promise<string> {
     // If no explicit quiet was requested, capture stdout/stderr without
     // forwarding them to the parent's streams (matches Bun's `.text()`).
@@ -79,7 +85,8 @@ class Sh implements PromiseLike<ShResult> {
           ? ['ignore', 'pipe', 'pipe']
           : ['inherit', 'pipe', 'pipe']
 
-    const proc = spawn(cmd, rest, { cwd: this._cwd, stdio })
+    const env = this._env ? { ...process.env, ...this._env } : undefined
+    const proc = spawn(cmd, rest, { cwd: this._cwd, stdio, env })
 
     const outChunks: Buffer[] = []
     const errChunks: Buffer[] = []

package/tools/mcp-tools/compile.ts

@@ -3,22 +3,29 @@ import { readFile } from 'node:fs/promises'
 import { z } from 'zod'
 import { sh } from '../_shell'
 
+// Disable ANSI color codes from spawned tools so MCP text output stays readable
+// (the host renders raw text; escape sequences leak into the result otherwise).
+const noColorEnv = { FORCE_COLOR: '0', NO_COLOR: '1' }
+
 export function register(server: McpServer, projectDir: string) {
   const { dirname } = import.meta
 
   server.tool('compile', {}, async () => {
-    let log = ''
+    let log = 'Type checking & Compiling...\n'
     try {
-      log += 'Type checking & Compiling...'
-      log += await sh`bun compile`.cwd(projectDir).text()
-    } catch (err) {
-      log += `${err.stdout.toString()}\n${err.stderr.toString()}`
+      log += await sh`bun compile`.cwd(projectDir).env(noColorEnv).text()
+    } catch (err: any) {
+      const stdout = err.stdout?.toString() ?? ''
+      const stderr = err.stderr?.toString() ?? ''
+      log += [stdout, stderr].filter(Boolean).join('\n')
     }
     return {
       content: [{ type: 'text', text: log }],
     }
   })
 
+  if (process.env.BRICKS_CTOR_MCP_DISABLE_PREVIEW === '1') return
+
   server.tool(
     'preview',
     {
@@ -63,9 +70,12 @@ export function register(server: McpServer, projectDir: string) {
         if (testTitleLike) args.push('--test-title-like', testTitleLike)
         log = await sh`bunx --bun electron ${toolsDir}/preview-main.mjs ${args}`
           .cwd(projectDir)
+          .env(noColorEnv)
           .text()
-      } catch (err) {
-        log = `${err.stdout.toString()}\n${err.stderr.toString()}`
+      } catch (err: any) {
+        const stdout = err.stdout?.toString() ?? ''
+        const stderr = err.stderr?.toString() ?? ''
+        log = [stdout, stderr].filter(Boolean).join('\n')
         error = true
       }
       let screenshotBase64: string | null = null

package/tools/mcp-tools/media.ts

@@ -2,9 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import { sh } from '../_shell'
 
+// MCP results are rendered as raw text — disable ANSI colors from the child.
+const noColorEnv = { FORCE_COLOR: '0', NO_COLOR: '1' }
+
 const runBricks = async (projectDir: string, ...args: string[]) => {
   try {
-    return await sh`bunx bricks ${args}`.cwd(projectDir).text()
+    return await sh`bunx bricks ${args}`.cwd(projectDir).env(noColorEnv).text()
   } catch (err: any) {
     throw new Error(err.stderr?.toString() || err.message)
   }

package/types/animation.ts

@@ -104,8 +104,13 @@ export interface AnimationComposeDef {
 
 export type Animation = AnimationDef | AnimationComposeDef
 
+// Animation event handlers accept either a direct Animation or a getter that
+// returns one. The getter form is useful for lazy/forward references between
+// animations defined across files.
+export type AnimationOrGetter = Animation | (() => Animation)
+
 export interface AnimationBasicEvents {
-  showStart?: Animation
-  standby?: Animation
-  breatheStart?: Animation
+  showStart?: AnimationOrGetter
+  standby?: AnimationOrGetter
+  breatheStart?: AnimationOrGetter
 }

package/types/brick-base.ts

@@ -1,7 +1,7 @@
 /* Auto generated by build script */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from './switch'
 import type { Data, DataLink } from './data'
-import type { Animation, AnimationBasicEvents } from './animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from './animation'
 import type {
   Brick,
   EventAction,

package/types/bricks/Camera.ts

@@ -4,7 +4,7 @@
  */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
 import type { Data, DataLink } from '../data'
-import type { Animation, AnimationBasicEvents } from '../animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from '../animation'
 import type {
   Brick,
   EventAction,
@@ -213,13 +213,13 @@ Default property:
     faceDetected?: () => Data<Array<{ [key: string]: any }>>
   }
   animation?: AnimationBasicEvents & {
-    stateChange?: Animation
-    recordStart?: Animation
-    recordEnd?: Animation
-    barcodeRead?: Animation
-    pictureTaken?: Animation
-    recordFinish?: Animation
-    mountError?: Animation
+    stateChange?: AnimationOrGetter
+    recordStart?: AnimationOrGetter
+    recordEnd?: AnimationOrGetter
+    barcodeRead?: AnimationOrGetter
+    pictureTaken?: AnimationOrGetter
+    recordFinish?: AnimationOrGetter
+    mountError?: AnimationOrGetter
   }
 }
 

package/types/bricks/Chart.ts

@@ -4,7 +4,7 @@
  */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
 import type { Data, DataLink } from '../data'
-import type { Animation, AnimationBasicEvents } from '../animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from '../animation'
 import type {
   Brick,
   EventAction,
@@ -343,9 +343,9 @@ Default property:
     >
   }
   animation?: AnimationBasicEvents & {
-    onRender?: Animation
-    onPress?: Animation
-    onLegendSelectChanged?: Animation
+    onRender?: AnimationOrGetter
+    onPress?: AnimationOrGetter
+    onLegendSelectChanged?: AnimationOrGetter
   }
 }
 

package/types/bricks/GenerativeMedia.ts

@@ -4,7 +4,7 @@
  */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
 import type { Data, DataLink } from '../data'
-import type { Animation, AnimationBasicEvents } from '../animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from '../animation'
 import type {
   Brick,
   EventAction,
@@ -250,20 +250,20 @@ Default property:
     loading?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
-    generativeMediaOnPress?: Animation
-    generativeMediaOnPressIn?: Animation
-    generativeMediaOnPressOut?: Animation
-    generativeMediaOnLongPress?: Animation
-    generativeMediaOnFocus?: Animation
-    generativeMediaOnBlur?: Animation
-    onSuccess?: Animation
-    onError?: Animation
-    promptStart?: Animation
-    promptSuccess?: Animation
-    promptError?: Animation
-    loadStart?: Animation
-    loadSuccess?: Animation
-    loadError?: Animation
+    generativeMediaOnPress?: AnimationOrGetter
+    generativeMediaOnPressIn?: AnimationOrGetter
+    generativeMediaOnPressOut?: AnimationOrGetter
+    generativeMediaOnLongPress?: AnimationOrGetter
+    generativeMediaOnFocus?: AnimationOrGetter
+    generativeMediaOnBlur?: AnimationOrGetter
+    onSuccess?: AnimationOrGetter
+    onError?: AnimationOrGetter
+    promptStart?: AnimationOrGetter
+    promptSuccess?: AnimationOrGetter
+    promptError?: AnimationOrGetter
+    loadStart?: AnimationOrGetter
+    loadSuccess?: AnimationOrGetter
+    loadError?: AnimationOrGetter
   }
 }
 

package/types/bricks/Icon.ts

@@ -4,7 +4,7 @@
  */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
 import type { Data, DataLink } from '../data'
-import type { Animation, AnimationBasicEvents } from '../animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from '../animation'
 import type {
   Brick,
   EventAction,
@@ -66,12 +66,12 @@ Default property:
     brickFocusing?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
-    onPress?: Animation
-    onPressIn?: Animation
-    onPressOut?: Animation
-    onLongPress?: Animation
-    onFocus?: Animation
-    onBlur?: Animation
+    onPress?: AnimationOrGetter
+    onPressIn?: AnimationOrGetter
+    onPressOut?: AnimationOrGetter
+    onLongPress?: AnimationOrGetter
+    onFocus?: AnimationOrGetter
+    onBlur?: AnimationOrGetter
   }
 }
 

package/types/bricks/Image.ts

@@ -4,7 +4,7 @@
  */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
 import type { Data, DataLink } from '../data'
-import type { Animation, AnimationBasicEvents } from '../animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from '../animation'
 import type {
   Brick,
   EventAction,
@@ -92,14 +92,14 @@ Default property:
     brickFocusing?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
-    onPress?: Animation
-    onPressIn?: Animation
-    onPressOut?: Animation
-    onLongPress?: Animation
-    onFocus?: Animation
-    onBlur?: Animation
-    onLoad?: Animation
-    onError?: Animation
+    onPress?: AnimationOrGetter
+    onPressIn?: AnimationOrGetter
+    onPressOut?: AnimationOrGetter
+    onLongPress?: AnimationOrGetter
+    onFocus?: AnimationOrGetter
+    onBlur?: AnimationOrGetter
+    onLoad?: AnimationOrGetter
+    onError?: AnimationOrGetter
   }
 }
 

package/types/bricks/Items.ts

@@ -4,7 +4,7 @@
  */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
 import type { Data, DataLink } from '../data'
-import type { Animation, AnimationBasicEvents } from '../animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from '../animation'
 import type {
   Brick,
   EventAction,
@@ -438,12 +438,12 @@ Default property:
     pageIsOutOfBound?: () => Data<boolean>
   }
   animation?: AnimationBasicEvents & {
-    onPageRender?: Animation
-    onPageChange?: Animation
-    onPageOutOfBound?: Animation
-    onIntoDetailMode?: Animation
-    onIntoListMode?: Animation
-    onError?: Animation
+    onPageRender?: AnimationOrGetter
+    onPageChange?: AnimationOrGetter
+    onPageOutOfBound?: AnimationOrGetter
+    onIntoDetailMode?: AnimationOrGetter
+    onIntoListMode?: AnimationOrGetter
+    onError?: AnimationOrGetter
   }
 }