stream_weaver 0.3.0

data/gsd/research/market-positioning-research.md

@@ -0,0 +1,139 @@
+# StreamWeaver Market Positioning Research
+
+Researched 2026-07-02. Three topics: (1) the Anthropic/industry shift from Markdown to HTML for agent output, (2) charm-ruby.dev site anatomy as a docs-site template, (3) pareto video-production stack for solo-dev OSS demos.
+
+---
+
+## 1. Anthropic's move from Markdown to HTML for agent output
+
+### The core event: Thariq Shihipar's post, official Anthropic blog, May 2026
+
+The load-bearing artifact for StreamWeaver's positioning is a post published **on Anthropic's own blog** (not just a personal take): "Using Claude Code: The Unreasonable Effectiveness of HTML," by **Thariq Shihipar, member of technical staff on the Claude Code team**.
+
+- Official post: https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html
+- Companion gallery (20 self-contained HTML files generated by Claude Code for common use cases): https://thariqs.github.io/html-effectiveness/
+- Companion GitHub repo: https://github.com/anthropics/html-effectiveness
+- Simon Willison's amplification/commentary (useful as an independent, widely-read second source): https://simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/
+- InfoQ coverage: https://www.infoq.com/news/2026/06/anthropic-html-markdown-agent/
+
+**Exact quotes from Shihipar (via Anthropic's blog):**
+
+> "HTML can convey much richer information compared to Markdown."
+
+> "there is almost no set of information that Claude can read that you cannot efficiently represent with HTML"
+
+> "I tend to not actually read more than a 100-line Markdown file"
+
+> "Markdown files are fairly hard to share since most browsers do not render them natively well" / "The chance of someone actually reading your spec, report, or PR writeup is much higher if it's in HTML"
+
+> "HTML can also allow you to interact with the document"
+
+> "As agents have become more and more powerful, I've found that Markdown has become an increasingly restrictive format." (via InfoQ)
+
+> "I've started preferring HTML as an output format instead of Markdown and increasingly see this pattern being applied by others on the Claude Code team." (via InfoQ)
+
+**The token-cost admission — this is the key line for StreamWeaver's pitch.** Shihipar does NOT deny the token cost; he concedes it and argues it's worth paying because Anthropic's context windows have grown large enough to absorb it:
+
+> "While Markdown often uses fewer tokens, I've found that the added expressiveness of HTML and the much higher likelihood of me reading it means I get overall better output."
+
+He justifies this by pointing to Opus 4.7's 1M-token context window, saying the extra usage "is not really noticeable in the context window." No Anthropic-sourced dollar or exact-multiplier figure was found in the official post itself.
+
+**The specific multiplier claim (secondary source, not Anthropic-official, but widely repeated and directly quotable for a "10x" framing):**
+
+Independent commentator Tom Crawshaw (via theaiarchitects.com), citing his own week of side-by-side client testing, put concrete numbers on it:
+
+> Markdown: "~250 tokens per 1,000 words"
+> HTML: "~1,500 tokens per 1,000 words"
+> "This represents a 4 to 8x increase" for HTML, with generation time also 2-4x longer (30s vs 90-120s for a 1,000-word doc).
+
+This is the closest thing in the wild to a citable "HTML costs ~5-8x more tokens than Markdown" data point. It's not an Anthropic-published number, so it should be cited as "industry practitioner benchmark" rather than attributed to Anthropic. It undershoots "10x" slightly (4-8x) — worth noting if StreamWeaver's own "10x" claim needs to be defensible; StreamWeaver's own benchmarking (README/docs) should be the primary source for that number, with this as corroborating context.
+
+Additional overview article worth linking for more color: https://theaiarchitects.com/blog/markdown-vs-html-claude-code — argues HTML wins "for anything you send to a human — audits, reports, plans, pricing models, dashboards" while Markdown "still wins for chained agents, git repos, short outputs, and anything inside the engineering loop." This is a useful frame for StreamWeaver: it's positioned squarely in the "human-facing agent output" zone this article says HTML wins, but at Markdown-like cost.
+
+### The broader trend: MCP Apps (the interactive-UI-over-MCP standard)
+
+This is the more important structural signal for positioning StreamWeaver as infrastructure, not just a nice-to-have. MCP Apps is now a **ratified, joint Anthropic/OpenAI/MCP-UI standard** — evidence that "rich HTML output from agents" is becoming protocol-level, not a one-off blog opinion.
+
+- Official spec announcement: https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/
+- Original MCP-UI proposal (Nov 2025): https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/
+- Spec overview docs: https://modelcontextprotocol.io/extensions/apps/overview
+- MCP-UI open-source SDK (predecessor project, still active): https://github.com/MCP-UI-Org/mcp-ui
+- Shopify engineering writeup, good "why" framing: https://shopify.engineering/mcp-ui-breaking-the-text-wall
+- WorkOS technical deep dive: https://workos.com/blog/mcp-ui-a-technical-deep-dive-into-interactive-agent-interfaces
+
+Key facts:
+- "MCP Apps is the first official MCP extension... with clients like ChatGPT, Claude, Goose and Visual Studio Code having shipped support."
+- Built on "the amazing work of MCP-UI and the OpenAI Apps SDK, with Anthropic, OpenAI, and MCP-UI collaborating to create a shared open standard."
+- Architecture: a `ui://` URI scheme for declaring UI resources tied to tool calls, rendered in a **sandboxed iframe**, with bi-directional JSON-RPC communication between the UI and host.
+- Use-case framing directly usable in StreamWeaver marketing: "a user asks 'show me sales by region,' an MCP App can render an interactive map where users click regions to drill down, hover for details, and toggle between metrics, all without additional prompts."
+
+### Competitor landscape: OpenAI and Google equivalents
+
+- **OpenAI Canvas**: https://openai.com/index/introducing-canvas/ — originally a separate collaborative window for writing/coding; per Help Center notes, canvas functionality has since been folded back into inline chat "writing blocks and code blocks" in GPT-5.5, and OpenAI's separate visual **Agent Builder** (drag-and-drop agent canvas) is being wound down (sunset from Nov 30, 2026). Net: OpenAI's dedicated canvas-as-a-surface bet has been partially reversed/absorbed, which is a mild point in favor of "rich inline HTML output" (StreamWeaver's model) over "separate canvas app" as the durable pattern.
+- **Google A2UI**: https://developers.googleblog.com/introducing-a2ui-an-open-project-for-agent-driven-interfaces/ — open project for agent-generated, cross-platform UI, explicitly framed around agents choosing "the interface which best suits the current conversation."
+- **Google Stitch** (I/O 2026): AI-native UI design canvas, infinite canvas + design agent + interactive prototypes — more a design tool than an agent-output format, but shows the same directional bet on rich, generated interactive surfaces. Coverage: https://www.animaapp.com/blog/ai-en/google-io-2026/
+
+### Positioning synthesis for StreamWeaver
+
+The strongest version of the pitch: *"Anthropic's own Claude Code lead just admitted, on Anthropic's blog, that HTML is 4-8x (practitioner-measured) more token-expensive than Markdown — and said it's worth it anyway because rich output keeps humans engaged. MCP Apps just standardized interactive HTML-in-iframe as the agent-to-human interface layer across Anthropic, OpenAI, and the broader ecosystem. StreamWeaver lets you get that same richness at Markdown's token cost, from a Ruby DSL, without hand-authoring HTML/CSS/JS or wiring an iframe sandbox."* That's a real, citable "expensive default vs. our product" tension — the Crawshaw 4-8x number is the number to lead with (attributed as an independent benchmark, not an Anthropic claim), with Shihipar's Anthropic-official quotes establishing that the *trend itself* is real and blessed by Anthropic, not fringe.
+
+---
+
+## 2. charm-ruby.dev site anatomy
+
+Fetched: https://charm-ruby.dev/
+
+**Hero & message**: Large ASCII-art wordmark spelling "CHARM" up top, tagline about making "the Ruby command line glamorous" — building "glamorous TUIs, style terminal output, create beautiful forms, and make your Ruby CLIs sparkle." The whole site commits to one adjective ("glamorous") and repeats it as the aesthetic thesis.
+
+**Navigation** (4 items only): Libraries, Get Started, Examples, GitHub link. Extremely shallow IA — no mega-menu, no deep category tree. Page flow is strictly top-down: hero → install options → library showcase → getting-started guide → code examples.
+
+**Progressive disclosure pattern**: Users are walked from zero-commitment overview → install → concrete library cards → runnable examples. Nobody has to understand the whole gem family before doing anything; each section commits you a little further.
+
+**How it sells the gems**:
+- Install as one metagem (`charm`) or piecemeal per-library — lowers commitment friction for a first try.
+- Library cards grouped by function (Build / Style / Interactive Tools) rather than alphabetically — organizes by *what you're trying to do*, not by gem name.
+- Each card: emoji + one-line description + gem name + links out to GitHub/RubyGems. No walls of prose.
+- Five examples of increasing complexity — "show, don't tell": the persuasion mechanism is working code, not marketing copy.
+
+**Tech/design signals**: Reads as a static site generator (Jekyll-like — clean semantic HTML, markdown-friendly content, no visible JS framework fingerprints). Minimalist palette anchored on a primary purple (`#7D56F4`) with a status-red accent (`#FF6B6B`) pulled straight from example code output — i.e., the brand color *is* the terminal-styling color, reinforcing the product. Monospace type for all code, ASCII art as the only "decorative" element. Minimal interactivity in the page itself — the *gems* are the interactive layer; the site just demonstrates them in static code blocks.
+
+**Direct applicability to StreamWeaver**: same playbook — pick a metagem install path, group components by "what you're building" (not alphabetically), lead with runnable code over prose, and let the brand color be literally a color StreamWeaver itself can render (since StreamWeaver *is* the output surface, this is even more natural than for charm-ruby, where the terminal only echoes ANSI escapes).
+
+### Other reference: dry-rb / Hanakai
+
+Note: dry-rb.org now 301-redirects to https://hanakai.org/dry — as of May 2026, dry-rb + Hanami + rom-rb merged their docs under a unified "Hanakai" umbrella. That site uses genuine progressive disclosure: a hovering top nav revealing project categories, then drilling into docs; gems organized thematically (Business Logic / Foundations / Architecture) rather than alphabetically; hero copy is a single flat claim — "Ruby gems for better code" — plus one supporting line about composability. Worth citing as a second data point for "small-OSS-family site" conventions: shallow top nav + thematic (not alphabetical) grouping + one-sentence hero + Learn/Blog/Community as separate top-level sections once the project matures past a single-page pitch. No Astro/Starlight-specific ruby-gem examples turned up in search; the Jekyll/plain-static-site pattern (as used by both charm-ruby.dev and apparently Hanakai) seems to be the dominant convention in this space rather than Starlight.
+
+---
+
+## 3. Pareto video stack for solo-dev OSS demos (2026)
+
+Recommended stack, cheapest effort first:
+
+| Need | Tool | Why |
+|---|---|---|
+| Terminal/CLI demo | VHS (charmbracelet) | Scripted `.tape` files -> deterministic, reproducible GIF/MP4/WebM. No manual screen recording, no retakes. |
+| Browser/UI demo | Playwright v1.59 screencast API | Agent drives the browser itself; new screencast API supports chapter markers, mid-test start/stop, and is explicitly designed for coding agents to produce "video receipts." |
+| Voiceover | ElevenLabs | Best-in-class synthetic voice in 2026 (listeners pick it ~7/10 times over next-best in blind tests); generate MP3/WAV separately. |
+| Assembly/editing | Descript | Text-based editing (edit the transcript, video follows), integrated screen recording, filler-word removal — glue layer between raw captures and a finished video. |
+| Fancier programmatic marketing video (optional, higher effort) | Remotion | Videos as React components — good for a polished launch trailer, data-driven, but adds a whole frontend build; save for v2, not first drop. |
+
+**Recommended minimum-effort path for a rubygem launch:**
+1. Script the CLI/terminal parts of the demo as a VHS `.tape` file → GIF for the README, MP4 for a landing page hero. https://github.com/charmbracelet/vhs
+2. If StreamWeaver's differentiator is *browser-rendered rich output* (which it is), drive the browser with Playwright's screencast API to capture the actual rendered HTML output live, rather than screenshotting — this directly demonstrates the "markdown-cost, HTML-richness" claim in motion. https://playwright.dev/agent-cli/commands/video-recording
+3. Generate a short voiceover script, synthesize in ElevenLabs, drop the audio track under the VHS/Playwright footage.
+4. Assemble/trim in Descript (text-based editing means no timeline fiddling) and export.
+5. Skip Remotion and asciinema/agg for v1 — they're valid alternatives (agg is a fine VHS substitute if you want SVG output for smaller file size: https://github.com/asciinema/agg) but add tooling surface without adding capability StreamWeaver doesn't already need from VHS + Playwright.
+
+This whole pipeline is scriptable end-to-end (VHS tapes, Playwright scripts, ElevenLabs API calls are all automatable), which matters for a repo where Claude Code is already doing agentic development — the demo-video generation step can itself become a repeatable `bin/` task rather than a one-off manual recording session.
+
+Sources for this section:
+- https://github.com/charmbracelet/vhs
+- https://playwright.dev/agent-cli/commands/video-recording
+- https://playwright.dev/docs/videos
+- https://purpleowl.io/blog/we-automated-our-product-walkthrough-video-the-whole-thing
+- https://elevenlabs.io/blog/elevenlabs-vs-descript
+- https://getstacksmart.com/blog/elevenlabs-vs-descript-2026
+- https://www.remotion.dev/
+- https://github.com/remotion-dev/remotion
+- https://github.com/asciinema/agg
+- https://docs.asciinema.org/manual/agg/

data/gsd/research/production-patterns-research.md

@@ -0,0 +1,270 @@
+# Production-Readiness Patterns: Precedent Survey
+
+Research for the StreamWeaver "production-ready 20%" strategy. StreamWeaver
+(this repo) grew from quick helper-UI
+scripts into full web apps. The owner wants Rails-grade production mechanisms
+*without* building Rails — the minimal proven mechanisms that give 80% of
+production readiness for 20% of the engineering cost.
+
+Known pain points driving this research:
+
+- **(a)** State lived in session cookies until they overflowed the 4KB cookie limit.
+- **(b)** Multi-app-in-one-server (`streamweaver app.rb` service mode) produces
+  hash-based URLs instead of human-readable ones.
+- **(c)** Users occasionally hit a wall and rewrite their app in raw Sinatra.
+
+Five topics below. Each ends with a proven-pattern table and a recommendation.
+
+---
+
+## 1. Server-side state/session
+
+**The scaling story, in order:** cookie session (client-side, ~4KB cap) →
+in-memory server-side session (`Rack::Session::Pool`, single-process only) →
+external store (Redis/Memcached, the traditional answer) → **database-backed
+store on the app's existing DB** (the 2025-26 answer, popularized by Rails 8's
+"Solid" trio — Solid Cache, Solid Queue, Solid Cable — explicitly built to
+avoid requiring Redis as extra infrastructure).
+
+**Streamlit** hits this exact wall: `st.session_state` is in-process/in-memory
+per browser session by default, which is explicitly documented as
+insufficient once you have multiple users or server restarts/multiple nodes.
+Streamlit's own docs point users to Redis or to hand-rolling a
+disk/EFS-backed session-key scheme — i.e., Streamlit does *not* solve this for
+you; it punts to the deployer. That's the trap StreamWeaver should avoid
+repeating.
+
+**Sinatra/Rack apps** graduate off `enable :sessions` (cookie-based) to
+`use Rack::Session::Pool` (server-side, in-memory hash — good for single
+process, breaks under multiple workers/dynos) or plug in **moneta**, a gem
+that provides one unified key-value interface over ~20 backends (Memory,
+SQLite3, PStore/YAML file, Redis, Memcached, ActiveRecord, Sequel, etc.) and
+ships a `Rack::MonetaStore` middleware plus direct Sinatra/Rails integration.
+Moneta is the "swap the backend without rewriting the app" abstraction layer
+— exactly the pattern needed for a gem that has to work identically for a
+solo dev (file-backed) and a small team (DB-backed).
+
+**Rails 8's Solid trio** is the strongest recent precedent for the philosophy
+itself: default to the database you already have (SQLite is explicitly fine
+— "SSDs are only marginally slower than RAM for reads, at a fraction of the
+cost and complexity of running Redis"). Basecamp/HEY run this in production.
+The win isn't the specific gem, it's the stance: **zero extra infrastructure
+by default, pluggable up to Redis only if you need it.**
+
+| Pattern | Project | Adopt/Adapt/Skip |
+|---|---|---|
+| In-memory session (works until multi-process/restart) | Rack::Session::Pool, current StreamWeaver | Skip as the *only* option — keep as dev-mode default |
+| Unified key-value store abstraction (memory/SQLite/file/Redis, swappable) | moneta gem | **Adapt** — thin StreamWeaver-native abstraction over SQLite-first, Redis-optional |
+| DB-backed session/cache using an embedded DB, no external service required by default | Rails 8 Solid Cache/Solid Queue philosophy | **Adopt the philosophy** — SQLite-backed session store as the 1.0 default |
+| Punt state scaling to the deployer (EFS/Redis, docs-only) | Streamlit | Skip — this is the exact pain point already reported |
+
+**Recommendation:** Ship a `StreamWeaver::SessionStore` interface with two
+built-in backends: in-memory (today's default, fine for `ruby app.rb`
+single-process) and **SQLite-backed** (default for `streamweaver` service
+mode and anywhere `STREAMWEAVER_HOST=0.0.0.0`). No Redis dependency in core;
+document a Redis/moneta adapter as an escape hatch for teams that already run
+Redis.
+
+---
+
+## 2. App naming/routing (human-readable URLs for multi-app service mode)
+
+The web has few frameworks solving "many small apps, one server, friendly
+URLs" as a first-class feature — most precedent comes from tunnel/PaaS
+products (ngrok, Heroku-style) and from Rails engine mounting, not from
+peer micro-frameworks.
+
+- **ngrok**: paid tiers let you claim a human-readable static subdomain
+  (`myapp.ngrok.app`) per tunnel; multiple local services get separate named
+  tunnels via a config file, each mapped 1:1 to a name. Wildcard domains
+  (route-by-subdomain to one process) require the enterprise tier — i.e. even
+  ngrok treats "one name = one process" as the easy case and "one process,
+  many subpath names" as the harder, less-supported case.
+- **Puma-dev** (already used by StreamWeaver, see README puma-dev mode):
+  solves this locally for free — `puma-dev link` in a directory gives you
+  `http://<dirname>.test` with zero config, auto-starts on first request. This
+  is the actual precedent StreamWeaver already leans on, and it's the right
+  shape: **name = directory/app name, not a hash.**
+  - `puma-dev` doesn't do subpath routing at all — it's one name per process,
+    which sidesteps the routing problem instead of solving it.
+- **Rack::Builder / Sinatra modular mounting**: `run Rack::Builder.new { use
+  App1; use App2 }` mounts multiple Sinatra apps in one process, but every
+  request passes through every app's before-filters until one claims it —
+  a real cost at scale, and the community's own conclusion (via projects like
+  `sinatra-router`) is that a dedicated slug-based router in front of
+  `Rack::Builder` is worth adding rather than relying on middleware stacking.
+
+| Pattern | Project | Adopt/Adapt/Skip |
+|---|---|---|
+| Named local domain, zero config, one process | Puma-dev (already integrated) | **Adopt more** — make service-mode registration name-first, not hash-first |
+| Named subdomain per tunnel/app | ngrok | Adapt the naming *convention* (slug from app name/directory), not the tunnel infra |
+| Subpath router in front of Rack::Builder to avoid middleware-stacking cost | sinatra-router pattern | **Adopt** — give service mode a slug router: `/apps/<slug>` derived from `app "Name"` title or explicit `slug:` option |
+
+**Recommendation:** In service mode, derive `/apps/<slug>` from the app's
+declared name (slugified) or an explicit `app "Meeting Notes", slug: "notes"`
+option, replacing the current hash. Keep Puma-dev mode as the "one app, one
+memorable domain" path for users who want that instead of subpaths — don't
+force a single routing model.
+
+---
+
+## 3. Escape hatches (never rewrite in Sinatra)
+
+Every framework in this class has learned the same lesson: users will hit a
+wall the DSL doesn't cover, and if there's no sanctioned drop-to-raw path they
+leave the framework entirely. The mature answer is always **a small, explicit
+API for "give me a raw request/response here," not a philosophy of covering
+every case in the DSL.**
+
+- **Streamlit**: `st.components.v1.html()` / `.iframe()` for one-way raw
+  HTML/embed, and a full **Components API** (bidirectional, JS↔Python) for
+  cases needing two-way data — explicitly documented as "start with html/
+  iframe first, only reach for the bidirectional Components template if you
+  need callbacks back into Python." This graduated-complexity offering (raw
+  HTML → iframe → full bidirectional component) is a strong minimal template.
+- **Phoenix LiveView**: `Hooks` — `phx-hook="MyHook"` lets you write arbitrary
+  client JS and have LiveView guarantee it's wired up/cleaned up on
+  mount/update/destroy, without leaving the LiveView model. Router-level,
+  LiveView routes coexist with plain controller routes in the same router —
+  users aren't forced to choose one paradigm for the whole app.
+- **Hotwire/Turbo**: Turbo Frames/Streams degrade gracefully to normal
+  full-page navigation, and standard Rails routes/controllers sit right next
+  to Turbo-powered ones — there's no separate "Hotwire app" vs "Rails app,"
+  it's additive.
+- **Rack ecosystem generally**: any Sinatra/Roda/Rails app can `mount` a bare
+  Rack app or define a raw route block that skips all the DSL and just
+  returns `[status, headers, body]` — the universal Ruby web escape hatch.
+
+| Pattern | Project | Adopt/Adapt/Skip |
+|---|---|---|
+| Raw HTML/iframe embed, no callback wiring | Streamlit `components.v1.html/iframe` | **Adopt** — `raw_html { }` / iframe component, already low-cost to add |
+| Full bidirectional custom component (JS↔server), offered as escalation, not the default path | Streamlit Components API | **Adapt** — a `custom_component` hook for canvas/push mode only, document as "advanced" |
+| Client-side hook wired to component lifecycle without leaving the framework's data model | Phoenix LiveView `Hooks` | **Adapt** — a `js_hook:` option on any component for custom client behavior |
+| Raw Rack route block coexisting with DSL routes in the same app | Sinatra/Roda/Rails universal pattern | **Adopt** — `route "/webhook", methods: [:post] { |req| ... }` escape hatch returning a raw Rack triple, so users never need a second Sinatra process |
+
+**Recommendation:** Ship two escape hatches, both small: (1) a `raw_html`/
+`raw` component for arbitrary markup (Streamlit's html/iframe tier), and (2) a
+`route` DSL method that registers a raw Rack endpoint inside the same app/
+server (the universal Sinatra/Roda pattern) — covering webhooks, custom JSON
+APIs, and file downloads without a second process. Skip building a full
+bidirectional custom-component protocol until there's evidence of real demand
+past (1) and (2); that's the expensive tier Streamlit only added because
+"just embed HTML" wasn't enough for chart libraries specifically.
+
+---
+
+## 4. 1.0 gem production checklist
+
+There isn't a single canonical 2026 checklist, but the RubyGems guides plus
+current framework practice converge on the same short list:
+
+- **Semver**: RubyGems' own guidance is to follow semantic versioning
+  strictly from the first 1.0 tag — breaking changes bump major, and the gem
+  should declare a `required_ruby_version` in the gemspec rather than assume.
+- **Ruby version support**: as of 2026, Ruby 3.2 is EOL and 3.3 is
+  security-only; a credible 1.0 targets 3.3 (min, if backward compat
+  matters) through 3.4/4.0, tested via CI matrix (GitHub Actions with a Ruby
+  version matrix is the de facto standard across Sinatra/Roda/Rails-family
+  gems).
+- **Security posture — bind address**: both Rails-adjacent minimal frameworks
+  (Roda, Hanami) and StreamWeaver's own README already get this right in
+  principle — default to `127.0.0.1`, require an explicit opt-in
+  (`STREAMWEAVER_HOST=0.0.0.0`) for LAN/Tailscale exposure. That's the
+  correct minimal default and should be called out explicitly as a security
+  feature in 1.0 docs, not just a config knob.
+- **CSRF**: Roda ships a `route_csrf` plugin (opt-in, per-route tokens) and
+  Hanami bakes CSRF + secure-by-default headers (CSP, X-Frame-Options) into
+  the framework itself rather than leaving it to the app. StreamWeaver's
+  auto-submit form components are exactly the surface that needs CSRF
+  protection once apps are bound beyond localhost — currently likely
+  unprotected given the localhost-only original design assumption.
+- **Auth hook for exposing beyond localhost**: neither Roda nor Hanami forces
+  a specific auth scheme; both expose a middleware slot. The minimal
+  equivalent for StreamWeaver is a documented Rack middleware insertion point
+  (e.g. HTTP Basic Auth via `Rack::Auth::Basic`) that's trivial to enable
+  when `STREAMWEAVER_HOST` isn't localhost.
+- **Deployment story**: Kamal 2 is now the default Rails answer for
+  "containerize and deploy to any VPS with zero-downtime," and it works for
+  any Dockerized Ruby app, not just Rails — a Kamal-friendly `Dockerfile` +
+  short "deploy with Kamal" doc is more credible in 2026 than a bespoke
+  deploy guide. Puma-dev (already used) covers the "run persistently on my
+  own machine" case well.
+
+| Pattern | Project | Adopt/Adapt/Skip |
+|---|---|---|
+| Semver from 1.0, `required_ruby_version` in gemspec, GH Actions Ruby matrix (3.3–3.4/4.0) | RubyGems guides, Rails-family gems | **Adopt** — mechanical, low cost |
+| Bind to `127.0.0.1` by default, explicit opt-in for `0.0.0.0` | Roda/Hanami convention; StreamWeaver already does this | **Adopt & document as a security feature**, not just a config default |
+| Built-in CSRF plugin, opt-in but one-liner | Roda `route_csrf` | **Adapt** — wire CSRF token into StreamWeaver's existing auto-submit forms, on by default once host != localhost |
+| Secure-by-default headers (CSP, X-Frame-Options) baked into framework | Hanami | **Adapt** — ship as default middleware, overridable |
+| Documented middleware slot for auth (Basic Auth, etc.), not a built auth system | Roda/Hanami middleware pattern | **Adopt** — one doc page + example, don't build auth |
+| Kamal-ready Dockerfile + deploy doc | Rails 8 default | **Adapt** — one example Dockerfile in `examples/`, not a StreamWeaver-specific deploy tool |
+
+**Recommendation:** The 1.0 checklist is mostly *documentation and defaults*,
+not new engineering: lock semver + Ruby CI matrix, keep localhost-default
+bind but frame it explicitly as security posture, add opt-in CSRF for
+auto-submit forms, and ship one example Dockerfile for Kamal deploys. Skip
+building any bespoke auth system — a middleware insertion point plus a
+Basic Auth example is the whole scope.
+
+---
+
+## 5. Real-time push at production quality (SSE/WebSocket robustness)
+
+StreamWeaver's canvas push mode is SSE-based (per the bridge/session files in
+the repo). The precedent split is stark: **LiveView-style (stateful,
+WebSocket, server holds a process per client) vs. Datastar-style (stateless,
+SSE, server recomputes from state on each push)** — and the failure modes are
+different for each.
+
+- **LiveView's known weak spot**: when the WebSocket drops, the server-side
+  GenServer holding that session's state dies with it — everything in
+  `assigns` is gone on reconnect unless it was persisted somewhere durable.
+  The documented fix is architectural discipline: treat in-memory state as a
+  disposable cache and always keep a "recipe" (DB row, URL params) to
+  reconstruct it, never treat process memory as the source of truth.
+- **SSE reconnection (the protocol StreamWeaver already uses)**: the
+  browser's native `EventSource` auto-reconnects, but correctness requires
+  the server to (1) send a `retry:` field to control backoff, and (2) assign
+  a monotonic `id:` to every event so a reconnecting client's `Last-Event-ID`
+  header lets the server replay only what was missed. Skipping `id:` is
+  called out repeatedly as the most common silent bug — reconnection appears
+  to work in dev (small gaps) and silently drops events under real network
+  interruption.
+- **Backpressure**: the consistent production pattern (Ktor/Kotlin Flow
+  examples, Phoenix GenServer mailbox examples) is that the transport must
+  apply backpressure by suspending/queuing at the producer when a client
+  can't keep up, rather than unbounded buffering — for StreamWeaver's push
+  model (owner explicitly pushes content, not a firehose) this is lower risk
+  than a chat/metrics use case, but batching rapid successive pushes to the
+  same session is the cheap defensive move.
+- **Datastar's stance** (SSE + hypermedia, no WebSocket, no per-client
+  process) is the closest architectural cousin to StreamWeaver's canvas
+  push — worth reading as validation that SSE-only is a legitimate production
+  choice, not just "the easy version," as long as event IDs + replay are
+  handled.
+
+| Pattern | Project | Adopt/Adapt/Skip |
+|---|---|---|
+| Monotonic `id:` on every SSE event + honor `Last-Event-ID` on reconnect to replay only missed events | SSE spec / general production guidance | **Adopt** — likely the single highest-leverage fix; check if `bridge_server.rb`/`protocol.rb` already assign event IDs |
+| `retry:` field to control client backoff | SSE spec | **Adopt** — one-line addition |
+| Never treat in-process state as sole source of truth; keep a durable "recipe" to rebuild on reconnect | Phoenix LiveView lesson-learned | **Adapt** — pairs directly with topic 1's session-store recommendation; canvas session state should live in the same SQLite-backed store, not only in the bridge process |
+| Batch/coalesce rapid successive pushes per session rather than unbounded queuing | Ktor/GenServer backpressure pattern | **Adapt** — cheap given StreamWeaver's push is owner-driven, not high-frequency |
+| Stateless SSE + hypermedia as a legitimate alternative to stateful WebSocket | Datastar | Reference/validate current approach — no change needed, just confirms SSE-only is production-credible |
+
+**Recommendation:** Audit `lib/stream_weaver/canvas/protocol.rb` and
+`bridge_server.rb` for event IDs and `Last-Event-ID` handling — if absent,
+that's the top-priority fix for push-mode robustness. Add a `retry:` field.
+Tie canvas session state to the same durable session store from topic 1 so a
+bridge restart doesn't lose in-flight canvas content.
+
+---
+
+## Summary Table
+
+| # | Topic | Adopt | Adapt | Skip |
+|---|---|---|---|---|
+| 1 | State/session | DB-backed-by-default philosophy (Rails 8 Solid) | moneta-style pluggable backend abstraction, SQLite default | Redis-required, EFS-style punt (Streamlit's gap) |
+| 2 | App naming/routing | Slug-based `/apps/<name>` router | ngrok's naming convention (not its infra) | Hash-based mounting, wildcard-domain routing |
+| 3 | Escape hatches | Raw HTML/iframe tier, raw Rack `route` block | LiveView-style `js_hook:` for client behavior | Full bidirectional custom-component protocol (until demand proven) |
+| 4 | 1.0 checklist | Semver + Ruby CI matrix, localhost-default bind, middleware auth slot, Kamal-ready Dockerfile | Roda's opt-in CSRF, Hanami's secure headers-by-default | Building a bespoke auth system |
+| 5 | Real-time push | SSE `id:`/`Last-Event-ID` replay, `retry:` field | Durable session-backed canvas state, push coalescing | Switching to WebSocket/per-client process model |