stream_weaver 0.3.0

data/docs/plans/shadcn-polish-plan.md

@@ -0,0 +1,417 @@
+# PLAN: shadcn Polish for StreamWeaver
+
+**Goal:** Get shadcn/ui-level visual polish in StreamWeaver components, with optional Tailwind mode for full fidelity.
+
+**Reference:** `docs/ruby-ui-comparison.md` for full gap analysis.
+**RubyUI source:** `~/work/ruby_ui/` (gem), `~/work/ruby_ui_web/` (docs/CSS)
+
+---
+
+## Phase 1: shadcn Token Layer + Dark Mode
+
+**Outcome:** All existing components gain consistent colors, dark mode, and visual polish. Zero breaking changes.
+
+### 1.1 Create `shadcn_tokens.css`
+
+Add to StreamWeaver's base CSS output. This defines the semantic color system that both pure CSS and Tailwind modes will share.
+
+**Location:** `lib/stream_weaver/assets/shadcn_tokens.css`
+
+```css
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: #fff;
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --radius: 0.5rem;
+  --warning: hsl(38 92% 50%);
+  --warning-foreground: #fff;
+  --success: hsl(87 100% 37%);
+  --success-foreground: #fff;
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+}
+```
+
+**Integration with existing Theme system:**
+
+Update `Theme::VARIABLE_SCHEMA` to map existing `--sw-` vars to shadcn tokens. When a StreamWeaver theme sets `color_primary`, it should also update `--primary`. This can be done in the CSS output:
+
+```css
+:root {
+  --primary: var(--sw-color-primary, oklch(0.205 0 0));
+  --background: var(--sw-color-bg, oklch(1 0 0));
+  /* etc — shadcn tokens fall back to SW vars if set, else default */
+}
+```
+
+### 1.2 Create `shadcn_base.css`
+
+Global base styles that give everything the shadcn feel.
+
+**Location:** `lib/stream_weaver/assets/shadcn_base.css`
+
+```css
+/* Base reset for shadcn consistency */
+*, *::before, *::after {
+  border-color: var(--border);
+}
+
+body {
+  background-color: var(--background);
+  color: var(--foreground);
+}
+
+/* Shared interactive states */
+.sw-interactive {
+  transition: color 0.15s ease, background-color 0.15s ease,
+              border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.sw-interactive:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--background), 0 0 0 4px var(--ring);
+}
+
+.sw-interactive:disabled,
+.sw-interactive[aria-disabled="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+  cursor: not-allowed;
+}
+```
+
+### 1.3 Update Component CSS
+
+Migrate existing component styles from hardcoded colors to semantic tokens. Example diffs:
+
+**Button (before):**
+```css
+.sw-button { background: var(--sw-color-primary); color: #fff; border-radius: var(--sw-radius-md); }
+.sw-button:hover { background: var(--sw-color-primary-hover); }
+```
+
+**Button (after):**
+```css
+.sw-button {
+  display: inline-flex; align-items: center; justify-content: center;
+  border-radius: var(--radius);
+  font-weight: 500; font-size: 0.875rem;
+  height: 2.25rem; padding: 0.5rem 1rem;
+  transition: color 0.15s, background-color 0.15s;
+}
+.sw-button:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--background), 0 0 0 4px var(--ring);
+}
+.sw-button:disabled { opacity: 0.5; pointer-events: none; }
+
+.sw-button--primary { background: var(--primary); color: var(--primary-foreground); }
+.sw-button--primary:hover { filter: brightness(1.1); }
+
+.sw-button--secondary { background: var(--secondary); color: var(--secondary-foreground); }
+.sw-button--secondary:hover { filter: brightness(0.95); }
+
+.sw-button--destructive { background: var(--destructive); color: var(--destructive-foreground); }
+.sw-button--destructive:hover { filter: brightness(1.1); }
+
+.sw-button--outline {
+  background: var(--background); color: var(--foreground);
+  border: 1px solid var(--input); box-shadow: 0 1px 2px rgba(0,0,0,0.05);
+}
+.sw-button--outline:hover { background: var(--accent); color: var(--accent-foreground); }
+
+.sw-button--ghost { background: transparent; color: var(--foreground); }
+.sw-button--ghost:hover { background: var(--accent); color: var(--accent-foreground); }
+
+.sw-button--link { background: transparent; color: var(--primary); text-decoration-line: underline; text-underline-offset: 4px; }
+```
+
+**Card (before):**
+```css
+.card { background: var(--sw-color-bg-card); border: 1px solid var(--sw-color-border); border-radius: var(--sw-radius-lg); }
+```
+
+**Card (after):**
+```css
+.sw-card {
+  background: var(--card); color: var(--card-foreground);
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) + 4px);
+  box-shadow: 0 1px 3px rgba(0,0,0,0.08);
+}
+.sw-card-header { padding: 1.5rem 1.5rem 0; display: flex; flex-direction: column; gap: 0.375rem; }
+.sw-card-content { padding: 1.5rem; padding-top: 0; }
+.sw-card-footer { padding: 0 1.5rem 1.5rem; display: flex; align-items: center; }
+```
+
+**Apply this pattern to all components:**
+- Alert → `var(--destructive)`, `var(--warning)`, `var(--success)`
+- Badge → variant colors from tokens
+- Input/TextArea → `var(--input)` border, `var(--ring)` focus
+- Select/Dropdown → `var(--popover)` background
+- Modal/Dialog → `var(--popover)` with backdrop
+- Table → `var(--muted)` for header, `var(--border)` for rows
+- Tabs → `var(--muted)` for inactive, `var(--background)` for active
+- Sidebar → `var(--card)` or dedicated sidebar tokens
+
+### 1.4 Dark Mode Toggle
+
+Update `ThemeSwitcher` component to support dark mode:
+
+```ruby
+class ThemeSwitcher < Base
+  def render(view, state)
+    # Emit a button that toggles .dark class on <html> and persists to localStorage
+    view.adapter.render_theme_switcher(view, self, state)
+  end
+end
+```
+
+Add JS to the adapter output:
+```javascript
+function toggleDarkMode() {
+  const html = document.documentElement;
+  html.classList.toggle('dark');
+  localStorage.setItem('theme', html.classList.contains('dark') ? 'dark' : 'light');
+}
+
+// On load: respect saved preference or system preference
+(function() {
+  if (localStorage.theme === 'dark' ||
+      (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
+    document.documentElement.classList.add('dark');
+  }
+})();
+```
+
+### 1.5 Verify with Existing Apps
+
+Run existing StreamWeaver examples/apps and confirm:
+- Colors look correct with new tokens
+- Dark mode works
+- No visual regressions
+- Existing `register_theme` still works (SW vars feed into shadcn tokens)
+
+---
+
+## Phase 2: Extract Adapter Pattern
+
+**Outcome:** Clean separation between component logic (DSL) and rendering (adapter).
+
+### 2.1 Formalize BaseAdapter
+
+Ensure all component rendering goes through adapter methods:
+
+```ruby
+module StreamWeaver
+  class BaseAdapter
+    def render_button(view, component, state); end
+    def render_card(view, component, state); end
+    def render_input(view, component, state); end
+    # ... one method per component
+  end
+end
+```
+
+### 2.2 Rename Current Adapter → PureCSSAdapter
+
+The existing AlpineJS adapter becomes `PureCSSAdapter` (or `AlpineJSAdapter` stays but internally uses pure CSS classes).
+
+### 2.3 Configuration
+
+```ruby
+StreamWeaver.configure do |config|
+  config.adapter = :alpine_js  # default, uses pure CSS classes
+  # or
+  config.adapter = :tailwind   # uses Tailwind utility classes
+end
+```
+
+---
+
+## Phase 3: Tailwind Adapter
+
+**Outcome:** Full shadcn fidelity when Tailwind is available.
+
+### 3.1 Add `tailwind_merge` Gem (Optional Dependency)
+
+```ruby
+# stream_weaver.gemspec
+spec.add_development_dependency 'tailwind_merge', '~> 1.0'
+```
+
+### 3.2 Build TailwindAdapter
+
+Port RubyUI's class strings directly. The classes are already defined in `~/work/ruby_ui/lib/ruby_ui/button/button.rb`, etc.
+
+```ruby
+module StreamWeaver
+  class TailwindAdapter < BaseAdapter
+    MERGER = TailwindMerge::Merger.new.freeze
+
+    BUTTON_BASE = "inline-flex items-center justify-center rounded-md font-medium transition-colors " \
+                  "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring " \
+                  "disabled:pointer-events-none disabled:opacity-50"
+
+    BUTTON_VARIANTS = {
+      primary: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+      secondary: "bg-secondary text-secondary-foreground hover:bg-opacity-80",
+      destructive: "bg-destructive text-white shadow-sm hover:bg-destructive/90",
+      outline: "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+      ghost: "hover:bg-accent hover:text-accent-foreground",
+      link: "text-primary underline-offset-4 hover:underline"
+    }.freeze
+
+    BUTTON_SIZES = {
+      sm: "px-3 py-1.5 h-8 text-xs",
+      md: "px-4 py-2 h-9 text-sm",
+      lg: "px-4 py-2 h-10 text-base",
+      xl: "px-6 py-3 h-12 text-base"
+    }.freeze
+
+    def render_button(view, component, state)
+      classes = MERGER.merge([
+        BUTTON_BASE,
+        BUTTON_VARIANTS[component.variant] || BUTTON_VARIANTS[:primary],
+        BUTTON_SIZES[component.size] || BUTTON_SIZES[:md],
+        component.options[:class]
+      ].compact.join(" "))
+
+      view.button(class: classes, type: "button", **data_attrs(component)) do
+        yield if block_given?
+      end
+    end
+
+    # ... similar for Card, Input, Alert, etc.
+    # Port class strings from ~/work/ruby_ui/lib/ruby_ui/*/
+  end
+end
+```
+
+### 3.3 Tailwind CSS Requirement
+
+When using the Tailwind adapter, the output HTML needs Tailwind CSS loaded. Options:
+- CDN link (easiest for development)
+- Bundled Tailwind (for production)
+- User provides their own Tailwind setup
+
+The adapter should inject the appropriate `<link>` or `<script>` in the HTML head.
+
+Tailwind v4 config needed for shadcn tokens:
+```css
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  /* ... */
+}
+```
+
+---
+
+## Phase 4: Port High-Value Components
+
+Port these from RubyUI, adapting for StreamWeaver's DSL pattern:
+
+### Priority 1 (most impact):
+| Component | RubyUI Source | DSL Example |
+|-----------|--------------|-------------|
+| **Sheet** | `ruby_ui/sheet/` | `sheet(:right) { text "Details..." }` |
+| **Skeleton** | `ruby_ui/skeleton/` | `skeleton width: "100%", height: "20px"` |
+| **Command** | `ruby_ui/command/` | `command_palette { item "Search...", shortcut: "⌘K" }` |
+| **Clipboard** | `ruby_ui/clipboard/` | `clipboard "code to copy"` |
+
+### Priority 2 (nice to have):
+| Component | RubyUI Source | DSL Example |
+|-----------|--------------|-------------|
+| **Combobox** | `ruby_ui/combobox/` | `combobox :user, choices, searchable: true` |
+| **Calendar** | `ruby_ui/calendar/` | `calendar :date, range: true` |
+| **AlertDialog** | `ruby_ui/alert_dialog/` | `alert_dialog "Are you sure?", confirm: "Delete"` |
+| **HoverCard** | `ruby_ui/hover_card/` | `hover_card { text "Preview content" }` |
+
+### Implementation Pattern
+
+For each component:
+1. Read RubyUI's Phlex component for structure
+2. Define StreamWeaver DSL method (in `components.rb` or new file)
+3. Add `render_*` method to PureCSSAdapter with CSS-variable styling
+4. Add `render_*` method to TailwindAdapter with RubyUI's exact class strings
+5. Add CSS for the pure CSS version to `shadcn_components.css`
+
+---
+
+## File Summary
+
+```
+lib/stream_weaver/
+├── assets/
+│   ├── shadcn_tokens.css          # Phase 1: semantic color tokens + dark mode
+│   ├── shadcn_base.css            # Phase 1: global base styles
+│   └── shadcn_components.css      # Phase 1: component styles using tokens
+├── adapters/
+│   ├── base_adapter.rb            # Phase 2: abstract adapter interface
+│   ├── alpine_js_adapter.rb       # Phase 2: existing adapter (pure CSS classes)
+│   └── tailwind_adapter.rb        # Phase 3: Tailwind utility classes
+├── components.rb                  # Existing + Phase 4 new components
+└── theme.rb                       # Updated to bridge --sw-* → shadcn tokens
+```
+
+---
+
+## Quick Start (for Claude Code session)
+
+```bash
+cd ~/work/rstreamlit/stream_weaver
+
+# Reference material:
+# - RubyUI gem source: ~/work/ruby_ui/lib/ruby_ui/
+# - RubyUI CSS tokens: ~/work/ruby_ui_web/app/assets/stylesheets/application.tailwind.css
+# - Current SW theme: lib/stream_weaver/theme.rb
+# - Current SW components: lib/stream_weaver/components.rb
+# - Current SW adapter: lib/stream_weaver/adapter/
+# - Full comparison: docs/ruby-ui-comparison.md
+
+# Start with Phase 1:
+# 1. Create lib/stream_weaver/assets/shadcn_tokens.css
+# 2. Create lib/stream_weaver/assets/shadcn_base.css
+# 3. Update component CSS to use var(--primary) etc.
+# 4. Add dark mode toggle JS
+# 5. Test with existing examples
+```

data/docs/porting-artifacts.md

@@ -0,0 +1,252 @@
+# Porting a Claude Artifact into StreamWeaver
+
+A repeatable process for reproducing a claude.ai-hosted Artifact (or any
+rich static HTML/CSS document) as a StreamWeaver app at high visual
+fidelity, and for feeding what you learn back into the framework. Proven
+on `examples/components/design_review_dsl.rb` / `design_review.css` (a
+six-option design-review document with option cards, chips, a comparison
+matrix, and a checklist split) -- see that pair, plus the `doc-parity`
+example bundled in the `streamweaver-visual-companion` skill, for two
+different genres this process has produced.
+
+This is a process doc, not a tutorial -- it assumes familiarity with
+`docs/theming-hooks.md` (the sw- hook contract) and the component/DSL
+vocabulary in `lib/stream_weaver/display_dsl.rb`.
+
+## The steps
+
+### a. Fetch the artifact HTML, strip the frame-runtime preamble
+
+A claude.ai Artifact page is served inside a "frame-runtime" wrapper: a
+large minified script handling theme sync with the parent claude.ai
+shell, scroll-position restore, link-click interception, MCP capability
+proxying, and an RTC lockdown. None of that is the authored content --
+it's platform plumbing for embedding the page in an iframe. The authored
+document always starts at the page's own `<title>` tag and the `<style>`
+block that follows it. Locate that boundary before doing anything else;
+everything above it is safe to ignore entirely.
+
+### b. Dissect into a rendering-capability checklist
+
+Read the authored `<style>` block and body once, closely, and produce two
+things:
+
+1. **Exact palettes.** Transcribe every custom property in both the light
+   and dark color sets verbatim (hex values, not approximations) -- these
+   become CSS custom properties in your own port, prefixed to avoid
+   collision with StreamWeaver's own `--sw-*` tokens (this port used
+   `--ad-*`; pick a prefix tied to the artifact's subject, not
+   StreamWeaver's).
+2. **A numbered checklist of rendering techniques**, not a prose
+   description -- "bordered callout with colored left accent + mono
+   kicker label", "option card: badge + title/subtitle + optional
+   pinned tag + wrapping chip row", "checklist tile: bordered card with
+   fixed-width colored glyph column", etc. Each item should be scoped
+   tightly enough that step (c) can answer "component, CSS, or gap?" for
+   it individually. The design-review port used 15 such items.
+
+### c. Gap-assess against the component vocabulary
+
+For each checklist item, check in this order:
+
+1. `docs/theming-hooks.md` -- does an existing component already emit a
+   stable `sw-` hook you can restyle? (Coverage note: that doc lists the
+   structural components; the doc-component family -- `doc_header`,
+   `doc_section_header`, `callout`, `columns`, `markdown` -- also emits
+   stable hooks not yet listed there (stream_weaver-d11). When a component
+   is missing from the doc, read the classes the adapter actually emits.)
+2. The doc/component family (`doc_header`, `doc_section_header`,
+   `callout`, `card`/`card_header`/`card_body`, `table`, `comparison`,
+   `columns`/`column`, `status_dot`, `badge`) -- proven to reach 1:1
+   Artifact parity for editorial documents (`doc-parity-example`).
+3. A prior parity slice (`examples/parity/tyrion_warroom_components.rb`)
+   for anything board/lane/topbar/navbar-shaped.
+4. Only if none of the above expresses it: `wireframe`/`wireframe_block
+   (html:)` for raw HTML/SVG passthrough. This is a last resort, not a
+   starting point -- see the "sanctioned escape hatches inside existing
+   components" note below before reaching for it.
+
+**Sanctioned escape hatches inside existing components, short of
+`wireframe_block`:**
+
+- `table(..., markdown: true)` renders each cell's markdown-processed
+  HTML *raw* -- already used by the framework to turn `[text](url)` into
+  `<a>` tags. A cell that needs a colored status dot or any other small
+  inline markup (not achievable through the table's own options) can emit
+  that markup directly as a string, e.g. a rating cell built from
+  `%(<span class="sw-status-dot sw-status-dot-green sw-status-dot-sm">
+  </span>#{value})`. This is a real, intentional feature of `Table`, not
+  a workaround -- prefer it over `wireframe_block` for anything
+  table-cell-shaped.
+- A `card_header`/`callout`/any container's block accepts arbitrary DSL
+  calls as extra children, rendered after that component's own built-in
+  fields. Use this to add a pinned corner badge, a markdown-rendered
+  subtitle (see gap notes below on why `card_header`'s own `meta:` can't
+  hold markdown), or any other small addition -- then position it with
+  CSS rather than fighting the DSL for a parameter that doesn't exist.
+
+### d. Port via the shared-DSL pattern + one unlayered CSS file
+
+Follow `prd_dsl.rb`/`prd_demo.rb`'s split:
+
+- `<name>_dsl.rb` -- a bare DSL body (no `app` wrapper), safe to load via
+  `instance_eval` from either a standalone demo or `canvas-push`. Caveat:
+  the canvas bridge currently injects only master-theme CSS, so a port
+  whose look lives in its own stylesheet renders on a canvas as correct
+  structure without the re-skin (stream_weaver-9uk) -- the standalone demo
+  is the faithful rendering until that lands or the genre's vocabulary is
+  promoted into a theme (step g).
+- `<name>_demo.rb` -- the standalone wrapper.
+- `<name>.css` -- **one** stylesheet, targeting only the `sw-` hooks
+  documented in `docs/theming-hooks.md` plus your own invented classes for
+  the handful of elements with no dedicated component.
+
+Every framework-emitted style lives in `@layer stream-weaver` (since
+stream_weaver-oeo), so a plain unlayered stylesheet always wins,
+regardless of selector specificity or `<head>` document order. There is
+no specificity fight to plan around -- write the CSS you want the
+rendered page to have, full stop.
+
+**The chrome-neutralization recipe.** StreamWeaver's default chrome wraps
+app content in `body.sw-layout-default` (caps width, adds padding) plus a
+child `#app-container` div that paints its *own* background/border/shadow
+from theme tokens (`--sw-color-bg-card`, etc.). If your port's content
+column is meant to be the *entire* page (an editorial document, not a
+dashboard with chrome around it), both of those need neutralizing or
+they'll show through as a visible "card within a card" boundary and can
+silently reintroduce the base theme's own light/dark palette underneath
+your own:
+
+```css
+body[class*="sw-layout-"] {
+  max-width: none;
+  padding: 0;
+  background: var(--your-bg-token);
+}
+#app-container {
+  background: transparent;
+  padding: 0;
+  margin: 0;
+  border: none;
+  box-shadow: none;
+  border-radius: 0;
+  max-width: none;
+}
+```
+
+Let your own top-level wrapper div (e.g. `.ad-doc`) become the sole
+layout/background authority: its own `max-width`/`margin: 0 auto`/padding
+replaces what `body`/`#app-container` used to provide.
+
+**A related gotcha worth checking early:** if your port uses
+`app(...) do ... end` (the top-level convenience wrapper) with a local
+`stylesheets:` path, `App#script_dir` resolves to the wrapper's own call
+site inside `lib/stream_weaver.rb`, not your script -- the local-file
+auto-detection raises `ArgumentError: ... resolves outside the app's
+script directory`. Use `StreamWeaver::App.new(...) do ... end` +
+`App.generate.run!` directly (the pattern
+`examples/parity/tyrion_warroom_components.rb` already uses), with an
+explicit `assets_dirs: [__dir__]` -- the top-level helper's fixed kwarg
+list has no `assets_dirs:` param at all, so this isn't optional once
+`stylesheets:` points at a local file.
+
+### e. Main-thread browser verification against the reference -- never builder self-assessment
+
+The agent that builds the port should verify the server renders without
+exceptions (boot it, curl it, grep the response for the structural
+markers you expect, kill the boot). It should **not** be the one to judge
+visual fidelity. A builder that wrote the CSS is the worst-positioned
+reviewer of whether it actually looks right -- render a page confidently
+wrong and re-reading your own rules won't catch it. Visual sign-off needs
+a separate pass, on the main thread, with both the port and the original
+artifact open side by side, in both light and dark mode.
+
+Two sharp edges specific to this workflow:
+
+- `playwright-cli` (and most headless browser tooling) blocks `file://`
+  navigation by default. Serve the reference artifact HTML over a real
+  origin instead: `ruby -run -e httpd <dir-containing-the-html> -p <port>`
+  from Ruby's stdlib, no extra gem needed.
+- Verify `location.href` in the browser before trusting a screenshot --
+  a stale tab left open from a prior round, or a redirect, will silently
+  screenshot the wrong page. Similarly, dark-mode toggles that persist
+  their preference to `localStorage` will carry a prior round's choice
+  into the next one -- clear it (or use a fresh browser context) before
+  comparing light mode again, or you will spend time debugging a "bug"
+  that's actually stale toggle state.
+
+### f. File framework gaps as bugs; fix at the app level first
+
+A port will surface real gaps -- places where an existing component is
+missing a `class:`/`style:` passthrough, has no per-row/per-item
+modifier hook, or where a convenience wrapper (like the top-level `app`
+helper above) breaks under a combination of options nobody had hit
+before. File each one as its own issue (this port's run filed
+stream_weaver-0n6, stream_weaver-mcn, stream_weaver-rhi, and
+stream_weaver-t37) rather than silently working around it and moving on
+-- the workaround belongs in the port either way (you can't block a port
+on a framework fix), but the gap needs to be visible to whoever plans the
+next promotion pass. Examples from this port:
+
+| Gap | Component | Workaround used |
+|---|---|---|
+| No per-row `class:`/tone hook | `Table` | Rely on the "pick" row being deterministically last (`tr:last-child`) |
+| No `class:`/`style:` passthrough | `Callout` | Wrap in a scoping `div` + descendant-selector CSS |
+| `meta:` renders escaped plain text, no markdown | `CardHeader` | Render the subtitle as an extra block child through `md` instead |
+| `stylesheets:` + top-level `app()` helper resolves `script_dir` wrong | `App` / top-level `app()` | Use `StreamWeaver::App.new` directly with `assets_dirs:` |
+
+### g. The promotion pass -- this is where token savings actually come from
+
+Be honest about the economics before claiming a port was cheap. This
+port's `design_review.css` + `design_review_dsl.rb` totals roughly 36.5KB
+of Ruby+CSS against the source artifact's 37.3KB of authored HTML+CSS --
+essentially 1:1, not a savings. That's expected: the artifact's palette,
+type pairing, chip/card idiom, and layout are all *bespoke to that one
+document*, so nothing in this port's CSS was reusable from an existing
+theme -- every rule had to be written fresh. Compare that to the
+`doc-parity-example` port, which reached the same 1:1 visual fidelity at
+roughly a 6x size reduction, because it could lean on the already-built
+`:doc` theme (Charter serif, compact editorial spacing, `--sw-color-*`
+tokens) almost as-is and only needed a handful of component calls on top.
+
+The lesson: a single port's cost is dominated by however much of its
+visual vocabulary is genuinely new. The savings show up the *second*
+time a similar genre gets ported -- if, and only if, someone takes the
+promotion step of pulling the recurring parts (the chip pattern, the
+pick-state idiom, the checklist-tile pattern, the chrome-neutralization
+recipe above) out of the one-off app CSS and into either a registered
+theme (`StreamWeaver.register_theme`) or genuinely new components. Budget
+for this as a distinct follow-up step, not something that happens for
+free as a side effect of shipping the first port. Until it happens, treat
+"tokens saved vs. hand-authoring the HTML" as *prose-only* savings (you
+still write the artifact's text once, not twice) rather than a savings on
+the surrounding visual machinery.
+
+### h. Add the pair to the visual-companion skill gallery
+
+Once a port is genericized (see below) and verified, copy the DSL/demo/CSS
+trio into
+`lib/stream_weaver/skills/streamweaver-visual-companion/examples/` so it
+ships with the skill (duplicated, not symlinked, so the skill stays
+self-contained if packaged separately -- see that directory's existing
+files for why). Add one line to that skill's `SKILL.md` gallery index
+naming the genre and the techniques it proves out, so a future session
+can tell at a glance which example is the closer starting point for a new
+request.
+
+## A note on genericizing content before it ships
+
+If the artifact you're porting contains anything personal or
+organization-specific (real names, an employer, an internal tool's real
+name, a personal design-philosophy framework), rewrite it as
+fictional-but-plausible content *before* committing -- same standard
+`prd_dsl.rb` already holds itself to (invented company, invented author).
+Preserve every visual pattern exactly (same number of option cards, same
+chip dimensions per card, same table shapes, same checklist tile count) --
+only the words change. Rename the example's own files at the same time if
+their name was content-derived (an artifact literally about "agent
+discovery" produced `agent_discovery_*` files; once genericized to a
+fictional product, the files were renamed to the genre-based
+`design_review_*` to match how `doc-parity-example` is named after its
+*genre* -- a document proving Artifact-grade doc parity -- not its
+original PRD's subject matter).