poetry-ui 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1346a1ff6a62e643e9440c7c42e835d643b55ea2dbcf8bc7938d800964995306
-  data.tar.gz: a569d21afd89f4f611309bab9c05492bc47d1ff4e9997d1178bcfd8859c840de
+  metadata.gz: cfaee0a24a3a61b10a2bf12f2afb0dd5a0b8f93117392f8deb4fbb81da36c984
+  data.tar.gz: bf5011451e6d6bd7fe2c7bed1ebc1150f3503d04fc04687f8bd0463d6a1612e4
 SHA512:
-  metadata.gz: '01872acf5407b8d3b14bb91c10f33f19b9fca4124f39338d8f88560c86bb6d41913ff50b92ef3dfa3293f4d14500fd3faa67395109a6d6f41a16412ab80c26ed'
-  data.tar.gz: 4180cbf5784bc923d57da1394c91542959570209ae1f8beb89e68d31e1c80f7ec5c0809fc65f363f6c6b3b025e72851f0ec08614b2020e94bee5df44ca6ccea0
+  metadata.gz: 11db0fc73021f75632fbf927e3f807043c7091eeaa049b5d58b90561910e2d521a94abe0f871333484f9f0292e3cc2f25c262c578d4dfb5d43a12591cb33159a
+  data.tar.gz: d27e5cb320b82e7f40fca65b3e3898350a5ec6ac8778c88b95fb7f8a11fca29861783a1bc016322e5dab9a583b82586fccc7fd48d905f4f0603029fed700f866

data/CHANGELOG.md

@@ -1,6 +1,72 @@
 # Changelog
 
-## [Unreleased]
+## [0.1.2] - 2026-09-13
+
+### Added
+
+- The install names the theme it puts in the slot: on a first install or an explicit `--theme`, one line says which theme fills `poetry/style-default.css`, that the slot name never changes, and that the file's first line names the theme. The Theming and Installation guides say the same, for the reader who opens a file called default and finds vega.
+
+- `poetry:install` and `poetry:skill` say so when the host gitignores `.claude/skills`: the skills still serve that checkout, and the note names the refresh command teammates and CI run (`bin/rails g poetry:skill`) or the alternative of un-ignoring the directory. Asked of git only; no git, no repository, or a tracked directory stay silent.
+
+- App components are first-class on the booted surfaces. A component the app defines on the DSL with `helper :name` renders through that helper, `poetry:check` lints it under that name with its own contract, `/poetry/llms.txt` and `llms-full.txt` list it under an App components section with its agent rules, and `poetry:skill` writes a `references/app.md` with a menu line. The AGENTS.md section and the poetry-component skill teach the declaration. The MCP server's `check` tool learns the declared helpers from source, so it agrees the helper exists; its contracts and the runtime skill map stay gem-only (boot-free by design).
+
+- `poetry:install --no-preflight`, for an app that imports Tailwind without preflight: vendors the reset floor (`poetry/reset.css`, Tailwind's preflight at zero specificity, generated from the pinned binary and gated against it) into `layer(base)` ahead of the theme, and on a fresh entry writes the split no-preflight import. A plain re-run keeps the floor once installed. Measured against the golden corpus: without preflight two thirds of the components render differently even behind a modern reset, so the floor is what keeps them whole; `POETRY_PREFLIGHT=0 rake test:visual` proves it. The installer and `poetry:check` warn (`preflight-missing`) when an entry imports neither preflight nor the floor.
+- `poetry:design:overrides` counts only a rule against a theme-owned `cn-*` name (a gem dictionary's or the installed fragment's own) as an override. A host kit's own `cn-*` dictionary, or a page helper class in that namespace, is no longer reported as undeclared drift; a blanket declaration written to silence those now shows as stale.
+- `bin/rails poetry:stimulus:manifest` writes the app's controllers manifest (`config/controllers_manifest.json`, the file a gem commits) from `app/javascript/controllers`; registered at boot, a host controller validates like poetry's (the DSL by Symbol at class load, template wiring in `poetry:check`, its API in the registry). A controller the reader cannot describe is named and stays unvalidated until its entry is written by hand in the same file, where regeneration keeps it. `poetry:check` warns (`manifest-stale`) and `poetry:verify` fails when the entries the reader produced no longer match the sources; hand-written entries never count.
+- `bin/rails poetry:registry` writes the app's own components to `config/component_registry.yml`, the path a gem's registry lives at, so the MCP server and the runtime skill find them boot-free with full contracts and agent rules. Opt-in; once written, `poetry:check` warns (`registry-stale`) and `poetry:verify` fails when the file no longer matches the classes.
+
+### Changed
+
+- The reset floor's header and the Installation guide say exactly what wins: an unlayered host rule always, a host rule in `layer(base)` when it comes after the floor's import, and `[hidden]` keeps preflight's `!important` on purpose. `poetry:verify` names the remedy when a kit's own `cn-*` class is not in the compiled CSS. The AGENTS.md section spells JSON output as `POETRY_CHECK_JSON=1`.
+
+- The upgrade path holds on real hosts: `--charts` is remembered by the vendored `poetry/charts.css`, so a plain re-run refreshes the chart files and a theme switch swaps the chart fragment with the theme; the superseded 0.1.1 tokens import converges however it was written (indented, annotated, or with a carriage return, which it keeps); every `eval_gemfile` spelling is read before `herb` is added; the Claude Code skills are refreshed like the vendored CSS, without an overwrite prompt (`--skip` keeps a hand-edited one); an AGENTS.md begin marker without its end is an error naming the file, a byte-identical section reports `identical`, the section is written in the file's own line endings, and only the first section is replaced.
+
+- `poetry:check` hands the runner the app root, so the mailer exemption and the design tier judge a template by its path inside the app; an unreadable file is a warning in the report, not a crash of the task.
+
+- `poetry:check` reports `registry-invalid` when `config/component_registry.yml` exists but is not a registry (empty, malformed, the wrong shape), naming `bin/rails poetry:registry` as the fix; the committed registry regenerates with every helper named.
+
+- The scaffold form template is the form builder's: `form_with(model:, builder: Poetry::Ui::FormBuilder)` and one `f.input` per attribute, the control inferred from the column, the name and the validations, with the template adding only what the generator knows and the model cannot say (`as: :text` for rich text, `multiple: true` for many attachments, `required: true` from `null: false`). The gem's reference CRUD form now follows the gem's own first rule about forms. A host that installed the templates before keeps its copy (re-runs never overwrite); delete `lib/templates/erb/scaffold/_form.html.erb.tt` and re-run `poetry:scaffold_templates` for the builder version. On the way, two inference gaps in the builder: `has_many_attached` attributes infer a file input (the plural responder), and `website` / `permalink` infer a URL input like `url` does.
+
+- The form builder's agent rules say which parts a builder field renders (`field-label`, `field-description` for the hint, `field-error`), so llms.txt's Forms section, the registry, the MCP server and the skill all name the slots a wiring test asserts on; the Testing guide says the same.
+
+- `poetry:check` treats mailer templates as email, not pages: under a `*_mailer/` directory or in the mailer layout the raw-color rule stays quiet (an inline hex is the only paint a mail client honours) and the design tier skips them; every other rule runs there as before. The AGENTS.md section says so.
+
+- An off-list variant or a missing required option now raises at construction in development and test (poetry-core's runtime values tier) instead of rendering unstyled; the AGENTS.md section says so beside the check.
+- poetry-ui pins its components to `css_mode :tailwind`, and the class-name merger follows: a host's global `BemMerger` (for a kit of its own) never reaches poetry-ui's utility conflict resolution. A host's global `css_mode = :bem` (for a kit of its own on the DSL) no longer strips poetry-ui's styling; the two render side by side. The seeded initializer's comment says so instead of offering `:bem` as a poetry-ui option.
+- `poetry:check` and the AGENTS.md census find registry roots by convention (every loaded engine with a published registry, then the app's own file) and name no gem; poetry-charts is no longer special-cased, and any engine built on the DSL that commits a registry joins the check the same way.
+- `poetry:install` imports `tokens.css` into `layer(theme)`, so a token the host already declares (`--primary`, `--accent`, `--muted`, ...) keeps its value whatever the order in the Tailwind entry, and that value now reaches Poetry's components too. Before, the appended import landed after the host's own `:root` and took the same names over: an app's brand color vanished before a single Poetry component rendered. A re-run rewrites the earlier unlayered import line in place.
+- `poetry:install` reports, before writing anything, every Poetry token name and theme key the app's stylesheets already declare, with the file and line and what Poetry paints with that role. It never blocks. `poetry:check` repeats the report as `token-collision` warnings.
+
+- The WebMCP agent-focus rules (`:tool-form-active`, `:tool-submit-active`) leave the nine theme fragments, where they were identical, for poetry-agent's own stylesheet; `poetry:install` vendors it into `layer(base)` when that gem is bundled. A host without poetry-agent no longer carries them, nor the two warnings the CSS optimizer printed for the origin-trial pseudo-classes on every minified build (the Rails Tailwind task minifies by default, so every build and watch run).
+
+### Fixed
+
+- `poetry:install --force` no longer rewrites the four files the install seeds once for the host to own (`config/poetry_components.yml`, the initializer, `poetry/base.css`, `poetry/typeset.css`); a re-run with the flag used to reset a host's override declarations and settings to the seed. The vendored artifacts refresh on every run, so the flag is never needed on an upgrade.
+- `poetry:install` no longer adds a second `herb` declaration when the gem is declared in a file the Gemfile pulls in with `eval_gemfile` (a shared Gemfile).
+
+## [0.1.1] - 2026-09-08
+
+### Added
+
+- `content_class:` on `poetry_dropdown_menu` and `poetry_context_menu`, on Menubar's `with_menu`, and on every menu family's `with_sub`: the panel's class merge seam, the one Popover, HoverCard and Dialog already had. A dropdown panel opens at its trigger's width (minimum 8rem), so `content_class: "w-56"` is how a menu with icons, shortcuts or long labels gets its width.
+- NavigationMenu `with_item(title, value:, disabled: true)`: an inert trigger (`disabled` + `data-disabled`) that hover, click and the arrows skip. `disabled:` on a link raises.
+- `Poetry::Ui::Chat::Error`, a `Poetry::Core::Error`: `AssistantTurn#continuation_frames` raises it on a turn without an approval pause, where a missing constant raised NameError before.
+- `poetry:install --skip-bundle`.
+
+### Changed
+
+- `poetry:install` adds the `herb` gem to the development group (once, never when the Gemfile already declares it) and runs `bundle install`, so `bin/rails poetry:check` works on a fresh app with no manual step. `poetry:check`'s missing-parser message points at the installer.
+- The upstream pin is shadcn@4.21.0. The theme CSS is unchanged between the releases; both fidelity ledgers are re-snapshotted at the new pin.
+- MessageScroller renders `data-pending-scroll` on its root and viewport for `:end` and `:"last-anchor"`; the viewport hides while it is set (visibility, so the layout stays) and the hold lifts without JavaScript. The part contracts declare the state.
+- Select, Combobox and Command group headings are `aria-hidden`: the group's name flows through `aria-labelledby`, so screen readers stop announcing the heading a second time. Menu groups wire `aria-labelledby` to a label rendered inside them and hide it the same way; a label outside any group stays plain text.
+- HoverCard's trigger wiring is `pointerdown->pointerDown` (was `touchstart->touchGuard`), and NumberField's input no longer wires a `focus` action. A copy made with `poetry:add hover_card` or `poetry:add number_field` before this version carries the old wiring and logs a Stimulus "undefined method" error on those events: run `bin/rails g poetry:diff` and update the two lines. Apps on the gem-owned tier need nothing.
+- ToastTrigger names its Button root through `identity:`.
+- NavigationMenu's agent rules state the keyboard contract: ArrowLeft/ArrowRight between triggers and links, ArrowDown opens the focused trigger's panel, Escape closes.
+
+### Fixed
+
+- HoverCard: a tap on the trigger clicks through on touch devices (the collapsed sidebar's icons did nothing on a tablet).
+- NumberField: Tab's select-all and a click's caret placement stay native.
 
 ## [0.1.0] - 2026-09-05
 

data/README.md

@@ -59,8 +59,8 @@ bin/rails g poetry:add <name>  # adds newly-shipped files, never overwrites
 ```
 
 And `rails g scaffold` itself can produce poetry-composed views — a
-DataTable index with sanitized URL state, Field-composed forms, and a
-matching controller — by installing the app-owned template overrides once:
+DataTable index with sanitized URL state, forms on the poetry form
+builder, and a matching controller — by installing the app-owned template overrides once:
 
 ```bash
 bin/rails g poetry:scaffold_templates

data/THIRD_PARTY_NOTICES.md

@@ -33,6 +33,35 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## Tailwind CSS
+
+- Source: https://github.com/tailwindlabs/tailwindcss (MIT)
+- `reset/reset.css` (the reset floor `poetry:install --no-preflight` vendors) is preflight, generated from the pinned tailwindcss binary with every selector wrapped in `:where()`
+
+```
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## Base UI
 
 - Source: https://github.com/mui/base-ui (MIT)

data/app/components/poetry/ui/combobox/component.rb

@@ -236,9 +236,12 @@ module Poetry
           "#{group_id}-heading"
         end
 
+        # The group's name flows through aria-labelledby; aria-hidden keeps
+        # the text from being read a second time as a stray child of the
+        # listbox.
         def heading_part
           content_tag(:div, @heading_text, "data-slot" => "combobox-label", "id" => heading_id,
-                                           "class" => Style.css(:label))
+                                           "aria-hidden" => "true", "class" => Style.css(:label))
         end
       end
 

data/app/components/poetry/ui/command/component.rb

@@ -207,10 +207,11 @@ module Poetry
         end
 
         # A styled heading, no ARIA role - the group points at it via
-        # aria-labelledby.
+        # aria-labelledby, and aria-hidden keeps the text from being read a
+        # second time as a stray child of the listbox.
         def heading_part
           content_tag(:div, @heading_text, "data-slot" => "command-group-heading", "id" => heading_id,
-                                           "class" => Style.css(:heading))
+                                           "aria-hidden" => "true", "class" => Style.css(:heading))
         end
       end
 

data/app/components/poetry/ui/context_menu/component.rb

@@ -135,6 +135,9 @@ module Poetry
         option :loop, :boolean, default: false, doc: "Wraps arrow-key movement past either end of the menu."
         option :long_press_delay, :integer, default: 700, doc: "Touch long-press duration in ms before the menu opens."
         option :disabled, :boolean, default: false, doc: "Inerts the surface - no gesture opens the menu."
+        option :content_class, :string,
+               doc: "Class merge seam for the menu panel (e.g. content_class: \"w-48\"). Root-level " \
+                    "class: styles the surface wrapper, not the panel."
         option :label, :string, doc: "The menu's accessible name (localized fallback when omitted)."
         option :focusable_surface, :boolean, default: false,
                                              doc: "Puts the surface in the tab order and advertises Shift+F10."
@@ -278,7 +281,7 @@ module Poetry
             "data-slot" => "context-menu-content", (open ? "data-open" : "data-closed") => "",
             # The initial placement (side: option; re-resolved live by popper).
             "data-side" => side.to_s, "data-align" => "start",
-            "class" => css(:content)
+            "class" => css(:content, class: content_class)
           }.merge(stimulus_attributes_for(:content))
           attrs["hidden"] = true unless open
           attrs

data/app/components/poetry/ui/dialog/component.rb

@@ -169,7 +169,7 @@ module Poetry
         # block--modifier tokens ARE the host's styling contract.
         # @api private
         def html_attributes
-          return super unless Poetry::Core::Config.current.css_mode == :tailwind
+          return super unless css_mode == :tailwind
 
           @html_attributes.merge(class: classnames(@html_attributes[:class]))
         end

data/app/components/poetry/ui/drawer/component.rb

@@ -142,6 +142,9 @@ module Poetry
         tool :open, description: "Open the drawer.", executes: :open, mutating: true
         tool :close, description: "Close the drawer.", executes: :close, mutating: true
 
+        # The inherited render checks, then the snap-point rules when
+        # snap_points: is given.
+        # @api private
         def before_render
           super
           validate_snap_points! if snap_points.present?

data/app/components/poetry/ui/dropdown_menu/component.rb

@@ -143,6 +143,10 @@ module Poetry
         option :loop, :boolean, default: false, doc: "Arrow-key navigation wraps from the last item back to the first."
         option :dir, :symbol, doc: "Reading direction; :rtl flips submenu sides and indicators."
         option :disabled, :boolean, default: false, doc: "Disables the menu trigger button."
+        option :content_class, :string,
+               doc: "Class merge seam for the menu panel - the panel opens at the trigger's width " \
+                    "(min 8rem), so content_class: \"w-56\" widens it. Root-level class: styles the " \
+                    "wrapper, not the panel."
 
         validates :side, inclusion: { in: SIDES }
         validates :align, inclusion: { in: ALIGNS }
@@ -272,7 +276,7 @@ module Poetry
             "data-slot" => "dropdown-menu-content", (open ? "data-open" : "data-closed") => "",
             # Initial placement, re-resolved live by popper on open.
             "data-side" => side, "data-align" => align,
-            "class" => css(:content)
+            "class" => css(:content, class: content_class)
           }.merge(stimulus_attributes_for(:content))
           attrs["hidden"] = true unless open
           attrs

data/app/components/poetry/ui/hover_card/component.rb

@@ -95,14 +95,15 @@ module Poetry
           end
           # The trigger handlers: pointerenter/leave pair
           # timers (touch excluded), focus opens immediately / blur closes,
-          # and the touchstart guard (a tap navigates, never focus-opens).
+          # and the pointerdown latch (a tap or click never focus-opens; the
+          # tap keeps its click, so it navigates).
           on :trigger do
             controller :hover_card do
               action :pointer_enter, on: :pointerenter
               action :pointer_leave, on: :pointerleave
               action :focus_open, on: :focus
               action :blur_close, on: :blur
-              action :touch_guard, on: :touchstart
+              action :pointer_down, on: :pointerdown
             end
             controller(:popper) { target :anchor }
           end

data/app/components/poetry/ui/menubar/component.rb

@@ -73,7 +73,7 @@ module Poetry
         renders_many :menus,
                      doc: "The top-level menus. Each takes with_trigger (the menu button) plus the family item " \
                           "slots (with_item, with_checkbox_item, with_radio_group, with_sub, with_separator, ...); " \
-                          "value: defaults to the menu's position.",
+                          "value: defaults to the menu's position; content_class: is the panel's class merge seam.",
                      renders: ->(**options) { Menu.new(bar: self, dir: dir, **options) }
 
         use_stimulus do
@@ -341,11 +341,12 @@ module Poetry
                       content_tag(:button, Poetry::Core::HTML::Attributes.merged(attrs, options)) { capture(&block) }
                     }
 
-        def initialize(bar:, value: nil, disabled: false, dir: nil, **extra_attributes)
+        def initialize(bar:, value: nil, disabled: false, dir: nil, content_class: nil, **extra_attributes)
           super(extra_attributes)
           @bar = bar
           @disabled = disabled
           @dir = dir
+          @content_class = content_class
           position = @bar.register_menu(self)
           @value = (value || "menu-#{position}").to_s
         end
@@ -419,7 +420,7 @@ module Poetry
             "data-slot" => "menubar-content", (open? ? "data-open" : "data-closed") => "",
             # Initial placement, re-resolved live by popper on open.
             "data-side" => "bottom", "data-align" => "start",
-            "class" => Style.css(:content)
+            "class" => Style.css(:content, class: @content_class)
           }.merge(stimulus_attributes(:popper) { |popper| popper.with_target(:content) })
           attrs["hidden"] = true unless open?
           content_tag(:div, attrs) { safe_join(items.map(&:to_s)) }

data/app/components/poetry/ui/menus.rb

@@ -226,11 +226,28 @@ module Poetry
 
         def call
           attrs = { "data-slot" => "#{family_slot_prefix}-group", "role" => "group" }
+          attrs["aria-labelledby"] = label_id if @labelled
           content_tag(:div, Poetry::Core::HTML::Attributes.merged(attrs, html_attributes)) { safe_join(items.map(&:to_s)) }
         end
 
         private
 
+        # A label inside a group names the group (aria-labelledby) and is
+        # aria-hidden, so its text is not read a second time as a stray child
+        # of the menu; a label outside any group stays plain text.
+        def label_part(**, &)
+          @labelled = true
+          super("id" => label_id, "aria-hidden" => "true", **, &)
+        end
+
+        def group_id
+          @group_id ||= poetry_instance_id("poetry-#{family_slot_prefix}-group")
+        end
+
+        def label_id
+          "#{group_id}-label"
+        end
+
         def menu_dir
           @dir
         end
@@ -311,9 +328,11 @@ module Poetry
                       end
                     }
 
-        def initialize(dir: nil, **extra_attributes)
+        # content_class: is the sub-panel's class merge seam (with_sub(content_class: "w-40")).
+        def initialize(dir: nil, content_class: nil, **extra_attributes)
           super(extra_attributes)
           @dir = dir
+          @content_class = content_class
         end
 
         def before_render
@@ -363,7 +382,7 @@ module Poetry
             "id" => content_id, "role" => "menu", "aria-orientation" => "vertical",
             "aria-labelledby" => trigger_id, "tabindex" => "-1",
             "data-slot" => "#{family_slot_prefix}-sub-content", "data-closed" => "", "hidden" => true,
-            "class" => family_style.css(:sub_content)
+            "class" => family_style.css(:sub_content, class: @content_class)
           }.merge(stimulus_attributes(:popper) { |popper| popper.with_target(:content) })
           content_tag(:div, attrs) { safe_join(items.map(&:to_s)) }
         end

data/app/components/poetry/ui/message_scroller/component.rb

@@ -9,6 +9,16 @@ module Poetry
       # a jump-to-latest button. Without JavaScript it is a plain
       # scrollable region, fully readable.
       #
+      # Opening position: a scroll container always opens at the top, so a
+      # transcript opening at the newest message would paint the oldest
+      # rows first and jump once the controller runs. For :end and
+      # :"last-anchor" the root and the viewport render
+      # data-pending-scroll; the viewport's dictionary hides it while the
+      # attribute is present (visibility, so layout exists for the scroll)
+      # and the controller clears it once the position lands, or at once
+      # for an empty transcript. Without JavaScript the hold is lifted
+      # (a scripting: none media rule), so the region stays readable.
+      #
       # The content element is the Turbo Stream append target (stable
       # dom id "<id>-messages"); rows are poetry_message_scroller_item
       # wrappers keyed by message id. History prepends keep the reading
@@ -92,14 +102,20 @@ module Poetry
                "data-scrollable" => "overflow exists - carries which edges have room " \
                                     "(start, end, or both as a space-separated pair)",
                "data-autoscrolling" => "a programmatic scroll is settling - the " \
-                                       "follow-bottom release is suppressed while set"
+                                       "follow-bottom release is suppressed while set",
+               "data-pending-scroll" => "the opening-position hold - rendered for " \
+                                        "default_scroll_position :end / :\"last-anchor\", " \
+                                        "cleared once the position lands (at once for an " \
+                                        "empty transcript)"
              }
         part "message-scroller-viewport", "The native scroll region (role=region, " \
                                           "focusable) - the controller mirrors the same " \
                                           "runtime attributes here",
              states: {
                "data-scrollable" => "overflow exists - the same edge tokens as the root",
-               "data-autoscrolling" => "a programmatic scroll is settling"
+               "data-autoscrolling" => "a programmatic scroll is settling",
+               "data-pending-scroll" => "the opening-position hold (the root's) - the " \
+                                        "dictionary hides the viewport while it is set"
              }
         part "message-scroller-content", "The row container and Turbo Stream append target " \
                                          "(stable dom id <id>-messages); role=log announces " \
@@ -120,6 +136,7 @@ module Poetry
             { "data-slot" => "message-scroller" }
               .merge(stimulus_attributes_for(:root))
               .merge(component_data_attributes)
+              .merge(pending_scroll_attributes)
           )
         end
 
@@ -129,7 +146,13 @@ module Poetry
             "class" => css(:viewport), "data-slot" => "message-scroller-viewport",
             "role" => "region", "tabindex" => "0",
             "aria-label" => t("poetry.message_scroller.region")
-          }.merge(stimulus_attributes_for(:viewport))
+          }.merge(stimulus_attributes_for(:viewport)).merge(pending_scroll_attributes)
+        end
+
+        # The opening-position hold (the class doc) - the server renders it so
+        # the first paint never shows the top of the thread.
+        def pending_scroll_attributes
+          %i[end last-anchor].include?(default_scroll_position) ? { "data-pending-scroll" => "" } : {}
         end
 
         # @api private
@@ -156,7 +179,8 @@ module Poetry
           }.merge(stimulus_attributes_for(:jump_button))
         end
 
-        private :root_attributes, :viewport_attributes, :content_attributes, :spacer_attributes, :button_attributes
+        private :root_attributes, :viewport_attributes, :content_attributes, :spacer_attributes, :button_attributes,
+                :pending_scroll_attributes
       end
     end
   end

data/app/components/poetry/ui/message_scroller/style.rb

@@ -16,8 +16,14 @@ module Poetry
         # (rightly) rejects classes no build can produce.
         base "relative flex size-full min-h-0 flex-col overflow-hidden group/message-scroller"
 
+        # data-pending-scroll:invisible = the opening-position hold: the
+        # viewport hides (layout intact) until the controller lands the
+        # opening position. The noscript pair lifts it when scripts are off -
+        # the plain scrollable region stays readable, this component's no-JS
+        # contract.
         element :viewport, "size-full min-h-0 min-w-0 scroll-fade-b scrollbar-thin scrollbar-gutter-stable " \
-                           "overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-none"
+                           "overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-none " \
+                           "data-pending-scroll:invisible noscript:data-pending-scroll:visible"
 
         element :content, "cn-message-scroller-content flex h-max min-h-full flex-col"
 

data/app/components/poetry/ui/navigation_menu/component.rb

@@ -30,27 +30,36 @@ module Poetry
           "Panel content is poetry_navigation_menu_link entries (active: marks the current page) - " \
           "never buttons; navigation navigates.",
           "This is a DISCLOSURE bar: Tab moves through it normally and nothing traps - do not " \
-          "wire menu/menuitem roles.",
+          "wire menu/menuitem roles. Keys: ArrowLeft/ArrowRight step between triggers and links, " \
+          "ArrowDown opens the focused trigger's panel (focus stays on the trigger; Tab enters it), " \
+          "Escape closes and returns focus to the trigger.",
           "Rich panels (title + description grids) want viewport: true - the shared morphing " \
           "card contains and sizes them; the default per-item mode suits simple link lists " \
           "(the top-nav block shows the viewport pattern)."
         ].freeze
 
-        # One declared bar entry - a link (href:) or a trigger + panel pair.
+        # One declared bar entry - a link (href:) or a trigger + panel pair
+        # (disabled: renders the trigger inert).
         # @api private
-        Entry = Data.define(:title, :value, :href, :panel)
+        Entry = Data.define(:title, :value, :href, :panel, :disabled)
 
         renders_many :items,
-                     doc: "The bar entries. with_item(title, value:) { panel } declares a trigger + panel; " \
-                          "with_item(title, href:) a top-level link (with_link is the shorthand).",
-                     renders: lambda { |title, value: nil, href: nil, &panel|
+                     doc: "The bar entries. with_item(title, value:) { panel } declares a trigger + panel " \
+                          "(disabled: true renders the trigger inert - native disabled plus data-disabled; hover " \
+                          "and click never open its panel); with_item(title, href:) a top-level link (with_link " \
+                          "is the shorthand).",
+                     renders: lambda { |title, value: nil, href: nil, disabled: false, &panel|
                        if href.nil? && panel.nil?
                          raise ArgumentError,
                                "NavigationMenu item #{title.inspect} needs href: (a link) or a panel block"
                        end
+                       if href && disabled
+                         raise ArgumentError,
+                               "NavigationMenu item #{title.inspect}: disabled: applies to a trigger, not a link"
+                       end
 
                        entries << Entry.new(title: title, value: value&.to_s || title.to_s.parameterize, href: href,
-                                            panel: panel)
+                                            panel: panel, disabled: disabled)
                        nil
                      }
 
@@ -116,7 +125,9 @@ module Poetry
                "data-popup-open" => "its panel is open (written with aria-expanded - the chevron " \
                                     "rotation hook)",
                "data-open" => "its panel is open (the controller writes both vocabularies)",
-               "data-closed" => "its panel is closed (written after the first close)"
+               "data-closed" => "its panel is closed (written after the first close)",
+               "data-disabled" => "disabled: true - inert (native disabled rides along; hover and " \
+                                  "click never open the panel, the arrows step over it)"
              }
         part "navigation-menu-content", "One item's panel - presence-animated; in viewport mode it is " \
                                         "adopted into the shared viewport on first activation",
@@ -203,11 +214,16 @@ module Poetry
 
         # @api private
         def trigger_attributes(entry)
-          {
+          attrs = {
             "type" => "button", "data-slot" => "navigation-menu-trigger",
             "aria-expanded" => "false", "aria-controls" => panel_id(entry),
             "class" => "#{css(:trigger)} group"
-          }.merge(stimulus_attributes_for(:trigger))
+          }
+          if entry.disabled
+            attrs["disabled"] = true # inert: no focus, no click
+            attrs["data-disabled"] = "" # the contract's styling hook
+          end
+          attrs.merge(stimulus_attributes_for(:trigger))
         end
 
         # @api private

data/app/components/poetry/ui/number_field/component.rb

@@ -59,7 +59,6 @@ module Poetry
               target :input
               action :keydown, on: :keydown
               action :input, on: :input
-              action :focus, on: :focus
               action :blur, on: :blur
             end
           end

data/app/components/poetry/ui/select/component.rb

@@ -626,12 +626,14 @@ module Poetry
         end
 
         # A styled heading, no ARIA role - the group points at it via
-        # aria-labelledby.
+        # aria-labelledby, and aria-hidden keeps the text from being read a
+        # second time as a stray child of the listbox (the name still flows
+        # through the reference).
         def label_part
           return if @label_text.blank?
 
           content_tag(:div, @label_text, "data-slot" => "select-label", "id" => label_id,
-                                         "class" => Style.css(:label))
+                                         "aria-hidden" => "true", "class" => Style.css(:label))
         end
       end
     end

data/app/components/poetry/ui/toast_trigger/component.rb

@@ -65,12 +65,13 @@ module Poetry
         def button_options
           wiring = { data: { slot: "toast-trigger" } }
                    .merge(stimulus_attributes_for(:root))
-                   .merge(component_data_attributes)
 
           # Caller attributes never clobber the trigger's wiring: both sides
           # flow through Attributes, so a host data-controller/action
-          # concatenates instead of silently killing fire-on-click.
-          { variant: variant, size: size }
+          # concatenates instead of silently killing fire-on-click. The
+          # Button root wears THIS component's identity through the
+          # identity: seam (the raw data-component is reserved).
+          { variant: variant, size: size, identity: self.class.component_title }
             .merge(Poetry::Core::HTML::Attributes.merged(wiring, html_attributes))
             .symbolize_keys
         end

data/app/controllers/poetry/ui/llms_controller.rb

@@ -21,7 +21,11 @@ module Poetry
         # The shared builder (the llms construction rule, extended): the
         # served text uses the exact registry construction the committed
         # file is generated from - helpers and blocks sections included.
-        Poetry::Core::LlmsText.new(registry: Poetry::Ui.registry)
+        # The app's own components ride along (their section follows the
+        # gem catalog), so an agent reading llms-full.txt sees their agent
+        # rules and helpers too.
+        Poetry::Core::LlmsText.new(registry: Poetry::Ui.registry,
+                                   host_registry: Poetry::Core::HostComponents.registry(root: Rails.root))
       end
     end
   end

data/app/helpers/poetry/ui/form_builder/type_inference.rb

@@ -17,7 +17,7 @@ module Poetry
         STRING_HEURISTICS = {
           /password/ => :password,
           /email/ => :email,
-          /\burl\b|_url\b/ => :url,
+          /\burl\b|_url\b|website|permalink/ => :url,
           /phone|\btel\b/ => :tel,
           /search|query/ => :search
         }.freeze
@@ -43,9 +43,11 @@ module Poetry
           COLUMN_TYPES.fetch(column, :string)
         end
 
+        # has_one_attached answers to <name>_attachment, has_many_attached
+        # to <name>_attachments; the other two are the classic uploaders.
         def attachment_attribute?(method)
-          object.respond_to?("#{method}_attachment") || object.respond_to?("#{method}_attacher") ||
-            object.respond_to?("remote_#{method}_url")
+          object.respond_to?("#{method}_attachment") || object.respond_to?("#{method}_attachments") ||
+            object.respond_to?("#{method}_attacher") || object.respond_to?("remote_#{method}_url")
         end
 
         def enum_attribute?(method)

data/app/helpers/poetry/ui/form_builder.rb

@@ -32,6 +32,9 @@ module Poetry
         "overrides the presence inference (aria only).",
         "Hints/placeholders resolve from poetry_form.* i18n (simple_form.* keys keep working " \
         "as a fallback); pass hint:/placeholder: to override.",
+        "Every builder field renders a Field, so wiring tests assert on its parts: the label is " \
+        "data-slot=field-label, the hint data-slot=field-description, the error data-slot=field-error, " \
+        "with the control inside (never a bare hint or description slot).",
         "f.submit renders a poetry Button with the Rails i18n label; f.fieldset(legend:)/" \
         "f.group lay out sections; boolean f.input renders the horizontal Field " \
         "(switch: true -> the setting row).",