@fugood/bricks-project 2.24.3 → 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
@@ -641,6 +643,7 @@ const compileAutomationTest = (
 
   return {
     id: testId,
+    alias: test.alias,
     title: test.title,
     hide_short_ref: test.hideShortRef,
     timeout: test.timeout,
@@ -1189,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 || {}, {
@@ -1209,6 +1212,7 @@ export const compile = async (app: Application) => {
           )
 
           const calc: any = {
+            alias: dataCalc.alias,
             title: dataCalc.title,
             description: dataCalc.description,
             hide_short_ref: dataCalc.hideShortRef,
@@ -1454,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.3",
+  "version": "2.24.5",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.3",
+    "@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.3",
+  "version": "2.24.5",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.3",
+    "@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, and Buttress (remote inference). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, or canvas transitions.
+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,6 +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 tool selection, on-device DevTools, Path 1/2/3 decision rule |
 
 ## Quick Reference
 
@@ -30,3 +31,4 @@ This skill covers advanced BRICKS features not in the main project instructions.
 - **AI offloading**: See [Buttress](rules/buttress.md) for GPU server delegation
 - **E2E testing**: See [Automations](rules/automations.md) for test automation
 - **Enter animations**: See [Standby Transition](rules/standby-transition.md) for canvas transitions
+- **Verification before done**: See [Verification Toolchain](rules/verification-toolchain.md) for the definition-of-done gate and Path 1/2/3 decision rule

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

@@ -0,0 +1,177 @@
+# Verification Toolchain
+
+Three runtime targets, one decision rule. Verify against the cheapest path that proves what you need to prove.
+
+## Definition of done — the hard gate
+
+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 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.
+   - What intentionally diverges, and why (deployment constraint, BRICKS-runtime semantic, system commitment).
+   - What unintentionally diverges, and the planned fix.
+5. **Path appropriate to deployment executed.** Path 1 by default. Path 2 (on-device) when the deployment depends on real hardware behaviour, or whenever the brief touches payment, identity, peripherals, or LocalSync.
+6. **Console clean.** No 404s on media, no Data-key-undefined warnings, no Generator init failures, no React-style warnings — every console line is either zero or accept-with-a-comment.
+
+What does **not** count as done:
+
+- A single hero-Canvas screenshot.
+- "Looks roughly like the reference" with no per-Canvas comparison.
+- "Compiled successfully" with no rendered preview.
+- A claim of done with no screenshots in evidence.
+- Captured screenshots saved to disk but never read back by the agent.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.
+
+## Path 1 — Electron preview (no device required)
+
+The default loop. Always available; deterministic; no device wear; safe for side-effecting flows because nothing real fires.
+
+`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.
+
+### 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.
+
+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.
+
+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 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 + saved screenshot path + image content when supported.
+
+### `bun preview` (project script)
+
+Sustained dev session — watches `subspaces/`, recompiles on save, exposes CDP at `localhost:19852` (configurable via `--cdp-port`), writes `.bricks/devtools.json` with port/pid for downstream tooling.
+
+Useful flags:
+- `--screenshot` + `--screenshot-delay/width/height/path` — drive screenshot capture without keeping the window open.
+- `--show-menu` — surface the Electron menu (debugging).
+- `--test-id` / `--test-title-like` — run an Automation in this preview.
+- `--no-keep-open` — exit after one screenshot.
+- `--no-cdp` — disable CDP server (rare; default is to expose it).
+- `--clear-cache` — reset cached state between runs.
+
+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.
+
+### Project Automations
+
+E2E tests authored in TypeScript inside the project (`AutomationTest` / `TestCase`). Test cases include:
+
+- `brick_press` — synthesize a press on a Brick.
+- `wait_until_canvas_change` — assert navigation.
+- `assert_property` — assert a Data value equals expected.
+- `wait_property_update` — wait for a Data value to change.
+- `match_screenshot` — visual regression with stored reference image.
+
+Trigger types: `launch` (runs on app start), `anytime` (manual), `cron` (scheduled).
+
+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: 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
+
+Required when the deployment depends on hardware behaviour the Electron preview cannot reproduce: physical orientation/DPI, real touch hardware (IR overlays, multi-touch), peripherals (camera, BLE, MQTT, NFC, payment, printer, sensors), watchdog cycles on the actual launcher build, fleet-managed reboot semantics, LocalSync across multiple devices, the actual color/luminance of the panel.
+
+**Always Path 2** when the brief touches: payment, identity capture, real-time peripheral data, multi-device LocalSync, certified hardware.
+
+### One-time manual setup (the agent cannot do this)
+
+Ask the user to:
+
+1. On the device, open **Settings** → advanced settings.
+2. Toggle **Chrome DevTools** on. The device starts a DevTools server on the local network on port `19851` (auto-increments if taken).
+3. Confirm **Enable LAN Discovery** is on (default) so the device is discoverable.
+4. Note the device passcode if displayed.
+
+Requires BRICKS Foundation **≥ 2.24** for CDP commands.
+
+### Endpoints exposed once enabled
+
+| Endpoint | URL shape | Use |
+|---|---|---|
+| Web UI | `http://<ip>:19851` | DevTools landing in a browser |
+| CDP | `http://<ip>:19851/devtools-frontend/inspector.html?ws=<ip>:19851/ws/<passcode>` | Chrome DevTools front-end |
+| MCP | `http://<ip>:19851/mcp` | MCP endpoint (Bearer-token auth with passcode) |
+| MCP SSE | `http://<ip>:19851/sse` | Same, SSE transport |
+| Info | `http://<ip>:19851/devtools/info` | Device / server metadata |
+
+### Driving the device
+
+Once DevTools is on, ask the user how they want to drive the verification — Chrome DevTools front-end, an MCP client they already run, or screenshot export from their own tooling — and follow their lead. Capture every Canvas screenshot through whichever path the user picks; the verification gate is about the evidence, not the tool.
+
+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.
+
+### 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.
+
+## Path 3 — Remote debugging via BRICKS Controller (off-LAN)
+
+Out of scope for the standard verification loop. It exists for ops scenarios where the device is not on the same network. If the user asks for it, point them at the BRICKS Controller documentation rather than attempting it as part of verification.
+
+## Decision rule
+
+```
+default Path 1.
+
+if deployment depends on:
+   physical orientation / DPI / touch HW / peripherals /
+   watchdog on real launcher / LocalSync / certified hardware
+→ escalate to Path 2 before declaring done.
+
+if brief touches payment, identity, peripherals, LocalSync
+→ Path 2 is mandatory, not optional.
+
+if user is off-LAN
+→ Path 3 (out of scope here).
+```
+
+## What to actually verify (per shape)
+
+### Static signage (single-canvas glance loop)
+- Path 1 screenshot captures the loop frame.
+- Watch one full rotation in `bun preview` to see all queue items.
+- Cut network mid-loop; confirm cached media plays.
+- Path 2 only if the panel is OLED / has burn-in concerns or specific color profile.
+
+### Multi-canvas state machine (kiosk)
+- Path 1: Automation walking the happy path with `brick_press` + `wait_until_canvas_change` + `assert_property` + `match_screenshot` per Canvas.
+- Cancel + inactivity reset paths verified as Automations.
+- Watchdog reset: kill the runtime, restart, confirm boot Canvas resets transient flow Data.
+- Path 2 mandatory if payment / identity is in the flow — fire a real test transaction on staging hardware.
+
+### Subspace-driven composition
+- Path 1: open the Subspace standalone if the preview supports it; verify in isolation.
+- Embedded test: walk the host's flow; assert Outlets fire as expected via `wait_property_update`.
+- Re-mount test: cause the host to re-bind the Subspace; confirm internal state resets.
+
+### Generator-driven reactive
+- Path 1: drive the source by writing to Data from the runtime (whatever CDP path the user prefers); observe Brick re-render.
+- Throttle / firehose tests: write 100 updates rapidly; confirm the canvas doesn't choke (frame budget intact).
+- Disconnect: simulate source disconnect; confirm UI surfaces stale state, not blank.
+- Threshold transitions: cross every Switch boundary; confirm visual reaction.
+- Path 2 mandatory if the source is a real peripheral — Electron cannot fake the timing or the failure modes.
+
+### Multi-device LocalSync
+- Path 2 mandatory. Two devices on the same LAN with DevTools on. Drive one, observe the other.
+
+## Browser / runtime log discipline
+
+Throughout: the DevTools console must be clean. 404s on media, "Data key not defined" warnings, Generator init failures, React-style warnings — every one is a defect or accept-with-comment. Don't ship around them.