@fugood/bricks-project 2.24.2 → 2.24.4

package/compile/index.ts

@@ -301,6 +301,162 @@ const animationTypeMap = {
   AnimationTimingConfig: 'timing',
   AnimationSpringConfig: 'spring',
   AnimationDecayConfig: 'decay',
+} as const
+
+type CompiledAnimationType = (typeof animationTypeMap)[keyof typeof animationTypeMap]
+type WarningMetadata = Record<string, unknown>
+
+const animationProperties = new Set([
+  'transform.translateX',
+  'transform.translateY',
+  'transform.scale',
+  'transform.scaleX',
+  'transform.scaleY',
+  'transform.rotate',
+  'transform.rotateX',
+  'transform.rotateY',
+  'opacity',
+])
+
+const animationComposeTypes = new Set(['parallel', 'sequence'])
+const springConfigFamilies = [
+  ['stiffness', 'damping', 'mass'],
+  ['tension', 'friction'],
+  ['bounciness', 'speed'],
+]
+const springConfigFamilyKeys = new Set(springConfigFamilies.flat())
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+const hasDefinedConfigValue = (config: Record<string, unknown>, key: string) =>
+  config[key] !== undefined
+
+const assertConfigValue = (
+  config: Record<string, unknown>,
+  key: string,
+  errorReference: string,
+) => {
+  if (!hasDefinedConfigValue(config, key)) {
+    throw new Error(`Invalid animation config ${errorReference}: missing "${key}"`)
+  }
+}
+
+const assertAnimationProperty = (property: unknown, errorReference: string) => {
+  if (typeof property !== 'string' || !animationProperties.has(property)) {
+    throw new Error(
+      `Invalid animation property${errorReference ? ` ${errorReference}` : ''}: ${String(
+        property,
+      )}`,
+    )
+  }
+  return property
+}
+
+const getAnimationType = (config: unknown, errorReference: string): CompiledAnimationType => {
+  if (!isRecord(config)) {
+    throw new Error(`Invalid animation config ${errorReference}: config must be an object`)
+  }
+
+  const animationType = animationTypeMap[config.__type as keyof typeof animationTypeMap]
+  if (!animationType) {
+    throw new Error(`Invalid animation config type ${errorReference}: ${String(config.__type)}`)
+  }
+  return animationType
+}
+
+const assertAnimationComposeType = (composeType: unknown, errorReference: string) => {
+  if (typeof composeType !== 'string' || !animationComposeTypes.has(composeType)) {
+    throw new Error(`Invalid animation compose type ${errorReference}: ${String(composeType)}`)
+  }
+  return composeType
+}
+
+const pickDefinedConfigValues = (config: Record<string, unknown>, keys: string[]) =>
+  keys.reduce((acc, key) => {
+    if (hasDefinedConfigValue(config, key)) acc[key] = config[key]
+    return acc
+  }, {})
+
+const getDefinedConfigKeys = (config: Record<string, unknown>, keys: string[]) =>
+  keys.filter((key) => hasDefinedConfigValue(config, key))
+
+const formatWarningMetadata = (metadata: WarningMetadata = {}) =>
+  Object.entries(metadata)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${key}: ${String(value)}`)
+    .join(', ')
+
+const formatWarningReference = (metadata?: WarningMetadata) => {
+  const metadataText = formatWarningMetadata(metadata)
+  return metadataText ? ` [${metadataText}]` : ''
+}
+
+const normalizeSpringConfig = (
+  config: Record<string, unknown>,
+  errorReference: string,
+  warningMetadata?: WarningMetadata,
+): Record<string, unknown> => {
+  assertConfigValue(config, 'toValue', errorReference)
+
+  const usedFamilies = springConfigFamilies.filter((keys) =>
+    keys.some((key) => hasDefinedConfigValue(config, key)),
+  )
+  if (usedFamilies.length <= 1) return config
+
+  const configWithoutSpringFamily = Object.entries(config).reduce((acc, [key, value]) => {
+    if (!springConfigFamilyKeys.has(key)) acc[key] = value
+    return acc
+  }, {})
+
+  // Match runtime normalization: physical spring values are most explicit,
+  // otherwise preserve BRICKS' historical tension/friction controls.
+  const resolvedFamily =
+    usedFamilies.find((keys) => keys.includes('stiffness')) ||
+    usedFamilies.find((keys) => keys.includes('tension')) ||
+    usedFamilies[0]
+  const resolvedFamilyKeys = getDefinedConfigKeys(config, resolvedFamily)
+  const droppedFamilyKeys = usedFamilies
+    .filter((keys) => keys !== resolvedFamily)
+    .flatMap((keys) => getDefinedConfigKeys(config, keys))
+
+  console.warn(
+    `[Warning] Resolved animation spring config${formatWarningReference(
+      warningMetadata,
+    )}: using ${resolvedFamilyKeys.join('/')}, dropping ${droppedFamilyKeys.join('/')}`,
+  )
+
+  return {
+    ...configWithoutSpringFamily,
+    ...pickDefinedConfigValues(config, resolvedFamily),
+  }
+}
+
+const compileAnimationConfig = (
+  animationType: CompiledAnimationType,
+  config: unknown,
+  errorReference: string,
+  warningMetadata?: WarningMetadata,
+) => {
+  if (!isRecord(config)) {
+    throw new Error(`Invalid animation config ${errorReference}: config must be an object`)
+  }
+
+  const compiledConfig = compileProperty(omit(config, '__type'), errorReference)
+
+  if (!isRecord(compiledConfig)) {
+    throw new Error(`Invalid animation config ${errorReference}: config must compile to an object`)
+  }
+
+  if (animationType === 'timing') {
+    assertConfigValue(compiledConfig, 'toValue', errorReference)
+  } else if (animationType === 'spring') {
+    return normalizeSpringConfig(compiledConfig, errorReference, warningMetadata)
+  } else if (animationType === 'decay') {
+    assertConfigValue(compiledConfig, 'velocity', errorReference)
+  }
+
+  return compiledConfig
 }
 
 const compileFrame = (frame: Canvas['items'][number]['frame']) => ({
@@ -485,6 +641,7 @@ const compileAutomationTest = (
 
   return {
     id: testId,
+    alias: test.alias,
     title: test.title,
     hide_short_ref: test.hideShortRef,
     timeout: test.timeout,
@@ -629,39 +786,63 @@ export const compile = async (app: Application) => {
             `(animation index: ${animationIndex}, subspace: ${subspaceId})`,
           )
 
-          if (animation.__typename === 'Animation') {
+          const animationTypename = animation.__typename
+          if (animationTypename === 'Animation') {
             const animationDef = animation as AnimationDef
+            const animationErrorReference = `(animation: ${animationId}, subspace ${subspaceId})`
+            const animationWarningMetadata = {
+              animationIndex,
+              animationTitle: animationDef.title,
+              animationAlias: animationDef.alias,
+              animationProperty: animationDef.property,
+              subspaceIndex,
+              subspaceTitle: subspace.title,
+            }
+            const animationType = getAnimationType(animationDef.config, animationErrorReference)
             map[animationId] = {
               alias: animationDef.alias,
               title: animationDef.title,
               description: animationDef.description,
               hide_short_ref: animationDef.hideShortRef,
               animationRunType: animationDef.runType,
-              property: animationDef.property,
-              type: animationTypeMap[animationDef.config.__type],
-              config: compileProperty(
-                omit(animationDef.config, '__type'),
-                `(animation: ${animationId}, subspace ${subspaceId})`,
+              property: assertAnimationProperty(animationDef.property, animationErrorReference),
+              type: animationType,
+              config: compileAnimationConfig(
+                animationType,
+                animationDef.config,
+                animationErrorReference,
+                animationWarningMetadata,
               ),
             }
-          } else if (animation.__typename === 'AnimationCompose') {
+          } else if (animationTypename === 'AnimationCompose') {
             const animationDef = animation as AnimationComposeDef
+            const animationErrorReference = `(animation: ${animationId}, subspace ${subspaceId})`
             map[animationId] = {
               alias: animationDef.alias,
               title: animationDef.title,
               description: animationDef.description,
               hide_short_ref: animationDef.hideShortRef,
               animationRunType: animationDef.runType,
-              compose_type: animationDef.composeType,
+              compose_type: assertAnimationComposeType(
+                animationDef.composeType,
+                animationErrorReference,
+              ),
               item_list: animationDef.items.map((item, index) => {
                 const innerAnimation = item()
-                if (!innerAnimation?.id)
-                  throw new Error(
-                    `Invalid animation index: ${index} (animation: ${innerAnimation.id}, subspace ${subspaceId})`,
-                  )
-                return { animation_id: innerAnimation.id }
+                const innerAnimationId = assertEntryId(
+                  innerAnimation?.id,
+                  'ANIMATION',
+                  `(animation item index: ${index}, animation: ${animationId}, subspace ${subspaceId})`,
+                )
+                return { animation_id: innerAnimationId }
               }),
             }
+          } else {
+            throw new Error(
+              `Invalid animation typename (animation: ${animationId}, subspace ${subspaceId}): ${String(
+                animationTypename,
+              )}`,
+            )
           }
           return map
         }, {}),
@@ -1029,6 +1210,7 @@ export const compile = async (app: Application) => {
           )
 
           const calc: any = {
+            alias: dataCalc.alias,
             title: dataCalc.title,
             description: dataCalc.description,
             hide_short_ref: dataCalc.hideShortRef,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-project",
-  "version": "2.24.2",
+  "version": "2.24.4",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.2",
+    "@fugood/bricks-cli": "^2.24.4",
     "@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.2",
+  "version": "2.24.4",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.2",
+    "@fugood/bricks-cli": "^2.24.4",
     "@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/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.
 ---
 
 # 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 MCP, 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/animation.md

@@ -41,12 +41,13 @@ const bounce: AnimationDef = {
     toValue: 1,
     friction: 7,
     tension: 40,
-    speed: 12,
-    bounciness: 8,
   },
 }
 ```
 
+Use one spring parameter family per config: `tension/friction`, `speed/bounciness`, or
+`stiffness/damping/mass`.
+
 ### Decay Animation
 Velocity-based deceleration animation.
 

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

@@ -20,16 +20,26 @@ When mobile devices or embedded systems lack hardware for local AI inference (LL
 
 ## Client Configuration
 
-In generator properties, configure Buttress settings:
+In generator properties, configure `buttressConnectionSettings`:
 
 | Setting | Description |
 |---------|-------------|
-| `Enabled` | Toggle Buttress offloading |
-| `URL` | Buttress server URL (e.g., `http://192.168.1.100:2080`) |
-| `Fallback Type` | Action if Buttress unavailable: `use-local` or `no-op` |
-| `Strategy` | Execution preference |
+| `enabled` | Toggle Buttress offloading |
+| `autoDiscoverType` | `auto` (LAN auto-discovery, recommended) or `manual` (typed URL) |
+| `url` | Server URL (`manual` mode only — leave empty for `auto`) |
+| `fallbackType` | If Buttress is unreachable: `use-local` runs locally, `no-op` blocks the load |
+| `strategy` | Execution preference (see below) |
 
-### Strategy Options
+The launcher provides the access token automatically — there is **no user-facing access-token setting**. In `auto` mode the launcher discovers servers bound to the device's workspace and uses its workspace-scoped JWT; in `manual` mode it sends the same JWT only when the typed URL belongs to a server bound to the same workspace (verified against the server's `/buttress/info`).
+
+### `autoDiscoverType` options
+
+| Mode | When to use | What the device does |
+|------|-------------|----------------------|
+| `auto` | LAN deployment with a workspace-bound buttress-server | Listens for UDP announcements and picks the strongest server bound to its workspace; reconnects automatically when the workspace flips |
+| `manual` | Internet-reachable server, mixed networks, or a public/unbound server | Connects to the typed `url` directly; sends a token only when the server is bound to the same workspace |
+
+### Strategy options
 
 | Strategy | Description |
 |----------|-------------|
@@ -37,7 +47,11 @@ In generator properties, configure Buttress settings:
 | `prefer-buttress` | Use Buttress if available, fallback to local |
 | `prefer-best` | Auto-select based on capability comparison |
 
-## Generator Configuration Example
+## Generator Configuration Examples
+
+### Auto-discovery (recommended)
+
+Workspace-bound launcher + workspace-bound buttress-server on the same LAN. No URL needed — discovery picks the highest-scoring server that runs the requested backend.
 
 ```typescript
 import { makeId } from 'bricks-ctor'
@@ -53,7 +67,7 @@ const llmGenerator: GeneratorLLM = {
     contextSize: 8192,
     buttressConnectionSettings: {
       enabled: true,
-      url: 'http://192.168.1.100:2080',
+      autoDiscoverType: 'auto',
       fallbackType: 'use-local',
       strategy: 'prefer-best',
     },
@@ -63,6 +77,44 @@ const llmGenerator: GeneratorLLM = {
 }
 ```
 
+### Manual URL
+
+Use when the server isn't on the launcher's broadcast domain (cross-subnet, internet, behind a reverse proxy) or you want to point at a specific public/unbound server.
+
+```typescript
+buttressConnectionSettings: {
+  enabled: true,
+  autoDiscoverType: 'manual',
+  url: 'http://192.168.1.100:2080',
+  fallbackType: 'use-local',
+  strategy: 'prefer-best',
+}
+```
+
+> ⚠️ With `fallbackType: 'no-op'` the generator refuses to load locally if Buttress is unreachable. Use `'use-local'` whenever the device can also run the model standalone.
+
+## Integrating a discovered buttress-server
+
+The ctor-desktop "Local Devices" panel (and the `bricks buttress scan` CLI) can hand you a server's identity, workspace, and announced generator caps. When the user asks to integrate one:
+
+1. **Confirm workspace match.** The discovery message says whether the server's workspace matches this project's. If it doesn't, do NOT add the integration — instruct the user to run `bricks buttress unbind && bricks buttress bind` from this workspace's owner CLI on the server host. The launcher won't trust a cross-workspace server.
+
+2. **Map announced types to generator templates.** For each `generators[].type` in the announce, target the matching templateKey (create the generator if absent):
+
+   | Announced type | templateKey                  | Default model |
+   |----------------|------------------------------|---------------|
+   | `ggml-llm`     | `GENERATOR_LLM`              | `ggml-org/gemma-3-12b-it-qat-GGUF` (≥20 GB usable) or `ggml-org/gpt-oss-20b-GGUF` (~12 GB usable) |
+   | `mlx-llm`      | `GENERATOR_MLX_LLM`          | `mlx-community/Qwen3-4B-4bit` (or a larger 4-bit quant if `usableBytes` allows) |
+   | `ggml-stt`     | `GENERATOR_SPEECH_INFERENCE` | `BricksDisplay/whisper-ggml` (filename `ggml-small-q8_0.bin`) |
+
+   Pick a model that fits the announced `usableBytes`. Set `contextSize` to match.
+
+3. **Use the canonical auto-discovery config** from "Auto-discovery (recommended)" above. Don't switch to manual mode just because the server is on the LAN — auto mode picks the workspace-bound server automatically and rebinds when the device's workspace flips.
+
+### Real-device caveat
+
+Buttress LAN auto-discovery uses native UDP via `react-native-jsi-udp`. The iOS Simulator silently fails to bind UDP, so auto mode is a no-op there. With `fallbackType: 'use-local'` the generator falls back to local inference in the simulator — dev/test stays functional. **Validate the buttress path itself only when deploying to a real Foundation device; don't gate the build on simulator validation.**
+
 ## Server Setup
 
 ### Requirements
@@ -98,6 +150,43 @@ bricks-buttress --config ./config.toml
 |----------|-------------|
 | `HF_TOKEN` | Hugging Face token for model downloads |
 | `ENABLE_OPENAI_COMPAT_ENDPOINT` | Set to `1` for OpenAI-compatible API |
+| `BRICKS_BUTTRESS_STATE_DIR` | Override the workspace state directory (default `~/.bricks-cli/buttress`) |
+
+## Bind the Server to a Workspace
+
+To use `autoDiscoverType: 'auto'` — and to require workspace-scoped JWT auth — pair the buttress-server with a BRICKS workspace using the `bricks buttress` CLI commands. An unbound server stays in legacy public mode and accepts any LAN client.
+
+### One-time bind
+
+```bash
+# Log into the cloud bricks-server with the workspace owner's account
+bricks auth login
+
+# Pair the buttress-server running on this machine with the active workspace
+bricks buttress bind
+
+# Restart bricks-buttress so it picks up the new state.json
+```
+
+`bricks buttress bind` writes `~/.bricks-cli/buttress/state.json` containing the workspace id, the issuer's Ed25519 public key, and a stable `serverId` (defaults to `buttress-<machineId>`). Override location with `--state-dir` or `$BRICKS_BUTTRESS_STATE_DIR`. For headless setups, use `bricks buttress bind --print` to emit state.json to stdout.
+
+### Verify and manage
+
+```bash
+# Show local binding + workspace-side bound list
+bricks buttress status
+
+# Discover buttress-servers on the LAN (with version, auth state, generator caps)
+bricks buttress scan
+
+# Issue a long-lived workspace access token (CI / ctor agents that already hold a workspace token)
+bricks buttress issue-token --ttl 86400
+
+# Detach this server from the workspace
+bricks buttress unbind
+```
+
+After binding, launchers in the same workspace will auto-discover this server; manual-mode generators will only send their access token if the server's reported workspace matches their own.
 
 ## Server Configuration (TOML)
 

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

@@ -0,0 +1,170 @@
+# 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 `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.
+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.
+
+### `bricks-ctor` MCP — `compile`
+
+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`
+
+Launches headless Electron, takes a screenshot, optionally runs a named Automation test by id or partial title.
+
+Arguments:
+- `delay` (ms before screenshot) — default 3000. 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).
+- `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.
+
+### `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: `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.