poetry-ui 0.0.2

data/lib/poetry/ui.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "poetry/core"
+require "yaml"
+require_relative "ui/version"
+require_relative "ui/themes"
+require_relative "ui/code_block_highlighter"
+require_relative "ui/recipes"
+require_relative "ui/chat"
+require_relative "ui/webmcp"
+
+# The poetry namespace: poetry-ui shares it with poetry-core (the DSL)
+# and the optional poetry-charts.
+module Poetry
+  # The component library: ViewComponents tracking the full ported
+  # component vocabulary, built entirely on
+  # poetry-core's PUBLIC DSL - if a component here needs private core API,
+  # that is a core API gap, not a license to reach in.
+  module Ui
+    # The committed static-template-class list (herb-extracted in poetry's
+    # CI, drift-gated) - poetry:install reads it so hosts never need herb.
+    TEMPLATE_CLASSES_PATH = "config/template_classes.txt"
+
+    # Where the block templates live: the generator's source tree,
+    # scanned by the registry builder, the template-class extraction,
+    # the dummy's /blocks previews, and the MCP server's describe_block.
+    BLOCKS_DIR = "lib/generators/poetry/block/templates"
+
+    # Curated composition edges: which components a copy-in of X also needs
+    # locally. Single-sourced here - the add generator's recursive copy AND
+    # every registry item's registryDependencies read this one map.
+    # (Replaced by registry-carried anatomy when the contract's anatomy
+    # section lands.)
+    COMPONENT_DEPENDENCIES = {
+      "button" => %w[icon],
+      "dialog" => %w[button icon],
+      "sheet" => %w[dialog button icon], # subclasses Dialog::Component (shared dialog controller)
+      "alert_dialog" => %w[dialog button], # shares the dialog controller + posture
+      "field" => %w[label input],
+      "alert" => %w[icon],
+      "select" => %w[icon], # chevrons + check; Field is an optional pairing, not a hard edge
+      "number_field" => %w[input input_group button icon], # composes their chrome
+      "stat" => %w[icon], # the delta's trend arrow
+      "toolbar" => %w[button input separator], # the typed slots render them
+      "file_input" => %w[input icon], # input variant wears Input; the dropzone's upload glyph
+      "date_field" => %w[input], # the pre-enhancement native input wears Input's chrome
+      "time_field" => %w[date_field input], # DateField at hour granularity - one segment engine
+      "meter" => %w[progress], # wears Progress::Style chrome verbatim
+      "search_field" => %w[input input_group button icon], # composes their chrome
+      "tag_group" => %w[icon], # the remove glyph
+      "timeline" => %w[icon], # the indicator glyph
+      "tree" => %w[icon], # the chevron
+      "clipboard_text" => %w[input input_group button icon], # composes their chrome
+      "sensitive_input" => %w[input input_group button icon clipboard_text], # + the copy: engine
+      "code_block" => %w[button icon] # the copy affordance
+    }.freeze
+
+    # The usage skill's family partition: every component in exactly one
+    # reference file, so the skill's menu stays lean and an agent loads
+    # only the family it is composing in. The coverage gate fails on any
+    # new component until it is mapped here.
+    SKILL_FAMILIES = {
+      "forms" => %w[autocomplete button button_group calendar checkbox combobox date_field date_picker field
+                    field_group field_separator fieldset
+                    file_input input input_group input_otp label native_select number_field
+                    questionnaire radio_group search_field select sensitive_input slider switch textarea time_field
+                    toggle toggle_group],
+      "overlays" => %w[alert_dialog command command_dialog context_menu dialog drawer
+                       dropdown_menu hover_card menubar popover sheet tooltip],
+      "data" => %w[accordion avatar badge card carousel clipboard_text code_block collapsible data_table empty
+                   item metadata_list meter stat table tag_group timeline toolbar tree typeset],
+      "feedback" => %w[alert deferred progress skeleton spinner toast toast_trigger toaster],
+      "navigation" => %w[breadcrumb navigation_menu pagination sidebar tabs],
+      "foundations" => %w[icon kbd link marker separator],
+      "chat" => %w[attachment bubble message message_scroller],
+      "layout" => %w[aspect_ratio resizable scroll_area]
+    }.freeze
+
+    class << self
+      # Gem root (the directory containing lib/, app/, config/).
+      def root
+        @root ||= Pathname.new(File.expand_path("../..", __dir__))
+      end
+
+      # @return [Array<String>] the committed template-static classes
+      def template_classes
+        root.join(TEMPLATE_CLASSES_PATH).read.lines
+            .map(&:strip).reject { |line| line.empty? || line.start_with?("#") }
+      end
+
+      # The public poetry_* helper names, so poetry check / poetry-agent know
+      # the full set (group / provider helpers AND the define_method'd part
+      # helpers like poetry_table_cell) WITHOUT booting Rails. The module's
+      # method bodies reference component constants only at call time, so
+      # requiring the file standalone is safe.
+      def helper_names
+        require root.join("app/helpers/poetry/ui/components_helper.rb")
+        ComponentsHelper.public_instance_methods(false).grep(/\Apoetry_/).map(&:to_s)
+      rescue StandardError
+        # Fallback: the static-def helpers (misses define_method ones) if the
+        # module can't load standalone in some host.
+        root.join("app/helpers/poetry/ui/components_helper.rb").read.scan(/def (poetry_[a-z_]+)/).flatten.uniq
+      end
+
+      # The registry builder this gem commits from (booted contexts only:
+      # rake registry:generate/verify and the sync test share it, so the
+      # drift gate always compares against the exact construction that
+      # generated the file - helpers AND blocks sections included).
+      def registry
+        components = Poetry::Core::Registry.new(source_root: root).components
+        component_paths = components.map(&:component_path)
+        Poetry::Core::Registry.new(
+          components: components, source_root: root,
+          helpers: registry_helpers(component_paths: component_paths),
+          blocks: registry_blocks(component_paths: component_paths),
+          helper_args: registry_helper_args,
+          descriptions: registry_descriptions,
+          form_builder: Poetry::Ui::FormBuilder.registry_section
+        )
+      end
+
+      # The editorial per-component descriptions merged into the registry
+      # (component_path => one-liner, from config/component_descriptions.yml).
+      # Absent file -> nil, so a registry without it stays lint-identical, like
+      # every other optional section.
+      def registry_descriptions
+        path = root.join("config/component_descriptions.yml")
+        path.exist? ? YAML.safe_load_file(path) : nil
+      end
+
+      # The interop item projection - registry items in the ecosystem's
+      # shared JSON item schema, boot-free
+      # from the COMMITTED registry - the docs site serves /r/*.json from
+      # this, and the add generator matches gem-satisfied dependencies
+      # against its names.
+      def registry_items
+        Poetry::Core::RegistryItems.new(
+          registry: YAML.safe_load_file(root.join(Poetry::Core::Registry::RELATIVE_PATH)),
+          root: root, gem_name: "poetry-ui", gem_version: VERSION,
+          dependencies: COMPONENT_DEPENDENCIES
+        )
+      end
+
+      # The recipes projection: skill bundles, scaffold template
+      # sets, and screen slices as registry items -
+      # served at /r/*.json beside components and blocks, installed by
+      # poetry:add or any client speaking the same item schema.
+      def recipe_items
+        Poetry::Core::RecipeItems.new(
+          recipes: Recipes.definitions, gem_name: "poetry-ui", gem_version: VERSION
+        )
+      end
+
+      # The installable component-usage skill: a lean SKILL.md menu +
+      # per-family references, generated from the live
+      # registry - the seam the poetry:skill generator and the eval
+      # harness share (the agents_section_text pattern).
+      def skill_files
+        Poetry::Core::SkillText.new(
+          registry: registry, families: SKILL_FAMILIES, charts_registry: charts_registry
+        ).files
+      end
+
+      # Tolerant on charts, like the AGENTS.md census: a host without the
+      # gem (or with a stubbed/partial one) just drops the charts reference.
+      def charts_registry
+        return nil unless defined?(Poetry::Charts::Engine)
+
+        Poetry::Charts.registry
+      rescue StandardError
+        nil
+      end
+
+      # The MCP server's runtime skill map (get_skill): the SAME
+      # files `rails g poetry:skill` writes, for hosts that cannot write
+      # files. Boot-free by construction - the usage skill regenerates from
+      # the COMMITTED registries (never the booted builders above), the
+      # design skill reads its static templates - so the exe can serve both
+      # without Rails. Lazy: nothing generates until an agent asks.
+      def agent_skills
+        {
+          "poetry" => -> { runtime_skill_files },
+          "poetry-design" => lambda {
+            require "generators/poetry/skills_section"
+            Object.new.extend(Poetry::Generators::SkillsSection).design_skill_files
+          },
+          "poetry-component" => lambda {
+            require "generators/poetry/skills_section"
+            Object.new.extend(Poetry::Generators::SkillsSection).component_skill_files
+          }
+        }
+      end
+
+      # The usage-skill files regenerated boot-free from the COMMITTED
+      # registries (never the booted builders above) - what the MCP server
+      # and the recipes projection serve without Rails.
+      #
+      # @api private
+      def runtime_skill_files
+        Poetry::Core::SkillText.new(
+          registry: Poetry::Core::Registry.committed(root),
+          families: SKILL_FAMILIES, charts_registry: committed_charts_registry
+        ).files
+      end
+
+      # The charts reference rides along whenever the charts gem is present
+      # (its committed registry, not its booted builder); absent, the skill
+      # simply drops it - the charts_registry tolerance, boot-free.
+      def committed_charts_registry
+        require "poetry/charts"
+        Poetry::Core::Registry.committed(Poetry::Charts.root)
+      rescue LoadError, StandardError
+        nil
+      end
+
+      # The parameter kinds that count as positional in a signature.
+      POSITIONAL_PARAM_KINDS = %i[req opt].freeze
+
+      # The registry "helper_args" map: max positional arity for EVERY
+      # poetry_* helper, introspected from the real method signatures, so
+      # the linter can flag the crash class of `poetry_link "text", href:`
+      # against a kwargs-only helper. Rest-signatures are omitted - the
+      # linter enforces arity only where a key exists.
+      #
+      # @api private
+      def registry_helper_args
+        helper_names.sort.filter_map do |name|
+          params = ComponentsHelper.instance_method(name.to_sym).parameters
+          next if params.any? { |kind, _param| kind == :rest }
+
+          [name, params.count { |kind, _param| POSITIONAL_PARAM_KINDS.include?(kind) }]
+        end.to_h
+      end
+
+      # The registry "helpers" section: every poetry_* helper that
+      # maps to no component - group/provider/item wrappers - each carrying
+      # its declared value contract (ComponentsHelper::HELPER_CONTRACTS) or
+      # {} for a plain wrapper.
+      def registry_helpers(component_paths:)
+        mapped = component_paths.map { |path| "poetry_#{path.delete_prefix("poetry/ui/").tr("/", "_")}" }
+        (helper_names - mapped).sort.to_h do |name|
+          [name, ComponentsHelper::HELPER_CONTRACTS.fetch(name, {})]
+        end
+      end
+
+      # The registry "blocks" section: every block template's metadata,
+      # all source-derived - title/description/keywords from the
+      # mandatory poetry:block header (keywords power the MCP compose
+      # tool's brief routing), the composed component list from the
+      # template's own poetry_* calls (longest-prefix fold:
+      # sidebar_menu_button counts as sidebar), the gem-relative template
+      # path for boot-free source reads. No hand-authored catalog to drift.
+      def registry_blocks(component_paths:)
+        titles = component_paths.map { |path| path.delete_prefix("poetry/ui/").tr("/", "_") }
+        Dir.glob(root.join(BLOCKS_DIR, "*.html.erb").to_s).to_h do |file|
+          source = File.read(file)
+          header = source.match(
+            /\A<%#\s*poetry:block\s+title="([^"]*)"\s+description="([^"]*)"(?:\s+keywords="([^"]*)")?\s*%>/
+          )
+          raise Poetry::Core::Error, "#{file} is missing its poetry:block header" unless header
+
+          entry = { "title" => header[1], "description" => header[2],
+                    "components" => block_components(source, titles: titles),
+                    "template" => "#{BLOCKS_DIR}/#{File.basename(file)}" }
+          entry["keywords"] = header[3].split(",").map(&:strip) if header[3]
+          [File.basename(file, ".html.erb").tr("_", "-"), entry]
+        end
+      end
+
+      # The distinct components a block composes, folded from its poetry_*
+      # helper calls: each call maps to the LONGEST component title that
+      # prefixes it (poetry_sidebar_menu_badge -> sidebar; poetry_table_head
+      # -> table); calls matching no component (pure wrapper helpers like
+      # poetry_input_group_addon fold through input_group) are dropped
+      # rather than guessed.
+      def block_components(source, titles:)
+        source.scan(/\bpoetry_([a-z0-9_]+)/).flatten.uniq.filter_map do |called|
+          titles.select { |title| called == title || called.start_with?("#{title}_") }.max_by(&:length)
+        end.uniq.sort
+      end
+    end
+  end
+end
+
+require_relative "ui/engine"

data/lib/poetry-ui.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience entrypoint so `require "poetry-ui"` (Bundler auto-require)
+# resolves to the namespaced Poetry::Ui gem.
+require_relative "poetry/ui"

data/lib/tasks/poetry/check.rake

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Host-side poetry check: lint the app's ERB against the committed
+# registry + controllers manifest.
+# Loaded automatically by the engine (lib/tasks).
+namespace :poetry do
+  desc "Lint app ERB + icon declarations in app Ruby against the poetry registry " \
+       "(glob arg overrides the default sweep; POETRY_CHECK_JSON=1 for JSON)"
+  task :check, [:glob] => :environment do |_task, args|
+    # The linter parses ERB with herb, which stays out of poetry's runtime
+    # dependencies on purpose (hosts never need it to RENDER) - same
+    # optional-parser posture as poetry:verify's template gate.
+    unless Poetry::Core::CSS::TemplateClasses.available?
+      abort "poetry:check: the herb gem is required to parse templates - " \
+            "add `gem \"herb\"` to your Gemfile (development group is enough)"
+    end
+
+    # Default sweep: ERB through the template tier, app Ruby through the
+    # icon-declaration tier (the FLASH_ICONS pattern lives in .rb).
+    patterns = args[:glob] ? [args[:glob]] : ["app/{views,components}/**/*.html.erb", "app/**/*.rb"]
+    paths = patterns.flat_map { |pattern| Dir.glob(Rails.root.join(pattern).to_s) }.uniq
+    if paths.empty?
+      warn "poetry check: no files matched #{patterns.join(", ").inspect}"
+      exit 0
+    end
+
+    helpers = Poetry::Ui.helper_names
+    roots = [Poetry::Ui.root]
+    if defined?(Poetry::Charts::ComponentsHelper)
+      helpers += Poetry::Charts::ComponentsHelper.public_instance_methods(false)
+                                                 .grep(/\Apoetry_/).map(&:to_s)
+      # The charts registry must join the catalog, not just the helper
+      # names - a name-valid pathless helper reads as a yielding wrapper
+      # (the chart yieldless-block false-positive class).
+      roots << Poetry::Charts.root
+    end
+    # The active set's names light up membership validation (the value
+    # contract) and the declaration tier; a host without a
+    # registered set still checks icon-name shape.
+    icon_names = begin
+      Poetry::Core::Icons.set.names
+    rescue Poetry::Core::Error
+      nil
+    end
+    catalog = Poetry::Core::Check::Catalog.from_registries(roots, helpers: helpers, icon_names: icon_names)
+    findings = Poetry::Core::Check::Runner.new(catalog).run(paths)
+
+    # The taste tier: design-slop warnings join the mechanical
+    # findings on request - same vocabulary, same JSON/text output. The
+    # stock-theme nudge fires only for a FOREIGN DESIGN.md (a brand waiting
+    # to be applied) - poetry's own export IS the current state.
+    if ENV["POETRY_CHECK_DESIGN"] == "1"
+      # DesignLint herb-parses templates - the .rb paths in the sweep are
+      # the declaration tier's, not its.
+      findings += paths.grep(/\.erb\z/).flat_map { |path| Poetry::Core::DesignLint.lint(File.read(path), file: path) }
+      design_md = Rails.root.join("DESIGN.md")
+      foreign = design_md.exist? && Poetry::Core::DesignMd.parse(design_md.read)["theme"].nil?
+      findings += Poetry::Core::DesignLint.lint_dom(
+        doc: nil,
+        context: { design_md_present: foreign,
+                   overrides_present: Rails.root.join("app/assets/tailwind/poetry/design-overrides.css").exist? }
+      )
+    end
+
+    if ENV["POETRY_CHECK_JSON"] == "1"
+      puts Poetry::Core::Check.to_json(findings)
+    else
+      puts Poetry::Core::Check.to_text(findings)
+    end
+
+    exit 1 if findings.any? { |finding| finding.severity == :error }
+  end
+end

data/lib/tasks/poetry/design.rake

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+# Host-side DESIGN.md export: serialize THIS app's poetry design as
+# the design-skill ecosystem's shared artifact, so external design
+# skills can read the system the app actually ships. Loaded
+# automatically by the engine (lib/tasks).
+namespace :poetry do
+  namespace :design do
+    desc "Export this app's poetry design to DESIGN.md " \
+         "(POETRY_DESIGN_PATH overrides the target; POETRY_DESIGN_FORCE=1 overwrites a non-poetry file)"
+    task export: :environment do
+      path = Pathname.new(ENV["POETRY_DESIGN_PATH"] || Rails.root.join("DESIGN.md"))
+      if path.exist? && Poetry::Core::DesignMd.parse(path.read)["theme"].nil? && ENV["POETRY_DESIGN_FORCE"] != "1"
+        abort "poetry:design:export: #{path} exists and was not written by poetry - " \
+              "set POETRY_DESIGN_PATH to export elsewhere, or POETRY_DESIGN_FORCE=1 to overwrite"
+      end
+
+      theme = poetry_design_installed_theme
+      registry = YAML.safe_load_file(Poetry::Ui.root.join(Poetry::Core::Registry::RELATIVE_PATH))
+      details = Poetry::Ui::Themes.details(theme).merge(
+        "components_count" => registry.fetch("components").size,
+        "generator" => "bin/rails poetry:design:export"
+      )
+      doc = Poetry::Core::DesignMd.build(tokens: Poetry::Core::Tokens.load, theme: theme, details: details,
+                                         deviations: poetry_design_declared_overrides)
+      poetry_design_apply_overrides(doc)
+      path.write(Poetry::Core::DesignMd.serialize(doc))
+
+      poetry_design_warn_on_token_drift
+      puts "poetry:design:export: wrote #{path} (theme #{theme})"
+    end
+
+    # The .cn-* override contract (the intent-vs-accident
+    # model): token-level restyling has a sanctioned channel
+    # (poetry:design:import -> design-overrides.css); host CSS that targets
+    # theme-owned .cn-* classes is the OTHER channel, and every such
+    # override must be declared - dated, reasoned, scoped - under
+    # `overrides:` in config/poetry_components.yml. This task reports both
+    # directions (undeclared drift AND stale declarations); undeclared
+    # findings print a paste-ready declaration. Never silence a finding to
+    # skip fixing it - declare only what the design owner confirms.
+    desc "Report host CSS overriding theme-owned .cn-* classes against the declared contract " \
+         "(config/poetry_components.yml `overrides:`; STRICT=1 exits nonzero on undeclared/invalid)"
+    task overrides: :environment do
+      scan = Poetry::Core::CSS::OverrideScan.new(
+        sources: poetry_design_host_css_sources,
+        declarations: poetry_design_declared_overrides
+      )
+
+      scan.invalid.each { |message| puts "  INVALID   #{message}" }
+      scan.stale.each do |declaration|
+        puts "  STALE     overrides[#{declaration.index}] (cn: #{declaration.cn.inspect}) matches no host CSS - " \
+             "remove it or fix its `files:` scope"
+      end
+      scan.undeclared.each do |path, classes|
+        puts "  UNDECLARED #{path}: #{classes.join(", ")}"
+        puts "    declare it (after confirming intent) in config/poetry_components.yml under overrides:"
+        puts scan.snippet_for(path, classes).gsub(/^/, "      ")
+      end
+
+      if scan.ok?
+        puts "poetry:design:overrides: clean - #{scan.declared_count} declared override(s), " \
+             "#{scan.stale.size} stale declaration(s)"
+      else
+        message = "poetry:design:overrides: #{scan.undeclared.sum { |_, c| c.size }} undeclared .cn-* " \
+                  "override(s), #{scan.invalid.size} invalid declaration(s)"
+        ENV["STRICT"] == "1" ? abort(message) : puts(message)
+      end
+    end
+
+    desc "Import a design source into token overrides " \
+         "(a DESIGN.md, a Figma/DTCG variables .json, or a Paper/CSS .css theme -> " \
+         "app/assets/tailwind/poetry/design-overrides.css; AA enforced at the door, " \
+         "POETRY_DESIGN_FORCE=1 ships failing pairs, POETRY_DESIGN_JSON=1 for a JSON report)"
+    task :import, [:path] => :environment do |_task, args|
+      poetry_design_run_import(args[:path], task: "poetry:design:import")
+    end
+  end
+
+  # Design-tool token bridges: thin, discoverable entry points onto the SAME
+  # importer. `TokenImport.load` dispatches by extension, so a Figma variables
+  # .json or a Paper "Copy theme" .css runs through the exact AA-gated pipeline
+  # poetry:design:import uses -- imported swatches inherit the contrast law, the
+  # drop-not-fabricate rule, and the dark-mode pins for free.
+  namespace :figma do
+    desc "Import a Figma variables export (DTCG .json) into token overrides " \
+         "(same AA-gated pipeline as poetry:design:import; POETRY_DESIGN_FORCE / POETRY_DESIGN_JSON honored)"
+    task :import, [:path] => :environment do |_task, args|
+      poetry_design_run_import(args[:path], task: "poetry:figma:import")
+    end
+  end
+
+  namespace :paper do
+    desc "Import a Paper 'Copy theme' export (CSS .css) into token overrides " \
+         "(same AA-gated pipeline as poetry:design:import; POETRY_DESIGN_FORCE / POETRY_DESIGN_JSON honored)"
+    task :import, [:path] => :environment do |_task, args|
+      poetry_design_run_import(args[:path], task: "poetry:paper:import")
+    end
+  end
+end
+
+# Shared importer for the DESIGN.md / Figma / Paper entry points: one file in,
+# one AA-gated design-overrides.css out. Poetry::Core::TokenImport.load
+# dispatches by extension (.md -> DesignMd.parse, .json -> Figma/DTCG variables,
+# .css -> Paper/CSS custom properties); everything downstream is the pipeline
+# poetry:design:import already ran, so nothing new decides what ships.
+def poetry_design_run_import(source, task:)
+  abort "#{task}: pass the file - bin/rails '#{task}[path]'" unless source
+  abort "#{task}: no such file #{source}" unless File.exist?(source)
+
+  doc = Poetry::Core::TokenImport.load(source)
+  plan = Poetry::Core::DesignMd::Import.new.plan(doc, force: ENV["POETRY_DESIGN_FORCE"] == "1")
+
+  written = nil
+  if plan.any_overrides?
+    written = Rails.root.join("app/assets/tailwind/poetry/design-overrides.css")
+    written.write(poetry_design_overrides_css(plan, File.basename(source)))
+    poetry_design_wire_overrides
+  end
+
+  if ENV["POETRY_DESIGN_JSON"] == "1"
+    puts JSON.pretty_generate(poetry_design_report_json(plan, written))
+  else
+    puts poetry_design_report(plan, written)
+  end
+end
+
+# The declared .cn-* overrides from the host manifest - tolerant
+# like every other manifest reader (missing file/key = none declared).
+def poetry_design_declared_overrides
+  path = Rails.root.join("config/poetry_components.yml")
+  # Hosts write `created:` as a bare YAML date - permit it, then normalize
+  # to ISO strings so everything downstream (scan, DESIGN.md) is string-typed.
+  config = path.exist? ? YAML.safe_load_file(path, permitted_classes: [Date]) : nil
+  return [] unless config.is_a?(Hash) && config["overrides"].is_a?(Array)
+
+  config["overrides"].map do |entry|
+    entry.is_a?(Hash) ? entry.merge("created" => entry["created"]&.to_s) : entry
+  end
+end
+
+# Host-owned stylesheet SOURCES: everything the app authors, excluding the
+# poetry-vendored set (which legitimately defines cn-*) and compiled output.
+def poetry_design_host_css_sources
+  root = Rails.root
+  sources = {}
+  root.glob("app/assets/**/*.css").each do |path|
+    relative = path.relative_path_from(root).to_s
+    next if relative.start_with?("app/assets/tailwind/poetry/", "app/assets/builds/")
+
+    sources[relative] = path.read
+  end
+  sources
+end
+
+# The installed theme, recovered from the slot bytes themselves (the
+# installer vendors the chosen fragment verbatim into the style-default.css
+# slot) - "custom" when the slot was hand-edited past recognition.
+def poetry_design_installed_theme
+  slot = Rails.root.join("app/assets/tailwind/poetry/style-default.css")
+  abort "poetry:design:export: no poetry install found (#{slot} missing) - run `bin/rails g poetry:install`" \
+    unless slot.exist?
+
+  bytes = slot.read
+  Poetry::Ui::Themes.names.find { |name| Poetry::Ui.root.join("themes/#{name}.css").read == bytes } || "custom"
+end
+
+# The vendored tokens.css may have been replaced wholesale (the shadcn
+# drop-in contract) - this export reads the gem's DTCG source, so say so
+# rather than silently exporting values the app no longer paints.
+def poetry_design_warn_on_token_drift
+  host_tokens = Rails.root.join("app/assets/tailwind/poetry/tokens.css")
+  return unless host_tokens.exist?
+  return if host_tokens.read == Poetry::Core.root.join("tokens/tokens.css").read
+
+  puts "poetry:design:export: NOTE - app/assets/tailwind/poetry/tokens.css diverges from the gem " \
+       "defaults (drop-in theme or hand edits); this export lists the gem's token values"
+end
+
+# Exports must tell the truth AFTER an import: fold the app's
+# design-overrides.css (our own generated format) back into the document
+# so the exported DESIGN.md carries the values the app actually paints.
+def poetry_design_apply_overrides(doc)
+  path = Rails.root.join("app/assets/tailwind/poetry/design-overrides.css")
+  return unless path.exist?
+
+  path.read.scan(/^(:root|\.dark)\s*\{([^}]*)\}/m).each do |selector, body|
+    mode = selector == ":root" ? "light" : "dark"
+    body.scan(/--([a-z0-9-]+):\s*([^;]+);/).each do |name, value|
+      if name == "radius"
+        doc["radius"] = value.strip if mode == "light"
+      elsif doc["colors"][mode].key?(name) && (color = Poetry::Core::Tokens::Color.parse(value.strip))
+        doc["colors"][mode][name] = color
+      end
+    end
+  end
+  puts "poetry:design:export: includes app/assets/tailwind/poetry/design-overrides.css values"
+end
+
+# The overrides stylesheet: :root carries the imported light values (+
+# radius); .dark carries imported dark values plus the poetry-default PINS
+# for light-overridden names the source left dark-silent (without them the
+# later :root block would also win in dark mode - equal specificity).
+def poetry_design_overrides_css(plan, source_name)
+  lines = ["/* Generated by `bin/rails poetry:design:import` from #{source_name} - do not edit.",
+           "   Loads AFTER the poetry theme imports so these blocks win the cascade;",
+           "   re-run the import to regenerate. */", ""]
+  lines << ":root {"
+  lines << "  --radius: #{plan.radius};" if plan.radius
+  plan.overrides["light"].sort.each { |name, color| lines << "  --#{name}: #{color.css};" }
+  lines << "}"
+
+  dark = plan.overrides["dark"].sort + plan.pins.sort
+  if dark.any?
+    lines << "" << ".dark {"
+    plan.overrides["dark"].sort.each { |name, color| lines << "  --#{name}: #{color.css};" }
+    if plan.pins.any?
+      lines << "  /* pinned to the poetry defaults (source had no dark palette) */"
+      plan.pins.sort.each { |name, color| lines << "  --#{name}: #{color.css};" }
+    end
+    lines << "}"
+  end
+  "#{lines.join("\n")}\n"
+end
+
+# Idempotently add the overrides import after the last top-level ./poetry/
+# import in the Tailwind entry (later = wins at equal specificity).
+def poetry_design_wire_overrides
+  entry = Rails.root.join("app/assets/tailwind/application.css")
+  import_line = %(@import "./poetry/design-overrides.css";)
+  unless entry.exist?
+    puts "poetry:design:import: NOTE - no #{entry}; add #{import_line} to your Tailwind entry yourself"
+    return
+  end
+
+  lines = entry.read.lines
+  return if lines.any? { |line| line.start_with?(import_line) }
+
+  last = lines.rindex { |line| line.match?(%r{\A@(?:import|source) "\./poetry/}) }
+  if last
+    lines.insert(last + 1, "#{import_line}\n")
+    entry.write(lines.join)
+    puts "poetry:design:import: wired #{import_line} into app/assets/tailwind/application.css"
+  else
+    puts "poetry:design:import: NOTE - no ./poetry/ imports found in #{entry}; " \
+         "add #{import_line} after them yourself"
+  end
+end
+
+def poetry_design_report(plan, written)
+  out = []
+  plan.overrides.each do |mode, colors|
+    next if colors.empty?
+
+    out << ("  applied (#{mode}): " + colors.sort.map { |name, color| "#{name} #{color.css}" }.join(", "))
+  end
+  out << "  radius: #{plan.radius}" if plan.radius
+  out << "  pinned (dark, poetry defaults): #{plan.pins.keys.sort.join(", ")}" if plan.pins.any?
+  if plan.contrast.any?
+    out << "  contrast (merged set, AA floor):"
+    plan.contrast.each { |result| out << "    #{result}" }
+  end
+  if plan.dropped.any?
+    out << "  dropped (never guessed):"
+    plan.dropped.each { |drop| out << "    #{drop.name}: #{drop.reason}" }
+  end
+  out << "  #{plan.typography_note}" if plan.typography_note
+  out << if written
+           "wrote #{written.relative_path_from(Rails.root)}"
+         else
+           "no overrides written (nothing importable survived the gate)"
+         end
+  out.join("\n")
+end
+
+def poetry_design_report_json(plan, written)
+  {
+    "applied" => plan.applied.map do |a|
+      { "role" => a.role, "from" => a.from, "mode" => a.mode, "css" => a.color.css }
+    end,
+    "pins" => plan.pins.transform_values(&:css),
+    "radius" => plan.radius,
+    "contrast" => plan.contrast.map do |r|
+      { "mode" => r.mode, "pair" => r.label, "ratio" => r.ratio.round(2), "pass" => r.pass,
+        "suggestion" => r.suggestion, "shipped_failing" => r.shipped }.compact
+    end,
+    "dropped" => plan.dropped.map do |d|
+      { "name" => d.name, "value" => d.value, "mode" => d.mode, "reason" => d.reason }.compact
+    end,
+    "typography_note" => plan.typography_note,
+    "written" => written&.relative_path_from(Rails.root)&.to_s
+  }.compact
+end