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

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

@@ -0,0 +1,265 @@
+# Design Languages
+
+A curated library of visual languages, each with concrete BRICKS-native execution notes. The library exists because *committing to a system* is what separates polished work from generic output — and an agent without anchors averages toward generic. These anchors give you something specific to commit to.
+
+The library does not constrain you. Pick one, blend two, or invent a new one rooted in the same discipline. What it prevents is the no-commitment middle.
+
+## Two orthogonal axes
+
+A picked direction is the combination of two independent choices:
+
+- **Interaction archetype** — *what the user does* in front of the screen (glance / browse / interact / transact / monitor / dwell). Drives the Subspace structure: Canvas count, state-machine shape, dominant Bricks. See [`when-the-brief-is-vague.md`](when-the-brief-is-vague.md).
+- **Visual language** — *what the design says*. Drives expression: type, color logic, motion vocabulary, signature moves, asset emphasis. This file.
+
+A "browse + Kenya Hara emptiness" Subspace is profoundly different from a "browse + Brutalist web" Subspace, even though the user does the same thing. Advisor mode picks 3 candidates spanning both axes.
+
+## The commitment principle — fight your averaging instinct
+
+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.
+
+- Swiss Editorial without numbered folios, hairline rules, and oversized headlines is just "generic minimal."
+- Kenya Hara without 70%+ negative space is just "a bit sparse."
+- Brutalist web with rounded corners and gradient accents is just "an unfinished page."
+
+If you find yourself softening signature moves to "make it more accessible" — stop. The signature moves are the language. Soften them and you've abandoned the language for no destination.
+
+## How to use the library in Advisor mode
+
+1. **Pick 3 directions from different schools.** Not three minimalist variants. Spread across the schools below so the user sees a real choice.
+2. **For each direction, give:**
+   - One-sentence pitch.
+   - A flagship the user is likely to recognize (designer / firm / brand / institution).
+   - 3 vibe keywords.
+   - The interaction archetypes it fits.
+   - One sentence on what it would mean concretely for this brief.
+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
+ */
+```
+
+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.
+
+---
+
+## School 1 · Structural modernism
+
+### 1. Swiss Editorial (Pentagram / Vignelli lineage)
+
+- **Pitch:** Precision, authority, editorial gravity. Type, grid, hairline rule, restraint.
+- **Flagships:** Pentagram, Vignelli's Unimark, MIT Press canon.
+- **Keywords:** structural · monochrome · grid-disciplined · quiet.
+- **Fits:** glance / browse / monitor.
+- **BRICKS execution:**
+  - Bricks: large RichText for headlines, smaller Text for body, hairline `Rect` rules (1–2 grid units tall), numbered RichText folios in a corner, `Image` bricks at controlled scale.
+  - Heroes: brand wordmark or logo, numbered folio, masthead hairline rule — same id across Canvases.
+  - Theme tokens (Data): two grounds (cream + ink), one accent reserved for callouts; single sans family declared as `ApplicationFont`.
+  - Spacing scale: `2 / 4 / 8 / 16 gu`. Grid stance: **lean** (strict alignment, generous 4–8 gu margins, body columns at typeset widths).
+  - Density rhythm: dense type Canvases broken by wide-margin breathers every 3–4 Canvases.
+  - Motion: subtle vertical Standby on entrance (`ease-out` 280ms); shared headers across canvases via same-id Bricks; no `loop` animations.
+  - Asset emphasis: real photograph or none; never decorative imagery; logo at restrained scale.
+- **Wrong for:** hospitality warmth, retail playfulness, ambient dwell loops.
+
+### 2. Bauhaus geometric (Müller-Brockmann / Karel Martens lineage)
+
+- **Pitch:** Primary, architectural, confident. Geometry as the composition itself, not decoration.
+- **Flagships:** Müller-Brockmann's Zurich Tonhalle posters, Paula Scher's Public Theater identity.
+- **Keywords:** geometric · primary-color · flat · rhythmic.
+- **Fits:** glance / dwell / monitor.
+- **BRICKS execution:**
+  - Bricks: oversized `Rect` bricks as primary anchors (circles via `borderRadius`, squares, diagonals via `rotate`), `Text` bricks rotated 90° as composition elements, no photographic imagery.
+  - Heroes: one or two large geometric anchors (circle, square, diagonal bar) that re-position and re-scale across Canvases via shared id — the geometry is *the* narrative.
+  - Theme tokens: primary RGB or fluorescent accents (`#FF3C00`, `#0019FF`, `#F5E100`) on flat black or white; tri-color palette fixed in Data.
+  - Spacing scale: `1 / 3 / 6 / 12 gu`. Grid stance: **lean** (geometric anchors snapped hard to grid).
+  - Density rhythm: high-energy geometric Canvases alternating with declarative single-shape pause Canvases.
+  - Motion: bold sweep entrances (400–500ms), shared-Brick auto-tween of geometric anchors across canvases.
+  - Asset emphasis: logo, geometric forms, type-as-image; no scene photography.
+- **Wrong for:** corporate finance, hospitality, hi-fi product UI.
+
+---
+
+## School 2 · Quiet minimalism
+
+### 3. Kenya Hara emptiness (MUJI / Shiseido editorial lineage)
+
+- **Pitch:** Quiet, meditative, reverent, deliberately un-full.
+- **Flagships:** MUJI art direction, Shiseido editorial, Hara's own book design.
+- **Keywords:** generous-whitespace · monochrome · patient · reduced.
+- **Fits:** dwell / glance.
+- **BRICKS execution:**
+  - Bricks: a single hero `Image` (real photo, never redrawn), one small `RichText` caption, lots of empty Canvas; `Slideshow` rotation slow (12–24s per item).
+  - Heroes: the single hero `Image` shifts subtly in scale/position across Canvases (same id) — the photograph is the constant; everything else is breath.
+  - Theme tokens: warm-white ground (`#F8F4ED` or similar), single warm-charcoal ink (never pure black), no accent color.
+  - Spacing scale: `8 / 24 / 48 gu`. Grid stance: **breathe** (the grid is there but mostly unused; content islands placed with precision, 70–80% empty).
+  - Density rhythm: every Canvas is low-density. Variation is in framing (top-third / bottom-third / centered isolate), not density jumps.
+  - Motion: barely perceptible Standby (300–500ms delay, slow opacity easing); no `loop` animations.
+  - Asset emphasis: photography is the work — Media Flow asset must score 9–10 on the 5-10-2-8 craft dimension; one image carries the canvas.
+- **Wrong for:** information-dense kiosks, transactional flows, dashboards.
+
+### 4. Dieter Rams industrial (Braun / Vitsœ / pre-2010 Apple)
+
+- **Pitch:** Useful, honest, restrained, quietly confident.
+- **Flagships:** Braun catalogs, pre-2010 Apple, Vitsœ.
+- **Keywords:** functional · tactile · unobtrusive · long-lasting.
+- **Fits:** glance / browse / monitor.
+- **BRICKS execution:**
+  - Bricks: product `Image` as hero, sparse `RichText` specification blocks, hairline `Rect` grids separating spec columns.
+  - Heroes: the product photograph itself — re-framed and re-scaled across Canvases via shared id; spec callouts are auxiliary.
+  - Theme tokens: monochrome grey scale + one functional accent (used only where it means something — warning, primary action).
+  - Spacing scale: `2 / 4 / 8 gu`. Grid stance: **lean** (tight, even, predictable; nothing breaks rank).
+  - Density rhythm: even and measured across Canvases — no dramatic density jumps; pacing comes from Brick weight not layout shifts.
+  - Motion: minimal — Standby with linear easing, no spring, no `loop`.
+  - Asset emphasis: hero product photography first-class; spec icons as restrained line drawings.
+- **Wrong for:** consumer entertainment, maximalist branding, hospitality warmth.
+
+---
+
+## School 3 · Editorial and narrative
+
+### 5. Magazine editorial (NY Magazine / Bloomberg Businessweek lineage)
+
+- **Pitch:** Opinionated, layered, alive. Real editorial hierarchy.
+- **Flagships:** New York Magazine, Bloomberg Businessweek, The California Sunday Magazine.
+- **Keywords:** layered · photographic · type-driven · maximalist-typography.
+- **Fits:** dwell / browse.
+- **BRICKS execution:**
+  - Bricks: oversized `RichText` display headlines (a strong serif), second sans family for body, `Image` bricks anchored to text columns, pull-quote `Text` bricks at 2× body scale, color-blocked `Rect` sidebars.
+  - Heroes: masthead chrome (publication name + date), pull-quote container, hero photograph — all reposition across Canvases via shared id, giving the layered flip-through feel.
+  - Theme tokens: photograph-driven palette, accent values pulled from the hero images themselves and bound as Data; rich supporting neutrals.
+  - Spacing scale: `1 / 2 / 4 / 8 / 16 gu` (wider scale for editorial-style overlap and pull-quote breaks).
+  - Grid stance: **lean** with deliberate overlaps — content sits on the grid but layers cross gutter lines.
+  - Density rhythm: full-bleed portrait → text-heavy spread → pull-quote → image grid → breather — rotate hard, this language *needs* density variation.
+  - Motion: rich Standby with stagger (50–100ms increments per Brick); shared chrome animates across canvases.
+  - Asset emphasis: editorial-quality photography (full-bleed, scene, portrait); custom display serif as `ApplicationFont`.
+- **Wrong for:** short-attention-span interfaces, transactional kiosks, dashboards.
+
+### 6. Risograph zine (indie print lineage)
+
+- **Pitch:** Handmade, immediate, low-fidelity on purpose, warm.
+- **Flagships:** Independent zines, Rough Trade posters, skate-culture print design.
+- **Keywords:** risograph · two-color · textured · hand-placed.
+- **Fits:** dwell / browse.
+- **BRICKS execution:**
+  - Bricks: 2–3 spot-color `Rect` grounds, slightly off-grid `Image` bricks (deliberate), `Text` in a distinctive display, halftone overlays as low-opacity `Image` bricks (texture asset in Media Flow).
+  - Heroes: a distinctive display-type wordmark or a halftone-textured shape that re-stamps in different positions across Canvases — the hero feels stamped, not placed.
+  - Theme tokens: risograph palette (flo-pink, teal, navy, mustard) — saturated, slightly imperfect overprints.
+  - Spacing scale: deliberately irregular — `1 / 5 / 13 gu` (hand-placed feel; consistent within scale but not evenly stepped).
+  - Grid stance: **break** (Bricks deliberately off-grid by 1–2 units, slight rotations, content kissing edges).
+  - Density rhythm: chunky-and-busy alternating with stark single-image Canvases — the zine flip-through feel.
+  - Motion: hand-placed feel via tiny rotations on Standby (`rotate: 1–2deg` baseline); avoid the runtime's polished auto-tween for primary entries — use `ease-linear` or even snap on Standby for some elements.
+  - Asset emphasis: spot-color illustration, halftone texture, distinctive display type.
+- **Wrong for:** enterprise, premium, anything trust-seeking.
+
+---
+
+## School 4 · Motion and the digital-native
+
+### 7. Field.io motion poetics
+
+- **Pitch:** Alive, computational, mesmerizing. Motion is the medium.
+- **Flagships:** Field.io, Active Theory, Universal Everything.
+- **Keywords:** generative · motion-first · particle · light-as-material.
+- **Fits:** dwell / monitor (high-end).
+- **BRICKS execution:**
+  - Bricks: dominant `Video` / `VideoStreaming` / `Lottie` / `Rive` / `GenerativeMedia` full-bleed; `RichText` overlays at delicate sizes with semi-transparent backgrounds.
+  - Heroes: the brand reel / generative motion piece itself, full-bleed and persistent across Canvases — only the overlaid type changes; the motion is the throughline.
+  - Theme tokens: dark indigo to electric gradient ground, or pure monochrome with one light-based accent.
+  - Spacing scale: `2 / 8 / 24 gu` (delicate gaps for overlay type, large gaps for breathing room around full-bleed motion).
+  - Grid stance: **breathe** — motion is full-bleed; UI sits on the grid but quietly.
+  - Density rhythm: every Canvas is low-density overlay on full-bleed motion; variation is in *what the motion is doing* this Canvas, not in layout density.
+  - Motion: slow continuous motion via `Animation` `runType: 'loop'` — used sparingly, only on the hero. Cross-canvas transitions use shared-Brick auto-tween of full-bleed elements.
+  - Asset emphasis: brand reel video and animated logo Lottie/Rive are first-class — preloaded via Media Flow, hash-verified, offline-safe; the canvas is *driven* by these assets.
+- **Wrong for:** content-heavy displays, purchase funnels, anything requiring careful reading.
+
+### 8. Brutalist web (Are.na / terminal lineage)
+
+- **Pitch:** Raw, direct, anti-polish, confident.
+- **Flagships:** Are.na, Bloomberg Terminal, deliberate "unstyled" indie sites.
+- **Keywords:** unstyled · monospace · text-dense · system-typography.
+- **Fits:** browse / monitor.
+- **BRICKS execution:**
+  - Bricks: system-font `Text` and `RichText` only (or IBM Plex Mono / Times New Roman as `ApplicationFont`); dense `Items` lists with templated rows; hairline `Rect` borders only; no decorative imagery.
+  - Heroes: a single persistent navigation bar or "you are here" address-style label, same id across Canvases.
+  - Theme tokens: black on white, occasional single saturated accent, almost no gradients/shadows/rounded corners.
+  - Spacing scale: `1 / 2 / 4 gu` (tight, monospaced character cell rhythm).
+  - Grid stance: **lean** but ascetic — grid used as a literal table, no decorative breathing.
+  - Density rhythm: uniformly dense — variation is in content depth, not visual density. This language earns its weight by *refusing* the density-rotation principle.
+  - Motion: snap-cuts allowed and even welcome — but only as deliberate emphasis. Most transitions are shared-Brick auto-tween of typographic chrome.
+  - Asset emphasis: type. That's it.
+- **Wrong for:** consumer retail, emotional storytelling, hospitality.
+
+---
+
+## School 5 · Expressive and experimental
+
+### 9. Sagmeister / experimental
+
+- **Pitch:** Provocative, hand-made, emotional, attention-grabbing. The concept drives every choice.
+- **Flagships:** Stefan Sagmeister, Paula Scher in expressive mode, Stefan Walz.
+- **Keywords:** expressive · hand-craft · concept-driven · theatrical.
+- **Fits:** dwell / glance (cultural / event contexts).
+- **BRICKS execution:**
+  - Bricks: anything goes, but every choice serves the concept — `Sketch` for hand-drawn elements, sourced `Image` for hand-crafted typography photographs, `Text` bricks at extreme scale shifts via `rotate` and large grid frames.
+  - Heroes: the conceptual centerpiece (a hand-crafted word, a built-physical-object photograph) re-staged dramatically across Canvases — different angle, different scale, different distance — same id.
+  - Theme tokens: saturated, often clashing pairs used deliberately. No fear of "bad taste."
+  - Spacing scale: deliberately broken — `0 / 7 / 23 gu` (the irregularity is the point; siblings still share the same set so it doesn't read as drift).
+  - Grid stance: **break** — the grid is a foil to push against, not a rule.
+  - Density rhythm: extreme oscillation between maximalist Canvases and empty-pause Canvases.
+  - Motion: theatrical — long durations (600–1000ms), dramatic easing (`easeInOutBack`, `easeInOutElastic`), deliberate "broken" timings.
+  - Asset emphasis: hand-craft photography, custom or modified type, conceptual imagery.
+- **Wrong for:** ongoing systems, B2B utility, any context demanding restraint.
+
+### 10. Y2K / futurist-retro
+
+- **Pitch:** Optimistic, technological, nostalgic-for-futures-past.
+- **Flagships:** Early-2000s tech branding, contemporary nostalgia revivals in fashion and music.
+- **Keywords:** chrome · bubble · glossy · iridescent.
+- **Fits:** dwell / interact (gaming / music / Gen Z contexts).
+- **BRICKS execution:**
+  - Bricks: chrome-treatment `Image` bricks (sourced or brand-anchored generated); pixel/bitmap font as `ApplicationFont` (Departure Mono, VT323) for HUD overlays; scan-line overlay `Rect` bricks at low opacity.
+  - Heroes: HUD frame chrome (scan-line overlay, corner brackets, status readout strip) — persistent across Canvases via shared id, the chrome *is* the throughline; content swaps inside the HUD.
+  - Theme tokens: chrome / iridescence, acid green, electric blue, hot pink. Heavy gradients but in a meant-to-be-retro way (declared as Data tokens, never default web gradients).
+  - Spacing scale: `2 / 6 / 12 gu` (HUD-style regular intervals).
+  - Grid stance: **lean** — HUDs are precise; the chrome stays orthogonal even when content goes psychedelic.
+  - Density rhythm: HUD frame is constant; inner content alternates between data-readout dense and hero-render isolate.
+  - Motion: HUD-style entrances, cursor / scanner animations via `Animation`, pseudo-CRT glow via `Rect` shadow tokens.
+  - Asset emphasis: chrome 3D renders, retro-tech imagery, bubble lettering.
+- **Wrong for:** trust-seeking finance, healthcare, enterprise.
+
+---
+
+## Combining language with archetype
+
+The picked language constrains *expression*. The picked archetype constrains *structure*. They multiply, but with constraints:
+
+| Archetype | Naturally fits | Resistant to |
+|---|---|---|
+| Glance | Swiss Editorial · Bauhaus · Kenya Hara · Brutalist web | Field.io (motion competes with glance) · Sagmeister (concept needs dwell) |
+| Browse | Magazine editorial · Risograph · Brutalist web · Dieter Rams | Field.io · Y2K (too much motion noise) |
+| Interact | Dieter Rams · Swiss Editorial · Brutalist web · Y2K (gaming) | Kenya Hara (precious quiet doesn't survive a tap) · Sagmeister (instability discourages decision) |
+| Transact | Dieter Rams · Swiss Editorial | Field.io · Sagmeister · Y2K · Risograph (trust deficit) |
+| Monitor | Swiss Editorial · Bauhaus · Brutalist web · Dieter Rams | Magazine editorial · Sagmeister (decoration distracts from data) |
+| Dwell | Field.io · Magazine editorial · Kenya Hara · Sagmeister · Y2K | (any of the above can dwell; least natural is Brutalist web) |
+
+When the user picks an awkward combination ("transact + Sagmeister"), surface the tension explicitly. Either talk them into the natural pairing, or commit hard to the awkward one as a deliberate brand statement — but don't middle-ground it into mush.
+
+## Adapting and inventing
+
+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.

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

@@ -0,0 +1,116 @@
+# Performance
+
+Second-order rules that keep a BRICKS Application fast on the actual hardware it deploys to (typically lower-spec than the developer's laptop) and resilient across watchdog reboots and offline windows.
+
+## Throttle at the Generator boundary
+
+A high-frequency source (sensor publishing at 100 Hz, MQTT firehose, LLM token stream) written directly to Data will fire `update` / `valueChange` events on every write. Every bound Brick re-renders. Every dependent DataCalc re-runs. The canvas chokes.
+
+**Throttle / aggregate inside the Generator**, not after.
+
+- For sensor / MQTT: cap the published rate in the Generator (sample to 1–10 Hz, or only emit on Δ).
+- For LLM streaming: write progressive deltas, but emit a `complete` event at the end and let downstream chains key off completion.
+- For HTTP polling: respect a backoff; don't re-emit identical payloads.
+
+If the source is upstream of you (a Generator template you can't modify), insert a buffering DataCalc that publishes to a downstream Data on a rate-limited schedule.
+
+## Bound Data history explicitly
+
+Data is not a time-series store. If a design needs "the last N values" (a chart series, recent log lines, a conversation history), keep an explicitly bounded array.
+
+- Use an `Iterator` Generator or a DataCalc that pushes new values and trims the head when length exceeds the cap.
+- Pick the cap to fit the *visible* need, not "for safety" — 60 points for a 60-second chart, not 10 000.
+- Unbounded arrays are a slow memory leak that watchdog will eventually paper over by killing the Application — and the user will see a reset they don't understand.
+
+For longer-term history, push to a backend (Remote Data Bank, GraphQL, HTTP) via a separate Generator and treat the Data side as a recent-window cache.
+
+## `persistData: true` is for survival, not state
+
+`Data.persistData: true` causes the Data value to be persisted across launcher restarts. This is the right knob for:
+
+- Last-known-good content (the most recent fetched menu, the last cached weather payload).
+- Idempotency keys generated at flow start.
+- Locale preference and other long-lived configuration.
+
+It is the *wrong* knob for transient flow state. A half-completed kiosk flow that survives a watchdog reset stuck in the middle is worse than a clean reset to Welcome. Default Path: keep flow Data ephemeral; reset on boot Canvas enter.
+
+## Boot Canvas must render in < 1 second using only cached/persisted Data
+
+The boot Canvas is what the user sees on cold start, after a watchdog reset, after every fleet-managed reboot. It must:
+
+- Render *something* immediately, with no Generator success required.
+- Read from cached / persisted Data only — no synchronous network dependencies.
+- Provide a self-recovery path (Cancel / Restart accessible from any deeper Canvas) so users stuck in a half-completed Subspace can always return.
+- Reset all transient flow Data and Subspace state on entry.
+
+**Failure mode:** boot Canvas waits for an HTTP fetch to render its content; user sees a blank screen on offline cold boot.
+
+## `renderOutOfViewport: false` for legitimate off-grid Bricks
+
+By default the runtime auto-culls Bricks fully outside the grid. For Bricks that intentionally sit partly off-grid (overflow effects, anchored at origin) the in-viewport portion still renders.
+
+If you have a Brick that is *entirely* off-grid for design reasons (a parked element that animates in via Switch / DynamicAnimation), set `renderOutOfViewport: false` to make the cull explicit and reduce per-frame cost on canvases with many such elements.
+
+For Bricks that are off-grid only momentarily during a transition, leave the default — culling mid-tween causes flicker.
+
+## Brick count discipline
+
+Every Brick on a Canvas costs render budget; off-screen-but-on-Canvas Bricks still cost something. Lists of 100 small text Bricks for a daily schedule will outrun a low-spec signage panel.
+
+- Prefer **Items** Brick (virtualized) over hand-laid lists of repeating Bricks.
+- Prefer **fewer-bigger** decorative Bricks over **many-tiny** ones for purely visual texture.
+- Composite tiles often work better as a single Slideshow / Items frame than as N hand-positioned Brick groups per Canvas.
+
+## Offline-first wrap on every networked Generator
+
+The standard wrap for any Generator that touches the network:
+
+1. **Cache layer** — read from local cache (DataBank, File Generator, persisted Data) before / instead of hitting network.
+2. **Fetch layer** — when network is up, fetch and update cache; emit `data updated` event.
+3. **Queue layer** — for writes (form submissions, payments), queue locally on offline; flush on reconnect with idempotency keys.
+4. **Status layer** — expose `network.online` and `data.lastSyncedAt` Data values for the UI to surface.
+
+Default canvases read from the cache. Live fetches happen out-of-band; their results land in cache and trigger re-render via Data events.
+
+**Failure mode:** a Generator that fetches synchronously on Canvas enter and renders blank on failure. Every networked Generator without this wrap is an outage waiting to ship.
+
+## Media in Media Flow is local-first — image/video/Lottie/Rive does NOT break offline
+
+A common misread of "offline-first" is that media-rich designs (lots of images, video loops, Lottie / Rive animations, brand reels) are dangerous for offline deployments. **They are not.** Media bound through Media Flow is **preloaded** to the device at boot (or background-synced when Media Flow content updates) and served from local storage thereafter. Once cached, the media is available with no network at all — that is the whole point of Media Flow.
+
+The mechanism:
+
+- Each Media Flow asset is referenced from the Subspace by a Data of `kind: { type: 'media-resource-image' | 'media-resource-video' | 'lottie-file-uri' | 'rive-file-uri' | ... }` with a `preload: { type: 'url', hashType, hash }` block.
+- The runtime's preload pass downloads every media asset referenced by the Application before letting the boot Canvas activate (or during a controlled progress state), and verifies integrity via the hash.
+- Subsequent renders read from the local cache; the original URL is no longer needed.
+- Cache survives watchdog restarts and reboots; `Application.runtimeCacheOptions` controls the policy.
+
+Implications for design:
+
+- **You can build heavy, image-rich, motion-heavy, video-driven Applications for fully-offline kiosks and signage.** The deployment doesn't lose anything by being offline; it loses something only if media isn't bound through Media Flow.
+- **Brick templates that consume Media Flow assets — Image, Video, Slideshow, Lottie, Rive, GenerativeMedia source bricks — are offline-safe by default**, as long as their `source` (or equivalent) binds to a Media Flow Data with `preload` metadata, not to an arbitrary external URL referenced inline.
+- **The offline-first wrap above is for Generators producing dynamic / runtime data** — current menu, train times, sensor readings, LLM responses, server-fed inventory. Not for design-time media. Don't conflate the two.
+- **Do not** drop image / video / motion bricks "to be safe for offline". The result is generic, text-only design that loses the brand and the polish for no real gain.
+
+The two failure modes to actually worry about:
+
+1. **Inline URLs that bypass Media Flow.** A Brick prop set to a literal `https://...` image URL is fetched at render time; offline = blank. Bind via Media Flow Data, not inline strings. (Truth #2 + the asset protocol enforce this structurally.)
+2. **Generators that fetch *content* synchronously**, even when the bricks displaying that content are bound through Media Flow. The content fetch is what fails, not the rendering. Wrap those Generators per the section above.
+
+When unsure: ask "is this binary baked into the Application via Media Flow, or fetched at runtime from a server?" The first is offline-safe automatically; the second needs the wrap.
+
+## DataCalc trigger discipline
+
+`triggerMode: 'auto'` reruns the calc on every input change. With multiple inputs and multiple downstream consumers, an `auto` calc can fire dozens of times per logical update.
+
+- Use `auto` only when the calc is cheap and the consumers genuinely want every result.
+- For expensive calcs (collection reductions, large object transforms), use `manual` and trigger explicitly via `PROPERTY_BANK_COMMAND` from the relevant event chain.
+- Watch for circular dependencies: A's output is B's input is A's input. Auto mode will spin.
+
+## Animation budget
+
+Standby Transitions are nearly free. Continuous `loop` animations are not.
+
+- Reserve `runType: 'loop'` for genuine attention-draws: alarm pulse, recording-active indicator, "scan in progress" hint.
+- A Canvas with 5+ looping animations on idle bricks burns frame budget for no design payoff.
+- One orchestrated canvas-enter (staggered standby reveals) creates more delight than six scattered loops.

package/skills/bricks-design/references/presentation-and-slideshow.md

@@ -0,0 +1,137 @@
+# Presentation and slideshow
+
+Anything that reads as "a sequence of states the viewer is walked through" — pitch deck, intro presentation, explainer, storyboard, training slides, demo flow, kiosk welcome loop, lobby showcase. The deliverable is a runnable Subspace, not a slide export. The frame is the Application's Canvas graph plus what moves across it.
+
+The difference between a real designed presentation and "narrated PowerPoint in a Canvas wrapper" is whether anything *persists* across slides — visually, structurally, narratively. The runtime gives this for free via Shared Brick auto-tween (Truth #3); the design discipline is to use it as a narrative principle, not just a runtime fact.
+
+## Canvas-graph shape — pick one
+
+Three viable shapes. Pick once, before placing Bricks; the choice constrains everything downstream.
+
+### Shape A — Slideshow Generator (single Canvas, slides as Data)
+
+- One Canvas, one Slideshow Brick, slides as Data list (text content, image refs, timing). Optionally a small Generator that feeds the list from a remote source.
+- Identical or near-identical layout per slide — only content varies.
+- Fits: glanceable signage loops, ambient lobby content, menu rotations, training-slide loops, anything where rhythm is regular and structure is uniform.
+- Cost: cheapest to author and maintain. Adding a slide is adding a Data row.
+- Limit: every slide has the same Brick layout. No bespoke composition per slide.
+
+### Shape B — Multi-Canvas state machine
+
+- One Canvas per slide (or per scene). Bricks per Canvas can differ; hero Bricks share ids across Canvases for auto-tween.
+- Transitions are Canvas changes — auto-advance via timed Animation, gesture via `brick_press`, remote/keyboard via on-device DevTools, Data-driven via Switch on a `currentScene` value, external trigger via MQTT / BLE Generator.
+- Fits: pitch decks with bespoke layouts per slide, narrative arcs with chapter shifts, branching demos, interactive storyboards.
+- Cost: heavier to author — each Canvas is a real composition.
+- Win: every slide is its own designed thing while heroes (logo, headline word, brand chrome) carry continuity for free.
+
+### Shape C — Hybrid
+
+- A controlling Canvas with a Slideshow Brick for a linear sub-flow (intro montage, product gallery), bracketed by full Canvases for moments of bespoke composition (cover, chapter divider, finale, branching choice).
+- Fits: presentations with a regular middle and dramatic endpoints; explainers that loop a product gallery between narrative beats.
+- Cost: medium. The boundary between the Slideshow Brick's slides and the parent Canvases is the design decision worth thinking about — heroes should persist through both.
+
+### Decision rule
+
+```
+Uniform layout, regular rhythm, content-driven?      → Shape A (Slideshow Generator)
+Bespoke layouts, narrative arc, hero continuity?     → Shape B (multi-Canvas)
+Regular middle + dramatic endpoints?                  → Shape C (hybrid)
+```
+
+If you find yourself wanting per-slide bespoke layout inside a Slideshow Brick, you've outgrown Shape A — promote to B or C.
+
+## Navigation patterns
+
+How does the viewer (or the runtime) move forward?
+
+- **Auto-advance** — an Animation drives a `slideIndex` Data forward on an interval; Switches on Canvas show/hide accordingly. Use for: signage loops, lobby content, ambient screens. Per-slide duration calibrated to the interaction archetype (glanceable: 3–5s; dwell: 8–15s; narrative read: 10–20s).
+- **Gesture** — `brick_press` on a thin left/right zone or full-Canvas `on_press`. Use for: interactive kiosks, touch-driven presentations. Make the affordance visible if the deployment is touch-capable; invisible zones on no-touch are pointless.
+- **Operator remote / keyboard** — via on-device DevTools or a companion app. Map to a `next` / `prev` action that increments `slideIndex`. Use for: pitch decks with a live presenter.
+- **External trigger** — MQTT / BLE / sensor / API Generator writes `slideIndex`. Use for: synchronized screens, event-driven storytelling, sensor-reactive displays.
+- **Data-progress-driven** — a `progress` Data crosses thresholds; Switches reveal scenes. Use for: progress meters, onboarding flows where steps are tied to actual state, not arbitrary advance.
+
+**Position memory:** if the deployment can resume (operator break, watchdog reset during a presentation), `persistData: true` on the slide-index Data. Note the trade-off — a watchdog reset half-way through a kiosk loop will resume mid-loop, which is usually wrong for ambient signage. Pick deliberately.
+
+## Visual rhythm and pacing
+
+Three Canvases with identical layout in a row is monotony. Three Canvases with wildly different layouts in a row is chaos. The work between those extremes is rhythm.
+
+### Density rotation
+
+Across consecutive Canvases, alternate density. Eight layout archetypes worth rotating through:
+
+| Archetype | Use for |
+|---|---|
+| Full-bleed image | Cover, chapter break, emotional beat |
+| Big headline + thin body | Single-point slides, declarations |
+| Two-column comparison | Before/after, A vs B, our way vs their way |
+| Data-figure feature | Stat that needs to land |
+| Pull quote | Testimonial, principle, mantra |
+| Stepped list | Process, sequence, recipe |
+| Portrait + caption | Speaker intro, customer face |
+| Negative-space breather | Reset, transition, deliberate pause |
+
+In a 10-Canvas deck, hit at least 5 different archetypes. Never three of the same archetype in a row.
+
+### Colour rhythm
+
+Mostly your declared ground, occasional inverted Canvas (dark on light or light on dark) to punctuate chapter breaks, rare full-bleed accent to mark a hero moment. Don't alternate ground every Canvas — the rhythm collapses into strobe.
+
+### Pacing tied to archetype
+
+- *Glanceable*: 3–5s per slide; viewer catches one idea per moment. Heroes minimal — one image, one headline.
+- *Dwell* (lobby, ambient): 8–15s per slide; viewer absorbs slowly. Heroes can hold the screen.
+- *Presented* (live presenter): operator-driven, but design for ~30–60s per slide; presenter elaborates the Canvas. Heroes can be subtle persistents.
+- *Narrative read* (training, explainer): 10–20s per slide; viewer reads the Canvas in full.
+
+## Hero continuity — the narrative principle
+
+This is what separates real presentation design from narrated PowerPoint.
+
+Pick **one or two hero Bricks** — typically the logo lockup, a headline word, a product silhouette, or a brand chrome element. Give them the **same id** across every Canvas they appear on. Each Canvas is then a *transformation* of the hero's state (position, scale, opacity, rotation), not a new set of elements appearing and disappearing.
+
+The runtime tweens position/size for free between Canvases when ids match (Truth #3). What the designer commits to is *which* Brick is the hero and how its journey reads across the sequence.
+
+**Pattern:** open with hero at full scale, centered. Chapter Canvases shrink/dock the hero to a corner as auxiliary content fills the Canvas. Chapter break enlarges/recentres the hero. Finale returns hero to opening scale. Heroes are the thread that makes the sequence feel like one designed thing.
+
+**Auxiliary Bricks** — content that only matters to one Canvas (one chart, one quote, one figure) — scope to that Canvas. They appear via Standby Transition and exit when the Canvas leaves. Heroes live above; auxiliaries cycle.
+
+This eliminates the failure mode where every Canvas unmounts its entire Brick set and remounts a new one. That is the visual equivalent of slide cuts; runtime expense aside, it tells the viewer the design is a slide deck pretending to be an Application.
+
+## Anti-"narrated PowerPoint" rules
+
+- **No bare Canvas changes.** Every Canvas change has a hero that persists, or a deliberate snap-cut for emphasis. Never a full-set unmount + remount as routine navigation.
+- **Standby Transitions cross-fade, not gap.** Standby entrance starts before the previous Canvas's exit completes — overlap. A blank moment between Canvases reads as the runtime hanging.
+- **Per-Canvas content scoped to the Canvas.** Heroes parented above, in the shared id pool. Auxiliaries Canvas-local.
+- **No chrome contamination.** Page counters, progress bars, chapter numbers — if you need them, render them via the runtime's standby/auto-tween of a shared chrome Brick, not by drawing them into Canvas content. Better: drop them entirely unless the audience genuinely needs to know where they are.
+- **Motion vocabulary consistent.** One easing for routine transitions, one for emphasis, one for entry. Six different easings across ten Canvases reads as random.
+
+## Subtitle Brick rules (if narration is in scene)
+
+If audio narration plays alongside the Canvas sequence:
+
+- Subtitle is a `RichText` Brick bound to a `subtitle` Data, updated by the Generator that drives narration.
+- Contrast: high enough to read against any ground used in the sequence (commit to it across all Canvases). If the chosen language requires light subtitles, hero photography must accommodate.
+- Length: max 12–15 characters per line; max 2 lines.
+- Line breaks at sentence boundaries (`。 ！ ？` for CJK, `. ! ?` for Latin), never mid-clause.
+- No full-bleed background. A subtle drop shadow or text outline (via `RichText` styling) is enough — a black bar across the bottom reads as TV captioning, not design.
+- Standby Transition: fade in 200ms before the corresponding narration phrase, fade out 200ms after. Snap-cuts on subtitles look broken.
+
+## First-viewer reaction rubric
+
+Use this as a self-check before declaring a presentation done. Predict (or directly ask, if you can) the first reaction:
+
+- *"This is narrated PowerPoint."* — Redesign. Hero architecture is missing or broken. Likely full-set unmount per Canvas. Back to Pass 1.
+- *"Things were just moving."* — Motion is present but hierarchy isn't. Heroes exist but compete with auxiliaries. Quiet down everything except the hero.
+- *"I wanted to keep watching."* — Baseline good. Pacing works, hero continuity reads. Polish from here.
+- *"I wanted to screenshot that frame."* — Memorable keyframe achieved. At least one Canvas is doing more than its job. Don't disturb it; check the surrounding Canvases match the bar.
+
+A presentation that gets ≤ first reaction has a structural problem; a presentation that gets ≥ third has a craft problem at worst. Aim for fourth on at least one Canvas in any sequence ≥ 5 Canvases.
+
+## Anti-patterns specific to presentations
+
+- **Title-slide wrapper.** A "BRICKS Presentation v1" splash before the actual cover is wasted attention. Open in the work.
+- **Decorative bullet rows.** A list with an icon per row is rarely the design. Either commit to icons that mean something or drop them.
+- **Three "key benefits" Canvases in a row, same layout.** Density rotation broken.
+- **Animation `loop` everywhere.** One looped hero motion is fine. Looped sparkle on every accent is noise.
+- **Conventional "Thank You" finale Canvas.** Either make the finale carry weight (a callback to the opening hero state, a single declarative line, a quiet pause) or end on the last meaningful Canvas. A boilerplate close undoes the work.