stream_weaver 0.3.0

data/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-09-04
+
+First published RubyGems release.
+
+### Added
+- **`streamweaver get-started` — three steps to a guided course** - `gem install stream_weaver; streamweaver install; streamweaver get-started` opens StreamWeaver University: an interactive 5-step course driven from a live canvas controller that launches and directs an agent (Claude Code or Codex) in a worker session. Premier experience on macOS + iTerm2 (auto-arranged windows, one-click step runs, automatic hand-back); degraded browser-tab path everywhere else. Course demos ship in the gem (`streamweaver university-demo <name>`); progress persists across reboots; `streamweaver university-reset` starts over.
+- **`streamweaver install`** - friendlier alias of `setup`: installs the bundled agent skills to both the Claude Code and cross-tool (`.agents/`) skill roots.
+- **`streamweaver canvas-snapshot` / `canvas-restore` / `canvas-restart`** - snapshot every live canvas session (theme + layout + content), restore them, or restart the bridge onto newly installed code without losing sessions.
+- **`streamweaver canvas-raise` / `focus-me`** - bring a canvas pane or the calling iTerm session to the front from the CLI; used by the course choreography, handy anywhere.
+- **Charts render on the live canvas bridge** - `chart type:` initialization now survives poll-driven content swaps (previously charts only rendered on a first page load).
+- **Canvas auto-scroll** - a growing doc follows the bottom when the viewer is already there (and never yanks a reader who scrolled up); full-page reshapes land at the top.
+- **Platform support matrix + canvas-read guide** - README states what is tested (macOS + iTerm2), what degrades, and what is future; `docs/canvas-read.md` documents the document-shelf workflow, with a real-world case study.
+
+
+- **Tutorial: "Build My Todos: the StreamWeaver Way"** - The narrated twin of the `streamweaver-way` skill. Where the skill *prescribes* — here are the six laws, here are the four recipes, copy them — the tutorial *narrates*: it rebuilds inline editing, scoped live search, lazy hover cards, and Russian-doll infinite scroll in the order you'd hit them building the app yourself, and every step names three things: the law it obeys, the gotcha it avoids, and the measured number where one exists (deferring a 1.5s region: 0.018s shell vs a 1.508s fragment fetch; hover cards: a 0.085s shell vs 9.151s eager; search: an 800-byte scoped morph vs a 2,123-byte whole-body swap; inline edit: an 806-byte save vs a 108,792-byte page; infinite scroll: O(1) per page vs O(n) per click). The infinite-scroll section teaches Turbo's real shape — current page inline, only the *next* page lazy — and uses the empty-shell bug a clean-room agent hit as its teaching moment: wrapping page N itself in the lazy fragment serves HTML with zero rows in it and only *looks* correct, because page 1's placeholder starts in the viewport, so the reader must `curl` the page rather than trust the screen. Ships in two forms from one outline (`examples/tutorials/tutorial_content.rb`): a `:doc`-theme StreamWeaver app at `examples/tutorials/streamweaver_way_tutorial.rb` and a markdown twin at `docs/tutorials/the-streamweaver-way.md`, regenerated by `ruby examples/tutorials/render_markdown.rb`. `spec/tutorial_twins_spec.rb` fails if the checked-in markdown drifts from the outline, so the twins can't quietly disagree. Every code sample is an extract from `examples/my_todos/`, verified by assembling them into a running four-feature app. Linked from `llms.txt`.
+- **`streamweaver-way` skill — the conventions layer, taught** - A third bundled agent skill (alongside `streamweaver-visual-companion` and `streamweaver-doc-builder`), installed by the same `streamweaver setup` / `streamweaver install-skill` command to both Claude Code's path and the `.agents/skills/` cross-tool alias. It codifies "The StreamWeaver Way" with progressive disclosure: one screen of laws up front — key by what is unique per *position* not by what the content is *about*; deferred over hand-rolled timers; lazy means visible; dev loud, prod self-heals; state your intent in DSL verbs (zero custom JavaScript is the default, not an aspiration); trilaws as design filters — then the four benchmark Turbo Frames recipes (inline editing via `form_for` + `fragment`, scoped live search, lazy hover cards, Russian-doll infinite scroll), each complete and runnable with the two or three gotchas that actually bite, then pointers to the long tail. The gotchas are the ones the parity spike paid for: `text_field ..., updates:` is silently accepted and silently ignored (an input can target only its own enclosing fragment or `#app-container`, so a field placed outside the results fragment swaps the whole container), a lazy fragment inside a tab goes *inside* a `tab` block and never beside one, a named-action button inside a deferred fragment doesn't fire, and hiding a hover card with `visibility: hidden` instead of `display: none` makes every card fetch eagerly. The infinite-scroll recipe teaches Turbo's real shape — **the page the reader is on renders inline, and only the *next* page is lazy** — and names the wrong-but-tempting alternative: wrapping page N itself in the lazy fragment serves HTML with no rows in it at all, and only looks correct because page 1's placeholder starts in the viewport, so the IntersectionObserver fires immediately. `llms.txt` gains a matching "The StreamWeaver Way" section near the top linking each law to its detailed section. Worked example set: `examples/my_todos/`.
+- **Deferred fragments — `fragment :name, defer: true`** - The Turbo `turbo_frame_tag ..., src:` equivalent: the deferred block does not run during the page render at all, so a slow region can't hold the shell hostage. The page ships immediately with a placeholder, and the fragment fetches its own content right after — with no custom JavaScript in app code, just the one option on the verb you already use. Measured on a page with one `sleep 1.5` fragment: initial GET 0.018s (was 1.5s), fragment endpoint 1.508s. `placeholder:` takes a String (rendered as text), a Proc (evaluated as DSL), or nothing (a small spinner). The auto-fetch is an `hx-trigger="load"` POST to the same signed `_sw_fragment` endpoint every in-fragment interaction already uses, so there's no new route and no new authorization path. Nesting works and chains — a deferred fragment inside another loads after its parent — though each fetch re-runs its ancestors' blocks, so nest for staging, not to split one expensive block. Two things to know: the block is skipped on the shell render, so keep action/timer registration outside it; and a *named*-action button (`action: :foo`) inside a deferred fragment does not fire (its token is minted outside the session's action manifest) — use a block button (`button('X') { |s| ... }`), which is unaffected. Static exports run every deferred block inline, since nothing will fetch them later. See `llms.txt` and `examples/deferred_fragments_demo.rb`.
+- **Lazy fragments — `fragment :name, lazy: true`** - Turbo's `loading="lazy"` for deferred fragments: the fetch waits until the fragment is *visible*, whatever made it visible — scrolled into the viewport, or a CSS rule flipping an ancestor out of `display: none`. Two guarantees follow. A CSS-hidden fragment **never** fetches while it stays hidden, which is what makes a zero-JavaScript hover card cost nothing on page load: `display: none` until `:hover`, and revealing it is what fires the fetch. And it fetches **exactly once** — the content lands in the DOM and stays, so hiding and re-showing the region doesn't refetch. Nesting gives you infinite scroll for free, in Turbo's own shape: the page the reader is on renders inline and its block ends by declaring only the *next* page as a lazy fragment, so page N+1 doesn't exist until page N has been scrolled past — no scroll handler, no page counter in state, and the served HTML still carries real rows. (Wrapping page N itself in the lazy fragment is the tempting shape and it's wrong: the block is skipped on the shell render, so nothing but a placeholder goes out.) `lazy: true` implies `defer: true`, so you only write one option. Under the hood the placeholder wrapper carries `hx-trigger="intersect once"` (htmx's `IntersectionObserver`-backed trigger, the same browser API Turbo uses) rather than `hx-trigger="load"`; htmx's other visibility trigger, `revealed`, reads `getBoundingClientRect()` and so counts a hidden element as revealed, which would fetch every hidden fragment on load. A full-container swap re-arms a lazy fragment the way it re-arms a deferred one, but lazily — off-screen when the re-render lands means it waits. See `llms.txt`, `examples/lazy_fragments_demo.rb`, and `docs/research/2026-08-22-lazy-fragments-trigger-decision.md` (which also sketches how route tabs adopt this as the deprecated `tabs ..., lazy: true` mode's successor).
+- **Route tabs — `tabs :view, url: true`** - A tab group's active index lives in a query param (`?view=2`), so a tab is bookmarkable, shareable, and back/forward-aware. Switching is pure client-side History API (`pushState`/`popstate`) — zero requests — and multiple groups compose, one param per key (`/?view=2&panel=1`). On a full GET the URL is authoritative: the param wins when present and valid, and an absent or invalid param means tab 0, *never* the session's value, so the same URL always renders the same tabs. Invalid values degrade rather than error (`?view=999`, `?view=abc`, `?view[]=` all return 200 on tab 0). Two consequences worth knowing: read `state[:view]` *below* the declaration (above it the key still holds the raw pre-authority value), and a `url: true` group can't be server-side preset — `state[:view] ||= 1` above the declaration is overwritten by URL authority. Raises at build time on reserved keys (`app_id`, `splat`, `captures`, `button_id`), duplicate `url:` keys, or `url: true` with `lazy: true`. Ignored on canvas pages (plain client tabs plus one logged warning per render pass), which have no app URL to carry the tab. See `docs/components_reference.md#route-tabs-url-true` and `examples/layout/route_tabs_demo.rb`.
+- **`canvas-read`: live file browser** - A "📁 Browse files…" link in the reader's nav rail opens a live filesystem browser inside the already-running reader — breadcrumbs, folder navigation, and shortcuts to "This repo" and "StreamWeaver (global)" — so you can open a doc saved somewhere else without restarting `canvas-read` with a new path. No index or registered locations: browsing computes fresh on every request, so it finds anything, including docs saved before this shipped. Deliberately read-only (no move/copy/delete — a plain `mv` still does that). Guarded by a new cross-origin request check (Host + `Sec-Fetch-Site`) on every `canvas-read` route, since the file browser's `/open` route evaluates the `.rb` file it's handed and that's now reachable from any tab in your browser, not just a CLI argument you typed yourself.
+- **Mermaid diagrams: expand to full screen** - Every mermaid diagram, regardless of `zoom:`, now gets an expand button that opens it in a full-viewport modal with no width constraint. The in-place `zoom: true` pan/zoom controls help but don't fix the actual problem — a wide diagram's fixed-px labels shrink proportionally to fit whatever doc column width it renders in, no matter how the layout is tuned. Expand re-hosts the already-rendered SVG at natural size with real scroll (scroll/drag to pan, Ctrl+scroll to zoom further, Escape/backdrop-click/close-button to exit). Pure client-side, no new dependency — works identically in the live canvas, `canvas-read`, and any exported doc (including `--offline`).
+- **`--offline` HTML export: mermaid diagrams render in viewers that block every external script** - `streamweaver export <file.rb> --offline` (also `?offline=1` on the reader's `GET /export`, and a second "⬇ Export HTML (offline)" nav link shown only on docs with a mermaid diagram) fetches mermaid's own library at export time and inlines it as a plain `<script>`, instead of referencing its CDN. A plain inline script is covered by a CSP's `unsafe-inline`, so the diagram renders even in a viewer (SharePoint's built-in HTML preview is the motivating case) whose CSP doesn't allowlist any external host at all — the gap the Alpine/htmx fix below couldn't close on its own, since it still referenced mermaid's CDN URL. Doesn't cover `elk: true` diagrams (ELK has no equivalent inlinable build) or any other CDN asset (Chart.js, Prism); needs network access once, at export time, not at view time.
+- **Export a canvas doc to standalone HTML** - "⬇ Export HTML" in `canvas-read`'s nav rail (every file, not just history snapshots) downloads the doc you're viewing as a single self-contained HTML file — same theme/layout, same look, no server required to view it. Same capability from the CLI: `streamweaver export <file.rb> [-o out.html] [--inline-images] [--offline]`. `--inline-images` embeds local images as base64 data URIs so the file is fully portable.
+- **`use_theme`/`use_layout` DSL directives, plus `canvas-read --theme=/--layout=`** - A canvas doc's theme now travels with it: `use_theme :doc` / `use_layout :wide` declared in the DSL (or automatically prepended when you use the "Save as doc" button on a themed canvas session) makes the doc render with that theme wherever it's later opened — `canvas-read` no longer has no way to know a saved file was meant to be `:doc` themed. `canvas-read --theme=doc --layout=wide` sets a fallback for files that declare neither. Precedence: DSL directive > CLI flag > `:default`/`:fluid`.
+- **Human-readable service-mode URLs** - `streamweaver run <file.rb>` now serves apps at slug URLs like `/apps/sales-dashboard` (derived from the app's declared name, falling back to the filename) instead of opaque hashes. The hex `/apps/:app_id` URL still resolves as a canonical fallback. Slugs that collide across different files get a numeric suffix (`-2`, `-3`, ...); re-loading the same file reuses its existing slug.
+- **`endpoint` DSL — the "never rewrite in Sinatra" escape hatch** - Register a real HTTP route (webhook receiver, JSON API, file download) directly from the app DSL: `endpoint(:get, "/api/status") { |req| { ok: true } }`. Supports `:get`/`:post`/`:put`/`:patch`/`:delete`; the block receives the raw `Rack::Request` and its return value maps to a response (`Hash` -> JSON 200, `String` -> HTML 200, `[status, headers, body]` -> passed through verbatim). Endpoints bypass StreamWeaver's state/session/CSRF machinery entirely and always lose to a colliding internal route (`/update`, `/action/*`, `/submit`, `/event/*`, `/form/*`, `/theme/*`, `/sw/*`), with a warning at registration time if that happens. Works in both standalone (`run!`) and multi-app service mode (scoped under `/apps/:app_id/...`). See `docs/endpoints.md`.
+- **`canvas-read` renders `.org` docs, not just `.rb`** - StreamWeaver-flavored org files (marked with `#+STREAMWEAVER_DSL:`) now open in the reader everywhere `.rb` docs do — file lists, the browser, `GET /open`, and rendering — via a server-side detect-then-convert path (`Org::Reader.to_dsl`), the same conversion the browser extension's sandbox has done client-side since it shipped.
+- **`canvas-read` multi-repo doc discovery with repo filter** - The reader now shows every docs root on the machine, grouped by repo and filterable, instead of only the repo it was launched in. Discovery unions two sources: a one-level scan of `$STREAMWEAVER_DOCS_SCAN_ROOTS` (default `~/work`) for `*/docs/streamweaver_canvas`, and an append-only registry at `~/.streamweaver/docs_roots.log` written automatically by "Save as doc" and by `canvas-read <explicit path>` — visiting a doc once backfills its repo, so there is no registration command. Deleted or moved repos drop off on read.
+- **iTerm split-pane install hint** - When `streamweaver panel` falls back to the system browser because the optional `iterm2_ruby` gem isn't installed (but you ARE in iTerm2 on macOS), the CLI now prints a one-line `gem install iterm2_ruby` tip so the split-pane perk is discoverable.
+- **`bin/smoke` — executable UAT smoke test** - Freezes a manual UAT battery into a repeatable script: boots a fixture app in both standalone (`run!`) and multi-app service (`streamweaver serve`) mode on ephemeral ports and drives it over real HTTP, checking the `endpoint` DSL, the reserved-path boot warning, slug/hex `/apps/:id` resolution, endpoint dispatch scoping, and slug collision/reuse. Prints one check/x check line per assertion plus a final summary; exits nonzero on any failure. Wired into CI as the `smoke` job. See `docs/testing.md`.
+
+- **`strict_ids` as a global setting, and it degrades in production** - `StreamWeaver.strict_ids = true` (or `SW_STRICT_IDS=1`) opts every app into strict interactive-id checking without threading `strict_ids:` through each `App.new`; an explicit `strict_ids:` still wins. A strict violation now raises in development and test but only warns when `RACK_ENV=production` — a live page shouldn't 500 over an id the framework already auto-disambiguated. Ids stay unique either way. Documented in `llms.txt` under "Interactive IDs and keying".
+- **Feed/canvas-pushed buttons get the same id guarantees as app buttons** - `DisplayDSL#button` (the `FeedBuilder` path behind `feed`, `streamer`, and `canvas-push`) previously had no auto-disambiguation, no `key:`, and no scalar-key validation, so same-label buttons pushed in a loop shared one id. It now shares the App's identity helpers: `key:` for content-stable ids, verbatim `id:`, occurrence-based auto-disambiguation, and `ArgumentError` on a non-scalar key.
+
+### Changed
+- **`button id:` is now a verbatim id override, and outranks `key:`** - Previously `id:` was an alias for `key:` (hashed into the derived id, and *lost* to `key:` when both were passed). It now sets the emitted id directly — `button "Delete", id: "row-7"` renders `id="btn_delete_row-7"` — which is what you want when SSE pushes, CSS, or tests target the element by selector. Precedence is `id:` > `key:` > auto-derivation from label + block source location. Existing `id:` callers keep working (dispatch has always used the emitted id); only the *shape* of that id changes, from an MD5 hash to your literal value.
+- **`tabs lazy: true` is deprecated** - The POST-morph lazy mode now warns once per process, naming route tabs (`url: true`) as the direction and a future lazy route-tab mode as its replacement. Lazy tabs fetch the newly-active panel with an `hx-post` morph that canvas has no route for, so inactive lazy panels on a canvas page can never receive content (`stream_weaver-pkh`). The warning is the only change — the mode behaves exactly as before, and a compat spec locks that (active-only panel evaluation, the placeholder comment for inactive panels, and the full `hx-post`/`hx-include`/`hx-vals`/`hx-target`/`hx-swap` attribute set).
+- **Built-in tutorial (`streamweaver tutorial`) revamped for the last ~6 months of features** - Refreshed the Themes and Layout/Cards lessons (`:doc` theme, `:sketch` preset, `theme_switcher`/`theme_toggle` auto dark mode, `card_header` `badge:`/`meta:`) and added six new lessons: The Four Modes (standalone/agentic/service/canvas-panel orientation), Navigation (`navbar`/`nav_item`/`link_to` + `route_by`/`route_with`), Resource DSL, Endpoints (the tutorial now registers and self-demonstrates a real `GET /tutorial/api/hello` endpoint), Service Mode, and Canvas/Panel. Also fixed an invalid-Ruby one-liner in the Resource DSL quick-start example (`docs/resource-dsl.md`).
+
+### Fixed
+- **`route_with`: a `/now`-style dedicated view left open in one tab no longer poisons every sibling tab's clicks** - Session state is one hash per browser (one cookie), not per tab, but `route_with`'s special-view flags were only ever reset by `parser` on a real GET — every POST (`/update`, `/action/:button_id`, `/event/:key`, `/form/:form_name`, and any future POST route) only read them via `builder`. So a tab that navigated to a dedicated view (e.g. `/now`) kept that flag true in the shared session forever, and any OTHER tab's next click inherited it and got pushed there too — even a tab that never touched that view. Fixed by re-running `parser` against the requesting tab's own on-screen URL (htmx already sends this as `HX-Current-URL` on every request) before dispatching any POST, wired as a `before` filter (`server.rb`) / path-scoped `before '/apps/:app_id/*'` filter (`service.rb`, mount-prefix aware so a stale URL for a different mounted app is never misapplied) rather than a per-route call, so a future POST route can't be added without the fix. A raw non-htmx POST has no such header and is left exactly as before. Found live in a downstream app's dashboard from real multi-tab usage. See `docs/routing.md` "Pitfall 3 — one session, many tabs".
+- **A design deck no longer confirms a choice the server never got** - Clicking a deck option checked the card — `.sw-deck-option--selected` plus `aria-checked="true"`, and the checkmark taken off whichever sibling really was selected — and *then* fired a `POST /deck/select` whose response it never looked at. Only `server.rb` mounts the `/deck/*` routes and the deck's JS posts to them by absolute path, so on the canvas bridge, in `canvas-read`, under `streamweaver serve`, and in an exported file that call 404s or never lands at all — and the deck sat there showing a decision nobody recorded. Selection, notes, final notes, Submit, generate-more, and the model selector's per-model click are now all gated on the response — the card is marked only once the server has the choice, with `aria-busy` covering the round trip so the click is still acknowledged — and any deck call that fails is reported to the console naming the route and the status instead of being swallowed. Where nothing serves those routes the deck now renders read-only rather than offering the dead call at all: cards carry `aria-disabled` and `title="Read-only: deck selections need the standalone deck server"`, drop out of the tab order, and the note/generate/submit controls are disabled. That covers the bridge and the reader (known from the render mode) plus exports, service-mode apps, and canvas live-push (each of which builds its own adapter and now declares `deck_server: false`, since an export and the standalone server are otherwise indistinguishable at render time). Standalone deck markup is unchanged, pinned by golden-string specs; the emitted JS is exercised for real under node.
+- **`ComponentRenderer` can render fragments** - `Components::Fragment` asks the view it renders into to track fragment scope, which only the app views implemented — so any app using `fragment` raised `NoMethodError` when rendered through `ComponentRenderer` (static HTML export, `Streamer`, `Feed`). It now tracks scope the same way the app views do.
+- **The bare `defer { ... }` verb raises instead of silently dropping its block** - It was never implemented (an empty method sitting alongside real verbs like `every` and `watch`), so content written inside it simply never appeared, with no error. It now raises and names the real verb, `fragment(:name, defer: true)`.
+- **`canvas-read` no longer renders dead interactive controls** - Buttons and radio groups in a doc opened in the reader used to render as fully live canvas controls, but the reader deliberately omits the canvas bridge's scripts — so clicking a button greyed it out and then threw `ReferenceError: sendEvent is not defined`, and a radio moved its selection for nothing. The reader now renders those controls disabled with a `title="Interactive on live canvas only"` tooltip: honest about being a preview instead of pretending to work. Live canvas rendering (where the bridge *does* define `sendEvent`) is byte-for-byte unchanged.
+- **Tab indices are clamped everywhere** - An out-of-range active tab index (a stale session value, or a group that shrank between renders) now renders tab 0 instead of matching no panel and blanking the group. Applies to plain tabs, not just route tabs.
+- **Standalone param sync no longer leaks route-owned params into state** - Standalone mode strips `app_id`, `splat`, `captures`, and `button_id` from the request params it syncs into state, matching what service mode already did. Previously a route's own plumbing could land in a state key of the same name.
+- **HTML export no longer needs htmx or an unconditional Alpine.js, and mermaid renders without either** - A static export never talks to a server, so `htmx`/`idiomorph` are dropped from every export entirely. Alpine.js now loads only when the rendered doc actually contains an `x-data` directive (checked against the rendered markup itself, not a hardcoded list of component classes, so it can't silently drift as new Alpine-using components are added). Mermaid no longer depends on Alpine at all: `sw-mermaid-zoom.js` self-initializes on `DOMContentLoaded`/`htmx:afterSwap` instead of relying on an `x-init` directive, so a mermaid-only export loads no Alpine and a mermaid diagram never again silently fails to render just because Alpine's external `<script>` didn't load in some CSP-locked-down viewer (e.g. SharePoint's built-in HTML preview). Note: mermaid's own CDN-hosted library is still an external load, so a CSP that blocks *all* external hosts (not just Alpine's) needs the `--offline` diagram-inlining flag above to actually render there.
+- **HTML export no longer silently discards every component** - `HtmlExporter` unconditionally rebuilt the app before rendering, which re-runs the block a standalone `App.new { ... }` was built from — but a canvas doc/history snapshot is `instance_eval`'d from a DSL string into a bare `App` with no block, so the rebuild re-evaluated nothing and wiped every component, exporting an empty page with none of your content. Only rebuilds when there's a block to rebuild from.
+- **`canvas-read` now renders docs the way canvas actually does** - The reader was missing the framework's theme CSS entirely (no `master_theme_css`, no cascade-layer pin) and nested its content wrapper inside an extra `<div>`, so every selector depending on `#app-container` being a direct `<body>` child was dead — `sidebar_toc` rendered as a full-width block instead of a sticky rail, and a doc's declared theme never applied. `canvas-read` now emits the same framework CSS as canvas, keeps `#app-container` a direct body child, and its own file-browser sidebar is a separate collapsible rail (collapses below ~1100px viewport width) that doesn't interfere with a doc's own `sidebar_toc`.
+- **Canvas `sidebar_toc` nav stays sticky again** - Two cascade-layer/specificity bugs caused the TOC sidebar to scroll away instead of staying pinned (desktop) and bounce to the top on every scroll-spy update (mobile). The framework's base CSS is now layer-wrapped alongside `master_theme_css`/`visual_skills_css` (previously it was left unlayered and silently outranked them), and the sidebar's `overflow: visible` override now out-specifies the `#app-container` rule it needs to beat and applies below 1000px too, not just on desktop.
+- **`date_field` now works inside `form`/`scope` blocks** - Previously `date_field` ignored `form_context`/`scope_name` and always emitted a flat top-level `name`/`x-model`, so a date picker inside a `form` or `scope` block silently landed its value outside the intended nested state instead of `state[scope][key]`. It now branches the same way `text_field` does, and also gained `on_change`/`on_blur`/`debounce` callback support and a `render_date_field` stub on `Adapter::Base`/the Opal adapter. `resource`/`form_for` `:date` fields now render a real date picker instead of a plain text field. See `docs/components_reference.md#dates`.
+- **`streamweaver serve` auto-selects a free port** - When 4567 (or the default) is busy, `serve` now increments to the next free port like standalone mode instead of crashing with EADDRINUSE; an explicit `--port` is still honored strictly
+- **`streamweaver panel` browser fallback works beyond macOS** - The fallback now uses the cross-platform `open_browser` helper (`open`/`xdg-open`/`start`) instead of macOS-only `open`
+- **Canvas history ignores empty `STREAMWEAVER_HISTORY_ROOT`** - An empty-string env var no longer redirects history writes to filesystem-root-relative paths
+- **Canvas history writes are atomic** - `History.record` claims snapshot paths with `File::EXCL`, so concurrent writers in the same second get distinct files instead of clobbering each other
+- **Loading a `.run!` app file no longer kills service mode** - `Service.load_app` evaluates app files with a `service_loading` flag set, and `run!` is now a warn-and-no-op while it's active. Previously a file ending in `end.run!` (the documented standalone pattern) started a second server inside the service process and took the whole service down on exit. Standalone `ruby app.rb` behavior is unchanged.
+
+### Fixed
+- Plain `gem install` no longer crashes on load: the Opal compiler is now an optional, lazily-required dependency (`gem install opal` only if you use `opal-build`).
+- Org export tolerates interactive components (forms save cleanly as `.org`, controls omitted with a marker; the `.rb` sibling keeps full fidelity).
+
+## [0.2.0] - 2026-07-05
+
+### Changed
+- **`iterm2_ruby` is now an optional enhancement, not a runtime dependency** - `gem install stream_weaver` no longer requires it; iTerm2 split-pane browser panes activate when the (now published) `iterm2_ruby` gem is installed (`gem install iterm2_ruby`), otherwise panel/canvas commands fall back to opening the system browser
+
+### Added
+- **Canvas theme support** - Canvas/panel sessions can now use the `:doc` theme (and any registered theme): `streamweaver panel my-session --theme=doc`. Canvas sessions default to `:default` as before; the canvas page now reuses the same theme CSS (including dark-mode variants) as full-page rendering, so the mermaid dark-mode fix also applies in canvas mode.
+- **`CardHeader` `badge:` / `meta:` options** - `card_header "Title", badge: "C1", meta: "right-aligned text"` renders a mono badge before the title and right-aligned meta text after it, for compact labeled card headers.
+- **Puma-dev support** - Run StreamWeaver apps with memorable URLs like `http://myapp.test`:
+  - Detects `PORT` environment variable (set by Puma-dev and PaaS platforms)
+  - Skips auto-browser opening when `PORT` is set for on-demand access
+  - Provides `config.ru` example in `examples/puma_dev/`
+  - See [examples/puma_dev/README.md](examples/puma_dev/README.md) for setup guide
+
+### Fixed
+- **Mermaid diagrams stayed light in dark mode** - Diagrams didn't re-render when the page switched to dark mode, and modern CSS color functions (`oklch()`, `color-mix()`) in theme tokens crashed Mermaid's color parser. Diagrams now re-render on theme change, and colors are resolved through a canvas probe so Mermaid always receives plain `rgb()`.
+- **`theme_toggle` `mode:` was a dead parameter** - `theme_toggle mode: :light` (or `:dark`) had no effect on first-page-load behavior; the page always defaulted to following OS `prefers-color-scheme` regardless of `mode:`. `AutoMode.inline_script`/`.alpine_data` now accept the component's `mode:` as the localStorage-fallback default, so `mode: :light`/`:dark` actually forces that theme until the user toggles.
+- **Puma thread pool exhaustion** - SSE streaming apps could hang when opening multiple browser tabs; increased default Puma thread pool from 5 to 16 to accommodate long-lived SSE connections
+- **Canvas-push error feedback** - DSL errors now reported to stderr with exit code 1, enabling Claude to see and fix syntax errors
+- **Tutorial checkbox syntax** - Fixed incorrect `checkbox :key, label: "text"` to correct `checkbox :key, "text"` in learn.md examples
+- **iTerm panel stability** - AppleScript keystrokes could hang or type into wrong window; now opens URL in external browser instead
+
+### Added
+- **`navbar` / `nav_item` / `link_to` components** - Cross-app navigation bar DSL. `navbar` renders a horizontal nav bar; `nav_item` renders as a bold non-clickable span when `active: true` or a link otherwise; `link_to` renders an inline anchor element.
+  ```ruby
+  navbar do
+    nav_item "Dashboard", active: true
+    nav_item "Settings", href: "/settings"
+  end
+  link_to "Docs", href: "https://example.com"
+  ```
+- **`--reset` flag** - Clear corrupted session state on any app: `ruby my_app.rb --reset`. One-shot clear on first page load, then normal operation resumes
+- **`SW_DEBUG` env var** - Request-level debug logging for troubleshooting: `SW_DEBUG=1 ruby my_app.rb`. Logs request method, path, cookie/state sizes, and SSE connection counts
+- **StatusDot `label:` option** - Display text labels below status dots:
+  ```ruby
+  status_dot status: :green, pulse: true, label: "billing.rb"
+  ```
+- **Canvas Mode CSS** - Full component styling in canvas/panel mode:
+  - Progress bars with animated stripes
+  - Spinners with rotation animation
+  - Status dots with pulse animation and labels
+  - Badges, alerts, activity items
+  - Tables with striped rows and sortable headers
+  - Collapsible sections, hstack/vstack spacing
+- **Canvas Syntax Highlighting** - Code blocks in canvas mode now have syntax highlighting via highlight.js (github theme)
+- **Canvas Charts** - Chart.js support in canvas mode for bar_chart, line_chart, etc.
+- **`git_health.sh` example** - Dynamic git repository analyzer:
+  - Scans real git history, generates custom health dashboard
+  - Charts showing commit patterns by day of week
+  - Author contribution tables with sorting
+  - Contextual recommendations based on findings
+  - Different results each run based on actual repo state
+- **Enhanced `panel_demo.sh`** - 4-step workflow showcasing canvas capabilities:
+  - Step 1: Issue selection (cards, badges, checkboxes, radio groups)
+  - Step 2: Diff preview (side-by-side columns, alerts)
+  - Step 3: Progress animation (spinner, progress bar, status dots, activity log)
+  - Step 4: Results summary (badges, alerts, sortable table, collapsibles)
+- **Canvas Mode** - IPC system for external apps to push rich UI:
+  - Persistent browser canvas for agentic CLIs to display interactive UI
+  - WebSocket + HTTP bridge for bidirectional communication
+  - `streamweaver panel SESSION` - Open canvas in iTerm2 split pane (side-by-side with terminal)
+  - `streamweaver canvas-push SESSION` - Push DSL content to canvas
+  - `streamweaver canvas-wait SESSION` - Wait for button click, return JSON (ignores radio/checkbox)
+  - `streamweaver setup` - Configure Claude Code with bash permissions and panel skill
+  - High-level Ruby helpers: `Canvas.pick(session, options)`, `Canvas.confirm(session, message)`
+  - See [docs/canvas-roadmap.md](docs/canvas-roadmap.md) for full documentation
+- **Button `id:` option** - Disambiguate buttons in loops to prevent callback collisions:
+  ```ruby
+  items.each { |i| button "Select", id: i[:name] do |s| ... end }
+  ```
+- **Templates** - Pre-built UI patterns for common interactions:
+  - `wizard` - Multi-step forms with branching (`next: {branch_on: "field_name"}`)
+  - `choices` - Quick selection from options, returns `{choice: "Selected"}`
+  - `confirm` - Yes/No decisions, returns `{confirmed: true/false}`
+  - `info` - Display messages with action buttons, returns `{action: "Clicked"}`
+  - `table` - Data display with optional row selection
+  - `code` - Code display with syntax highlighting and line numbers
+  - `diff` - Unified diff display with add/remove highlighting
+  - Usage: `streamweaver template <name> <session> '<json-config>'`
+  - See [docs/templates.md](docs/templates.md) for full documentation
+- **Dashboard Components** - Operations dashboard UI elements (best with `theme: :dark`):
+  - `status_dot` - Colored status indicators with optional pulse animation
+  - `badge` - Pill-shaped badges with variant colors (`:default`, `:danger`, `:warning`, `:success`)
+  - `stat_display` - Large value + label statistics (e.g., "42 TASKS")
+  - `type_tag` - Activity type badges (`:research`, `:task`, `:decision`, `:planning`)
+  - `pulse_indicator` - Animated system status indicators
+  - `priority_item` - Priority-colored items (`:critical`, `:high`, `:medium`, `:low`)
+  - `activity_item` - Time-stamped activity feed entries
+  - `app_shell` - Dashboard layout with main area and collapsible sidebar
+  - `expandable_card` - Cards that expand/collapse to show details
+- **Table Component Enhancements**:
+  - `markdown: true` option for clickable links in table cells
+  - Smart header inference from array of hashes (no need to specify headers)
+  - Column DSL with formatters: `column :balance, format: :currency, align: :right`
+  - Built-in formatters: `:currency`, `:date`, `:number`, `:percent`, `:boolean`
+  - Interactive features: `sortable: true`, `sticky_header: true`
+  - Styling options: `striped: true`, `bordered: true`, `hoverable: true`, `compact: true`
+- **Dark Theme** - Full dark mode with deep backgrounds, glow effects, and dashboard styling
+- **`default:` option** for `text_field`, `text_area`, and `code_editor` to set initial values
+- **Service Mode** - Single server renders multiple apps without per-app process management:
+  - `streamweaver <file.rb>` - Run app (auto-starts service if needed)
+  - `streamweaver list` - List all loaded apps with timing info
+  - `streamweaver remove <id>` - Remove a specific app
+  - `streamweaver clear` - Remove all apps
+  - `streamweaver admin` - Open admin dashboard
+  - `streamweaver status` - Show service status
+  - `streamweaver stop` - Stop background service
+  - Named sessions via `--name` flag for easier identification
+- **Admin Dashboard** - StreamWeaver app managing other StreamWeaver apps (meta!)
+  - Shows service stats (apps loaded, PID, port)
+  - Lists all apps with timing (loaded/idle duration)
+  - Open/Remove buttons for each app
+  - Clear All Apps action
+- **Multi-app routing** - Each app gets unique URL (`/apps/:app_id`)
+- **URL prefix support** in adapter for service mode routing
+- **Multi-theme system** with three built-in themes:
+  - `:default` - Warm Industrial (Source Sans 3, 17px, generous spacing)
+  - `:dashboard` - Data Dense (15px, tighter spacing, minimal accents)
+  - `:document` - Reading Mode (Crimson Pro serif, 19px, paper background)
+- **Custom theme registration** via `StreamWeaver.register_theme`
+- **Runtime theme switching** via `theme_switcher` component
+- **Theme Tweaker app** (`examples/theme_tweaker.rb`) - Visual theme editor with live preview and export
+- **`submit: false` option** for form components to disable HTMX auto-submit:
+  - `text_field :key, submit: false`
+  - `checkbox :key, "Label", submit: false`
+  - `select :key, choices, submit: false`
+  - `button "Label", submit: false` (display-only button)
+- **Adapter pattern** for rendering - `StreamWeaver::Adapter::AlpineJS` handles all framework-specific rendering
+- **New components**:
+  - **Charts** via Chart.js (CDN-loaded only when charts present):
+    - `BarChart` / `bar_chart` / `hbar_chart` - Bar charts (vertical/horizontal)
+    - `LineChart` / `line_chart` - Line charts with fill, smooth, points options
+    - `PieChart` / `pie_chart` / `doughnut_chart` - Pie and doughnut charts
+    - `StackedBarChart` / `stacked_bar_chart` - Multi-series stacked/grouped bars
+    - `sparkline` - Compact inline trends (no axes/labels)
+    - `area_chart` - Line chart with fill (shorthand)
+    - Multiple data input modes: inline hash, file+path, explicit labels/values, state-bound
+    - File loading with dot-path extraction (e.g., `"entries.-1.phases"`)
+  - `Markdown` / `md` - Full GitHub Flavored Markdown via Kramdown
+  - `Header` with `header1`-`header6` helpers for semantic headers
+  - `TextArea` for multi-line text input
+  - `RadioGroup` for single-choice radio buttons
+  - `Card` for styled content containers with `card_header`, `card_body`, `card_footer`
+  - `Collapsible` for expandable/collapsible sections
+  - `Columns` and `Column` for multi-column layouts with custom widths
+  - `Form` with `submit`/`cancel` for deferred submission forms (client-side only until submit)
+  - `ScoreTable` for color-coded metrics display
+  - `LessonText`, `Term`, `Phrase` for educational content with glossary tooltips
+  - `CheckboxGroup` with `item` for batch selection with select all/none
+  - `StatusBadge` for visual match indicators (🟢 Strong / 🟡 Maybe / 🔴 Skip)
+  - `TagButtons` for quick-select tag groups (single-select with destructive style option)
+  - `ExternalLinkButton` for buttons that open URLs in new tabs (with optional form submit)
+- **Layout components**:
+  - `VStack` for vertical stacking with spacing and dividers
+  - `HStack` for horizontal stacking with alignment and justify options
+  - `Grid` for responsive grid layouts with breakpoint columns (`[1, 2, 3]`)
+- **Navigation components**:
+  - `Tabs` with `tab` for tabbed navigation (variants: `:line`, `:enclosed`, `:soft-rounded`)
+  - `Breadcrumbs` with `crumb` for hierarchical navigation trails
+  - `Dropdown` with `trigger`, `menu`, `menu_item`, `menu_divider` for action menus
+- **Modal dialogs**:
+  - `Modal` with `modal_footer` for overlay dialogs (sizes: `:sm`, `:md`, `:lg`, `:xl`)
+  - State-driven open/close via `state[:modal_key_open]`
+- **Feedback components**:
+  - `Alert` for static feedback messages (variants: `:info`, `:success`, `:warning`, `:error`)
+  - `ToastContainer` with `show_toast`/`clear_toasts` for stacked notifications
+  - `ProgressBar` for visual progress indicators with variants and animation
+  - `Spinner` for loading indicators with sizes and labels
+- **Event callbacks**:
+  - `on_change` callback for text_field, checkbox, select
+  - `on_blur` callback for text_field, text_area
+  - `debounce:` option for text input callbacks
+- **Custom component modules** via `components:` option on `app`
+- **Layout modes** via `layout:` parameter: `:default` (900px), `:wide` (1100px), `:full` (1400px), `:fluid` (100%)
+- `default:` option for `select` component to set initial value
+- `auto_close_window:` option for `run_once!` to close browser after submit
+- Automatic "Submit to Agent" button in agentic mode
+- CSS custom properties (CSS variables) for theme customization
+- Comprehensive inline CSS with modern styling
+
+### Changed
+- `Text` component now renders literal text only (no markdown parsing)
+- Refactored component rendering to use adapter pattern for future extensibility
+- **New "Warm Industrial" theme**: Source Sans 3 font, terracotta primary color (#c2410c), 17px base font with 1.7 line-height
+
+### Fixed
+- **Canvas panel iTerm2 integration** - Panel now opens in split pane beside terminal
+- **Canvas bridge port conflicts** - Auto-finds available port instead of hardcoded 4568
+- **Canvas bridge race condition** - Waits for HTTP server health before returning URL
+- **Canvas bridge reuse** - Verifies HTTP health on existing bridge before reusing
+- **iTerm2 URL navigation** - Adds Escape keys to dismiss autocomplete before typing URL
+- **Canvas-wait event filtering** - Now filters for 'action' events by default (button clicks only), ignoring checkbox/radio changes
+- **Canvas 'Submitted' feedback** - Only shows for button clicks, not radio/checkbox changes
+- **Canvas card styling** - Cards now render with proper borders, backgrounds, and the terracotta left accent
+- **Canvas checkbox rendering** - Checkboxes wrapped in proper div with aligned label, inline markdown parsed
+- Checkbox state properly handles unchecked values
+- Agentic mode correctly outputs JSON to STDOUT after form submission
+- Select `default:` now properly initializes Alpine.js state
+- **Table markdown cells** - Use correct Phlex raw/safe pattern for markdown rendering in table cells
+- **Table data: keyword** - Support `data:` keyword argument in table DSL method for explicit data passing
+- **Tutorial session overflow** (2026-01-02) - Session cookie was exceeding 4KB limit due to `*_edited_code` keys; now filtered from session storage
+- **Tutorial button ID mismatch** (2026-01-02) - Button IDs now use stable hash from `block.source_location` instead of render-order counter, preventing action failures when conditional content changes component tree
+- **Tutorial Reset button** (2026-01-02) - Reset always renders with block for stable ID; uses flag pattern to survive session filtering
+
+## [0.1.0] - 2025-11-08
+
+### Added
+- Initial release of StreamWeaver gem
+- Core DSL for building interactive UIs with `app` helper method
+- MVP components: TextField, Button, Text, Div, Checkbox, Select
+- Sinatra-based web server with automatic port detection
+- Phlex-based HTML rendering with inline CSS
+- HTMX + Alpine.js frontend reactivity
+- Session-based state management
+- Single-file execution with `run!` method
+- Browser auto-opening (cross-platform: macOS/Linux/Windows)
+- **Agentic mode** with `run_once!` method for AI agent workflows
+- Documentation and examples
+- RSpec test suite
+
+[Unreleased]: https://github.com/fkchang/stream_weaver/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/fkchang/stream_weaver/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/fkchang/stream_weaver/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,67 @@
+# Project Instructions for AI Agents
+
+This file provides instructions and context for AI coding agents working on this project.
+
+## Work tracking authority
+
+Tyrion is authoritative for all new StreamWeaver work. Run `tyrion prime` and
+`tyrion status` at session start, and use the Tyrion skills for shaping, importing,
+claiming, implementing, gating, checkpointing, and completing stories.
+
+Beads remains readable only as a legacy backlog. Existing Beads IDs may be searched,
+updated, and closed, but never use `bd create`, `bd ready`, `bd update --claim`, or
+`bv` to create or select new work. Re-home still-relevant legacy work in Tyrion and
+record the Beads ID in the Tyrion note/evidence trail.
+
+
+## Build & Test
+
+_Add your build and test commands here_
+
+```bash
+# Example:
+# npm install
+# npm test
+```
+
+## Architecture Overview
+
+_Add a brief overview of your project architecture_
+
+## Visual Output
+
+Whenever about to show something visually — a UI mockup, diagram, dashboard, layout/design comparison, or long-form doc — use the `streamweaver-visual-companion` skill. Do NOT use the `Artifact` tool, and do NOT write a local HTML file and open/screenshot it via Chrome browser tools (claude-in-chrome, superpowers-chrome, playwright) for this purpose. StreamWeaver's canvas-push is 5-7x cheaper in tokens than the chrome route and avoids GEA session conflicts. The skill's own "Fall back to Artifact only when..." section covers the rare exceptions (StreamWeaver unavailable, or a claude.ai-hosted link that must persist/reach someone outside this repo).
+
+## Conventions & Patterns
+
+### Git Hygiene Policy
+
+This repo is destined for **open source release**. Every commit is a candidate for public history — git history cannot be sanitized after the fact without rewriting it.
+
+**Staging rules:**
+
+- NEVER use `git add -A`, `git add .`, or `git add -u`. Stage explicit paths only, and only files you created or intentionally changed for the task at hand.
+- Every staged file must be StreamWeaver-related. Personal tooling state (`.registry/`, `.serena/`, `.beads/`), build artifacts (`dist/`, `*.gem`), and session/agent scratch content stay out (most are gitignored — if you see one in `git status`, add it to `.gitignore` rather than committing it).
+- Do not commit content containing personal info: home directory paths (`/Users/...`), personal emails, employer references, real names of testers/colleagues, travel/location details. Use placeholders or relative paths.
+
+**Enforcement:**
+
+- `bin/check_git_hygiene` runs automatically from `.githooks/pre-commit`. It BLOCKS on home paths, personal email, personal-system references, secret-shaped strings, and staged files over 500KB; it WARNS on employer/tester-name references (full pattern list lives in the script itself, which is exempt from its own scan).
+- False positive? Bypass once with `SW_HYGIENE_SKIP=1 git commit ...` — never disable the hook itself.
+
+**Before the public flip (tracked in epic stream_weaver-b9g):**
+
+- Full-history scan for the block patterns (e.g. `gitleaks` or `git log -S`), docs/ cleanup (stream_weaver-wh2), and repo hygiene sweep (stream_weaver-kj0).
+- Decide the public committer identity — history currently uses a work email.
+
+<!-- BEGIN TYRION-MANAGED-BLOCK v1 sha256:bc9a54f4421ec81e87306bdadc00e7524d992aaa63e04ed655f8670b5cd1bc0f -->
+## Tyrion
+
+This repo is tracked by Tyrion, a resumability ledger for coding agents.
+
+Rules:
+- claim before code (tyrion claim-next)
+- evidence via tyrion note/check, not ad hoc
+
+Run `tyrion prime` for the live session briefing — active epic/story, next action, unmet criteria.
+<!-- END TYRION-MANAGED-BLOCK -->

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Forrest Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.