poetry-core 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbcb8f5566d4740ebb19e9fc4e4ffed10332cff25bde4e807cf844ddee70770a
-  data.tar.gz: 82e4cbb3c6f3bb340ecb20fb3e0406e83b8b2008364467dc83c7deddda93331e
+  metadata.gz: 1831a4d45731d76d83cfdbb9a65b20433a32bf7c57a15297f7838e04d0a55c21
+  data.tar.gz: a65f3175560897a70c6f2f8e29d3373bf3c5ef02f7baae20c35fcc3ddb4b3b6f
 SHA512:
-  metadata.gz: 53de8890c3deeb5f377f4c9d825f9599c499ef4bc66becdfd3266864166a6119024486b32c385fd02ef452af27ec9eebac63c8ab54570bad6a0a758707164637
-  data.tar.gz: d761c54985f8e367c72b5b9c99d609303b787d8bf13c9857bffee008e2b633a3fd778f719e3a07e70c179c11b7ad9430ba75693c511a4c3f33eb2a7794c325a2
+  metadata.gz: 2f77187b648438d1e648956744425e82efbeb28f4b8efe0aa19b04ec647db0420bc6320405f01ccb938d6594856974c26702a2572c972a5a71134c16afa67e85
+  data.tar.gz: 59f36c4032dc99a6643486ae88f1cacfe71cf7f1ab94f046ee22654276feba9baa4a95244bfa8a011edd2731d269a8dee2408b458e00d00c52367d38076ee647

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.1.9] - 2026-09-30
+
+### Added
+
+- `element_tag(name, ..., **attributes)`, on every component and in every view: the helper a template builds its elements through, and where a component's template spends what `root_attributes` and `element_attributes` build. It takes what `content_tag` takes and renders the same bytes, and it renders a void element the way `tag.input` does. A host that compiles its templates with Herb's slots has Action View's own tag helpers resolved into markup ahead of the render, and a splat or a tag name held in a variable does not survive that: the element comes out without its attributes, or the template stops compiling. A helper Herb does not know stays a call. Components written on the DSL in a host should build their elements the same way.
+- `poetry check` holds a component's template (an ERB file under `app/components/`) to the element rule, `element-tag`, as a warning: a tag helper handed a splat or a variable for its attributes, `content_tag` given a tag name that is not a literal, and `tag.attributes` handed a splat each name the `element_tag` call to write instead. A view is left alone: handing a tag helper a splat is valid Rails, and whether the host compiles with slots is not something a lint of the source can know.
+- `poetry check` compiles a component's HTML template under Herb, in the posture `bin/rails herb:check` holds an app's views to: the security validator, with the compiled Ruby checked for syntax. Rails renders HTML templates through Herb under its 8.2 defaults and its task walks the view paths, so a template under `app/components/` is outside its reach. Rails checks views, Poetry checks components. A template Herb refuses is a `herb-compile` finding that carries the engine's reason and its line: an error when the app renders through Herb, a warning until then. The runner compiles when it is handed the tier (`Check::Runner.new(catalog, compile:)`), and `Poetry::Core::TemplateCompile` takes `posture: :rails` for it beside the strict posture the gems' own gate runs.
+- `poetry check` holds a component class to the renderable rule, `renderable-reader`: an `option`, a `style` or a slot named `format` defines the reader Rails asks a component for the format of its template, and it answers with the declared value, so a render through the renderer raises `Invalid formats`. From Rails 8.2 every render in a view goes through the renderer, so the host's check reports it as an error there and as a warning before. A class that defines `format` itself, with `def` or `define_method`, is left alone: it keeps the keyword for its callers and reads the value under another name, which is what NumberField does.
+- `Poetry::Core::SlotMarkers.strip(html)` takes off what a slot compile writes around a template's own markup: the region, slot and branch comments, the `data-herb-slot` attribute and the branches parked in a `<template>`. What is left is the markup the template wrote, which is what a test in a host that compiles with slots means to compare.
+
+### Changed
+
+- The helpers of an app's own components (`helper :name`) are defined before the first view renders, not while the application is still initializing. The engine used to load every `app/components` directory from `to_prepare`, and a component is a view, so Action View loaded before initialization completed: Rails logs that in a boot that does not eager load, and raises on it when `config.action_on_early_load_hook` is `:raise`. A host that eager loads now syncs once its boot is done, with the classes already loaded; every other host syncs on its first view context, at render time; a reload syncs as before. `Poetry::Core::HostHelpers.sync_now!` is the sync, `ready?` says whether the first one has happened, and `HostHelpers::FirstView` is what Action View's base class gets for it.
+- The template compile gate (`rake herb:compile`, `Poetry::Core::TemplateCompile`) runs on Herb 0.11. It requires the engine itself, since `require "herb"` no longer loads it. It hands the engine every validator Herb ships, each one fatal, since from 0.11 the engine validates nothing it is not handed, and has the compiled Ruby checked for syntax. It lists parse and compile errors, which Herb now raises as syntax errors, where they used to pass the rescue and abort the run. A Herb older than 0.11.0 raises a setup error that names the version found.
+
+## [0.1.8] - 2026-09-22
+
+### Added
+
+- `ActiveModel::Type::HtmlSafeString`, the type behind every `option :name, :string` declaration: an html-safe value (a hint built with `link_to`, a translated `_html` key) stays html-safe where ActiveModel's String type copied it into a plain String, so a Field's `hint:` or `error:` renders the markup it was given; a plain String still escapes at render. The type is substituted inside the option DSL only, never registered, and reports `:string`, so the registry reads every declaration unchanged.
+
+### Changed
+
+- A content block that returns a scalar (a number, a symbol, a boolean) while writing nothing to the buffer captures as nothing, so `poetry_badge { count }` rendered an empty badge without a word. A component that declares `requires_content` now raises in development and test naming the value and the fix (call `to_s` on it, or write it with `<%= %>`) and logs in production; every other component logs. A block that wrote to the buffer, returned a String or nil, or returned a collection (an empty loop's `each`) is untouched.
+- `poetry check`'s stable-identity rules skip a pathless helper whose registry `helpers` entry declares `identity: false` (a table part helper stamps no poetry-minted id, so `key:` had nothing to stabilize and the warning was noise), and read a double-splat of an id-bearing hash (`**field.control_attributes`, `**attrs`) as identity: the id arrives through the splat.
+
 ## [0.1.7] - 2026-09-20
 
 ### Changed

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

@@ -39,6 +39,7 @@ module Poetry
       include ActiveModel::AttributeAssignment
       include ActiveModel::Validations
       include Poetry::Core::Contrib::WrappedHelper
+      include Poetry::Core::TagHelper
       include Poetry::Core::Concerns::Styles
       include Poetry::Core::Concerns::Options
       include Poetry::Core::Concerns::Stimulus
@@ -296,12 +297,12 @@ module Poetry
       #     super("role" => "status", "data-variant" => variant)
       #   end
       # @example The template
-      #   <%= tag.div(**root_attributes) do %>
+      #   <%= element_tag(:div, **root_attributes) do %>
       #
       # @param extra [Hash] the component's own root attributes; a
       #   `"data-slot"` here replaces the default
       # @return [Hash] the root's attributes, flat (`data-x`, `aria-x`,
-      #   booleans as the attribute name), for `tag` and `content_tag`
+      #   booleans as the attribute name), for {Poetry::Core::TagHelper#element_tag}
       def root_attributes(extra = {})
         own = { "data-slot" => root_slot }.merge(extra).merge(component_data_attributes)
         wired = self.class.stimulus_elements.key?(:root) ? :root : nil
@@ -335,7 +336,7 @@ module Poetry
       #     attrs["hidden"] = true unless open
       #     element_attributes(:content, attrs)
       #   end
-      #   # <%= tag.div(**content_attributes) do %>
+      #   # <%= element_tag(:div, **content_attributes) do %>
       #
       # @param part [Symbol, String, nil] the part; nil (or a Hash in its
       #   place) for markup with no part of its own
@@ -343,7 +344,7 @@ module Poetry
       # @param stimulus [Symbol, String, false, nil] the `use_stimulus`
       #   element whose wiring joins the markup: nil takes the part's own when
       #   one is declared, false takes none
-      # @return [Hash] the element's attributes, flat, for `tag` and `content_tag`
+      # @return [Hash] the element's attributes, flat, for {Poetry::Core::TagHelper#element_tag}
       def element_attributes(part = nil, attrs = {}, stimulus: nil)
         if part.is_a?(Hash)
           attrs = part
@@ -382,7 +383,63 @@ module Poetry
                              "(#{self.class.required_content})"
       end
 
+      # ViewComponent's render_in, with the content block wrapped once so
+      # #content can read what the block RETURNED - capture keeps only what
+      # the block wrote to the buffer, and a scalar return vanishes there.
+      #
+      # @param view_context [ActionView::Base] the rendering view
+      # @return [ActiveSupport::SafeBuffer] the rendered component
+      def render_in(view_context, **)
+        @content_guarded = false
+        remove_instance_variable(:@content_return) if defined?(@content_return)
+        return super unless block_given?
+
+        recorded = proc { |*args| @content_return = yield(*args) }
+        super(view_context, **, &recorded)
+      end
+
+      # The captured content block, guarded once per render: a block that
+      # returned a scalar (a number, a symbol, a boolean) while writing
+      # nothing to the buffer captures as nothing at all - `poetry_badge {
+      # count }` renders an empty badge - so a requires_content component
+      # raises in development and test naming the value and the fix, and
+      # logs everywhere else; a component without the declaration logs. A
+      # block that wrote to the buffer, returned a String, returned nil,
+      # returned a collection (an empty loop's each) or composed slots
+      # (its last call a with_* setter, which returns the slot or the
+      # component) is fine.
+      #
+      # @return [ActiveSupport::SafeBuffer, nil] the captured content
+      def content
+        captured = super
+        guard_content_return(captured) unless @content_guarded
+        captured
+      end
+
+      # The content-return guard behind #content.
+      #
+      # @param captured [ActiveSupport::SafeBuffer, nil] what capture kept
+      # @return [void]
+      # @raise [ArgumentError] a scalar return on a requires_content
+      #   component, in development and test
+      def guard_content_return(captured)
+        @content_guarded = true
+        return unless defined?(@content_return)
+
+        value = @content_return
+        return if value.nil? || value.is_a?(::String) || value.respond_to?(:each) || captured.present?
+        return if value.is_a?(ViewComponent::Base) || value.is_a?(ViewComponent::Slot)
+
+        message = "#{passthrough_owner} content block returned #{value.inspect.truncate(60)} (#{value.class}), " \
+                  "which captures as nothing - return a String (call to_s on it) or write it with <%= %>"
+        raise ArgumentError, message if strict_passthrough? && self.class.required_content
+
+        Rails.logger&.warn("poetry: #{message}") if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+      private :guard_content_return
+
       # Indicates whether this component instance is persisted.
+
       # Always returns false as components are not persisted entities.
       #
       # @return [Boolean] always returns false

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

@@ -90,8 +90,9 @@ module Poetry
             required, default_value = extract_declared_defaults(options)
             register_option_format(name, options.delete(:format))
 
-            attribute(name, type, **options)
+            attribute(name, option_cast_type(type), **options)
             add_option_validations(name, type, required)
+
             setup_declared_tracking(:option, name, default_value)
             define_type_getter(name, type)
           end
@@ -200,6 +201,18 @@ module Poetry
             validates name, presence: true if required
           end
 
+          # The ActiveModel type an option declaration casts with. A :string
+          # option casts with ActiveModel::Type::HtmlSafeString, which keeps
+          # an html-safe value (a link, a translated `_html` key) html-safe
+          # where the String type copied it into a plain String; every other
+          # type is looked up by name as ActiveModel does.
+          #
+          # @param type [Symbol] the declared type
+          # @return [Symbol, ActiveModel::Type::Value] what `attribute` receives
+          def option_cast_type(type)
+            type == :string ? ActiveModel::Type::HtmlSafeString.new : type
+          end
+
           # Defines a singleton method to access the type for this attribute.
           #
           # @param name [Symbol] the attribute name

data/lib/active_model/type/html_safe_string.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module ActiveModel
+  module Type
+    # The string type behind every `option :name, :string` declaration:
+    # ActiveModel's String type copies each value into a fresh String,
+    # which drops the html_safe mark a SafeBuffer carries, so a caller's
+    # `hint: link_to(...)` or `t(".hint_html")` arrived escaped. This
+    # type keeps an html-safe value as it is and casts everything else
+    # exactly as the String type does; a plain String still escapes at
+    # render, because nothing here marks anything safe.
+    #
+    # Substituted inside the option DSL only - never registered, so
+    # `attribute :x, :string` in a host model keeps Rails' own type - and
+    # it reports :string, so the registry and every introspection surface
+    # read the declaration unchanged.
+    class HtmlSafeString < ActiveModel::Type::String
+      private
+
+      # An html-safe String passes through untouched; everything else casts
+      # as a String does.
+      #
+      # @param value [Object] the raw option value
+      # @return [::String]
+      def cast_value(value)
+        return value if value.is_a?(::String) && value.html_safe?
+
+        super
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Check
+      # The compile tier for component templates: each one is compiled
+      # under Herb the way `bin/rails herb:check` compiles an app's views.
+      #
+      # Rails renders HTML templates through Herb under its 8.2 framework
+      # defaults, and its check task tells an app which views will not
+      # compile. That task walks the view paths. A template that sits
+      # beside its component lives outside them, so nothing reaches it
+      # before the page that renders the component does. Rails checks
+      # views, this checks components: the app's own, and the ones the gems
+      # in the boot ship.
+      #
+      # The severity follows the app. One that renders through Herb has the
+      # template fail where it is used, which is an error. One that renders
+      # through Erubi renders it as it always has, so the finding is a
+      # WARNING about the day the app adopts the defaults.
+      #
+      # @api private
+      class Compile
+        # The rule the findings carry.
+        RULE = "herb-compile"
+
+        # The HTML templates of the components under a root, variants
+        # included. Rails compiles no other format through Herb.
+        GLOB = "app/components/**/*.html{,+*}.erb"
+
+        # A component's HTML template by convention: a file under
+        # `app/components/` in the HTML format, with or without a variant.
+        HTML_TEMPLATE = %r{(?:\A|/)app/components/.+\.html(?:\+[\w-]+)?\.erb\z}
+
+        # The path, line and column the engine opens a message with.
+        LOCATION = /\A:\d+:\d+(?::| -) /
+
+        class << self
+          # Whether a path is a component's HTML template by convention.
+          #
+          # @param path [String]
+          # @return [Boolean]
+          def html_template?(path)
+            HTML_TEMPLATE.match?(path.to_s)
+          end
+
+          # Why the tier cannot run, or nil when it can: the herb gem is
+          # missing, or older than the engine the gate is written for.
+          #
+          # @return [String, nil]
+          def unavailable
+            TemplateCompile.compile("")
+            nil
+          rescue Poetry::Core::Error => e
+            e.message
+          end
+
+          # Whether the booted app compiles its HTML templates with Herb:
+          # the handler registered for ERB hands them to the engine, or
+          # Rails' own implementation switch names it.
+          #
+          # @return [Boolean]
+          def rendering?
+            return false unless defined?(::Herb::Engine) && defined?(::ActionView::Template)
+
+            handler = ::ActionView::Template.handler_for_extension(:erb)
+            owner = handler.is_a?(Module) ? handler : handler.class
+            return true if defined?(::ReActionView::Template::Handlers::ERB) &&
+                           owner <= ::ReActionView::Template::Handlers::ERB
+
+            implementation = owner.erb_implementation if owner.respond_to?(:erb_implementation)
+            implementation.is_a?(Class) && implementation <= ::Herb::Engine
+          end
+        end
+
+        # A compile tier for an app.
+        #
+        # @param rendering [Boolean] whether the app renders its HTML
+        #   templates through Herb, which makes a finding an error
+        def initialize(rendering: false)
+          @rendering = rendering
+        end
+
+        # The finding for one template, when the engine refuses it.
+        #
+        # @param source [String] the template
+        # @param filename [String] its path, which the engine's message opens with
+        # @param shipped [Boolean] whether the template ships in a gem
+        # @return [Array<Finding>]
+        def lint(source, filename:, shipped: false)
+          failure = TemplateCompile.failure(source, filename: filename.to_s, posture: :rails)
+          return [] unless failure
+
+          [Finding.new(rule: RULE, severity: @rendering ? :error : :warning, line: failure.line,
+                       message: message(failure, filename.to_s, shipped))]
+        end
+
+        # The findings for the component templates the roots ship, each
+        # stamped with its file. A template that cannot be read is skipped:
+        # the render that needs it reports that better than a lint can.
+        #
+        # @param roots [Array<String, Pathname>] gem roots
+        # @return [Array<Finding>]
+        def scan(roots)
+          roots.flat_map do |root|
+            Dir.glob(GLOB, base: root.to_s).sort.flat_map do |relative|
+              path = File.join(root.to_s, relative)
+              lint(File.read(path, encoding: "UTF-8"), filename: path, shipped: true)
+                .each { |finding| finding.file = path }
+            rescue SystemCallError, IOError, ArgumentError, Encoding::CompatibilityError
+              []
+            end
+          end
+        end
+
+        private
+
+        # The finding's sentence: the compiler, the engine's reason
+        # without the path it opens with, and what fixes a shipped template.
+        def message(failure, filename, shipped)
+          compiler = @rendering ? "this app renders with" : "Rails 8.2 renders with by default"
+          text = "does not compile under Herb, the compiler #{compiler}: #{reason(failure, filename)}"
+          return text unless shipped
+
+          "#{text} - the template ships in a gem: update the gem, or hold herb at the version it was " \
+            "checked against (the bundle resolves herb #{Herb::VERSION})"
+        end
+
+        # The engine's message on one line, without its location prefix.
+        def reason(failure, filename)
+          first = failure.message.to_s.each_line.map(&:strip).reject(&:empty?).first.to_s
+          first.delete_prefix(filename).sub(LOCATION, "")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Check
+      # The renderable rule for a component class: no declaration defines
+      # the reader Rails asks a component for.
+      #
+      # Rails reads `format` off what it renders and takes the answer for
+      # the format of the template. An `option :format`, a `style :format`
+      # or a slot named `format` defines that reader, and it answers with
+      # the declared value. A render through the renderer then raises
+      # `Invalid formats`. A render from a controller has always gone
+      # through it; from Rails 8.2 a render in a view goes through it too,
+      # which is every helper call on the page.
+      #
+      # A class that answers Rails itself is left alone: one that defines
+      # `format` in its own body, with `def` or `define_method`, keeps the
+      # keyword for its callers and reads the value under another name.
+      #
+      # @api private
+      class RenderableReaders
+        # The rule the findings carry.
+        RULE = "renderable-reader"
+
+        # The name Rails reads off a renderable.
+        READER = "format"
+
+        # The declarations that define a reader named after the declaration.
+        DECLARATIONS = %w[option style renders_one renders_many].freeze
+
+        # A rule over a Ruby file; it reads the source alone and needs no
+        # catalog.
+        #
+        # @param severity [Symbol] :warning, or :error where the host's
+        #   Rails renders a view through the renderer
+        def initialize(severity: :warning)
+          @severity = severity
+        end
+
+        # The findings for one Ruby source.
+        #
+        # @param source [String] the Ruby source
+        # @return [Array<Finding>]
+        def lint(source)
+          require "prism"
+
+          result = Prism.parse(source)
+          return [] unless result.success?
+
+          findings = []
+          walk(result.value, findings)
+          findings
+        end
+
+        private
+
+        # Judges every class body on the way down.
+        def walk(node, findings)
+          findings.concat(class_findings(node)) if node.is_a?(Prism::ClassNode)
+          node.compact_child_nodes.each { |child| walk(child, findings) }
+        end
+
+        # The declarations in one class body that define the reader, unless
+        # the body defines it itself.
+        def class_findings(klass)
+          statements = klass.body.is_a?(Prism::StatementsNode) ? klass.body.body : []
+          return [] if statements.any? { |statement| answers_rails?(statement) }
+
+          statements.filter_map do |statement|
+            next unless (name = declaration(statement))
+
+            Finding.new(rule: RULE, severity: @severity, line: statement.location.start_line,
+                        message: message(name))
+          end
+        end
+
+        # A `def format` or `define_method(:format)` in the class body.
+        def answers_rails?(statement)
+          return statement.name.to_s == READER if statement.is_a?(Prism::DefNode)
+
+          call?(statement, "define_method") && literal_name(statement.arguments&.arguments&.first) == READER
+        end
+
+        # The declaration keyword when the statement declares the reader.
+        def declaration(statement)
+          return unless statement.is_a?(Prism::CallNode) && statement.receiver.nil?
+
+          name = statement.name.to_s
+          return unless DECLARATIONS.include?(name)
+          return unless literal_name(statement.arguments&.arguments&.first) == READER
+
+          name
+        end
+
+        # A receiverless call by that name.
+        def call?(node, name)
+          node.is_a?(Prism::CallNode) && node.receiver.nil? && node.name.to_s == name
+        end
+
+        # A symbol or string literal's text, or nil.
+        def literal_name(node)
+          node.unescaped if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+        end
+
+        # The finding's sentence.
+        def message(name)
+          "#{name} :#{READER} defines the reader Rails asks a component for the format of its template, and it " \
+            "answers with the declared value: a render through the renderer raises `Invalid formats`, and from " \
+            "Rails 8.2 every render in a view goes through it - keep the keyword and read the value under another " \
+            "name, with `define_method(:#{READER}) { nil }` beside the declaration, or rename it"
+        end
+      end
+    end
+  end
+end

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

@@ -24,8 +24,12 @@ module Poetry
       #
       # A component whose registry entry declares "identity" => false
       # renders no poetry-minted id - key:/id: would have nothing to
-      # stabilize - so both rules skip it. The registry derivation owns
-      # that fact per gem; legacy entries without the key keep warning.
+      # stabilize - so both rules skip it (a pathless helper declares the
+      # same in the registry helpers section). The registry derivation
+      # owns that fact per gem; legacy entries without the key keep
+      # warning. A double-splat of an id-bearing hash (`**field.control_attributes`,
+      # `**attrs`) counts as identity too: the id arrives through the splat,
+      # and the scan reads the name, not the hash.
       #
       # @api private
       class StableIdentity
@@ -36,7 +40,8 @@ module Poetry
         CACHE_OPENER = /\A\s*cache[\s(]/
         LOOP_OPENER =
           /\.(?:each|each_with_index|each_with_object|each_slice|map|collect|flat_map)\b.*\bdo\b|\Afor\s.+\sin\s/
-        IDENTITY_ARG = /(?:\bkey:|\bid:|["']key["']\s*=>|["']id["']\s*=>)/
+        IDENTITY_ARG =
+          /(?:\bkey:|\bid:|["']key["']\s*=>|["']id["']\s*=>|\*\*[\w.@]*(?:control_attributes|attributes|attrs)\b)/
 
         # A stable-identity linter over the catalog.
         def initialize(catalog)

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    module Check
+      # The element rule for component templates: an element is built
+      # through `element_tag`, and `tag.attributes` takes its hash as an
+      # argument.
+      #
+      # A host may compile its templates with Herb's slots. That compile
+      # resolves Action View's own tag helpers into markup ahead of the
+      # render, and three shapes do not survive it: attributes handed over
+      # in a splat or in a variable are dropped from the element, and a tag
+      # name that is not a literal leaves Ruby that does not parse. Nothing
+      # reports the first, and the second fails the page. `element_tag` is
+      # a helper Herb does not resolve, so the element is built at render
+      # time from what the component handed it.
+      #
+      # WARNING severity, component templates only: a view that hands a tag
+      # helper a splat is valid Rails, and whether its host compiles with
+      # slots is not something a lint of the source can know.
+      #
+      # `strict:` is the rule poetry's own templates are held to: no call to
+      # `content_tag` or `tag.<name>` at all, whatever its arguments.
+      #
+      # @api private
+      class TagHelpers
+        # An ERB tag with code in it: not a comment, not an escaped tag.
+        ERB_TAG = /<%(?![#%])(?:==|=|-)?(.*?)-?%>/m
+
+        # A tag-helper linter; it reads the source alone and needs no catalog.
+        #
+        # @param strict [Boolean] flag every call to an Action View tag
+        #   helper, not only the shapes a slot compile gets wrong
+        def initialize(strict: false)
+          @strict = strict
+        end
+
+        # The findings for one ERB source.
+        #
+        # @param source [String] the template
+        # @return [Array<Finding>]
+        def lint(source)
+          require "prism"
+
+          source.to_enum(:scan, ERB_TAG).flat_map do
+            match = Regexp.last_match
+            line = source[0...match.begin(1)].count("\n") + 1
+            calls_in(Prism.parse(match[1]).value).filter_map { |call| finding_for(call, line) }
+          end
+        end
+
+        private
+
+        # Every call to `content_tag`, `tag.<name>` or `tag.attributes` under a node.
+        def calls_in(node, into = [])
+          return into unless node
+
+          into << node if node.is_a?(Prism::CallNode) && tag_helper?(node)
+          node.compact_child_nodes.each { |child| calls_in(child, into) } if node.respond_to?(:compact_child_nodes)
+          into
+        end
+
+        # Whether a call is `content_tag(...)` or a method on the bare `tag` builder.
+        def tag_helper?(call)
+          return true if call.name == :content_tag && call.receiver.nil?
+
+          builder = call.receiver
+          builder.is_a?(Prism::CallNode) && builder.name == :tag && builder.receiver.nil? && builder.arguments.nil?
+        end
+
+        # The finding for one call, or nil when the call is one a slot compile reads right.
+        def finding_for(call, base_line)
+          line = base_line + call.location.start_line - 1
+          written = written(call)
+          return attributes_finding(call, written, line) if call.name == :attributes && call.receiver
+
+          problem = problem_with(call)
+          return unless problem || @strict
+
+          Finding.new(rule: "element-tag", severity: :warning, line: line,
+                      message: "#{written} #{problem || "is an Action View tag helper"} - " \
+                               "build the element with #{replacement(call)}")
+        end
+
+        # The finding for `tag.attributes` handed a splat; its hash as an argument is the form to keep.
+        def attributes_finding(call, written, line)
+          return unless splat?(call)
+
+          Finding.new(rule: "element-tag", severity: :warning, line: line,
+                      message: "#{written} hands its hash over as a splat, which a host compiling with " \
+                               "Herb's slots drops from the element - pass it as an argument: " \
+                               "tag.attributes(#{splat_source(call)})")
+        end
+
+        # What a slot compile gets wrong about a call, in words, or nil.
+        def problem_with(call)
+          if call.name == :content_tag && !literal_name?(call)
+            "takes its tag name from a variable, which stops the template compiling in a host " \
+              "that compiles with Herb's slots"
+          elsif splat?(call) || variable_options?(call)
+            "takes attributes a host compiling with Herb's slots cannot read, and drops them from the element"
+          end
+        end
+
+        # Whether `content_tag` names its tag with a symbol or a string literal.
+        def literal_name?(call)
+          first = positional(call).first
+
+          first.is_a?(Prism::SymbolNode) || first.is_a?(Prism::StringNode)
+        end
+
+        # Whether a call hands over a double splat.
+        def splat?(call)
+          keywords(call).any?(Prism::AssocSplatNode)
+        end
+
+        # Whether a block call takes its attributes as a variable: with a
+        # block, the argument after the tag name is the options.
+        def variable_options?(call)
+          return false unless call.block
+
+          options = call.name == :content_tag ? positional(call)[1] : positional(call)[0]
+          !options.nil? && !options.is_a?(Prism::HashNode)
+        end
+
+        # The arguments that are not keywords.
+        def positional(call)
+          (call.arguments&.arguments || []).grep_v(Prism::KeywordHashNode)
+        end
+
+        # The elements of the keyword hash, splats among them.
+        def keywords(call)
+          (call.arguments&.arguments || []).grep(Prism::KeywordHashNode).flat_map(&:elements)
+        end
+
+        # The call as it is written, up to its arguments.
+        def written(call)
+          call.receiver ? "tag.#{call.name}" : "content_tag"
+        end
+
+        # The `element_tag` call to write instead.
+        def replacement(call)
+          return "element_tag(:#{call.name}, ...)" if call.receiver
+
+          "element_tag(#{positional(call).first&.slice || ":name"}, ...)"
+        end
+
+        # The expression a splat spreads.
+        def splat_source(call)
+          keywords(call).grep(Prism::AssocSplatNode).first&.value&.slice || "attributes"
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/check.rb

@@ -197,12 +197,16 @@ module Poetry
         # that yields its slot builder.
         def helper_yields?(helper) = !@helper_entries.dig(helper, "yields").nil?
 
-        # A helper whose component entry declares "identity" => false:
-        # its rendered output carries no poetry-minted id, so key:/id:
-        # have nothing to stabilize and the stable-identity rules skip
-        # it. Pathless helpers and legacy entries (no key) read as
-        # minting - their warnings stand.
-        def identity_free?(helper) = @components.dig(@path_by_helper[helper], "identity") == false
+        # A helper whose component entry declares "identity" => false, or
+        # a pathless helper whose registry helpers-section entry declares
+        # it (a table part helper stamps no poetry-minted id): its rendered
+        # output carries no random id, so key:/id: have nothing to
+        # stabilize and the stable-identity rules skip it. Legacy entries
+        # (no key) read as minting - their warnings stand.
+        def identity_free?(helper)
+          @components.dig(@path_by_helper[helper], "identity") == false ||
+            @helper_entries.dig(helper, "identity") == false
+        end
 
         # The element-level wiring projection: which elements of
         # a component carry which controllers, values, actions, and
@@ -419,10 +423,11 @@ module Poetry
             node.class.name.include?("ERB") && !erb_comment?(node)
         end
 
-        # <%# ... %> parses as an ERBContentNode like any output tag - only
-        # the tag opening tells prose from code. Comment text mentioning a
-        # helper ("a plain poetry_input chromes it") must never reach Prism
-        # as Ruby (the helper-arity false-positive class).
+        # <%# ... %> carries content like any output tag, whichever node
+        # class the parser gives it - only the tag opening tells prose from
+        # code. Comment text mentioning a helper ("a plain poetry_input
+        # chromes it") must never reach Prism as Ruby (the helper-arity
+        # false-positive class).
         def erb_comment?(node)
           node.respond_to?(:tag_opening) && node.tag_opening&.value == "<%#"
         end
@@ -1373,9 +1378,10 @@ module Poetry
         # A click target that is not a button: an inert element carrying
         # onclick or wearing role=button. A real <button> brings focus,
         # keyboard activation, and the role for free, which is the first
-        # rule of ARIA. Anchors stay out (a role=button link is an accepted
-        # pattern), and so does a Stimulus click on a bare div - a backdrop
-        # or a row is a legitimate click target without a role.
+        # rule of ARIA. Anchors stay out (a link is a link - the Button's
+        # anchor form renders no role, and an author who adds one has
+        # chosen it), and so does a Stimulus click on a bare div - a
+        # backdrop or a row is a legitimate click target without a role.
         def fake_button_findings(node)
           tag = open_tag_name(node)
           attributes = node.child_nodes.compact.grep(Herb::AST::HTMLAttributeNode)
@@ -1656,11 +1662,21 @@ module Poetry
       # @api private
       class Runner
         # A runner over the catalog's linters.
-        def initialize(catalog)
+        #
+        # @param catalog [Catalog] the component catalog to validate against
+        # @param compile [Compile, nil] the compile tier, which a host's
+        #   check hands over and a gem's own leaves to its compile gate
+        # @param renderable [RenderableReaders] the renderable rule for
+        #   component classes, an error where the host's Rails renders every
+        #   view through the renderer
+        def initialize(catalog, compile: nil, renderable: RenderableReaders.new)
           @linter = Linter.new(catalog)
           @declarations = IconDeclarations.new(catalog)
           @internals = InternalConstants.new(catalog)
           @stable_identity = StableIdentity.new(catalog)
+          @tag_helpers = TagHelpers.new
+          @compile = compile
+          @renderable = renderable
         end
 
         # Every finding across the paths, each stamped with its file.
@@ -1683,12 +1699,19 @@ module Poetry
             return [Finding.new(rule: "unreadable", severity: :warning,
                                 message: "not valid UTF-8 - skipped (re-encode the file to lint it)")]
           end
-          return @declarations.lint(source) + @internals.lint(source) if path.end_with?(".rb")
+          if path.end_with?(".rb")
+            return @declarations.lint(source) + @internals.lint(source) + @renderable.lint(source)
+          end
 
           findings = @linter.lint(source, mail: Check.mail_template?(path, root: root))
           # The StableId heuristics ride every ERB pass (warnings only -
-          # they never flip the exit code).
-          findings + @stable_identity.lint(source)
+          # they never flip the exit code); the element rule rides a
+          # component's template, and so does the compile tier when the
+          # runner was handed one.
+          findings += @stable_identity.lint(source)
+          findings += @tag_helpers.lint(source) if Check.component_template?(path)
+          findings += @compile.lint(source, filename: path) if @compile && Compile.html_template?(path)
+          findings
         rescue SystemCallError, IOError, ArgumentError, Encoding::CompatibilityError => e
           [Finding.new(rule: "unreadable", severity: :warning, message: "#{e.class}: #{e.message} - skipped")]
         end
@@ -1702,8 +1725,21 @@ module Poetry
       # leave these alone.
       MAIL_TEMPLATE = %r{(?:\A|/)(?:[a-z0-9_]+_mailer|layouts/mailer|devise/mailer)(?:/|\.)}
 
+      # A component's template by convention: an ERB file under
+      # `app/components/`, where a sidecar template lives.
+      COMPONENT_TEMPLATE = %r{(?:\A|/)app/components/.+\.erb\z}
+
       module_function
 
+      # Whether a template path is a component's template by convention:
+      # an ERB file under `app/components/`.
+      #
+      # @param path [String]
+      # @return [Boolean]
+      def component_template?(path)
+        COMPONENT_TEMPLATE.match?(path.to_s)
+      end
+
       # Whether a template path is a mailer template by convention: a view
       # under a `*_mailer/` directory (Devise's `devise/mailer/` included)
       # or the mailer layout. With a root, only the path inside it counts,

data/lib/poetry/core/engine.rb

@@ -44,14 +44,23 @@ module Poetry
       end
 
       # The app's and its engines' own components' helpers (`helper :name`):
-      # defined at boot and on every reload, after the components directories load,
-      # so a view can call one before anything else referenced the class.
+      # defined before the first view renders and again on every reload, so a
+      # view can call one before anything else referenced the class.
+      #
+      # The components are loaded to find the helpers, and a component is a
+      # view. Loading them while the framework is still initializing loads
+      # Action View early, which Rails reports and, when asked, raises on.
+      # Loading them from Action View's own load hook is no better: when a
+      # component class is what loads Action View, the classes are half
+      # defined. So a host that eager loads syncs once its boot is done, with
+      # the classes already loaded, and every other host syncs on its first
+      # view context, at render time. Each reload syncs from `to_prepare`.
       initializer "poetry_core.host_helpers" do |app|
-        app.config.to_prepare do
-          Poetry::Core::HostHelpers.sync!(Poetry::Core::HostComponents.discover)
-          ActiveSupport.on_load(:action_view) do
-            include Poetry::Core::HostHelpers unless include?(Poetry::Core::HostHelpers)
-          end
+        app.config.after_initialize { Poetry::Core::HostHelpers.sync_now! if app.config.eager_load }
+        app.config.to_prepare { Poetry::Core::HostHelpers.sync_now! if Poetry::Core::HostHelpers.ready? }
+        ActiveSupport.on_load(:action_view) do
+          include Poetry::Core::HostHelpers unless include?(Poetry::Core::HostHelpers)
+          prepend Poetry::Core::HostHelpers::FirstView unless self < Poetry::Core::HostHelpers::FirstView
         end
       end
 

data/lib/poetry/core/host_helpers.rb

@@ -15,7 +15,45 @@ module Poetry
     #
     # @api private
     module HostHelpers
+      # Prepended to Action View's base class by the engine: the first view
+      # context of a host that did not eager load syncs the helpers, so the
+      # template about to render can call one. After that it is one
+      # comparison per view.
+      #
+      # @api private
+      module FirstView
+        # The view context, with the helpers defined first.
+        def initialize(...)
+          Poetry::Core::HostHelpers.sync_now! unless Poetry::Core::HostHelpers.ready?
+          super
+        end
+      end
+
+      SYNC = Mutex.new
+      private_constant :SYNC
+
       class << self
+        # Discovers the app's components and defines their helpers: the
+        # engine's sync, at the end of an eager loading boot, at the first
+        # view otherwise, and on every reload. One at a time, since two views
+        # can be the first on two threads.
+        #
+        # @return [Array<String>] the helper names now defined
+        def sync_now!
+          SYNC.synchronize do
+            names = sync!(HostComponents.discover)
+            @ready = true
+            names
+          end
+        end
+
+        # Whether the first sync has happened, so a reload may sync again.
+        #
+        # @return [Boolean]
+        def ready?
+          @ready == true
+        end
+
         # Defines the helpers of `components` and removes the helpers of
         # components that no longer declare one (a rename, a deletion).
         # Every name is checked before any is defined, so a clash leaves

data/lib/poetry/core/slot_markers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # What a slot compile writes around a template's own markup, and how to
+    # take it off again.
+    #
+    # A host that compiles its templates with Herb's slots gets every
+    # dynamic part of the page marked, so the browser can find it again:
+    # comments around a rendering and around each slot, a `data-herb-slot`
+    # attribute on an element that carries one, and the branches that did
+    # not render, parked in a `<template>` behind the rendering. None of it
+    # is the component's. Taken off, what is left is the markup the template
+    # wrote, which is what a test or a contract means to compare.
+    #
+    # @example
+    #   html = render_inline(Poetry::Ui::Button::Component.new) { "Save" }.to_html
+    #   Poetry::Core::SlotMarkers.strip(html) # => the button, as a plain host renders it
+    module SlotMarkers
+      # A marker comment: a region, a slot, a branch or the seeds, opening
+      # or closing.
+      COMMENT = %r{<!--/?herb-[a-z]+\b.*?-->}m
+
+      # The attribute on an element that carries a slot.
+      ATTRIBUTE = / data-herb-slot="[^"]*"/
+
+      # Where a parked block opens: branches under `data-herb-region`, the
+      # state map under `data-herb-dependencies`.
+      PARKED = /<template data-herb-(?:region|dependencies)\b[^>]*>/
+
+      # Either end of a template element.
+      TEMPLATE_EDGE = %r{<template\b[^>]*>|</template>}
+
+      class << self
+        # The markup without anything a slot compile added. Markup that
+        # carries none of it comes back as it went in.
+        #
+        # @param html [String] rendered markup
+        # @return [String] the markup the templates wrote, html-safe when
+        #   what it was given was
+        def strip(html)
+          source = html.to_s
+          return html unless source.include?("herb-")
+
+          stripped = without_parked(source).gsub(COMMENT, "").gsub(ATTRIBUTE, "")
+          html.respond_to?(:html_safe?) && html.html_safe? ? stripped.html_safe : stripped
+        end
+
+        private
+
+        # The markup without its parked blocks. A parked branch may hold a
+        # template element of its own, so the end of a block is the closing
+        # tag that balances its opening one.
+        def without_parked(html)
+          kept = +""
+          rest = html
+          while (opening = rest.match(PARKED))
+            kept << opening.pre_match
+            rest = after_block(opening.post_match)
+          end
+          kept << rest
+        end
+
+        # What follows the template element whose opening tag was just read.
+        def after_block(html)
+          depth = 1
+          rest = html
+          while depth.positive? && (edge = rest.match(TEMPLATE_EDGE))
+            depth += edge[0].start_with?("</") ? -1 : 1
+            rest = edge.post_match
+          end
+          depth.zero? ? rest : ""
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/tag_helper.rb

@@ -3,8 +3,50 @@
 module Poetry
   module Core
     # The view-helper seam: included into ActionView by the engine
-    # (initializer "poetry_core.tag_helper"). Carries no helpers in core.
+    # (initializer "poetry_core.tag_helper") and into every component, so a
+    # view and a component's template build an element the same way.
     module TagHelper
+      # The elements that take no content and no closing tag: {#element_tag}
+      # renders these through `tag` and every other name through
+      # `content_tag`.
+      VOID_ELEMENTS = %w[area base br col embed hr img input link meta source track wbr].freeze
+
+      # An element from a tag name and its attributes: where a component's
+      # template spends what `root_attributes` and `element_attributes`
+      # build. It takes what `content_tag` takes and renders what
+      # `content_tag` renders; a void element renders the way `tag.input`
+      # does.
+      #
+      # A component's template builds every element through this method,
+      # and never through `content_tag` or `tag.div` themselves. A host may
+      # compile its templates with Herb's slots, and that compile resolves
+      # Action View's own tag helpers into markup ahead of the render: a
+      # splat or a tag name held in a variable is more than it can read,
+      # and the element comes out without its attributes, or the template
+      # stops compiling. A method it does not know stays a call, so the
+      # element reaches the page as it was built. `tag.attributes` is the
+      # one helper a template still calls itself, for attributes written
+      # inside a literal tag, and it takes its hash as an argument, never as
+      # a splat. A view holds to the same rule wherever it hands a tag
+      # helper a splat.
+      #
+      # @param name [Symbol, String] the tag name
+      # @param arguments [Array] the content, when no block gives it, and
+      #   the attributes when they arrive as a Hash
+      # @param attributes [Hash] what `root_attributes` or a part builder
+      #   returned, splatted, or the attributes written out as keywords
+      # @return [ActiveSupport::SafeBuffer] the element
+      # @example A root, a part and a void element
+      #   <%= element_tag(:button, **root_attributes) do %>
+      #     <%= element_tag(:span, label, **element_attributes(:label)) %>
+      #     <%= element_tag(:input, **input_attributes) %>
+      #   <% end %>
+      def element_tag(name, *arguments, **attributes, &)
+        return content_tag(name, *arguments, **attributes, &) unless VOID_ELEMENTS.include?(name.to_s)
+
+        given = arguments.last.is_a?(Hash) ? arguments.last : {}
+        tag.public_send(name, **given, **attributes)
+      end
     end
   end
 end

data/lib/poetry/core/template_compile.rb

@@ -3,15 +3,29 @@
 module Poetry
   module Core
     # The Herb COMPILE gate: every ERB template is fed through
-    # `Herb::Engine` - the same compiler Rails routes templates through when
-    # a host opts into the Herb ERB implementation - so a template that
-    # parses but refuses to compile (ERB output in an attribute name, bare
-    # output in attribute position, an element nested where the validators
-    # forbid it) fails poetry's CI instead of the host's first request.
+    # `Herb::Engine` - the compiler Rails routes HTML templates through
+    # under its 8.2 framework defaults - so a template that parses but
+    # refuses to compile (ERB output in an attribute name, bare output in
+    # attribute position, an element nested where the validators forbid it)
+    # fails poetry's CI instead of the host's first request.
+    #
+    # The posture is the strictest one a host can run. The engine validates
+    # nothing unless it is handed validators, so the gate hands it every
+    # validator it ships, each one fatal, and has the compiled Ruby checked
+    # for syntax. Rails compiles without validators and its `herb:check`
+    # task adds the security one; a host that compiles gem templates with
+    # every validator raising is the far end. A template that passes here
+    # passes all of them. The validators are named in code, never read from
+    # `.herb.yml`, so no configuration can hollow the gate.
+    #
+    # A second posture, `:rails`, is the one `bin/rails herb:check` holds an
+    # app's views to: the security validator alone. `poetry:check` compiles
+    # component templates in it, since that task walks the view paths and
+    # never reaches them.
     #
     # Parsing clean (see CSS::TemplateClasses, the parse gate) and
-    # compiling clean are different contracts: the engine runs validators
-    # the parser does not.
+    # compiling clean are different contracts: the validators refuse shapes
+    # the parser accepts.
     #
     # Herb is loaded lazily: it is a build/CI-time tool, not a runtime
     # dependency of the gem.
@@ -26,6 +40,20 @@ module Poetry
       # copied verbatim into hosts. Rails renders both through the engine.
       DEFAULT_GLOBS = ["app/**/*.erb", "lib/generators/**/templates/**/*.erb"].freeze
 
+      # The oldest Herb the gate runs on: from this version the engine takes
+      # its validators as visitors and raises compile errors as syntax errors.
+      MINIMUM_HERB = "0.11.0"
+
+      # The validators of each posture, by their names in the engine.
+      POSTURES = {
+        strict: %i[security nesting accessibility render generator_template],
+        rails: %i[security]
+      }.freeze
+
+      # A template the engine refused: its message, and the line the engine
+      # points at when it names one.
+      Failure = Struct.new(:message, :line)
+
       # A template Herb's engine could not compile, with its message.
       CompileError = Struct.new(:path, :message) do
         # The path and the message.
@@ -39,25 +67,50 @@ module Poetry
 
       class << self
         # Compiles one ERB source string, returning the engine's error
-        # message or nil when it compiles.
+        # message or nil when it compiles. A missing or outdated herb gem
+        # raises instead: that is a broken setup, not a finding about the
+        # template.
         #
+        # @param source [String] the template
+        # @param filename [String] the path the engine opens its message with
+        # @param posture [Symbol] :strict or :rails
         # @return [String, nil]
-        def compile(source, filename: "template.html.erb")
+        def compile(source, filename: "template.html.erb", posture: :strict)
+          failure(source, filename: filename, posture: posture)&.message
+        end
+
+        # Compiles one ERB source string, returning what the engine refused
+        # it for, or nil when it compiles.
+        #
+        # @param source [String] the template
+        # @param filename [String] the path the engine opens its message with
+        # @param posture [Symbol] :strict or :rails
+        # @return [Failure, nil]
+        def failure(source, filename: "template.html.erb", posture: :strict)
           herb!
-          Herb::Engine.new(source, filename: filename)
-          nil
-        rescue StandardError => e
-          e.message
+          visitors = validators(posture)
+
+          begin
+            Herb::Engine.new(source, filename: filename, validate_ruby: true, visitors: visitors)
+            nil
+          rescue StandardError, SyntaxError => e
+            # The engine raises its compile and parse errors as syntax
+            # errors, which a bare rescue would let through.
+            Failure.new(e.message, line_of(e))
+          end
         end
 
         # Compiles every template under root matching the globs.
         #
+        # @param root [String, Pathname] the directory the globs are read under
+        # @param globs [Array<String>] the templates to compile
+        # @param posture [Symbol] :strict or :rails
         # @return [Result] compiled (Integer, templates that compiled) + errors (Array<CompileError>)
-        def check(root:, globs: DEFAULT_GLOBS)
+        def check(root:, globs: DEFAULT_GLOBS, posture: :strict)
           errors = []
           paths = globs.flat_map { |glob| Dir.glob(glob, base: root.to_s) }.uniq.sort
           paths.each do |relative|
-            message = compile(File.read(File.join(root, relative)), filename: relative)
+            message = compile(File.read(File.join(root, relative)), filename: relative, posture: posture)
             errors << CompileError.new(relative, message) if message
           end
           Result.new(paths.size - errors.size, errors)
@@ -65,12 +118,51 @@ module Poetry
 
         private
 
-        # Requires the herb gem, raising a clear error when it is missing.
+        # The validators of a posture, each one fatal. Built per compile,
+        # since a validator keeps what it found. The strict posture is every
+        # validator the engine ships, so one a later release adds joins it.
+        def validators(posture = :strict)
+          names = POSTURES.fetch(posture) do
+            raise ArgumentError, "unknown posture #{posture.inspect} - one of #{POSTURES.keys.join(", ")}"
+          end
+          shipped = Herb::Engine::Validators::ALL
+          chosen = posture == :strict ? shipped.values : shipped.values_at(*names)
+          chosen.map { |validator| validator.new(fatal: true) }
+        end
+
+        # The line an engine error points at: a validator's error carries
+        # it, a parse error carries it on its first diagnostic.
+        def line_of(error)
+          return error.line if error.respond_to?(:line) && error.line
+          return unless error.respond_to?(:diagnostics)
+
+          location = error.diagnostics.first&.location
+          location&.start&.line
+        end
+
+        # Requires the herb gem with its engine and validators, raising a
+        # clear error when the gem is missing or too old for the gate.
         def herb!
-          require "herb"
-        rescue LoadError
-          raise Poetry::Core::Error,
-                "the herb gem is required for the template compile gate - add `gem \"herb\"` to your Gemfile"
+          begin
+            require "herb"
+          rescue LoadError
+            raise Poetry::Core::Error,
+                  "the herb gem is required for the template compile gate - add `gem \"herb\"` to your Gemfile"
+          end
+
+          unless supported?(Herb::VERSION)
+            raise Poetry::Core::Error,
+                  "the template compile gate needs herb #{MINIMUM_HERB} or newer, found #{Herb::VERSION} - " \
+                  "run `bundle update herb`"
+          end
+
+          require "herb/engine"
+          require "herb/engine/validators"
+        end
+
+        # Whether a herb version carries the engine the gate is written for.
+        def supported?(version)
+          Gem::Version.new(version) >= Gem::Version.new(MINIMUM_HERB)
         end
       end
     end

data/lib/poetry/core/version.rb

@@ -4,6 +4,6 @@ module Poetry
   module Core
     # The gem version. Every gem in the family carries the same version
     # and pins poetry-core to it exactly.
-    VERSION = "0.1.7"
+    VERSION = "0.1.9"
   end
 end

data/lib/poetry/core.rb

@@ -5,6 +5,7 @@ require "zeitwerk"
 require "active_support/concern"
 require "active_model/type/symbol"
 require "active_model/type/list"
+require "active_model/type/html_safe_string"
 
 ActiveModel::Type.register(:symbol, ActiveModel::Type::Symbol)
 ActiveModel::Type.register(:list, ActiveModel::Type::List)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: poetry-core
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Matt Solt
 bindir: exe
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -180,13 +180,17 @@ files:
 - config/importmap.rb
 - config/state_vocabulary.json
 - eslint.config.mjs
+- lib/active_model/type/html_safe_string.rb
 - lib/active_model/type/list.rb
 - lib/active_model/type/symbol.rb
 - lib/poetry-core.rb
 - lib/poetry/core.rb
 - lib/poetry/core/api_internals.rb
 - lib/poetry/core/check.rb
+- lib/poetry/core/check/compile.rb
+- lib/poetry/core/check/renderable_readers.rb
 - lib/poetry/core/check/stable_identity.rb
+- lib/poetry/core/check/tag_helpers.rb
 - lib/poetry/core/config.rb
 - lib/poetry/core/contrib/wrapped_helper.rb
 - lib/poetry/core/css/bem_merger.rb
@@ -225,6 +229,7 @@ files:
 - lib/poetry/core/registry_items.rb
 - lib/poetry/core/requires_any.rb
 - lib/poetry/core/skill_text.rb
+- lib/poetry/core/slot_markers.rb
 - lib/poetry/core/stable_id.rb
 - lib/poetry/core/stimulus/builder.rb
 - lib/poetry/core/stimulus/declarations.rb