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

package/compile/__tests__/util.test.js

@@ -0,0 +1,278 @@
+import { generateCalulationMap, validateConfig } from '../util'
+
+const baseConfig = (overrides = {}) => ({
+  inputs: {},
+  enable_async: false,
+  disabled_triggers: {},
+  output: null,
+  outputs: {},
+  error: null,
+  code: 'return inputs',
+  ...overrides,
+})
+
+const SANDBOX_PREFIX = 'PROPERTY_BANK_COMMAND_NODE_'
+
+const sandboxNodeIds = (map) =>
+  Object.entries(map)
+    .filter(([id, node]) => id.startsWith(SANDBOX_PREFIX) && node.type === 'command-node-sandbox')
+    .map(([id, node]) => ({ id, command: node.properties.command }))
+
+const findSandboxIds = (map) => {
+  const sandbox = sandboxNodeIds(map)
+  return {
+    run: sandbox.find((s) => s.command === 'SANDBOX_RUN_JAVASCRIPT')?.id,
+    error: sandbox.find((s) => s.command === 'SANDBOX_GET_ERROR')?.id,
+    result: sandbox.find((s) => s.command === 'SANDBOX_GET_RETURN_VALUE')?.id,
+  }
+}
+
+describe('validateConfig', () => {
+  test('returns without throwing for a clean config', () => {
+    expect(() => validateConfig(baseConfig({ inputs: { a: 'foo' } }))).not.toThrow()
+  })
+
+  test('skips overlap checks in manual trigger mode', () => {
+    const config = baseConfig({
+      trigger_mode: 'manual',
+      inputs: { a: 'foo' },
+      output: 'a',
+      error: 'a',
+      outputs: { x: ['a'] },
+    })
+    expect(() => validateConfig(config)).not.toThrow()
+  })
+
+  test('throws when error key collides with an input id', () => {
+    const config = baseConfig({ inputs: { a: 'foo' }, error: 'a' })
+    expect(() => validateConfig(config)).toThrow(/key: error/)
+  })
+
+  test('throws when output key collides with an input id', () => {
+    const config = baseConfig({ inputs: { a: 'foo' }, output: 'a' })
+    expect(() => validateConfig(config)).toThrow(/key: output/)
+  })
+
+  test('throws when any outputs entry references an input id', () => {
+    const config = baseConfig({
+      inputs: { a: 'foo', b: 'bar' },
+      outputs: { x: ['c', 'b'] },
+    })
+    expect(() => validateConfig(config)).toThrow(/key: outputs/)
+  })
+
+  test('does not throw when error/output are falsy and inputs are empty', () => {
+    expect(() => validateConfig(baseConfig())).not.toThrow()
+  })
+})
+
+describe('generateCalulationMap', () => {
+  test('produces only the three sandbox nodes for an empty config', () => {
+    const result = generateCalulationMap(baseConfig())
+
+    expect(Object.keys(result.map)).toHaveLength(3)
+    const { run, error, result: returnValue } = findSandboxIds(result.map)
+
+    expect(result.map[run].in.inputs).toEqual([])
+    expect(result.map[error].out.result).toEqual([])
+    expect(result.map[returnValue].out.result).toEqual([])
+    expect(Object.keys(result.editor_info)).toHaveLength(3)
+  })
+
+  test('chains multiple inputs through OBJECT_SET commands', () => {
+    const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo.bar', b: 'baz' } }))
+
+    const { run } = findSandboxIds(result.map)
+
+    // Each input gets a data-node + an OBJECT_SET command-node.
+    expect(result.map.a.type).toBe('data-node')
+    expect(result.map.b.type).toBe('data-node')
+
+    const aCommandId = result.map.a.out.value[0].id
+    const bCommandId = result.map.b.out.value[0].id
+    expect(aCommandId).not.toBe(bCommandId)
+
+    const aCmd = result.map[aCommandId]
+    const bCmd = result.map[bCommandId]
+    expect(aCmd.properties.command).toBe('OBJECT_SET')
+    expect(aCmd.properties.args.path).toBe('foo.bar')
+    expect(bCmd.properties.command).toBe('OBJECT_SET')
+    expect(bCmd.properties.args.path).toBe('baz')
+
+    // First command has no upstream obj; second command's obj input is the first command.
+    expect(aCmd.in.obj).toBeNull()
+    expect(bCmd.in.obj).toEqual([{ id: aCommandId, port: 'result' }])
+    // First command forwards its result to the second command's `obj` input.
+    expect(aCmd.out.result).toEqual([{ id: bCommandId, port: 'obj' }])
+    // The last command feeds the SANDBOX_RUN_JAVASCRIPT `inputs` port.
+    expect(bCmd.out.result).toEqual([{ id: run, port: 'inputs' }])
+    expect(result.map[run].in.inputs).toEqual([{ id: bCommandId, port: 'result' }])
+  })
+
+  test('builds OBJECT_GET commands and target data-nodes for outputs', () => {
+    const result = generateCalulationMap(baseConfig({ outputs: { resultPath: ['pb1', 'pb2'] } }))
+
+    const { result: returnValue } = findSandboxIds(result.map)
+
+    // Both target property-bank nodes are created as data-nodes.
+    expect(result.map.pb1.type).toBe('data-node')
+    expect(result.map.pb2.type).toBe('data-node')
+
+    // The SANDBOX_GET_RETURN_VALUE forwards to the OBJECT_GET command for the output entry.
+    const objectGetRefs = result.map[returnValue].out.result
+    expect(objectGetRefs).toHaveLength(1)
+    const getCommandId = objectGetRefs[0].id
+    expect(objectGetRefs[0].port).toBe('obj')
+
+    const getCmd = result.map[getCommandId]
+    expect(getCmd.type).toBe('command-node-object')
+    expect(getCmd.properties.command).toBe('OBJECT_GET')
+    expect(getCmd.properties.args.path).toBe('resultPath')
+    expect(getCmd.in.obj).toEqual([{ id: returnValue, port: 'result' }])
+
+    // OBJECT_GET feeds both target data-nodes' `change` ports.
+    expect(getCmd.out.result).toEqual([
+      { id: 'pb1', port: 'change' },
+      { id: 'pb2', port: 'change' },
+    ])
+    // Target data-nodes consume the OBJECT_GET result via their `change` port.
+    expect(result.map.pb1.in.change).toEqual([{ id: getCommandId, port: 'result' }])
+    expect(result.map.pb2.in.change).toEqual([{ id: getCommandId, port: 'result' }])
+
+    // Without input usage their `out.value` defaults to null.
+    expect(result.map.pb1.out.value).toBeNull()
+    expect(result.map.pb2.out.value).toBeNull()
+  })
+
+  // Manual mode is the only mode that lets an output target reuse an input id
+  // (see validateConfig tests). When that happens, generateCalulationMap must
+  // keep the input-side `out.value` so the data-node remains a usable input.
+  test.each([
+    ['outputs', { outputs: { result: ['shared'] } }],
+    ['output', { output: 'shared' }],
+    ['error', { error: 'shared' }],
+  ])('preserves input out.value when %s target reuses an input id', (_, overrides) => {
+    const result = generateCalulationMap(
+      baseConfig({ trigger_mode: 'manual', inputs: { shared: 'foo' }, ...overrides }),
+    )
+    expect(Array.isArray(result.map.shared.out.value)).toBe(true)
+    expect(result.map[result.map.shared.out.value[0].id].properties.command).toBe('OBJECT_SET')
+  })
+
+  test('also rewires in.change to OBJECT_GET when an outputs target reuses an input id', () => {
+    const result = generateCalulationMap(
+      baseConfig({
+        trigger_mode: 'manual',
+        inputs: { shared: 'foo' },
+        outputs: { result: ['shared'] },
+      }),
+    )
+    expect(result.map.shared.in.change).toHaveLength(1)
+    expect(result.map[result.map.shared.in.change[0].id].properties.command).toBe('OBJECT_GET')
+  })
+
+  test('preserves out.value when the same pb appears in multiple outputs entries', () => {
+    // Two outputs entries both target `pb1`. The reduce visits each entry in turn
+    // and must preserve the accumulated `out.value` from the first iteration via
+    // `acc.map[pb]` rather than wiping it on the second.
+    const result = generateCalulationMap(
+      baseConfig({ outputs: { first: ['pb1'], second: ['pb1'] } }),
+    )
+    expect(result.map.pb1.type).toBe('data-node')
+    // Without an input, out.value remains null after both passes.
+    expect(result.map.pb1.out.value).toBeNull()
+    // The latest OBJECT_GET wins as the change source — each iteration overwrites
+    // `in.change`, so we end up pointing at the second outputs entry's command.
+    expect(result.map.pb1.in.change).toHaveLength(1)
+  })
+
+  test('wires the error data-node when error is configured', () => {
+    const result = generateCalulationMap(baseConfig({ error: 'errNode' }))
+
+    const { error } = findSandboxIds(result.map)
+    // SANDBOX_GET_ERROR now broadcasts to the error data-node's `change` port.
+    expect(result.map[error].out.result).toEqual([{ id: 'errNode', port: 'change' }])
+    expect(result.map.errNode.type).toBe('data-node')
+    expect(result.map.errNode.in.change).toEqual([{ id: error, port: 'result' }])
+    // No upstream input → out.value falls back to null.
+    expect(result.map.errNode.out.value).toBeNull()
+    // editor_info contains the new node.
+    expect(result.editor_info.errNode).toBeDefined()
+  })
+
+  test('wires the output data-node when output is configured', () => {
+    const result = generateCalulationMap(baseConfig({ output: 'outNode' }))
+
+    const { result: returnValue } = findSandboxIds(result.map)
+    expect(result.map[returnValue].out.result).toEqual([{ id: 'outNode', port: 'change' }])
+    expect(result.map.outNode.type).toBe('data-node')
+    expect(result.map.outNode.in.change).toEqual([{ id: returnValue, port: 'result' }])
+    expect(result.editor_info.outNode).toBeDefined()
+  })
+
+  test('manual trigger mode sets disable_trigger_command on input value ports', () => {
+    const result = generateCalulationMap(
+      baseConfig({
+        trigger_mode: 'manual',
+        inputs: { a: 'foo', b: 'bar' },
+      }),
+    )
+    const aCmdId = result.map.a.out.value[0].id
+    const bCmdId = result.map.b.out.value[0].id
+    expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBe(true)
+    expect(result.map[bCmdId].in.value[0].disable_trigger_command).toBe(true)
+  })
+
+  test('auto trigger mode honours per-key disabled_triggers', () => {
+    const result = generateCalulationMap(
+      baseConfig({
+        inputs: { a: 'foo', b: 'bar' },
+        disabled_triggers: { a: true, b: false },
+      }),
+    )
+    const aCmdId = result.map.a.out.value[0].id
+    const bCmdId = result.map.b.out.value[0].id
+    expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBe(true)
+    // Falsy disabled_triggers entry → property is not set (or set to undefined).
+    expect(result.map[bCmdId].in.value[0].disable_trigger_command).toBeUndefined()
+  })
+
+  test('auto trigger mode without disabled_triggers leaves disable_trigger_command undefined', () => {
+    const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo' } }))
+    const aCmdId = result.map.a.out.value[0].id
+    expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBeUndefined()
+  })
+
+  test('snapshotMode forwards to makeId so generated ids are sequential', () => {
+    const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo' } }), {
+      snapshotMode: true,
+    })
+    const sandboxIds = sandboxNodeIds(result.map).map((s) => s.id)
+    // Snapshot-mode ids embed a 12-digit counter — stable suffix lets us assert order.
+    sandboxIds.forEach((id) => {
+      expect(id).toMatch(/^PROPERTY_BANK_COMMAND_NODE_00000000-0000-0000-0000-\d{12}$/)
+    })
+  })
+
+  test('validateConfig errors propagate out of generateCalulationMap', () => {
+    expect(() => generateCalulationMap(baseConfig({ inputs: { a: 'foo' }, error: 'a' }))).toThrow(
+      /key: error/,
+    )
+  })
+
+  test('SANDBOX_GET_RETURN_VALUE broadcasts to both output target and outputs commands', () => {
+    const result = generateCalulationMap(
+      baseConfig({
+        output: 'outNode',
+        outputs: { foo: ['pb1'] },
+      }),
+    )
+    const { result: returnValue } = findSandboxIds(result.map)
+    const refs = result.map[returnValue].out.result
+    // First entry is the output data-node's `change` port; remainder are OBJECT_GET ids.
+    expect(refs[0]).toEqual({ id: 'outNode', port: 'change' })
+    expect(refs).toHaveLength(2)
+    expect(refs[1].port).toBe('obj')
+    expect(result.map[refs[1].id].properties.command).toBe('OBJECT_GET')
+  })
+})

package/compile/index.ts

@@ -641,6 +641,7 @@ const compileAutomationTest = (
 
   return {
     id: testId,
+    alias: test.alias,
     title: test.title,
     hide_short_ref: test.hideShortRef,
     timeout: test.timeout,
@@ -1209,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-ctor",
-  "version": "2.25.0-beta.11",
+  "version": "2.25.0-beta.13",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.25.0-beta.11",
+    "@fugood/bricks-cli": "^2.25.0-beta.12",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -25,5 +25,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "701de04bd2b569a5fe446a1c89ac776bb79f89f7"
+  "gitHead": "c3b77c39d10f0149b943e6ab92b02cdddd6a628b"
 }

package/skills/bricks-design/SKILL.md

@@ -1,66 +1,193 @@
 ---
 name: bricks-design
-description: Create distinctive, production-grade BRICKS application interfaces with high design quality. Use this skill when the user asks to build BRICKS canvases, screens, layouts, or applications. Generates creative, polished BRICKS code that avoids generic aesthetics.
-license: Complete terms in LICENSE.txt (Apache-2.0, based on github.com/anthropics/skills)
+description: >-
+  Visual design discipline for Applications and Subspaces — type,
+  palette, asset acquisition, design language, system commitment,
+  visual rhythm, brand. TRIGGER for visual / aesthetic / system /
+  style / brand-asset work even when the user names the surface in
+  product terms — slideshow / pitch deck / introduction / explainer
+  / storyboard; kiosk / signage / menu board / lobby / reception /
+  wayfinding / retail / hospitality / museum / transit; translate /
+  port / rebuild from Figma / HTML / screenshot / website / PDF /
+  brand book; vague creative brief ("design something for the
+  lobby"); branded scene work; iteration on existing Subspace
+  (rework, redesign, audit visual system, tighten the type / palette
+  / motion / rhythm). For end-to-end briefs (kiosk, dashboard,
+  interactive screen) this skill invokes in parallel with bricks-ux,
+  which carries the interaction / flow / usability layer. SKIP for
+  pure usability / flow / journey / affordance / feedback / recovery
+  / accessibility / multilingual audits — those go to bricks-ux. SKIP
+  for single-Brick or Generator template work
+  (create-brick-or-generator), debugging or refactoring with no
+  design intent, or non-display deliverables (CLI, server, tooling).
+  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 (Electron preview MCP, on-device CDP,
+  Automations).
 ---
 
-This skill guides creation of distinctive, production-grade BRICKS application interfaces that avoid generic aesthetics. Implement working code with exceptional attention to visual design and creative choices.
+# BRICKS Design
 
-The user provides interface requirements: a screen, layout, application, or component to build. They may include context about the purpose, audience, platform, or technical constraints.
+You are a BRICKS **visual designer**. Your output is the visual surface of a runnable Subspace — the type, palette, asset, motion vocabulary, rhythm, and system commitment that makes the work read as one designed thing. Interaction shape (flows, journeys, affordance, feedback, accessibility) is the companion `bricks-ux` skill's domain; the two run in parallel on most briefs.
 
-## Design Thinking
+Every visual decision is downstream of the deployment — hardware, scene, network, language, brand, peripherals, watchdog. Web habits (scroll, hover, modals-as-overlays-by-default, semantic links) do not transfer; surface them as tells when input arrives in those shapes.
 
-Before coding, understand the context and commit to a **bold** aesthetic direction:
-- **Purpose**: What problem does this interface solve? Who uses it? What platform(s)?
-- **Tone**: Pick a strong direction: brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. Use these for inspiration but design one true to the aesthetic.
-- **Constraints**: Target platform (mobile, TV, desktop, kiosk), screen dimensions, accessibility needs.
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+The user-facing primitive is **Data** (legacy alias: Property Bank — kept in some internal action names like `PROPERTY_BANK`). Surface "Data" in your prose. Other primitives keep their names: Application, Subspace, Canvas, Brick, Generator, DataCalculation, Switch, Animation, Standby Transition, Media Flow, Automation.
 
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
+## Priority #0 — Verify deployment context
 
-Then implement working BRICKS TypeScript code that is:
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
+Before any design exploration, confirm: **hardware** (size, resolution, orientation, touch, viewing distance), **scene** (where the screen lives, what the user does), **network** (always-on / intermittent / offline), **language(s)**, **brand**, **peripherals** (camera, BLE, MQTT, NFC, payment, printer, sensors), **watchdog / fleet management**. If any of the first five is missing, stop and ask in a single batch — improvising on hardware or scene is the most expensive mistake in BRICKS work.
 
-## Aesthetics Guidelines
+## Priority #0.5 — Visually inspect every reference, in full
 
-### Typography
-Choose fonts that are beautiful, unique, and interesting. Avoid defaulting to system fonts — opt for distinctive choices that elevate the interface. Pair a characterful display font with a refined body font. Create clear typographic hierarchy through weight, size, spacing, and alignment. Use auto-scaling (`fontSizeVector`) when text should fill its container proportionally.
+If the user supplies any reference material — a website URL, a docs site, a Figma link, an HTML project, a screenshot, an image, a PDF, a brand book, a video walkthrough, a competitor's product — you must **visually inspect every page, frame, and state of it**, not skim a text summary or rely on a markdown extraction. Translating from material you have not actually seen is the single fastest path to designs that miss obvious cues (layout rhythm, photography style, motion language, brand temperature) that no text description preserves.
 
-### Color & Theme
-Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Use gradients for rich, atmospheric surfaces — multi-stop linear gradients create far more depth than flat fills. Use Data nodes as a shared color store for consistency across bricks.
+Hard rule: a markdown extraction (e.g., `WebFetch`, an `llms.txt`, a `README.md`) is **not** visual inspection. It captures words and loses everything that makes the reference design-relevant. Use it only as a navigation aid — a list of pages to then visit visually.
 
-### Motion & Animation
-Focus on high-impact moments: one well-orchestrated canvas enter with staggered standby reveals creates more delight than scattered micro-interactions. Use spring animations for natural, bouncy UI elements. Use composed animations (parallel/sequence) for coordinated entrance choreography. Reserve looping animations (`breatheStart`) for attention-drawing elements — overuse dulls their impact.
+How to inspect, by source type:
 
-### Spatial Composition
-Absolute positioning gives total control — use it creatively. Overlap bricks. Create asymmetric layouts. Use generous negative space OR controlled density. Break grid expectations. Consider rotation for diagonal flow and perspective. Vary scale dramatically between elements for visual tension.
+- **Website / docs site URL** — drive a browser automation tool (browser-MCP, Playwright/Puppeteer-style MCP server, `agent-browser`-equivalent skill, or any host-provided browser tool). Visit the home page, every primary navigation entry, every page the user explicitly named, and every page that looks like it carries the brand's visual signature (hero, product, gallery, customers). Capture a full-page screenshot of each. Then read each screenshot back via the host's image-reading capability so you actually *see* it. If no browser automation is available, ask the user for screenshots before proceeding.
+- **Figma / design-tool link** — use a Figma-MCP / design-tool MCP if available to enumerate every frame and image-export each; otherwise ask the user for PNG exports of every frame. Inspect each image.
+- **HTML project on disk** — serve and screenshot every route via a browser tool, the same way as a public URL. Don't infer visuals from the source HTML/CSS.
+- **PDF / brand book / slide deck** — read every page via the host's PDF-reading capability (page-by-page if the document is long). Do not summarize from a text extraction.
+- **Local images / screenshots** — read each one via the image-reading tool.
+- **Video walkthrough** — ask the user to provide key-frame screenshots, or to describe each state explicitly. Do not claim to "watch" a video you cannot actually frame-step.
 
-### Depth & Atmosphere
-Create atmosphere through layered elements rather than flat solid colors:
-- **Gradients** with multiple color stops for rich backgrounds
-- **Shadows** for elevation and hierarchy
-- **Blur effects** (blur, progressive blur, liquid glass) for glass morphism on native platforms
-- **Opacity layering** — stack semi-transparent rects for texture and depth
-- **Border details** — per-side colors, styles, and widths for decorative framing
+Coverage check before continuing: list — out loud, in your reply — every reference artifact and the count of pages / frames / images you actually saw. If anything is unseen, name the gap and ask. Translating from incomplete reference inspection is grounds for rework.
 
-### Interactive Polish
-Design interactions that feel tactile and responsive:
-- Scale/opacity animations on press for physical feedback
-- Focus states for TV/controller navigation
-- Outlet-driven switches for state-dependent visual changes
-- Deliberate long-press patterns for secondary actions
+## Workflow spine
 
-## What to NEVER Do
+Pass-based delivery, not sprint-to-finished. Full discipline in [`references/workflow.md`](references/workflow.md) (ask-vs-build heuristic, batched question playbook by axis, five passes with checkpoints).
 
-- **No generic aesthetics**: Avoid the same tired palette, the same safe layout, the same system font on every screen. Each design should feel distinct and intentional.
-- **No flat sameness**: Don't make every canvas look like the same template with different text. Vary spatial composition, color weight, animation timing, and typographic scale.
-- **No placeholder layouts**: Don't just center everything in a grid. Use the absolute positioning system to create spatial interest — overlap, offset, scale contrast.
+1. **Verify deployment context** (Priority #0) and branch on input shape:
+   - Vague brief → [`references/when-the-brief-is-vague.md`](references/when-the-brief-is-vague.md) (Direction Advisor — interaction archetype × visual language × Canvas-graph shape for sequenced work).
+   - Branded brief → [`references/when-the-brief-is-branded.md`](references/when-the-brief-is-branded.md) (Media Flow protocol).
+   - Figma / HTML / screenshot input → [`references/translating-inputs.md`](references/translating-inputs.md).
+   - Presentation / slideshow / intro / explainer / storyboard → [`references/presentation-and-slideshow.md`](references/presentation-and-slideshow.md) (Canvas-graph shape decision, hero continuity).
+2. **Pass 0** — Declare the system as a comment block at the top of the Subspace file: type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance (lean / break / breathe), hero Brick ids. The grid substrate is given by the runtime (Truth #6); the design decisions sit on top.
+3. **Pass 1 — Showcase Canvas lockdown.** Build one Canvas fully lit, verify, show the user. This is the cheapest moment to redirect; do not build the full Canvas graph before sign-off.
+4. **Pass 2** — Build out the full Canvas graph with hero ids shared across Canvases (Truth #3 as narrative principle). Mid-review checkpoint partway through.
+5. **Pass 3** — Polish: spacing-scale adherence, density rhythm, Standby Transition vocabulary consistent, multilingual fits.
+6. **Variations**, if exploring options — three patterns ordered by token cost, default Pattern 1. See [`references/variations-and-tweaks.md`](references/variations-and-tweaks.md). Comparison surface is chat + source tree, not the Canvas.
+7. **Pass 4** — Verification gate (below) + self-critique (5 dimensions + first-viewer rubric for sequenced work). Never declare done off a single screenshot.
 
-Vary between light and dark themes, different fonts, different aesthetics across generations. NEVER converge on common choices across designs.
+## The 10 architecture truths
 
-**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate animations, layered rects, and rich gradients. Minimalist designs need restraint, precision in spacing, and carefully chosen typography. Elegance comes from executing the vision well.
+The load-bearing laws. Each is unpacked in [`references/architecture-truths.md`](references/architecture-truths.md).
 
-Remember: The agent is capable of extraordinary creative work. Don't hold back — show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+1. **Canvas is a state, not a screen.** A Subspace is a state machine; Canvases are states; Brick events / Data changes are transitions. Treat Canvases as web pages and you'll fight the runtime.
+2. **Data is the conduit for *dynamic* values.** Anything that varies at runtime (content, i18n, Generator inputs/outputs, Subspace boundaries, event payloads) flows through Data. Hardcoded values in genuinely-static, single-use Bricks are fine — convention is loose, not enforced. The rule kicks in the moment the value can change.
+3. **Shared Brick ids across Canvases auto-tween.** Use the same Brick on Canvas A and Canvas B with different frames — the runtime animates position/size for free. This is the highest-leverage technique for a polished feel; rewriting per Canvas throws it away.
+4. **Switches compare; Data Hit/Not-Hit only matches.** Canvas / Brick / Generator Switches support `==` `!=` `>` `<` `>=` `<=` against Data values (`SwitchCondData`). Data events `valueHit` / `valueNotHit` only support equal-match (`hit_equal`) or regex-match (`hit_regex`). Threshold-driven UI lives on Switches, not on Data event subscriptions. Don't confuse them.
+5. **Generators are headless, async, event-driven.** Wire them via events; never as synchronous calls. Every chain needs a termination condition. Generators that hit hardware/network must not block the canvas thread.
+6. **Frames are grid units.** Off-grid placement is legal but only ever intentional (overflow effects, anchor-at-origin tricks). It is never a nudge to escape the grid. Bricks fully outside the grid are auto-culled.
+7. **Standby Transition is part of the design language.** Every visible Brick gets an entrance offset (`standbyMode` + `standbyOpacity` + `standbyDelay`); the runtime's auto-tween handles in-flight motion. Snap-cuts are reserved for emphasis (alarm states), never for routine navigation.
+8. **Subspace is a typed module.** Inputs are call-by-value-on-host-change; outlets emit update + value-change events on the host. Extract a Subspace only when the same flow appears 2+ times or when the boundary scopes Data meaningfully — never as a "tidy up" tactic.
+9. **DataCalculation is for derivation only.** Pure inputs → outputs (DataCalculationScript or DataCalculationMap). If your transformation has side effects, navigation, or async I/O, it belongs in an Event Action chain or a Generator. DataCalc orchestrating DataCalc is the wrong primitive.
+10. **No scroll, no overflow, no responsive reflow.** Frames are fixed; what doesn't fit doesn't show. Design within the Canvas; don't import web habits.
+
+## Commit to a design language
+
+A BRICKS Application that doesn't commit to a design language reads as generic regardless of how well it runs. After Direction Advisor (or directly, when the brief is concrete enough), pick a visual language from [`references/design-languages.md`](references/design-languages.md) — Swiss Editorial / Kenya Hara emptiness / Field.io motion poetics / Brutalist web / Y2K futurist-retro / etc. — and write its system declaration as a comment block at the top of the Subspace file. Every subsequent choice cites the block; adding a value not in the block requires updating the block first. That's what makes the system structural rather than aspirational.
+
+The commitment principle: when unsure, do *more* of what defines the chosen language, not less. A style executed at 30% reads as hesitant; at 80% it reads as deliberate. Soften signature moves and you've abandoned the language for nowhere.
+
+The picked language is orthogonal to the picked **interaction archetype** (glance / browse / interact / transact / monitor / dwell — see [`references/when-the-brief-is-vague.md`](references/when-the-brief-is-vague.md)). Together they define the work. Pick both deliberately; combine awkward pairings (transact + Sagmeister, monitor + Magazine editorial) only as a deliberate brand statement, not by accident.
+
+## Pressable composition
+
+Composite-button wiring (where `on_press` sits, which Bricks bypass) is an interaction concern — see the companion `bricks-ux` skill's `pressable-composition.md`. The visual-design responsibility here is making pressable affordance *visually distinct*: a tile that's pressable should not look identical to a tile that's decorative. Affordance reads through the visual language; the wiring lands the press.
+
+## Performance & complexity guardrails
+
+Two reference files cover the second-order rules. Read them when the design is non-trivial.
+
+- [`references/performance.md`](references/performance.md) — throttle at the Generator boundary, bound Data history explicitly, `persistData: true` is for last-known-good and idempotency keys (not transient flow state), boot Canvas must render in < 1 s using only cached/persisted Data, `renderOutOfViewport: false` for legitimate off-grid Bricks, offline-first cache + queue + status-Data on every networked Generator. **Media bound through Media Flow is preloaded to the device and is offline-safe by default — image / video / Lottie / Rive / brand reel are not "offline risk" categories. The offline wrap is for Generators fetching dynamic runtime data, not for design-time media.**
+- [`references/avoiding-complexity.md`](references/avoiding-complexity.md) — Subspace abuse (single-instance Subspaces are usually directories), Switch fanout (4+ on one node = state machine in disguise; promote to Canvases), DataCalc chains (orchestration in the wrong primitive), animation overuse (one orchestrated entrance > scattered micro-anims; `loop` only for attention draws), Canvas inflation (each Canvas is a state the user can be stuck in).
+
+## Asset discipline
+
+Brand work succeeds or fails on assets, not on colors. Logo, product photography, UI screenshots, scene photography, and motion assets are first-class — colors and fonts are auxiliary. Acquire them through the protocol in [`references/when-the-brief-is-branded.md`](references/when-the-brief-is-branded.md): five steps, the 5-10-2-8 quality bar with five named scoring dimensions, three fallback paths per asset category, and structural enforcement that Bricks reference Media Flow Data via DataLink rather than embed, redraw, or skip.
+
+When an asset category genuinely cannot be acquired and the user has no plan to provide one, the priority is: stop and ask (always for logo) → compose the host environment's image / motion generators (canvas-design / imagen / generative MCP), brand-reference-anchored, scored at the same bar → labeled placeholder with the gap tracked in `brand-spec.md`. **This skill does not duplicate generative or composition skills — it composes them.** Where the host has none, surface the constraint to the user; don't silently degrade.
+
+## Anti-slop, terse
+
+Snap canvas transitions on routine navigation. Hardcoded *dynamic* strings (content, i18n) bypassing Data. Hover affordances on no-touch hardware. Sketch-drawn imitations of real brand assets. Aggregator-sourced logos shipped as final. Generated brand imagery without a real brand-reference anchor. Subspaces extracted for "neatness". Switch fanout standing in for state. DataCalc chains standing in for orchestration. Animation everywhere. Stock-photo grounds behind real product photography. CSS-style scroll containers.
+
+## Variations
+
+When exploring options for the user to choose from, default 3, differentiated on a real axis (visual language / interaction archetype / Canvas-graph shape / motion language / content rhythm). Three colour-swap variants is not three variants.
+
+**The comparison surface is chat + source tree, never the Canvas.** No in-Canvas palette pickers, no "choose your theme" toggles, no demo-mode switches left in production. Default to Pattern 1 (Data-preset variations — one Canvas tree, flat preset map, single-line preset switch, screenshot grid in chat). Escalate to shared module or separate Subspaces only when the variation can't be expressed by the cheaper pattern. Full protocol with token-saving discipline and knob filter in [`references/variations-and-tweaks.md`](references/variations-and-tweaks.md).
+
+Ship a one-paragraph trade-off note alongside so the user can pick or blend with full context.
+
+## Verification gate
+
+**Definition of done — non-negotiable.** Before declaring a design complete, every one of the following must be true:
+
+1. The latest source compiles cleanly (`compile` MCP).
+2. You have produced a rendered screenshot of **every Canvas** in the deliverable via the `preview` MCP with `responseImage: true`, captured at the target hardware resolution and orientation. Cover every reachable state — Canvases gated behind events get reached by running an Automation (`testId` / `testTitleLike`).
+3. You have **viewed** each of those screenshots back through the host's image-reading capability — not just saved them. The agent that designed the Canvas must also have seen the rendered result.
+4. If the user supplied any reference material (Figma / website / HTML / screenshot / PDF / brand book), you have done a side-by-side visual comparison between each Canvas screenshot and the corresponding reference, and have written a short delta report listing:
+   - What matches.
+   - What intentionally diverges, and why (deployment constraint, system commitment, BRICKS-runtime limitation).
+   - What unintentionally diverges, and how you will fix it.
+5. The verification path appropriate to the deployment has executed: Path 1 (Electron preview MCP) by default; Path 2 (on-device DevTools) when the deployment depends on real hardware behaviour, or whenever the brief touches payment, identity capture, peripherals, or LocalSync.
+6. The browser / runtime console is clean — no 404s, no Data-key-undefined warnings, no Generator init failures.
+
+A single hero-Canvas screenshot is **not** done. A "looks roughly like the reference" handwave is **not** done. A claim of done without screenshots in evidence is **not** done. If you have not produced and reviewed a screenshot of every Canvas, you are still mid-iteration and must say so explicitly to the user.
+
+**Default loop — Path 1 (Electron preview, no device):**
+
+1. `bricks-ctor` MCP `compile` — typecheck + compile gate.
+2. `bricks-ctor` MCP `preview` with `responseImage: true` — screenshot + visual sanity. Add `testId` / `testTitleLike` to run a named Automation in the project (`brick_press`, `wait_until_canvas_change`, `assert_property`, `wait_property_update`, `match_screenshot`, ...).
+3. Repeat step 2 for every Canvas. Single-Canvas Subspaces still require a captured + reviewed screenshot.
+4. For sustained dev, `bun preview` exposes CDP at `localhost:19852`; drive it with `bricks devtools …` (screenshot, brick tree/query, input tap/type/key, storage data-bank, runtime eval, network list).
+5. **Self-critique pass before declaring done** — every Canvas scored on 5 dimensions (system commitment / visual hierarchy / craft / functional fit / originality), anti-slop top-10 swept clean, < 8 scores either fixed or surfaced as accepted trade-offs. See [`references/design-critique.md`](references/design-critique.md). Verification proves it runs; critique proves it's good — both required.
+
+**Escalate to Path 2 (device-bound DevTools)** before declaring done if the deployment depends on hardware behaviour the Electron preview cannot reproduce: physical orientation/DPI, real touch hardware, peripherals (camera/BLE/MQTT/NFC/payment/printer/sensors), watchdog cycles on the actual launcher build, LocalSync across multiple devices. **Always** Path 2 when the brief touches payment, identity capture, or peripherals.
+
+Path 2 setup is **manual** and the agent cannot do it: ask the user to open the device's **Settings → advanced → Chrome DevTools** toggle (requires BRICKS Foundation ≥ 2.24). The device starts CDP on `:19851`. Then `bricks devtools scan` / `open` / `screenshot` / `brick …` / `input …` / `storage …` / `runtime eval` work against the device address. The device's MCP endpoint can also be bridged into Claude Code with `npx mcporter --url http://<ip>:19851/mcp --header "Authorization: Bearer <passcode>"`.
+
+Path 3 (Remote Debugging via BRICKS Controller, off-LAN) exists for ops scenarios — out of scope for the design loop.
+
+Full toolchain table, decision rule, and concrete invocations: [`references/verification-toolchain.md`](references/verification-toolchain.md).
+
+## Boundaries
+
+- Do not recreate copyrighted UIs. Build an original design that respects the IP.
+- Do not invent brand assets. Use a labeled placeholder Brick + tracked gap list.
+- Do not bypass Data for dynamic values.
+- Do not carry web-frame habits across (scroll, hover, semantic links, modals-by-default, responsive reflow).
+- Treat real-device runs as side-effecting — peripherals fire for real, payment terminals charge for real, MQTT/BLE may broadcast on shared topics. Use a staging device for verification cycles.
+
+## Companion skill: `bricks-ux`
+
+Interaction / flow / journey / affordance / feedback / recovery / accessibility / multilingual concerns live in `bricks-ux`. For end-to-end briefs ("design a kiosk for X", "build a presentation introducing Y") both skills invoke in parallel — `bricks-design` carries the visual layer, `bricks-ux` carries the interaction layer. Cross-references in this skill point to `bricks-ux/references/...` where the interaction discipline matters.
+
+## Reference index
+
+| When you need to... | Read |
+|---|---|
+| Decide when to ask vs build; pace the work across passes | [`references/workflow.md`](references/workflow.md) |
+| Deepen any of the 10 truths | [`references/architecture-truths.md`](references/architecture-truths.md) |
+| Tune for performance / offline | [`references/performance.md`](references/performance.md) |
+| Resist over-engineering | [`references/avoiding-complexity.md`](references/avoiding-complexity.md) |
+| Translate a Figma / HTML / screenshot | [`references/translating-inputs.md`](references/translating-inputs.md) |
+| Pick and commit to a design language | [`references/design-languages.md`](references/design-languages.md) |
+| Design a presentation / pitch deck / intro / explainer / slideshow (visual rhythm + hero continuity) | [`references/presentation-and-slideshow.md`](references/presentation-and-slideshow.md) |
+| Offer variations / pick what becomes a Data knob | [`references/variations-and-tweaks.md`](references/variations-and-tweaks.md) |
+| Self-critique on the visual dimensions | [`references/design-critique.md`](references/design-critique.md) |
+| Verify a design before shipping | [`references/verification-toolchain.md`](references/verification-toolchain.md) |
+| Propose visual directions for a vague brief | [`references/when-the-brief-is-vague.md`](references/when-the-brief-is-vague.md) |
+| Acquire and bind brand assets | [`references/when-the-brief-is-branded.md`](references/when-the-brief-is-branded.md) |
+| Compose a button so taps land where intended | `bricks-ux/references/pressable-composition.md` (companion skill) |
+| Walk the universal interaction journey | `bricks-ux/references/user-journey.md` (companion skill) |
+| Apply interaction-archetype rule sets | `bricks-ux/references/interaction-archetypes.md` (companion skill) |
+| Design idle / loading / empty / error / boot / maintenance states | `bricks-ux/references/flow-states.md` (companion skill) |
+| Design monitoring / dashboard UX | `bricks-ux/references/monitoring-screens.md` (companion skill) |
+| Accessibility floors at deployment-relative thresholds | `bricks-ux/references/accessibility.md` (companion skill) |
+| Tiered UX critique | `bricks-ux/references/ux-critique.md` (companion skill) |