@fugood/bricks-ctor 2.25.0-beta.11 → 2.25.0-beta.13

package/skills/bricks-design/references/translating-inputs.md

@@ -0,0 +1,152 @@
+# Translating Inputs
+
+When the user arrives with a Figma render, an HTML mockup, a screenshot, a competitor URL, or a brand book, you are translating across an impedance mismatch. Web/Figma artifacts encode assumptions (scroll, hover, modal, semantic links, responsive reflow) that BRICKS does not share. Translate intent, not pixels.
+
+## Step 0 — visual inspection is mandatory and exhaustive
+
+You cannot translate from material you have not actually seen. Markdown extractions, text summaries, and `llms.txt`-style indices preserve words and lose every visual signal that makes the reference design-relevant — hierarchy, rhythm, photography style, motion language, brand temperature, typography pairing, density, color weighting. Translating from those alone produces designs that miss the point.
+
+Hard rule before any translation work begins:
+
+- **List every reference artifact** the user supplied (URLs, Figma frames, HTML files, PDFs, screenshots, videos).
+- **Visually inspect each** to completeness — every page, every frame, every state.
+- **State the coverage out loud** in your reply ("inspected: home page, product page, 3 case-study pages, 12 Figma frames, all 8 PDF pages") so the user can spot gaps.
+- If the host environment lacks the tooling to actually see something (no browser automation, no PDF rendering), **ask the user for screenshots before continuing**. Do not pretend.
+
+How to inspect, by source type:
+
+| Source | How to actually see it |
+|---|---|
+| Public URL (website / docs / product page) | Drive a browser automation tool — browser-MCP, Playwright/Puppeteer-style MCP, an `agent-browser`-equivalent skill, or any host-provided browser tool — to navigate the page and capture full-page screenshots. Then read each screenshot back through the host's image-reading capability. `WebFetch` and similar text extractors are **not** visual inspection; use them only as navigation aids to enumerate which pages to visit. |
+| Figma / design-tool URL | Use a Figma-MCP / design-tool MCP if present to enumerate frames and image-export each. Otherwise ask the user for PNG exports of every relevant frame. |
+| HTML project on disk | Serve and screenshot every route via a browser tool, the same as a public URL. Do not infer visuals by reading source HTML/CSS — the rendered output is what you need. |
+| PDF / brand book / slide deck | Read every page through the host's PDF capability, page-by-page when the document is long. Cover all pages, not just the first few. |
+| Local images / screenshots | Read each via the image tool. |
+| Video walkthrough | Ask the user for key-frame screenshots, or to describe each state. Do not claim to have "watched" a video you cannot frame-step. |
+| Live competitor product / app | Run it (or have the user run it and capture screen recordings); inspect the screenshots/states. |
+
+If a reference is partially inaccessible (paywalled page, unauthenticated content, broken link), name the gap explicitly. Don't extrapolate from the visible portion.
+
+Inspection comes before everything else in this file. The translation table below assumes you have already seen every relevant frame.
+
+## A render is one state, not an Application
+
+Most translation mistakes start here. A Figma frame, a screenshot, an HTML page — each is a snapshot of one state. It is never an Application.
+
+Before translating, identify:
+
+- **Which Canvas is this?** Welcome / browsing / editing / confirming / receipt / error?
+- **What Data drives the visible variation in this state?** Which strings, images, lists are dynamic vs. static?
+- **What other Canvases does this flow imply?** A "submit" button implies at minimum a result/confirmation Canvas. A list view implies a detail Canvas (or a Subspace overlay).
+- **What shared chrome carries across?** Logo, header, status bar — these become same-id Bricks across multiple Canvases for auto-tween.
+
+Translating a single render verbatim into one Canvas with no state graph is the most common mistake when porting from web mocks. Don't.
+
+## Translation table — web/Figma → BRICKS
+
+### Scroll
+
+Web overflow scrolling has no BRICKS equivalent. Pick one:
+
+- **Many items, lightweight, glanceable** → `Slideshow` Brick on a timed loop.
+- **Many items, user-driven browse** → `Items` Brick (virtualized list with templated row).
+- **Distinct content sections that don't fit one Canvas** → paginate across Canvases with shared chrome and a paging Brick.
+- **Long form** → Canvas-per-question (Truth #10).
+
+If the source design relies on the user scrolling for hours of content, the information architecture needs a redesign before translation. Don't fake it.
+
+### Hover / focus / `:hover` styles
+
+- **Touch hardware** → hover doesn't exist; the design needs a touch target instead. Move the affordance to the resting state.
+- **No-touch hardware (signage)** → hover doesn't exist; either drop the affordance or convert to a Switch on a non-pointer Data signal (e.g., a peripheral sensor, a state Data toggled by a different Generator).
+- **Web focus rings** → focusable Brick prop where the brick template supports it (TextInput, etc.); for non-input bricks, drop or use Switch-driven outline.
+
+Carrying hover affordances into BRICKS is one of the loudest tells of a sloppy port.
+
+### CSS animations and transitions
+
+CSS keyframes are imperative; BRICKS animations are property-targeted (`transform.translateX | translateY | scale | scaleX | scaleY | rotate | rotateX | rotateY | opacity`) with timing / spring / decay configs.
+
+Translate **intent**, not keyframes:
+
+- A CSS fade-in → a Standby Transition with `standbyOpacity: 0` and a delay.
+- A slide-in from the right → Standby with `standbyMode: 'right'` (or custom standbyFrame) and an x-axis easing.
+- A bounce → an `AnimationSpringConfig` with chosen friction/tension.
+- A continuous CSS pulse → an Animation with `runType: 'loop'` (use sparingly — see performance).
+- A page transition → shared-Brick auto-tween + entrance/exit Standby on non-shared elements (Truth #3 + #7).
+
+### Modal / dialog / popup
+
+Web modals are usually overlays painted via z-index. In BRICKS:
+
+- **Always-on modal pattern (e.g., language picker that any Canvas can summon)** → Subspace with `portal: 'top' | 'left' | 'bottom' | 'right'` invoked from the host.
+- **Single-use confirmation in one flow** → a Canvas of its own. The design is a state; treat it as one.
+- **Inline reveal (e.g., expandable card)** → Switch-driven Brick visibility on the same Canvas. Don't reach for a Subspace for inline behavior.
+
+### Buttons, links, ARIA roles
+
+Translation table:
+
+| Source | BRICKS |
+|---|---|
+| `<button>` (text only) | `BrickText` with `on_press` |
+| `<button>` (with bg, border, padding, icon) | `BrickRect` with `on_press`; children `pressable: 'bypass'` |
+| `<a href="...">` | Same as `<button>` — there is no link primitive. `on_press` triggers `CHANGE_CANVAS` (internal) or a Generator (external) |
+| `<div role="button">` | `BrickRect` with `on_press`; children bypass |
+| `aria-pressed` toggle | A toggle Data + Switch on the visual state |
+| `:hover` | Drop on no-touch; convert to a touch state on touch HW |
+| `:focus` | Focusable Brick prop where supported |
+| `:disabled` | Switch on a `disabled` Data; alter visual + set `pressable: 'disabled'` |
+
+See [`pressable-composition.md`](pressable-composition.md) for the failure modes around composite buttons.
+
+### Form fields / inputs
+
+- Single text input → `BrickTextInput` bound to a Data via DataLink.
+- Long form → Canvas per question (Truth #10), not a scrolling form.
+- Validation → DataCalc producing a `<field>.valid` Data; Switch on the field's appearance to surface error state.
+- Submit → event chain that runs the submission Generator (with idempotency key from Data) and CHANGE_CANVAS to a result Canvas; never a synchronous wait.
+
+### Lists / grids / repeating cards
+
+- Static list (≤ 5 items, never changes) → hand-laid Bricks.
+- Dynamic list, glanceable → `Slideshow` (timed) or `Items` (interactive).
+- Long, browse-heavy → `Items` Brick with templated row Brick; bind `data` to a Data array.
+
+### Images, fonts, video, brand binaries
+
+Lift to **Media Flow** at translation time. Do not embed base64 in Brick props or paste binaries into the Subspace file.
+
+- Images → Data of `kind: { type: 'media-resource-image' }`, referenced by Bricks via DataLink.
+- Fonts → `ApplicationFont` entries in the Application; declare in `applicationSettings`.
+- Video / Lottie / Rive → corresponding `media-resource-video` / `lottie-file-uri` / `rive-file-uri` Data with preload metadata.
+
+When the source contains brand binaries, you are inheriting them — but only at the resolution and quality the source happened to embed, which is often insufficient for the deployment. **Hand the brand-binary work off to the asset protocol** in [`when-the-brief-is-branded.md`](when-the-brief-is-branded.md) rather than translating the visual reference directly into the Subspace as a redraw:
+
+- A logo you can see in the Figma mockup is not the logo you ship — go acquire the official high-resolution source through Step 2/3 of the asset protocol.
+- A product photo embedded in the HTML mockup is the *placeholder* the source designer used; verify it's the brand-current canonical asset before binding, and source a higher-resolution version if the embedded one is below the 5-10-2-8 bar.
+- A redrawn-in-Figma logo or product silhouette in the source design is a tell that the source designer didn't have the real asset either — start the asset hunt from scratch, don't carry the redraw across.
+- Embedded brand fonts may not be license-cleared for embedded display use; verify the license and switch to a documented alternative if the constraint isn't met.
+
+Score everything against 5-10-2-8 before binding. If the source's brand binaries are unclear, low-resolution, or stylized substitutes, surface as a gap in `brand-spec.md` and either acquire properly or — for non-logo categories — escalate to brand-reference-anchored generation per [`when-the-brief-is-branded.md`](when-the-brief-is-branded.md). **Don't ship Sketch-Brick imitations.**
+
+### Brand colors and tokens
+
+- A few colors used in many places → a small set of Data entries acting as theme tokens, bound via DataLink. Worth the indirection.
+- One-off decorative color → hardcode (Truth #2's loose convention).
+- Token system from a brand book (light / dark / accent / semantic) → expose as Data tokens; switch theme by writing to the token Data values.
+
+### Long copy / paragraphs
+
+- A signage screen at 5 m has time for one claim. If the source design has paragraphs of body copy, the design is wrong for the deployment, not the runtime.
+- Cut copy until the screen reads in under 2 seconds.
+- For genuinely long copy (terms of service, instructions), Canvas-per-section + a paging Brick beats fake scrolling.
+
+## Order of operations for a porting task
+
+1. **Verify deployment context** (Priority #0 in SKILL.md). Don't translate before knowing the screen size and orientation; you'll waste the translation.
+2. **Map the source to a Canvas graph.** Sketch which states exist; identify shared chrome.
+3. **Lift binaries to Media Flow.** Don't translate with embedded data; it pollutes the Subspace.
+4. **Walk per-Canvas.** For each Canvas, translate elements via the table above. Make explicit pressable decisions for every interactive element.
+5. **Wire the state machine.** Event chains for transitions; shared-Brick ids for chrome continuity; Standby for entrances.
+6. **Verify against the actual deployment** (see [`verification-toolchain.md`](verification-toolchain.md)). The translation is done when it runs on the target hardware, not when it looks right in the Electron preview.

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

@@ -0,0 +1,124 @@
+# Variations and tweaks
+
+Two different concerns that look similar from a distance and ruin each other when conflated.
+
+- **Exploration variations** — agent offers the user 2–3 directions to compare during the design phase, picks one, the others are discarded. Lives outside the deployed artifact.
+- **Production tweakability** — knobs the operator or environment will actually change once the Application is deployed (locale, theme accent for franchise variants, content feed URL). Lives in Data, with discipline.
+
+Keep them separate. The deployed Application is not a palette picker. The exploration phase is not a Data-knob proliferation event.
+
+## Why no on-Canvas variation picker
+
+Reference design skills built for unbounded HTML put palette pickers and tweak panels in the artifact corner — the user is at a desktop browser, the panel is welcome. BRICKS deliverables run on target hardware (kiosk, signage, lobby screen). An in-Canvas palette picker is design contamination — a tweak UI bolted into the design, same category as decorative page counters or progress chrome.
+
+The comparison surface for exploration variations is **chat and source tree**, never the Canvas.
+
+---
+
+## Exploration variations — three patterns, token-cost order
+
+Default to **Pattern 1**. Escalate only when the variation can't be expressed by the cheaper pattern.
+
+### Pattern 1 — Data-preset variations (default, cheapest)
+
+Use when variations differ only on values: palette, copy, asset paths, density factor, type tokens, brand text, motion timing constants.
+
+**Shape:**
+
+- One Canvas / Subspace. All variant-specific values are Data with initial constants.
+- Source has a `VARIATION_PRESETS` map near the top of the Subspace define file. Each preset is a flat map of token values. Keep the map flat — nested config trees make per-preset diffs noisy.
+- Active preset is selected by a single line near the top: `const ACTIVE = PRESETS.bauhaus`. Agent flips this line, runs preview, captures screenshot, repeats.
+- All hero Bricks keep **the same id** across all presets — preserves Shared Brick auto-tween if the user later wants to A/B them at runtime in a settings Canvas (different use case, but the door stays open).
+
+**Comparison surface:** screenshot grid in chat reply, captioned with preset name + key choices.
+
+**Token cost:** 1 Canvas tree + ~10 lines per preset. A 3-variation comparison ≈ `1 × Canvas + 30 × preset lines`, not `3 × Canvas`.
+
+**Example skeleton:**
+
+```ts
+const PRESETS = {
+  bauhaus: { ground: '#FFFFFF', ink: '#1A1A1A', accent: '#FF3C00', font: 'Inter', density: 1.0 },
+  hara:    { ground: '#F8F4ED', ink: '#2A2A28', accent: undefined,  font: 'Noto Serif', density: 1.4 },
+  brutal:  { ground: '#000000', ink: '#00FF00', accent: undefined,  font: 'IBM Plex Mono', density: 0.8 },
+}
+const ACTIVE = PRESETS.bauhaus  // ← agent flips this one line per variation
+```
+
+Bricks read from `ACTIVE.ground` / `ACTIVE.ink` etc. via Data. The Canvas tree is authored once.
+
+### Pattern 2 — Shared module + variant Subspaces (medium)
+
+Use when variations share most of the Brick tree but differ on a chunk that can't be expressed as Data — different motion language, different hero element identity, different Canvas-graph rhythm, different Standby Transition feel.
+
+**Shape:**
+
+- A shared module (a Subspace-as-typed-module per Truth #8) exports the common Brick definitions, hero ids, and Data shape.
+- 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.
+
+**Token cost:** 1 shared module + N small variant Subspaces.
+
+**Caveat:** if the project's Subspace composition support is limited (some setups don't allow clean cross-Subspace imports of partial Brick trees), escalate to Pattern 1 with a Data-driven Switch on the variant-distinguishing chunk before falling all the way to Pattern 3. A few Switches and a single extra Data value can absorb a surprising amount of "structural" difference.
+
+### Pattern 3 — Separate Subspaces (heaviest, justified case only)
+
+Use when variations differ structurally — Canvas-graph shape (Slideshow vs state-machine vs hybrid), interaction archetype, fundamentally different Brick tree, fundamentally different Data shape.
+
+**Shape:** one Subspace per variation, each stands alone. Previewed individually via the project's Subspace switcher.
+
+**Comparison surface:** chat with screenshots from each Subspace.
+
+**Token cost:** full Subspace × N. Justified only because the variations *aren't* variants of one design — they're different designs.
+
+### Decision rule
+
+```
+Differs only in token values?                            → Pattern 1 (Data presets)
+Differs in some Brick subtree but
+  shares most + same Canvas-graph shape?                 → Pattern 2 (shared module)
+Differs structurally / different shape or archetype?     → Pattern 3 (separate Subspaces)
+```
+
+Default escalation: Pattern 1 first. Move up only when the cheaper pattern would lie about what's varying.
+
+## Token-saving discipline
+
+- **Hero ids identical across presets** — same Brick tree, only Data values differ. Token diff is small; auto-tween stays available for any later A/B Canvas.
+- **Flat preset maps** — each preset is a single object literal, all keys at one depth. Easier to diff, cheaper to edit per variation.
+- **Don't author 3 showcase Canvases inside one Subspace** to compare — triplicates Brick trees for no gain over Pattern 1 + screenshot grid. The temporary-showcase Subspace pattern survives only as a fallback when the user wants to physically walk between variations on real hardware, on explicit request.
+- **Don't escalate proactively** — agent's instinct will be to "just build it three times so the user sees three real things." That's the expensive path. Pattern 1 + a screenshot grid is the same review experience at a fraction of the cost.
+
+---
+
+## Production tweakability — the knob filter
+
+After variations are picked and the production Subspace exists, the question is what should stay user-tweakable in deployment. A Data knob has cost — Generator wiring, history bound, persistence behaviour to reason about, every consumer needs an event handler. The bar is **concrete scenario**, not "maybe someone wants to change this."
+
+**Passes the filter (becomes a Data knob):**
+
+- **Operator-controlled in deployment** — locale switch on a multilingual kiosk, theme accent for franchise variant, content feed URL for menu boards, store hours, item availability.
+- **Environment-driven** — sensor / time-of-day / network state already arriving via a Generator.
+- **Per-instance branding** in fleet deployments where one Subspace serves N venues.
+- **i18n strings** — visible text in a Subspace bound for multilingual deployment, even when only one language is populated at first.
+
+**Fails the filter (hardcode it):**
+
+- Stuff the agent explored during design but the operator won't touch.
+- "Maybe in the future." Three hardcoded lines beat one Data wire until the future arrives.
+- Tweaks meant for the designer's own iteration loop — that's what source edits and Pattern 1 are for, not Data.
+- Speculative theming. If there's no franchise / no white-label requirement, don't make the palette a Data knob.
+
+When in doubt, hardcode. Adding a Data knob later is a small refactor; removing one once consumers exist is a big one.
+
+## Anti-patterns
+
+- **In-Canvas palette pickers / colour swatches / "choose your theme" buttons as a deliverable feature.** Same category as page counters drawn into Canvas content. Allowed only as a literal settings Canvas in a settings Subspace, which is a different use case entirely.
+- **Demo-mode toggles left in production code.** Strip them before declaring done.
+- **Three showcase Canvases inside the production Subspace just for variation review.** Triplicates Brick trees. Use Pattern 1 + screenshot grid.
+- **Speculative Data knobs.** Every Data knob without a named operator scenario is dead weight that complicates the next change.
+- **Pattern-3-by-default** because "the user wants to see real options." User wants to see differences, not duplicated effort. Show differences via Pattern 1.
+- **Triplicated Canvas trees + variant-specific Subspaces for what's actually a palette difference.** Always check: could this be a flat preset?
+- **Forgetting to delete the losing presets after pick.** The production Subspace ships with one preset, hardcoded. The `VARIATION_PRESETS` map is exploration scaffolding, not a runtime selector.

package/skills/bricks-design/references/verification-toolchain.md

@@ -0,0 +1,213 @@
+# 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 a design 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 designed 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.
+
+### `bricks-cli devtools` against `localhost:19852`
+
+Same CDP commands as the device path; just point them at the local preview.
+
+```
+bricks devtools screenshot -a localhost -p 19852 -o local.png
+bricks devtools brick tree -a localhost -p 19852 -d 5
+bricks devtools input tap 480 270 -a localhost -p 19852
+bricks devtools storage data-bank list -a localhost -p 19852
+bricks devtools runtime eval -a localhost -p 19852 "document.title"
+```
+
+### 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 `bricks devtools scan` can find it.
+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 | `devtools://devtools/bundled/inspector.html?ws=<ip>:19851/ws/<passcode>` | Chrome DevTools front-end (or `chrome://inspect`) |
+| MCP | `http://<ip>:19851/mcp` | Bridge to Claude Code via mcporter (below) |
+| MCP SSE | `http://<ip>:19851/sse` | Same, SSE transport |
+
+### Discover the device
+
+```
+bricks devtools scan
+bricks devtools open <ip>
+bricks devtools open <ip> --info   # show full URLs incl. CDP/MCP/passcode
+```
+
+### CDP commands against the device
+
+All `bricks devtools …` commands accept `-a <address> [-p <port>] [--passcode <pc>]`:
+
+```
+bricks devtools screenshot -a <ip> --passcode <pc> -o on-device.png
+bricks devtools brick tree -a <ip> --passcode <pc> -d 5
+bricks devtools brick query "[short-id='abc']" -a <ip> --passcode <pc>
+bricks devtools brick attributes <nodeId> -a <ip> --passcode <pc>
+bricks devtools brick box-model <nodeId> -a <ip> --passcode <pc>
+bricks devtools input tap 540 960 -a <ip> --passcode <pc>
+bricks devtools input type "test user" -a <ip> --passcode <pc>
+bricks devtools input key Enter -a <ip> --passcode <pc>
+bricks devtools storage data-bank list -a <ip> --passcode <pc>
+bricks devtools storage data-bank get <name> <store> -a <ip> --passcode <pc>
+bricks devtools storage system persist -a <ip> --passcode <pc>
+bricks devtools storage generator-cache -a <ip> --passcode <pc>
+bricks devtools network list -a <ip> --passcode <pc>
+bricks devtools network get <requestId> -a <ip> --passcode <pc>
+bricks devtools runtime eval "Object.keys(window)" -a <ip> --passcode <pc>
+```
+
+### Bridge the device into Claude Code via MCP
+
+For interactive agent-driven verification, bridge the device's MCP endpoint as a local STDIO server with mcporter:
+
+```
+npx mcporter --url http://<ip>:19851/mcp --header "Authorization: Bearer <passcode>"
+```
+
+Configure Claude Code (or another MCP client) to spawn that command as an MCP server. The agent can then call the device's MCP tools the same way it calls `bricks-ctor` MCP tools.
+
+### 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 design 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 design 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 via `runtime eval` writes to Data; 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.