stream_weaver 0.3.0

data/lib/stream_weaver/service_client.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'rbconfig'
+
+module StreamWeaver
+  # Client module for interacting with the StreamWeaver service.
+  # Include this in tools that load apps via the service API.
+  #
+  # @example
+  #   class MyTool
+  #     include StreamWeaver::ServiceClient
+  #
+  #     def run_example(file_path)
+  #       result = load_app_via_service(file_path, source: "my_tool")
+  #       open_in_browser(result[:url]) if result[:ok]
+  #     end
+  #   end
+  module ServiceClient
+    # Get the service port from PID file or default
+    #
+    # @return [Integer] The port number
+    def service_port
+      info = Service.read_pid_file
+      info ? info[:port] : Service::DEFAULT_PORT
+    end
+
+    # Open a URL in the default browser (OS-aware)
+    #
+    # @param url [String] The URL to open
+    # Guarded here, at the root -- see StreamWeaver::CLI.open_browser and
+    # SinatraApp.open_browser for the same guard on the other two
+    # independent browser-open implementations in this codebase.
+    def open_in_browser(url)
+      return if ENV['SW_NO_OPEN']
+
+      case RbConfig::CONFIG['host_os']
+      when /darwin|mac os/
+        system('open', url)
+      when /linux|bsd/
+        system('xdg-open', url)
+      when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+        system('start', url)
+      end
+    end
+
+    # Load an app via the service API
+    #
+    # @param file_path [String] Path to the Ruby file defining the app
+    # @param source [String] Source identifier for tracking (e.g., "tutorial", "examples_browser")
+    # @param name [String, nil] Optional display name
+    # @return [Hash] Result with :ok, :app_id, :url, :aliased_url, or :error
+    def load_app_via_service(file_path, source:, name: nil)
+      expanded_path = File.expand_path(file_path)
+
+      uri = URI("http://localhost:#{service_port}/load-app")
+      params = { file_path: expanded_path, source: source }
+      params[:name] = name if name
+
+      response = Net::HTTP.post_form(uri, params)
+      result = JSON.parse(response.body)
+
+      if result['success']
+        {
+          ok: true,
+          app_id: result['app_id'],
+          name: result['name'],
+          url: "http://localhost:#{service_port}#{result['url']}",
+          aliased_url: result['aliased_url'] ? "http://localhost:#{service_port}#{result['aliased_url']}" : nil
+        }
+      else
+        { ok: false, error: result['error'] }
+      end
+    rescue Errno::ECONNREFUSED
+      { ok: false, error: "Service not running" }
+    rescue => e
+      { ok: false, error: e.message }
+    end
+
+    # Remove an app from the service
+    #
+    # @param app_id [String] The app ID to remove
+    # @return [Hash] Result with :ok key for consistency
+    def remove_app_via_service(app_id)
+      uri = URI("http://localhost:#{service_port}/remove-app")
+      response = Net::HTTP.post_form(uri, { app_id: app_id })
+      result = JSON.parse(response.body)
+      { ok: result['success'] }
+    rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout
+      { ok: false }
+    end
+
+    # Clear all apps from a specific source
+    #
+    # @param source [String] The source identifier to clear
+    def clear_source_via_service(source)
+      uri = URI("http://localhost:#{service_port}/clear-source")
+      Net::HTTP.post_form(uri, { source: source })
+    rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout
+      # Service might be down, that's ok during cleanup
+    end
+  end
+end

data/lib/stream_weaver/session_store.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'rack/session/abstract/id'
+require 'fileutils'
+
+module StreamWeaver
+  # ── Session state filters ─────────────────────────────────────────────────
+  # Each store type owns its filter logic. Cookie store guards the 4KB limit;
+  # file store passes state through unchanged.
+
+  module SessionStore
+    class Base
+      # Flash is one-shot (flash-prg.md §1): visible in the response that set
+      # it, never persisted for the next request. Excluding it here -- at the
+      # single point every filter subclass already funnels through -- is what
+      # makes that true; the caller's `state` object itself is untouched, so
+      # the render that already read it for *this* response is unaffected.
+      FLASH_KEY = :_flash
+
+      def filter(state, app_transient: [], scope_names: [])
+        raise NotImplementedError, "#{self.class}#filter not implemented"
+      end
+
+      private
+
+      # Treat nil and empty string as blank — both are equivalent to "unset" for form fields.
+      def blank?(v)
+        v.nil? || v == ""
+      end
+
+      # Recurse exactly one level into hash values that are registered scopes
+      # (App#scope_names) so a blank field buried inside e.g. state[:person_form]
+      # gets stripped too, same as a blank top-level key — FAC-P3.1 §7. Arbitrary
+      # user-managed hash values that were never declared via scope/form/resource
+      # are left opaque, exactly as before.
+      def strip_scoped_blanks(state, scope_names)
+        return state if scope_names.empty?
+        state.each_with_object({}) do |(k, v), result|
+          result[k] = (scope_names.include?(k) && v.is_a?(Hash)) ? v.reject { |_, sv| blank?(sv) } : v
+        end
+      end
+    end
+
+    class FileStore < Base
+      # No size limit, but strip blank values — they'll be re-initialized by ||= on next load.
+      def filter(state, app_transient: [], scope_names: [])
+        strip_scoped_blanks(state, scope_names).reject { |k, v| blank?(v) || k == FLASH_KEY }
+      end
+    end
+
+    class CookieStore < Base
+      HARD_TRANSIENT = %i[code_content current_file_path examples _deck_state].freeze
+      LIMIT_BYTES    = 4096
+      WARN_THRESHOLD = 3072 # warn at 75% capacity
+
+      def filter(state, app_transient: [], scope_names: [])
+        filtered = strip_scoped_blanks(state, scope_names).reject do |k, v|
+          blank?(v) ||
+            k == FLASH_KEY ||
+            HARD_TRANSIENT.include?(k) ||
+            app_transient.include?(k) ||
+            k.to_s.end_with?('_edited_code')
+        end
+        size = JSON.dump(filtered).bytesize
+        if size > WARN_THRESHOLD
+          $stderr.puts "[SW] WARNING: cookie session #{size}B / #{LIMIT_BYTES}B limit — " \
+                       "set SW_SESSION_STORE=file to avoid silent data loss"
+        end
+        filtered
+      end
+    end
+
+    def self.build(store_name)
+      case store_name.to_s
+      when 'file'   then FileStore.new
+      when 'cookie' then CookieStore.new
+      else raise ArgumentError, "Unknown SW_SESSION_STORE '#{store_name}'. Use 'file' or 'cookie'."
+      end
+    end
+  end
+
+  # ── File-backed Rack session middleware ────────────────────────────────────
+  # Stores one Marshal file per session under SW_SESSION_DIR.
+  # Compatible with Rack::Session::Abstract::PersistedSecure (same interface as Pool).
+
+  class FileSession < Rack::Session::Abstract::PersistedSecure
+    DEFAULT_OPTIONS = Rack::Session::Abstract::ID::DEFAULT_OPTIONS.merge(
+      drop:           false,
+      allow_fallback: true,
+      expire_after:   86_400
+    )
+
+    def initialize(app, options = {})
+      @session_dir  = options.delete(:path) { ::File.join(Dir.home, '.config', 'stream_weaver', 'sessions') }
+      @expire_after = options.fetch(:expire_after, DEFAULT_OPTIONS[:expire_after])
+      @allow_fallback = options.fetch(:allow_fallback, DEFAULT_OPTIONS[:allow_fallback])
+      @mutex = Mutex.new
+      FileUtils.mkdir_p(@session_dir)
+      super
+    end
+
+    def generate_sid(*args, use_mutex: true)
+      loop do
+        sid = super(*args)
+        exists = use_mutex ? @mutex.synchronize { file_exists_for?(sid) } : file_exists_for?(sid)
+        break sid unless exists
+      end
+    end
+
+    def find_session(req, sid)
+      @mutex.synchronize do
+        session = sid && fetch_session_data(sid)
+        unless session
+          sid     = generate_sid(use_mutex: false)
+          session = {}
+          # Don't write here — let write_session handle it so we don't create orphan files
+        end
+        [sid, session]
+      end
+    end
+
+    def write_session(req, session_id, new_session, options)
+      @mutex.synchronize do
+        write_file(session_id, new_session)
+        session_id
+      end
+    rescue => e
+      $stderr.puts "[SW] FileSession write error: #{e}"
+      false
+    end
+
+    def delete_session(req, session_id, options)
+      @mutex.synchronize do
+        remove_file(session_id)
+        unless options[:drop]
+          sid = generate_sid(use_mutex: false)
+          write_file(sid, {})
+          sid
+        end
+      end
+    end
+
+    private
+
+    def session_path(sid)
+      id = sid.respond_to?(:private_id) ? sid.private_id : sid.to_s
+      ::File.join(@session_dir, "session_#{id.gsub(/[^a-zA-Z0-9\-]/, '_')}")
+    end
+
+    def file_exists_for?(sid)
+      ::File.exist?(session_path(sid))
+    end
+
+    # Renamed from load_session to avoid overriding Persisted#load_session(req)
+    def fetch_session_data(sid)
+      session = read_session_file(sid.private_id)
+      session ||= read_session_file(sid.public_id) if @allow_fallback && sid.respond_to?(:public_id)
+      session
+    rescue => e
+      $stderr.puts "[SW] FileSession load error: #{e}"
+      nil
+    end
+
+    def read_session_file(raw_id)
+      path = ::File.join(@session_dir, "session_#{raw_id.to_s.gsub(/[^a-zA-Z0-9\-]/, '_')}")
+      return nil unless ::File.exist?(path)
+      if ::File.mtime(path) < Time.now - @expire_after
+        ::File.delete(path)
+        return nil
+      end
+      Marshal.load(::File.binread(path))
+    rescue => e
+      $stderr.puts "[SW] FileSession read error for #{raw_id}: #{e}"
+      nil
+    end
+
+    def write_file(sid, session)
+      ::File.binwrite(session_path(sid), Marshal.dump(session))
+    end
+
+    def remove_file(sid)
+      path = session_path(sid)
+      ::File.delete(path) if ::File.exist?(path)
+    end
+  end
+end

data/lib/stream_weaver/skills/streamweaver-canvas-safe/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: streamweaver-canvas-safe
+description: Use before building a canvas doc, pushing a Save-as-doc that will be reopened later, or running `streamweaver export` — tells you which components stay honest with no backend behind them (canvas-read, an exported file) versus which ones need the live bridge or a real server, so the doc you hand someone doesn't quietly stop working the moment it leaves the live canvas
+---
+
+# StreamWeaver Canvas-Safe
+
+A canvas doc gets rendered in more places than the live canvas it was written for: `canvas-read` opens it with no app session, `streamweaver export` writes it out as a static file with no server at all. Same `.rb`, three runtimes. This skill is the compact version of that story — read it before you reach for a component you haven't checked, and drop into a reference file only when you're actually about to use one of the components it covers.
+
+**Full source of truth:** `docs/frontend-only.md` (compatibility table + mechanisms) and `docs/research/frontend-only-matrix.md` (the ~95-row long tail with source lines and repro commands). This skill is a shorter, action-oriented cut of both — when in doubt, they win.
+
+## The three contexts
+
+| Ctx | Name | Behind it | htmx? | Alpine? |
+|---|---|---|---|---|
+| A | Live canvas | `Canvas::BridgeServer` + WebSocket, an agent may be listening on `canvas-wait` | yes | yes |
+| B | canvas-read | `Canvas::Reader`, render-only, no app session | yes | yes |
+| C | Exported HTML | nothing — a static file | no | only if `x-data` is present |
+
+## Verdict vocabulary
+
+- **WORKS** — full intended function.
+- **DEGRADES** — reduced but honest (disabled control, visible title, read-only state) — the user can see less is on offer.
+- **SILENTLY-DEAD** — renders, looks interactive, does nothing. No error, no visual sign. The one to design out of a doc before it ships.
+- **BREAKS** — errors, blanks, or visibly wrong output.
+
+## Plays well everywhere (WORKS in A, B, and C)
+
+Anything that owns its own state — Alpine `x-data` it never asks an enclosing scope for — or is flat markup with no server dependency. This is the safe backbone for any doc that needs to survive `canvas-read` or an export: `text`, `md`, `header1`–`header6`, `card`/`card_header`/`card_body`, `callout`, `table` (incl. `sortable: true`), `collapsible`/`expandable_card`/`dropdown`, `tabs` (eager, default — **not** `url: true`, see `references/tabs-and-navigation.md`), `sidebar_toc`, `mermaid`, the whole chart family (`chart`, `bar_chart`, `line_chart`, `pie_chart`, `sparkline`, `stacked_bar_chart`, `area_chart`, `hbar_chart`, `doughnut_chart` — fixed 2026-08-23, see `references/charts-and-diagrams.md`), `theme_toggle`/`theme_switcher`/`theme_preset`, `copy_button`, `code_block`, `keyboard_shortcuts` (as a legend), `use_stylesheet`, `doc_header`/`doc_section_header`, `badge`/`status_dot`, and every layout primitive (`columns`, `div`, `section`, `grid`, `vstack`/`hstack`, ...).
+
+**If a doc is built only from this list, it renders identically in a live canvas, `canvas-read`, and an export.** `examples/canvas-safe-showcase.rb` proves it — see below.
+
+## sendEvent-only-on-live-canvas (WORKS in A only)
+
+These dispatch through `window.sendEvent`, which only `Canvas::BridgeServer`'s `cdn_scripts` defines: `button`, `radio_group`, `clickable(action:)`, `menu_item` (action block), `form` submit, `tag_buttons`, `chip_group`. In B (canvas-read) they render honestly `disabled`/`aria-disabled` with an explanatory title — no `ReferenceError`, no self-mutating click. In C (export) htmx never loads, so their `hx-post` fallback never fires either — SILENTLY-DEAD, quiet and invisible. **Use these to build the live-canvas interaction; don't expect them to do anything once the doc is reopened as a saved doc or exported.** Detail + minimal examples: `references/actions-and-buttons.md` and `references/inputs-and-forms.md`. Saving the session **as `.org`** doesn't render them dead — it leaves them out entirely (one `#+STREAMWEAVER_OMITTED: <call>` keyword line each, counted as `omitted` in the save dialog's coverage notice), because a static org document cannot hold a live control. Save as `.rb` when the controls have to come back.
+
+## Needs a real server (`streamweaver run`/`serve` with the routes mounted — not canvas, not canvas-read, not export)
+
+- Per-keystroke sync on `text_field`/`text_area`/`date_field`/`checkbox`/`select`/`checkbox_group` (auto-submit `hx-post /update` — 404s everywhere backend-less; the *value itself* still reaches an agent because `button`'s `getFormState()` harvests the DOM on click, but the field's own auto-submit never fires cleanly). See `references/inputs-and-forms.md`.
+- `design_deck` option selection, notes, generate-more — DEGRADES to honestly read-only wherever `deck_server:` isn't set (canvas, canvas-read, export, and `streamweaver serve` alike). See `references/deck.md`.
+- `modal` opening (server-state driven — can close client-side, can't open without a live push), `route_by`/`route`/`page`, `every`/`stream` (SSE — `AppView`-only, no client at all backend-less), `resource`/`form_for` (routed CRUD), `endpoint(...)`, `tabs lazy: true` (deprecated — blank panels, not this skill's concern to fix).
+- `local_asset` / relative `image_block` src / any `/sw-asset/...` reference — BREAKS everywhere except `--inline-images` on export or a colocated file.
+
+## When to load a reference file
+
+| Building with... | Read |
+|---|---|
+| `text_field`, `checkbox_group`, `chip_group`, `tag_buttons`, `form` blocks | `references/inputs-and-forms.md` |
+| `button`, `clickable`, `menu_item`, submit buttons | `references/actions-and-buttons.md` |
+| `mermaid`, `chart`/`bar_chart`/etc. | `references/charts-and-diagrams.md` |
+| `tabs`, `collapsible`, `dropdown`, `modal`, `route_by` | `references/tabs-and-navigation.md` |
+| `design_deck` | `references/deck.md` |
+
+Each reference file is advice plus a minimal working DSL snippet plus the one gotcha that actually bites — load it only when you're about to use that component, not up front.
+
+## The comprehensive example
+
+`examples/canvas-safe-showcase.rb` is a bare DSL body (`streamweaver-doc: v1`, no `app` wrapper — see `streamweaver-doc-builder` for the shared-body pattern) built entirely from the plays-well-everywhere list above. It was verified to render correctly — no silently-dead component, no missing script pairing — in all three contexts: pushed through the real bridge (websocket adapter, context A), served by `Canvas::Reader` (context B, `SW_NO_OPEN=1`, ephemeral port, killed and `lsof`-verified after), and run through `streamweaver export` (context C). Use it as the starting skeleton for a doc that must survive being saved and reopened later, or exported and handed to someone with no server at all.
+
+It deliberately does **not** include any sendEvent-only component (button, radio_group, ...) — adding one is a live-canvas-only enhancement to layer on top, not part of the guaranteed-everywhere core. See `references/actions-and-buttons.md` for how to add interactivity honestly.
+
+## Known gotchas (cross-cutting, see `docs/frontend-only.md` for the full list)
+
+- **Bare `x-model` with no owning `x-data` is silently-dead everywhere backend-less** — console-clean, no error. Every component above either owns its own `x-data` or uses server-round-trip inputs (which are covered under "needs a real server").
+- **`canvas-wait`'s default only catches `action` events** (`button`, `clickable`, `menu_item`, `form` submit). `tag_buttons` and `chip_group` dispatch `change` — pass `--event change` or `--any`.
+- **A CSP-locked viewer breaks every Alpine-dependent component in an export**, even ones marked WORKS above (tabs, collapsible, dropdown, theme_toggle) — `x-cloak` content never un-hides. `--offline` on export only inlines mermaid, not Alpine.

data/lib/stream_weaver/skills/streamweaver-canvas-safe/examples/canvas-safe-showcase.rb

@@ -0,0 +1,98 @@
+# streamweaver-doc: v1
+# Canvas-safe showcase — every component below is drawn from the
+# plays-well-everywhere list in SKILL.md. Verified to render correctly with
+# no silently-dead component and no missing script pairing in all three
+# backend-less contexts: the live bridge (websocket adapter), Canvas::Reader
+# (canvas-read), and `streamweaver export`. Deliberately carries no
+# sendEvent-only component (button, radio_group, ...) — see
+# references/actions-and-buttons.md for how to layer live-canvas
+# interactivity on top of a doc built from this skeleton.
+
+sidebar_toc sections: [
+  { id: "overview", label: "Overview" },
+  { id: "data", label: "Data" },
+  { id: "diagram", label: "Diagram" }
+]
+
+doc_header(
+  eyebrow: "streamweaver-canvas-safe · example",
+  title: "Canvas-Safe Component Showcase",
+  pills: [{ text: "Reference" }, "Renders identically in canvas, canvas-read, and export"]
+)
+
+doc_section_header "01", "Overview", id: "overview"
+
+md <<~MD
+  Every component on this page owns its own state — either it's flat markup with
+  no server dependency, or it's Alpine `x-data` that never asks an enclosing
+  scope for anything. That's the whole trick: nothing here round-trips, so
+  nothing here has anything to lose when the doc is reopened with no backend
+  behind it.
+MD
+
+callout(variant: :info, title: "Why this matters") do
+  text "A doc built only from this component set survives being saved and reopened " \
+       "later, or exported and handed to someone with no StreamWeaver server running " \
+       "at all — byte-for-byte the same interactivity in every context."
+end
+
+card do
+  card_header "Status", badge: "Live", meta: "plays-well-everywhere"
+  card_body do
+    status_dot(status: :green)
+    text "All components below: WORKS in canvas, canvas-read, and export"
+    md "Collapse the section below to see client-side Alpine state that never touches a server."
+  end
+end
+
+collapsible "Show implementation notes" do
+  md "This panel opens and closes via Alpine `x-show` — no request, no round-trip, " \
+     "identical behavior whether a bridge is listening or not."
+end
+
+tabs :showcase_tabs do
+  tab "Plain tabs" do
+    text "Eager, client-side tabs (no url: true) — pure @click state, works everywhere."
+  end
+  tab "Why not url: true?" do
+    text "tabs url: true degrades on canvas (plain client tabs + an agent-only stderr " \
+         "warning) but becomes MORE capable in an export (real pushState routing). " \
+         "See references/tabs-and-navigation.md."
+  end
+end
+
+doc_section_header "02", "Data", id: "data"
+
+table(
+  headers: ["Component", "A live canvas", "B canvas-read", "C export"],
+  rows: [
+    ["Everything on this page", "WORKS", "WORKS", "WORKS"],
+    ["button / clickable / form submit", "WORKS", "DEGRADES", "SILENTLY-DEAD"],
+    ["text_field auto-submit", "DEGRADES", "SILENTLY-DEAD", "SILENTLY-DEAD"]
+  ],
+  sortable: true
+)
+
+bar_chart data: { canvas: 3, "canvas-read": 3, export: 3 }
+
+doc_section_header "03", "Diagram", id: "diagram"
+
+mermaid <<~MERMAID
+  graph LR
+    A["Same .rb file"] --> B["Live canvas (A)"]
+    A --> C["canvas-read (B)"]
+    A --> D["streamweaver export (C)"]
+    B --> E["Identical render"]
+    C --> E
+    D --> E
+MERMAID
+
+code_block(<<~RUBY, lang: "ruby", copy: true)
+  # Pushed to a live canvas...
+  streamweaver canvas-push showcase < canvas-safe-showcase.rb
+  # ...or exported as a static file...
+  streamweaver export canvas-safe-showcase.rb -o showcase.html
+  # ...same DSL, same rendered result either way.
+RUBY
+
+theme_toggle

data/lib/stream_weaver/skills/streamweaver-canvas-safe/references/actions-and-buttons.md

@@ -0,0 +1,47 @@
+# Actions and Buttons
+
+Seven components dispatch through `window.sendEvent`, which only the live bridge's `cdn_scripts` defines (context A). All seven share the same three-context shape: **WORKS on the live canvas, DEGRADES-honest on canvas-read, SILENTLY-DEAD in an export.** There is no way to make click-driven interactivity survive an export — a static file has nothing to dispatch to. Design around that instead: use these for the live-canvas conversation loop, and lean on the plays-well-everywhere list (SKILL.md) for anything that has to survive being saved and reopened.
+
+## button
+
+```ruby
+button "Submit" do |state|
+  # runs when clicked, on the live canvas, with an agent listening on canvas-wait
+end
+
+button "Preview only", submit: false  # decorative — WORKS in all three contexts, never dispatches
+```
+
+Default `button` dispatches `sendEvent('action', {button: <token>, state: getFormState()})`. With no `canvas-wait` holder listening, the click still fires `showFeedback()` and replaces the container with "✓ Submitted" — the page is gone even though nothing consumed the event, so always have something waiting before you tell a user to click.
+
+## clickable(action:)
+
+```ruby
+clickable(action: :open_row, key: "r1") { text "Row" }
+```
+
+Ported to `sendEvent('action')` (disc-097) — same payload shape as `button`. Can't be natively `disabled` (it's a `<div>`), so on canvas-read it drops `aria-disabled` + no `tabindex` instead of `disabled` — a focusable element that does nothing would be its own lie.
+
+## menu_item (action block)
+
+```ruby
+dropdown do
+  menu do
+    menu_item("Archive") { |state| state[:archived] = true }
+  end
+end
+```
+
+Dispatches `sendEvent('action', {button: 'menu_item_N', ...})`; the menu still closes on dispatch, live canvas only.
+
+## Waiting on the right event
+
+`canvas-wait`'s default only catches `action` events (`button`, `clickable`, `menu_item`, `form` submit). `tag_buttons` and `chip_group` dispatch `change` instead — mirroring `radio_group` since they're a state change, not a submission. Pass `--event change` or `--any` if your doc's only dispatching control is one of those two, or the wait will hang forever on an event that's never coming.
+
+## Quoting
+
+Author-supplied strings reaching a JS handler (tag labels, menu item text) route through JSON quoting — an apostrophe in a label won't produce a JS syntax error. The one exception is `external_link_button`'s `window.open(url)` call, which is emitted identically in HTTP and canvas mode by design (quoting it would change HTTP-mode output); an unquoted URL there is a known, tracked edge case (disc-107), not something this skill's examples exercise.
+
+## The gotcha
+
+None of these components render any different markup between "will dispatch to an agent" and "will replace the page with a submitted-state placeholder because nobody's listening." Before telling a user to click a button, make sure a `canvas-wait` (with the right `--event`) is actually running — otherwise the click looks like it worked and just wasn't heard.

data/lib/stream_weaver/skills/streamweaver-canvas-safe/references/charts-and-diagrams.md

@@ -0,0 +1,38 @@
+# Charts and Diagrams
+
+Both families WORK in all three contexts. This is the one area where the fix (chart-export-allowlist, 2026-08-23) is recent enough to be worth restating rather than assuming.
+
+## Charts
+
+```ruby
+bar_chart data: { calendar: 45, news: 120, tasks: 30 }
+hbar_chart data: { "Phase A" => 25, "Phase B" => 45 }
+line_chart data: { jan: 10, feb: 25, mar: 18 }
+pie_chart data: { chrome: 60, safari: 25, firefox: 15 }
+sparkline data: [3, 7, 4, 9, 2, 8]
+stacked_bar_chart data: [{ label: "Q1", series: { a: 10, b: 20 } }]
+area_chart data: { jan: 10, feb: 25, mar: 18 }
+doughnut_chart data: { chrome: 60, safari: 25, firefox: 15 }
+chart type: :bar, data: { a: 1, b: 2 }  # the base component directly
+```
+
+Every one of the shorthand methods above builds a `ChartBase` subclass under the hood, not `Components::Chart` itself. Before 2026-08-23, `streamweaver export`'s CDN-inclusion check tested `is_a?(Components::Chart)` — so every shorthand method failed the check while `chart type: ...` passed it. The exported markup still carried the guarded `x-init="if (typeof Chart !== 'undefined') { new Chart(...) }"`, so nothing threw; you got an empty bordered box, console-silent, that looked like a rendering glitch rather than a missing library. **Fixed:** the gate now checks `components_include?(Components::Chart) || components_include?(Components::ChartBase)` — the whole family, keyed on the base class so a future chart subclass can't silently join the dead list the way the shorthand methods did.
+
+## Mermaid
+
+```ruby
+mermaid <<~MERMAID
+  graph LR
+    A["Calendar"] --> B["Sync script"] --> C["state.yaml"]
+MERMAID
+
+mermaid diagram_code, zoom: true      # pan/zoom controls
+mermaid diagram_code, compact: true   # reduced padding for card embedding
+mermaid diagram_code, layout: :elk    # note: --offline export has no global ELK build
+```
+
+`sw-mermaid-zoom.js` (the interaction engine) is inlined and travels into every export; the mermaid *library itself* is CDN-referenced by default. `streamweaver export --offline` inlines the mermaid library so diagrams survive a CSP-locked viewer — but that flag covers mermaid only, not Alpine or Prism, and it doesn't help `layout: :elk` (no global ELK build to inline).
+
+## The gotcha
+
+Don't assume "WORKS in all three contexts" from this file also means "survives a CSP-locked viewer with no flags." A default (non-`--offline`) export still loads the chart/mermaid CDN scripts over the network — a CSP that blocks external hosts breaks them exactly like it breaks Alpine. `--offline` closes the mermaid gap; nothing closes the Chart.js one yet if you need a fully offline, CSP-safe chart export.

data/lib/stream_weaver/skills/streamweaver-canvas-safe/references/deck.md

@@ -0,0 +1,32 @@
+# Design Deck
+
+`design_deck` navigation (moving between slides, `slide_container`/`slide`) is plain inlined JS (`sw-slide-nav.js`) — WORKS in every context, no server needed. Everything below is about the interactive part: option selection, notes, generate-more, model selection.
+
+```ruby
+design_deck "Design Options" do
+  slide "arch", "Architecture" do
+    option("Monolith") { text "Simple, one deploy unit" }
+    option("Microservices") { text "Scales independently, more ops" }
+  end
+end
+```
+
+## What changed 2026-08-23 (disc-096)
+
+**Before:** `swDeckSelect` applied the selected CSS class and `aria-checked` **before** calling `fetch('/deck/select')`, with no `.catch`. Every backend-less context — canvas, canvas-read, export — has no `/deck/*` route, so the fetch 404s (or fails outright) and the failure was swallowed. The user saw a confirmed selection that was never recorded and never reached anything. Not just dead — it actively lied about recorded state, `aria-checked` included.
+
+**After:** confirmation is success-gated. Visual/aria state only changes after the POST resolves; a failed request surfaces a console error naming the route and reason, and applies no visual change. An `aria-busy` state covers the in-flight moment. Separately, the whole interactive surface (option cards, notes textarea, submit, generate-more, model selector) renders **read-only** wherever `/deck/*` genuinely doesn't exist — gated by a `deck_server:` construction flag the adapter carries, set correctly at every render site including canvas, canvas-read, export, and `streamweaver serve` (service mode never mounted `/deck/*` either — a second, previously-undocumented instance of the same bug, now covered too).
+
+## Where it WORKS vs. where it's read-only
+
+| Context | Deck interactivity |
+|---|---|
+| `streamweaver run` (real standalone server, `/deck/*` mounted) | WORKS — confirmation lands slightly after the click now (the fix), not before |
+| Live canvas (A) | DEGRADES — honestly read-only, `/deck/*` doesn't exist here |
+| canvas-read (B) | DEGRADES — same |
+| Export (C) | DEGRADES — same |
+| `streamweaver serve` (service mode) | DEGRADES — read-only, same previously-undocumented bug, now covered |
+
+## The gotcha
+
+If you're building a doc meant to demo option selection interactively, `design_deck` will render but every click will be inert (honestly, not silently) unless it's opened under a real `streamweaver run` server that mounts `/deck/*`. Don't put deck-selection interactivity in a doc you intend to Save-as-doc and reopen later, or export — it'll render fine and simply not accept input in either context. There's also a separate, still-open gap: the deck JS posts to `/deck/*` by absolute path, ignoring the adapter's `url_prefix` — so even a service-mode app that mounted deck routes under a prefix would post to the wrong place. That's why today's fix makes it read-only rather than pointing it at the prefixed route; url-prefixing the deck JS is a prerequisite for ever flipping `deck_server: true` under `streamweaver serve`.

data/lib/stream_weaver/skills/streamweaver-canvas-safe/references/inputs-and-forms.md

@@ -0,0 +1,65 @@
+# Inputs and Forms
+
+Every plain input (`text_field`, `text_area`, `date_field`, `checkbox`, `select`) auto-submits via a debounced `hx-post /update` on every keystroke or change. That request 404s on every backend-less context (A, B, C) — it needs `streamweaver run`/`serve` with the update route mounted. This is disc-106, tracked and deliberately out of scope; know it going in rather than chase a phantom 404 in the console.
+
+The good news: on the live canvas (A), the value still reaches an agent — just not through the field's own auto-submit. `getFormState()` walks the DOM for every `[x-model]` element at the moment some *other* `sendEvent`-carrying control fires (a `button`, `clickable`, a form submit). So a `text_field` sitting next to a `button` works as a value carrier even though its own round-trip never completes.
+
+```ruby
+text_field :city, placeholder: "City"
+button "Submit" do |state|
+  # state[:city] is populated from getFormState() on the live canvas
+end
+```
+
+If you don't want the debounced 404 noise on canvas, pass `submit: false` — the field becomes an inert value carrier with no auto-submit at all (DEGRADES honestly instead of failing silently):
+
+```ruby
+text_field :city, submit: false
+```
+
+## checkbox_group — array harvest, not auto-submit
+
+```ruby
+checkbox_group :selected_items, select_all: "Select All", select_none: "Clear" do
+  items.each { |item| item(item.id) { text item.name } }
+end
+# button click elsewhere harvests state[:selected_items] = ["id1", "id3"]
+```
+
+**Fixed 2026-08-23 (disc-098):** the harvest used to collapse every group to the *last* checked item's boolean — confidently wrong data, worse than dead. It's fixed now: items inside a `.checkbox-group` accumulate into an array; a lone `checkbox` outside a group still returns a boolean. `checkbox_group` itself was never ported to `sendEvent` — its auto-submit still 404s everywhere backend-less, same as the plain inputs above. The array only leaves the page when another control's click harvests it.
+
+## chip_group — multi-select, sendEvent-ported
+
+```ruby
+chip_group :langs, %w[ruby js python]              # multi: true by default
+chip_group :lang, %w[ruby js python], multi: false  # single-select
+```
+
+Ported to `sendEvent('change')` on the live canvas (disc-097) — dispatches `{field: :langs, value: [...], state: getFormState()}` on every click, array-harvest-correct. See `references/actions-and-buttons.md` for the sendEvent-only-on-live-canvas rundown; canvas-read renders it honestly `aria-disabled`, export falls back to a dead `hx-post`.
+
+## tag_buttons — sendEvent-ported
+
+```ruby
+tag_buttons :category, ["Fiction", "Non-fiction", "Mystery"]
+```
+
+Same disposition as `chip_group`: `sendEvent('change')` on the live canvas, honest `aria-disabled` on canvas-read, dead `hx-post` in export.
+
+## form blocks
+
+```ruby
+form :edit_person do
+  text_field :name, placeholder: "Name"
+  select :status, %w[active paused archived]
+  submit "Save" do |form_values|
+    # form_values = { name: "...", status: "..." }
+  end
+  cancel "Cancel"
+end
+```
+
+`submit` dispatches through `sendEvent('action')` on the live canvas (disc-097 — `form` was the one auto-submit-based component that got fully ported, not just harvest-fixed). `cancel` is Alpine-only client-side reset, so it works in all three contexts.
+
+## The gotcha
+
+Checking a box or typing into a field, by itself, sends **nothing** anywhere. Only a `sendEvent`-carrying control's click harvests the current DOM state. If your doc's only interactive elements are plain inputs with no `button`/`clickable`/`form submit` alongside them, nothing an agent waits on will ever fire — the fields will look interactive (you can type, you can check boxes) and simply never report anywhere. Always pair inputs with at least one dispatching control.