nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.3

data/docs/customization.md

@@ -79,7 +79,15 @@ Color tokens need a light value, a no-JavaScript system fallback, and a dark val
 
 The media query matters when JavaScript or the appearance bootstrap is unavailable. When the runtime is active, `data-theme` is always the resolved `light` or `dark` appearance. `system` is a stored preference in `data-theme-preference`, not a third palette and never a `data-theme="system"` selector.
 
-Raised default Buttons have their own tokens, so their dark treatment can change without recoloring cards, dialogs, menus, or data-entry controls:
+Buttons can also preserve a product-specific shape without changing inputs or surfaces:
+
+```css
+:root {
+  --nk-button-radius: var(--nk-radius-full);
+}
+```
+
+Raised default Buttons have their own color tokens, so their dark treatment can change without recoloring cards, dialogs, menus, or data-entry controls:
 
 ```css
 @media (prefers-color-scheme: dark) {
@@ -187,7 +195,7 @@ Treat related tokens as a system:
 - Accent changes usually set `--nk-color-primary`, `--nk-color-primary-foreground`, and `--nk-color-focus` for both appearances. The default hover value is derived automatically; set `--nk-color-primary-hover` only when the derived color is unsuitable.
 - Neutral changes should coordinate canvas, surface, elevated, foreground, muted, border, and neutral-content pairs for both appearances.
 - Default Button changes use the `--nk-button-default-*` tokens. They are separate from `--nk-color-surface` so a raised neutral action can change without recoloring inputs, cards, dialogs, and menus.
-- Radius changes should move `--nk-radius-xs` through `--nk-radius-xl` together. Leave `--nk-radius-full` alone unless pills and circular controls should stop being fully rounded.
+- Radius changes should move `--nk-radius-xs` through `--nk-radius-xl` together. Leave `--nk-radius-full` alone unless pills and circular controls should stop being fully rounded. Set `--nk-button-radius` when buttons intentionally use a distinct shape, such as a pill treatment, without changing inputs and surfaces.
 - Density changes should coordinate `--nk-space` with all five control-height tokens. Changing one component's internal gap is not a public theme contract.
 - Font changes normally set `--nk-font-sans`; set `--nk-font-mono`, text sizes, line heights, or weights only when the whole type system calls for it.
 
@@ -449,7 +457,10 @@ import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading";
 eagerLoadControllersFrom("controllers", application);
 ```
 
-This registers Nitro's `controllers/nk/*` modules together with application controllers. Without importmap, Ruby and CSS still work, but a bundler-based application must expose and register those Stimulus modules itself. Nitro Kit ships no third-party JavaScript runtime, and Nitro Kit 2.0 has no JavaScript-package entrypoint.
+This registers Nitro's `controllers/nk/*` modules together with application controllers. Without importmap, server-rendered HTML and CSS remain available, but controller-dependent behavior and compatibility bridges are unavailable unless a bundler-based application exposes and registers those Stimulus modules itself. Nitro Kit ships no third-party JavaScript runtime, and Nitro Kit 2.0 has no JavaScript-package entrypoint.
+
+For the resulting behavior when those modules are not registered, use the
+canonical no-JavaScript matrix in [`browser_support.md`](browser_support.md).
 
 ## Optional Tailwind CSS v4 adapter
 
@@ -471,7 +482,7 @@ Use `@theme inline` when a Tailwind theme variable references another custom pro
 
 ## Public token reference
 
-The following 84 variables are the complete public token set. Theme-independent tokens are declared on `:root`. Appearance tokens have light, dark, and system-fallback values. Derived tokens have defaults expressed in terms of other public tokens and remain overrideable.
+The following 85 variables are the complete public token set. Theme-independent tokens are declared on `:root`. Appearance tokens have light, dark, and system-fallback values. Derived tokens have defaults expressed in terms of other public tokens and remain overrideable.
 
 ### Typography
 
@@ -516,17 +527,18 @@ The following 84 variables are the complete public token set. Theme-independent
 
 ### Shape, borders, and focus
 
-| Token               | Role                                |
-| ------------------- | ----------------------------------- |
-| `--nk-radius-xs`    | Extra-small corner radius.          |
-| `--nk-radius-sm`    | Small corner radius.                |
-| `--nk-radius-md`    | Default control corner radius.      |
-| `--nk-radius-lg`    | Large surface corner radius.        |
-| `--nk-radius-xl`    | Extra-large overlay corner radius.  |
-| `--nk-radius-full`  | Fully rounded pills and circles.    |
-| `--nk-border-width` | Default border and separator width. |
-| `--nk-focus-width`  | Focus-ring width.                   |
-| `--nk-focus-offset` | Focus-ring offset.                  |
+| Token                | Role                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| `--nk-radius-xs`     | Extra-small corner radius.                                                                 |
+| `--nk-radius-sm`     | Small corner radius.                                                                       |
+| `--nk-radius-md`     | Default control corner radius.                                                             |
+| `--nk-radius-lg`     | Large surface corner radius.                                                               |
+| `--nk-radius-xl`     | Extra-large overlay corner radius.                                                         |
+| `--nk-radius-full`   | Fully rounded pills and circles.                                                           |
+| `--nk-button-radius` | Optional Button-only radius override; the default `initial` preserves size-specific radii. |
+| `--nk-border-width`  | Default border and separator width.                                                        |
+| `--nk-focus-width`   | Focus-ring width.                                                                          |
+| `--nk-focus-offset`  | Focus-ring offset.                                                                         |
 
 ### Elevation and motion
 

data/docs/hotwire.md

@@ -16,7 +16,9 @@ responses. Hotwire transports server-rendered HTML between those boundaries.
 
 Do not copy Nitro Kit controllers into the application. Do not add files under
 `app/javascript/controllers/nk`; consume the `nk--*` controllers packaged by
-the installed gem.
+the installed gem. For browser-sensitive interactions, follow
+[`browser_support.md`](browser_support.md); Nitro owns compatibility bridges for
+its own components.
 
 ## Response matrix
 
@@ -30,6 +32,10 @@ the installed gem.
 Use `dom_id` or one named constant for a frame. The show, edit, invalid,
 success, and cancel responses must preserve that identifier.
 
+An HTML response branch preserves the request path when Turbo is unavailable;
+it is not a blanket guarantee that every surrounding component operates
+without JavaScript.
+
 ## Forms and application Stimulus
 
 Let Turbo submit real Rails forms. Use `data-turbo-submits-with` to opt a Button
@@ -38,7 +44,11 @@ immediately; `submission_indicator: :spinner` additionally reveals an indicator
 after 1 second and lets the Button expand to fit it. Use `data-turbo-confirm` for
 compact destructive confirmation.
 Reviewed destructive flows may compose `DangerZone` and `Dialog`, but the
-dialog must still submit a real Rails form.
+dialog must still submit a real Rails form. `data-turbo-confirm` is a Turbo
+enhancement, while an ordinary server-owned review route is the no-JavaScript
+confirmation path; neither an HTML response branch nor a form inside a closed
+dialog supplies that interaction by itself. See the canonical classifications
+in [`browser_support.md`](browser_support.md).
 
 Keep application controllers small, declarative, and disposable. For a
 self-submitting control, the complete controller can be:
@@ -68,7 +78,9 @@ permanent.
 
 Clean ephemeral UI before Turbo caches the page. Nitro Kit controllers own
 their own cache and reconnect behavior; application controllers must do the
-same for application-owned state.
+same for application-owned state. `nk--dialog` closes an open Dialog, Sheet, or
+CommandPalette on `turbo:before-cache`; reconnecting does not install listeners
+or retain a mirrored open flag.
 
 ## Frame escape and recovery
 

data/docs/initialization_prompt.md

@@ -7,7 +7,11 @@ APIs or examples.
    `2.`.
 2. Read `docs/agent_guide.md` from that installed gem, then read the locally
    installed `nitro-kit-rails`, `nitro-kit-hotwire`, and `nitro-kit-ui` skills.
-3. Inspect the application before editing. Preserve established application
+3. Inspect the application before editing. Inventory user flows, every rendered
+   button treatment (including application-owned `.btn` classes and native Rails
+   helpers), joined controls, and the existing semantic color, focus, radius,
+   density, and typography tokens. Capture representative wide and narrow
+   screenshots before changing markup. Preserve established application
    conventions unless they conflict with the requested Nitro Kit 2 setup.
 4. Ensure an application base Phlex component includes `NitroKit` once and
    product components inherit from it.
@@ -25,11 +29,32 @@ APIs or examples.
 8. Use ordinary Rails routes, models, forms, and server-rendered HTML. Follow
    the installed Rails and Hotwire guidance for new work. During a migration,
    replace an existing control only when Nitro Kit 2 has a genuine semantic
-   and behavioral equivalent. Otherwise preserve it as application-owned
-   Rails and semantic HTML; never downgrade specialized behavior or retain
-   copied Nitro Kit 1.x source as the fallback.
-9. Run `bin/rails nitro_kit:doctor`, fix actionable failures, and run the
-   application's relevant tests.
+   and behavioral equivalent. Preserve compound ownership: use `ButtonGroup`
+   for joined actions and `ControlGroup` for joined inputs, addons, and buttons
+   instead of rebuilding their geometry with a raw flex wrapper. Otherwise
+   preserve the control as application-owned Rails and semantic HTML; never
+   downgrade specialized behavior or retain copied Nitro Kit 1.x source as the
+   fallback. Preserve strict component boundaries: route native attributes
+   through `html:`, `aria:`, or `data:`, explicitly name icon-only Buttons and
+   triggers, and give custom `form.field` blocks explicit labels.
+9. Translate the application's existing semantic theme into documented public
+   `--nk-*` tokens. Preserve primary, focus, danger, neutral, font, density, and
+   radius decisions rather than selecting visually similar raw palette values.
+   Use `--nk-button-radius` when buttons intentionally have a different shape
+   from inputs and surfaces.
+10. Run `bin/rails nitro_kit:doctor`, fix actionable failures, and run the
+    application's relevant tests plus the generated upgrade smoke tests. When
+    the application uses strict i18n, render representative forms with
+    `ActiveModel::Translation.raise_on_missing_translations` enabled. Doctor
+    inventories migration work; a clean result is not runtime or visual
+    verification.
+11. Compare the same representative flows across the dated matrix in
+    `docs/browser_support.md`, including Mobile Safari where available, at wide
+    and narrow widths. Exercise keyboard focus and inspect computed styles for missing
+    application classes, stacked Button content, broken compound corners,
+    double focus rings, clipping, and theme drift. Re-audit rendered native
+    buttons, `button_tag`, `submit_tag`, and application-owned button classes
+    before declaring the migration complete.
 
 Report what you changed, any existing convention you deliberately preserved,
 any unsupported control recorded as a Nitro Kit coverage gap, and any warning

data/docs/migration_1_to_2.md

@@ -4,12 +4,12 @@ Treat a 1.x migration as a product-flow review, not a helper rename. Nitro Kit
 2 deliberately removed copied components, `nk_*` helpers, application-owned
 `controllers/nk`, and unrestricted utility-class customization.
 
-## Install the 2.0 alpha before migrating
+## Install the 2.0 prerelease before migrating
 
-Add the 2.0 alpha prerelease to the application's Gemfile:
+Add the 2.0 prerelease to the application's Gemfile:
 
 ```ruby
-gem "nitro_kit", "2.0.0.alpha.2"
+gem "nitro_kit", "2.0.0.alpha.3"
 ```
 
 Bundler records the exact released version in `Gemfile.lock`; commit `Gemfile`
@@ -22,14 +22,19 @@ rather than a moving Git branch.
 ## Inventory behavior before editing
 
 1. List every `nk_*` helper, `NitroKit::*` component, copied Nitro source file,
-   and `controllers/nk` controller.
+   `controllers/nk` controller, rendered native or Rails button helper, and
+   application-owned button class such as `.btn`.
 2. Group usage by user flow: authentication, settings, collection browsing,
    mobile navigation, editing, destructive actions, notifications, and
    copy/share controls.
 3. Record behavior that must survive: native element, submitted method and
    parameters, Turbo target, accessible name and description, focus behavior,
    narrow-screen presentation, empty/error state, and visual density.
-4. Capture representative wide and narrow screenshots before conversion.
+4. Inventory the existing semantic primary, focus, danger, neutral, font,
+   density, and radius decisions. Translate those roles to public `--nk-*`
+   tokens rather than choosing similar raw palette values. Record separately
+   when buttons use a distinct shape from inputs and surfaces.
+5. Capture representative wide and narrow screenshots before conversion.
 
 If the Nitro Kit MCP catalog is connected, search it by workflow after this
 inventory — for example `mobile transcript navigation`, `settings form`, or
@@ -46,11 +51,12 @@ Map each flow to the highest-level matching 2.x component first:
 | Sign-in or recovery card                | `AuthShell`                             |
 | Application navigation                  | `AppShell`, `AppNavigation`             |
 | Mobile contextual navigation or details | `Sheet`                                 |
-| Settings screen                         | `SettingsLayout`, `FormSection`         |
+| Settings screen                         | `SettingsLayout`, `SettingsSection`     |
 | Empty collection card                   | `EmptyState`                            |
 | Data collection                         | `DataSection`, `Table`, `PaginationBar` |
 | Destructive settings                    | `DangerZone`, `Dialog`, `ButtonTo`      |
 | Joined copy or filter controls          | `ControlGroup`                          |
+| Joined action controls                  | `ButtonGroup`                           |
 
 Only then replace remaining atoms. Common direct mappings include:
 
@@ -279,9 +285,11 @@ supported by the host's Rails Minitest and system-test setup and prints setup
 guidance for skipped files. The tests use the currently bundled gem and cover
 the shared upgrade boundary — browser-submitted Turbo validation and mutation,
 Dialog and Sheet, layout-owned Rails flash, Turbo Frame identity, redirects,
-and post-mutation Phlex rendering. Their collision-checked route exists only
-during each test and is restored afterward; they add no production route or
-component source. Keep application-specific migration tests for inventoried
+and post-mutation Phlex rendering. Their route is prepended only during each
+test, so host catch-all routes remain compatible; an exact GET or PATCH route
+at the same path is still rejected rather than masked. The route is restored
+afterward and adds no production route or component source. Keep
+application-specific migration tests for inventoried
 product behavior alongside them.
 
 The endpoint deliberately inherits `ApplicationController` callbacks. If the
@@ -291,20 +299,52 @@ and account-selection helpers used by ordinary integration and system tests.
 Extend those application-owned classes rather than changing gem test support
 or skipping host callbacks.
 
-Run focused request and component tests, then compare the converted flows in a
-browser at wide and narrow widths. Exercise keyboard focus, dialogs and sheets,
+Run focused request and component tests, then compare the converted flows
+across the dated matrix in `docs/browser_support.md`, including Mobile Safari
+where available, at wide and narrow widths. Exercise keyboard focus, dialogs and sheets,
 Turbo submissions, errors, empty states, light/dark appearance, and dense
-metadata. A green request suite does not prove that a tooltip, off-canvas
+metadata. Inspect computed styles for missing application classes, stacked
+Button content, broken compound corners, double focus rings, clipping, and
+theme drift. A green request suite does not prove that a tooltip, off-canvas
 panel, interactive Card treatment, or responsive composition survived.
 
 Finish by deleting copied components, helpers, and controllers; run
 `bin/rails nitro_kit:doctor`; and record every remaining application-owned
-fallback as either intentional product UI or a Nitro Kit coverage gap.
-
-Doctor inventories only concrete Nitro Kit 1.x conventions: `nk_*` helpers,
+fallback as either intentional product UI or a Nitro Kit coverage gap. Use
+`bin/rails nitro_kit:doctor --format=json` when migration automation needs
+stable `status`, `label`, and `detail` fields.
+
+Before declaring the migration complete, search for every
+`desperately_need_a_class:` use and review each one. Aim for zero. Move layout,
+spacing, width, responsive positioning, and application colors to an
+application-owned wrapper; use documented component options and native
+attributes for semantics and state; accept Nitro defaults where the difference
+is incidental; and keep specialized controls or navigation application-owned
+when Nitro is not the right abstraction. Remove generic class forwarding from
+shared builders. A scoped wrapper rule may target ordinary descendant elements
+when the application truly owns that layout behavior, such as fixed table
+layout. Retain the escape only when a named external integration actually
+requires a class hook, and document why.
+
+For such a retained integration, `desperately_need_a_class:` accepts Rails-style
+strings, symbols, nested arrays, or conditional hashes without manual
+`compact.join(" ")` formatting. A Tailwind application may use its own
+Tailwind-aware merger when that hook needs conflicting utility classes
+resolved. Nitro does not require the dependency because its own component CSS
+is static and classless.
+
+Doctor inventories concrete Nitro Kit 1.x conventions: `nk_*` helpers,
 generated files under `app/components/nitro_kit`, controllers under
-`app/javascript/controllers/nk`, the old Floating UI and combobox packages,
-and `tailwind_merge`. Every finding includes a file and replacement. Its
+`app/javascript/controllers/nk`, and the old Floating UI and combobox packages.
+When application CSS defines a `.btn` treatment, Doctor
+also records rendered `btn` class usages as application-owned review work; it
+does not assume every specialized control should become a Nitro Button. Doctor
+also uses Ruby syntax trees to catch provable 2.0 runtime violations: direct
+`id:` keywords on Table compound methods and statically icon-only
+`NitroKit::Button`, Dropdown trigger, and Sheet trigger declarations without an
+accessible name. Rendering remains
+the final authority for dynamic wrappers and delegated component declarations.
+Every finding includes a file and replacement or review instruction. Its
 disposition is:
 
 - `migrated` — no remaining occurrence in that category.
@@ -314,5 +354,7 @@ disposition is:
   an application namespace, not as a Nitro shadow.
 
 The inventory deliberately does not guess from generic component, JavaScript,
-or dependency names. Review application-owned product behavior separately and
-keep its migration record with the application.
+or dependency names beyond a button treatment the application itself defines.
+Review application-owned product behavior separately and keep its migration
+record with the application. Re-audit native buttons, Rails button helpers, and
+application-owned button classes after Doctor is otherwise clean.

data/docs/patterns/application_foundation.md

@@ -15,11 +15,11 @@ replaced later.
 - One wrapper immediately inside `shell.main` owns responsive page padding for
   every route; the shell owns viewport height and scrolling.
 - Infrequent account destinations go after `navigation.spacer`; settings
-  compose with `SettingsLayout` and plain `FormSection` regions.
+  compose with `SettingsLayout` and plain `SettingsSection` regions.
 - When destination count warrants search, compose one `CommandPalette` in the
   shell and render only routes the current membership may visit.
 - Centralize cross-cutting feedback in one flash-driven toast region rendered
-  by the layout.
+  by the layout, and set the document language on the root `html` element.
 
 ## Use memberships from the first user
 
@@ -46,7 +46,9 @@ primary destinations in `AppNavigation`; place route titles and persistent
 basic actions in the shell `Toolbar`. One wrapper immediately inside
 `shell.main` owns responsive page padding for every route. The topbar and
 sidebar header should use the shell's shared height and border tokens rather
-than independent padding guesses.
+than independent padding guesses. At narrow widths, allow trailing actions to
+stack below the Back affordance and title so neither the title nor persistent
+actions are clipped.
 
 Put infrequent account navigation after `navigation.spacer`, near the account
 controls at the bottom of the sidebar:
@@ -91,7 +93,7 @@ its major regions.
 
 Use `SettingsLayout` inside the normal shell main region. Its navigation lists
 stable subsections such as Profile, Notifications, Appearance, and Password;
-its content renders the selected form. Use `FormSection` for genuinely distinct
+its content renders the selected form. Use `SettingsSection` for genuinely distinct
 form regions and ordinary whitespace or dividers between them.
 
 Render subsection destinations as links and mark the active link with

data/docs/patterns/crud_resource.md

@@ -17,6 +17,8 @@ and their tests together.
   `DataSection`, Card, and caption.
 - Child routes add one compact icon Back link before the title instead of a
   trailing Cancel action.
+- At narrow widths, trailing actions stack below the Back affordance and title;
+  do not clip the title or hide persistent actions to keep the header short.
 - One responsive padding rule on the main wrapper owns the page gutter;
   data-heavy hybrid CRUD content uses the full available width.
 
@@ -31,7 +33,8 @@ Put a `Toolbar` in `shell.topbar`. Its leading region contains the route's one
 `h1`; its trailing region contains basic actions such as New, Edit, Cancel,
 Save, Publish, or View. A Button outside a form can submit it through the
 native `form:` attribute. This keeps the same action hierarchy on narrow and
-wide screens without custom JavaScript.
+wide screens without custom JavaScript. Nitro Kit stacks the regions at narrow
+widths so a Back affordance, long title, and several actions remain legible.
 
 ```ruby
 AppShell(id: "admin", layout: :hybrid) do |shell|
@@ -70,7 +73,7 @@ Do not add viewport height or another outer padding rule to `admin-main`; the
 shell owns viewport geometry and the wrapper owns the one page gutter. Use the
 same shell and gutter on team administration and settings routes.
 Place a bottom-anchored Settings destination after `AppNavigation#spacer`, then
-compose settings subsections with `SettingsLayout` and plain `FormSection`
+compose settings subsections with `SettingsLayout` and plain `SettingsSection`
 regions. Settings destinations are links with `aria-current`, not action
 Buttons. Read `application_foundation.md` for the complete application frame.
 
@@ -90,7 +93,7 @@ renders its table and pagination directly. Use `DataSection` when a page has
 multiple independently named datasets. At zero records, replace the data region
 with one intentional `EmptyState`; keep the primary New action in the toolbar.
 
-A new or edit page begins with `FormSection`. Use one form component for new,
+A new or edit page begins with `SettingsSection`. Use one form component for new,
 edit, and invalid renders. Put the primary submit in the toolbar by setting the
 button's `form:` to the form's stable DOM ID. Invalid submissions render the
 same model and form with `422 Unprocessable Entity`. The toolbar owns that

data/docs/patterns/destructive_action.md

@@ -2,6 +2,11 @@
 
 Use a native Nitro Dialog when the user needs to review impact or type confirmation. The dialog only owns accessible disclosure and focus behavior; a real Rails form owns the destructive request.
 
+Nitro keeps the declarative dialog command as the native path and supplies a
+capability-detected JavaScript bridge for supported browsers that lack Invoker
+Commands. The bridge changes only disclosure; it never intercepts or recreates
+the form request.
+
 ## Summary
 
 - Use a native Nitro `Dialog` only when the user must review impact or type a
@@ -100,6 +105,26 @@ end
 
 Do not stack `turbo_confirm` inside a Dialog. Choose one confirmation surface.
 
+## Browser fallback
+
+The reviewed flow depends on Dialog opening in the user's browser. Nitro owns
+the compatibility path when its packaged controller is installed, but no
+client-side dialog can guarantee confirmation when both JavaScript and the
+required native dialog invocation API are unavailable. Applications that must
+support that case should link to a server-rendered review route with an ordinary
+deletion form.
+
+`data-turbo-confirm` is a compact Turbo enhancement, not that no-JavaScript
+fallback. Without Turbo it does not display a confirmation, although the real
+form can still submit. When confirmation must be unavoidable, make review a
+server-owned step rather than stacking both client confirmation surfaces.
+
 ## Tests
 
 Request-test authorization, deletion, 303 redirect, and flash. System-test the dialog only when the reviewed flow matters: trigger opens it, Cancel closes and restores focus, and the destructive submit removes the record.
+
+The successful `DELETE` response must redirect with `303 See Other`, including
+when Turbo submits the form. Without JavaScript the real form still provides a
+request path, but a form placed only inside a closed dialog is reachable only
+where Invoker Commands are supported; provide an ordinary server-rendered link
+to a review page when deletion must remain reachable across that baseline.

data/docs/patterns/resource_form.md

@@ -37,7 +37,7 @@ module UI
     end
 
     def view_template
-      render NitroKit::FormSection.new(
+      render NitroKit::SettingsSection.new(
         title: project.persisted? ? "Edit project" : "New project",
         description: "Project details are visible to every workspace member."
       ) do |section|

data/docs/rails_conventions.md

@@ -50,6 +50,9 @@ public.
 ## Use ordinary Rails responses
 
 - Use `form_with` and `NitroKit::FormBuilder` for model-backed forms.
+- Treat `month_field` and `week_field` as progressive enhancement. Validate
+  `YYYY-MM` and `YYYY-Www`, ranges, and increments in the model; use an
+  application-owned Select with explicit options when exact selection matters.
 - Redirect successful non-GET submissions with `status: :see_other`.
 - Render the same invalid model with `status: :unprocessable_entity`.
 - Keep an HTML response for every Turbo-enhanced flow.
@@ -68,7 +71,7 @@ Do not repeat the route title in a `PageHeader`, section heading, card title,
 and table caption. Use `PageHeader` inside an application shell only when the
 page needs a genuinely content-led introduction beyond the toolbar title. A
 single-table index renders the table directly. A form page begins with the
-actual `FormSection`. A detail page begins with status or metadata. Use a Card
+actual `SettingsSection`. A detail page begins with status or metadata. Use a Card
 only for a bounded object that needs a surface, never as the automatic wrapper
 for every region.
 

data/docs/rails_integration.md

@@ -4,10 +4,10 @@ Nitro Kit 2.0 uses Rails where Rails owns important application semantics: model
 
 ## Installation and assets
 
-Add the 2.0 alpha prerelease to the application's Gemfile:
+Add the 2.0 prerelease to the application's Gemfile:
 
 ```ruby
-gem "nitro_kit", "2.0.0.alpha.2"
+gem "nitro_kit", "2.0.0.alpha.3"
 ```
 
 Bundler records the exact released version in `Gemfile.lock`; commit `Gemfile`
@@ -53,7 +53,7 @@ stylesheet_link_tag("lexxy", "nitro_kit", "application", data: { turbo_track: "r
 There is no component source-copy step. Re-run the generator after upgrading
 the gem, then run `bin/rails nitro_kit:doctor`. Doctor fails for a missing,
 duplicate, or misordered bootstrap or stylesheet entry and reports the exact
-repair.
+repair. Use `--format=json` for structured automation output.
 
 Install a focused upgrade acceptance flow separately:
 
@@ -67,8 +67,9 @@ The generator creates each test only when its path is absent and its host
 prerequisite exists: `test/test_helper.rb` for integration coverage and
 `test/application_system_test_case.rb` for browser coverage. It prints an
 actionable message for unsupported pieces and never overwrites
-application-owned coverage. Using the currently bundled gem, the tests install
-a collision-checked route only for each test, then restore host routing. The
+application-owned coverage. Using the currently bundled gem, the tests prepend
+a route only for each test, then restore host routing. Catch-all routes remain
+compatible, while an exact GET or PATCH collision is rejected. The
 endpoint inherits the host `ApplicationController` and renders through the
 application layout, so Nitro CSS, the appearance bootstrap, host JavaScript and
 CSP handling remain in the exercised path. Coverage includes browser-submitted
@@ -108,9 +109,24 @@ the gem controller, because that would bypass the integration under test.
 
 ## Stimulus and importmap
 
-Enhanced components use gem-owned Stimulus controllers, including `nk--app-shell`, `nk--appearance`, `nk--avatar`, `nk--checkable`, `nk--combobox`, `nk--dropdown`, `nk--dropzone`, `nk--progressive-image`, `nk--tabs`, `nk--toast`, and `nk--tooltip`.
-
-Accordion and Dialog are controller-free: native `details` grouping and declarative `command`/`commandfor` own their complete interaction. Dropdown uses native Popover as its source of truth and adds only menu keyboard focus; Tooltip uses CSS for hover/focus and JavaScript only for Escape dismissal. Nitro does not promise dialog light dismiss.
+Enhanced components use gem-owned Stimulus controllers, including `nk--app-shell`, `nk--appearance`, `nk--avatar`, `nk--checkable`, `nk--combobox`, `nk--dialog`, `nk--dropdown`, `nk--dropzone`, `nk--progressive-image`, `nk--tabs`, `nk--toast`, and `nk--tooltip`.
+
+Accordion disclosure is controller-free. Its shared `name` is the native
+single-group authority; browsers without named-details grouping retain full
+disclosure but have the documented reduced, independently-open single-mode
+baseline. Dialog and Sheet prefer declarative
+`command`/`commandfor`, while `nk--dialog` owns backdrop and cancel policy. The
+controller checks each invoker's reflected relationship and uses
+`HTMLDialogElement.showModal()` or `close()` only when the native command will
+not run. CommandPalette uses the same bridge instead of replacing the native
+path. Without JavaScript, these controls still require native Invoker Commands.
+Server-rendered content inside a closed overlay is therefore not itself a
+JavaScript-free fallback; critical content needs an ordinary server review
+route. The canonical classification matrix is in
+[`browser_support.md`](browser_support.md).
+Dropdown uses native Popover as its source of truth and adds menu keyboard focus
+and positioning; Tooltip uses CSS for hover/focus and JavaScript only for Escape
+dismissal. See the [browser support policy](browser_support.md).
 
 When `importmap-rails` is present, the engine adds its importmap and asset paths automatically. The application must still install Stimulus and provide the normal controller loader:
 
@@ -121,7 +137,10 @@ import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading";
 eagerLoadControllersFrom("controllers", application);
 ```
 
-Nitro Kit packages no third-party JavaScript. Accordion, Dialog, date inputs, and Switch use native browser behavior and need no controllers.
+Nitro Kit packages no third-party JavaScript. Accordion disclosure, date inputs,
+and Switch use native browser behavior. Dialog and Sheet mount their packaged
+controller for dismissal policy, Turbo cache cleanup, and the feature-detected
+Invoker Commands bridge.
 
 The engine deliberately boots when importmap is absent. In that configuration, Ruby and CSS remain available, but automatic JavaScript registration does not: a bundler-based application must expose and register the controller modules itself. Nitro Kit 2.0 does not ship a JavaScript-package entrypoint.
 
@@ -208,11 +227,11 @@ render NitroKit::CommandPalette.new(id: "workspace-search", label: "Search works
 end
 ```
 
-The application remains responsible for authorization and must render only destinations the current user may visit. Native dialog commands and links provide the baseline; Stimulus adds filtering and the Command-K or Control-K shortcut. Use `shortcut: false` for any additional palette on the same document so only one component owns the global shortcut.
+The application remains responsible for authorization and must render only destinations the current user may visit. Stimulus adds filtering and the Command-K or Control-K shortcut. Without JavaScript, the trigger and destination links are available only where declarative dialog commands are supported. Use `shortcut: false` for any additional palette on the same document so only one component owns the global shortcut.
 
 ### Server-rendered command palette results
 
-For a large or dynamic destination set, pass a GET endpoint through `search_url:`. Keep a useful authorized set in the declaration block: those links are the no-JavaScript baseline and the immediate first render.
+For a large or dynamic destination set, pass a GET endpoint through `search_url:`. Keep a useful authorized set in the declaration block: those links are the immediate first render and the no-JavaScript baseline in browsers with declarative dialog commands.
 
 ```ruby
 render NitroKit::CommandPalette.new(
@@ -350,6 +369,15 @@ The complete builder surface includes:
 - `submit` and `button`.
 - Rails-shaped color, date, datetime, email, file, month, number, password, phone/telephone, range, rich text, search, text, textarea, time, URL, and week fields.
 
+`month_field` and `week_field` emit native `month` and `week` input types as
+progressive enhancement. Some supported desktop browsers expose ordinary text
+entry, and older iOS Safari releases lack week selection, so do not rely on a
+picker, browser normalization, or `min`, `max`, and `step`. Validate `YYYY-MM`
+and `YYYY-Www` plus domain range and increment rules on the model. If the user
+must choose from an exact bounded set, render `form.field(..., as: :select,
+options: ...)` with application-owned options. Nitro does not ship a generic
+datepicker for this case.
+
 `submit` renders a primary submit Button named `commit`, and `button` defaults
 to `type: :submit`. The Rails helpers Nitro does not style — `label`,
 `collection_select`, `grouped_collection_select`, `collection_radio_buttons`,

data/lib/generators/nitro_kit/upgrade_smoke_tests_generator.rb

@@ -9,6 +9,12 @@ module NitroKit
         prerequisite: "test/test_helper.rb",
         remedy: "Install Rails' Minitest test infrastructure, then rerun this generator.",
         content: <<~RUBY
+        # Generated by Nitro Kit as a host-integration regression check.
+        #
+        # This exercises the bundled Nitro Kit through this application's layout,
+        # ApplicationController callbacks, Rails forms, Turbo, and flash rendering.
+        # It does not replace acceptance tests for the application's migrated flows.
+
         require "test_helper"
         require "nitro_kit/upgrade_smoke_test"
 
@@ -26,6 +32,12 @@ module NitroKit
         prerequisite: "test/application_system_test_case.rb",
         remedy: "Run `bin/rails generate system_test`, configure a browser driver, then rerun this generator.",
         content: <<~RUBY
+        # Generated by Nitro Kit as a host-integration regression check.
+        #
+        # This exercises the bundled Nitro Kit through this application's layout,
+        # ApplicationController callbacks, Rails forms, Turbo, and browser runtime.
+        # It does not replace acceptance tests for the application's migrated flows.
+
         require "application_system_test_case"
         require "nitro_kit/upgrade_smoke_test"
 

data/lib/nitro_kit/installation.rb

@@ -152,12 +152,17 @@ module NitroKit
       end
 
       def stimulus_loader_check
-        path = application_root.join("app/javascript/controllers/index.js")
-        ready = path.exist? && path.read.include?("eagerLoadControllersFrom")
+        javascript = application_root.glob("app/javascript/**/*.{js,ts}").select(&:file?).map(&:read)
+        loader = if javascript.any? { _1.include?("eagerLoadControllersFrom") }
+          "eager controller loading"
+        elsif javascript.any? { _1.match?(/\bapplication\.register\s*\(/) }
+          "explicit controller registration"
+        end
+
         Check.new(
-          status: ready ? :pass : :warn,
+          status: loader ? :pass : :warn,
           label: "Stimulus loader",
-          detail: ready ? "eager controller loading is configured" : "verify the application's controller registration"
+          detail: loader ? "#{loader} is configured" : "verify the application's controller registration"
         )
       end