poetry-ui 0.0.2

data/lib/generators/poetry/skill/templates/poetry-design/references/paper.md

@@ -0,0 +1,56 @@
+# paper - bring a paper.design canvas into poetry
+
+Paper's canvas is real HTML + CSS, and its tokens are CSS custom properties
+on the same axes poetry themes use, so it speaks poetry's dialect directly.
+Two doors, independent - a theme handoff, and a canvas-to-components handoff.
+Translate INTO poetry primitives and tokens; never transcribe raw styles.
+
+## Door 1: theme -> an AA-gated theme (no MCP needed)
+
+1. In Paper, run **Copy theme** and paste the CSS into a file (e.g.
+   `paper-theme.css`).
+2. Run `bin/rails poetry:paper:import[paper-theme.css]` (or
+   `poetry:design:import` - it detects `.css`).
+3. **Read the report.** The importer parses the `:root` / `@theme` custom
+   properties (stripping a Tailwind `color-` namespace), resolves `var()`
+   references, converts values into poetry's OKLCH model, then measures every
+   touched pair against WCAG AA. A value that fails AA is **dropped and
+   reported with the nearest passing suggestion** - never shipped; a property
+   with no poetry role is dropped and listed, never guessed.
+4. It writes `app/assets/tailwind/poetry/design-overrides.css` and wires the
+   import. Rebuild CSS. `POETRY_DESIGN_FORCE=1` / `POETRY_DESIGN_JSON=1` as
+   with any import.
+
+Copy theme is a one-shot copy, not a live sync - re-run the import when the
+Paper theme changes.
+
+## Door 2: a canvas -> components (dual-MCP)
+
+Needs the **Paper MCP** connected alongside the poetry MCP. Paper's MCP ships
+with the Paper Desktop app and runs locally once a file is open; register it
+once: `claude mcp add paper --transport http http://127.0.0.1:29979/mcp
+--scope user`. The free tier's 100 tool calls/week is enough for a handoff.
+
+Flow:
+
+1. Read the design - `get_selection` / `get_tree_summary` for structure,
+   `get_jsx` (ask for the Tailwind form) and `get_computed_styles` for the
+   styling, `get_screenshot` to keep layout fidelity.
+2. Land the tokens first via Door 1 so Paper's variables line up with poetry
+   theme tokens.
+3. Translate, do not copy. Map each Paper subtree to the nearest poetry
+   primitive - consult `list_components` / `describe_component`; assemble with
+   `compose` / `build_page`, never hand-authored markup.
+4. Run poetry `check` LAST - a PASS verdict, not an eyeball.
+
+Mapping guide:
+
+- Artboard -> a poetry block or page.
+- Node subtree -> the nearest poetry component.
+- Tailwind classes from `get_jsx` -> poetry variants and theme tokens, not
+  copied class strings.
+- Computed styles -> poetry theme tokens (Door 1), never per-instance CSS.
+
+Optional round-trip: push a rendered poetry component back into Paper as
+editable layers with `write_html`, so a designer can review poetry's output
+on the canvas. Bank this as a review loop, not a build step.

data/lib/generators/poetry/skill/templates/poetry-design/references/study.md

@@ -0,0 +1,47 @@
+# study - extract a brand into a DESIGN.md poetry can import
+
+`study` turns a brand surface (a URL, screenshots, an existing style guide)
+into the design-skill ecosystem's shared artifact: a DESIGN.md. poetry both
+writes and reads the format, so the loop is:
+
+    study the brand -> DESIGN.md -> bin/rails "poetry:design:import[DESIGN.md]"
+
+## Writing the DESIGN.md
+
+Front-matter carries the machine-readable part:
+
+- Flat `colors:` = the LIGHT mode palette, role-named (`brand`, `surface`,
+  `text`, `accent`, ...). poetry's importer maps roles conservatively
+  (`brand` -> `--primary`, `surface` -> `--card`, `text` -> `--foreground`,
+  Material-style `on-*` -> `*-foreground`) and reports every mapping.
+- `modes.dark:` for dark values when the brand defines them. A light-only
+  study is fine: poetry PINS dark to its shipped defaults rather than
+  letting light values bleed into dark mode.
+- `rounded:` resolved to px; typography as metadata (family names, pairing
+  intent) - fonts never enter CSS via import.
+- Markdown sections (voice, imagery, spacing notes) carry the prose the
+  front-matter can't; the importer ignores what it can't parse and REPORTS
+  it rather than guessing.
+
+**Extract, never fabricate.** Record only what the brand actually shows.
+If the brand has no dark mode, don't invent one; if you can't find a
+motion language, omit the section. Dropped-with-a-note beats guessed - the
+import report is the honest ledger.
+
+## What import will do with it
+
+Role-mapped token overrides, WCAG AA enforced on the merged set: failing
+pairs are DROPPED with a deterministic nearest-AA suggestion (an OKLCH
+lightness walk, chroma held), and `POETRY_DESIGN_FORCE=1` is the only way
+a failing pair ships. Expect the report to move some values - a brand hex
+that fails AA against white comes back as the nearest passing neighbor,
+which is usually what the brand's own accessible surfaces do anyway.
+
+## redesign - same content, different fingerprint
+
+`redesign` keeps copy, information architecture, and brand meaning, and
+swaps the visual fingerprint: pick a different shipped theme
+(`references/theme.md`), re-run the brand's DESIGN.md on top if one
+exists, and re-audit. Nothing in the templates should need to change - if
+a redesign forces template edits, the original leaned on per-instance
+styling it shouldn't have had.

data/lib/generators/poetry/skill/templates/poetry-design/references/theme.md

@@ -0,0 +1,70 @@
+# theme - pick, adapt, or import a visual fingerprint
+
+One visual theme per app, chosen at install: `bin/rails g poetry:install
+--theme <name>` (re-runnable; the chosen fragment's bytes land in
+`app/assets/tailwind/poetry/style-default.css`). Components read tokens and
+`cn-*` names; the theme owns every visual decision, so switching themes is
+a reinstall, not a refactor.
+
+## The nine shipped themes
+
+| Theme | Character |
+|---|---|
+| `default` | poetry's original look - the new-york-v4 lineage the library was built against |
+| `vega` | closest to default: ring-based surfaces, subtle blur scrims, xl radii |
+| `nova` | compact - tighter paddings and smaller surfaces |
+| `mira` | compact and quiet - relaxed xs body text, heavily dimmed drawer scrims |
+| `rhea` | soft and elevated - capped 4xl radii, shadow-xl, blurred scrims |
+| `maia` | fully rounded - 4xl surfaces, deeply dimmed scrims |
+| `luma` | soft-round - blurred scrims and a floating drawer frame |
+| `lyra` | boxy and sharp - radius zero, type one step down, made for mono fonts |
+| `sera` | editorial - uppercase tracked type, underline-only fields, serif pairing |
+
+Choosing by brief, not by taste-in-a-vacuum:
+
+- Dense operational tools (admin, monitoring, tables everywhere): `nova` or
+  `mira` - the compact surfaces buy rows.
+- Consumer/marketing warmth: `rhea`, `maia`, or `luma` - rounded, elevated,
+  soft scrims.
+- Technical/developer products: `lyra` - sharp, mono-biased, zero radius.
+- Editorial/content products: `sera` - tracked uppercase labels, serif
+  pairing, underline fields.
+- `default` is the stock look. Picking it is legitimate but should be a
+  DECISION - when a brief implies any character at all, a non-default theme
+  is usually the stronger answer (the design-lint `stock-theme-nudge` rule
+  exists for exactly this).
+
+## Fonts ride the theme as metadata
+
+No poetry theme moves a font token - `lyra` is biased hard to mono
+(JetBrains Mono; radius forced to zero) and `sera` keeps serif company
+(Noto Serif, Instrument Serif), but both express their typography through
+size, weight, tracking, and uppercase utilities. The font-family itself is
+the app's call: add the family in the app's own CSS/font pipeline when
+installing lyra or sera.
+
+## Status color vocabulary
+
+The token set carries `--success`, `--warning`, and `--info` alongside
+`--destructive` (all four AA-managed in both modes). Badges ship soft
+status variants on them. Use the set; never invent status colors from
+palette utilities.
+
+## The DESIGN.md door (brand import/export)
+
+- `bin/rails poetry:design:export` writes this app's DESIGN.md (tokens +
+  treatment; `POETRY_DESIGN_PATH` to target elsewhere, `POETRY_DESIGN_FORCE=1`
+  to overwrite a non-poetry file). Run it so external design skills can read
+  the app's current design.
+- `bin/rails "poetry:design:import[path/to/DESIGN.md]"` plans role-mapped
+  token overrides from a foreign DESIGN.md (a brand study, or an export
+  from another design tool): conservative role aliases, WCAG AA enforced on the
+  MERGED set, failing pairs dropped with a deterministic nearest-AA
+  suggestion, dark values pinned when the source is light-only. The report
+  lists every mapping and every drop (`POETRY_DESIGN_JSON=1` for JSON);
+  `POETRY_DESIGN_FORCE=1` is the only way a failing pair ships.
+- Overrides land in `app/assets/tailwind/poetry/design-overrides.css` - the
+  one sanctioned place brand values live outside the theme fragment.
+
+Adapting a theme = shipped theme + DESIGN.md overrides on top. Full brand
+work = `study` (see `references/study.md`) then import.

data/lib/generators/poetry/skills_section.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Generators
+    # The Claude Code skills, shared by poetry:install and the standalone
+    # poetry:skill (the refresh path - re-run after updating poetry gems):
+    #
+    #   .claude/skills/poetry/           GENERATED from the live registry
+    #   .claude/skills/poetry-design/    curated taste layer (static templates)
+    #   .claude/skills/poetry-component/ authoring layer: anatomy, docs
+    #                                    standard, audit checklist (static)
+    #
+    # Same Thor note as AgentsSection: only methods on the generator class
+    # register as steps, so each generator declares its own public step and
+    # calls apply_poetry_skills.
+    #
+    # @api private
+    module SkillsSection
+      DESIGN_TEMPLATES = File.expand_path("skill/templates/poetry-design", __dir__)
+      COMPONENT_TEMPLATES = File.expand_path("skill/templates/poetry-component", __dir__)
+
+      # Writes or refreshes the three skill directories under
+      # .claude/skills/.
+      def apply_poetry_skills
+        Poetry::Ui.skill_files.each do |relative, content|
+          create_file ".claude/skills/poetry/#{relative}", content
+        end
+        design_skill_files.each do |relative, content|
+          create_file ".claude/skills/poetry-design/#{relative}", content
+        end
+        component_skill_files.each do |relative, content|
+          create_file ".claude/skills/poetry-component/#{relative}", content
+        end
+      end
+
+      # Path => content for the curated skills - the eval harness writes
+      # these without a Thor context (the agents_section_text pattern:
+      # Object.new.extend(SkillsSection).design_skill_files).
+      def design_skill_files
+        static_skill_files(DESIGN_TEMPLATES)
+      end
+
+      # Path => content for the poetry-component authoring skill (static
+      # templates).
+      def component_skill_files
+        static_skill_files(COMPONENT_TEMPLATES)
+      end
+
+      # Path => content for every .md under a template root.
+      def static_skill_files(templates)
+        root = Pathname(templates)
+        Dir.glob(root.join("**/*.md").to_s).to_h do |file|
+          [Pathname(file).relative_path_from(root).to_s, File.read(file)]
+        end
+      end
+    end
+  end
+end

data/lib/poetry/ui/chat.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The chat replay DSL: script a user/assistant conversation in
+    # Ruby, get a DETERMINISTIC timeline of
+    # streaming frames to replay through the real Turbo Stream pipeline -
+    # no model, no network, fixed ids, fixed pacing. The DSL is pure data
+    # (transcript + timing); rendering frames into Message rows is the
+    # consumer's job (the docs replay demo is the reference consumer).
+    #
+    # A tool with `approval: true` PAUSES its segment after the input frame;
+    # the frames that follow (its output - or denial - and later parts)
+    # belong to the continuation and are produced by
+    # `continuation_frames(approved:)` - the human-in-the-loop
+    # model, server-shaped: the pause is a rendered form, the continuation
+    # is the stream after the decision.
+    #
+    # @example Scripting a turn with a tool call
+    #   script = Poetry::Ui::Chat.script do
+    #     user "What's the weather in Tokyo?"
+    #     assistant do |w|
+    #       w.reasoning "Check the weather tool first."
+    #       w.tool("getWeather", input: { city: "Tokyo" }, sleep_ms: 800,
+    #              output: { temp: 21, condition: "clear" })
+    #       w.text "Clear skies and 21°C in Tokyo."
+    #     end
+    #   end
+    #   script.segments  # => enumerable segments; assistant segments carry
+    #                    #    frames (accumulated part states + sleeps + versions)
+    module Chat
+      # Builds a Script from the block - instance_eval'd, so bare `user`
+      # and `assistant` calls declare the segments in transcript order.
+      #
+      # @return [Script] the compiled, deterministic script
+      def self.script(&)
+        Script.new(&)
+      end
+
+      # One rendered state of an assistant row mid-stream.
+      Frame = Struct.new(:parts, :sleep_ms, :version, keyword_init: true)
+
+      # A step of the conversation: :user (text) or :assistant (frames,
+      # possibly pausing for approval).
+      class Segment
+        # kind (:user or :assistant), the deterministic DOM id, the user
+        # text, and the AssistantTurn (assistant segments only).
+        attr_reader :kind, :id, :text, :turn
+
+        def initialize(kind:, id:, text: nil, turn: nil)
+          @kind = kind
+          @id = id
+          @text = text
+          @turn = turn
+        end
+
+        # Whether this segment stops at an approval pause.
+        #
+        # @return [Boolean]
+        def pause? = kind == :assistant && turn.pause?
+
+        # The frame timeline up to (and including) an approval pause, or
+        # the whole turn when nothing pauses.
+        #
+        # @return [Array<Frame>]
+        def frames = turn.frames
+
+        # The frames after the approval pause, resolved by the decision.
+        #
+        # @param approved [Boolean] the human decision at the pause
+        # @return [Array<Frame>]
+        def continuation_frames(approved:) = turn.continuation_frames(approved: approved)
+
+        # The final resting parts (approval segments resolve per decision).
+        #
+        # @return [Array<Hash>] the part list as last rendered
+        def final_parts(approved: true)
+          return [{ kind: :text, text: text }] if kind == :user
+          return frames.last.parts unless pause?
+
+          continuation_frames(approved: approved).last.parts
+        end
+      end
+
+      # The DSL root: collects user/assistant segments in scripted order
+      # and assigns each a deterministic id.
+      class Script
+        # Per-chunk streaming delay (ms) when a text part names none.
+        DEFAULT_TEXT_DELAY_MS = 30
+        # Words per streamed text chunk in the compiled frames.
+        TEXT_CHUNK_WORDS = 3
+
+        def initialize(&)
+          @segments = []
+          @counter = 0
+          instance_eval(&)
+        end
+
+        # Declares a user message at this point in the transcript.
+        #
+        # @param text [String] the user's message
+        def user(text)
+          @segments << Segment.new(kind: :user, id: next_id, text: text)
+        end
+
+        # Declares an assistant turn: pass plain text, or take the block
+        # form and compose text / reasoning / tool parts in order.
+        #
+        # @param text [String, nil] shortcut for a single text part
+        # @yieldparam writer [Writer] appends parts to the turn
+        def assistant(text = nil, &block)
+          turn = AssistantTurn.new
+          if block
+            yield(turn.writer)
+          elsif text
+            turn.writer.text(text)
+          end
+          @segments << Segment.new(kind: :assistant, id: next_id, turn: turn)
+        end
+
+        # @return [Array<Segment>] the declared segments, in scripted order
+        attr_reader :segments
+
+        private
+
+        def next_id
+          @counter += 1
+          "chat-msg-#{@counter}"
+        end
+      end
+
+      # Collects writer calls into an ordered part list, then compiles the
+      # deterministic frame timeline.
+      class AssistantTurn
+        def initialize
+          @parts = []
+        end
+
+        # The Writer collecting this turn's parts (memoized - `assistant`
+        # yields it).
+        #
+        # @return [Writer]
+        def writer = @writer ||= Writer.new(@parts)
+
+        # Whether any tool part requests approval (pausing the segment).
+        #
+        # @return [Boolean]
+        def pause? = @parts.any? { |part| part[:kind] == :tool && part[:approval] }
+
+        # Frames up to (and including) the pause, or the whole turn.
+        #
+        # @return [Array<Frame>]
+        def frames
+          compile(@parts.take_while.with_index { |_part, i| i.zero? || !pause_before?(i) })
+        end
+
+        # Frames AFTER the pause point, resolved by the decision. Versions
+        # continue from the paused prefix so the morph guard stays monotonic.
+        # Parts scripted AFTER an approval tool are the APPROVED path
+        # (denial streams tool-output-denied and stops;
+        # the approved branch carries the follow-through). So a denied
+        # continuation is exactly the resolution frame.
+        #
+        # @param approved [Boolean] the human decision at the pause
+        # @return [Array<Frame>]
+        def continuation_frames(approved:)
+          raise Error, "turn has no approval pause" unless pause?
+
+          resolved = @parts.map do |part|
+            next part unless part[:kind] == :tool && part[:approval]
+
+            part.merge(state: approved ? :done : :denied,
+                       output: approved ? part[:output] : nil)
+          end
+          keep = approved ? resolved : resolved.take(pause_index + 1)
+          compile(keep).drop(frames.length)
+        end
+
+        private
+
+        def pause_index
+          @parts.index { |part| part[:kind] == :tool && part[:approval] }
+        end
+
+        def pause_before?(index)
+          before = @parts.first(index)
+          before.any? { |part| part[:kind] == :tool && part[:approval] }
+        end
+
+        # The accumulated-state timeline: every frame is the FULL part list
+        # as rendered at that instant (streaming morphs the same row).
+        def compile(parts)
+          frames = []
+          acc = []
+          version = 0
+          push = lambda do |sleep_ms|
+            version += 1
+            frames << Frame.new(parts: acc.map(&:dup), sleep_ms: sleep_ms, version: version)
+          end
+
+          parts.each do |part|
+            case part[:kind]
+            when :reasoning, :text
+              chunks = part[:text].split(/(?<=\S)\s+/).each_slice(Script::TEXT_CHUNK_WORDS).map { |w| w.join(" ") }
+              delay = part.fetch(:delay_ms, Script::DEFAULT_TEXT_DELAY_MS) || Script::DEFAULT_TEXT_DELAY_MS
+              acc << part.merge(text: "")
+              chunks.each do |chunk|
+                acc[-1] = acc[-1].merge(text: [acc[-1][:text], chunk].reject(&:empty?).join(" "))
+                push.call(delay)
+              end
+            when :tool
+              acc << part.merge(state: :loading, output: nil)
+              push.call(0)
+              # An approval tool always passes through :awaiting_approval -
+              # resolved or not - so the paused prefix and the resolved
+              # timeline share frame counts up to the pause and the
+              # continuation begins AT the resolution frame (a denial with
+              # nothing after it still streams its denial).
+              if part[:approval]
+                acc[-1] = acc[-1].merge(state: :awaiting_approval)
+                push.call(part.fetch(:sleep_ms, 0))
+              end
+              unless part[:approval] && part[:state].nil?
+                acc[-1] = acc[-1].merge(state: part[:state] || :done, output: part[:output])
+                push.call(part.fetch(:sleep_ms, 0))
+              end
+            end
+          end
+          frames
+        end
+      end
+
+      # The builder handed to `assistant do |w| ... end` - each call
+      # appends one part (text / reasoning / tool) to the turn, in order.
+      class Writer
+        def initialize(parts)
+          @parts = parts
+        end
+
+        # Appends a streamed text part.
+        #
+        # @param text [String] the assistant prose
+        # @param delay_ms [Integer, nil] per-chunk delay override (defaults
+        #   to Script::DEFAULT_TEXT_DELAY_MS)
+        # @return [Writer] self, for chaining
+        def text(text, delay_ms: nil)
+          @parts << { kind: :text, text: text, delay_ms: delay_ms }.compact
+          self
+        end
+
+        # Appends a reasoning part - streamed like text, rendered as the
+        # collapsible thinking block.
+        #
+        # @param text [String] the reasoning prose
+        # @param delay_ms [Integer, nil] per-chunk delay override
+        # @return [Writer] self, for chaining
+        def reasoning(text, delay_ms: nil)
+          @parts << { kind: :reasoning, text: text, delay_ms: delay_ms }.compact
+          self
+        end
+
+        # Appends a tool-call part: the input frame streams first (state
+        # :loading), then after sleep_ms the resolution frame carries the
+        # output. approval: true pauses the segment at the input frame for
+        # a human decision; denied: true scripts the denied resolution.
+        #
+        # @param name [String] the tool name as rendered
+        # @param input [Hash] the tool input payload
+        # @param output [Object, nil] the result shown on resolution
+        # @param sleep_ms [Integer] thinking time before the resolution
+        # @param approval [Boolean] pause for a human decision after input
+        # @param denied [Boolean] script the denied resolution
+        # @return [Writer] self, for chaining # -- the writer vocabulary mirrors the tool part's options
+        def tool(name, input:, output: nil, sleep_ms: 0, approval: false, denied: false)
+          @parts << { kind: :tool, name: name, input: input, output: output,
+                      sleep_ms: sleep_ms, approval: approval,
+                      state: denied ? :denied : nil }
+          self
+        end
+      end
+    end
+  end
+end

data/lib/poetry/ui/code_block_highlighter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Ui
+    # The CodeBlock's rouge seam: highlighting is a SOFT capability -
+    # `gem "rouge"` in the host Gemfile turns it on; without it the component
+    # renders the plain escaped code unchanged (the fallback is simply
+    # "no rouge", and nothing shifts because the markup shape is identical).
+    module CodeBlockHighlighter
+      module_function
+
+      # Whether rouge is loadable in this host (memoized).
+      #
+      # @return [Boolean]
+      def available?
+        return @available if defined?(@available)
+
+        @available = begin
+          require "rouge"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # -> html_safe highlighted markup - every line wrapped in .line (the
+      # counter hook), the requested ones also .hll (the theme's tint hook) -
+      # or nil when rouge is absent. Unknown languages lex as plain text.
+      def highlight(code, language:, highlight_lines: [])
+        return nil unless available?
+
+        lexer = Rouge::Lexer.find(language.to_s) || Rouge::Lexers::PlainText.new
+        formatter.new(highlight_lines: Array(highlight_lines).map(&:to_i))
+                 .format(lexer.lex(code)).html_safe
+      end
+
+      # Rouge 5 asserts a PLAIN HTML delegate inside its line-wise wrappers
+      # (HTMLLinewise cannot wrap HTMLLineHighlighter), so poetry carries its
+      # own line formatter over the stable token_lines API.
+      def formatter
+        @formatter ||= Class.new(Rouge::Formatters::HTML) do
+          def initialize(highlight_lines: [])
+            super()
+            @highlight_lines = highlight_lines
+          end
+
+          def stream(tokens)
+            token_lines(tokens).each.with_index(1) do |line_tokens, lineno|
+              classes = ["line"]
+              classes << "hll" if @highlight_lines.include?(lineno)
+              yield %(<span class="#{classes.join(" ")}">)
+              line_tokens.each { |token, value| yield span(token, value) }
+              yield "</span>\n"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/ui/engine.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Poetry
+  module Ui
+    # The Rails engine: wires the component classes, the poetry_* view
+    # helpers, the Turbo Stream toast action, and the preview paths into
+    # the host app.
+    class Engine < ::Rails::Engine
+      # Standard engine layout: app/components, app/helpers, and
+      # config/locales are picked up by Rails' engine path conventions.
+      config.autoload_paths << "#{Poetry::Ui.root}/app/components"
+      config.eager_load_paths << "#{Poetry::Ui.root}/app/components"
+
+      # ComponentsHelper lives in app/helpers (Zeitwerk-autoloaded), so unlike
+      # a lib/ helper it is NOT already loaded at gem-require time. A host gem
+      # that forces ActionView to load *during* initialization - e.g. an
+      # ActionText editor prepending to ActionView::Helpers::FormHelper
+      # - fires this on_load hook before the engine's
+      # app/helpers constant is resolvable, raising NameError at boot. Deferring
+      # the hook registration into a to_prepare block runs it only once autoload
+      # paths are wired (and re-runs safely on reload), so the constant always
+      # resolves. (poetry-core's TagHelper avoids this only because it lives in
+      # lib/ and is required eagerly.)
+      initializer "poetry_ui.helpers" do |app|
+        app.config.to_prepare do
+          ActiveSupport.on_load(:action_view) do
+            include Poetry::Ui::ComponentsHelper
+          end
+        end
+      end
+
+      # turbo_stream.poetry_toast(...) - the canonical server-side toast.
+      # poetry-ui does not depend on turbo-rails; hosts that load it get
+      # the action through turbo's own load hook (a no-op otherwise).
+      initializer "poetry_ui.turbo_stream_actions" do
+        ActiveSupport.on_load(:turbo_streams_tag_builder) do
+          include Poetry::Ui::ToastStreamActions
+        end
+      end
+
+      initializer "poetry_ui.previews" do |app|
+        app.config.view_component.previews.paths << "#{Poetry::Ui.root}/app/components"
+      end
+
+      # Lookbook is a dev-only dependency; guard so the engine never crashes
+      # a production (or lean test) host that does not load it (the
+      # poetry-core pattern).
+      initializer "poetry_ui.setup_lookbook" do |app|
+        app.config.lookbook.preview_paths << "#{Poetry::Ui.root}/app/components" if defined?(Lookbook)
+      end
+    end
+  end
+end