poetry-core 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b4189654db2722eff128793c1bd4ce725c06a60ec1b7ff8bf29d5af7aa4e9ef
-  data.tar.gz: fb0245f3b9abff92ad3f9bdd48d3da7a5fc421531e346d40e3e53eadaf304233
+  metadata.gz: 68f26084516bebd43571b5f687d9fb07cce952f00aba8e41448715b66b996fba
+  data.tar.gz: d1ec44154a85d4c2b4fda384432f2e73349973dfc21862aeddf06bde0d09303b
 SHA512:
-  metadata.gz: 3c79e20564e016e6b3b7b34378bb6222ca8708279864235bfd0c8d2a7b899f56e229a53cb284dbec9b9601e91922fc6f9799353fc8c7ddac8d1fa5d8fba6ae0b
-  data.tar.gz: 73b7dc73529fb2c1782a343ef7ddac9228591fba3b73c57163a0cfab4f6066e26da0d573447af273605e0bc98e1ff40d0fe0917a770c56e873ec22714b563182
+  metadata.gz: 65965b0865ade83c8b778c3ba773c6d1272bd4da2139e68cd8ab5b798903d12e3224d75df0f77f849cd72403e782d5da87ba470a4597d8654c7ab72a6bdc90ea
+  data.tar.gz: e3b822469b4ed1253193dd331b9b43b7923aa5626265ec9f6d1cdc6c4112a7306eb93e37f3a7670b9985da406ef804b5eb4b5174b03263004eced90e306e03c3

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.1.2] - 2026-09-13
+
+### Added
+
+- `helper :name` on a component: an application's (or an engine's) own component written on the DSL names its view helper. The engine defines that helper on Action View at boot and on every reload, and `Poetry::Core::HostComponents` discovers the app's components by convention (under `app/`, outside the `poetry/` namespace, published), builds their registry live, and reads their declared helpers boot-free from source. The registry entry carries `helper`; `poetry check` lints a declared helper under its own name (options, variants, arity, stable identity); llms.txt and the generated skill take an app registry and render an App components section and a `references/app.md`.
+- The runtime values tier. A component built with an off-list style value or a missing required option raises at construction in development and test, naming the allowed values with a did-you-mean, and logs in production while rendering as before (the passthrough guard's posture, at the same seam, so it holds whatever a component does in `before_render`). Only the DSL's own validations are enforced; a component's custom validators keep their own policy. An omitted style is nil, not an off-list value (`allow_nil` on the inclusion validations). The check is a direct lookup over the declared vocabulary (`style` variants, `required`, and `validates ... inclusion: { in: [...] }` on a declared attribute), not an ActiveModel validation pass.
+- Render cost. Measured on 200 Buttons in one view context, a Button went from 0.122 ms to 0.089 ms: the values tier is a direct lookup instead of a validation pass, construction converts the caller's attributes once, and the Style resolver memoises its dictionary walk per variant tuple (bounded by the variant space, cleared when the dictionary changes). The remaining time is ViewComponent's own render (about forty percent) and attribute assignment (a quarter).
+- The class-name merger follows the kit's CSS mode (`Poetry::Core::CSS::Modes.merger_for`): a `:bem` kit merges with a `BemMerger`, a `:tailwind` kit with a `TailwindMerger`. The global `classname_merger` is honoured whenever it is of the right kind, so a customised Tailwind merger still reaches poetry-ui and a host's BEM merger still reaches its BEM kit; a mismatch falls back to the stock merger of the mode. A host that set the global mode to `:bem` without a merger now gets the BEM merger on its kit, the pairing the guide always asked for. Attribute objects keep their assigned merger across copies.
+- `css_mode` is decided per kit. A component class declares it (`css_mode :bem`, inherited), or a kit pins its namespace (`Poetry::Core::CSS::Modes.pin("Acme::Ui", :bem)`); the global `Config.current.css_mode` is the default for kits that declare nothing, and a `css_mode:` keyword on a `css` call still wins over all of them. poetry-ui and poetry-charts pin `:tailwind`, so a host's global never reaches them and a BEM kit on the DSL renders beside them in one app. Before, the global was the only switch and setting it to `:bem` silently stripped poetry-ui's styling.
+- `OverrideScan` takes `owned:`, the theme-owned `cn-*` names; only a rule against one of those is an override. A host's own `cn-*` classes (a kit's dictionary, a page helper) are never findings. Nil keeps the old meaning (every `cn-*` name).
+- The host controllers manifest. `Poetry::Core::Stimulus::HostManifest` reads `app/javascript/controllers` (static targets, values in both forms, classes, `static events`, the class body's own methods) and writes `config/controllers_manifest.json`, the file a gem commits; the engine registers every loaded engine's and the app's manifest by convention before components load. A host controller then validates like poetry's: `use_stimulus` by Symbol at class load, template wiring in `poetry check` (the value-attribute rule now covers any registered controller), and its API in the registry's controllers section. The reader masks comments and string, template and regex literals before it reads structure, so a comment inside `static values`, a brace in a string, a one-line method body or an arrow-function class field all read correctly; it scrubs stray bytes and a BOM. An entry is complete or absent: a parent that is another host controller (relative import) or a poetry controller (`@poetry/controllers`, file or barrel import; charts and agent by their packages) merges child-first; an unresolvable parent, a computed static, a getter or a spread yields no entry and a named skip. A hand-written entry for a skipped identifier survives regeneration and never reads as stale (the gate compares only the controllers the reader read). Events are validated only from a literal `static events`; a controller that only calls `dispatch()` keeps them unknown, never empty. A Symbol declaration resolves to a gem's namespaced controller before a host controller of the same bare name, so a host `tabs_controller.js` never hijacks `controller :tabs`; the unknown-Symbol message names `bin/rails poetry:stimulus:manifest`. `Manifest.register_roots`, `Manifest.forget`; `Registry.gem_roots(registry: false)` lists every bundled root for the manifest walk.
+- Registry roots by convention. `Poetry::Core::Registry.roots` (booted: every loaded engine whose root carries a published registry, then the app when it committed one), `.gem_roots` (boot-free, from the bundle, plus an app root), and `.merged` (one view over several roots, block templates resolved to absolute paths). A registry can mark itself `internal: true` and consumers skip it; poetry-core's own is now marked, since its building blocks have no helpers. `HostComponents.committed_state` reports the app's committed registry as missing, fresh, or stale against the live build.
+- `Poetry::Core::CSS::TokenCollisions`: scans a host app's stylesheets for declarations of Poetry's token names (`--primary`, `--accent`, `--radius`, ...) and Tailwind theme keys (`--color-*`, `--radius-*`), and reports each with its location and what the role paints in Poetry's components. `poetry:install` and `poetry:check` run it.
+
+### Changed
+
+- A namespace pin follows the dictionary: a component's mode is its own declaration, else the pin of the root-most pinned ancestor (`Modes.inherited_for`), else the global, so a host subclass of a poetry-ui component stays Tailwind inside a BEM-pinned namespace while a host component written on the DSL takes the pin.
+- A dictionary merges by its own mode at every level: the resolver takes its class merger from the Style's sidecar component (its declaration, its kit's pin, or the global), so a host's global BEM merger never reaches a Tailwind kit's element-level joins, not only its root. A style redeclared without variants is open, whatever the parent listed: an inherited inclusion validator no longer narrows it. The "Style class not found" debug line is logged once per class.
+
+- `poetry check` validates every descriptor of a `data-action`, not only the last (a bogus first descriptor was invisible); a `data-<controller>-<name>-value` or `-target` attribute resolves to the controller the element declares when several registered identifiers fit (`foo` and `foo-bar`), a plain `data-foo-value` is the host's own attribute, a host controller's targets validate like poetry's, and an attribute whose value carries ERB skips the wiring rules instead of type-checking its fragments. A declared app helper matches bare calls only (`u.badge` is somebody's method); the stable-identity pass agrees. A file the runner cannot read or decode is one `unreadable` warning naming it, never the end of the sweep. `Check.mail_template?(path, root:)` judges the path inside the app root (an app checked out under a folder called `acme_mailer` keeps its pages) and knows Devise's `devise/mailer/`.
+
+- Every registry names every helper. A gem entry carries its `poetry_` convention name and an app entry the name it declared with `helper :name`; `Registry.helper_for(path, entry)` is the one resolver every surface reads (llms.txt, the check, the skill, the MCP server), so an app component that declared no helper is listed by class and no surface invents a `poetry_` name for it. The committed gem registries regenerate with the added key and nothing else.
+- Host helpers are checked before any is defined: a clash (a name Action View, poetry-ui, or the app's own `ApplicationController` helpers already carry, private methods included) or two components declaring one name raises naming both sides, leaves the module untouched, and the next reload after the fix starts clean. `Registry.read_file` is the one validated reader of a committed registry file; an empty, malformed, or wrong-shaped file reads as no registry (`Registry.invalid_at?`) instead of raising in whichever surface opened it first. The boot-free `HostComponents.declared_helpers` parses component sources with Prism, so a mention in a string, heredoc, or comment is not a declaration and `helper(:x)`, `helper "x"`, and `self.helper :x` are. `poetry:registry` leaves an engine's own components to that engine's registry.
+
+- `poetry check` leaves a mailer template's colors alone: under a `*_mailer/` directory or in the mailer layout, an inline hex or a color literal in a utility class is the only paint an email client honours (no stylesheet, no tokens), so the raw-color rule stays quiet there while every other rule runs as on a page. `Check.lint` takes `mail:` for a source string; the runner derives it from the path (`Check.mail_template?`).
+
+- The generated Tailwind theme mapping is `@theme inline default`. A host `@theme` value for the same key (its own `--color-primary`, a `--radius-sm` it set before Poetry arrived) wins whether it is declared before or after the mapping; Poetry's value still applies wherever the host set nothing. Before, the mapping replaced the host's keys wholesale, so every `rounded-sm` in an existing app changed size.
+
 ## [0.1.1] - 2026-09-08
 
 ### Added

data/README.md

@@ -20,10 +20,6 @@ After checking out the repo, run `bin/setup` to install dependencies, then `bund
 
 Releases publish to [RubyGems.org](https://rubygems.org) via GitHub Actions OIDC **trusted publishing** (no API keys). Run `bundle exec rake "version:bump[X.Y.Z]"` (sets `Poetry::Core::VERSION` and package.json together; `rake version:verify` in the default chain fails on drift), commit, then push a `vX.Y.Z` tag — the `Release` workflow checks the tag against the version and publishes the gem.
 
-## Lineage
-
-poetry-core evolves the framework layer of `view_component_plus` (the `Plus` gem) — itself a synthesis of view_component-contrib and fox_tail.
-
 ## License
 
 Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/components/poetry/core/component.rb

@@ -54,6 +54,14 @@ module Poetry
       # a subclass of an internal component stays internal.
       class_attribute :internal_component, default: false, instance_predicate: false
 
+      # The declared vocabulary the runtime values tier checks:
+      # name => { variants: [...] or nil, required: true/false }, recorded
+      # by `style` and `option` at declaration (copy-on-write per class, so
+      # a subclass's declarations never leak up). A direct lookup, not an
+      # ActiveModel validation pass - measured at nine percent of a
+      # Button's render when it ran through `valid?`.
+      class_attribute :declared_values, instance_accessor: false, default: {}.freeze
+
       class << self
         # Marks this class (and its descendants) as an implementation
         # detail - full machinery, no registry entry.
@@ -66,6 +74,86 @@ module Poetry
         def internal_component!
           self.internal_component = true
         end
+
+        # The vocabulary the runtime values tier checks, computed once per
+        # class at first construction (the class body is complete by then):
+        # the recorded `style`/`option` declarations plus every inclusion
+        # validator with an Array (`validates :side, inclusion: { in: SIDES }`
+        # is how options declare a closed vocabulary). Method validators are
+        # not vocabulary and stay the component's own (Icon's unknown-name
+        # policy).
+        #
+        # @return [Hash{Symbol => Hash}]
+        # @api private
+        def runtime_vocabulary
+          @runtime_vocabulary ||= begin
+            vocabulary = declared_values.dup
+            names = attribute_names.map(&:to_sym)
+            validators.each do |validator|
+              next unless validator.is_a?(ActiveModel::Validations::InclusionValidator)
+              next unless (allowed = validator.options[:in]).is_a?(Array)
+
+              validator.attributes.each do |attribute|
+                attribute = attribute.to_sym
+                next unless names.include?(attribute)
+
+                spec = vocabulary[attribute] || { variants: nil, required: false }
+                # A style declared open (no variants) stays open: an inherited
+                # inclusion validator from a parent's closed declaration never
+                # narrows it again.
+                next if spec[:open]
+
+                vocabulary[attribute] = spec.merge(variants: allowed).freeze unless spec[:variants]
+              end
+            end
+            vocabulary.freeze
+          end
+        end
+
+        # Records a declared attribute's vocabulary for the runtime values
+        # tier ({#guard_declared_values}).
+        #
+        # @param name [Symbol]
+        # @param variants [Array, nil] the closed vocabulary, nil for open values
+        # @param required [Boolean]
+        # @return [void]
+        # @api private
+        def record_declared_value(name, variants:, required:, open: false)
+          spec = { variants: variants, required: required, open: open }.freeze
+          self.declared_values = declared_values.merge(name.to_sym => spec).freeze
+        end
+
+        # Names the view helper that renders this component - for a
+        # component the host application (or an engine) defines on the
+        # DSL. The poetry-core engine defines the method on Action View at
+        # boot and on every reload, and the app's registry carries the name
+        # so `poetry check`, llms.txt and the generated skill know the
+        # helper. Own-class only: a subclass declares its own or has none.
+        # The gems' components do not declare one; their helpers follow the
+        # `poetry_<name>` convention.
+        #
+        # @example
+        #   class Demo::Badge::Component < Poetry::Core::Component
+        #     helper :demo_badge
+        #   end
+        #   # <%= demo_badge(tone: :loud) { "New" } %>
+        # @param name [Symbol, String] a Ruby method name
+        # @return [void]
+        # @raise [ArgumentError] when the name is not a plain method name
+        def helper(name)
+          name = name.to_s
+          unless name.match?(/\A[a-z_][a-z0-9_]*\z/)
+            raise ArgumentError, "helper name #{name.inspect} must be a plain method name (a-z, 0-9, _)"
+          end
+
+          @helper_name = name
+        end
+
+        # The declared helper name, or nil (the gems' components; a
+        # subclass that declares none).
+        #
+        # @return [String, nil]
+        attr_reader :helper_name
       end
 
       class << self
@@ -279,10 +367,14 @@ module Poetry
         end
 
         @attributes = self.class._default_attributes.deep_dup
-        html_attrs = guard_passthrough(attributes.with_indifferent_access.except(*attribute_names))
-        @html_attributes = Poetry::Core::HTML::Attributes.new(html_attrs)
-
-        assign_attributes attributes.with_indifferent_access.slice(*attribute_names)
+        given = attributes.with_indifferent_access
+        names = attribute_names
+        @html_attributes = Poetry::Core::HTML::Attributes.new(guard_passthrough(given.except(*names)))
+        # The root merges classes with the kit's merger (its CSS mode's).
+        @html_attributes.classname_merger = classname_merger
+
+        assign_attributes given.slice(*names)
+        guard_declared_values
       end
 
       # The passthrough contract, enforced at the seam. A keyword that is not
@@ -343,12 +435,55 @@ module Poetry
         self.class.name ? self.class.component_title : "this component"
       end
 
+      # The runtime values tier, beside the passthrough guard: the declared
+      # vocabulary (`style ... variants:`, `required:`) is checked at
+      # construction, where every component - gem or app, whatever it does
+      # in before_render - passes. Off-list values raise in development and
+      # test with the allowed values and a did-you-mean; in production they
+      # log and render as before. `poetry check` catches the same mistakes
+      # in templates statically; this tier catches the value that arrives
+      # from data. A direct lookup over {.declared_values}; a component's
+      # custom validators keep their own policy.
+      def guard_declared_values
+        problems = nil
+        self.class.runtime_vocabulary.each do |name, spec|
+          value = public_send(name)
+          if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+            (problems ||= []) << "#{passthrough_owner} requires #{name}:" if spec[:required]
+          elsif spec[:variants] && !spec[:variants].include?(value)
+            (problems ||= []) << off_list_problem(name, value, spec[:variants])
+          end
+        end
+        return unless problems
+
+        message = problems.join("; ")
+        raise ArgumentError, message if strict_passthrough?
+
+        Rails.logger&.warn("poetry: #{message}") if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+
+      # The message a developer reads for an off-list value: the declared
+      # vocabulary and a did-you-mean.
+      def off_list_problem(name, value, allowed)
+        "#{passthrough_owner} #{name}: #{value.inspect} is not one of " \
+          "#{allowed.map(&:inspect).join(", ")}#{variant_suggestion(value, allowed)}"
+      end
+
+      def variant_suggestion(value, allowed)
+        return "" if allowed.empty? || value.nil?
+
+        require "did_you_mean"
+        suggestion = DidYouMean::SpellChecker.new(dictionary: allowed.map(&:to_s)).correct(value.to_s).first
+        suggestion ? " (did you mean #{suggestion.to_sym.inspect}?)" : ""
+      end
+
       # Raise (development, test) or log (everything else).
       def strict_passthrough?
         defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
       end
 
-      private :guard_passthrough, :option_suggestion, :passthrough_owner, :strict_passthrough?
+      private :guard_passthrough, :option_suggestion, :passthrough_owner, :strict_passthrough?,
+              :guard_declared_values, :off_list_problem, :variant_suggestion
 
       # Returns all component attributes, ensuring proc defaults are evaluated.
       #
@@ -421,15 +556,24 @@ module Poetry
 
       # Merges multiple class name values into a single string.
       #
-      # Uses the configured classname merger (typically Tailwind Merge) to
-      # intelligently combine CSS class names, handling conflicts and duplicates.
+      # Uses the kit's classname merger (Tailwind Merge in :tailwind mode,
+      # the BEM merger in :bem mode - {Poetry::Core::CSS::Modes.merger_for})
+      # to combine CSS class names, handling conflicts and duplicates.
       #
       # @param classnames [Array<String, nil>] class names to merge
       # @return [String] the merged class names
       # @example
       #   classnames("text-red-500", "text-blue-500") # => "text-blue-500"
       def classnames(*classnames)
-        self.class.config.classname_merger.merge(*classnames)
+        classname_merger.merge(*classnames)
+      end
+
+      # The class-name merger this component merges with: the one that
+      # matches its CSS mode ({Poetry::Core::CSS::Modes.merger_for}).
+      #
+      # @return [#merge]
+      def classname_merger
+        Poetry::Core::CSS::Modes.merger_for(css_mode)
       end
 
       # HTML-safe JSON for embedding in a `<script type="application/json">`

data/app/components/poetry/core/concerns/options.rb

@@ -195,6 +195,7 @@ module Poetry
           # @param _type [Symbol] the attribute type (unused; kept for signature parity)
           # @param required [Boolean] whether the attribute is required
           def add_option_validations(name, _type, required)
+            record_declared_value(name, variants: nil, required: required)
             # Type validation is automatic via ActiveModel::Type
             validates name, presence: true if required
           end

data/app/components/poetry/core/concerns/styles.rb

@@ -53,6 +53,8 @@ module Poetry
         STYLE_CLASS_SUFFIX = "::Style"
 
         included do
+          # The kit-level mode declaration (`css_mode :bem`), inherited.
+          class_attribute :declared_css_mode, instance_accessor: false, default: nil
           class_attribute :registered_styles,
                           instance_writer: true,
                           instance_predicate: false,
@@ -60,6 +62,28 @@ module Poetry
         end
 
         class_methods do
+          # The CSS mode this component renders in, declared per kit
+          # (inherited by subclasses): `css_mode :bem` on a kit's base
+          # class, and every component in it emits the BEM token IR. With
+          # no argument, the resolved mode: the declaration, else the mode
+          # pinned for the namespace ({Poetry::Core::CSS::Modes} - poetry-ui
+          # pins `:tailwind`), else the global
+          # `Poetry::Core::Config.current.css_mode`. A `css_mode:` keyword
+          # on a `css` call still wins over all of them.
+          #
+          # @example A kit that brings its own CSS
+          #   class Acme::Ui::Base < Poetry::Core::Component
+          #     css_mode :bem
+          #   end
+          # @param mode [Symbol, nil] :tailwind or :bem to declare; nil to read
+          # @return [Symbol] the declared or resolved mode
+          # @raise [Poetry::Core::Error] for an unknown mode
+          def css_mode(mode = nil)
+            return self.declared_css_mode = Poetry::Core::CSS::Modes.validate!(mode) unless mode.nil?
+
+            declared_css_mode || Poetry::Core::CSS::Modes.inherited_for(self) || Poetry::Core::Config.current.css_mode
+          end
+
           # Defines a style attribute for the component.
           #
           # @param name [Symbol, String] the name of the style attribute
@@ -145,7 +169,12 @@ module Poetry
             style_class_name = component_module + STYLE_CLASS_SUFFIX
             style_class_name.constantize
           rescue NameError => e
-            log_style_class_not_found(style_class_name, e) if defined?(Rails)
+            # Once per class: a component with no dictionary (Icon) is a
+            # design, not a line per render in the development log.
+            unless @style_class_miss_logged
+              @style_class_miss_logged = true
+              log_style_class_not_found(style_class_name, e) if defined?(Rails)
+            end
             nil
           end
 
@@ -177,10 +206,14 @@ module Poetry
           # @param variants [Object] the allowed variants
           # @param required [Boolean] whether the attribute is required
           def add_style_validations(name, type, variants, required)
+            record_declared_value(name, variants: type == :boolean ? nil : variants, required: required,
+                                        open: type != :boolean && variants.nil?)
+            # nil is an omitted value, not an off-list one; `required` adds
+            # presence for the styles that may not be omitted.
             if type == :boolean
-              validates name, inclusion: { in: [true, false] }
+              validates name, inclusion: { in: [true, false] }, allow_nil: true
             elsif variants
-              validates name, inclusion: { in: variants }
+              validates name, inclusion: { in: variants }, allow_nil: true
             end
             validates name, presence: true if required
           end
@@ -274,7 +307,7 @@ module Poetry
         # @raise [Poetry::Core::Error] for a css_mode other than :tailwind
         #   or :bem
         def css(element = nil, **options, &)
-          mode = options.delete(:css_mode) || Poetry::Core::Config.current.css_mode
+          mode = options.delete(:css_mode) || css_mode
 
           case mode
           when :tailwind
@@ -288,10 +321,18 @@ module Poetry
             extra = options.delete(:class)
             [bem(element, **options), extra].compact.join(" ")
           else
-            raise Poetry::Core::Error, "unknown css_mode #{mode.inspect} (expected :tailwind or :bem)"
+            Poetry::Core::CSS::Modes.validate!(mode)
           end
         end
 
+        # The CSS mode this instance renders in (the class's resolved mode;
+        # see the class-level `css_mode`).
+        #
+        # @return [Symbol] :tailwind or :bem
+        def css_mode
+          self.class.css_mode
+        end
+
         # The component's BEM block name - the stable, framework-agnostic
         # class contract of the token IR ("poetry/core/dot" -> "poetry-core-dot").
         #

data/app/components/poetry/core/style.rb

@@ -27,7 +27,38 @@ module Poetry
         #
         # @return [CSS::Resolver]
         def resolver
-          @resolver ||= superclass.respond_to?(:resolver) ? superclass.resolver.dup : CSS::Resolver.new
+          @resolver ||= begin
+            dictionary = superclass.respond_to?(:resolver) ? superclass.resolver.dup : CSS::Resolver.new
+            dictionary.owner = self
+            dictionary
+          end
+        end
+
+        # The class merger for this dictionary's mode: the sidecar
+        # component's resolved `css_mode` (its own declaration, its kit's
+        # pin, or the global), else this class's own namespace pin, else the
+        # global mode - so `Acme::Pill::Style` under a `:bem` pin merges like
+        # BEM while poetry-ui's dictionaries merge like Tailwind whatever the
+        # host set globally.
+        #
+        # @return [Object] a class-name merger
+        def merger
+          component = sidecar_component
+          mode = if component.respond_to?(:css_mode)
+                   component.css_mode
+                 else
+                   CSS::Modes.inherited_for(self) || Poetry::Core::Config.current.css_mode
+                 end
+          CSS::Modes.merger_for(mode)
+        end
+
+        # The `X::Component` beside this `X::Style`, when it exists.
+        def sidecar_component
+          return nil unless name&.end_with?("::Style")
+
+          Object.const_get("#{name.delete_suffix("::Style")}::Component")
+        rescue NameError
+          nil
         end
 
         # -- The dictionary DSL (delegates to the resolver) --------------------

data/config/component_registry.yml

@@ -14,7 +14,9 @@ components:
       description: The element to render ('div', 'section', 'span', ...); void elements
         (br, hr, img, ...) self-close and take no content block.
     slots: []
+    helper: poetry_box
     identity: false
     parts:
     - name: box
       description: The rendered element itself - the whole component is one part
+internal: true

data/lib/poetry/core/check/stable_identity.rb

@@ -68,6 +68,19 @@ module Poetry
 
         private
 
+        # The gem convention plus every helper the catalog knows by a name
+        # of its own (an app component's declared helper), so the
+        # heuristics cover app components too.
+        def helper_pattern
+          @helper_pattern ||= begin
+            declared = @catalog.helper_names.reject { |name| name.start_with?("poetry_") }
+            # A bare call: not after a dot or a colon (`u.badge`, `Foo::badge`).
+            Regexp.union(/(?<![\w.:])(poetry_[a-z0-9_]+)\b/, *declared.map do |name|
+              /(?<![\w.:])(#{Regexp.escape(name)})\b/
+            end)
+          end
+        end
+
         def frame_for(code)
           return :cache if code.match?(CACHE_OPENER)
           return :loop if code.match?(LOOP_OPENER)
@@ -76,7 +89,7 @@ module Poetry
         end
 
         def flag_helpers(code, line, stack, findings)
-          code.scan(/\b(poetry_[a-z0-9_]+)\b/) do |(helper)|
+          code.scan(helper_pattern) do |(helper)|
             next unless @catalog.helper?(helper)
             next if @catalog.identity_free?(helper)
             next if code.match?(IDENTITY_ARG)