@fugood/bricks-project 2.25.0-beta.21 → 2.25.0-beta.23

package/compile/index.ts

@@ -1194,7 +1194,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 || {}, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fugood/bricks-project",
-  "version": "2.25.0-beta.21",
+  "version": "2.25.0-beta.23",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",

package/package.json.bak

@@ -1,6 +1,6 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.21",
+  "version": "2.25.0-beta.23",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",

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

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,16 +3,21 @@ 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 }],
@@ -65,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/common.ts

@@ -12,7 +12,7 @@ export interface Brick {
   description?: string
   hideShortRef?: boolean
   property?: {}
-  events: {}
+  events?: {}
   outlets?: {}
   animation?: {}
   switches?: Array<SwitchDef>
@@ -33,7 +33,7 @@ export interface Generator {
   hideShortRef?: boolean
   localSyncRunMode?: LocalSyncStrategy
   property?: {}
-  events: {}
+  events?: {}
   outlets?: {}
   switches?: Array<SwitchDef>
 }

package/types/data-calc-command/base.ts

@@ -0,0 +1,57 @@
+/* Auto generated by build script */
+import type { Data } from '../data'
+import type { DataCalculation } from '../data-calc'
+
+// Shared helpers — every generated DataCommand{Name} reuses these to describe
+// its narrowed inputs/outputs, so the per-command files stay short.
+export type DataCalcInput<K extends string = string, T = any> = {
+  key: K
+  source: (() => DataCalculationData | DataCommand) | T
+  sourceKey: string
+  trigger?: boolean
+}
+
+export type DataCalcOutput<K extends string = string> = {
+  key: K
+  target: () => DataCalculationData | DataCommand
+  targetKey: string
+}
+
+export interface DataCalculationData {
+  __typename: 'DataCalculationData'
+  title?: string
+  description?: string
+  hideShortRef?: boolean
+  data: () => Data
+  // 'change' is the only valid input port on a data node; the source must be
+  // another node (no inline literals), hence `never` for the second type arg.
+  inputs: Array<DataCalcInput<'change', never>>
+  outputs: Array<DataCalcOutput<'value'>>
+}
+
+export interface DataCommand {
+  __typename: 'DataCommand'
+  __commandName: string
+  id: string
+  title?: string
+  description?: string
+  hideShortRef?: boolean
+  inputs: Array<DataCalcInput>
+  outputs: Array<DataCalcOutput>
+}
+
+export type DataCalculationMap = DataCalculation & {
+  __typename: 'DataCalculationMap'
+  nodes: Array<DataCalculationData | DataCommand>
+  editorInfo: Array<{
+    node: DataCalculationData | DataCommand
+    position: { x: number; y: number }
+    points: Array<{
+      source: DataCalculationData | DataCommand
+      sourceOutputKey: string
+      target: DataCalculationData | DataCommand
+      targetInputKey: string
+      positions: Array<{ x: number; y: number }>
+    }>
+  }>
+}