stream_weaver 0.3.0

data/docs/ideas/dhh-review-future-refactors.md

@@ -0,0 +1,142 @@
+# DHH Review: Future Refactors
+
+Notes from DHH-style code review of service mode implementation (2026-01-02).
+
+## Route Duplication Between Service and SinatraApp
+
+The `/apps/:app_id/update`, `/apps/:app_id/action/:button_id`, `/apps/:app_id/event/:key`, and `/apps/:app_id/form/:form_name` routes in `service.rb` are nearly identical to their counterparts in `server.rb`. Extract shared logic to `RouteHelpers` module.
+
+```ruby
+# lib/stream_weaver/route_helpers.rb
+module StreamWeaver
+  module RouteHelpers
+    def coerce_param_value(value, current_value)
+      case
+      when value.is_a?(Array)               then value
+      when %w[on true].include?(value)      then true
+      when value == "false"                 then false
+      when current_value.is_a?(Array)       then Array(value)
+      else                                  value
+      end
+    end
+
+    def sync_params_to_state(state, excluded_keys: [])
+      excluded = %w[splat captures app_id button_id] + excluded_keys.map(&:to_s)
+      params.each do |key, value|
+        next if excluded.include?(key)
+        state[key.to_sym] = coerce_param_value(value, state[key.to_sym])
+      end
+    end
+  end
+end
+```
+
+## PID File Management Should Be Its Own Class
+
+Extract PID file logic from Service (lines 96-129) to dedicated class:
+
+```ruby
+# lib/stream_weaver/pid_file.rb
+module StreamWeaver
+  class PidFile
+    PATH = File.expand_path('~/.streamweaver/server.pid').freeze
+
+    class << self
+      def write(port:)
+        FileUtils.mkdir_p(File.dirname(PATH))
+        File.write(PATH, "port=#{port}\npid=#{Process.pid}\n")
+      end
+
+      def delete
+        File.delete(PATH) if File.exist?(PATH)
+      end
+
+      def read
+        return unless File.exist?(PATH)
+        content = File.read(PATH)
+        { port: content[/port=(\d+)/, 1]&.to_i,
+          pid:  content[/pid=(\d+)/, 1]&.to_i }
+      end
+
+      def process_alive?
+        info = read or return false
+        Process.kill(0, info[:pid])
+        true
+      rescue Errno::ESRCH
+        delete
+        false
+      end
+    end
+  end
+end
+```
+
+## Admin Inline Styles Should Use Semantic CSS Classes
+
+The Admin class has inline styles everywhere. Should use semantic classes that reference the theme system:
+
+```ruby
+# Before
+div style: "display: inline-flex; align-items: center; gap: 0.5rem; ..." do
+
+# After
+div class: "admin-status-bar" do
+  status_indicator :running, "Port #{Service.settings.port}"
+end
+```
+
+## CLI Repetitive Error Handling
+
+Every CLI method that contacts the service has identical error handling. Extract to helper:
+
+```ruby
+# Before: Repeated 5+ times
+rescue Errno::ECONNREFUSED
+  puts "Error: Could not connect to StreamWeaver service"
+  exit 1
+end
+
+# After
+def self.with_service_connection
+  yield
+rescue Errno::ECONNREFUSED
+  puts "Error: Could not connect to StreamWeaver service"
+  exit 1
+end
+```
+
+## CLI Case Statement Could Be More Declarative
+
+```ruby
+# After: Declarative command mapping
+COMMANDS = {
+  'serve'   => :serve,
+  'run'     => :run_app,
+  'list'    => :list_apps,
+  'remove'  => ->(args) { remove_app(args.first) },
+  # ...
+}.freeze
+
+def self.run(args)
+  return help if args.empty?
+  command = args.shift
+  handler = COMMANDS[command]
+
+  case handler
+  when Symbol then send(handler, args)
+  when Proc   then handler.call(args)
+  when nil    then handle_unknown_command(command, args)
+  end
+end
+```
+
+## Remove Comment Banners
+
+The Service class has banner comments like:
+```ruby
+# =========================================
+# Service Management Routes
+# =========================================
+```
+
+Well-organized code documents itself through structure. If you need a banner to find routes, the class is too large.

data/docs/opal-jamstack.md

@@ -0,0 +1,47 @@
+# StreamWeaver Goes Static
+
+You've always been able to write reactive, server-rendered UIs without touching JavaScript. Now the same Ruby DSL runs entirely in the browser — no server, no round-trips, no ops.
+
+Here's a complete interactive app:
+
+```ruby
+app "Hello World" do
+  header1 "Welcome to StreamWeaver!"
+
+  text_field :name, placeholder: "Enter your name"
+
+  if state[:name] && state[:name].strip != ""
+    text "Hello, #{state[:name]}!"
+
+    checkbox :subscribe, "Subscribe to newsletter"
+
+    if state[:subscribe]
+      text "You're subscribed!"
+    end
+  end
+end
+```
+
+That's not a server app stripped of its `require` lines. That is the whole thing — identical DSL, running in-browser via Opal. State lives in the page. Interactions re-execute the block and patch the DOM with morphdom. No server involved.
+
+## One command to deploy
+
+```bash
+streamweaver opal-build app.rb
+```
+
+That produces a `dist/` folder: `index.html`, `app.js`, `morphdom.min.js`. Drag it to GitHub Pages, Netlify, S3 — anywhere that serves files. Done.
+
+## What this is not
+
+It's not React. It's not Next.js. There's no webpack config, no `package.json`, no `node_modules`, no TypeScript compilation step, no context switch between your "frontend language" and your "backend language" because there is only one language. You write Ruby. You ship Ruby. The toolchain is one gem.
+
+The mental model stays the same whether you're building a server-rendered dashboard or a static page: declare what the UI looks like given the current state, let StreamWeaver figure out the rest.
+
+## Phase 1 — honest about scope
+
+The core components are covered: `app`, `header`, `text_field`, `checkbox`, `button`, `md`, `div`. State is fully reactive in-browser.
+
+What's not there yet: `feed`, `streamer`, and `service_client` (they require a server by definition), plus `mermaid`, `chartjs`, `tabs`, and `table` (coming in Phase 2). If your app uses those, keep running it server-side — that path isn't going anywhere.
+
+Full component parity is the goal. Phase 1 gets you surprisingly far.

data/docs/opal-npm-direction.md

@@ -0,0 +1,184 @@
+# StreamWeaver → Opal → NPM: Direction Document
+
+**Author:** Forrest Chang  
+**Date:** May 2026  
+**Status:** Vision / Future Work — Do Not Pursue Until Prerequisites Met  
+**Purpose:** Preserve this architectural vision so it's not lost. This is a north star, not a sprint.
+
+---
+
+## The Vision
+
+StreamWeaver is currently a Ruby gem with a Sinatra server backend. The vision: **package StreamWeaver as an NPM module via Opal's "Sole" engine**, making it installable as:
+
+```bash
+npm install stream-weaver
+```
+
+This would allow JavaScript developers to use a Ruby-authored reactive UI framework **without knowing Ruby**. They import it, write component trees in JS (which would be Opal-transpiled Ruby API), and get all the same reactive rendering, component library, and DSL expressiveness — in their existing JS stack.
+
+This is a compelling story for reaching the much larger JavaScript ecosystem while keeping the canonical source of truth in Ruby.
+
+---
+
+## What Already Exists
+
+### Opal Adapter
+`lib/stream_weaver/adapter/opal.rb` — an Opal-compatible adapter layer already exists. This was written with browser execution in mind.
+
+### Opal Runtime
+`lib/stream_weaver/opal/runtime.rb` contains:
+- `OpalRuntime` — Opal-clean entry point
+- `OpalBridge` — browser ↔ Ruby communication bridge
+- `ReactiveState` — client-side reactive state, already Opal-clean
+
+These three modules are **already ready** for Opal compilation. They have no server-side dependencies.
+
+### JS Stubs
+`lib/stream_weaver/opal/stubs/` contains stubs for:
+- `marked.umd.js` — markdown rendering (browser equivalent of kramdown)
+- `morphdom.min.js` — DOM diffing
+
+### Opal Compatibility Spike
+`bin/opal_spike.rb` — an existing spike script that tests which modules compile cleanly through Opal. Run this to audit current compilation status.
+
+---
+
+## What "Sole" Does
+
+Opal's **Sole** engine is the build tool that makes Ruby→NPM publishing practical:
+
+1. Reads your `.gemspec`
+2. Generates a `package.json` from gem metadata
+3. Compiles all Ruby source files to JavaScript via Opal
+4. Creates an `index.js` entry point that exports your Ruby classes/modules as JS
+5. Enables `npm publish` — the package is now installable like any JS library
+
+The result: `npm install stream-weaver` gives a JS developer access to `StreamWeaver.canvas()`, reactive state, and all components, backed by Opal's Ruby runtime in the browser.
+
+---
+
+## The Technical Gap
+
+### What Can't Run in a Browser
+
+The current server layer has components that fundamentally cannot run in a browser:
+
+| Server Concern | Why It Can't Go to Browser |
+|---------------|---------------------------|
+| Sinatra HTTP server | No server socket in browser |
+| Canvas Bridge WebSocket server | No TCP listener in browser |
+| `kramdown` gem (Markdown) | Server-side Ruby gem, no browser equivalent |
+| File I/O for table loading | No filesystem access in browser |
+| Prism.js CDN loading via server | Needs to be bundled or loaded differently |
+
+### The Replacement Model
+
+Instead of a server → client push model, the Opal version needs a **pure client-side reactive model**:
+
+```
+Ruby DSL (compiled by Opal) → OpalRuntime → OpalBridge → DOM
+                                    ↕
+                              ReactiveState
+                              (in-memory, browser)
+```
+
+The server is replaced by in-browser reactive state. Component updates are DOM mutations, not WebSocket pushes.
+
+**The good news:** `OpalRuntime`, `OpalBridge`, and `ReactiveState` already implement this model. They were written with Opal in mind.
+
+### Remaining Gaps to Close
+
+Before a full Opal build would succeed:
+
+#### 1. `components.rb` — Server-Side Concerns
+- `kramdown` calls need to be replaced with `marked.umd.js` (stub already exists)
+- File I/O for table data loading needs an Opal stub or in-memory equivalent
+- Any `require 'json'` or `require 'tempfile'` needs Opal stubs
+
+#### 2. `display_dsl.rb` — Server-Side Concerns
+- Prism.js loading pattern needs to be browser-native (script tag or bundled)
+- Any server-side rendering helpers need client-side equivalents
+
+#### 3. WebSocket → In-Memory Events
+`canvas_bridge.rb` uses WebSockets. The Opal version needs to replace this with an in-browser event bus (custom events or a simple pub/sub).
+
+#### 4. Sole Configuration
+A `stream-weaver.gemspec` needs Sole-compatible metadata and the Opal build needs to be configured to exclude the server layer files entirely.
+
+---
+
+## Minimal Viable NPM Path
+
+Rather than porting the entire feature set at once, there's a pragmatic MVP:
+
+**MVP Scope:** Just the reactive core
+
+```
+OpalRuntime          ← Opal-clean ✅
+OpalBridge           ← Opal-clean ✅
+Opal adapter         ← Opal-clean ✅
+Basic components     ← ~20 most-used components, stubs for server deps
+ReactiveState        ← Opal-clean ✅
+```
+
+**What's excluded from MVP:**
+- Mermaid (external library dependency)
+- Chart.js integration (manageable but deferred)
+- Prism.js code blocks (deferred)
+- Slide container (deferred)
+- All navigation/server-rendered concerns
+
+The MVP would demonstrate:
+- `npm install stream-weaver` works
+- `import StreamWeaver from 'stream-weaver'` gives you a working reactive component tree
+- Basic layout, cards, text, stat displays, progress bars all render
+- Reactive state updates propagate to DOM
+
+This is enough to be interesting to JS developers and validate the concept.
+
+---
+
+## Strategic Framing
+
+### Do This AFTER Traction
+
+The NPM story is most compelling when there's proven Ruby-side value to port. The sequence should be:
+
+1. ✅ **Build the Ruby gem to be feature-rich** — fill the audit gaps, get to parity with artifact aesthetic
+2. ✅ **Publish the gem publicly** — RubyGems, documentation, README with demos
+3. ✅ **See community adoption** — GitHub stars, issues filed by others, blog posts, use in production
+4. 🔜 **Then pursue NPM** — "The Ruby reactive UI framework that JS developers can also use"
+
+Pursuing NPM too early means spending engineering time on a complex cross-compilation build before there's proven demand. The JS community will be more receptive to "port this popular Ruby thing" than "try this new thing that happens to be Ruby inside."
+
+### The Narrative When the Time Is Right
+
+> "StreamWeaver is Streamlit for Ruby — and now you can use it from JavaScript too, without ever touching Ruby. All the expressiveness of a Ruby DSL, compiled to JavaScript by Opal, available on NPM."
+
+This is a genuinely novel story. Opal's NPM publishing via Sole is underutilized. StreamWeaver would be a showcase of what's possible.
+
+---
+
+## Technical Checklist (When Ready to Execute)
+
+- [ ] Run `bin/opal_spike.rb` — document which modules compile cleanly and which fail
+- [ ] Create Opal stubs for `kramdown`, file I/O, and WebSocket dependencies
+- [ ] Audit `components.rb` for every `require` and server assumption
+- [ ] Audit `display_dsl.rb` same
+- [ ] Implement in-browser event bus to replace WebSocket canvas bridge
+- [ ] Configure Sole build with gemspec metadata
+- [ ] Build and test MVP component set in a browser via Opal
+- [ ] Publish `stream-weaver` to NPM (scoped or unscoped)
+- [ ] Write JS-facing documentation (different audience from Ruby docs)
+
+---
+
+## References
+
+- Opal documentation: https://opalrb.com
+- Sole (Opal NPM bridge): https://github.com/opal/opal (see `sole` tooling)
+- Existing Opal adapter: `lib/stream_weaver/adapter/opal.rb`
+- Existing Opal runtime: `lib/stream_weaver/opal/runtime.rb`
+- Opal spike: `bin/opal_spike.rb`
+- JS stubs: `lib/stream_weaver/opal/stubs/`

data/docs/opal-spike-findings.md

@@ -0,0 +1,194 @@
+# Opal Compatibility Spike Findings
+
+**Spike date:** 2026-04-29
+**Opal version:** 1.8.2
+**Ruby version:** 3.3.5
+
+## Summary
+
+All 7 candidate files compile cleanly under Opal when missing-require errors are suppressed (syntax-only pass). Two files have `require` statements for standard library modules unavailable in Opal. These are fixable by conditionally guarding the requires or replacing the calls. There are no fundamental syntax incompatibilities in the target files.
+
+---
+
+## Files and Results
+
+### Files that compiled cleanly (no issues at all)
+
+| File | Result |
+|---|---|
+| `lib/stream_weaver/version.rb` | OK |
+| `lib/stream_weaver/utils.rb` | OK |
+| `lib/stream_weaver/theme.rb` | OK |
+| `lib/stream_weaver/components.rb` | OK |
+| `lib/stream_weaver/adapter/base.rb` | OK |
+
+### Files with missing-require issues (fixable)
+
+| File | Missing require | Impact |
+|---|---|---|
+| `lib/stream_weaver/display_dsl.rb` | `require 'digest/md5'` | Inside `DisplayDSL#button` at runtime — for generating stable button IDs |
+| `lib/stream_weaver/app.rb` | `require 'digest'`, `require 'set'` | `digest` for `Digest::MD5` in `App#button`; `set` for `@transient_keys = Set.new` |
+
+**Note:** `set`, `json`, `cgi`, `base64`, and `ostruct` ARE available in Opal's stdlib. Only `digest` and `digest/md5` are missing from Opal.
+
+**All 7 files pass Opal syntax compilation when `missing_require_severity: :ignore` is used.**
+
+---
+
+## Missing Requires Analysis
+
+### `digest` / `digest/md5`
+
+Used for: generating stable 8-character hex IDs for buttons from source location or label+id pair.
+
+**Where:** `display_dsl.rb:580` (in `DisplayDSL#button`) and `app.rb:3` (top-level require) + `app.rb:326` (in `App#button`).
+
+**Workarounds:**
+1. **Best for Opal:** Replace `Digest::MD5.hexdigest(id_input)[0..7]` with a pure-Ruby FNV or djb2 hash (no stdlib needed). This is the recommended approach for the Opal adapter.
+2. **Conditional guard:** `require 'digest/md5' unless RUBY_PLATFORM == 'opal'` — but this leaks server/client coupling into shared files.
+3. **OpalRenderer handles button IDs independently** — the Opal runtime can use JS `Date.now()` or a counter; the Ruby-side `stable_id` is server-only.
+
+**Recommended resolution:** The Opal runtime/renderer does not need stable IDs from Ruby — buttons in the browser are handled via JS event listeners, not HTMX post-backs. The `DisplayDSL#button` and `App#button` methods can be overridden in `adapter/opal.rb` without the `digest` dependency.
+
+### `require 'set'` in `app.rb`
+
+`Set` IS available in Opal's stdlib (`stdlib/set.rb`). However, the `require 'set'` at the top of `app.rb` will trigger a missing-require warning in strict mode — but since Opal includes `set.rb` in its stdlib, this resolves correctly at runtime. **No action needed.**
+
+Wait — re-checking: Opal's stdlib has `set.rb` but it needs to be added to the Opal path. In practice, when using `missing_require_severity: :ignore`, `Set` will be undefined at runtime unless explicitly included. The `opal_entry.rb` build step should add `require 'set'` before bundling, or stub it.
+
+**Resolution:** Add `require 'set'` to the Opal bundle entrypoint build configuration.
+
+---
+
+## Opal Standard Library Availability
+
+| Library | In Opal | Notes |
+|---|---|---|
+| `set` | YES (`stdlib/set.rb`) | Must be explicitly included in bundle |
+| `json` | YES (`stdlib/json.rb`) | Must be explicitly included in bundle |
+| `cgi` | YES (`stdlib/cgi.rb`) | Must be explicitly included in bundle |
+| `base64` | YES (`stdlib/base64.rb`) | Must be explicitly included in bundle |
+| `ostruct` | YES (`stdlib/ostruct.rb`) | Must be explicitly included in bundle |
+| `digest` | NO | Not in Opal core or stdlib — replace with pure-Ruby hash |
+| `digest/md5` | NO | Same as above |
+
+---
+
+## kramdown Opal Compatibility
+
+**Result: NOT Opal-safe for production use.**
+
+When kramdown's gem `lib/` is added to Opal's load path:
+- Compiles with `missing_require_severity: :ignore` but produces warnings:
+  - "Cannot handle dynamic require" — `kramdown/document.rb:130`, `kramdown/converter.rb:39`, `kramdown/converter.rb:55`
+  - "Skipping the 'o' Regexp flag as it's not widely supported by JavaScript vendors" — multiple occurrences in `kramdown/parser/html.rb`
+- Fails strict compilation with `MissingRequire` on `kramdown/converter/math_engine/`
+- kramdown uses `require` with dynamic strings (string interpolation), which Opal cannot resolve
+
+**Conclusion:** `render_markdown` in the Opal renderer MUST use `marked.js` via JS interop (or another browser-native Markdown library) rather than kramdown. This is a firm constraint.
+
+**Implementation note:** `marked.js` is already a common CDN dependency for Markdown rendering in browser contexts. The Opal adapter can call `JS.global[:marked].call(content)` after loading marked.js.
+
+---
+
+## Server-Only Constructs in Candidate Files
+
+### `app.rb`
+
+| Construct | Impact |
+|---|---|
+| `SinatraApp.create(self)` in `App#generate` | Only called from server entrypoint — not in browser path |
+| `File.exist?` / `File.binread` in `build_favicon_href` | File I/O — not callable in browser. `build_favicon_href` only reached if `favicon` DSL is used. Override in Opal adapter. |
+| `CGI.escape` in `define_path_helpers` | CGI is available in Opal stdlib — works in browser |
+| `Time.now.to_f` in `show_toast` | `Time` is available in Opal core — works in browser |
+| `require 'resource'` at top of `app.rb` | `resource.rb` requires `cgi` (available) but also integrates with Sinatra routing. Must stub or exclude. |
+
+### `display_dsl.rb`
+
+| Construct | Impact |
+|---|---|
+| `require 'digest/md5'` in `#button` | See above — override button in Opal adapter |
+| `block.source_location` | Available in Opal — OK |
+
+### `components.rb`
+
+| Construct | Impact |
+|---|---|
+| `require "yaml"` / `require "json"` (inside Table/ScoreTable) | `json` available in Opal stdlib; `yaml` not needed for browser rendering |
+| Direct `view.div`, `view.span`, `view.h4`, `view.p`, `view.hr` calls | These 5 HTML methods must exist on the OpalRenderer's view object |
+| `view.adapter.*` delegation | All rendering goes through adapter — clean separation |
+
+---
+
+## OpalRenderer Must-Implement Method List
+
+The `OpalRenderer` (the `view` object passed to `component.render(view, state)`) must support:
+
+### Direct HTML element methods (called directly on view in components.rb)
+
+- `div(**attrs, &block)` — Card, CardHeader, CardBody, CardFooter, Div
+- `span(&block)` — Phrase, Card label
+- `h4(&block)` — CardHeader
+- `p(&block)` — Text component
+- `hr(**attrs)` — MenuDivider
+
+### Adapter methods (via `view.adapter.*`)
+
+From `components.rb` (64 adapter calls):
+- `render_text_field`, `render_text_area`, `render_checkbox`, `render_select`, `render_radio_group`
+- `render_button`, `render_app_header`, `render_div`, `render_term`, `render_lesson_text`
+- `render_vstack`, `render_hstack`, `render_grid`, `render_scroll_box`
+- `render_collapsible`, `render_alert`, `render_tabs`, `render_breadcrumbs`, `render_dropdown`
+- `render_modal`, `render_toast_container`, `render_theme_toggle`, `render_theme_preset`, `render_theme_switcher`
+- `render_header`, `render_markdown`, `render_stat_display`, `render_badge`, `render_status_dot`
+- `render_type_tag`, `render_pulse_indicator`, `render_activity_item`, `render_timeline_event`
+- `render_priority_item`, `render_progress_bar`, `render_spinner`, `render_score_table`, `render_table`
+- `render_status_badge`, `render_external_link_button`, `render_link`, `render_navbar`, `render_nav_item`
+- `render_checkbox_group`, `render_code_editor`, `render_tag_buttons`, `render_form`
+- `render_expandable_card`, `render_canvas_continue`, `render_bar_chart`, `render_line_chart`
+- `render_pie_chart`, `render_stacked_bar_chart`, `render_column`, `render_columns`
+- `render_app_shell`, `render_main_content`, `render_sidebar`
+
+From visual skills component sub-files:
+- `render_code_block`, `render_image_block`, `render_mermaid`, `render_keyboard_shortcuts`
+- `render_slide_container`, `render_slide`, `render_sidebar_toc`, `render_callout`, `render_comparison`
+- `render_pipeline`, `render_kpi_dashboard`, `render_chartjs`, `render_timeline_event`
+- `render_design_deck`, `render_deck_slide`, `render_deck_option`, `render_deck_summary`
+- `render_generate_more_controls`, `render_skeleton_placeholder`, `render_model_selector`
+- `render_close_overlay`, `render_confirmation_bar`
+- `render_hero`, `render_prose`, `render_pullquote`, `render_dir_tree`, `render_legend`
+- `render_flow_arrow`, `render_layout_toggle`
+
+**Phase 1 OpalRenderer priority (minimal viable set for basic text/container rendering):**
+- `div`, `span`, `h4`, `p`, `hr`
+- `render_text`, `render_markdown` (via marked.js), `render_header`, `render_button`
+- `render_div`, `render_vstack`, `render_hstack`, `render_card`
+
+---
+
+## Adjustments to Phase 1 Plan
+
+1. **Opal version locked:** Use `opal ~> 1.8` (installed 1.8.2). API confirmed working.
+
+2. **Builder pattern:** Use `Opal::Builder.new(missing_require_severity: :ignore)` for the entrypoint build. The 7 candidate files all compile under this mode.
+
+3. **digest replacement:** The `App#button` and `DisplayDSL#button` use `Digest::MD5` for stable IDs. In the Opal adapter, override the button logic to use a pure counter or JS `Math.random()`. No digest dependency needed in the browser.
+
+4. **stdlib requires in Opal bundle:** The opal build step must explicitly `require` stdlib modules: `set`, `json`, `cgi` before bundling `stream_weaver/app`.
+
+5. **kramdown is out:** `render_markdown` in `OpalAdapter` must use `marked.js` via `JS.global[:marked].call(content)`. Add marked.js to the CDN list alongside the Opal runtime bundle.
+
+6. **`require 'resource'` in app.rb:** `resource.rb` is a server-only routing concern. The `opal_entry.rb` entrypoint does NOT require `app.rb` directly — it requires only the safe subset. Phase 1 OpalRenderer can stub or skip resource/routing machinery.
+
+7. **Direct view HTML calls are minimal:** Only `div`, `span`, `h4`, `p`, `hr` — the OpalRenderer's view interface is very simple.
+
+8. **Adapter delegation is the primary pattern:** 64 of 73 `view.` calls go through `view.adapter.*` — the clean separation makes OpalAdapter straightforward to implement incrementally.
+
+---
+
+## Files Created/Modified This Spike
+
+- `Gemfile` — added `group :development { gem "opal", "~> 1.8" }`
+- `lib/stream_weaver/opal_entry.rb` — browser-only require tree (created, placeholder for non-existent files)
+- `bin/opal_spike.rb` — Opal compatibility test script
+- `docs/opal-spike-findings.md` — this document