stream_weaver 0.3.0

data/lib/stream_weaver/display_dsl.rb

@@ -0,0 +1,1004 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  # Shared display-only component DSL methods.
+  # Included by both App (which adds interactive components) and FeedBuilder.
+  module DisplayDSL
+    # =========================================
+    # Containers
+    # =========================================
+
+    def div(**options, &block)
+      with_container(Components::Div.new(**options), &block)
+    end
+
+    def app_header(title, subtitle: nil, variant: :dark, &block)
+      with_container(Components::AppHeader.new(title, subtitle: subtitle, variant: variant), &block)
+    end
+
+    def card(**options, &block)
+      with_container(Components::Card.new(**options), &block)
+    end
+
+    def card_header(content_or_options = nil, **options, &block)
+      component = if content_or_options.is_a?(String)
+        Components::CardHeader.new(content_or_options, **options)
+      else
+        opts = content_or_options.is_a?(Hash) ? content_or_options.merge(options) : options
+        Components::CardHeader.new(nil, **opts)
+      end
+      with_container(component, &block)
+    end
+
+    def card_body(**options, &block)
+      with_container(Components::CardBody.new(**options), &block)
+    end
+
+    def card_footer(**options, &block)
+      with_container(Components::CardFooter.new(**options), &block)
+    end
+
+    def vstack(spacing: :md, align: nil, divider: false, **options, &block)
+      with_container(Components::VStack.new(spacing: spacing, align: align, divider: divider, **options), &block)
+    end
+
+    def hstack(spacing: :sm, align: nil, justify: nil, divider: false, **options, &block)
+      with_container(Components::HStack.new(spacing: spacing, align: align, justify: justify, divider: divider, **options), &block)
+    end
+
+    def grid(columns: 3, gap: :md, template: nil, template_areas: nil, template_rows: nil, template_columns: nil, **options, &block)
+      with_container(Components::Grid.new(columns: columns, gap: gap, template: template, template_areas: template_areas, template_rows: template_rows, template_columns: template_columns, **options), &block)
+    end
+
+    # @param n [Integer, nil] Optional column count, primarily used with
+    #   items:. With no widths:, columns already divide evenly (flex 1 1 0
+    #   per column) -- n alone is advisory. Combined with items:, it drives
+    #   auto-distribution (see below).
+    # @param widths [Array<String>, nil] Explicit per-column widths -- still
+    #   honored as before.
+    # @param items [Enumerable, nil] When given, items are split into n (or
+    #   widths.size, or 2) equal chunks via each_slice and each chunk is
+    #   wrapped in its own `column`; the block runs once per item (03
+    #   honorable mention: presidential_mockup hand-computed
+    #   `each_slice((size / 3.0).ceil)` for exactly this).
+    def columns(n = nil, widths: nil, items: nil, **options, &block)
+      return with_container(Components::Columns.new(widths: widths, **options), &block) unless items
+
+      n ||= widths&.size || 2
+      slice_size = [(items.size / n.to_f).ceil, 1].max
+
+      with_container(Components::Columns.new(widths: widths, **options)) do
+        items.each_slice(slice_size) do |slice|
+          column { slice.each { |item| block.call(item) } }
+        end
+      end
+    end
+
+    def column(**options, &block)
+      with_container(Components::Column.new(**options), &block)
+    end
+
+    def scroll_box(max_height: "300px", **options, &block)
+      with_container(Components::ScrollBox.new(max_height: max_height, **options), &block)
+    end
+
+    def grid_area(name, **options, &block)
+      with_container(Components::GridArea.new(name, **options), &block)
+    end
+
+    def sticky(top: nil, bottom: nil, left: nil, right: nil, z_index: nil, **options, &block)
+      with_container(Components::Sticky.new(top: top, bottom: bottom, left: left, right: right, z_index: z_index, **options), &block)
+    end
+
+    def overlay(z: 1, pointer_events: nil, **options, &block)
+      with_container(Components::Overlay.new(z: z, pointer_events: pointer_events, **options), &block)
+    end
+
+    def fullbleed(**options, &block)
+      with_container(Components::Fullbleed.new(**options), &block)
+    end
+
+    def collapsible(label, expanded: false, subtitle: nil, badge_text: nil, badge_variant: :default, **options, &block)
+      with_container(Components::Collapsible.new(label, expanded: expanded, subtitle: subtitle, badge_text: badge_text, badge_variant: badge_variant, **options), &block)
+    end
+
+    # Progressive disclosure without nested expandable_card hacks (03 gap #7):
+    # native <details>/<summary>, works with zero JS/Alpine.
+    def accordion(**options, &block)
+      with_container(Components::Accordion.new(**options), &block)
+    end
+
+    def section(title, open: false, **options, &block)
+      with_container(Components::AccordionSection.new(title, open: open, **options), &block)
+    end
+
+    # Static Kanban board layout (03 gap #9: tyrion hand-built its "War Room"
+    # board from plain divs with inline styles). No drag-and-drop -- that's
+    # future work; this is the static-columns layout primitive real apps
+    # were hand-rolling.
+    def board(**options, &block)
+      with_container(Components::Board.new(**options), &block)
+    end
+
+    def lane(title, **options, &block)
+      with_container(Components::Lane.new(title, **options), &block)
+    end
+
+    def board_card(**options, &block)
+      with_container(Components::BoardCard.new(**options), &block)
+    end
+
+    def alert(variant: :info, title: nil, dismissible: false, **options, &block)
+      with_container(Components::Alert.new(variant: variant, title: title, dismissible: dismissible, **options), &block)
+    end
+
+    # =========================================
+    # Text / display
+    # =========================================
+
+    def text(content, tone: nil, **options)
+      components << Components::Text.new(content, tone: tone, **options)
+    end
+
+    def md(content, **options)
+      components << Components::Markdown.new(content, **options)
+    end
+    alias_method :markdown, :md
+
+    (1..6).each do |level|
+      define_method(:"header#{level}") { |content, **options| components << Components::Header.new(content, level: level, **options) }
+    end
+    alias_method :header, :header2
+
+    def phrase(content, **options)
+      components << Components::Phrase.new(content, **options)
+    end
+
+    # =========================================
+    # Dashboard display
+    # =========================================
+
+    def stat_display(value:, label:, color: :blue, size: :md, **options)
+      components << Components::StatDisplay.new(value: value, label: label, color: color, size: size, **options)
+    end
+
+    def badge(text, variant: :default, size: :sm, **options)
+      components << Components::Badge.new(text, variant: variant, size: size, **options)
+    end
+
+    def status_dot(status: :gray, pulse: false, size: :md, **options)
+      components << Components::StatusDot.new(status: status, pulse: pulse, size: size, **options)
+    end
+
+    def type_tag(type_name, color: nil, **options)
+      components << Components::TypeTag.new(type_name, color: color, **options)
+    end
+
+    def pulse_indicator(color: :green, label: nil, **options)
+      components << Components::PulseIndicator.new(color: color, label: label, **options)
+    end
+
+    def activity_item(time:, title:, summary: nil, type: nil, **options)
+      components << Components::ActivityItem.new(time: time, title: title, summary: summary, type: type, **options)
+    end
+
+    def timeline_event(index:, event_type:, timestamp:, label:, fields: {}, expanded: false, **options)
+      components << Components::TimelineEvent.new(
+        index: index, event_type: event_type, timestamp: timestamp,
+        label: label, fields: fields, expanded: expanded, **options
+      )
+    end
+
+    def priority_item(priority: :normal, title:, description: nil, meta_left: nil, meta_right: nil, **options, &block)
+      component = Components::PriorityItem.new(
+        priority: priority, title: title, description: description,
+        meta_left: meta_left, meta_right: meta_right, **options
+      )
+      with_container(component, &block)
+    end
+
+    def progress_bar(value:, max: 100, variant: :default, show_label: false, animated: false, **options)
+      components << Components::ProgressBar.new(value: value, max: max, variant: variant, show_label: show_label, animated: animated, **options)
+    end
+
+    def spinner(size: :md, label: nil, **options)
+      components << Components::Spinner.new(size: size, label: label, **options)
+    end
+
+    def score_table(scores:, **options)
+      components << Components::ScoreTable.new(scores: scores, **options)
+    end
+
+    def table(positional_data = nil, data: nil, headers: nil, rows: nil, file: nil, path: nil, **options, &block)
+      actual_data = positional_data || data
+      table_component = Components::Table.new(
+        actual_data, headers: headers, rows: rows, file: file, path: path, **options, &block
+      )
+      # A deterministic (not SecureRandom) dom id, keyed off the enclosing
+      # fragment id plus a per-render occurrence counter, both of which
+      # replay identically across rebuilds of the same DSL for the same
+      # control-flow path. This is what lets InteractionRunner's row-granular
+      # narrowing (stream_weaver-95k) address a `<tr>` rendered by a prior
+      # rebuild -- a random id would never match between requests. Only
+      # tables using the column DSL have row identity worth addressing.
+      if table_component.columns.any?
+        render_state.table_counter += 1
+        fragment_part = (render_state.fragment_stack.last || "root").downcase.gsub(/[^a-z0-9]+/, "-")
+        table_component.dom_id = "table_#{fragment_part}-#{render_state.table_counter}"
+      end
+      # Resolve cells now (not lazily at render time) so any buttons a cell
+      # builds already exist in the component tree for dispatch to find --
+      # button-action requests never call #render (FAC-P2.1 decision 4).
+      table_component.resolve!(self, state, fragment: render_state.fragment_stack.last)
+      components << table_component
+    end
+
+    def status_badge(status, reasoning)
+      components << Components::StatusBadge.new(status, reasoning)
+    end
+
+    def external_link_button(label, url:, submit: false)
+      components << Components::ExternalLinkButton.new(label, url: url, submit: submit)
+    end
+
+    def link_to(label, href:, **options)
+      components << Components::Link.new(label, href: href, **options)
+    end
+
+    def navbar(**options, &block)
+      with_container(Components::Navbar.new(**options), &block)
+    end
+
+    def topbar(**options, &block)
+      with_container(Components::Topbar.new(**options), &block)
+    end
+
+    def nav_item(label, href: nil, active: false, **options)
+      components << Components::NavItem.new(label, href: href, active: active, **options)
+    end
+
+    # =========================================
+    # Visual skills content blocks
+    # =========================================
+
+    # Render a syntax-highlighted code block with optional file header.
+    # Uses Prism.js CDN for highlighting (loaded lazily).
+    #
+    # @param code [String] The source code to display
+    # @param lang [String, nil] Language for Prism.js highlighting (e.g. "ruby", "javascript")
+    # @param file [String, nil] File path to show in a header bar above the code
+    # @param truncate [Integer, nil] Max lines to show (with truncation indicator)
+    # @param scroll [Boolean] Enable scrolling for long code (default: true)
+    # @param copy [Boolean] Show a copy-to-clipboard affordance in the header (default: false)
+    #
+    # @example Basic
+    #   code_block("puts 'hi'", lang: "ruby")
+    #
+    # @example With file header and truncation
+    #   code_block(code, file: "src/app.rb", lang: "ruby", truncate: 10)
+    #
+    # @example With copy-to-clipboard affordance
+    #   code_block(code, lang: "ruby", copy: true)
+    def code_block(code, copy: false, **options)
+      components << Components::CodeBlock.new(code, copy: copy, **options)
+    end
+
+    # Render an image with optional caption.
+    # Supports local files, URLs, and base64 data URI conversion for export.
+    #
+    # @param src [String] Image source (URL or file path)
+    # @param alt [String] Alt text for accessibility
+    # @param caption [String, nil] Caption text below the image
+    # @param base64 [Boolean] Convert local file to base64 data URI (default: false)
+    #
+    # @example Basic
+    #   image_block("photo.png", alt: "A photo")
+    #
+    # @example With caption
+    #   image_block("diagram.svg", caption: "Figure 1: Architecture")
+    def image_block(src, **options)
+      components << Components::ImageBlock.new(src, **options)
+    end
+
+    # Render a Mermaid diagram.
+    # CDN loads lazily -- only when this method is called.
+    #
+    # @param code [String] Mermaid diagram definition
+    # @param zoom [Boolean] Enable zoom/pan controls (default: false)
+    # @param compact [Boolean] Compact mode for card embedding (default: false)
+    # @param layout [Symbol] Layout engine (:default or :elk)
+    # @param theme_vars [Hash, nil] Per-block Mermaid themeVariables overrides
+    # @param options [Hash] Additional options
+    #
+    # @example
+    #   mermaid("graph LR; A-->B")
+    #   mermaid("graph TD; A-->B-->C", zoom: true)
+    #   mermaid("graph LR; A-->B", compact: true)
+    #   mermaid("graph TD; A-->B", layout: :elk)
+    def mermaid(code, zoom: false, compact: false, layout: :default, theme_vars: nil, **options)
+      components << Components::Mermaid.new(
+        code, zoom: zoom, compact: compact, layout: layout,
+        theme_vars: theme_vars, **options
+      )
+    end
+
+    # =========================================
+    # Visual explainer components (T12)
+    # =========================================
+
+    # Render a horizontal pipeline step flow with arrow connectors.
+    # Steps are color-coded by status: complete (green), active (blue), pending (gray).
+    # Responsive: collapses to vertical layout on narrow screens.
+    #
+    # @param steps [Array<Hash>] Steps with :label, :description (optional), :status (:complete, :active, :pending)
+    #
+    # @example
+    #   pipeline steps: [
+    #     { label: "Build", status: :complete },
+    #     { label: "Test",  status: :active },
+    #     { label: "Deploy", status: :pending }
+    #   ]
+    def pipeline(steps:, **options)
+      components << Components::Pipeline.new(steps: steps, **options)
+    end
+
+    # Render a KPI dashboard with auto-fit grid of metric cards.
+    # Each card shows a large value, label, optional trend arrow, and optional color.
+    #
+    # @param metrics [Array<Hash>] Metrics with :value, :label, :color (optional), :trend (optional :up/:down/:flat)
+    #
+    # @example
+    #   kpi_dashboard metrics: [
+    #     { value: "99.9%", label: "Uptime", color: :green, trend: :up },
+    #     { value: "42ms",  label: "Latency", trend: :down }
+    #   ]
+    def kpi_dashboard(metrics:, **options)
+      components << Components::KpiDashboard.new(metrics: metrics, **options)
+    end
+
+    # Render a Chart.js chart. CDN loads lazily (only when this method is called).
+    # Supports: :bar, :line, :pie, :doughnut, :radar.
+    # Dark mode aware: reads --sw-text and --sw-border for grid/text colors.
+    #
+    # @param type [Symbol] Chart type
+    # @param data [Hash] Chart.js data config (labels, datasets)
+    # @param options [Hash] Chart.js options config
+    # @param height [Integer] Canvas height in pixels (default: 300)
+    #
+    # @example
+    #   chart type: :bar, data: { labels: ["A", "B"], datasets: [{ data: [1, 2] }] }
+    def chart(type:, data:, options: {}, height: 300, **extra)
+      components << Components::Chart.new(type: type, data: data, options: options, height: height, **extra)
+    end
+
+    # =========================================
+    # Keyboard shortcuts (visual skills)
+    # =========================================
+
+    # Register keyboard shortcuts with context-aware suppression.
+    # Non-visual component -- emits a <script> block.
+    # "mod" maps to Cmd on Mac, Ctrl elsewhere.
+    #
+    # @yield [kb] Builder for registering shortcuts
+    # @yieldparam kb [Components::KeyboardShortcuts] The shortcut registry
+    #
+    # @example
+    #   keyboard_shortcuts do |kb|
+    #     kb.on "mod+s", context: :global, js_action: "alert('save')"
+    #     kb.on "ArrowRight", context: :navigation, js_action: "console.log('next')"
+    #   end
+    def keyboard_shortcuts(**options, &block)
+      component = Components::KeyboardShortcuts.new(**options)
+      yield component if block
+      components << component
+      component
+    end
+
+    # =========================================
+    # Slide container (visual skills)
+    # =========================================
+
+    # Create a slide container for navigable slides.
+    # Supports :swap (one visible at a time) and :scroll_snap (CSS scroll-snap) modes.
+    #
+    # @param mode [Symbol] Display mode (:swap or :scroll_snap)
+    # @param progress_bar [Boolean] Show progress bar (default: true)
+    # @param keyboard_nav [Boolean] Enable arrow key navigation (default: true)
+    # @param nav_dots [Boolean] Show navigation dots (default: false)
+    # @param counter [Boolean] Show slide counter (default: false)
+    # @param options [Hash] Additional options
+    #
+    # @example Swap mode
+    #   slide_container mode: :swap do
+    #     slide "intro", "Introduction" do
+    #       text "Welcome"
+    #     end
+    #     slide "arch", "Architecture" do
+    #       text "Design"
+    #     end
+    #   end
+    #
+    # @example Scroll-snap mode
+    #   slide_container mode: :scroll_snap, nav_dots: true do
+    #     slide "s1" do
+    #       text "Slide 1"
+    #     end
+    #   end
+    def slide_container(**options, &block)
+      with_container(Components::SlideContainer.new(**options), &block)
+    end
+
+    # Create a slide within a slide_container.
+    #
+    # @param id [String] Unique slide identifier
+    # @param title [String, nil] Optional slide title
+    # @param type [Symbol] Slide type (:content, :title)
+    # @param options [Hash] Additional options
+    #
+    # @example
+    #   slide "intro", "Introduction" do
+    #     text "Welcome to the presentation"
+    #   end
+    def slide(id, title = nil, **options, &block)
+      with_container(Components::Slide.new(id, title, **options), &block)
+    end
+
+    # =========================================
+    # Theme toggle (visual skills auto-mode)
+    # =========================================
+
+    # Add a dark/light/auto mode toggle button.
+    # Auto-mode follows OS prefers-color-scheme via CSS media query + JS listener.
+    # Preference persists in localStorage.
+    #
+    # @param mode [Symbol] Initial mode (:dark, :light, :auto)
+    # @param hotkey [String, nil] Keyboard shortcut (e.g. "mod+shift+l")
+    # @param persist [Boolean] Persist preference in localStorage (default: true)
+    #
+    # @example
+    #   theme_toggle mode: :auto
+    #   theme_toggle mode: :auto, hotkey: "mod+shift+l"
+    def theme_toggle(mode: :auto, hotkey: nil, persist: true, **options)
+      components << Components::ThemeToggle.new(mode: mode, hotkey: hotkey, persist: persist, **options)
+    end
+
+    # =========================================
+    # Theme presets (visual skills T15)
+    # =========================================
+
+    # Apply a curated theme preset.
+    # Injects Google Fonts <link> and CSS custom property overrides
+    # for the selected preset. Affects both light and dark modes.
+    #
+    # Available presets: :editorial, :technical, :warm, :minimal, :terminal
+    #
+    # @param name [Symbol] Preset name
+    #
+    # @example
+    #   theme_preset :editorial   # Magazine serif + terracotta
+    #   theme_preset :warm        # Friendly rounded + amber
+    #   theme_preset :terminal    # Monospace retro hacker
+    def theme_preset(name, **options)
+      components << Components::ThemePreset.new(name, **options)
+    end
+
+    # =========================================
+    # Explainer components (visual skills T11)
+    # =========================================
+
+    # Render a sticky sidebar table-of-contents with scroll spy.
+    # Desktop (>=1000px): sticky 170px sidebar with IntersectionObserver.
+    # Mobile (<1000px): horizontal scrollable sticky bar.
+    #
+    # @param sections [Array<Hash>] Array of { id:, label: } hashes
+    # @param options [Hash] Additional options
+    #
+    # @example
+    #   sidebar_toc sections: [
+    #     { id: "summary", label: "Executive Summary" },
+    #     { id: "architecture", label: "Architecture" }
+    #   ]
+    def sidebar_toc(sections:, **options)
+      components << Components::SidebarToc.new(sections: sections, **options)
+    end
+
+    # Render a document-level header with eyebrow, serif title, and meta pills.
+    # Used to open PRDs, reports, and long-form explainer documents.
+    #
+    # Pills are an array of mixed items:
+    #   - String → plain meta text (e.g., "June 25, 2026")
+    #   - Hash { text:, variant: } → colored pill — variant: :default (blue), :warn (amber), :good (green)
+    #
+    # @param eyebrow [String, nil] Small all-caps label above the title
+    # @param title [String] Main document title (rendered in serif)
+    # @param pills [Array] Status pills and meta text items
+    #
+    # @example
+    #   doc_header(
+    #     eyebrow: "cultiv-ai · Personal OS",
+    #     title: "Calendar-Driven Travel State",
+    #     pills: [{ text: "Draft" }, "June 25, 2026", "Author: Forrest Chang"]
+    #   )
+    def doc_header(title:, eyebrow: nil, pills: [], **options)
+      components << Components::DocHeader.new(title: title, eyebrow: eyebrow, pills: pills, **options)
+    end
+
+    # Render a numbered section eyebrow + h2 heading.
+    # The eyebrow is a monospace number with an extending decorative line.
+    # Pass id: to make the section linkable from sidebar_toc.
+    #
+    # @param number [String] Section number label, e.g., "01"
+    # @param title [String] Section heading text
+    # @param id [String, nil] HTML id for TOC anchor linking
+    #
+    # @example
+    #   doc_section_header "01", "Problem Statement", id: "problem"
+    def doc_section_header(number, title, id: nil, **options)
+      components << Components::DocSectionHeader.new(number, title, id: id, **options)
+    end
+
+    # Render a non-dismissible callout box with colored left border.
+    # Unlike Alert, Callout is static -- no dismiss button.
+    #
+    # @param content [String, nil] Optional banner text, rendered as the sole
+    #   (or first) child -- sugar for the common one-line-banner case (03
+    #   honorable mention: raw hex/padding divs standing in for a banner).
+    # @param variant [Symbol] Callout type (:info, :warning, :success, :error, :tip)
+    # @param tone [Symbol, nil] Alias for variant: (kept consistent with `text`'s
+    #   tone: vocabulary); wins over variant: when both are given.
+    # @param title [String, nil] Optional callout title
+    # @param options [Hash] Additional options
+    # @yield Block of child components rendered inside the callout body
+    #
+    # @example
+    #   callout(variant: :warning, title: "Caution") do
+    #     text "Be careful with this API."
+    #   end
+    #
+    # @example
+    #   callout("Saved successfully.", tone: :success)
+    def callout(content = nil, variant: :info, tone: nil, title: nil, **options, &block)
+      component = Components::Callout.new(variant: tone || variant, title: title, **options)
+      components << component
+
+      parent_components = components
+      self.components = []
+      text(content) if content
+      evaluate_dsl_block(block) if block
+      component.children = components
+      self.components = parent_components
+      component
+    end
+
+    # Render a file-path-to-rationale mapping for pre-flight planning.
+    #
+    # @param files [Array<Hash>] Array of {path:, note:} hashes
+    # @example
+    #   implementation_map(files: [
+    #     { path: "lib/foo.rb", note: "Add the new method" }
+    #   ])
+    def implementation_map(files: [], **options)
+      components << Components::ImplementationMap.new(files: files, **options)
+    end
+
+    # Render an architecture decision block with labeled option cards.
+    # The block is evaluated in DecisionBuilder scope — only `option(...)` is valid inside it.
+    # Other DSL helpers (text, mermaid, etc.) are not available inside the block.
+    #
+    # @param question [String] The decision question shown as a heading
+    # @yield Block of `option(id:, label:, detail:, recommended:)` calls
+    #
+    # @example
+    #   decision(question: "Which database?") do
+    #     option(id: :pg, label: "PostgreSQL", detail: "Full ACID", recommended: true)
+    #     option(id: :sqlite, label: "SQLite", detail: "Zero-dep")
+    #   end
+    def decision(question:, **options, &block)
+      component = Components::Decision.new(question: question, **options)
+      components << component
+      if block
+        builder = DecisionBuilder.new(component)
+        builder.instance_eval(&block)
+      end
+      component
+    end
+
+    # Builder context for decision component's option calls
+    class DecisionBuilder
+      def initialize(component)
+        @component = component
+      end
+
+      def option(id:, label:, detail:, recommended: false)
+        @component.add_option(id: id, label: label, detail: detail, recommended: recommended)
+      end
+    end
+
+    # Render a wireframe surface block with raw HTML.
+    # CSS tokens (--wf-ink, --wf-muted, etc.) and helper classes
+    # (.wf-card, .wf-pill, .wf-muted, button.primary) are automatically
+    # scoped to .sw-wireframe-surface.
+    #
+    # @param html [String] Raw HTML fragment to render inside the wireframe surface
+    # @param surface [String] Surface type: browser, desktop, mobile, popover, panel
+    #
+    # @example
+    #   wireframe_block(html: '<h1>Login</h1><button class="primary">Sign in</button>')
+    def wireframe_block(html: "", surface: "browser", **options)
+      components << Components::WireframeBlock.new(html: html, surface: surface, **options)
+    end
+
+    # Render an HTML mockup wrapped in device chrome matching the surface type.
+    # Accepts a block that returns the HTML string to display inside the chrome frame.
+    # CSS tokens (--wf-ink, --wf-muted, etc.) and helper classes apply inside the frame.
+    #
+    # @param surface [Symbol, String] Device surface: :browser, :desktop, :mobile, :phone,
+    #   :tablet, :popover, :card, :widget, :panel
+    #
+    # @example
+    #   wireframe(surface: :browser) do
+    #     "<h1>Login</h1><button class='primary'>Sign in</button>"
+    #   end
+    def wireframe(surface: :browser, **options, &block)
+      html = block ? instance_exec(&block).to_s : ""
+      components << Components::Wireframe.new(html: html, surface: surface, **options)
+    end
+
+    # Render a code block with line-number-pinned annotation bubbles in a side panel.
+    # Uses Prism.js for syntax highlighting (loaded once per page).
+    # Layout: code pane left, annotation panel right — annotations aligned to their target lines.
+    # Annotated lines receive a subtle left-border highlight. Close annotations stack without overlap.
+    # See +Components::AnnotatedCode+ for behaviour notes on per-line highlighting limits.
+    def annotated_code(language: nil, annotations: [], **options, &block)
+      component = Components::AnnotatedCode.new(language: language, annotations: annotations, **options)
+      component.code = block ? instance_exec(&block) : ""
+      components << component
+      component
+    end
+
+    def diff(language: nil, **options, &block)
+      component = Components::DiffBlock.new(language: language, **options)
+      components << component
+      return component unless block
+
+      builder = DiffBlockBuilder.new
+      builder.instance_eval(&block)
+      component.before_code = builder.before_code
+      component.after_code  = builder.after_code
+      component
+    end
+
+    class DiffBlockBuilder
+      attr_reader :before_code, :after_code
+
+      def initialize
+        @before_code = ""
+        @after_code  = ""
+      end
+
+      def before(&block)
+        @before_code = block.call.to_s
+      end
+
+      def after(&block)
+        @after_code = block.call.to_s
+      end
+    end
+
+    def api_endpoint(method:, path:, description: nil, params: [], response: {}, **options)
+      component = Components::ApiEndpoint.new(
+        method: method, path: path, description: description,
+        params: params, response: response, **options
+      )
+      components << component
+      component
+    end
+
+    # Render side-by-side comparison panels.
+    # Use `before { ... }` and `after { ... }` named blocks inside
+    # to populate each panel.
+    #
+    # @param before_label [String] Label for the "before" panel (default: "Before")
+    # @param after_label [String] Label for the "after" panel (default: "After")
+    # @param options [Hash] Additional options
+    # @yield Block containing `before { ... }` and `after { ... }` calls
+    #
+    # @example
+    #   comparison(before_label: "Old", after_label: "New") do
+    #     before { text "Version 1" }
+    #     after { text "Version 2" }
+    #   end
+    def comparison(before_label: "Before", after_label: "After", **options, &block)
+      component = Components::Comparison.new(
+        before_label: before_label, after_label: after_label, **options
+      )
+      components << component
+      return component unless block
+
+      # Capture before/after blocks using a builder context
+      builder = ComparisonBuilder.new(self)
+      builder.instance_eval(&block)
+      component.before_children = builder.before_components
+      component.after_children = builder.after_components
+      component
+    end
+
+    # Builder context for comparison component's before/after blocks
+    class ComparisonBuilder
+      attr_reader :before_components, :after_components
+
+      def initialize(dsl)
+        @dsl = dsl
+        @before_components = []
+        @after_components = []
+      end
+
+      def before(&block)
+        @before_components = capture_components(&block)
+      end
+
+      def after(&block)
+        @after_components = capture_components(&block)
+      end
+
+      private
+
+      def capture_components(&block)
+        parent = @dsl.components
+        @dsl.components = []
+        @dsl.instance_eval(&block)
+        captured = @dsl.components
+        @dsl.components = parent
+        captured
+      end
+    end
+
+    # =========================================
+    # CSS-only helpers (T13)
+    # =========================================
+
+    # Render a hero section with accent background tint and large padding.
+    #
+    # @param options [Hash] Additional options
+    # @yield Block of child components rendered inside the hero
+    #
+    # @example
+    #   hero { header1 "Welcome" }
+    def hero(**options, &block)
+      with_container(Components::Hero.new(**options), &block)
+    end
+
+    # Render a reading-optimized prose container (max-width ~65ch).
+    #
+    # @param dropcap [Boolean] Whether to enable dropcap on first paragraph (default: false)
+    # @param options [Hash] Additional options
+    # @yield Block of child components rendered inside the prose container
+    #
+    # @example
+    #   prose(dropcap: true) { md "Long form text..." }
+    def prose(dropcap: false, **options, &block)
+      with_container(Components::Prose.new(dropcap: dropcap, **options), &block)
+    end
+
+    # Render a styled pullquote with optional attribution.
+    #
+    # @param text [String] The quote text
+    # @param attribution [String, nil] Attribution (e.g., "Author Name")
+    #
+    # @example
+    #   pullquote "Design is not just what it looks like.", attribution: "Steve Jobs"
+    def pullquote(text, attribution: nil, **options)
+      components << Components::Pullquote.new(text, attribution: attribution, **options)
+    end
+
+    # Render a monospace file tree display with color-coded status.
+    # Lines ending with [new], [modified], or [deleted] are color-coded.
+    #
+    # @param tree_text [String] Multi-line file tree text
+    #
+    # @example
+    #   dir_tree "src/\n  app.rb [modified]\n  new_file.rb [new]"
+    def dir_tree(tree_text, **options)
+      components << Components::DirTree.new(tree_text, **options)
+    end
+
+    # Render a color swatch legend (horizontal row of dots with labels).
+    #
+    # @param items [Array<Hash>] Array of { color: "#hex", label: "text" }
+    #
+    # @example
+    #   legend items: [{ color: "#22c55e", label: "New" }, { color: "#f59e0b", label: "Modified" }]
+    def legend(items:, **options)
+      components << Components::Legend.new(items: items, **options)
+    end
+
+    # Render a vertical arrow connector between sections.
+    #
+    # @param label [String, nil] Optional label on the arrow
+    #
+    # @example
+    #   flow_arrow label: "transforms into"
+    def flow_arrow(label: nil, **options)
+      components << Components::FlowArrow.new(label: label, **options)
+    end
+
+    # Render column count override buttons (1/2/3/4 columns).
+    # Uses JS to change grid-template-columns on the target element.
+    #
+    # @param target [String] CSS selector of the grid to control
+    # @param columns [Array<Integer>] Available column counts
+    #
+    # @example
+    #   layout_toggle target: ".my-grid", columns: [1, 2, 3]
+    def layout_toggle(target: ".sw-layout-target", columns: [1, 2, 3, 4], **options)
+      components << Components::LayoutToggle.new(target: target, columns: columns, **options)
+    end
+
+    # @example
+    #   copy_button "Copy summary", text: report_text
+    def copy_button(label = "Copy", text:, copied_label: "Copied!", **options)
+      components << Components::CopyButton.new(label, text: text, copied_label: copied_label, **options)
+    end
+
+    # =========================================
+    # Interactive components (render-only versions for FeedBuilder context)
+    # App overrides these with full callback-wiring implementations.
+    # =========================================
+
+    # Feed-context buttons carry the same identity guarantees as App#button:
+    # id: is an explicit override, key: gives content-stable identity, and
+    # repeat occurrences are auto-disambiguated (id: > key: > auto-derivation).
+    def button(label, key: nil, id: nil, **options, &block)
+      require 'digest/md5'
+      explicit_id = validate_scalar_key!(id, context: "button")
+      key = validate_scalar_key!(key, context: "button")
+      stable_id = if explicit_id
+        sanitize_explicit_id(explicit_id)
+      elsif block
+        id_input = key ? "#{label}:#{key}" : "#{label}:#{block.source_location.join(':')}"
+        Digest::MD5.hexdigest(id_input)[0..7]
+      else
+        @button_counter = (@button_counter || 0) + 1
+        @button_counter.to_s
+      end
+      btn = Components::Button.new(label, stable_id, **options, &block)
+      btn.id = disambiguate_component_id(btn.id, label: label, source_loc: block&.source_location)
+      components << btn
+    end
+
+    def select(key, choices, **options)
+      @_state[key] = options[:default] || "" unless @_state&.key?(key)
+      components << Components::Select.new(key, choices, **options)
+    end
+
+    def expandable_card(key:, title:, subtitle: nil, badge_text: nil, badge_variant: :default,
+                        status: nil, initially_expanded: false, **options, &block)
+      @_state[key] ||= initially_expanded if @_state
+      component = Components::ExpandableCard.new(
+        key: key, title: title, subtitle: subtitle,
+        badge_text: badge_text, badge_variant: badge_variant,
+        status: status, initially_expanded: initially_expanded,
+        **options
+      )
+      with_container(component, &block)
+    end
+
+    def show_toast(message, variant: :info, duration: nil)
+      return unless @_state
+      @_state[:_toasts] ||= []
+      toast_id = "toast_#{Time.now.to_f.to_s.gsub('.', '_')}_#{rand(1000)}"
+      toast = { id: toast_id, message: message, variant: variant }
+      toast[:duration] = duration if duration
+      @_state[:_toasts] << toast
+    end
+
+    private
+
+    # =========================================
+    # Interactive component identity (FAC-P0.1)
+    # =========================================
+
+    # Ensures a component's key/id is a stable scalar -- never a positional
+    # index or an arbitrary object's #inspect, which would silently break on
+    # any collection reorder.
+    def validate_scalar_key!(key, context:)
+      return key if key.nil?
+      unless key.is_a?(String) || key.is_a?(Symbol) || key.is_a?(Integer)
+        raise ArgumentError, "#{context}: key: must be a String, Symbol, or Integer, got #{key.class}"
+      end
+      key
+    end
+
+    # An explicit id: is used verbatim (it is the author's override), minus
+    # characters that aren't legal in an HTML id / CSS selector.
+    def sanitize_explicit_id(id)
+      id.to_s.gsub(/[^a-zA-Z0-9_-]+/, '_')
+    end
+
+    # Detects two interactive components resolving to the same id within a
+    # single build (typically same-label buttons in a loop, sharing block
+    # source_location). First occurrence keeps its id unchanged; each further
+    # occurrence gets a stable "-dup-N" suffix so it remains independently
+    # dispatchable -- no author intervention required.
+    #
+    # Occurrence-index ids are POSITION-stable, not CONTENT-stable: they hold
+    # steady across rerenders of the same list, but deleting or inserting an
+    # earlier item shifts the later suffixes. That is why the warning points
+    # at key:, which binds identity to the record instead of the slot.
+    #
+    # Under strict_ids the collision raises (dev) or warns (production) --
+    # after auto-disambiguation a residual collision is not reachable, so
+    # strict mode is really "tell me my ids are position-derived, loudly".
+    def disambiguate_component_id(candidate_id, label:, source_loc:)
+      occurrence = seen_component_ids[candidate_id]
+      seen_component_ids[candidate_id] = occurrence + 1
+      return candidate_id if occurrence.zero?
+
+      loc = source_loc ? Array(source_loc).join(':') : 'unknown location'
+      message = "StreamWeaver: duplicate component id for \"#{label}\" at #{loc} " \
+                "-- likely the same label/block in a loop. Pass a stable key:, e.g. " \
+                "button(#{label.inspect}, key: item.id) { ... }, for distinct, order-independent ids."
+
+      raise ArgumentError, message if strict_ids? && !StreamWeaver.production_env?
+
+      unless warned_duplicate_ids.include?(candidate_id)
+        warned_duplicate_ids << candidate_id
+        warn "#{message} Auto-assigned a unique id for now."
+      end
+
+      "#{candidate_id}-dup-#{occurrence + 1}"
+    end
+
+    # Occurrence table for auto-disambiguation. App overrides this with its
+    # pass-scoped render_state accumulator so every rebuild starts clean.
+    def seen_component_ids
+      @seen_component_ids ||= Hash.new(0)
+    end
+
+    def warned_duplicate_ids
+      @_warned_duplicate_ids ||= Set.new
+    end
+
+    def strict_ids?
+      StreamWeaver.strict_ids?
+    end
+
+    # Evaluates a user-supplied DSL block (FAC-P0.3). Arity-0 blocks keep the
+    # legacy instance_eval behavior (self inside the block is `receiver`).
+    # Arity>=1 blocks are called as a plain block.call(receiver) instead --
+    # instance_exec is deliberately not used, so the block keeps its own
+    # self/binding and can call methods on its enclosing object (e.g. a
+    # presenter) while still reaching the DSL via the yielded argument.
+    def evaluate_dsl_block(block, receiver = self)
+      return unless block
+      # instance_exec, not instance_eval: instance_eval yields the receiver to
+      # the block, which a zero-arity lambda -- the natural way to write
+      # `placeholder: -> { ... }` -- refuses to accept.
+      block.arity >= 1 ? block.call(receiver) : receiver.instance_exec(&block)
+    end
+
+    def with_container(component, &block)
+      components << component
+      return component unless block
+
+      parent_components = components
+      self.components = []
+      evaluate_dsl_block(block)
+      component.children = components
+      self.components = parent_components
+      component
+    end
+
+    def watch(key, &block); end
+    def on_start(&block); end
+    def after(seconds, &block); end
+    def every(seconds, &block); end
+
+    # Never implemented, and it reads exactly like the deferred-rendering verb
+    # an author would reach for -- so it raises instead of silently dropping the
+    # block it is given.
+    def defer(*)
+      raise NoMethodError, "defer is not a verb; use `fragment(:name, defer: true) { ... }`"
+    end
+  end
+end