stream_weaver 0.3.0

data/docs/canvas-ipc-session-summary.md

@@ -0,0 +1,127 @@
+# Canvas IPC Session Summary
+
+**Date:** January 2025
+**Branch:** `feature/canvas-ipc`
+**Status:** OUTDATED - Canvas is now working and actively used
+
+> **Note:** This doc is historical. Canvas IPC is now fully functional.
+> See `docs/canvas-panel-workflow.md` for current documentation.
+
+## What We Attempted
+
+Implement two-way IPC similar to [claude-canvas](https://github.com/BEARLY-HODLING/claude-canvas):
+- Unix socket for Claude CLI ↔ Bridge communication
+- WebSocket mode for Bridge ↔ Browser (partially implemented)
+- Commands: `canvas`, `canvas-push`, `canvas-wait`, `canvas-close`, `pick`, `confirm`
+
+## Overlap with Template Approach
+
+Both solve the same problem: **Push UI → Wait for response → Get JSON**
+
+| Feature | Canvas (this session) | Templates (other thread) |
+|---------|----------------------|-------------------------|
+| Push UI | `canvas-push` via Unix socket | `push` via HTTP |
+| Wait for response | `canvas-wait` (Unix socket, broken) | `wait` (HTTP polling, working) |
+| Confirm dialog | `streamweaver confirm` | `streamweaver template confirm` |
+| Pick/choices | `streamweaver pick` | `streamweaver template choices` |
+
+**The template approach won** - simpler architecture, working code.
+
+## Dead Code (if going with templates)
+
+### Files to Delete (~1023 lines)
+
+```
+lib/stream_weaver/canvas/
+  protocol.rb        # 69 lines - Unix socket message encoding
+  session.rb         # 66 lines - Session with websocket tracking
+  bridge.rb          # 161 lines - Message routing
+  client.rb          # 205 lines - CLI to Unix socket communication
+  bridge_server.rb   # 413 lines - Sinatra + Unix socket server
+  helpers.rb         # 109 lines - DSL generators (overlaps with templates)
+```
+
+### CLI Commands to Remove (cli.rb lines 58-73)
+
+```ruby
+when 'canvas'        # line 58
+when 'canvas-push'   # line 60
+when 'canvas-wait'   # line 62
+when 'canvas-close'  # line 64
+when 'canvas-list'   # line 66
+when 'canvas-stop'   # line 68
+when 'pick'          # line 71 (use `template choices` instead)
+when 'confirm'       # line 73 (use `template confirm` instead)
+```
+
+Plus the method implementations (~300 lines):
+- `canvas_session`
+- `canvas_push`
+- `canvas_wait`
+- `canvas_close`
+- `canvas_list`
+- `canvas_stop`
+- `canvas_pick`
+- `canvas_confirm`
+
+### Dead Code in alpinejs.rb
+
+WebSocket mode code (~100 lines) only used by canvas:
+- Line 25-34: `mode` parameter and `websocket_mode?` method
+- Line 317-335: WebSocket mode in `render_radio_group`
+- Line 451-458: WebSocket mode in `render_button`
+- Line 499-505: WebSocket mode in `container_attributes`
+- Line 570-665: `websocket_init_script` method (sendEvent, getFormState, WebSocket connection)
+
+## What's NOT Dead Code
+
+### In alpinejs.rb - Keep These
+
+The HTTP fallback for `sendEvent` and visual feedback are useful but currently embedded in websocket_init_script. If removing websocket mode, these would be lost.
+
+### Templates Already Cover
+
+- `templates/confirm.rb` - Better than `canvas/helpers.rb` confirm
+- `templates/choices.rb` - Better than `pick` command
+- `templates/wizard.rb` - Multi-step forms (no canvas equivalent)
+- `templates/table.rb`, `code.rb`, `diff.rb`, `info.rb` - No canvas equivalents
+
+## Recommendation
+
+### Option A: Full Cleanup (Recommended)
+
+1. Delete entire `lib/stream_weaver/canvas/` directory
+2. Remove canvas-* and pick/confirm commands from CLI
+3. Remove websocket mode from alpinejs.rb
+4. Keep templates as the solution
+
+**Effort:** ~1400 lines to remove
+
+### Option B: Keep Canvas, Fix Later
+
+1. Leave canvas code dormant
+2. Document it as "experimental, use templates instead"
+3. Maybe fix the socket forwarding someday
+
+**Risk:** Confusion about which approach to use
+
+### Option C: Salvage Pieces
+
+1. Port visual feedback to templates
+2. Port helpers.rb parsing fixes to templates
+3. Then do Option A
+
+## Files Changed Summary
+
+| File | Change Type | Dead if using templates? |
+|------|-------------|-------------------------|
+| `lib/stream_weaver/canvas/*` | Created | YES - delete all |
+| `lib/stream_weaver/cli.rb` | Modified | Partial - remove canvas commands |
+| `lib/stream_weaver/adapter/alpinejs.rb` | Modified | Partial - remove websocket mode |
+| `stream_weaver.gemspec` | Modified | Check if sinatra-contrib still needed |
+| `docs/plans/2026-01-10-canvas-ipc-design.md` | Created | Archive or delete |
+
+## Testing Note
+
+No spec files were created for canvas (checked `spec/*canvas*` - empty).
+Templates have their own tests in the other thread.

data/docs/canvas-panel-workflow.md

@@ -0,0 +1,172 @@
+# Canvas Panel Workflow
+
+Two-way IPC for Claude Code integration. Open a side panel, push content, wait for user interaction, repeat.
+
+## Quick Start
+
+```bash
+# Open panel (creates iTerm2 split with browser)
+streamweaver panel myapp --fresh
+
+# Push content
+streamweaver canvas-push myapp <<'RUBY'
+  header1 "Pick an option"
+  radio_group :choice, ["A", "B", "C"]
+  button "Submit"
+RUBY
+
+# Wait for user interaction (returns JSON)
+streamweaver canvas-wait myapp
+# => {"choice": "B"}
+
+# Close panel (also closes browser pane)
+streamweaver canvas-close myapp
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `panel <name> [--fresh]` | Open split pane with browser. `--fresh` closes existing session first |
+| `canvas-push <name>` | Push DSL content from stdin |
+| `canvas-wait <name>` | Block until user clicks a button, returns form state as JSON |
+| `canvas-toast <name> <msg>` | Show toast notification overlay |
+| `canvas-close <name>` | Close session and browser pane |
+| `canvas-raise <name>` | Surface an already-open session without opening a second pane: activates its tracked iTerm pane, or opens its URL in the default browser if there is none to reuse |
+| `canvas-reset <name>` | Reset session state (keep connections) |
+| `canvas-list` | List all canvas sessions |
+
+## Multi-Step Workflows
+
+Use `canvas_continue` to show a spinner after submit instead of "You can close this window":
+
+```bash
+streamweaver canvas-push myapp <<'RUBY'
+  card do
+    header1 "Step 1"
+    text_field :name, label: "Name"
+    button "Next"
+  end
+  canvas_continue message: "Processing..."
+RUBY
+```
+
+After user clicks "Next", they see "Processing..." spinner until you push the next page.
+
+**Final page** (no `canvas_continue`): Shows "Submitted - You can close this window"
+
+## Panel Features
+
+### Automatic Pane Tracking
+
+When you open a panel, StreamWeaver tracks the iTerm2 pane ID. When you call `canvas-close`, it automatically closes the browser pane. `panel` always opens a NEW pane -- calling it a second time on a session that already has one duplicates it. To bring an existing session's pane back to the front instead (a push you made after the user's attention moved elsewhere, for example), use `canvas-raise <name>`.
+
+### URL Fallback
+
+If the browser doesn't auto-open, the panel command shows a URL you can paste manually:
+
+```
+Canvas 'myapp' ready
+Browser opened in split pane
+
+URL (if browser didn't open): http://localhost:4570/canvas/myapp
+```
+
+## DSL Components
+
+All standard StreamWeaver DSL components work in canvas mode:
+
+- `header1`, `header2`, `header3` - Headings
+- `md "text"` - Markdown content
+- `text_field :key, label: "...", placeholder: "..."` - Text input
+- `radio_group :key, ["opt1", "opt2"]` - Radio buttons
+- `select :key, ["opt1", "opt2"]` - Dropdown
+- `checkbox :key, label: "..."` - Checkbox
+- `button "Label", id: "btn_id", style: :primary` - Submit button
+- `card { ... }` - Card container
+- `status_dot status: :green, pulse: true, label: "OK"` - Status indicator
+- `badge "TEXT", variant: :success` - Badge/tag
+- `table headers: [...], rows: [...]` - Data table
+
+## Example: Verification Flow
+
+See `examples/claude_code/verification_flow/` for a complete multi-step workflow:
+
+1. Sign-up form with `canvas_continue`
+2. Verification page with toast notification
+3. Welcome page (final, no `canvas_continue`)
+
+## Claude Code Integration
+
+### Permissions
+
+Add to `.claude/settings.local.json`:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(streamweaver *)"]
+  }
+}
+```
+
+### Slash Command Pattern
+
+Create `.claude/commands/myflow.md`:
+
+```markdown
+# My Flow
+
+## Instructions
+
+### Phase 1: Open Panel
+\`\`\`bash
+streamweaver panel myflow --fresh
+\`\`\`
+
+### Phase 2: First Page
+\`\`\`bash
+streamweaver canvas-push myflow <<'RUBY'
+  # DSL content here
+  canvas_continue message: "Loading..."
+RUBY
+\`\`\`
+
+Wait for input:
+\`\`\`bash
+streamweaver canvas-wait myflow
+\`\`\`
+
+### Phase 3: Final Page
+\`\`\`bash
+streamweaver canvas-push myflow <<'RUBY'
+  # Final page - no canvas_continue
+RUBY
+\`\`\`
+
+### Cleanup
+\`\`\`bash
+streamweaver canvas-close myflow
+\`\`\`
+```
+
+## Architecture
+
+```
+Claude Code CLI
+      │
+      ▼
+┌─────────────────┐
+│ Unix Socket IPC │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     WebSocket      ┌─────────────┐
+│  Canvas Bridge  │◄──────────────────►│   Browser   │
+│  (background)   │                    │  (iTerm2)   │
+└─────────────────┘                    └─────────────┘
+```
+
+- **Unix Socket**: CLI ↔ Bridge communication
+- **WebSocket**: Bridge ↔ Browser real-time updates
+- **Bridge**: Renders DSL to HTML, manages sessions, routes events

data/docs/canvas-read.md

@@ -0,0 +1,147 @@
+# canvas-read: the document shelf
+
+The most portable way to read a StreamWeaver doc. No iTerm2, no Chrome extension, no
+`gh` — just a local web server and a URL.
+
+## What it is
+
+`streamweaver canvas-read` starts a small local web server that renders one or more
+StreamWeaver DSL/Org files with full styling: sidebar navigation, a per-doc table of
+contents, callouts, cards, tables, live Mermaid diagrams, images. Point it at a file,
+a directory, or nothing (it finds your docs automatically) and it prints a URL.
+
+```bash
+streamweaver canvas-read notes.org
+```
+
+```text
+canvas-read  1 file(s)  →  http://127.0.0.1:4800/?file=0
+Ctrl-C to stop
+```
+
+**Never assume the port.** StreamWeaver auto-finds an available one starting near 4800
+and prints the real URL every time — read it from the command's own output.
+
+## The happy path (tested: macOS + iTerm2)
+
+1. Save or author a StreamWeaver doc (`.rb` or `.org` — see below).
+2. Run `streamweaver canvas-read <file>`.
+3. A browser tab opens automatically at the printed URL (iTerm2 users can instead pop
+   it into a split pane — see [canvas-panel-workflow.md](canvas-panel-workflow.md)).
+4. Read, navigate the table of contents, click through Mermaid diagrams.
+5. Ctrl-C the process when done.
+
+## Authoring Org docs
+
+Org is the portable, human-readable source format. Every StreamWeaver Org doc starts
+with:
+
+```org
+#+STREAMWEAVER_DSL: 1
+#+TITLE: Document Title
+```
+
+Numbered headings with `CUSTOM_ID` properties become sections and drive the sidebar
+table of contents. Ordinary prose, lists, tables, quotes, and source blocks read as
+plain Org. Components with no native Org form (anything outside the recognized set
+below) use a passthrough block:
+
+```org
+#+begin_src ruby :streamweaver-raw t
+image_block File.join(__dir__, "assets/example.png"), base64: true,
+  alt: "Description"
+#+end_src
+```
+
+`.rb` (the DSL source) is the other option — canonical, always lossless, and what
+`org-export`/`org-render` convert to and from.
+
+## Opening one document
+
+```bash
+streamweaver canvas-read path/to/doc.org
+```
+
+Works for both `.rb` and `.org` files.
+
+## Opening a shelf
+
+Pass multiple files, or a directory, and canvas-read turns them into a shelf: every
+doc listed in a left rail, one click to switch between them.
+
+```bash
+streamweaver canvas-read docs/proposals/
+```
+
+With no arguments at all, canvas-read scans your usual docs roots (this repo, if
+you're in one, plus `~/.streamweaver`) and builds the shelf from whatever it finds —
+handy for a quick `streamweaver canvas-read` with nothing else typed.
+
+## Comparing versions
+
+The left rail lists every document in the shelf; click any entry to switch. Inside a
+document, **Previous/Next** buttons step through the shelf in order, and each
+document's own generated table of contents lets you jump to a section directly. This
+is the pattern from the [DiDX case study](case-studies/2026-09-03-didx-canvas-read-shelf.md):
+keep a neutral version, a personal-voice version, and a technical version side by
+side, and compare them without leaving the shelf.
+
+## Working with images
+
+Ordinary relative image paths don't have a backing asset route in canvas-read.
+Use `image_block` with `base64: true` so the image is embedded directly:
+
+```org
+#+begin_src ruby :streamweaver-raw t
+image_block File.join(__dir__, "assets/diagram.png"), base64: true, alt: "Architecture"
+#+end_src
+```
+
+Without `base64: true`, the image won't resolve — this is the one gotcha worth
+knowing before you build a doc full of screenshots.
+
+## Exporting or packaging
+
+- `streamweaver export file.rb` writes a saved DSL doc out as standalone HTML
+  (`--inline-images` to embed local images, `--offline` to inline the Mermaid
+  library for viewers with a strict CSP).
+- `.rb` and `.org` docs checked into a GitHub repo or Gist render with full
+  StreamWeaver styling via the [browser extension](../extension/README.md) — no
+  install, no Ruby, no server required for the reader.
+
+See the known gap below for `streamweaver export` on `.org` files specifically.
+
+## Platform support
+
+canvas-read is the most portable piece of StreamWeaver — see the
+[Platform support matrix](../README.md#platform-support) in the README. In short: it's
+a plain local web server, so it's expected to work anywhere Ruby and a browser do,
+independent of iTerm2, Chrome, or `gh`.
+
+## No-iTerm degraded demo
+
+```bash
+SW_NO_OPEN=1 streamweaver canvas-read docs/
+```
+
+`SW_NO_OPEN=1` skips the auto-open — the command prints its URL and exits into the
+running server; open that URL in any browser yourself. Expect the shelf to list every
+Org and Ruby doc under `docs/`, with navigation, table of contents, images, diagrams,
+and reading mode all working, no iTerm2 required.
+
+## Known gaps
+
+- **disc-175 — `streamweaver export` doesn't accept `.org` files first-class.**
+  `canvas-read` handles Org source directly; `export` still tries to eval the raw Org
+  text as Ruby and fails. The workaround (`Org::Reader.to_dsl` → `App` →
+  `HtmlExporter`) is documented in the
+  [case study](case-studies/2026-09-03-didx-canvas-read-shelf.md#important-export-gap).
+- **disc-176 — canvas-read doesn't rewrite cross-document links.** Same-document Org
+  anchors work; a relative link from one Org doc to another in the same shelf isn't
+  rewritten into a canvas-read navigation URL. The shelf's left rail is the workaround
+  today — MarkyMark has prior art for rewriting relative links into reader routes.
+
+## Case study
+
+This guide's structure follows the write-up from a real multi-document session:
+[Case study: the Org + canvas-read document shelf (DiDX proposal session)](case-studies/2026-09-03-didx-canvas-read-shelf.md).