@fugood/bricks-ctor 2.25.0-beta.5 → 2.25.0-beta.50

package/skills/bricks-ux/references/pressable-composition.md

@@ -0,0 +1,126 @@
+# Pressable Composition
+
+The composition decision and the wiring decision are the same decision. Affordance — *can I press this?* — is a UX signal the user reads off the screen. Pressable configuration is how that signal lands at the runtime. Get the configuration wrong and the screen lies to the user: a tile looks pressable but isn't, or is pressable but only on certain pixels. Either way, the user fights the design.
+
+This file covers the configuration side. For the affordance discipline above it (when a thing should look pressable in the first place, how it joins the 7-step journey), see [`user-journey.md`](user-journey.md) step 1 and the relevant archetype rule set in [`interaction-archetypes.md`](interaction-archetypes.md).
+
+The single principle: **every composite (multi-element) button needs a deliberate `on_press` decision per Brick, with `pressable` set explicitly wherever press chains layer.** The runtime auto-bypasses safe cases (see below), so the trivial wrapper case works without ceremony — but the design intent should still be readable from the configuration when chains compete.
+
+There is no single mandated shape. Many arrangements work. The discipline is making the decision explicit where presses can collide, not following a recipe.
+
+## The values
+
+`Brick.property.pressable` accepts:
+
+- `'enabled'` — Brick receives press events; if it has an `on_press` chain, the chain runs.
+- `'disabled'` — Brick does not receive press events even if `on_press` is configured. Useful for runtime-disabled state via DataLink.
+- `'bypass'` — Brick is transparent to press events; the press passes through to whatever sits behind/around it.
+
+**Runtime auto-bypass.** Pressable-capable Bricks — `BrickText`, `BrickImage`, `BrickIcon`, `BrickRect`, `BrickSvg`, `BrickLottie`, `BrickRichText`, `BrickVideo`, `BrickVideoStreaming`, `BrickQRCode`, `BrickMaps`, `BrickGenerativeMedia` — with no configured press events (no `on_press`, no `on_focus`, no press/focus outlets feeding Switches or Animations) are auto-bypassed: the runtime renders them with `pointerEvents='none'` so taps fall through to the Brick underneath. A user-set `pressable` value always wins over auto-bypass.
+
+**Non-pressable families** — `BrickTextInput`, `BrickCamera`, `BrickSlideshow`, `BrickItems`, `BrickChart`, `BrickWebView`, `BrickRive` — manage their own interaction internally and are not auto-bypassed. Their pressable behavior is unchanged.
+
+`Brick.events.on_press` is the standard press handler — an array of `EventAction`s that runs on tap.
+
+## Common arrangements
+
+### Text-only press surface
+
+Simplest, most BRICKS-idiomatic.
+
+- One `BrickText` with an `on_press` chain.
+- The entire press surface is the text run itself.
+
+Use when: the visual is the text and only the text. Branding-light text links, in-flow CTAs.
+
+### Wrapped region (background, border, padding)
+
+The moment you add a `BrickRect` (or any shape) as a tile, card, button background, or padded container, the press intent moves to the wrapper.
+
+- `BrickRect` carries `on_press`.
+- Inner Bricks (the text label, an icon, an image) sit on top with no press events of their own.
+- The runtime auto-bypasses pressable-capable inner Bricks without press events, so the wrapper's chain fires regardless of where on the tile the user taps. No explicit `pressable: 'bypass'` is required for the common case.
+- Setting `pressable: 'bypass'` on the inner Bricks is still good practice when the child is purely decorative: it documents the design and protects against later edits that wire press- or focus-driven effects onto the child (e.g., a Switch fed by a press outlet) and silently break the tile.
+
+Use when: the press surface includes background, border, padding, or composition beyond a single text run.
+
+### Composite tile (image + text + meta, all pressable as one)
+
+Same shape as the wrapped region, with more children.
+
+- Backing `BrickRect` carries `on_press`.
+- All visual children — image, headline, subhead, icon, meta — auto-bypass when they carry no press events of their own.
+- The user perceives one tile; the runtime sees one press surface.
+- Explicit `pressable: 'bypass'` per child remains a clarity discipline, especially in tile layouts that are duplicated and later edited — a stray press handler on one child would otherwise break that tile silently.
+
+Use when: a card, a row in a list (note: `Items` Brick has its own row press model — read the template), a media tile.
+
+### Mixed-action composite (rare but real)
+
+A composite where most of the surface does action A, but a small region does action B (e.g., a card whose body opens a detail view but whose corner heart icon toggles favorite).
+
+- Backing `BrickRect` carries `on_press` for action A.
+- Most children auto-bypass (no press events of their own).
+- The exception child (heart icon) carries its own `on_press` for action B. Because it now has a press chain, auto-bypass is off and the icon owns its hit region.
+- Caveat: ensure the exception child is large enough to hit reliably without colliding with the surrounding action A. If it's too small, users will fight it.
+
+Use when: genuinely needed. If you find yourself reaching for this often, the design is probably trying to do too much per tile — split into clearer affordances.
+
+## Failure modes
+
+### Overlapping pressables
+
+Two or more children of a composite each carry their own `on_press` (or a Switch/Animation fed by a press/focus outlet). Auto-bypass doesn't apply — each child has events. The runtime resolves taps to whichever Brick owns that pixel; in practice this means inconsistent behavior depending on where the user actually lands.
+
+**Fix**: pick the press owner (usually the wrapper) and set the others to `pressable: 'bypass'` explicitly. The user-set value wins, so this forces the press through to the intended owner even when the loser Bricks have events.
+
+### Hidden press handlers on inner Bricks
+
+A composite that used to auto-bypass cleanly stops doing so after a Switch is wired to read a press or focus outlet on an inner Brick, or after an `on_press` is added to that child for an unrelated effect. The wrapper appears to lose hit area for that region without an obvious cause — auto-bypass is off the moment any press event is configured.
+
+**Fix**: when you wire any press- or focus-driven effect on a Brick inside a composite, set its `pressable` explicitly. If the effect should run *and* the wrapper should still win the tap, use `pressable: 'bypass'` on the child and drive the effect from the wrapper's chain instead.
+
+### Decorative overlay with unintended press chain
+
+A decorative `BrickRect` (frame edge, gradient overlay, spacing tile) sits in front of a pressable region and has press events wired — usually a leftover Switch trigger or copy-pasted from a real button. Auto-bypass doesn't engage, and the overlay silently consumes taps.
+
+**Fix**: any decorative overlay sitting in front of a pressable region should be `pressable: 'bypass'` explicitly. Treat "transparent in front of pressable" as a code smell that needs an explicit pressable decision — the runtime would auto-bypass a Brick with no press events, but the explicit value documents intent and survives future edits that wire effects into it.
+
+### Phantom hover on no-touch hardware
+
+Carried over from a web design with hover affordances — usually a Brick that brightens or shifts on press but the deployment is signage with no touch.
+
+**Fix**: drop the affordance, or move it to a state driven by a different signal (proximity sensor, scheduled time, Data from a peripheral Generator).
+
+### Web link semantics
+
+Designers used to web habits sometimes add `<a>`-style underlines or color treatments expecting a navigation primitive.
+
+**Fix**: BRICKS has no link semantic. `on_press` triggers `CHANGE_CANVAS` (internal navigation), a Generator (external action — open URL, dial number), or a Subspace action. The visual treatment is a design choice; the navigation primitive is a press handler.
+
+### `pressable: 'disabled'` without visual signal
+
+A Brick is set to `disabled` programmatically (e.g., during a pending submission) but the visual doesn't change. Users tap and nothing happens — looks broken.
+
+**Fix**: pair `pressable: 'disabled'` with a Switch that alters appearance (opacity, color, an overlay) so disabled state is visible. This is also step 3 (immediate feedback) of the journey — the user must see that their tap was received *and* declined.
+
+### Long-press misuse
+
+`delayLongPress` is real — the runtime distinguishes tap from long-press. Useful for secondary actions on a primary tile (long-press to favourite, tap to open). Misuse: hiding *primary* actions behind a long-press because there isn't room for a button. Long-press is discoverable only to users who already know it; primary actions need primary affordances.
+
+### Press feedback collapsed
+
+A press registers — the wiring works — but there is no visual change at the moment of registration (no scale-down, no opacity flash, no Switch-driven highlight). This is the most common silent UX failure: the press works, the user can't tell, so they press again. See [`user-journey.md`](user-journey.md) step 3.
+
+**Fix**: every `on_press` must pair with a visible state change at registration. A 100ms scale-down via Standby is enough; the user's eye needs to land on *something* moving.
+
+## Decision checklist when authoring a composite button
+
+For every Brick in the composite, answer:
+
+1. Does this Brick own a press chain — `on_press`, or a Switch/Animation fed by a press/focus outlet?
+2. If yes — should it own the tap, or should the wrapper own it?
+
+If two or more Bricks answer "yes" on overlapping hit areas, set the loser(s) to `pressable: 'bypass'` explicitly. If only the wrapper has a press chain, pressable-capable inner Bricks auto-bypass — `pressable: 'bypass'` is recommended for clarity but not strictly required. Non-pressable family Bricks (TextInput, Camera, Slideshow, Items, Chart, WebView, Rive) follow their own interaction model and don't auto-bypass.
+
+If any answer is "I haven't thought about it", the failure modes above are how it bites.

package/skills/bricks-ux/references/user-journey.md

@@ -0,0 +1,168 @@
+# The Universal User-Journey Spine
+
+Every interaction in a BRICKS Application — touch press, peripheral input, remote command, external trigger — passes through the same seven steps. Skip any of them and the design has a hole the user will fall into. The shape is universal across QR scan, face detection, BLE proximity, NFC tap, payment terminal, voice mic, touch tile, operator remote.
+
+This file is the spine. Anything that isn't here probably belongs in a more specific reference (transact intensification, peripheral particulars, archetype rule sets).
+
+## The seven steps
+
+### 1. Affordance — "Can I do something here?"
+
+The user must know the channel exists before discovering it by chance. A QR-scan zone with no scan-here label, a BLE-proximity threshold with no "approach to begin" hint, a touch tile that looks decorative — all fail at step 1.
+
+Affordance is the *invitation* to act. Without it, the rest of the journey is invisible.
+
+**BRICKS-native expression:**
+
+- A pressable region's visual treatment must declare "press me" — contrast, weight, a hint of motion via Standby Transition (gentle pulse), an icon. Use the runtime; don't rely on the user inferring touch from a flat Rect.
+- Peripheral channels need an instructive Brick in the line-of-sight: a scan-frame Image, a microphone glyph that lights when listening is possible, a "tap card here" overlay.
+- For ambient peripherals (BLE, camera detection), use a `valueHit` Data event on detection to *promote* the affordance — the screen invites the next step once the user is in range.
+
+**Failure modes:**
+
+- **Affordance hidden.** Pressable Brick visually indistinguishable from non-pressable. User walks past.
+- **Affordance present but ambiguous.** "Touch screen" floating with no anchor — touch *what*?
+- **Affordance promised, channel absent.** A scan frame drawn for a deployment that has no scanner.
+- **Affordance for absent capability.** Hover affordance on a no-touch panel; web-style cursor pointer on touch hardware.
+
+### 2. Instruction — "What do I do?"
+
+Once the user is invited, they need to act. The instruction must be specific enough to act on without overspecifying. Match the user's likely mental model — a payment terminal is not a QR scanner; same Canvas should not pretend otherwise.
+
+**BRICKS-native expression:**
+
+- A short directive in `RichText` near the affordance: "Scan your QR code", "Tap to start", "Hold card to reader". Bind to a Data string for multilingual.
+- Iconography or animation that demonstrates the action (a hand reaching toward the reader, a card moving toward the panel). One demo, not a five-step diagram.
+- For unfamiliar peripherals (NFC, voice for new users), include a one-shot tutorial on first entry — a separate Canvas, not a permanent overlay.
+
+**Failure modes:**
+
+- **Instruction missing.** Affordance present, action unclear. Common with NFC and voice — users don't know they need to *speak* or *tap*.
+- **Instruction overspecified.** Five steps for a one-step action.
+- **Instruction in wrong language** for the actual user — pin to deployment locale.
+- **Instruction stays after the action.** "Scan now" still on screen after the scan succeeded — confuses about whether to scan again.
+
+### 3. Immediate feedback — "Did I do it?"
+
+The instant between the user's action and the system's acknowledgement is the highest-anxiety moment in the flow. The user has *committed* — touched, scanned, tapped, spoken — and now needs proof their action registered.
+
+This is non-negotiable. A flow that skips immediate feedback has a hole the user falls through every time.
+
+**BRICKS-native expression:**
+
+- A snap-cut visual change at the moment of registration (not a fade-in — fades read as ambient, snaps read as acknowledgement). Brick scale, opacity, or color change via Switch on the input event.
+- A Standby Transition on a new Brick that enters at the moment of acknowledgement — a checkmark, a state badge, a progress indicator.
+- For audio-enabled deployments, a short auditory cue at the moment of registration. Silent is OK; ambient music is not enough.
+- If the registration takes any perceptible time (peripheral confirming, network round-trip), step 3 still fires first — the *system received* you — then step 4 takes over for the *processing* state.
+
+**Failure modes:**
+
+- **Feedback skipped, jumps to continuation.** User can't tell if their action registered or the Canvas just changed for unrelated reasons.
+- **Feedback fades in slowly.** Fade reads as ambient, not as response. Use snap on the moment of registration.
+- **Feedback on the wrong Canvas.** User taps, Canvas A doesn't react, Canvas B (the next one) loads after a beat — user assumes nothing happened and taps again.
+- **Same feedback for success and failure.** A check-mark feedback for a payment that's still processing reads as success — user walks away from a partial transaction.
+
+### 4. In-flight visibility — "Is it being handled?"
+
+When the system needs time — peripheral confirming, network round-trip, Generator awaiting response — the user must know the system is working. Silent processing reads as broken.
+
+**BRICKS-native expression:**
+
+- A clear in-flight Brick set: spinner, progress indicator, animated state badge. Use `Animation` `runType: 'loop'` here — this is a legitimate loop use (continuous attention-draw signalling activity).
+- The trigger affordance disables (`pressable: 'disabled'` or Switch-driven hide) so the user can't trigger again.
+- Time-bounded: if the in-flight state can plausibly take > 5 seconds, surface a progress estimate or a continued-activity reassurance ("Still processing — this can take up to 30 seconds"). Don't leave the user staring at an unchanging spinner past their patience threshold.
+- For peripherals: the peripheral's own state (Generator event from the device) should drive Switch transitions, not a guess at how long it'll take.
+
+**Failure modes:**
+
+- **No in-flight state at all.** Action triggered, Canvas frozen until result. User taps again; second action queues; chaos.
+- **In-flight state visually identical to idle.** No motion, no change in tone — user can't tell whether the system is working or stalled.
+- **In-flight state with no time-out.** System hangs; Canvas stays on "processing…" forever. Every in-flight state needs a Generator-driven failure path back to step 6.
+- **In-flight state allows re-trigger.** User can press again, queues duplicate work — especially bad for transact flows.
+
+### 5. Continuation — "What's next?"
+
+The action succeeded; what now? The user needs to know whether they continue here, move to a next state, walk away, or hand over to a peripheral / operator.
+
+**BRICKS-native expression:**
+
+- A Canvas change is the most common continuation — Switch on the success Data event, new Canvas with the next prompt or the result.
+- For flows that loop (slideshow, ambient signage), continuation can mean returning to attract / idle state.
+- The continuation Canvas's hero Brick(s) share id with the previous Canvas's hero — Truth #3 auto-tween carries the user across with continuity, not by hard cut.
+- If continuation is "stay here, do another thing," the prompt must update — the user shouldn't have to guess that they can act again.
+
+**Failure modes:**
+
+- **Continuation ambiguous.** Success acknowledged but the user is left on a static Canvas with no next-step prompt. They wait, then walk away.
+- **Continuation surprises.** Success on Canvas A, but Canvas D loads next — the journey shifts in a way that didn't match the user's mental model.
+- **Continuation lacks closure for some users.** A receipt flow that auto-advances after 3s before the user has read the confirmation.
+
+### 6. Recovery — "What if it went wrong?"
+
+Error states are first-class designed states, not afterthoughts. The recovery path tells the user what failed, why if relevant, and how to proceed — including the option to abandon.
+
+**BRICKS-native expression:**
+
+- A dedicated error Canvas (or a clearly distinct error state on the current Canvas, Switch-revealed). Not a tiny red text in a corner.
+- The error declares the cause in user-language: "Card declined" not "ERR_TRANSACTION_REJECTED". "Couldn't read the code — try moving closer" not "Scanner timeout".
+- The recovery offers a path — retry, alternate method, get help, abandon — never just states the failure.
+- Form input retained across error — user shouldn't re-type after a validation fail.
+- For peripherals, distinguish *user error* (action failed; retry) from *system error* (device unavailable; not the user's fault) from *abandonment* (timeout; resume or restart).
+
+**Failure modes:**
+
+- **Recovery as dead-end.** "Error. Please try again." with no path forward.
+- **Recovery erases progress.** User restarts from step 1 of a 5-step flow after a single-step failure.
+- **Recovery in unrelated language.** Technical error codes shown to end users.
+- **Recovery missing for the silent failures.** Peripheral disconnected mid-flow with no recovery path — user assumed it'd just work.
+- **Same recovery for all error types.** User can't distinguish "try again" from "the system is broken, walk away" from "you need to do something different".
+
+### 7. Closure — "When can I leave?"
+
+Especially in transact flows, the *past-the-point-of-no-return* moment must be explicit. The success state must declare the action complete in a way the user trusts before they walk away.
+
+**BRICKS-native expression:**
+
+- A success Canvas with weight — a confident headline, a check or stamp graphic, a printed-receipt analogue if applicable. Not a transient toast.
+- The success Canvas must hold visibly for enough time that a careful user reads it (5–10 seconds for a transact closure; 2–3 for routine completion) before auto-advancing or resetting to idle.
+- For ongoing actions (registered, will-be-notified), the closure must clarify the future: "You'll receive a confirmation by email" or "We'll call you when ready" with the expected wait clearly stated.
+- For closures that have a physical artifact (receipt, ticket, badge), the artifact's presence is part of the closure — the Canvas waits for the printer event before declaring done.
+
+**Failure modes:**
+
+- **Closure transient.** Success shown for 800ms, auto-advances to idle. User mid-blink, never saw confirmation.
+- **Closure ambiguous with in-flight.** Success badge in the same visual tone as the processing spinner — user uncertain whether they're done.
+- **Closure missing for irreversible action.** Payment confirmed by terminal but no on-screen success — user walks away unsure, doubles up via a second tap.
+- **Closure carries forward as a state the user can edit.** Success Canvas with input fields the user can change — implies the action isn't really committed.
+
+## When the seven steps compress
+
+Some interactions naturally collapse steps. Don't pad; collapse with intention.
+
+- **Glance-archetype loops** (signage, attractor): the user doesn't act. Step 1 (affordance) collapses to "attention", step 5 (continuation) to "loop", steps 3, 4, 6, 7 don't apply. Only 1, 2, 5 are live.
+- **Pure-monitor screens**: user doesn't act. Steps 1–4, 6, 7 collapse; the design is entirely about reading the state (see [`monitoring-screens.md`](monitoring-screens.md)).
+- **One-step transact** (NFC tap-and-go without amount confirmation): steps 1–4 fire in rapid sequence, but each still must be present — affordance, instruction, registration feedback, in-flight visibility, even if the in-flight is <1 second.
+
+Collapse means *fewer steps*, not *skipped steps*. A step you've skipped is a hole, not a compression.
+
+## When the seven steps intensify (transact)
+
+For payment / identity capture / safety-critical actions, the journey tightens:
+
+- **Step 2 (instruction) gets a confirmation step bolted on** — "You're about to charge $42.50. Confirm?" — a designed checkpoint Canvas before commit.
+- **Step 4 (in-flight visibility) cannot be skipped or hurried** — even a sub-second processing moment needs explicit visual presence. The cost of a missed in-flight is the user double-tapping a $42 charge.
+- **Step 6 (recovery) gets explicit categories** — card declined / network error / user cancelled / timeout — each with its own recovery path. A generic "Try again" is insufficient.
+- **Step 7 (closure) gets longer hold time + receipt** — the user must trust the transaction completed; cheap closures invite dispute.
+
+This intensification is enough that transact flows often deserve a separate design pass; for v1 of this skill, treat it as the loudest application of the seven-step spine.
+
+## How to use this file
+
+When designing any interaction:
+
+1. **Open the seven steps.** Walk the flow as the user would.
+2. **For each step, name** what the user sees / what the system does / how feedback manifests / what fails. If you cannot fill all four for a step, that step is unfinished.
+3. **Check the failure modes per step.** Each is a thing agents commonly skip. Caught here is cheap.
+4. **Express in BRICKS primitives.** Each step has expression notes — which Brick families, which architecture truths (Truth #3 hero auto-tween across the journey; Truth #5 Generator async; Truth #7 Standby Transition for feedback).
+
+The spine doesn't tell you what to design. It tells you which holes to *not have*.

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

@@ -0,0 +1,256 @@
+# UX Critique
+
+Verification proves the flow *runs*. UX critique proves the flow is *usable*. Both are required before declaring done; neither substitutes for the other.
+
+UX critique runs in parallel with visual-design critique (`bricks-design/design-critique.md`). A Canvas can fail one and pass the other; both block ship.
+
+This file is tiered. The same UX problem (e.g., closure missing) is **CRITICAL** on a payment kiosk and **MEDIUM** on a museum signage loop. Critique fails ship when CRITICAL or HIGH items go unaddressed in their applicable tiers.
+
+## How to run the pass
+
+1. **Open the journey.** Walk every interaction step-by-step using `user-journey.md` as the spine.
+2. **For each Canvas / Brick group, classify by deployment risk** (table below). The classification determines which tier of checks apply.
+3. **Run the checks in the applicable tier(s).** CRITICAL items always run; HIGH applies broadly; MEDIUM and LOW depend on classification.
+4. **Fix every CRITICAL miss and every HIGH miss.** Surface MEDIUM and LOW misses in the trade-off note if not addressed.
+5. **Re-verify after fixes.** Don't accumulate fix debt.
+
+## Risk classification by deployment shape
+
+| Deployment shape | Risk profile | Tier weighting |
+|---|---|---|
+| Payment / identity capture / safety-critical | CRITICAL-dense — every transact discipline must pass | CRITICAL + HIGH + MEDIUM all apply |
+| Self-service interactive (ordering, check-in, configuration) | HIGH-dense — journey completeness, idle reset, recovery paths | CRITICAL + HIGH apply; MEDIUM where relevant |
+| Monitoring / dashboard / control room | HIGH-dense — alarm hierarchy, stale-data trust, calm/detect/demand | CRITICAL + HIGH apply for alarm states |
+| Browse / wayfinding / menu board | MEDIUM-dense — legibility, comparison clarity, sparse states | HIGH legibility, MEDIUM elsewhere |
+| Glanceable signage / dwell / ambient loop | LOW-dense — main checks are legibility and rhythm | HIGH legibility, LOW elsewhere |
+
+## CRITICAL — blocks ship
+
+Failure on any of these is sufficient grounds to declare the work mid-iteration.
+
+### CR-1. The user-journey spine is whole
+
+Every interaction must have all seven steps present (or deliberately compressed; see `user-journey.md` § "When the seven steps compress"). Most-common holes:
+
+- **Immediate feedback missing** (step 3). User taps, nothing visible, taps again.
+- **In-flight visibility missing** (step 4). Action triggered, screen frozen, user re-triggers.
+- **Recovery as dead-end** (step 6). Error Canvas with no path forward.
+- **Closure ambiguous or missing** (step 7). Success state transient or unclear.
+
+**Must Have:** every interaction has a designed and verified affordance, instruction, feedback, in-flight state, continuation, recovery, closure — or deliberate documented collapse.
+**Anti-Pattern:** journey skipping any step on the assumption "it's fast enough not to need".
+
+### CR-2. Transact has its intensification
+
+For payment / identity / safety-critical flows, the seven steps must be tightened (`user-journey.md` § "When the seven steps intensify"):
+
+- Confirmation step before commit.
+- In-flight visibility non-skippable.
+- Recovery categorised (declined / network / cancelled / timeout).
+- Closure with weight and hold time.
+
+**Must Have:** transact closure holds ≥ 5 seconds, success unmistakable, peripheral state visible.
+**Anti-Pattern:** "Process payment in one tap" with no confirmation; closure that auto-advances in < 2s.
+
+### CR-3. Monitoring has demand discipline
+
+For dashboards / monitor screens with alarm capability:
+
+- Calm / detect / demand are three distinct designed states.
+- Demand state stands out unambiguously; not a slight colour change.
+- Multiple concurrent demand states have priority ordering already designed.
+- Stale-data is visibly declared per source.
+- Color is never the only encoding of severity.
+
+**Must Have:** alarm-state preview captured and reviewed; squint-test passes (alarm visible from peripheral vision); monochrome preview still distinguishes severity tiers.
+**Anti-Pattern:** alarm styled identically to detect-state; "stale" indicator at 8pt in corner; severity by colour alone.
+
+### CR-4. Accessibility floors met for the audience
+
+The seven accessibility disciplines (`accessibility.md`) apply at deployment-relative floors. CRITICAL when the audience includes:
+
+- Reduced-vision users (contrast, scale, color-not-only).
+- Reduced-motor users (touch targets, no precise gestures, no time-pressure auto-cancels).
+- Sensitive-to-motion users (reduced-motion path available).
+- Multilingual audience (strings via Data; type scale accommodates longest translation).
+
+**Must Have:** contrast verified under deployment-actual lighting; touch targets verified with real-finger / real-hardware testing; severity / status encoded by shape + color + label.
+**Anti-Pattern:** WCAG-compliance-on-desktop-monitor as the audit (deployment is sunlit signage at 4m); time-pressure UI on a venue that includes slow / hesitant users.
+
+### CR-5. Idle reset is clean
+
+For self-service interactive deployments:
+
+- Idle timeout exists and is calibrated to the use pattern.
+- Idle reset clears flow state — no half-built order persists; no name on screen; no half-confirmed action.
+- Reset returns to a designed idle / attractor state, not to "whatever Canvas was loaded".
+
+**Must Have:** verified idle reset behaviour via Automation or live test; verified that no leaked state persists to next session.
+**Anti-Pattern:** idle = last interact Canvas; idle that requires operator to manually reset.
+
+## HIGH — must fix before launch
+
+### H-1. Affordance is unambiguous
+
+Every pressable Brick declares "press me" visually — contrast, weight, motion, or icon. Affordance vocabulary is consistent across the deployment.
+
+**Must Have:** pressable tiles visually distinct from non-pressable; squint test confirms which Bricks are interactive.
+**Anti-Pattern:** identical-looking tiles where some are pressable and some aren't; pressable Bricks with no visual distinction from background.
+
+### H-2. Press feedback at registration
+
+Every `on_press` produces a visible state change at the moment of registration — scale, opacity, color, or new Brick entry via Standby Transition. Not a fade-in.
+
+**Must Have:** Brick under press visibly responds within 100ms (effectively snap, not fade).
+**Anti-Pattern:** press registers, no visible change; press relies on Canvas-change-only feedback (user perceives lag).
+
+### H-3. Flow states designed, not skipped
+
+Idle / loading / empty / error / boot / maintenance (as applicable to the deployment) are designed states, each with verified preview.
+
+**Must Have:** every applicable state's preview captured and reviewed; failure modes per state checked against `flow-states.md`.
+**Anti-Pattern:** "empty state is fine, the list is always populated" without testing the empty case; error state in 8pt corner text; boot = loading spinner.
+
+### H-4. Hero continuity across journey Canvases
+
+For multi-Canvas flows, hero Bricks share ids across Canvases — chrome (logo, progress indicator, time, back action) carries via Truth #3 auto-tween.
+
+**Must Have:** primary chrome elements identifiable in the same screen positions across the flow's Canvases.
+**Anti-Pattern:** every Canvas remounts its full Brick set; user loses spatial mental model between steps.
+
+### H-5. Error recovery has a path
+
+Every error state offers retry, alternate method, abandon, or help — never a dead-end. Different error categories get distinguishable recovery treatments.
+
+**Must Have:** each error path verified end-to-end via Automation or live test.
+**Anti-Pattern:** "Error. Please try again." with no retry mechanism; generic recovery for all error types.
+
+### H-6. Stale-data trust
+
+For monitoring / live-data screens, every dynamic source has a visibly declared staleness state or a visible "last update" relative-time indicator.
+
+**Must Have:** staleness visible in peripheral vision; stale value distinguishable from current value.
+**Anti-Pattern:** dynamic value with no age indication; "last update" in 8pt absolute timestamp.
+
+### H-7. Predictable navigation
+
+Navigation affordances (back, next, home) sit consistently across Canvases. Idle returns to the same idle Canvas every time.
+
+**Must Have:** back / next affordance positions verified across Canvases; idle reset produces identical idle Canvas every time.
+**Anti-Pattern:** back button at top-left on Canvas 2, bottom-right on Canvas 3; idle rotates such that the "anchor" element moves.
+
+## MEDIUM — impacts polish; prioritize by user impact
+
+### M-1. Instruction matches user mental model
+
+Action instructions ("Scan your code", "Tap to start", "Pay now") match the user's likely understanding; jargon avoided; language locale-matched.
+
+**Must Have:** wording reviewed for the actual audience; jargon removed.
+**Anti-Pattern:** "Initiate authentication sequence" on a public kiosk; English-only instruction on a multilingual venue.
+
+### M-2. Continuation is non-surprising
+
+The Canvas the user lands on after an action matches their expectation. Big jumps in journey context happen only with explicit transition.
+
+**Must Have:** continuation Canvas reviewed for context preservation; hero continuity in place.
+**Anti-Pattern:** success on Canvas A jumps to Canvas D mid-flow; user loses context.
+
+### M-3. Closure proportional to stakes
+
+Success closure hold time and visual weight match the action's stakes. Routine completions get brief acknowledgement; transact completions get held visible.
+
+**Must Have:** closure hold time tuned to action stakes; auto-advance only after enough time for the user to read.
+**Anti-Pattern:** 1.5s closure for a transact flow; 8s closure for a "saved to favorites" toast.
+
+### M-4. Density rhythm in browse / dwell
+
+For browse / dwell deployments, content rotation has variation in density / framing / colour rhythm across Canvases or slides. Three identical-rhythm Canvases in a row is a tell. (Cross-reference: `bricks-design/design-critique.md` density-rhythm collapse.)
+
+**Must Have:** rhythm variation across the sequence; no three identical-archetype Canvases in a row.
+**Anti-Pattern:** ten Canvases that all read as "headline + bullet list".
+
+### M-5. Audio cues calibrated (when hardware allows)
+
+If the deployment uses audio, volume / timing / time-of-day awareness is intentional.
+
+**Must Have:** audio volume / scheduling reviewed; success / alarm cues distinguishable from ambient.
+**Anti-Pattern:** constant-volume cues regardless of time; audio-only confirmation (no visual pair).
+
+### M-6. Reduced-motion path available (if relevant)
+
+For deployments in clinical / safety / motion-sensitive contexts, a reduced-motion path exists.
+
+**Must Have:** `reduceMotion` Data flag wired where applicable; verified reduced-motion preview.
+**Anti-Pattern:** continuous-motion design with no reduction path for a clinical deployment.
+
+## LOW — context-dependent
+
+### L-1. Polish on idle / attractor presence
+
+For deployments where idle dominates: idle is *inviting*, not just *running*.
+
+**Must Have for high-traffic public deployments:** attractor sequence engages from peripheral vision.
+**Anti-Pattern:** logo-only idle on a deployment whose purpose is to invite interaction.
+
+### L-2. Maintenance state designed
+
+If the deployment has scheduled downtime, a maintenance Canvas exists and distinguishes itself from error.
+
+**Must Have for deployments with maintenance windows:** maintenance Canvas with return path.
+**Anti-Pattern:** maintenance = black screen.
+
+### L-3. Empty-state composition
+
+Empty states explain the absence and suggest what populates.
+
+**Must Have:** empty state designed rather than collapsed-whitespace.
+**Anti-Pattern:** "—" or blank where content would be.
+
+## Tier-by-tier checklist (running order)
+
+Use this when running the pass:
+
+**CRITICAL (always run):**
+
+- [ ] User-journey spine whole (CR-1)
+- [ ] Transact intensified if applicable (CR-2)
+- [ ] Monitoring demand discipline if applicable (CR-3)
+- [ ] Accessibility floors met (CR-4)
+- [ ] Idle reset clean if applicable (CR-5)
+
+**HIGH (always run except for glance / dwell loops):**
+
+- [ ] Affordance unambiguous (H-1)
+- [ ] Press feedback at registration (H-2)
+- [ ] Flow states designed (H-3)
+- [ ] Hero continuity across Canvases (H-4)
+- [ ] Error recovery has a path (H-5)
+- [ ] Stale-data trust if applicable (H-6)
+- [ ] Predictable navigation (H-7)
+
+**MEDIUM (run for interact / transact / browse):**
+
+- [ ] Instruction matches mental model (M-1)
+- [ ] Continuation non-surprising (M-2)
+- [ ] Closure proportional (M-3)
+- [ ] Density rhythm (M-4)
+- [ ] Audio cues calibrated (M-5)
+- [ ] Reduced-motion path (M-6)
+
+**LOW (run for public-facing / high-dwell):**
+
+- [ ] Idle / attractor polish (L-1)
+- [ ] Maintenance state (L-2)
+- [ ] Empty-state composition (L-3)
+
+## Definition of UX done
+
+A flow is UX-done when:
+
+1. The CRITICAL tier passes — zero unaddressed CRITICAL items.
+2. The HIGH tier passes — zero unaddressed HIGH items (or surfaced as accepted trade-off with rationale).
+3. Applicable MEDIUM / LOW items either pass or are surfaced.
+4. Every state (golden path + error categories + idle + empty if relevant) has been verified via preview screenshot or Automation, and reviewed.
+5. Accessibility floors are met at the deployment-relative threshold, not at a desktop default.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.

package/tools/__tests__/_cli-error.test.ts

@@ -0,0 +1,35 @@
+import { extractCliErrorMessage } from '../_cli-error'
+
+// bricks-project's tsconfig has no @types/jest, so declare the globals this test
+// uses (mirrors tools/mcp-tools/__tests__/huggingface.test.ts).
+declare const describe: (name: string, fn: () => void) => void
+declare const it: (name: string, fn: () => void) => void
+declare const expect: (actual: unknown) => { toBe: (expected: unknown) => void }
+
+describe('extractCliErrorMessage', () => {
+  // Regression: the tools used to build this message inside the same try that
+  // wrapped JSON.parse, so the throw was caught by its own catch and replaced
+  // with the raw JSON blob. The human-readable message must survive.
+  it('extracts error.message from a JSON error body', () => {
+    const output = JSON.stringify({ error: { message: 'Conflict: config was modified' } })
+    expect(extractCliErrorMessage(output, 'Update failed')).toBe('Conflict: config was modified')
+  })
+
+  it('extracts a string error from a JSON error body', () => {
+    expect(extractCliErrorMessage('{"error":"Boom"}', 'Pull failed')).toBe('Boom')
+  })
+
+  it('returns the raw output when it is not JSON', () => {
+    expect(extractCliErrorMessage('plain text failure', 'Release failed')).toBe(
+      'plain text failure',
+    )
+  })
+
+  it('falls back to the raw output when the JSON has no error field', () => {
+    expect(extractCliErrorMessage('{"ok":true}', 'Update failed')).toBe('{"ok":true}')
+  })
+
+  it('falls back to the generic message when output is empty', () => {
+    expect(extractCliErrorMessage('', 'Update failed')).toBe('Update failed')
+  })
+})

package/tools/_cli-error.ts

@@ -0,0 +1,17 @@
+// Extract a human-readable message from a `bricks ... --json` failure payload.
+//
+// On failure the CLI prints `{ "error": { "message": "..." } }` (or the older
+// `{ "error": "..." }`) to stdout/stderr. Earlier call sites built that message
+// inside the same `try` that wrapped `JSON.parse`, so the `throw` was caught by
+// its own `catch` and replaced with the raw JSON blob — the human-readable
+// message never surfaced. Parsing here, outside any throw, avoids that trap.
+export function extractCliErrorMessage(output: string, fallback: string): string {
+  try {
+    const { error } = JSON.parse(output)
+    const message = error?.message ?? error
+    if (typeof message === 'string' && message) return message
+  } catch {
+    // output is not JSON — fall through to the raw output below
+  }
+  return output || fallback
+}

package/tools/_edits-log.ts

@@ -0,0 +1,41 @@
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const auditLogIgnoreEntry = '.bricks/edits.jsonl'
+
+// Ensure the project's .gitignore excludes the audit log. No-op when it is already
+// ignored directly or via a broader `.bricks` rule.
+const ensureAuditLogIgnored = async (projectDir: string) => {
+  const gitignorePath = path.join(projectDir, '.gitignore')
+  const content = await readFile(gitignorePath, 'utf8').catch((err: any) => {
+    if (err?.code === 'ENOENT') return ''
+    throw err
+  })
+  const ignored = content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .some((line) => line === auditLogIgnoreEntry || line === '.bricks/' || line === '.bricks')
+  if (ignored) return
+
+  const prefix = content && !content.endsWith('\n') ? '\n' : ''
+  await writeFile(
+    gitignorePath,
+    `${content}${prefix}\n# MCP entry-editing audit log\n${auditLogIgnoreEntry}\n`,
+  )
+}
+
+// Append one JSON record to `.bricks/edits.jsonl`, creating the directory and the
+// gitignore entry as needed. Shared by the source-editing tools and `compile()` so
+// every project mutation lands in the same audit log.
+export const appendEditRecord = async (projectDir: string, record: Record<string, unknown>) => {
+  const bricksDir = path.join(projectDir, '.bricks')
+  await mkdir(bricksDir, { recursive: true })
+  await ensureAuditLogIgnored(projectDir)
+  await appendFile(path.join(bricksDir, 'edits.jsonl'), `${JSON.stringify(record)}\n`)
+}
+
+// Provenance stamped on every audit record: which agent/session produced the change.
+export const editProvenance = () => ({
+  session: process.env.BRICKS_CTOR_SESSION_ID || process.env.CODEX_SESSION_ID,
+  agent: process.env.BRICKS_CTOR_AGENT_ID || process.env.USER,
+})