@fugood/bricks-ctor 2.24.9 → 2.24.11

package/compile/index.ts

@@ -4,7 +4,7 @@ import upperFirst from 'lodash/upperFirst'
 import snakeCase from 'lodash/snakeCase'
 import omit from 'lodash/omit'
 import { parse as parseAST } from 'acorn'
-import type { ExportNamedDeclaration, FunctionDeclaration } from 'acorn'
+import type { BlockStatement, ExportNamedDeclaration, FunctionDeclaration } from 'acorn'
 import escodegen from 'escodegen'
 import { makeSeededId } from '../utils/id'
 import { generateCalulationMap } from './util'
@@ -97,17 +97,28 @@ const compileProperty = (property, errorReference: string, result = {}) => {
 const compileScriptCalculationCode = (code = '') => {
   try {
     const program = parseAST(code, { sourceType: 'module', ecmaVersion: 2020 })
-    // export function main() { ... }
-    const declarationBody = (
-      (program.body[0] as ExportNamedDeclaration).declaration as FunctionDeclaration
-    )?.body
-    return escodegen.generate(declarationBody, {
-      format: {
-        indent: { style: '  ' },
-        semicolons: false,
+    // The stored config holds the bare function body, which codegen re-wraps as
+    // `export function main() { <code> }`. Unwrap it back to that body here.
+    let block = ((program.body[0] as ExportNamedDeclaration).declaration as FunctionDeclaration)
+      ?.body as BlockStatement | undefined
+    if (!block) return code || ''
+    // Earlier versions emitted the whole BlockStatement (braces included), so every
+    // compile -> codegen round-trip nested the body in one more `{ }`. Emit the inner
+    // statements instead, collapsing any wrapper blocks previous round-trips added so
+    // existing over-wrapped sandboxes heal on the next compile.
+    while (block.body.length === 1 && block.body[0].type === 'BlockStatement') {
+      block = block.body[0] as BlockStatement
+    }
+    return escodegen.generate(
+      { type: 'Program', body: block.body },
+      {
+        format: {
+          indent: { style: '  ' },
+          semicolons: false,
+        },
+        comment: true,
       },
-      comment: true,
-    })
+    )
   } catch {
     return code || ''
   }
@@ -709,6 +720,17 @@ const compileAutomation = (automationMap: AutomationMap) =>
     }),
   )
 
+const buildDefaultExpandedState = (subspace: Subspace) => ({
+  brick: false,
+  generator: true,
+  canvas: (subspace.canvases || []).reduce((acc, canvas) => {
+    if (canvas?.id) acc[canvas.id] = false
+    return acc
+  }, {}),
+  property_bank: false,
+  property_bank_calc: true,
+})
+
 export const compile = async (app: Application) => {
   await new Promise((resolve) => setImmediate(resolve, 0))
   const timestamp = Date.now()
@@ -789,7 +811,7 @@ export const compile = async (app: Application) => {
               property_bank: !subspace.unexpanded.data,
               property_bank_calc: !subspace.unexpanded.dataCalculation,
             }
-          : undefined,
+          : buildDefaultExpandedState(subspace),
         layout: {
           width: subspace.layout?.width,
           height: subspace.layout?.height,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.24.9",
+  "version": "2.24.11",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.9",
+    "@fugood/bricks-cli": "^2.24.11",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",

package/skills/bricks-ctor/references/architecture-patterns.md

@@ -25,6 +25,7 @@ The primary way to orchestrate multi-step flows. A single event can contain an a
 - Use `waitAsync: true` to await async actions before the next step
 - Use `dataParams` + `mapping` to pass event data downstream
 - This is the "glue" that wires generators, state, and UI together
+- For Generator result UI: await Generator, write done/version Data; route/current Data stays identity.
 
 Sequential `PROPERTY_BANK` / `PROPERTY_BANK_EXPRESSION` actions in one chain read the data values that existed when the chain started. If a later action needs to read what an earlier action wrote, set `waitAsync: true` on the earlier action.
 

package/skills/bricks-ctor/references/data-calculation.md

@@ -87,6 +87,17 @@ const triggerCalc: EventAction = {
 - When a **later action reads the calc's outputs**, set `waitAsync: true` on the `PROPERTY_BANK_COMMAND` action itself — it awaits the full calc chain including output writes.
 - A dataParam's `value` acts as an execution gate: `{ input: () => d, value: false }` skips that trigger (combine with `mapping` for conditional runs).
 
+## One trigger source per result panel
+
+A panel that shows the result of an async action (Generator HTTP/LLM response, request telemetry) reads from a calc whose **trigger should come from a single source**: either the live async outlet, or a completion marker the action chain writes — not both.
+
+- **Outlet-triggered** (`{ data: () => dResponse, trigger: true }`): the calc reruns as outlets land. Use when each outlet is only written once its value is final.
+- **Marker-triggered**: run the generator with `waitAsync: true`, then write a `done` Data the calc triggers on. Use when several outlets settle separately and the panel must wait for all of them.
+
+Wiring both at once — triggering on the live outlet _and_ gating on a separately-written marker — lets the calc run before the outlets have settled (it renders `undefined`/stale) while the marker path masks it intermittently. A panel that updates "sometimes" usually has two competing triggers: pick one, and order it with `waitAsync` so the trigger fires after the values it reads are written.
+
+Scope the panel's calc to the **single value it derives** (the formatted display string), and write sibling status labels — running/done, progress, selected route — imperatively in the event chain with `PROPERTY_BANK`. A calc rewrites _every_ one of its outputs on each run, so a return that omits a key writes `undefined` to that output Data (see [Field Rules](#field-rules-defaults-and-constraints)): folding status labels into a multi-output result calc resets them to `undefined` on any run that returns only the derived value. If a calc genuinely must drive several outputs, return all of their keys every run.
+
 ## Script Sandbox
 
 Scripts run in `use strict` mode as a function body — top-level `return` returns the calc result. No `fetch`, `XMLHttpRequest`, or `require` in any mode: I/O belongs to Generators.
@@ -220,6 +231,8 @@ const appendHistory: DataCalculationScript = {
 | `PROPERTY_BANK_COMMAND` does nothing | Auto calc + `trigger: false` input, or `input` doesn't reference an input Data of the calc | Command a `trigger: true` input (auto) or any input (manual) |
 | Compile error `Not allow duplicate set property id...` | Auto mode with same Data as input and output | Use `triggerMode: 'manual'`, or split into separate Data |
 | Calc reads stale value written earlier in the same chain | Missing `waitAsync: true` on the preceding write | Set `waitAsync: true` on the write action |
+| Result/telemetry panel shows `undefined` or stale data intermittently | Calc triggered by two sources at once (live outlet + a separately-written marker) | Trigger from one source — see [One trigger source per result panel](#one-trigger-source-per-result-panel) |
+| Sibling status Data (selected/progress) resets to `undefined` after a calc runs | Multi-output result calc whose return omitted those keys on that run | Scope the calc to one output and write status labels imperatively, or return every output key each run — see [One trigger source per result panel](#one-trigger-source-per-result-panel) |
 | Works in Simulator, fails on device | V8 vs Hermes/JSC engine difference | Verify on device (Path 2); avoid engine-sensitive parsing |
 | `console.log` shows nothing | Console only emits during DevTools debug sessions | Attach DevTools, or write debug values to an output Data |
 | `Promise`/`setTimeout` undefined, or `Async mode is required` error | `enableAsync: false` | Set `enableAsync: true` |

package/skills/bricks-ctor/references/media-flow.md

@@ -31,6 +31,7 @@ const mediaListGenerator: GeneratorMediaFlow = {
   description: '',
   property: {
     boxId: 'promo-box-id',
+    passcode: 'box-read-only-passcode',
   },
   outlets: {
     files: () => promoFilesData, // Array of file objects
@@ -40,6 +41,12 @@ const mediaListGenerator: GeneratorMediaFlow = {
 }
 ```
 
+When hand-writing `GENERATOR_MEDIA_FLOW`, do not use a bare `boxId`. The editor
+flow creates the required authorization, but manual config must include either
+`property.passcode` from a Media Box passcode or `property.accessToken`.
+Without one, devices cannot read the box and the generator will report an
+authorization error.
+
 ## Property Kinds for Media
 
 Link Data properties to Media Flow for asset selection:

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

@@ -26,6 +26,15 @@ What does **not** count as done:
 
 If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.
 
+## Debug loop discipline
+
+Before cycling on a runtime or Automation bug, establish what you can observe. A green or red Automation alone is often not enough to explain a race or branch miss.
+
+- Use one repeatable probe at a time: DevTools state/storage/runtime reads, network/console output, Automation screenshots, or a targeted screenshot after a known event.
+- If branch execution or race timing is unclear, add the smallest temporary log/trace point in the relevant data-calculation script, event handler, or generator path, then compile and rerun the same probe.
+- Do not bounce between CLI, DevTools, and Automation without a hypothesis. State what signal will prove or disprove the next fix before changing code again.
+- Remove temporary traces before declaring done, unless the user asked for persistent diagnostics or the trace is intentionally part of the fix.
+
 ## 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.

package/skills/bricks-design/SKILL.md

@@ -2,7 +2,7 @@
 name: bricks-design
 description: >-
   Visual design discipline for Applications and Subspaces — type, palette, asset
-  acquisition, design language, system commitment, visual rhythm, brand. TRIGGER
+  acquisition, design language, DESIGN.md system, visual rhythm, brand. TRIGGER
   for visual / aesthetic / system / style / brand-asset work even when named in
   product terms — slideshow, pitch deck, explainer, kiosk, signage, menu board,
   lobby, wayfinding, retail, museum, transit; translate or rebuild from Figma /
@@ -40,7 +40,8 @@ How to inspect, by source type:
 - **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.
+- **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. If the host only exposes a cover preview or has no PDF capability, use an installed PDF skill when available. If no PDF skill or local PDF tool is installed and you cannot inspect the PDF fully, stop and respond in chat with the limitation instead of designing from partial evidence. Never proceed from only page 1.
+- **Large rendered PDF pages** — do not hand the vision tool 4-13 MB page PNGs and call the PDF unreadable. Downsample to inspection-sized JPEG/PNG previews, split long PDFs into page batches, and keep a page coverage checklist so every page is either inspected or explicitly marked inaccessible.
 - **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.
 
@@ -55,7 +56,7 @@ Pass-based delivery, not sprint-to-finished. Full discipline in [`references/wor
    - 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.
+2. **Pass 0** — Write the project's [`DESIGN.md`](references/design-md.md): named tokens in the frontmatter (type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, hero Brick ids) plus Deployment Context and the Visual Theme section. The grid substrate is given by the runtime (Truth #6); the design decisions sit on top. The Subspace file carries only a one-line pointer to DESIGN.md; every Brick cites its tokens by name.
 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.
@@ -79,7 +80,7 @@ The load-bearing laws. Each is unpacked in [`references/architecture-truths.md`]
 
 ## 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.
+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 commit it as named tokens in the project's [`DESIGN.md`](references/design-md.md). Every subsequent choice cites a token by name; adding a value not already in the tokens requires adding the token 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.
 
@@ -98,9 +99,9 @@ Two reference files cover the second-order rules. Read them when the design is n
 
 ## 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.
+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. The acquired assets, scores, and bindings land in the **Assets & Brand** sections of [`DESIGN.md`](references/design-md.md) — one artifact, not a separate brand spec.
 
-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.
+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 under DESIGN.md's **Gaps & placeholders**. **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
 
@@ -130,7 +131,7 @@ Ship a one-paragraph trade-off note alongside so the user can pick or blend with
 
 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.
 
-**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.
+**Self-critique pass before declaring done** — every Canvas scored on 5 dimensions (system commitment / visual hierarchy / craft / functional fit / originality), checked section by section against [`DESIGN.md`](references/design-md.md) (does every colour, gap, and motion in the render trace to a declared token?), 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.
 
 For the toolchain itself — `compile` / `preview` MCP usage, `bun preview` flags, Project Automation cases, on-device DevTools setup, the Path 1/2/3 decision rule, and per-deployment-shape verification checklists — see the `bricks-ctor` skill's `rules/verification-toolchain.md`.
 
@@ -150,6 +151,7 @@ Interaction / flow / journey / affordance / feedback / recovery / accessibility
 
 | When you need to... | Read |
 |---|---|
+| Write or update the project's design-system artifact (tokens, schema, brand merge) | [`references/design-md.md`](references/design-md.md) |
 | 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) |

package/skills/bricks-design/references/design-critique.md

@@ -20,19 +20,19 @@ If a dimension cannot be scored ≥ 8 within the deployment's constraints, surfa
 
 ### 1. System commitment
 
-*Does the work cite the declared system (the comment block at the top of the Subspace), and does deviation have rationale?*
+*Does the work cite the declared system (the named tokens in `DESIGN.md`), and does deviation have rationale?*
 
 | Score | Rubric |
 |---|---|
-| 9–10 | Every brick property points back to a Data token, an `ApplicationFont` entry, or the system block. Deviations carry a one-line comment explaining why. |
+| 9–10 | Every brick property points back to a DESIGN.md token, a Data token, or an `ApplicationFont` entry. Deviations carry a one-line comment explaining why. |
 | 7–8 | Direction is correct; 1–2 hardcoded values that should be tokens, or 1–2 deviations without rationale. |
 | 5–6 | Visible drift — a third type family slipped in, a fourth color appeared mid-flow, or a brick redrew an asset that exists in Media Flow. |
-| 3–4 | The system block is decorative; the work doesn't follow it. |
-| 1–2 | No system block, or the block contradicts the work. |
+| 3–4 | DESIGN.md is decorative; the work doesn't follow it. |
+| 1–2 | No DESIGN.md, or its tokens contradict the work. |
 
 **Audit moves:**
-- Open the system block. Pick five values from it (a color, a type size, a Standby duration, a margin, a Brick template). For each, check that the work uses it consistently.
-- Pick five values *from* the work (a `backgroundColor` literal, a `fontSize`, a Standby easing, a hex code in a Rect, a brick template choice). For each, check that the value traces back to the system block or has rationale.
+- Open DESIGN.md. Pick five tokens from it (a color, a type size, a Standby duration, a margin, a Brick template). For each, check that the work uses it consistently.
+- Pick five values *from* the work (a `backgroundColor` literal, a `fontSize`, a Standby easing, a hex code in a Rect, a brick template choice). For each, check that the value traces back to a DESIGN.md token or has rationale.
 - If signature moves of the chosen design language (per [`design-languages.md`](design-languages.md)) are absent, score drops regardless of token-discipline. Swiss Editorial without numbered folios and hairline rules is not Swiss Editorial; it's "vaguely minimal."
 
 ### 2. Visual hierarchy
@@ -67,7 +67,7 @@ If a dimension cannot be scored ≥ 8 within the deployment's constraints, surfa
 
 **Audit moves:**
 - **Grid stance match.** Off-grid placements should serve the declared language (Brutalist break, Sagmeister theatrical, Risograph hand-placed). Off-grid that drifted in accidentally — flag and snap. A Swiss Editorial Canvas with a Brick at `(3.5, 11.2)` is a tell.
-- **Spacing-scale adherence.** Open the style declaration block. Read the declared spacing scale (e.g., `2 / 4 / 8 / 16 gu`). Pick ten inter-Brick gaps across the Canvas — every one must come from that set. Gaps of 7 / 9 / 11 / 13 across siblings = arithmetic drift, the agent picked values ad-hoc instead of from the scale. Snap to the nearest scale value or update the scale (and re-check everywhere).
+- **Spacing-scale adherence.** Open DESIGN.md. Read the declared `spacing` tokens (e.g., `gap-s 2 / gap-m 4 / gap-l 8 / margin 8`). Pick ten inter-Brick gaps across the Canvas — every one must come from that set. Gaps of 7 / 9 / 11 / 13 across siblings = arithmetic drift, the agent picked values ad-hoc instead of from the scale. Snap to the nearest scale value or update the scale (and re-check everywhere).
 - List every distinct colour used in the Canvas. > 4 = deduction (excluding intentional photography palette spreads).
 - List every distinct type family. > 2 = deduction.
 - List every distinct Standby easing / duration combination. > 3 = deduction.
@@ -155,7 +155,7 @@ Walk this list every time. Each is a pattern that consistently slips into agent-
 **Tell:** a brick's `pressable: 'enabled'` carries a press scale-down animation, but the deployment is a 75" no-touch signage panel. **Why bad:** the affordance promises something the hardware cannot deliver; the design reads as "ported from web." **Fix:** drop hover on no-touch; convert to a Switch driven by a non-pointer signal (sensor, timer, peripheral Generator) if the visual intent matters.
 
 ### 10. AI-generated brand imagery without a real brand-reference anchor
-**Tell:** a generated "brand-appropriate" hero image that nobody at the brand has ever seen, produced from a prompt like "modern tech product on a gradient." **Why bad:** generation without anchoring produces uncanny-valley assets that feel adjacent to the brand without being the brand. **Fix:** anchor every generation on at least one verified brand asset (logo, real photo, official color sample); apply 5-10-2-8; log generation metadata in `brand-spec.md`. (See [Media Flow protocol § Creating assets when missing](when-the-brief-is-branded.md#creating-assets-when-missing).)
+**Tell:** a generated "brand-appropriate" hero image that nobody at the brand has ever seen, produced from a prompt like "modern tech product on a gradient." **Why bad:** generation without anchoring produces uncanny-valley assets that feel adjacent to the brand without being the brand. **Fix:** anchor every generation on at least one verified brand asset (logo, real photo, official color sample); apply 5-10-2-8; log generation metadata in DESIGN.md's Assets & Brand. (See [Media Flow protocol § Creating assets when missing](when-the-brief-is-branded.md#creating-assets-when-missing).)
 
 ## Bonus failure modes (BRICKS-specific, less common)
 

package/skills/bricks-design/references/design-languages.md

@@ -35,25 +35,31 @@ If you find yourself softening signature moves to "make it more accessible" —
 3. **Build a 3-cell preview** — three minimal Subspaces (one Canvas each) the user can render. Don't produce finished work; the preview is a chooser.
 4. **Once the user picks, drop out of Advisor mode** and continue the workflow rooted in that direction.
 
-## Style declaration ritual
-
-After the direction is picked, write the committed system as a comment block at the top of the Subspace file. Every subsequent choice should cite this block. Adding a value not in the block requires updating the block first — that's what makes the system structural rather than aspirational.
-
-```ts
-/**
- * System: Swiss Editorial (Pentagram lineage)
- * Archetype: glance
- * Type: <Brand Sans> 4 / 8 / 16 gu · single family · weight contrast
- * Color: ink #1A1A1A on cream #F5F0E6 · accent #FF3C00 (callouts only)
- * Spacing: 2 / 4 / 8 / 16 gu (use only these for inter-Brick gaps)
- * Grid stance: lean (strict alignment, generous margins 4–8 gu)
- * Motion: ease-out 280ms entrance · ease-in 180ms exit · no loops
- * Heroes: logo (id `brand-logo`) · folio (id `folio-num`)
- * Asset emphasis: logo + 1 hero photograph per canvas · no decorative imagery
- */
+## Style declaration ritual — into DESIGN.md
+
+After the direction is picked, commit the system as named tokens in the project's [`DESIGN.md`](design-md.md) frontmatter (full schema there). Every subsequent choice cites a token by name; adding a value not already in the tokens requires adding the token first — that's what makes the system structural rather than aspirational.
+
+```yaml
+system: Swiss Editorial (Pentagram lineage)
+archetype: glance
+colors:
+  ink: "#1A1A1A"      # body text — never pure black
+  ground: "#F5F0E6"   # default Canvas background
+  accent: "#FF3C00"   # callouts only — one per Canvas
+type:                 # sizes in grid units
+  display: { family: "<Brand Sans>", size: 16, weight: 400 }
+  heading: { family: "<Brand Sans>", size: 8,  weight: 400 }
+  body:    { family: "<Brand Sans>", size: 4,  weight: 400 }
+spacing: { gap-s: 2, gap-m: 4, gap-l: 8, margin: 8 }   # inter-Brick gaps come only from here
+grid: lean            # strict alignment, generous margins
+motion:
+  entrance: { ease: ease-out, ms: 280 }
+  exit:     { ease: ease-in,  ms: 180 }
+  loops: none
+heroes: [brand-logo, folio-num]   # persist across Canvases → auto-tween (Truth #3)
 ```
 
-The grid itself is given by the runtime (Truth #6). What the block commits to is the set of design decisions on top of the grid: type scale, palette, **spacing scale in grid units** (small enumeration so inter-Brick gaps stay consistent across many siblings), grid stance, motion vocabulary, and hero Brick ids. The comment is not for the runtime; it is for *you*, when you next look at the file and consider adding a third colour or a fourth gap value. The block's existence is what holds the line.
+The grid itself is given by the runtime (Truth #6). What the tokens commit to is the set of design decisions on top of the grid: type scale, palette, **spacing scale in grid units** (small enumeration so inter-Brick gaps stay consistent across many siblings), grid stance, motion vocabulary, and hero Brick ids. DESIGN.md is not for the runtime; it is for *you*, when you next consider adding a third colour or a fourth gap value. Its existence is what holds the line.
 
 ---
 
@@ -262,4 +268,4 @@ When the user picks an awkward combination ("transact + Sagmeister"), surface th
 
 The 10 directions are anchors. Real work often blends — "Kenya Hara emptiness with one Risograph spot-color accent for the call-to-action" is a legitimate combination if executed deliberately. What's not legitimate is blending three to dilute commitment.
 
-When inventing a direction not in the library: write its system declaration block as if it were one of the entries above (pitch / flagship / keywords / fits / BRICKS execution / wrong-for). If you can't, the direction isn't real yet — keep working on it before committing.
+When inventing a direction not in the library: write its system declaration into DESIGN.md as if it were one of the entries above (pitch / flagship / keywords / fits / BRICKS execution / wrong-for). If you can't, the direction isn't real yet — keep working on it before committing.

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

@@ -0,0 +1,225 @@
+# DESIGN.md — the project's design-system artifact
+
+Every BRICKS design project commits its system to a single durable file: **`DESIGN.md`**, at the project root. It is the source of truth for type, palette, spacing, motion, brand assets, and deployment context — written once in Pass 0, cited by every Brick afterward, and read back at the top of every later session.
+
+The format rests on four ideas:
+
+1. **One named, durable markdown artifact** — not a system scattered across code comments that dies with the file. Markdown is the format an agent reads best; there is nothing to parse.
+2. **Named tokens in YAML frontmatter, referenced by name in the prose.** Declare `accent` once; write `{colors.accent}` everywhere. The body never restates a raw hex or size — one place to change, no drift.
+3. **Real design depth, not surface tokens.** Each token carries its *role* (which colour is CTA vs. body vs. hairline) and the system carries its *signature moves* (the one gesture that makes it recognisable) and the *why* behind each rule.
+4. **An agent guide** that tells the next agent how to *use* the file.
+
+The nine-section schema below is the web-design convention reframed for BRICKS. BRICKS is a fixed-frame, grid-substrate, state-machine runtime, so three of the nine canonical sections are reframed rather than copied — see the mapping table. Importing web habits (breakpoints, scroll, CSS elevation) through this file is the fastest way to fight the runtime.
+
+## DESIGN.md replaces two older artifacts
+
+This file is the merge point for what earlier versions of this skill kept apart:
+
+- The **style-declaration comment block** at the top of the Subspace file → its tokens move into the DESIGN.md frontmatter. The Subspace comment shrinks to a one-line pointer (see [§ The Subspace pointer](#the-subspace-pointer)).
+- **`brand-spec.md`** → its asset bindings, score log, and gaps become the **Assets & Brand** sections of DESIGN.md. One artifact, not two. (The acquisition *protocol* still lives in [`when-the-brief-is-branded.md`](when-the-brief-is-branded.md); DESIGN.md is where its output lands.)
+
+A project has exactly one DESIGN.md. A multi-Subspace Application shares it; per-Subspace deviations are noted as scoped overrides inside it, never as a competing second file.
+
+## The nine sections, mapped to BRICKS
+
+| Web section | BRICKS section | Why it changes |
+|---|---|---|
+| Visual Theme & Atmosphere | **1. Visual Theme & Atmosphere** | Unchanged in spirit — adds the picked visual language × interaction archetype. |
+| Color Palette & Roles | **2. Colour Palette & Roles** | Colours used in 2+ places become theme-token Data bound via DataLink (Truth #2). |
+| Typography Rules | **3. Typography** | Sizes are **grid units**, not px. Families are `ApplicationFont` entries with a fallback ladder. |
+| Component Stylings | **4. Brick & Generator Stylings** | Bricks and Generators, not DOM components. Pressable affordance must read as visually distinct; Generators are headless/async (Truth #5). |
+| Layout Principles | **5. Grid, Spacing & Rhythm** | Frames are grid units (Truth #6). No scroll, overflow, or reflow (Truth #10). |
+| Depth & Elevation | **6. Motion, Standby & Depth** | No CSS z-index / box-shadow model. Depth = Brick draw order + Standby entrance offsets (Truth #7) + shared-id auto-tween (Truth #3). |
+| Do's and Don'ts | **7. Do's & Don'ts** | Each rule tied to what it protects; folds in this system's anti-slop. |
+| Responsive Behavior | **8. Hardware & Orientation** | **Not breakpoints.** Fixed target resolution + orientation; fleet variants are separate Canvas sets or device-scoped Data, never media queries. |
+| Agent Prompt Guide | **9. Agent Guide** | How to cite tokens, add tokens, and verify against this file. |
+
+Two BRICKS-native sections have no web equivalent and sit up front: **Deployment Context** (captures Priority #0 durably) and **Assets & Brand** (the merged `brand-spec.md`).
+
+## Token-reference discipline — the load-bearing habit
+
+This is what separates a system from an accumulation:
+
+- **Declare every reusable value as a named token in the frontmatter.** Reference it by name in the prose and in your reasoning: `{colors.ink}`, `{type.display}`, `{spacing.gap-m}`, `{heroes.brand-logo}`.
+- **Never restate a raw value in the body.** Writing `#1A1A1A` inline instead of `{colors.ink}` forks the source of truth; the next edit updates one and not the other.
+- **Adding a value not already in the tokens requires adding the token first.** Want a third colour or a fourth gap? Edit the frontmatter, then use it. The "first" is the whole mechanism — it forces a deliberate pause where averaging-toward-generic would otherwise sneak a value in.
+- **Sizes and gaps are in grid units (`gu`), never pixels.** The grid substrate is given by the runtime (Truth #6); the design sits on top of it.
+- **Shared colours (2+ uses) become theme-token Data** bound via DataLink, with the token name matching the DESIGN.md key. Single-use decorative colours may stay hardcoded (Truth #2 is loose by design).
+
+## The template
+
+Copy this verbatim into `DESIGN.md` and fill it. Every section is required; an empty section is a declared gap, not an omission.
+
+````markdown
+---
+name: <Application name> — design system
+system: <visual language, e.g. Swiss Editorial (Pentagram lineage)>
+archetype: <glance | browse | interact | transact | monitor | dwell>
+
+deployment:
+  hardware: <size · resolution · orientation · touch? · viewing distance>
+  scene: <where the screen lives, what the user does in front of it>
+  network: <always-on | intermittent | offline>
+  languages: [<en>, <...>]
+  peripherals: [<camera | BLE | MQTT | NFC | payment | printer | sensors | none>]
+  watchdog: <fleet-managed | single-instance>
+
+colors:            # role in the comment; hex is the value
+  ink: "#1A1A1A"        # body text — deep, never pure black
+  ground: "#F5F0E6"     # default Canvas background
+  accent: "#FF3C00"     # callouts only — at most one per Canvas
+  hairline: "#E3E0D6"   # 1gu rules and card edges
+  # forbidden: [<colours the brand explicitly never uses>]
+
+type:              # sizes in grid units (gu)
+  display: { family: "<Brand Sans>", size: 16, weight: 300, tracking: -0.02 }
+  heading: { family: "<Brand Sans>", size: 8,  weight: 400, tracking: 0 }
+  body:    { family: "<Brand Sans>", size: 4,  weight: 400, tracking: 0 }
+  caption: { family: "<Brand Sans>", size: 3,  weight: 400, tracking: 0 }
+
+spacing:           # inter-Brick gaps come ONLY from this set (gu)
+  gap-s: 2
+  gap-m: 4
+  gap-l: 8
+  margin: 8
+
+grid: lean         # lean (strict align, generous margin) | break | breathe
+
+motion:            # Standby Transition vocabulary (Truth #7)
+  entrance: { standbyMode: "<offset, e.g. translateY 4gu>", ease: ease-out, ms: 280, stagger: 40 }
+  exit:     { ease: ease-in, ms: 180 }
+  loops: <none | only on {brick-id}>
+
+heroes:            # Brick ids reused across Canvases → runtime auto-tweens them (Truth #3)
+  - brand-logo
+  - folio-num
+
+fonts:             # ApplicationFont entries → Application.applicationSettings.fonts
+  - { name: "<Brand Sans>", url: "<media-flow-or-cdn-url>", md5: "<optional>" }
+---
+
+# <Application name> — Design System
+> Captured: <YYYY-MM-DD> · Sources: <reference pages / Figma / brand book> · Coverage: <complete | partial | inferred>
+
+## Deployment Context
+The five Priority #0 facts in prose, plus peripherals and watchdog. Every visual
+decision below is downstream of these. If any of the first five was assumed rather
+than confirmed, mark it **ASSUMED** here so the next agent knows what to re-check.
+
+## 1. Visual Theme & Atmosphere
+What the system *says* in two or three sentences. Name the picked **visual language**
+and **interaction archetype**, then the **signature moves** — the one or two gestures
+that make this system recognisable at a glance (e.g. "oversized folio numerals + a
+single hairline rule per Canvas"). When unsure, commit *harder* to these, not softer.
+
+**Key characteristics:** 4–6 bullets, each a concrete, checkable rule.
+
+## 2. Colour Palette & Roles
+Each token by name with its job. Reference `{colors.<name>}` — never the raw hex.
+- `{colors.ink}` — body text on `{colors.ground}`. Deep charcoal, never pure black.
+- `{colors.accent}` — callouts and the single emphasis per Canvas. Never a body colour.
+- `{colors.hairline}` — 1gu rules, card edges.
+- Forbidden: <colours the brand never uses>, if any.
+Shared colours bind as theme-token Data; note which here.
+
+## 3. Typography
+- Families and the **fallback ladder** — what to substitute when the licensed font is
+  absent (e.g. "Söhne → Inter weight 300 + tracking -0.02"). Declared as `fonts` entries.
+- Each role (`{type.display}` … `{type.caption}`) with size in gu, weight, tracking,
+  and *where it is used*. Multilingual note: which scripts the families cover.
+
+## 4. Brick & Generator Stylings
+- **Pressable affordance** — how a tile that responds to a press looks different from a
+  decorative one. A pressable that looks identical to décor is a bug. (Wiring lives in
+  `bricks-ux`; the *visual* distinction lives here.)
+- **Hero Bricks** — the ids in `heroes`, what each is, and how it reads across Canvases.
+- **Generator-driven components** — list / chart / feed surfaces fed by a headless,
+  async Generator (Truth #5). Note their loading, empty, and error appearance.
+- **Media-bound Bricks** — every brand visual reads from Media Flow via DataLink (see
+  Assets & Brand); none is drawn, embedded, or set to a literal path.
+
+## 5. Grid, Spacing & Rhythm
+- **Grid stance** `{grid}` — lean / break / breathe, and what that means in margins.
+- **Spacing scale** — inter-Brick gaps come only from `{spacing.*}`. Ten gaps of
+  7/9/11/13 across siblings is arithmetic drift; snap to the scale.
+- **Density rhythm** — how consecutive Canvases vary (not three identical layouts).
+- **No scroll, overflow, or reflow** (Truth #10). What does not fit does not show;
+  design within the Canvas at the target resolution.
+
+## 6. Motion, Standby & Depth
+- **Standby Transition** `{motion.entrance}` / `{motion.exit}` — every visible Brick
+  gets an entrance offset; the runtime auto-tweens in-flight motion (Truth #7).
+- **Shared-id auto-tween** — heroes keep their id across Canvases so position/size
+  animate for free (Truth #3). This is the highest-leverage polish technique.
+- **Depth** is Brick draw order, not a z/shadow model. State the stacking intent.
+- **Snap-cuts** are reserved for emphasis (alarms), never routine navigation.
+
+## 7. Do's & Don'ts
+Each tied to what it protects. Examples:
+- **Do** reserve `{colors.accent}` for one emphasis per Canvas — sparingness is the signal.
+- **Don't** soften the signature moves "to be safe" — at 30% the language reads hesitant.
+- **Don't** introduce a gap outside `{spacing.*}` — add the token first or don't add it.
+
+## 8. Hardware & Orientation
+Not breakpoints — BRICKS frames are fixed.
+- **Target** resolution and orientation (from Deployment Context). The design is built
+  for this exact frame.
+- **Viewing distance → minimum legible size** in gu, especially for `glance` signage.
+- **Fleet variants** — if the same Application runs on differing resolutions, say how:
+  a separate Canvas set, or device-scoped Data — *not* a media query or reflow.
+- **Language fit** — longest-string behaviour; the design must hold without overflow.
+
+## 9. Agent Guide
+- Reference tokens by name (`{colors.accent}`, `{spacing.gap-m}`); never inline a raw value.
+- To add any value, add the token to the frontmatter first, then use it.
+- Default body to `{type.body}`; default gap to `{spacing.gap-m}`.
+- The Subspace's top comment points here; do not re-declare the system inline.
+- Before declaring done, the design-critique pass cites this file section by section,
+  and every Canvas screenshot is compared against the tokens here.
+
+## Assets & Brand
+(Merged brand spec — populated via the protocol in `when-the-brief-is-branded.md`.)
+
+### First-class assets
+- **Logo** — light / dark / mono → Media Flow IDs → Data keys (`brandLogoDark` …),
+  clearspace, minimum size, source.
+- **Product / UI / scene photography** (per brand type) → IDs → Data keys, each with
+  its 5-10-2-8 score `[R_ P_ B_ C_ N_ = _/10]`.
+- **Motion** — brand reel / animated logo → IDs → Data keys.
+
+### Voice & tone
+Register, capitalization, banned phrases — a constraint on every user-visible Data string.
+
+### Gaps & placeholders
+`<category>: <why missing> → <ask user | generate-with-anchor | accept placeholder> [as of <date>]`
+
+### Score log
+`<asset>: R_ P_ B_ C_ N_ = _/10` for every non-logo asset.
+````
+
+## The Subspace pointer
+
+The Subspace file no longer carries the full system as a comment. It carries a one-line pointer so a reader knows where the system lives and what it is at a glance:
+
+```ts
+/** System: Swiss Editorial · archetype: glance · tokens + assets in ../DESIGN.md */
+```
+
+If a Subspace genuinely needs a scoped deviation (a darker ground for a single monitoring Subspace, say), note the override inside DESIGN.md under that Subspace's name and point the comment at it — never fork a second system silently.
+
+## How DESIGN.md threads through the workflow
+
+- **Pass 0** writes DESIGN.md: frontmatter tokens + Deployment Context + section 1 at minimum. ([`workflow.md`](workflow.md))
+- **Picking a visual language** fills sections 1–3 and `system`/`archetype`. ([`design-languages.md`](design-languages.md))
+- **Branded work** fills Assets & Brand and the colour/type/voice tokens. ([`when-the-brief-is-branded.md`](when-the-brief-is-branded.md))
+- **Variations** are alternate token sets, expressed as a flat preset map keyed to these tokens, not a second DESIGN.md. ([`variations-and-tweaks.md`](variations-and-tweaks.md))
+- **Verification & critique** read DESIGN.md back and check the rendered Canvases against it section by section. ([`design-critique.md`](design-critique.md))
+
+## Anti-patterns specific to DESIGN.md
+
+- **Inlining raw values in the body** instead of `{token}` references — forks the source of truth.
+- **A breakpoint table** in section 8 — that is a web habit; BRICKS frames are fixed (Truth #10).
+- **A CSS-style elevation model** in section 6 — depth is draw order + Standby, not z-index/shadow.
+- **Two artifacts** — a `brand-spec.md` *and* a DESIGN.md, or per-Subspace system blocks competing with the file. One project, one DESIGN.md.
+- **Writing DESIGN.md after the Canvases** — it is a Pass 0 commitment that the build cites, not a doc written to describe finished work.
+- **Tokens with no roles** — `accent: "#FF3C00"` with no note on what it is for is a swatch, not a system. The role is the design depth.

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

@@ -20,13 +20,18 @@ How to inspect, by source type:
 | 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. |
+| 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. If the host only shows a cover preview or has no PDF capability, use an installed PDF skill when available. If no PDF skill or local PDF tool is installed and you cannot inspect the PDF fully, stop and respond in chat with the limitation instead of designing from partial evidence. |
 | 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.
 
+For PDF-derived page images, keep the artifacts sized for inspection. A giant
+4-13 MB PNG per page is a tool failure waiting to happen, not a useful
+handoff. Prefer downsampled JPEG/PNG previews, page batches, and a simple
+coverage checklist (`seen pages: 1-8 of 8`) before design work starts.
+
 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
@@ -128,7 +133,7 @@ When the source contains brand binaries, you are inheriting them — but only at
 - 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.**
+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 under DESIGN.md's **Gaps & placeholders** 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
 
@@ -136,6 +141,8 @@ Score everything against 5-10-2-8 before binding. If the source's brand binaries
 - 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.
 
+Extracted colors, type, and spacing become the named tokens in [`DESIGN.md`](design-md.md) (referenced by name thereafter), so the translated system is captured once rather than re-derived per Canvas.
+
 ### 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.

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

@@ -26,7 +26,7 @@ Use when variations differ only on values: palette, copy, asset paths, density f
 **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.
+- Source has a `VARIATION_PRESETS` map near the top of the Subspace define file. Each preset is a flat map of the DESIGN.md token keys (`ground`, `ink`, `accent`, `gap-m`, …) — a variation is one alternate token set, not a second DESIGN.md. 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).
 

package/skills/bricks-design/references/when-the-brief-is-branded.md

@@ -128,9 +128,9 @@ The bar exists because cosmetic-quality drift is invisible until shipped, then o
 | **Composition / craft** | Lighting, framing, background all consistent with the rest of the asset set | Mixed lighting across "set"; orphan background colors; visible artifacts |
 | **Narrative weight** | Carries one story alone; can be a hero on its own merits | Only works as decoration / filler; needs surrounding chrome to read |
 
-**Logging the scores** in `brand-spec.md` (per category) is what makes the bar real. If you didn't log a score, you didn't apply the bar.
+**Logging the scores** under DESIGN.md's **Score log** (per category) is what makes the bar real. If you didn't log a score, you didn't apply the bar.
 
-### Step 5 — Bind into Media Flow + persist `brand-spec.md`
+### Step 5 — Bind into Media Flow + record in DESIGN.md
 
 Upload acquired assets into a Media Flow workspace (use the host's Media Flow MCP tools where available — `list_media_workspaces`, `get_media_workspace`, `media_box_upload`, `update_media_file_meta`). Reference each from the Subspace via Data with the appropriate `kind`:
 
@@ -145,17 +145,17 @@ Bricks bind via DataLink: `Image.property.source = linkData(() => brandLogoData)
 
 Fonts: declare each as an `ApplicationFont` entry in `Application.applicationSettings.fonts` (`name`, `url`, optional `md5`). Reference by name in Brick `property.fontFamily`.
 
-`brand-spec.md` lives next to the Subspace. Use this template verbatim — every section is required, even the gap section:
+The brand spec is **not** a separate file — it is the **Assets & Brand** sections of the project's [`DESIGN.md`](design-md.md), alongside the colour/type/voice tokens. Use this structure verbatim under DESIGN.md's `## Assets & Brand` heading — every section is required, even the gap section:
 
 ```markdown
-# Brand spec — <brand name>
+## Assets & Brand
 > Captured: <YYYY-MM-DD>
 > Sources: <list>
 > Coverage: <complete / partial / inferred>
 
-## First-class assets
+### First-class assets
 
-### Logo
+#### Logo
 - Primary (dark ground): <Media Flow ID> → Data: brandLogoDark
 - Primary (light ground): <Media Flow ID> → Data: brandLogoLight
 - Mono / reverse: <Media Flow ID> → Data: brandLogoMono
@@ -163,57 +163,56 @@ Fonts: declare each as an `ApplicationFont` entry in `Application.applicationSet
 - Minimum size: <e.g., 96 px wide>
 - Source: <press-kit URL / inline-svg from <url> / file from user>
 
-### Product photography (if physical brand)
+#### Product photography (if physical brand)
 - Hero front: <Media Flow ID> → Data: productHero  (3000×2000, transparent)  [score: R9 P9 B8 C9 N9]
 - Detail crop A: ... [score: ...]
 - Scene context: ... [score: ...]
 
-### UI screenshots (if digital brand)
+#### UI screenshots (if digital brand)
 - Home: ... [score: ...]
 - Core feature A: ... [score: ...]
 
-### Scene / lifestyle (if relevant)
+#### Scene / lifestyle (if relevant)
 - ...
 
-### Motion
+#### Motion
 - Brand reel clip: <Media Flow ID> → Data: brandReel  (1920×1080, 12s, h264)
 - Animated logo: <Media Flow ID> → Data: brandLogoLottie
 
-## Auxiliary
+### Auxiliary
 
-### Colors (theme tokens — exposed as Data when shared)
-- --brand-primary    #XXXXXX   OKLCH(...)   source: <where>
-- --brand-accent     #XXXXXX
-- --brand-neutral-100 / -900
-- Forbidden: <colors the brand explicitly does not use>
+#### Colours
+The palette lives in the DESIGN.md frontmatter `colors` tokens (shared ones bound as theme-token Data). Record provenance and constraints here:
+- `{colors.primary}` / `{colors.accent}` / neutrals — source: <where each was sampled / documented>
+- Forbidden: <colours the brand explicitly does not use>
 
-### Fonts (ApplicationFont entries)
-- Display: <family / weights / file location / license>
-- Body:    <family / weights / file location / license>
+#### Fonts (ApplicationFont entries)
+- Display: <family / weights / file location / license>  → frontmatter `type.display` + `fonts`
+- Body:    <family / weights / file location / license>  → frontmatter `type.body` + `fonts`
 
-### Voice & tone
+#### Voice & tone
 - Register: <e.g., confident, terse, never effusive>
 - Capitalization: <e.g., sentence case>
 - Banned phrases: <e.g., "innovative", "revolutionary", "AI-powered">
 
-### Signature details
+#### Signature details
 - <One or two design moves the brand is known for — a specific corner radius, a hairline rule, a particular typographic treatment.>
 
-## Gaps & placeholders
+### Gaps & placeholders
 - <category>: <why missing> → <action: ask user / AI generate / accept placeholder> [as of <date>]
 
-## Score log (for non-logo assets)
+### Score log (for non-logo assets)
 - <asset>: R<n> P<n> B<n> C<n> N<n> = <avg>/10
 ```
 
 ## Structural enforcement — assets are referenced, not redrawn
 
-Once `brand-spec.md` exists, the discipline that keeps the design honest is structural, not behavioural. Encode it in the build:
+Once DESIGN.md's Assets & Brand sections are populated, the discipline that keeps the design honest is structural, not behavioural. Encode it in the build:
 
 - **Every brand visual** is a Brick reading from a Media Flow Data via DataLink. No `Image.property.source` set to a literal URL or path. No `Sketch` Brick drawing a "logo-shaped" graphic. No `Svg` Brick reproducing the logo as a path. The pattern enforces "you cannot ship a redrawn logo because the project structure doesn't allow it."
 - **Brand colors used in 2+ places** become theme-token Data, bound via DataLink. Single-use decorative colors can stay hardcoded (Truth #2's loose convention).
 - **Theme tokens are the single source of truth.** Want to add a new color? Add a Data entry first, then bind. The "first" is what makes it a system instead of an accumulation.
-- **Every Brick that uses a brand asset** has its source traceable to a `brand-spec.md` line. Reviewing the spec is reviewing the design.
+- **Every Brick that uses a brand asset** has its source traceable to a DESIGN.md Assets & Brand line. Reviewing DESIGN.md is reviewing the design.
 
 ## Creating assets when missing
 
@@ -221,13 +220,13 @@ When a category has no acquirable real asset and the user has no plan to provide
 
 1. **Stop and ask.** For logo, this is the only allowed option.
 2. **Compose the host environment's generative tools.** If a canvas-design / imagen / image-generation MCP / motion-generation MCP / Banana-style tool is available in the host, use it — *anchored on a verified brand reference*. This skill does not duplicate them; it composes them.
-3. **Accept a labeled placeholder Brick** with the gap tracked in `brand-spec.md`. Use this when generation is unavailable or known to fail for the asset type (e.g., generating a "real product photo" for a niche industrial product almost always fails).
+3. **Accept a labeled placeholder Brick** with the gap tracked under DESIGN.md's **Gaps & placeholders**. Use this when generation is unavailable or known to fail for the asset type (e.g., generating a "real product photo" for a niche industrial product almost always fails).
 
 ### Generative discipline (when option 2)
 
 - **Anchor on real brand material.** Feed at least one verified brand asset — the logo, a verified product photo, a brand color sample — as conditioning to the generator. Generation from "the brand's general vibe" produces uncanny-valley assets that feel adjacent to the brand without being the brand. Almost always recognized as fake by reviewers.
 - **Generate at the 5-10-2-8 quantity bar.** 8–10 candidates per slot, scored on the same 5 dimensions, keep 2.
-- **Persist generation metadata** in `brand-spec.md`: prompt, seed (where supported), reference assets used, model version. Reproducibility matters when the user later asks for a refresh in the same style.
+- **Persist generation metadata** under DESIGN.md's Assets & Brand: prompt, seed (where supported), reference assets used, model version. Reproducibility matters when the user later asks for a refresh in the same style.
 - **Never generate logos, wordmarks, or named characters.** These are identity, not imagery — generation produces look-alikes that legal will reject.
 - **Avoid AI-design tells.** Gradient orbs as "AI". Glassy translucent panels with no source. Generic happy-diverse-people-in-a-bright-office. Tech-y blue-purple gradients as backgrounds. Float / hover dot patterns. Watch for these in generated output and re-generate or discard.
 - **Motion generation is high-failure.** For Lottie / Rive / video, expect to discard 9 of 10 outputs. Budget the iteration; don't ship the first plausible result.
@@ -255,7 +254,7 @@ Some BRICKS deployments are for venues with no prior brand work — small clinic
 
 - Skip the protocol; admit the gap up front.
 - Switch into Direction Advisor mode ([`when-the-brief-is-vague.md`](when-the-brief-is-vague.md)) and propose 3 differentiated visual directions.
-- The picked direction *becomes* the brand spec for this Application. Persist the picked direction's tokens, motion language, photography style guidelines, and (if any) generated assets via the same `brand-spec.md` template — even when invented from scratch. Treat it as a real spec, not a working note. The next person to touch the deployment will need it.
+- The picked direction *becomes* the brand spec for this Application. Persist the picked direction's tokens, motion language, photography style guidelines, and (if any) generated assets in DESIGN.md (tokens + Assets & Brand) — even when invented from scratch. Treat it as a real spec, not a working note. The next person to touch the deployment will need it.
 
 ## Voice & tone as a constraint on user-visible Data
 
@@ -274,11 +273,11 @@ You cannot move from this protocol back into design until all of the following a
 1. Logo — present in Media Flow with light + dark + mono where applicable; bound via Data.
 2. Product / UI / scene category appropriate to the brand type — present, scored ≥ 8/10 on each kept asset, bound via Data.
 3. Motion category — present where the brand has motion identity; absent and noted otherwise.
-4. Colors — palette declared as theme-token Data (for shared colors) and / or as `brand-spec.md` entries.
+4. Colors — palette declared as DESIGN.md `colors` tokens (shared ones bound as theme-token Data).
 5. Fonts — declared as `ApplicationFont` entries; license confirmed.
 6. Voice & tone — captured as constraint or marked TBD with stakeholder + date.
 7. Gaps — every missing or placeholder asset listed under "Gaps & placeholders" with action and date.
 8. Score log — every non-logo asset scored on the 5 dimensions and logged.
-9. Spec committed — `brand-spec.md` exists alongside the Subspace; not in a chat scrollback or a working file that will be lost.
+9. Spec committed — DESIGN.md's Assets & Brand sections are filled in the project root; not in a chat scrollback or a working file that will be lost.
 
 If any item is incomplete, name it in your reply and either resolve it or pause for user input. Don't proceed silently.

package/skills/bricks-design/references/workflow.md

@@ -61,31 +61,27 @@ When you do ask, cover these axes — in one batch, omitting any already pinned:
 
 Don't sprint to a finished Subspace. Stage the work so wrong direction is caught at the cheapest point.
 
-### Pass 0 — Deployment context + style declaration
+### Pass 0 — Deployment context + DESIGN.md
 
-Confirm Priority #0 verbatim. Write the style declaration block at the top of the Subspace file before placing any Brick:
+Confirm Priority #0 verbatim, then write the project's **`DESIGN.md`** before placing any Brick. Full schema and template in [`design-md.md`](design-md.md); at Pass 0 you need at minimum:
+
+- **Frontmatter tokens** — `system`, `archetype`, the `colors` / `type` (sizes in grid units) / `spacing` (grid units) / `motion` / `grid` / `heroes` maps. Each token carries its role in a comment.
+- **Deployment Context** — the five Priority #0 facts in prose, with any assumed value flagged `ASSUMED`.
+- **Visual Theme & Atmosphere** (section 1) — what the system says and its one or two signature moves.
+
+The grid substrate is given (Truth #6). What you commit to is type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, and hero Bricks. The spacing scale is a small enumeration (3–5 values); inter-Brick gaps come from this set by name (`{spacing.gap-m}`), not arbitrary integers. DESIGN.md keeps the agent's arithmetic consistent across many Bricks and is what the design-critique pass cites.
+
+The Subspace file itself carries only a one-line pointer:
 
 ```ts
-/**
- * System: <picked design language, e.g., Swiss Editorial>
- * Archetype: <interaction archetype, e.g., glance>
- * Type: <font family> · <size scale in grid units, e.g., 2 / 4 / 8 / 16 gu>
- * Color: <ground> on <ink> · accent <#hex> (used only for …)
- * Spacing: <scale in grid units, e.g., 2 / 4 / 8 / 16 gu>
- * Grid stance: lean / break / breathe
- * Motion: <Standby easing + ms> entrance · <ms> exit · loops only on <element>
- * Heroes: <Brick id(s) that persist across Canvases via auto-tween>
- * Asset emphasis: <real photography / type-only / hero video / …>
- */
+/** System: <picked design language> · archetype: <archetype> · tokens + assets in ../DESIGN.md */
 ```
 
-The grid substrate is given (Truth #6). What you commit to is type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, and hero Bricks. The spacing scale is a small enumeration (3–5 values); inter-Brick gaps come from this set, not arbitrary integers. This block keeps the agent's arithmetic consistent across many Bricks and is what the design-critique pass cites.
-
 ### Pass 1 — Showcase Canvas (the lockdown moment)
 
 Build **one** Canvas, fully lit, that represents the work at its highest fidelity. Choose the hardest Canvas — the boot screen, the most content-dense state, or the moment that carries the brand most. Run through Verification (compile + screenshot + view back). Show the user.
 
-This is the cheapest point to discover the direction is wrong. If the user wants the type bigger, the photography swapped, the rhythm slower, the language different — fix the Canvas and the style declaration, not twelve Canvases.
+This is the cheapest point to discover the direction is wrong. If the user wants the type bigger, the photography swapped, the rhythm slower, the language different — fix the Canvas and the DESIGN.md tokens, not twelve Canvases.
 
 **Do not** build the full Canvas graph before this checkpoint. The temptation is real because state-machine work feels productive; resist it. Sign-off on one Canvas first.
 
@@ -131,4 +127,4 @@ Don't compress passes on:
 - **Asking one question at a time.** Burns volleys, drains user energy.
 - **Asking nothing and inferring.** The five Priority #0 items are not inferrable; trying to is the most expensive mistake.
 - **Declaring done after Pass 2.** Pass 4 critique is what separates "runs" from "good."
-- **Re-declaring the style block on every iteration.** If you find yourself updating five values at once mid-Pass-3, you're rebuilding the system — back up to Pass 1.
+- **Rewriting DESIGN.md tokens on every iteration.** If you find yourself updating five tokens at once mid-Pass-3, you're rebuilding the system — back up to Pass 1.

package/tools/mcp-tools/compile.ts

@@ -2,6 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { readFile } from 'node:fs/promises'
 import { z } from 'zod'
 import { sh } from '../_shell'
+import { appendSimulatorInspectionGuidance } from './simulator-guidance'
 
 // Disable ANSI color codes from spawned tools so MCP text output stays readable
 // (the host renders raw text; escape sequences leak into the result otherwise).
@@ -78,6 +79,7 @@ export function register(server: McpServer, projectDir: string) {
         log = [stdout, stderr].filter(Boolean).join('\n')
         error = true
       }
+      if (!error) log = appendSimulatorInspectionGuidance(log, { testId, testTitleLike })
       let screenshotBase64: string | null = null
       if (!error && responseImage) {
         const toolsDir = `${dirname}/..`

package/tools/mcp-tools/simulator-guidance.ts

@@ -0,0 +1,31 @@
+const quoteShellArg = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
+
+const buildInteractiveSimulatorCommand = ({
+  testId,
+  testTitleLike,
+}: {
+  testId?: string
+  testTitleLike?: string
+} = {}) => {
+  const args = ['bun preview']
+  if (testId) args.push('--test-id', quoteShellArg(testId))
+  if (testTitleLike) args.push('--test-title-like', quoteShellArg(testTitleLike))
+  return args.join(' ')
+}
+
+export function appendSimulatorInspectionGuidance(
+  log: string,
+  options: { testId?: string; testTitleLike?: string } = {},
+) {
+  return [
+    log.trimEnd(),
+    '',
+    'Inspection guidance:',
+    `- For interactive debugging of this same Preview runtime, run \`${buildInteractiveSimulatorCommand(options)}\` from the project directory. It exposes CDP on localhost:19852 by default and writes .bricks/devtools.json for CLI discovery.`,
+    '- Use `bricks devtools -p 19852 ...` from the project directory to inspect the Simulator. Plain `bricks devtools` may inspect another device on the default port.',
+    '- Useful commands: `bricks devtools -p 19852 brick tree`, `brick query <selector>`, `input tap <x> <y>`, `network list`, `storage data-bank get <S_xxxx>`, and `runtime eval "automation.list()" -j`.',
+    '- Prefer this Preview CDP/runtime path over a separate Playwright browser when validating BRICKS app state, logs, input, storage, or network behavior.',
+    '- If the `bricks-cli` skill is unavailable, run `bricks devtools --help`; the CLI help is authoritative.',
+    '',
+  ].join('\n')
+}

package/tools/pull.ts

@@ -1,6 +1,6 @@
-import { readdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import { format } from 'oxfmt'
 import { sh } from './_shell'
 import { extractCliErrorMessage } from './_cli-error'
@@ -86,7 +86,11 @@ const branchName = isModule
   ? 'BRICKS_PROJECT_try-pull-module'
   : 'BRICKS_PROJECT_try-pull-application'
 
+let landingBranch = ''
 if (isGitRepo && !force) {
+  landingBranch = (await sh`cd ${cwd} && git branch --show-current`.text()).trim()
+  if (!landingBranch) throw new Error('Cannot pull from a detached HEAD')
+
   console.log(`Checking commit ${baseCommitId}...`)
   const found = (await sh`cd ${cwd} && git rev-list -1 ${baseCommitId}`.nothrow().text())
     .trim()
@@ -100,8 +104,8 @@ if (isGitRepo && !force) {
 
   // When the base commit isn't reachable in this clone (server stored a
   // nanoid, or the commit was pruned), fall back to forking from current
-  // HEAD. The downstream merge into main collapses both paths into the
-  // same result, just with different merge bases.
+  // HEAD. The downstream merge into the starting branch collapses both paths
+  // into the same result, just with different merge bases.
   if (found) {
     await sh`cd ${cwd} && git checkout -b ${branchName} ${baseCommitId}`.nothrow()
   } else {
@@ -143,7 +147,9 @@ await Promise.all(
       const result = await format(file.name, file.input, oxfmtConfig)
       content = result.code
     }
-    return writeFile(`${cwd}/${file.name}`, content)
+    const target = join(cwd, file.name)
+    await mkdir(dirname(target), { recursive: true })
+    return writeFile(target, content)
   }),
 )
 
@@ -160,11 +166,11 @@ if (isGitRepo) {
     await sh`cd ${cwd} && git ${commitArgs}`
   }
   if (!force) {
-    // Land the pulled commits on main with a single 3-way merge using
+    // Land the pulled commits on the starting branch with a single 3-way merge using
     // baseCommit as the merge base. The user doesn't have to manage a side
-    // branch, and conflicts (if any) land in the working tree on main where
+    // branch, and conflicts (if any) land in the working tree on the starting branch where
     // auto-compile surfaces them as typecheck errors to resolve in-place.
-    await sh`cd ${cwd} && git checkout main`
+    await sh`cd ${cwd} && git checkout ${landingBranch}`
     const mergeResult = await sh`cd ${cwd} && git merge ${branchName} --no-edit`.nothrow()
     if (mergeResult.exitCode !== 0) {
       // Conflict markers are in the working tree — commit them so the tree
@@ -174,7 +180,7 @@ if (isGitRepo) {
       await sh`cd ${cwd} && git add .`
       const conflictArgs = await buildCommitArgs(
         cwd,
-        ['chore(project): merge with conflicts (resolve in main)'],
+        [`chore(project): merge with conflicts (resolve in ${landingBranch})`],
         ['--no-verify'],
       )
       await sh`cd ${cwd} && git ${conflictArgs}`

package/types/bricks/Items.d.ts

@@ -269,6 +269,7 @@ Default property:
                   y?: number | DataLink
                   width?: number | DataLink
                   height?: number | DataLink
+                  type?: string | DataLink
                   standbyMode?: 'custom' | 'top' | 'bottom' | 'left' | 'right' | DataLink
                   standbyFrame?: DataLink | {}
                   standbyOpacity?: number | DataLink
@@ -319,6 +320,7 @@ Default property:
                 }
             show?: string | DataLink
             pressToOpenDetail?: boolean | DataLink
+            pressToBackList?: boolean | DataLink
           }
       >
     | DataLink
@@ -346,6 +348,7 @@ Default property:
                   y?: number | DataLink
                   width?: number | DataLink
                   height?: number | DataLink
+                  type?: string | DataLink
                   standbyMode?: 'custom' | 'top' | 'bottom' | 'left' | 'right' | DataLink
                   standbyFrame?: DataLink | {}
                   standbyOpacity?: number | DataLink
@@ -395,6 +398,7 @@ Default property:
                   renderOutOfViewport?: boolean | DataLink
                 }
             show?: string | DataLink
+            pressToOpenDetail?: boolean | DataLink
             pressToBackList?: boolean | DataLink
           }
       >

package/types/bricks/Sketch.d.ts

@@ -191,9 +191,11 @@ Default property:
     /* A stroke was just committed (drawn or added programmatically) */
     onStrokeEnd?: Array<EventAction<string & keyof TemplateEventPropsMap['Sketch']['onStrokeEnd']>>
     /* The canvas was cleared */
-    onClear?: Array<EventAction>
+    onClear?: Array<EventAction<string & keyof TemplateEventPropsMap['Sketch']['onClear']>>
     /* Sketch state changed (any commit, undo, redo, clear, or import) */
-    onStateChange?: Array<EventAction>
+    onStateChange?: Array<
+      EventAction<string & keyof TemplateEventPropsMap['Sketch']['onStateChange']>
+    >
     /* Active tool changed */
     onToolChange?: Array<
       EventAction<string & keyof TemplateEventPropsMap['Sketch']['onToolChange']>

package/types/bricks/Video.d.ts

@@ -63,7 +63,13 @@ Default property:
   "muted": false,
   "progressUpdateInterval": 1000,
   "replayTimeout": 500,
-  "renderMode": "auto"
+  "renderMode": "auto",
+  "showSubtitles": true,
+  "subtitleColor": "#FFFFFF",
+  "subtitleBackgroundColor": "rgba(0, 0, 0, 0.6)",
+  "subtitleFontSize": 2,
+  "subtitlePosition": "bottom",
+  "subtitleTextAlign": "center"
 }
   */
   property?: BrickBasicProperty & {
@@ -106,6 +112,57 @@ Default property:
     replayTimeout?: number | DataLink
     /* Use what view type for render video (Auto / Texture or Surface).  Notice: Although using surface has better performance, it also affects the Animation & Standby Transition used by itself */
     renderMode?: 'auto' | 'texture' | 'surface' | DataLink
+    /* The subtitle file path list or single path (SRT/WebVTT), index-matched to the video path. Used when no inline subtitles are set for that video. */
+    subtitlePath?:
+      | string
+      | DataLink
+      | DataLink
+      | {
+          url?: string | DataLink
+        }
+      | Array<
+          | DataLink
+          | {
+              url?: string | DataLink
+            }
+          | string
+          | DataLink
+          | DataLink
+        >
+      | DataLink
+      | DataLink
+    /* Inline subtitles per video, index-matched to the video path: each entry holds a `cues` list of { start, end, text } (start/end in seconds). Takes precedence over the subtitle file for that video. */
+    subtitles?:
+      | Array<
+          | DataLink
+          | {
+              cues?:
+                | Array<
+                    | DataLink
+                    | {
+                        start?: number | DataLink
+                        end?: number | DataLink
+                        text?: string | DataLink
+                      }
+                  >
+                | DataLink
+            }
+        >
+      | DataLink
+    /* Render the subtitle overlay. Turn off to only trigger subtitle events without rendering text */
+    showSubtitles?: boolean | DataLink
+    /* Subtitle text color */
+    subtitleColor?: string | DataLink
+    /* Subtitle background color */
+    subtitleBackgroundColor?: string | DataLink
+    /* Subtitle font size, in grid units (same as Brick Text) */
+    subtitleFontSize?: number | DataLink
+    /* Subtitle font family */
+    subtitleFontFamily?: string | DataLink
+    /* Subtitle vertical position */
+    subtitlePosition?: 'bottom' | 'top' | DataLink
+    /* Subtitle text alignment */
+    subtitleTextAlign?: 'left' | 'center' | 'right' | DataLink
   }
   events?: BrickBasicEvents & {
     /* Event of the brick press */
@@ -130,6 +187,14 @@ Default property:
     onError?: Array<EventAction>
     /* Event of the video progress interval */
     onProgress?: Array<EventAction<string & keyof TemplateEventPropsMap['Video']['onProgress']>>
+    /* Event when a subtitle cue starts (appears) during playback */
+    subtitleCueEnter?: Array<
+      EventAction<string & keyof TemplateEventPropsMap['Video']['subtitleCueEnter']>
+    >
+    /* Event when a subtitle cue ends (disappears) during playback */
+    subtitleCueExit?: Array<
+      EventAction<string & keyof TemplateEventPropsMap['Video']['subtitleCueExit']>
+    >
   }
   outlets?: {
     /* Brick is pressing */
@@ -149,6 +214,8 @@ Default property:
     onLoad?: AnimationOrGetter
     onError?: AnimationOrGetter
     onProgress?: AnimationOrGetter
+    subtitleCueEnter?: AnimationOrGetter
+    subtitleCueExit?: AnimationOrGetter
   }
 }
 

package/types/generators/Http.d.ts

@@ -157,7 +157,12 @@ Default property:
     /* Event name to listen on SSE */
     eventName?: string | DataLink | Array<string | DataLink> | DataLink | DataLink
   }
-  events?: {}
+  events?: {
+    /* Event triggered when the HTTP request receives a response */
+    onResponse?: Array<EventAction<string & keyof TemplateEventPropsMap['Http']['onResponse']>>
+    /* Event triggered when the HTTP request or SSE stream reports an error */
+    onError?: Array<EventAction<string & keyof TemplateEventPropsMap['Http']['onError']>>
+  }
   outlets?: {
     /* Response for HTTP request */
     response?: () => Data<string | { [key: string]: any }>

package/types/generators/Tick.d.ts

@@ -33,7 +33,7 @@ Default property:
   property?: {
     /* Start tick on generator initialized */
     init?: boolean | DataLink
-    /* Interval of second for countdown */
+    /* Tick interval in milliseconds for countdown */
     interval?: number | DataLink
     /* Initial value of countdown */
     countdownStartValue?: number | DataLink

package/utils/data.ts

@@ -85,7 +85,7 @@ type SystemDataName =
 type SystemDataInfo = {
   name: SystemDataName
   id: string
-  type: 'string' | 'number' | 'bool' | 'boolean' | 'array' | 'object' | 'any'
+  type: Data['type']
   title?: string
   description?: string
   schema?: object

package/utils/event-props.ts

@@ -16,6 +16,13 @@ export const templateEventPropsMap = {
   Video: {
     nextVideo: { BRICK_VIDEO_NEXT_INDEX: 'number' },
     onProgress: { BRICK_VIDEO_CURRENT_TIME: 'number', BRICK_VIDEO_PLAYABLE_DURATION: 'number' },
+    subtitleCueEnter: {
+      BRICK_VIDEO_SUBTITLE_TEXT: 'string',
+      BRICK_VIDEO_SUBTITLE_INDEX: 'number',
+      BRICK_VIDEO_SUBTITLE_START: 'number',
+      BRICK_VIDEO_SUBTITLE_END: 'number',
+    },
+    subtitleCueExit: { BRICK_VIDEO_SUBTITLE_TEXT: 'string', BRICK_VIDEO_SUBTITLE_INDEX: 'number' },
   },
   VideoStreaming: {},
   Qrcode: {},
@@ -142,7 +149,9 @@ export const templateEventPropsMap = {
     },
   },
   Sketch: {
-    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number' },
+    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number', BRICK_SKETCH_STATE: '{}' },
+    onClear: { BRICK_SKETCH_STATE: '{}' },
+    onStateChange: { BRICK_SKETCH_STATE: '{}' },
     onToolChange: { BRICK_SKETCH_TOOL: 'string' },
     onExportImage: { BRICK_SKETCH_IMAGE_URI: 'string' },
   },
@@ -267,7 +276,14 @@ export const templateEventPropsMap = {
     subscribeDataOnConnectError: { GENERATOR_DATA_BANK_ERROR: '{ [key: string]: any }' },
   },
   Graphql: { subscriptionOnConnectionError: { GENERATOR_GRAPHQL_ERROR: '{ [key: string]: any }' } },
-  Http: {},
+  Http: {
+    onResponse: {
+      GENERATOR_HTTP_RESPONSE: 'any',
+      GENERATOR_HTTP_RESPONSE_DETAILS:
+        '{ ok?: boolean redirected?: boolean type?: string status?: number statusText?: string headers?: { [key: string]: any } body?: any event?: string id?: string data?: any [key: string]: any }',
+    },
+    onError: { GENERATOR_HTTP_ERROR: 'string' },
+  },
   SoundPlayer: { onLoadError: { GENERATOR_SOUND_PLAYER_ERROR: 'string' } },
   Keyboard: {
     onDown: {