stream_weaver 0.3.0

data/lib/stream_weaver/skills/streamweaver-canvas-safe/references/tabs-and-navigation.md

@@ -0,0 +1,53 @@
+# Tabs and Navigation
+
+## tabs (eager, default) — plays well everywhere
+
+```ruby
+tabs :settings_tabs do
+  tab "General" do
+    text "General settings content"
+  end
+  tab "Notifications" do
+    text "Notification settings content"
+  end
+end
+```
+
+Pure client-side `@click activeTab = N` — WORKS identically in A, B, and C. Variants (`variant: :enclosed`, `variant: :"soft-rounded"`) are CSS-only, no change to this. This is the form to reach for in the comprehensive example / any doc that has to survive an export.
+
+## tabs url: true — the one component that's MORE capable off the live canvas
+
+```ruby
+tabs :view, url: true do
+  tab "Overview" do ... end
+  tab "Details" do ... end
+end
+```
+
+On canvas (A, B) this degrades to plain client-side tabs and logs a warning once per render — to the **agent's** stderr, never shown to the human viewing the page (`route_tabs? = component.url? && !websocket_mode?`). In an export (C), `sw-route-tabs.js` is inlined and runs real `pushState` routing, so the URL updates and the tab state survives a reload. This is intentional and informational (disc-099), not a bug — but if you're diagnosing "why does this tab set behave differently exported vs. on canvas," this is why. Not yet confirmed under `file://` — several browsers throw `SecurityError` for `pushState` on `file://` origins, so an exported doc opened directly from disk (not served over HTTP) may still break tab switching; check by hand if that's how the export will be opened.
+
+## collapsible / expandable_card / dropdown — plays well everywhere
+
+```ruby
+collapsible "Show Details" do
+  text "Detail content"
+end
+
+expandable_card "Section" do  # like collapsible, but the SERVER learns the expanded state
+  text "..."
+end
+```
+
+Pure Alpine `x-show`/`x-data`, no server dependency — WORKS in A, B, C. Use `expandable_card` over `collapsible` only if you need `state` to know whether a section is open; that's a server round-trip and inherits the sendEvent-only-on-live-canvas disposition for that specific bit of state (the panel itself still opens/closes client-side everywhere).
+
+## modal — needs a real server, half the time
+
+Modal *closing* is Alpine-only and works everywhere. Modal *opening* is server-state driven — on the live canvas an agent has to push the state that opens it; on canvas-read and export there's no way to open one at all (SILENTLY-DEAD). Don't build a doc where the only path to some content is "click to open a modal" if that doc needs to survive being saved and reopened later.
+
+## route_by / route / page — needs a real server
+
+The SSE client and routing/`popstate` scripts are `AppView`-only. Canvas (A, B) renders through `AppContentView`, export (C) through `ComponentRenderer.render_html` — neither ever gets those scripts, so `route_by` has no client at all backend-less. The initial paint shows and nothing ever updates. Out of scope for this skill's fixes; know it going in rather than debug a page that "isn't routing."
+
+## The gotcha
+
+Route tabs are the one component in this whole skill where "more functional off the live canvas" is correct and not a regression. Every other asymmetry in this doc runs the other direction (live canvas is the most capable context) — this is the exception, and it's easy to mistake for a bug if you don't know it's by design.

data/lib/stream_weaver/skills/streamweaver-doc-builder/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: streamweaver-doc-builder
+description: Use when building editorial "doc"-style StreamWeaver apps — PRDs, reports, explainers, long-form write-ups — with the :doc theme, doc_header/doc_section_header/sidebar_toc, and the shared-DSL pattern for standalone + canvas delivery
+---
+
+# StreamWeaver Doc Builder
+
+Build long-form, editorial-style documents (PRDs, reports, explainers) as StreamWeaver apps using the `:doc` theme and the document component family. Documents can be authored once as a shared DSL body and delivered two ways — standalone Ruby app or live canvas — without duplicating content.
+
+## When to Use
+
+Use when the deliverable is a **document**, not a dashboard or a brainstorming canvas:
+
+- A PRD, spec, or proposal that needs sections, a table of contents, callouts, and tables
+- A report or explainer meant to be read top-to-bottom
+- Anything you'd otherwise write as a long markdown file, but want scroll-spy navigation, styled callouts, and diagrams rendered live
+
+Skip for: dashboards (use standard components), quick visual A/B comparisons or brainstorming (use `streamweaver-visual-companion`), pre-flight implementation plans (use `visual-plan`).
+
+## !! DO NOT LAUNCH STANDALONE SERVERS PER QUESTION !!
+
+Same rule as the other canvas-based skills: **never** run `ruby app.rb` or `streamweaver <file.rb>` for each content update while iterating on a doc with the user. Use `canvas-push` to update a single persistent session. Only reach for a standalone `ruby` run when you want a permanent, git-tracked app file from the start (see "Two Delivery Modes" below).
+
+## The `:doc` Theme
+
+`:doc` — "Compact Editorial" — is the theme for document-style apps: Charter/system-ui fonts, 15px base size, `#1E4ED8` primary blue, `#F5F4EF` background. Defined in `lib/stream_weaver/theme.rb`.
+
+```ruby
+app "My Document Title", theme: :doc do
+  # ... doc components here
+end
+```
+
+**Do not confuse this with the older `:document` theme** (serif Crimson Pro, 19px, "Reading Mode"). `:document` predates `:doc` and some older example files in this repo still reference it — for new doc-style apps, always use `theme: :doc`.
+
+Dark mode works automatically — the `:doc` theme has a dark variant, and `theme_toggle` / auto-mode JS sets `data-sw-theme="dark"` on `<html>` for you. Don't hand-roll dark-mode styling; just use `theme: :doc` (standalone) or `--theme=doc` (canvas panel) and it's wired through, including Mermaid diagram dark-sync.
+
+## Two Delivery Modes, One DSL Body
+
+The core pattern: write your document content **once**, as a bare DSL body file — no `app` wrapper, just a sequence of top-level component calls. Then consume that same file two ways:
+
+1. **Standalone app** — `instance_eval` the body inside an `app "...", theme: :doc do ... end` wrapper
+2. **Canvas push** — pipe the body file directly to `streamweaver canvas-push <session>`
+
+Because both modes read the exact same file, content never drifts between "the app I can `ruby run.rb`" and "the live canvas I've been iterating on with the user."
+
+**Start every DSL body with `# streamweaver-doc: v1`.** A body is bare component calls with no `require` and no `app` wrapper, so nothing about the file says what it is — tooling that meets one out of context (a renderer pointed at a GitHub blob, an editor plugin) can't tell it from ordinary Ruby, and guessing from content is unreliable for short docs. "Save as doc" adds the line automatically; hand-written bodies need it written in. It's a comment, so it costs nothing at eval time.
+
+Reference implementation in this repo: `examples/components/prd_dsl.rb` (body only) + `examples/components/prd_demo.rb` (standalone wrapper). Copy the shared-body/`instance_eval` structure — but note `prd_demo.rb` still says `theme: :document`, since it predates the `:doc` theme; use `theme: :doc` in new work.
+
+```ruby
+# doc_body.rb — no `app` block, just component calls
+# streamweaver-doc: v1
+sidebar_toc sections: [
+  { id: "problem", label: "Problem Statement" },
+  { id: "architecture", label: "Architecture" }
+]
+
+doc_header(title: "My PRD", pills: [{ text: "Draft" }])
+
+doc_section_header "01", "Problem Statement", id: "problem"
+md "Prose goes here."
+```
+
+```ruby
+# doc_app.rb — standalone wrapper
+require_relative "../../lib/stream_weaver"
+
+DOC_BODY_PATH = File.join(__dir__, "doc_body.rb")
+
+DocApp = app "My PRD", theme: :doc do
+  instance_eval(File.read(DOC_BODY_PATH), DOC_BODY_PATH)
+end
+
+DocApp.run! if __FILE__ == $0
+```
+
+```bash
+# Same doc_body.rb, pushed to a live canvas instead
+streamweaver canvas-push my-doc < doc_body.rb
+```
+
+## Shared DSL Fragments (multi-audience docs)
+
+When two docs for **different audiences** (a decision memo and its engineering companion, say) must quote the same tables, rules, or numbers, put those tables in ONE fragment file and load it from both bodies. Prose stays per-audience; only the facts are shared.
+
+A fragment is a plain `.rb` under `shared/` that defines methods emitting DSL and nothing else: no `app` wrapper, no `doc_header`/`sidebar_toc`, no side effects, no `# streamweaver-doc: v1` marker. Name the methods with a doc-family prefix (`pm_base_rules_table`), because `instance_eval` turns them into singleton methods on the App and they share a namespace with every DSL verb.
+
+Consumer snippet, top of each doc body:
+
+```ruby
+unless respond_to?(:pm_base_rules_table)
+  _root = __dir__ || ENV["SW_DOC_DIR"] || Dir.pwd
+  _frag = File.expand_path("shared/pm_discount_shared.rb", _root)
+  raise "shared DSL fragment not found: #{_frag}" unless File.file?(_frag)
+  instance_eval(File.read(_frag), _frag)
+end
+```
+
+`export` and `canvas-read` pass the doc's path to `instance_eval`, so `__dir__` resolves the fragment there. `org-export` and the canvas-push bridge do not, so `__dir__` is `nil`: run `org-export` from the doc's directory (or set `SW_DOC_DIR`), and for canvas-push concatenate the fragment ahead of the body, which the `respond_to?` guard makes idempotent:
+
+```bash
+cat shared/pm_discount_shared.rb my-doc.rb | streamweaver canvas-push my-doc
+```
+
+Never hardcode an absolute home-directory path as a fallback. Full rationale, the per-mode `__dir__` truth table with code cites, the org-mode answers, and a proposal for a first-class `dsl_fragment` helper: `docs/shared-dsl-fragments.md` in the stream_weaver repo.
+
+## Component Reference
+
+### `doc_header` — title block
+
+```ruby
+doc_header(
+  eyebrow: "Acme Corp · Internal Wiki",  # optional small label above the title
+  title: "Calendar-Driven Travel State", # required
+  pills: [                               # optional meta row
+    { text: "Draft" },                   # Hash -> colored pill (variant: :default/:warn/:good)
+    "June 25, 2026",                     # String -> plain meta text
+    "Author: Jane Doe"
+  ]
+)
+```
+
+### `doc_section_header` — numbered section heading
+
+```ruby
+doc_section_header "01", "Problem Statement", id: "problem"
+# number, title positional; id: becomes the DOM anchor id
+```
+
+### `sidebar_toc` — sticky scroll-spy table of contents
+
+Call once, near the top of the doc:
+
+```ruby
+sidebar_toc sections: [
+  { id: "problem", label: "Problem Statement" },
+  { id: "architecture", label: "Architecture" }
+]
+```
+
+Desktop (>=1000px): sticky 170px sidebar, active section highlighted via `IntersectionObserver`. Mobile (<1000px): horizontal scrollable sticky bar at top. Each `id:` here must exactly match the `id:` on a `doc_section_header` (see Known Gotchas).
+
+### `callout` — non-dismissible tip/warning box
+
+```ruby
+callout(variant: :warning, title: "Root cause:") do
+  text "Explanation text here."
+end
+# variants: :info, :warning, :success, :error, :tip, :decision, :risk
+```
+
+### `table` — data table
+
+```ruby
+table(
+  headers: ["Component", "Responsibility", "Owner"],
+  rows: [
+    ["Enforcement", "Require calendar entry", "scheduler secretary"],
+    ["Sync script", "Read calendars, write state", "launchd"]
+  ]
+)
+```
+
+### `card` / `card_header` / `card_body` — boxed section
+
+```ruby
+card do
+  card_header "Component Title", badge: "C1", meta: "owner · trigger"
+  # badge: optional small tag before title; meta: optional right-aligned text
+  card_body do
+    md "Body content, supports **markdown**."
+    code_block(<<~TXT, lang: "text")
+      inline code sample
+    TXT
+  end
+end
+```
+
+### `comparison` — side-by-side before/after panels
+
+Useful for "In Scope" / "Out of Scope" grids:
+
+```ruby
+comparison(before_label: "In Scope", after_label: "Out of Scope") do
+  before { md "- Item 1\n- Item 2" }
+  after  { md "- Excluded item" }
+end
+# Stacks vertically on viewports <768px.
+```
+
+### `code_block` — syntax-highlighted code
+
+```ruby
+code_block(<<~RUBY, lang: "ruby")
+  def hello
+    puts "hi"
+  end
+RUBY
+# Options: file: "path/to/file.rb" (shows file header bar),
+#          truncate: N (thumbnail line limit), scroll: true/false
+```
+
+### `mermaid` — diagrams (dark-mode aware)
+
+```ruby
+mermaid <<~MERMAID
+  graph LR
+    A["Calendar"] --> B["Sync script"] --> C["state.yaml"]
+    style A fill:#EEF2FF,stroke:#1E4ED8,color:#1E4ED8
+MERMAID
+# Options: zoom: true (pan/zoom controls), compact: true (reduced padding
+#          for card embedding), layout: :elk
+```
+
+### `md` — prose
+
+Use `md` for all body copy that needs bold/italic/links/lists. **`text` does not render markdown** — see Known Gotchas.
+
+## Minimal Copy-Paste Template
+
+A complete, runnable doc in under 30 lines. Adapt the titles/sections/content and go.
+
+```ruby
+require_relative "../../lib/stream_weaver"
+
+MyDoc = app "My Report Title", theme: :doc do
+  sidebar_toc sections: [
+    { id: "overview", label: "Overview" },
+    { id: "findings", label: "Findings" }
+  ]
+
+  doc_header(
+    eyebrow: "Team · Project",
+    title: "My Report Title",
+    pills: [{ text: "Draft" }, "July 2, 2026"]
+  )
+
+  doc_section_header "01", "Overview", id: "overview"
+  md "This report covers **what changed** and *why it matters*."
+
+  callout(variant: :info, title: "Key takeaway") do
+    text "The short version, up front."
+  end
+
+  doc_section_header "02", "Findings", id: "findings"
+  table(
+    headers: ["Metric", "Before", "After"],
+    rows: [["Latency", "220ms", "80ms"]]
+  )
+end
+
+MyDoc.run! if __FILE__ == $0
+```
+
+To push the same content live instead of running it standalone: strip the `require_relative`/`app ... do`/`.run!` wrapper down to just the component calls (the body), and pipe it: `streamweaver canvas-push my-doc < doc_body.rb`.
+
+## Canvas Workflow
+
+```bash
+# 1. Open a themed canvas panel (iTerm2 split pane, or browser tab elsewhere)
+streamweaver panel my-doc --theme=doc --fresh
+
+# 2. Push the DSL body (same file used standalone — see shared-DSL pattern above)
+streamweaver canvas-push my-doc < path/to/doc_body.rb
+
+# 3. Interact — user can click, scroll, use theme_toggle if included; you can push
+#    updates to the SAME session as content evolves (re-run canvas-push with the
+#    updated body — never spin up a second session)
+
+# 4. Save as doc — a floating 💾 "Save as doc" button sits bottom-right on the canvas.
+#    User clicks it, names the doc, and it's written to docs/streamweaver_canvas/<name>.rb
+#    — git-tracked, permanent. Don't reinvent this flow for the user; point them at the
+#    button. Fallback (only if the button isn't reachable, e.g. non-canvas context) —
+#    get <bridge-port> from `streamweaver canvas-list` output:
+curl -sX POST "http://localhost:<bridge-port>/canvas/my-doc/save-doc" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"<doc-name>"}'
+```
+
+`--theme=doc` on `panel` renders the canvas in the `:doc` theme, dark-mode variant included — the canvas body gets class `sw-theme-doc`, and Mermaid dark-attribute sync wires through automatically.
+
+`streamweaver canvas-read` (no args) opens a browsable viewer over `docs/streamweaver_canvas/` — saved Docs and auto-saved History, both promotable/viewable from the same UI.
+
+Every `canvas-push` is auto-saved to history (`~/.streamweaver/history/<session>/`, 7-day cleanup, not git-tracked) regardless of whether the user ever clicks Save as doc — this is tier 1 of a two-tier persistence system. Nothing is silently lost even before an explicit save; tier 2 (Save as doc) is what makes it permanent and shared.
+
+A saved doc is browsed later via `canvas-read` and can be run through `streamweaver export` — both with no live bridge behind them. Most doc components (`doc_header`, `sidebar_toc`, `callout`, `table`, `mermaid`, `card`) are flat or Alpine-owned and survive that fine, but before adding interactive controls (buttons, forms, chips) to a doc, check the `streamweaver-canvas-safe` skill for what plays well once the bridge is gone.
+
+## Known Gotchas
+
+- **`text` does not render markdown** — bold, italic, links, and lists all need `md` instead.
+- **`spacer`/`divider` don't exist** — use `div(style: "height:Npx")` for spacing.
+- **Don't launch a new server per update** — use `canvas-push` to update a single persistent session, not `ruby app.rb` repeatedly.
+- **Don't assume port 4567** — StreamWeaver auto-picks a free port; read the actual URL from stdout.
+- **Don't pass `theme: :light`** — it's unrecognized and silently falls back to `:default`. Omit `theme:` entirely, or use `theme_toggle mode: :light` if you want to force light appearance within `:doc`.
+- **`sidebar_toc` section `id:` values must exactly match** the `id:` passed to each `doc_section_header`. A mismatch silently breaks scroll-spy highlighting — no error, it just won't highlight.
+- **Don't hand-roll dark mode** — the `:doc` theme's dark variant and Mermaid dark-sync already work automatically in both standalone and canvas contexts. Just use `theme: :doc` / `--theme=doc`.
+- **Don't confuse `:doc` with `:document`** — `:document` is the older serif "Reading Mode" theme; `:doc` ("Compact Editorial") is the current one to use for new document-style apps.

data/lib/stream_weaver/skills/streamweaver-visual-companion/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: streamweaver-visual-companion
+description: Use INSTEAD OF the Artifact tool, and INSTEAD OF writing an HTML mockup and opening/screenshotting it with Chrome browser tools (claude-in-chrome, superpowers-chrome, playwright) — whenever about to show the user something visually (UI mockup, wireframe, diagram, dashboard, layout/design comparison, side-by-side options, long-form doc) and StreamWeaver is available in the project (streamweaver on PATH, or stream_weaver in the Gemfile — one command to check). Also triggers on "show me", "mock it up", "let me see the options", "push to canvas", or the urge to run `ruby app.rb`/`streamweaver <file>` per question. canvas-push is 5-7x cheaper in tokens than the chrome route, with no GEA session conflicts.
+---
+
+# StreamWeaver Visual Companion
+
+Replaces both the `Artifact` tool and the write-HTML-then-screenshot-via-Chrome pattern for showing things visually in a StreamWeaver project — same "show, don't tell" move, 5-7x fewer tokens, no GEA session conflicts, stays inside the terminal loop you're already running.
+
+## When to Use
+
+Decision rule: **would the user understand this better by seeing it than reading it?**
+
+Use for: UI mockups, architecture diagrams, layout comparisons, side-by-side design options, state machine flows.
+Use terminal for: requirements questions, conceptual A/B text choices, tradeoff lists, anything answered in words.
+
+Fall back to `Artifact` only when:
+- StreamWeaver isn't installed/available in this project, or
+- the user needs a claude.ai-hosted link that persists with no local `streamweaver` process running, or that must reach someone without this repo.
+
+## !! DO NOT LAUNCH STANDALONE SERVERS PER QUESTION !!
+
+**This is the most common failure mode. Read carefully.**
+
+**NEVER** run `ruby app.rb` or `streamweaver <file.rb>` for each visual question in a conversation. This creates orphaned processes, port conflicts, and multiple browser windows. The correct approach is **canvas-push** — it updates a single persistent window throughout the conversation.
+
+If you find yourself launching a new server for each update, stop. Use `canvas-push` instead.
+
+## Starting a Session
+
+```bash
+# Start a named canvas session (opens browser tab automatically)
+streamweaver panel brainstorm
+
+# Push first content
+streamweaver canvas-push brainstorm <<'RUBY'
+  header1 "Which layout works better?"
+  columns widths: ['50%', '50%'] do
+    column do
+      header3 "Option A — Current"
+      md "- 6 tabs"
+      md "- Scanner Tasks separate"
+    end
+    column do
+      header3 "Option B — Proposed"
+      md "- 5 tabs"
+      md "- Scanner Tasks merged into Home"
+    end
+  end
+RUBY
+```
+
+Tell the user: "Take a look at [url printed by StreamWeaver] and let me know what you think in the terminal."
+
+## Layout
+
+Canvas sessions default to **`:fluid` (full viewport width)** — the best choice for side-by-side comparisons. Override with `--layout=` if you need a narrower centered card:
+
+```bash
+streamweaver panel brainstorm                    # fluid (default, full-width)
+streamweaver panel brainstorm --layout=default   # 900px centered card
+streamweaver panel brainstorm --layout=wide      # 1100px
+streamweaver panel brainstorm --layout=full      # 1400px
+```
+
+## The Loop
+
+1. Push DSL content via `canvas-push`
+2. Tell user what to expect, give the URL, end your turn
+3. User responds in terminal — use their text as feedback
+4. Push updated content or next question
+5. Repeat until done
+
+Blocking selection: `radio_group` + `button`, then `canvas-wait <session>` to get their click as JSON. Ending a push with more than one question? Bundle into one form instead of one round-trip each — see `references/checkpoints-and-forms.md`.
+
+Every push auto-saves to history; the user can promote it to a permanent doc with the canvas's own Save-as-doc button (their action, never yours) — see `references/persistence.md`.
+
+## Returning to Terminal
+
+When the next step is text-only, push a placeholder so the user isn't staring at a resolved mockup:
+
+```bash
+streamweaver canvas-push brainstorm <<'RUBY'
+  div(style: "display:flex;align-items:center;justify-content:center;min-height:60vh") do
+    text "Continuing in terminal..."
+  end
+RUBY
+```
+
+## DSL Quick Reference
+
+```ruby
+header1 "Title"               # h1–h6 available
+text "Plain text"             # NEVER put markdown in text — use md instead
+md "**Bold** and *italic*"    # markdown renderer
+div(style: "height:16px")     # spacing (spacer/divider not available)
+
+columns widths: ['50%','50%'] do  # side-by-side comparison
+  column { header3 "Left" }
+  column { header3 "Right" }
+end
+
+card do                        # boxed section
+  header3 "Section"
+  text "Content"
+end
+
+table headers: ["Col","Col2"], rows: [["a","b"],["c","d"]]
+radio_group :choice, ["Option A", "Option B", "Option C"]
+button "Select"
+badge "New", color: :green
+status_dot :green, "Active"
+```
+
+## Known Gotchas
+
+- `spacer` and `divider` don't exist — use `div(style: "height:Npx")`
+- `theme: :light` unrecognized — omit, defaults to `:default`
+- StreamWeaver auto-selects an available port (not always 4567) — capture the URL from stdout
+- Canvas sessions default to `:fluid` (full-width) — use `--layout=default` if you want the 900px centered card
+- Numbered/bulleted list items split across **separate `md()` calls don't continue** — each `md()` call is its own independent markdown block, so three calls each starting `"1. ..."` render as three separate one-item lists (all showing "1.") instead of counting up 1/2/3. Put a multi-item list in **one** `md()` call, one item per line, e.g. `md "1. First\n2. Second\n3. Third"`.
+
+## Reference Files — Load On Demand
+
+| Doing... | Read |
+|---|---|
+| Porting a claude.ai Artifact 1:1, or building a long-form doc | `references/example-gallery.md` |
+| Ending a push with more than one question | `references/checkpoints-and-forms.md` |
+| Saving/persisting a canvas doc, sharing DSL across two docs | `references/persistence.md` |
+| Cleaning up orphaned processes, or how `panel` opens the browser | `references/cleanup-and-panel.md` |