stream_weaver 0.3.0

data/docs/university/roadmap.md

@@ -0,0 +1,72 @@
+# StreamWeaver University — Roadmap of Epics
+
+Draft 2026-08-28. Input for `/tyrion-shape`. Companion: `capability-inventory.md`.
+
+## Why
+
+A coworker saw the docs + canvas demo and wants to try it. Two audiences from day one:
+
+- **Developer** — installs the gem, runs the tutorial in their own Claude Code session.
+- **Non-developer** — never installs StreamWeaver; reads org docs on gists via the Chrome extension.
+
+Real-life forcing function: this week's discussions will run on gists + org mode with both kinds of coworker.
+
+## Architecture (what changes vs what stays)
+
+| Layer | Stays the same | Varies over time |
+|---|---|---|
+| Curriculum | Courses, steps, scripts, expected canvas state, progress ledger | Number of courses |
+| Driver | "Teacher session steps the user; worker session demonstrates" | Claude Code first; Codex (needs herdr) later |
+| Surface | "Canvas beside the terminal" | iTerm split pane (`streamweaver panel`) first; herdr chromium panel; cmux tab; plain browser fallback |
+
+Rule: the University app only knows the curriculum layer. Driver and surface are two shell-outs kept in one file, swapped later without touching courses.
+
+## Trilaws constraints (hard)
+
+- **Forrest's Law** — one door: `streamweaver get-started`. It installs skills, starts the bridge, opens the surface, lands on the course list. No second command to learn.
+- **Matt's Law** — course list is the table of contents. Only Getting Started enabled; future courses listed, disabled, one line each.
+- **Gloria's Law** — progress persists (`~/.streamweaver/university/progress.yml`); resume lands on the next unfinished step; every step is re-runnable and ends in a visible canvas payoff.
+
+## Epic 1 — `university-getting-started` (this week)
+
+Stories (draft, rigor in brackets):
+
+1. **readme-extension-webstore** [trivial] — README Browser Extension section links the Chrome Web Store listing (`https://chromewebstore.google.com/detail/streamweaver-doc-viewer/odjjednfpfiagefgpcfdlelldphmpcgj`) as the primary path (extension ID is stable across updates); "load unpacked" becomes the dev path. Add a "Share a doc" recipe with the two-level framing: gist = quick collab on one doc with anyone (send gist link + extension link, no install); the level-up is committing the same `.org` to the team repo, where it renders identically in the repo browser — docs graduate from shared-once to living with the code, no format change.
+2. **install-skill-covers-all-skills** [trivial] — `gem_skills` hash in `CLI.install_skill` (cli.rb ~2056) includes `visual-plan` and `visual-recap`; printed summary matches.
+3. **get-started-door-command** [loose] — `streamweaver get-started` extends existing `setup` (cli.rb ~2095, already installs skills to the Claude and `.agents` skill roots). Premier experience is opt-OUT: checks iTerm2 + `iterm2_ruby` + Python API and, if any is missing, prints exact install steps and a loud "full experience needs iTerm2" warning; only an explicit `--degraded` / "continue anyway" proceeds without it. Also checks core (Ruby, gem, canvas bridge) and agent skills (Claude and Codex roots, warn if no agent). Premier path: opens canvas split pane, opens a worker tab running `claude` (or `codex`), pushes the course-list canvas. Degraded path (Windows/Linux/no-iTerm): browser tab + instructions to arrange a second terminal beside it.
+4. **course-list-canvas** [loose] — course listing with Getting Started enabled, others disabled with one-line blurbs; points to existing `streamweaver tutorial` as "the classic component tour (older, being refreshed)".
+5. **progress-ledger** [loose] — per-step done state in `~/.streamweaver/university/progress.yml`, resume-to-next-unfinished, "repeat step" always available.
+5b. **driver-worker-runner** [strict] — the course canvas is the driver: each step has a Run button; clicking sends the step's prompt to the worker tab via `iterm2ctl send-text` (driver adapter lives in `iterm.rb` next to the surface adapter). Deterministic, no teacher LLM (IoC phase 3). Degraded mode: canvas shows the prompt with a copy button and "paste into your second terminal". Strict because tab targeting can silently hit the wrong tab.
+6. **step-1-canvas-push** [loose] — `panel` + `canvas-push` hello card. Payoff: appears in the pane, no HTML.
+7. **step-2-dsl-reexec** [loose] — 6-line `ruby app.rb`; mental model: block re-executes per interaction.
+8. **step-3-form-modes** [loose] — same form as stateful vs blocking (`canvas-wait`/`pick`/`confirm`). Payoff: "a TUI can't do this."
+9. **step-4-growing-doc** [loose] — worker runs a script that appends sections; save-as-doc; review versions in `canvas-read`.
+10. **step-5-org-portability** [loose] — `export`/`org-export` the doc, push to a gist, open with the extension; contrast native GitHub org rendering vs extension rendering.
+11. **coworker-install-blurb** [trivial] — one paragraph + 3 commands to send to a developer coworker; one link pair (gist + extension) to send to a non-developer.
+12. **clean-room-walkthrough** [strict, gate] — fresh machine/user runs the blurb end-to-end; every step reaches its payoff; evidence in ledger.
+
+Out of scope for Epic 1: LLM teacher session (`/worker-session`), Codex as worker beyond a pickup check, cmux, herdr, `template`/`pick`/`confirm` docs beyond what step 3 needs.
+
+## Earmarked epics (titles only, flesh out when reached)
+
+- **university-teacher-worker** — orchestrator session drives a `/worker-session`; course canvas becomes the teacher's control panel (jump to step N, repeat).
+- **tutorial-refresh** — bring `streamweaver tutorial` (Glimmer-derived code/edit/render format, keep it) up to current components and capabilities; register it as a University course.
+- **university-codex-driver** — Codex as the worker; depends on a herdr chromium-panel spike (personal payoff too).
+- **university-surfaces** — cmux tab and herdr panel adapters.
+- **course-docs-deep-dive**, **course-canvas-modes**, **course-skills-and-panels** — one epic each.
+- **cli-discoverability** — `template`, `pick`, `confirm` documented or hidden from help.
+
+## Open items
+
+- Meeting transcript → `demo-ask.md`; cross-check the five steps against what actually landed with the coworker.
+- Confirm the Web Store listing is current with `extension/` on main before pointing coworkers at it.
+
+## Additions after dependency survey (2026-08-28)
+
+Source: `dependency-survey.md`.
+
+- `iterm2_ruby` already degrades gracefully (`iterm.rb:85` LoadError → `open`), so the surface tier is a report, not a gate. Only real setup step is iTerm2 → Preferences → General → Magic → Enable Python API; get-started must say so.
+- Codex skill install already exists via `~/.agents/skills` (spec-tested). Follow-up story: also mirror `~/.codex/skills/` (legacy path) or verify Codex picks up `.agents/skills` on Brett's version — **verify-codex-skill-pickup** [strict].
+- `/worker-session` chain (skill → `~/work/claude_code_history/bin/worker-session` → herdr or `iterm2ctl` → `claude`) is personal tooling, not the gem. Stays out of Epic 1; in `university-teacher-worker` it is published as a world-tier skill and get-started installs it like any other skill. Gem owns canvas/docs; skill package owns session orchestration; get-started is the installer that knows both.
+- Browser-open logic duplicated 3× (service_client.rb, cli.rb, server.rb) — earmark **dedupe-browser-open** under `cli-discoverability`.
+- No private/team/world skill packaging scheme exists yet — earmark epic **skill-packaging-tiers**.

data/docs/university/send-to-coworker.md

@@ -0,0 +1,77 @@
+# Send this to a coworker
+
+The pitch, verbatim:
+
+```bash
+gem install stream_weaver
+streamweaver install
+streamweaver get-started
+```
+
+3 steps to awesome. Full experience is macOS + iTerm2; anywhere else, `get-started`
+falls back to a browser tab automatically -- same course, no surprises.
+
+Two versions below, depending on who's getting it. Pick one and paste it as-is.
+
+## Developer version
+
+> StreamWeaver is a Ruby DSL for building interactive UIs with almost no code, and it comes with a
+> five-step "Getting Started" course that teaches it by actually running it next to your terminal.
+> The full experience puts the course in an iTerm2 window of its own and your agent in a fresh tab
+> beside your work -- set iTerm2 up first, then install the gem and run the door command.
+
+**1. Prerequisites** (macOS + iTerm2 only -- skip if you're on another OS or terminal, you'll just
+get a browser tab instead):
+
+```bash
+gem install iterm2_ruby
+```
+
+Then in iTerm2: **Settings → General → Magic → Enable Python API**.
+
+**2. Install the gem:**
+
+```bash
+gem install stream_weaver
+```
+
+**3. Run the door command:**
+
+```bash
+streamweaver get-started
+```
+
+You'll see a dependency checklist (✅/❌ per item), then, if everything's green, `=== Opening
+premier experience ===` followed by two things: a new iTerm2 tab in your current window running
+your agent CLI, and the StreamWeaver University canvas in a window of its own. The canvas is the
+control panel -- you drive the course from there; the agent tab stays clear for the agent (and for
+the demo canvas panes it opens as you work through the steps). If iTerm2 isn't set up, the canvas
+falls back to a plain browser tab instead (same course) -- pass `--degraded` to skip straight to
+that.
+
+**You're done when** the Getting Started panel shows "Start with step 1." -- click "Run step 1" and
+watch it type the first prompt into the agent tab for you.
+
+Your progress persists to disk as you go, so you can close everything and come back later -- even
+after a reboot -- and `get-started` picks up exactly where you left off. Want to start over? Click
+the quiet "Reset course" link at the bottom of the list (or run `streamweaver university-reset`).
+
+If your agent CLI has browser control -- claude-in-chrome, playwright-cli, or gstack's `/browse`
+skill -- the worker session moves faster, but it's optional: every course step verifies what it did
+with `curl` first, so none of this blocks you from finishing the course without it.
+
+## Non-developer version
+
+> The gist link below is a placeholder -- replace it with the real one before sending.
+
+> Here's a doc StreamWeaver generated, viewable two ways:
+
+| Version | Link |
+|---|---|
+| Plain (works everywhere, no install) | `<GIST LINK — replace before sending>` |
+| Rendered (sidebar nav, callouts, tables, live diagrams) | Same gist link, after installing the [StreamWeaver Doc Viewer extension](https://chromewebstore.google.com/detail/streamweaver-doc-viewer/odjjednfpfiagefgpcfdlelldphmpcgj) |
+
+The gist link already renders as readable text without the extension -- the extension just makes it
+look exactly like it did in the original canvas: sidebar navigation, callouts, cards, tables, and
+live Mermaid diagrams, all in the browser, no install beyond the one-click extension. The extension
+is Chrome/Chromium only -- other browsers just see the plain org text, which is still readable.

data/docs/university/worker-session-mining.md

@@ -0,0 +1,109 @@
+# Worker-Session Mining: StreamWeaver University Live UAT
+
+Source transcripts (read-only mining, session IDs only — full paths omitted):
+
+| Session | Date | Duration | Steps covered |
+|---|---|---|---|
+| `9fc075bb` | 2026-08-31 | ~9 min | Step 1 (hello canvas), Step 2 (counter app) |
+| `25b1a28c` | 2026-09-03 | ~1h45m (elapsed; most of the gap is between step 1 and step 2, likely the human stepping away) | Steps 1-5 (hello canvas, counter, radio_group form + canvas-wait, growing-doc, org-export + gist + extension) |
+
+Only two worker sessions in the project's transcript directory matched the course signature
+(`"Using stream_weaver, ..."` prompts). The coordinator session and several other large
+transcripts were general StreamWeaver dev work, not course UAT, and were excluded.
+
+## 1. User-customization collisions
+
+| Collision | What happened | Course impact |
+|---|---|---|
+| `gstack /browse`-only rule vs. reflex reach for Chrome MCP | In `25b1a28c`, right after starting the counter app, Claude ran `ToolSearch` for `mcp__claude-in-chrome__*` tools, got an empty result, then self-corrected: *"I need to correct course — the repo's CLAUDE.md says to use the gstack `/browse` skill for web browsing, not `mcp__claude-in-chrome__*` directly."* | One wasted tool call + a visible reasoning detour per session. Self-corrected cleanly both times, but it's a repeatable tax the course prompts could pre-empt by naming the browser tool up front. |
+| Headless-browser CLAUDE.md rule vs. "install the extension" course step | Step 5 in `25b1a28c` asks the agent to install a Chrome extension and compare rendering. Claude correctly identified that `gstack browse` is a disposable headless Chromium daemon with no access to the user's real, logged-in Chrome — so it can't install a Web Store extension or show its effect. It flagged this constraint honestly *before* attempting anything, then used `AskUserQuestion` with three options: (1) "You install it yourself (recommended)" — click the Web Store link in real Chrome, refresh, click "View rendered"; (2) "I attempt it in the headless browser anyway" — likely blocked, won't persist, but shows what happens; (3) "Skip it." | This is the biggest single collision: a course step that structurally requires a persistent, logged-in browser profile is incompatible with the project's headless-only browsing rule. The user picked "I have it installed, just open the page" (a fourth, unlisted answer), and Claude correctly explained *again* that it still can't reach the user's real Chrome from the headless daemon — it can only show the plain-GitHub view it already had. |
+| Push-hook / git-push restriction | Not triggered in either session — neither worker committed or pushed. No evidence either way from these transcripts. |
+| Skill auto-triggering | The `browse` skill's own preamble (gstack-update-check, session bookkeeping, proactive-mode check) ran automatically and correctly both times with no visible friction — this one helped, not hindered. |
+
+## 2. Browser-control dependency
+
+Every step from the counter app onward needed a browser to verify server-rendered UI (StreamWeaver's whole pitch is "no client JS," so verification means watching the DOM change after a real click). Both sessions reached for the same tool, in this order:
+
+1. Reflexive attempt at `mcp__claude-in-chrome__*` tools (session `25b1a28c` only; `9fc075bb` went straight to `/browse`, suggesting the reflex is intermittent, not universal).
+2. Self-correct (or start directly) with the gstack `browse` CLI: `goto`, `text`, `snapshot -i`, `click @ref`, `network`, `prettyscreenshot`.
+3. For the counter/radio/growing-doc steps, `browse` fully sufficed — headless is enough to click a button and read the resulting text, and it worked cleanly except for one recurring quirk (below).
+4. For the extension-install step, headless was a hard wall — no logged-in profile, no persisted extensions, no way to reach the user's real Chrome from the agent's side at all.
+
+**What a user with no browser tooling would experience**: steps 1-4 of the course would fail outright, or fall back to a much weaker "trust me, curl showed the HTML changed" verification (both sessions actually did use `curl`/`grep` on the raw HTML as a first check before touching a browser at all, so a no-browser session isn't *totally* blind — it can confirm the server round-trip via `POST .../action/... → 200` and grep the returned HTML for the expected text). Step 5's extension comparison would be entirely unreachable without the user doing it by hand — which, as this UAT showed, is true even *with* the best browser tooling available in this repo (headless), since that step needs the user's own logged-in Chrome regardless.
+
+**Recommended course phrasing**: state the browser dependency and the fallback explicitly, e.g.:
+> "This step verifies UI state by reading the rendered page. If you have `claude-in-chrome`, `playwright-cli`, or a project `/browse`-style skill configured, use it to click through and confirm the count/text visually. If none of those are available, verify via `curl <url> | grep <expected text>` before and after the action, plus `POST .../action/... → 200` in the app's own log — that's sufficient to prove the DSL block re-ran server-side, just without a screenshot."
+
+For the extension step specifically, the course should say up front: *"This step needs your own logged-in Chrome — no automated/headless browser tool can complete it, by design (Chrome blocks extension installs from automation, and a headless session has no access to your profile). Expect the agent to hand this step back to you."*
+
+## 3. Good response patterns worth institutionalizing
+
+| Pattern | Where | Why it landed well |
+|---|---|---|
+| Honest capability boundary + structured choice | `25b1a28c` step 5: named the exact constraint (headless daemon, no logged-in profile, Web Store blocks automated installs), then gave 3 concrete options with one-line tradeoffs each, rather than silently attempting and failing or silently skipping. | Textbook "surface the tradeoff, don't hide confusion" — the user could make an informed call in one turn. Worth turning into a named pattern (something like "capability-boundary AskUserQuestion") for any course step that touches a resource the agent structurally cannot reach. |
+| Mechanism-level counter explanation | Both sessions, step 2: after clicking the button, Claude didn't just report the count — it pulled the raw HTML (`hx-post="/action/btn_increment_..."`), then in `9fc075bb` explicitly ran `browse network` to show the real `POST .../action/... → 200` calls, concluding *"each click fires a real HTTP POST ... the server re-runs the app block ... no client-side JS holding the counter."* | This is exactly the pedagogical point of StreamWeaver (server-side re-execution, not client JS) proven with evidence, not asserted. The course's own step-2 prompt already asks for this ("that's the same DSL block re-running, not JavaScript") — Claude's response consistently over-delivered on it by showing the network trace unprompted. |
+| Proactive location-mismatch flag | `25b1a28c` step 4: the saved doc landed at `~/.streamweaver/canvas/doc-demo-*.rb` instead of the course's assumed `docs/streamweaver_canvas/doc-demo.rb`, because the canvas bridge process (started in an earlier session) has a different cwd. Claude flagged this immediately and precisely ("likely because the canvas bridge process ... has a different working directory than this shell") rather than silently adjusting or failing later. | Saved the *next* course step from breaking silently — step 5's prompt hard-codes the `docs/streamweaver_canvas/doc-demo.rb` path, and Claude had already told the user it wouldn't be there. |
+
+## 4. Friction/waste
+
+| Issue | Sessions | Detail |
+|---|---|---|
+| Step-2 startup failure, two different causes | Both | `9fc075bb` (Aug 31): first draft of `app.rb` had no `.run!` — bare `app "Title" do...end` only builds the app, doesn't start the server; process exited immediately with no error, requiring several minutes of `lsof`/`ps`/source-diving to find `SinatraApp.run!`. `25b1a28c` (Sep 3): first draft was missing `require 'stream_weaver'` — hit `NoMethodError: undefined method 'app'` immediately, fixed in one turn by checking `streamweaver llm` and an example file. Same course step, same 6-line-app goal, two independent trial-and-error paths — evidence the "6 lines" framing in the prompt undercounts the two lines (`require` + `.run!`) that are structurally necessary but easy to omit. |
+| Slow first-run discovery path | `9fc075bb` | Rather than checking `streamweaver llm` (which `25b1a28c` used immediately and successfully), this session dispatched an `Explore` subagent to grep the repo for the button/state DSL, then used `ScheduleWakeup` to poll it twice (90s, then 120s) before the result came back — roughly 90+ seconds of pure waiting that the Sep 3 session avoided entirely by running `streamweaver llm | grep -n -i state` directly. |
+| `browse` "ambiguous selector" on ref-based clicks | `25b1a28c`, twice | Clicking a `@ref` returned from `snapshot -i` (not a CSS selector) twice failed with "Selector matched multiple elements. Be more specific or use @refs from 'snapshot'" — once on a radio button (`@e2`), once on a modal's Save button (`@e5`, which collided with a hidden "Saving..." `<span>` sharing structure). Both times Claude recovered by falling back to a hand-written CSS class selector (`.sw-save-doc-save`) found by grepping the raw HTML — a working but manual detour that cost 2-3 extra tool calls each time. |
+| Redundant polling loops for background server startup | Both | Both sessions ran 2-3 rounds of `sleep N && cat task-output.log` waiting for the "server started" banner to flush, then fell back to `lsof`/`ps` to find the bound port because the banner never appeared in the captured output at all (output buffering, not a real failure). Worked, but ~6 tool calls per session spent on what should be a fixed, known port-discovery recipe. |
+| Gist defaulted to secret | `25b1a28c` | `gh gist create` produced a **secret** gist (gh's default) even though the course step describes opening it and sharing/comparing rendering — Claude flagged this after the fact ("let me know if you wanted it public instead") rather than asking first or defaulting to `--public`. Not wrong, but a step that explicitly plans to open the gist URL and later compare it via a public-facing browser extension probably wants `--public` by default. |
+
+## Recommended changes
+
+### Course-prompt changes
+
+- Step 2 (counter app): explicitly note the two "invisible" required lines — `require 'stream_weaver'` at the top and `.run!` chained onto the `app do...end` block — so the "6-line app" framing doesn't cost agents a debug cycle discovering both independently. Alternatively, point straight at `streamweaver llm`'s canonical counter example as the first move, before writing anything from memory.
+- Step 5 (org-export + gist + extension): split into two explicit sub-steps with different expectations — (a) org-export + gist + view plain rendering, fully agent-completable; (b) extension install + "View rendered" comparison, framed as "hand this back to the user" rather than something the agent should attempt. State the headless-browser limitation up front instead of letting the agent discover and explain it live.
+- Step 5: default `gh gist create` to `--public` in the course's own suggested command, since the step's payoff depends on opening the URL and later showing it with the extension.
+- Any step that reads back rendered state after a click: suggest verifying via the app/action HTTP log (`POST .../action/... → 200`) as a browser-optional fallback, not just as bonus evidence.
+
+### Get-started/prereq changes
+
+- State explicitly, before the course begins, which browser-automation tool the session should use and why (e.g. "this repo's CLAUDE.md restricts browsing to gstack's `/browse` skill — don't reach for `claude-in-chrome` or `playwright-cli` directly here"), so the reflexive `ToolSearch` → correction detour seen in `25b1a28c` doesn't recur per session.
+- Add a one-line callout that the extension-install step is structurally out of reach for any headless/automated browser tool (claude-in-chrome-headless included), regardless of which one is configured — it needs the user's real, logged-in browser.
+- Document the fixed port-discovery recipe (`lsof -i :4567-4620 -sTCP:LISTEN`, per the project's own memory note) as the canonical way to find a backgrounded StreamWeaver server's port, instead of leaving agents to rediscover the `sleep && cat log` → `lsof` fallback each time.
+
+### Docs changes
+
+- README/growing_doc step: note that a doc saved via the canvas "Save as doc" button lands under `~/.streamweaver/canvas/` (not `docs/streamweaver_canvas/<repo>/`) whenever the canvas bridge process was started from a different working directory than the current shell — this is exactly what broke the assumed path in the org-export step of the Sep 3 session, and the design doc (`docs/plans/canvas-doc-location...`) is already flagged as not-yet-built for the global-vs-repo toggle.
+- `streamweaver llm` reference: confirm it's positioned as the first stop for DSL syntax questions (it worked well when used) — the Aug 31 session's slower path (dispatching an Explore subagent instead) suggests it isn't yet the obvious/first instinct.
+
+## Round-5 latency + portability pass (2026-09-03)
+
+Two additional Sep-3 worker sessions matched the course signature and were not yet in this report. `f53afb90` (21:27-22:05 UTC, ~38 min) ran the full redesigned 5-step course end to end and is the primary source below. `5cf4fbb1` (20:36-20:45, ~9 min) is an earlier, isolated run of just the dashboard-push step — fast and clean, no drag worth noting. A third large file, `bc7f531e`, was excluded: it spans Aug 11-Sep 2 and is general dev work, not a course run.
+
+### Latency ledger (`f53afb90`)
+
+| Step | Prompt arrival | First payoff | Elapsed (agent-active) | Notable drag |
+|---|---|---|---|---|
+| 1. Dashboard (3 pushes) | 21:27:58 | 21:30:54 | ~3 min | none — clean |
+| 2. Counter app | 21:35:12 | 21:37:52 | ~2.7 min | none — clean |
+| 3. Decision form (standalone + canvas + canvas-wait) | 21:47:34 | 21:57:17 | ~9.7 min | see below |
+| 4. Growing doc | 21:57:47 | 22:01:00 | ~3.2 min | none — clean |
+| 5. Org-export + gist | 22:04:29 | 22:05:55 | ~1.5 min | none — clean |
+
+### Top time sinks
+
+1. **`canvas-wait` foreground block + background promotion (~3.5 min, step 3)**: the session ran `canvas-wait decision` in the foreground, hit the harness's 120s foreground-block ceiling, got silently demoted to a background task, then had to wait for a `task-notification` and poll for the result before it could read the submitted JSON (21:53:44 to 21:57:17). This is the single largest agent-side sink found in this pass — a form-submission confirmation that should read back in a few seconds cost 3.5 minutes of wall clock, all spent waiting on the harness's own polling/promotion mechanics, not on the app or the model.
+2. **Step-to-step human/driver advance gaps (~4-10 min each)**: gaps of ~4.3 min (step 1→2) and ~9.7 min (step 2→3) between the agent finishing a step and the next step-prompt arriving. Confirmed by an `away_summary` system event at 21:40:55 stating the session was idle, "waiting for you to click it, then say so" — this is pacing/human latency, not agent drag, and matches the same pattern already noted for `25b1a28c` in the original report.
+3. **Doc-save location re-discovery (~10s, step 5)**: the session had to re-derive that the saved org file landed under `~/.streamweaver/canvas/` instead of the course's assumed `docs/streamweaver_canvas/` path — same known issue as the prior round, but resolved in one quick check this time rather than costing a debug cycle.
+
+### Env-portability risks
+
+| Risk | Detail |
+|---|---|
+| Hardcoded personal skill path | Every `browse` invocation ran `B="~/.claude/skills/gstack/browse/dist/browse"` directly via Bash — a personal global skill-install path that would not exist on a coworker's machine even with this repo checked out fresh. |
+| `gh` CLI auth dependency | Step 5 (gist) hard-requires `gh auth status` to already show an authenticated session with gist scope, with no fallback path or check-first framing if it's missing or unauthenticated. |
+| Dynamically-discovered bridge port baked into commands | The bridge bound port 4700 this run; once discovered, curl calls hardcoded that port rather than resolving it per call — fine within one session, but any copy-pasted command from a transcript or doc breaks on a different run/machine where the port differs (consistent with the project's own port-auto-detection memory note). |
+
+### Fixed vs. still-open (against the canned-demo redesign)
+
+**Already fixed** (both observed working cleanly in `f53afb90`): the `require 'stream_weaver'` + `.run!` omission from the original report is gone — the session wrote both deliberately and called them out explicitly; port discovery used `lsof` directly instead of the `sleep && cat log` polling loop; the gist step used `gh gist create --public` outright instead of defaulting to secret.
+
+**Still open**: the `canvas-wait` foreground-block/background-promotion tax (new finding, not in the original report — worth a course-prompt or harness-level fix, e.g. a shorter poll-and-report pattern instead of a blocking wait); the human/driver step-pacing gaps (framework-level, not prompt-fixable); the hardcoded personal `gstack/browse` path and `gh` auth dependency (both env-portability, need either a repo-relative resolution or an explicit prereq check at course start); the doc-save-location mismatch (already tracked, not yet built).

data/docs/visual/browser-rendering-spike.md

@@ -0,0 +1,173 @@
+# Rendering StreamWeaver Docs Without Ruby: Browser Extension and npm Package
+
+**Date:** 2026-08-07
+**Status:** Spike complete — end-to-end verified, not productized
+
+**TL;DR:** A StreamWeaver doc can be compiled from Ruby source and rendered
+entirely in JavaScript, with no Ruby installed — verified end to end at 640ms
+for the 385-line reference PRD, producing output identical to the Ruby-built
+version. One blocker stood in the way and is now solved: **Opal's self-hosted
+parser cannot lex heredocs of any form**, and doc DSL files are full of them.
+A source rewrite (`sw-heredoc-rewrite.js`) clears it. The same artifact serves
+both the browser extension and an npm package — they are one build, not two.
+
+---
+
+## The Realization That Reframes Both
+
+A browser extension that renders docs from GitHub has to handle Ruby *source* —
+that's what GitHub serves. Rendering it client-side therefore means **compiling
+Ruby in the browser**, not merely running a precompiled bundle.
+
+That is the same requirement an npm package has for anyone without Ruby. So the
+extension and the npm package are not two projects sharing a theme; they are
+one compiled artifact with two wrappers.
+
+```
+        .rb source (GitHub raw, local file, stdin)
+                        │
+                        ▼
+          sw-heredoc-rewrite.js        ← required; see below
+                        │
+                        ▼
+       Opal.compile()  (opal-parser.js, self-hosted)
+                        │
+                        ▼
+   StreamWeaver Opal runtime + Adapter::Static renderers
+                        │
+        ┌───────────────┴───────────────┐
+        ▼                               ▼
+  browser extension                 npm package
+  (viewer page/side panel)      (CLI, CI, VS Code preview)
+```
+
+---
+
+## Verified
+
+Every claim below was executed, not reasoned about.
+
+| Claim | Result |
+|---|---|
+| Opal compiles itself to JS | `opal` + `opal-parser` → **2.98MB** bundle |
+| That bundle compiles Ruby in Node, no Ruby installed | `Opal.compile("[1,2,3].map { \|x\| x * 2 }.inspect")` → `[2, 4, 6]` |
+| StreamWeaver runtime + compiler in one bundle | **3.65MB** |
+| A doc compiles and renders in-browser from source | ✅ 640ms for `prd_dsl.rb` |
+| Output matches the Ruby-built version | 12,972 chars, 27 headings, 5 tables, 7 code blocks, 11 TOC links, 3 callouts — identical |
+| Page errors | none |
+
+Size: ~3.65MB runtime + 3.5MB mermaid ≈ 7.2MB uncompressed. Unremarkable for an
+extension (loaded from local disk, no download per page) and fine for an npm
+package. Roughly 1–1.5MB gzipped if ever served over a network.
+
+---
+
+## The Blocker: Heredocs
+
+`opal-parser.js` **fails on every heredoc form**:
+
+```
+<<~MD    → "unterminated string meets end of file"
+<<-MD    → same
+<<MD     → same
+<<~"MD"  → same
+```
+
+Multi-line strings, `%w[]`, and `#{}` interpolation all parse fine — it is
+specific to heredoc lexing. The MRI-hosted compiler handles heredocs correctly,
+so this is a gap in the self-hosted parser only (Opal 1.8.3). Adding `strscan`
+and `racc/parser` to the build does not help; `StringScanner` itself works.
+
+This matters because heredocs are how doc DSL files are written —
+`md <<~MD`, `code_block(<<~TXT, lang: "ruby")`, `mermaid <<~MERMAID`. The
+reference PRD has **17 of them**. Without a fix, in-browser compilation fails on
+essentially every real document.
+
+### The fix
+
+`lib/stream_weaver/assets/js/sw-heredoc-rewrite.js` rewrites heredocs into
+double-quoted string literals before compilation. Double quotes preserve `#{}`
+interpolation, so the rewrite is transparent for the interpolating forms;
+`<<~'X'` is emitted single-quoted to stay non-interpolating. Squiggly heredocs
+get their common indentation stripped, matching Ruby's semantics.
+
+Verified against: plain squiggly, heredoc-as-argument with a following keyword
+argument, interpolation, embedded double quotes, and the full 17-heredoc PRD.
+
+**Known limits.** One heredoc per line; multiple heredocs opened on a single
+line are not handled. Nested heredocs are not handled. Neither appears in
+StreamWeaver doc files, but both would need work before this is a general Ruby
+tool. It is a targeted preprocessor, not a Ruby parser.
+
+---
+
+## Two Products, One Artifact
+
+### Browser extension
+
+Fetch raw `.rb` → rewrite → compile → render in an extension page or side panel.
+Per the earlier analysis, an extension *page* rather than in-page injection
+avoids both style collision with GitHub and the DOM-churn maintenance tax.
+
+Remote **script** is what MV3 forbids, which is why mermaid and Prism had to be
+bundled. Remote stylesheets and fonts are not restricted by the default policy,
+so Google Fonts is fine — worth an opt-out only for offline or privacy reasons.
+
+### npm package
+
+The same bundle plus a thin API:
+
+```js
+const { render } = require('@streamweaver/render')
+const html = render(fs.readFileSync('doc.sw.rb', 'utf8'))
+```
+
+Uses that don't involve GitHub at all:
+
+- `npx streamweaver-render doc.rb > doc.html` for people with no Ruby
+- Static site generation and CI, without adding Ruby to the image
+- A VS Code preview pane
+- Any JS toolchain that wants StreamWeaver docs as HTML
+
+**One caveat for the Node path.** The Opal runtime's render pass builds an HTML
+string without touching the DOM, but `OpalBridge` and `patch_dom` do. A Node
+renderer therefore needs either jsdom or a render-to-string entry point that
+skips the bridge. The string path exists inside the runtime already
+(`OpalRuntime#render_html`); it just is not exposed. That is the main piece of
+work between this spike and a shippable npm package.
+
+---
+
+## Recommended Order
+
+1. **Expose render-to-string** in the Opal runtime, bypassing the bridge. Small,
+   and it unblocks the entire Node path.
+2. **npm package** wrapping compiler + runtime + assets + rewriter. Testable in
+   CI, no browser or store review involved.
+3. **Browser extension** on top of the same package. Now the only new work is
+   the GitHub URL detection and the viewer page.
+
+Doing the npm package first means the extension inherits something already
+proven, and gets a test surface that does not require a browser.
+
+---
+
+## Open Questions
+
+1. **Upstream the heredoc gap?** Worth an Opal issue — a self-hosted parser that
+   cannot lex heredocs is a general limitation, not a StreamWeaver one. If it is
+   fixed upstream, the rewriter can be deleted.
+2. **Is `ruby.wasm` a better long-term base?** `@ruby/wasm-wasi` runs real CRuby,
+   so no parser gaps at all — but it is 10–30MB and would need the gem's server
+   dependencies stubbed. Worth revisiting if the parser gap widens.
+3. **Which file extension marks a StreamWeaver doc?** The extension needs to
+   decide what to render. `.sw.rb` is unambiguous; plain `.rb` under
+   `docs/streamweaver_canvas/` is convention-based and would misfire elsewhere.
+4. **Interactive components in a viewer.** Buttons and inputs work in Opal, but a
+   doc viewer probably wants them inert. Worth deciding whether the viewer
+   renders read-only.
+
+---
+
+*Spike verified against Opal 1.8.3, Ruby 3.3.6, Chromium (headless) with all
+HTTP blocked. Reference document: `examples/components/prd_dsl.rb`.*