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

data/app/javascript/controllers/nk/dropdown_controller.js

@@ -7,8 +7,13 @@ import {
 export default class extends Controller {
   static targets = ["trigger", "content", "item"];
 
+  connect() {
+    this.outsidePointerDown = this.outsidePointerDown.bind(this);
+  }
+
   disconnect() {
     this.stopPositioning?.();
+    this.stopOutsidePointerFallback();
   }
 
   openFromKeyboard(event) {
@@ -36,10 +41,12 @@ export default class extends Controller {
   focusOpened(event) {
     if (event.newState === "open") {
       this.startPositioning();
+      this.startOutsidePointerFallback();
       this.focusInitialItem();
     } else {
       this.stopPositioning?.();
       this.stopPositioning = null;
+      this.stopOutsidePointerFallback();
       this.focusLast = false;
       this.restoreFocus();
     }
@@ -65,6 +72,37 @@ export default class extends Controller {
     this.stopPositioning = observeOverlayPosition(update);
   }
 
+  startOutsidePointerFallback() {
+    if (!this.supportsPopover || this.stopOutsidePointerFallbackListener)
+      return;
+
+    document.addEventListener("pointerdown", this.outsidePointerDown, true);
+    this.stopOutsidePointerFallbackListener = () => {
+      document.removeEventListener(
+        "pointerdown",
+        this.outsidePointerDown,
+        true,
+      );
+      this.stopOutsidePointerFallbackListener = null;
+    };
+  }
+
+  stopOutsidePointerFallback() {
+    this.stopOutsidePointerFallbackListener?.();
+  }
+
+  outsidePointerDown(event) {
+    if (!this.contentTarget.matches(":popover-open")) return;
+
+    const path = event.composedPath?.();
+    const insideMenu = path
+      ? path.includes(this.contentTarget) || path.includes(this.triggerTarget)
+      : this.contentTarget.contains(event.target) ||
+        this.triggerTarget.contains(event.target);
+
+    if (!insideMenu) this.hide();
+  }
+
   navigate(event) {
     switch (event.key) {
       case "Escape":
@@ -123,4 +161,11 @@ export default class extends Controller {
       (item) => !item.disabled && item.getAttribute("aria-disabled") !== "true",
     );
   }
+
+  get supportsPopover() {
+    return (
+      typeof this.contentTarget.showPopover === "function" &&
+      typeof this.contentTarget.hidePopover === "function"
+    );
+  }
 }

data/app/javascript/controllers/nk/dropzone_controller.js

@@ -230,8 +230,8 @@ export default class extends Controller {
     this.element.dataset.state = this.initialInputDisabled
       ? "disabled"
       : selectedCount > 0
-        ? "success"
-        : "idle";
+      ? "success"
+      : "idle";
   }
 
   replaceFiles(files) {

data/app/javascript/controllers/nk/progressive_image_controller.js

@@ -24,6 +24,10 @@ export default class extends Controller {
     if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
   }
 
+  prepareForCache() {
+    delete this.element.dataset.enhanced;
+  }
+
   imageTargetConnected(image) {
     if (this.connected) this.bindImage(image);
   }
@@ -47,11 +51,14 @@ export default class extends Controller {
     this.releaseImage();
     this.boundImage = image;
     this.revision = (this.revision || 0) + 1;
-    this.setState("loading");
     image.addEventListener("load", this.onLoad);
     image.addEventListener("error", this.onError);
 
-    if (image.complete) this.reflectComplete(image);
+    if (image.complete) {
+      this.reflectComplete(image);
+    } else {
+      this.setState("loading");
+    }
   }
 
   releaseImage() {
@@ -98,11 +105,8 @@ export default class extends Controller {
   }
 
   reflectComplete(image) {
-    if (image.naturalWidth > 0) {
-      this.loaded();
-    } else {
-      this.failed();
-    }
+    this.revision = (this.revision || 0) + 1;
+    this.setState(image.naturalWidth > 0 ? "loaded" : "error");
   }
 
   setState(state) {

data/app/javascript/controllers/nk/tabs_controller.js

@@ -43,9 +43,12 @@ export default class extends Controller {
   }
 
   navigate(event) {
+    const rightToLeft = getComputedStyle(this.element).direction === "rtl";
     const directionKeys =
       this.orientationValue === "vertical"
         ? ["ArrowUp", "ArrowDown"]
+        : rightToLeft
+        ? ["ArrowRight", "ArrowLeft"]
         : ["ArrowLeft", "ArrowRight"];
 
     if (![...directionKeys, "Home", "End"].includes(event.key)) return;
@@ -142,7 +145,11 @@ export default class extends Controller {
       const active = panel.dataset.key === value;
 
       panel.hidden = !active;
-      panel.setAttribute("aria-hidden", String(!active));
+      if (active) {
+        panel.setAttribute("aria-hidden", "false");
+      } else {
+        panel.removeAttribute("aria-hidden");
+      }
       panel.dataset.state = active ? "active" : "inactive";
       panel.tabIndex = active ? 0 : -1;
     });

data/app/javascript/controllers/nk/tooltip_controller.js

@@ -6,6 +6,8 @@ export default class extends Controller {
   }
 
   dismiss(event) {
+    if (!this.shown) return;
+
     event.preventDefault();
     this.element.dataset.dismissed = "";
   }
@@ -21,4 +23,11 @@ export default class extends Controller {
   reset() {
     delete this.element.dataset.dismissed;
   }
+
+  get shown() {
+    return (
+      !("dismissed" in this.element.dataset) &&
+      this.element.matches(":hover, :focus-within")
+    );
+  }
 }

data/config/locales/en.yml

@@ -12,7 +12,9 @@ en:
         dark: "Dark"
         system: "System"
     avatar_stack:
-      overflow: "%{count} more avatars"
+      overflow:
+        one: "%{count} more avatar"
+        other: "%{count} more avatars"
     combobox:
       invalid_selection: "Choose an option."
       no_results: "No options found."
@@ -37,6 +39,7 @@ en:
     dropzone:
       label: "Upload files"
       prompt: "Drop files here or choose them from your device."
+      compact_prompt: "Drop or choose files."
       preview_list: "Selected files"
       progress: "Upload progress"
       progress_for: "Upload progress for %{name}"

data/docs/agent_guide.md

@@ -20,8 +20,9 @@ Read this guide from that directory, then consult only the reference needed for
 | Choose or compose UI                        | `docs/component_contracts.md`             |
 | Rails assets, forms, and application shells | `docs/rails_integration.md`               |
 | Turbo, Frames, Streams, morphs, or Stimulus | `docs/hotwire.md`                         |
+| Browser support or progressive fallback     | `docs/browser_support.md`                 |
 | Theme tokens and application composition    | `docs/customization.md`                   |
-| Upgrade an existing Nitro Kit 1.x app        | `docs/migration_1_to_2.md`                |
+| Upgrade an existing Nitro Kit 1.x app       | `docs/migration_1_to_2.md`                |
 | Query, sort, filter, or paginate            | `docs/patterns/queryable_collection.md`   |
 | Create, update, and show validation         | `docs/patterns/resource_form.md`          |
 | Delete, revoke, archive, or confirm         | `docs/patterns/destructive_action.md`     |
@@ -34,21 +35,21 @@ The installed component source is the final authority for constructor and compou
 
 Prefer the component that owns the whole region, then compose smaller components inside it.
 
-| Product need                     | Begin with                                                |
-| -------------------------------- | --------------------------------------------------------- |
-| Application chrome               | `AppShell`, `AppNavigation`, `CommandPalette`             |
-| Authentication page              | `AuthShell`                                               |
-| Settings navigation              | `SettingsLayout`                                          |
-| Team or account administration   | `AppShell`, `Toolbar`, `Table`, `FormSection`             |
-| App page title and basic actions | `AppShell`, then `Toolbar`                                |
-| Content-led page introduction    | `PageHeader`                                              |
-| Data region                      | `DataSection`, then `Table` or `EmptyState`               |
-| Queryable tabular data           | `Table`, `Toolbar`, `PaginationBar`                       |
-| Model-backed form                | `FormSection`, Rails `form_with`, `NitroKit::FormBuilder` |
-| Destructive settings             | `DangerZone`, optionally `Dialog`                         |
-| Transient server feedback        | `Toast::FlashMessages`                                    |
-| Rendered Markdown or rich text   | `Container`, then `Typeset`                               |
-| General grouping                 | `Card`, `Flex`, `Grid`, `Container`                       |
+| Product need                     | Begin with                                                    |
+| -------------------------------- | ------------------------------------------------------------- |
+| Application chrome               | `AppShell`, `AppNavigation`, `CommandPalette`                 |
+| Authentication page              | `AuthShell`                                                   |
+| Settings navigation              | `SettingsLayout`                                              |
+| Team or account administration   | `AppShell`, `Toolbar`, `Table`, `SettingsSection`             |
+| App page title and basic actions | `AppShell`, then `Toolbar`                                    |
+| Content-led page introduction    | `PageHeader`                                                  |
+| Data region                      | `DataSection`, then `Table` or `EmptyState`                   |
+| Queryable tabular data           | `Table`, `Toolbar`, `PaginationBar`                           |
+| Model-backed form                | `SettingsSection`, Rails `form_with`, `NitroKit::FormBuilder` |
+| Destructive settings             | `DangerZone`, optionally `Dialog`                             |
+| Transient server feedback        | `Toast::FlashMessages`                                        |
+| Rendered Markdown or rich text   | `Container`, then `Typeset`                                   |
+| General grouping                 | `Card`, `Flex`, `Grid`, `Container`                           |
 
 Application-specific product UI belongs under the application's namespace and composes Nitro components. Nitro owns component markup, styles, accessibility structure, and narrowly scoped progressive behavior. The application owns product policy, records, routes, authorization, queries, DOM IDs, and server responses.
 
@@ -70,6 +71,8 @@ After establishing that inventory, generate the host integration smoke tests
 from the currently bundled gem with `bin/rails generate
 nitro_kit:upgrade_smoke_tests`. The generator preserves existing files and
 skips missing Rails Minitest or system-test infrastructure with setup guidance.
+Keep the generated explanatory header in each test: these are host-integration
+regression checks, not substitutes for application-specific acceptance tests.
 Run supported generated tests before and after the application conversion,
 while retaining application-specific acceptance coverage for every inventoried
 flow. Customize each generated `prepare_nitro_kit_upgrade_smoke_test` method
@@ -89,6 +92,15 @@ Do not retain copied Nitro Kit 1.x source as the fallback. Remove the legacy
 component and preserve the unsupported behavior in clearly application-owned
 code. Report the missing equivalent as a Nitro Kit coverage gap.
 
+At the end of a migration, search the whole application for
+`desperately_need_a_class:` and review every result. Aim for zero rather than
+translating old utility classes mechanically. Move application layout and
+visual treatment to wrappers, use semantic component options or native
+attributes, accept incidental Nitro defaults, and keep unmatched product UI
+application-owned. Remove generic class forwarding from shared builders.
+Retain an escape only for a named external integration that requires a class
+hook, and record that reason in the migration review.
+
 ## Use one interaction grammar
 
 Choose the smallest primitive that completes the interaction:
@@ -119,6 +131,9 @@ Successful non-GET HTML submissions redirect with `303 See Other`. Invalid form
   inline or multi-column.
 - Use component options, compound declarations, layouts, and documented `--nk-*` theme properties.
 - Keep an HTML fallback for every Turbo form flow.
+- Treat that HTML response as a Turbo transport fallback, not automatically a
+  JavaScript-free interaction; use `docs/browser_support.md` for the canonical
+  component classifications.
 - Test semantic output and stable owned attributes.
 
 Do not copy component source, add `nk_*` helpers, invent a general ERB bridge, mutate Nitro-owned Stimulus controllers, or pass `class:` and `style:`. The intentionally loud `desperately_need_a_class:` escape exists only for external integrations that require a class hook.

data/docs/agent_native_spec.md

@@ -66,6 +66,20 @@ Rails remains first-class where Rails owns meaningful semantics:
 
 Applications include the `Phlex::Rails::Helpers::*` adapters they actually use. Nitro Kit does not recreate Rails helpers under an `nk_*` namespace.
 
+### Browser support
+
+Nitro Kit uses modern web standards while keeping core content and actions
+usable for the overwhelming majority of people on maintained browsers. The
+practical target is current stable and popular evergreen Chrome, Edge, Firefox,
+macOS Safari, and iOS Safari releases from roughly the two years before each
+Nitro release. Mobile Safari is a first-class functional target. Nitro
+feature-detects newer capabilities and owns the smallest fallback needed to
+keep essential actions operable without holding components to the oldest
+browser's feature set. Visual polish may degrade when the underlying content,
+request path, semantics, and keyboard behavior remain intact. The versioned
+public contract and no-JavaScript policy are in
+[`browser_support.md`](browser_support.md).
+
 ## Consistency boundary
 
 The initial correctness layer is explicit Ruby APIs and immediate component validation, not a generalized page linter.
@@ -149,15 +163,18 @@ The stable release contains 40 atoms and components:
 
 The non-visual `AppearanceBootstrap` installs the shared document appearance runtime, and `NitroKit::Choice` is the typed option value shared by the choice controls.
 
-There is no Datepicker component and no date controller. `Input`'s `type: :date` is the only date control; `Field` and `FormBuilder` reach it through `as: :date`, and their CSS inherits the Safari date-editor alignment fix. `Combobox::Option` is likewise gone in favor of `Choice`.
+There is no Datepicker component and no date controller. `Input`'s native date-family types are progressive enhancement; `Field` and `FormBuilder` preserve them, and `type: :date` inherits the Safari date-editor alignment fix. Month and week may render as text controls without picker, normalization, or constraint enforcement, so applications validate their ISO formats and ranges on the server and compose an application-owned `Select` when an exact bounded choice is required. `Combobox::Option` is likewise gone in favor of `Choice`.
 
 ### Native interaction authority
 
-Nitro uses current evergreen HTML primitives as the source of truth before adding JavaScript:
+Nitro uses standards-based HTML primitives as the preferred path before adding
+JavaScript. Native is not proof of compatibility: the primitive must cover the
+browser-support window or Nitro must supply a focused fallback for essential
+behavior.
 
-- Accordion items are native `details`/`summary` disclosures. Single mode uses one shared `name`; it has no controller or disabled-item abstraction.
-- Dialog declarations produce exactly one native panel through the required `panel(title:, description: nil, nonmodal: false)` declaration, and Nitro renders close button, title, description, then application content inside it. `command="show-modal"` and `command="close"` controls target the panel through `commandfor`; `nonmodal: true` is the only server-rendered open mode and cannot be combined with a trigger. `nk--dialog` adds only backdrop light dismissal and, for `dismissible: false`, Escape suppression.
-- Dropdown visibility and invoker state belong to `popover="auto"`. `trigger` forwards `icon:`, `icon_end:`, and `label:` to Button, and `item` accepts its own `icon:`. Its small controller supplies menu focus, arrow/Home/End navigation, and focus restoration to the trigger when the popover closes with focus still inside it. CSS anchor positioning follows the trigger when supported and otherwise centers the menu safely in the viewport.
+- Accordion items are native `details`/`summary` disclosures. Single mode uses one shared `name` as its exclusive-group authority; where named-details grouping is unavailable, disclosure remains fully usable but the single-mode baseline is reduced to independently open items. Nitro deliberately adds no controller or browser detection for that short compatibility gap.
+- Dialog declarations produce exactly one native panel through the required `panel(title:, description: nil, nonmodal: false)` declaration, and Nitro renders close button, title, description, then application content inside it. `command="show-modal"` and `command="close"` controls target the panel through `commandfor`; `nonmodal: true` is the only server-rendered open mode and cannot be combined with a trigger. `nk--dialog` handles backdrop light dismissal and, for `dismissible: false`, Escape suppression. Because Invoker Commands do not cover the full browser-support window, that controller also checks the reflected invoker relationship and falls back to `showModal()` or `close()` when the native command cannot run. The canonical no-JavaScript classifications remain in [`browser_support.md`](browser_support.md).
+- Dropdown visibility and invoker state belong to `popover="auto"`. `trigger` forwards `icon:`, `icon_end:`, and `label:` to Button, and `item` accepts its own `icon:`. Its small controller supplies menu focus, arrow/Home/End navigation, focus restoration, collision-aware positioning, and a capability-checked outside-pointer dismissal fallback for WebKit Popover engines that miss light dismissal. The fallback requests the native close transition only while the popover is open, ignores composed-path interactions inside the menu or its trigger, and releases its listener on close or disconnect. Without Nitro JavaScript, native Popover still owns visibility; its bounded top-left placement is reduced from trigger-relative collision-aware placement.
 - CommandPalette uses one native dialog, a declarative search-shaped trigger, and native destination links. Its controller adds the optional Command-K/Control-K shortcut, local filtering, result announcements, and Turbo cleanup without replacing link navigation or retaining hidden application policy. With `search_url:`, the same input submits debounced GET requests into the owned Turbo Frame; the endpoint returns `CommandPalette::Results` HTML and remains responsible for authorization.
 - Tooltip visibility belongs to CSS hover and focus selectors, including a hoverable bridge across the visual gap. Button triggers cover ordinary buttons and links; `as: :custom` forwards owned HTML, ARIA, and data to an existing focusable mutation or compound trigger. Its controller only implements Escape dismissal and reset.
 
@@ -211,7 +228,7 @@ Eleven blocks and shells were extracted:
 - `PageHeader`
 - `StatGrid`
 - `DataSection`
-- `FormSection`
+- `SettingsSection`
 - `DangerZone`
 - `EmptyState`
 
@@ -294,7 +311,7 @@ The audited former-Pro catalog maps completely to the new architecture:
 
 | Former surface                                           | 2.0 disposition                                                                                                                               |
 | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| Sidebar and Top Navigation layouts                       | Rebuilt as `AppShell` for whole-application navigation and `Sheet` for contextual narrow panels                                                |
+| Sidebar and Top Navigation layouts                       | Rebuilt as `AppShell` for whole-application navigation and `Sheet` for contextual narrow panels                                               |
 | Details Table                                            | Rebuilt as `DetailsTable`                                                                                                                     |
 | Dropzone                                                 | Rebuilt as native `Dropzone`; Dropzone.js is removed                                                                                          |
 | Progressive Image                                        | Rebuilt as `ProgressiveImage`                                                                                                                 |
@@ -338,7 +355,7 @@ nitro-kit.compound
 
 Selectors use `:where()` for zero authored specificity. Nitro ships its own global, Preflight-style reset in the `nitro-kit.reset` layer and never depends on Tailwind Preflight. It normalizes the whole page, so arbitrary content inside a component gets the same baseline as Nitro's own markup, and because it is layered, unlayered application CSS always wins. `min-width: 0` and list-marker removal stay scoped to Nitro-owned elements so prose lists keep real markers.
 
-Public `--nk-*` variables cover semantic colors, the component-specific raised default-button treatment, typography, spacing, radii, border and focus geometry, shadows, motion, control heights, and content widths. Private `--_nk-*` variables coordinate component mechanics and are not theme API.
+Public `--nk-*` variables cover semantic colors, the component-specific raised default-button treatment and optional button-only radius, typography, spacing, shared radii, border and focus geometry, shadows, motion, control heights, and content widths. Private `--_nk-*` variables coordinate component mechanics and are not theme API.
 
 The exact browser order is optional third-party base CSS such as Lexxy, optional `nitro_kit-tailwind-v4.css`, generated `nitro_kit.css`, compiled Tailwind CSS when present, then unlayered application styles containing token overrides. `AppearanceBootstrap` precedes every stylesheet. Applications never edit the generated asset. [`customization.md`](customization.md) is the complete public token inventory and usage guide.
 
@@ -360,9 +377,9 @@ Turbo Frames and Turbo Streams remain Rails helpers used directly from Phlex. In
 
 Server-rendered feedback is the Rails flash. `Toast` renders `section[data-nk="toast"][role="region"]` wrapping `ol[data-slot="toast-list"]`, whose id is the toast id plus `-list`, so the default region is addressable as `nk-toast-list` and a Turbo Stream can append `NitroKit::Toast::Item` to it directly. Items carry `role="status"`, or `role="alert"` for the error variant, so a server-rendered item announces without waiting for a DOM mutation, and every item is `data-turbo-temporary` so a cached page never replays stale feedback while the region and list survive. `Toast::FlashMessages` maps an enumerable Rails flash onto the same items. Nitro does not add a client-side notification store.
 
-The engine ships CSS assets and Nitro-owned Stimulus controllers for enhancements that native HTML and CSS do not cover. When importmap is present it adds its pins automatically; the host still owns Stimulus and its normal controller loader. The engine boots without importmap: Accordion is complete with no controller at all and Dialog still opens and closes through declarative `command`/`commandfor`, while enhanced interactions such as Dropdown keyboard navigation, Tooltip Escape dismissal, and Dialog backdrop light dismissal require their pinned controllers. Nitro Kit 2.0 does not define a JavaScript-package entrypoint for automatic bundler registration.
+The engine ships CSS assets and Nitro-owned Stimulus controllers for enhancements and compatibility bridges that native HTML and CSS do not cover throughout the support window. When importmap is present it adds its pins automatically; the host still owns Stimulus and its normal controller loader. The engine boots without importmap, but only the component-specific no-JavaScript baselines remain. Accordion keeps its full native disclosure baseline without a controller; its single mode is reduced to independently open items only where named-details grouping is unavailable. Dialog opens without its controller only where declarative `command`/`commandfor` is supported. Nitro Kit 2.0 does not define a JavaScript-package entrypoint for automatic bundler registration.
 
-Date inputs, Switch, and ordinary checked state deliberately use native inputs rather than custom controllers. The one exception is `indeterminate:`, which HTML cannot express as an attribute: `Checkbox` mounts `nk--checkable` only in that case, and the controller's whole job is to apply the native DOM property and own the matching `data-state="indeterminate"`. No third-party JavaScript runtime is vendored.
+Date-family inputs, Switch, and ordinary checked state deliberately use native inputs rather than custom controllers. Month and week retain their native types as progressive enhancement even where a browser exposes text entry; Nitro does not promise a picker or client-side normalization. The one exception is `indeterminate:`, which HTML cannot express as an attribute: `Checkbox` mounts `nk--checkable` only in that case, and the controller's whole job is to apply the native DOM property and own the matching `data-state="indeterminate"`. No third-party JavaScript runtime is vendored.
 
 ## Examples and verification
 

data/docs/browser_support.md

@@ -0,0 +1,193 @@
+# Browser support
+
+Nitro Kit uses modern web standards while keeping core content and actions
+usable for the overwhelming majority of people on maintained browsers.
+
+The practical target is current stable and popular evergreen releases from
+roughly the two years before each Nitro Kit release. This includes Chrome and
+Edge on desktop, Chrome on Android, Firefox, Safari on macOS, and Safari on iOS.
+It is a coverage target, not a promise of identical results in every version or
+a reason to hold components to the oldest browser's feature set.
+
+Each release's dated test matrix sets the concrete floor using release date and
+real-world usage rather than an equal number of major versions. Mobile Safari
+is a first-class target, not a reduced mobile tier. Important usage,
+accessibility, or platform constraints may justify coverage outside the usual
+window.
+
+## Functional baseline
+
+In browsers covered by a release's matrix, Nitro components must keep their
+essential content and actions usable. Forms must submit, links must navigate,
+disclosures and overlays must open and close, destructive actions must retain a
+usable request path, and controls must preserve their accessible names and
+keyboard behavior.
+
+Visual and convenience enhancements may degrade when a browser lacks a newer
+CSS or platform feature. Exact animation, preferred overlay placement, advanced
+text wrapping, and similar polish are not required when the simpler result
+remains understandable and operable. Support means usable and accessible, not
+pixel-identical presentation or identical convenience behavior.
+
+Nitro prefers approved web standards and native browser behavior, but native is
+not synonymous with supported. A newer standard can be adopted before it covers
+the practical browser target when Nitro can preserve essential behavior:
+
+1. Keep the standard markup or API as the preferred path.
+2. Detect support by capability rather than user agent.
+3. Add the smallest Nitro-owned fallback needed to preserve functionality.
+4. Use a focused polyfill only when a local fallback cannot provide the
+   required semantics.
+
+Typeset is a CSS-only exception to the usual progressive-enhancement note:
+its readable source uses `@scope`, while the stylesheet also contains a
+low-specificity fallback for engines that do not parse `@scope` (including
+Firefox through 145). The fallback provides root typography and explicitly
+anchored direct-child rules for headings, flow elements, lists, code/pre, and
+tables, plus links within those supported semantic elements and their focus
+state. It excludes direct nested
+`[data-nk]` and `data-typeset="off"` boundaries and intentionally does not
+promise the full descendant styling of the scoped path.
+
+Applications should not need to copy Nitro controllers or install a general
+polyfill bundle for a Nitro-owned component. Browsers outside a release's matrix
+may still work, but Nitro does not promise fixes for them.
+
+### Month and week inputs
+
+`Input(type: :month)` and `Input(type: :week)`, including the matching `Field`
+and `FormBuilder` paths, retain the standard native input types as progressive
+enhancement. Desktop Safari and Firefox can expose these controls as text
+inputs, and native week selection arrived later on iOS Safari. In those cases a
+picker, browser normalization, and enforcement of `min`, `max`, and `step` may
+be absent.
+
+Applications must accept and validate the submitted ISO shapes on the server:
+`YYYY-MM` for month and `YYYY-Www` for ISO week. They must also validate allowed
+ranges and increments as domain rules; the native constraint attributes are
+client-side hints, not an authorization or validation boundary. When choosing
+only from an exact, bounded set is essential, compose an application-owned
+`Select` with explicit month or week options instead of relying on a generic
+Nitro datepicker. Ordinary `date`, `time`, and `datetime-local` controls keep
+their existing contracts.
+
+## JavaScript and progressive enhancement
+
+Normal support assumes the documented Nitro JavaScript is installed. Nitro is
+server-rendered and progressively enhanced, not JavaScript-free. Static content,
+links, ordinary forms, and only the component-specific baselines documented in
+the component contracts are guaranteed without JavaScript. Turbo transport,
+Stimulus enhancements, and compatibility bridges are then unavailable.
+
+The classifications below describe the rendered page with Nitro JavaScript,
+Stimulus, and Turbo absent:
+
+- **Full** means the component's essential content and action remain available;
+  documented convenience behavior may still be absent.
+- **Reduced** means useful content or a simpler native interaction remains, but
+  part of the component's defining interaction is absent.
+- **Unavailable** means the defining interaction cannot be completed. Critical
+  actions need an ordinary server-rendered route outside that component.
+
+A server-rendered HTML response is not automatically a JavaScript-free
+interaction. It can still place content in a closed dialog or rely on Turbo to
+submit, replace, or confirm. Likewise, an HTML response branch is the fallback
+for Turbo transport, not proof that the surrounding control works without
+JavaScript.
+
+### No-JavaScript component matrix
+
+| Component or family                                        | Classification                                                     | Concise baseline without JavaScript                                                                                                                                                                                                 |
+| ---------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Links, Button, ButtonTo, and ordinary forms                | Full                                                               | Native navigation and submission work. Submission indicators and Turbo transport or confirmation do not.                                                                                                                            |
+| Input, Select, Textarea, Switch, RadioButton, and Checkbox | Full; reduced for indeterminate Checkbox                           | Native controls edit and submit. `indeterminate: true` cannot be applied because it is a DOM property; month/week have the separate native-control limitations below.                                                               |
+| Accordion                                                  | Full; reduced single grouping where named `details` is unsupported | Every `details` opens and closes. Exclusive grouping depends on native shared-`name` support.                                                                                                                                       |
+| AppShell                                                   | Full                                                               | Navigation stays visible in document flow at narrow widths; the enhanced drawer interaction is absent.                                                                                                                              |
+| Appearance                                                 | Reduced                                                            | CSS follows the system preference and server-rendered picker state remains visible, but a picker cannot apply or persist a new choice without the bootstrap runtime and controller.                                                 |
+| Avatar                                                     | Reduced                                                            | The native image and rendered fallback remain, but a failed image is not swapped to its fallback.                                                                                                                                   |
+| Combobox                                                   | Full                                                               | The labelled native Select remains the named control and submission source; searchable listbox behavior is absent.                                                                                                                  |
+| Dialog and Sheet                                           | Reduced with Invoker Commands; unavailable without them            | Declarative trigger and close controls work only with native Invoker Commands. A server-open nonmodal Dialog remains visible; controller dismissal policy and the compatibility bridge are absent.                                  |
+| CommandPalette                                             | Reduced with Invoker Commands; unavailable without them            | Native commands can open the dialog and its destination links navigate, but search, shortcut, announcements, and Turbo results are absent. Without Invoker Commands the closed content is unreachable.                              |
+| Dropdown                                                   | Reduced                                                            | Native Popover opens, closes, and light-dismisses. Menu keyboard conventions, focus restoration, collision-aware placement, and Nitro's outside-pointer compatibility fallback are absent; CSS supplies bounded top-left placement. |
+| Dropzone                                                   | Full                                                               | Its labelled native file input and ordinary form submission work; drag preview, policy feedback, progress, and direct upload are absent.                                                                                            |
+| RichTextArea                                               | Unavailable unless the host editor provides its own fallback       | Nitro wraps trusted host-editor markup and does not manufacture a plain-text control. The host editor owns its JavaScript and fallback contract.                                                                                    |
+| ProgressiveImage                                           | Reduced                                                            | The native image loads and retains its accessible alternative; decode/load state and the visible error fallback are not enhanced.                                                                                                   |
+| Tabs                                                       | Reduced                                                            | Every panel and its heading control remain visible and reachable; single-panel selection and APG keyboard behavior are absent.                                                                                                      |
+| Toast                                                      | Reduced                                                            | Server-rendered flash content and live-region semantics remain; timed and manual dismissal are absent.                                                                                                                              |
+| Tooltip                                                    | Reduced                                                            | CSS hover and focus disclosure remain; Escape dismissal is absent.                                                                                                                                                                  |
+
+Typeset is not interactive, but its no-JavaScript and no-`@scope` CSS path is
+also reduced: the fallback covers the documented semantic subset rather than
+full descendant parity.
+
+### Compatibility details
+
+#### Accordion
+
+Accordion always keeps native `details` and `summary` as the disclosure
+authority. Its no-JavaScript baseline is full for opening and closing each
+item. In `single` mode, a shared `name` is the browser-native exclusive-group
+mechanism: browsers that support named details provide the full one-open-item
+behavior without a Nitro controller.
+
+The short Firefox gap before Firefox 130, including Firefox 128 ESR, has a
+reduced `single` baseline: each disclosure still opens and closes normally,
+but more than one item can remain open. Nitro does not detect the browser or
+install JavaScript merely to duplicate that native grouping. Applications for
+which strict one-open-at-a-time behavior is essential in that gap should use a
+different interaction with an application-owned server or JavaScript policy.
+
+Browser compatibility is verified against current stable browsers and
+representative older releases near the edge of the support window. Compatibility
+work prioritizes real Safari and iOS Safari coverage in addition to Chromium;
+tests that merely remove an attribute in current Chrome are useful branch tests,
+but are not a substitute for the affected browser engine.
+
+Dialog, Sheet, and CommandPalette keep declarative `command`/`commandfor`
+controls in their server markup. With Nitro JavaScript installed, their shared
+controller uses the reflected invoker relationship when available and falls
+back to `HTMLDialogElement.showModal()` or `close()` only when that relationship
+cannot run. Without JavaScript, opening and closing these overlays is available
+only in browsers with Invoker Commands; destination links and ordinary forms
+remain server-rendered, but content inside a closed dialog is not reachable.
+
+Each Nitro release records a dated tested-browser matrix. The rolling policy is
+the durable contract; the matrix records the concrete versions used to verify a
+particular release.
+
+## Nitro Kit 2.0 release matrix (2026-08-05)
+
+This is the release checklist for the next Nitro 2.0 release. “Automated” means
+the Rails/Selenium system suite runs in CI; it does not claim that Selenium
+reproduces every device or browser UI detail. Version numbers are the stable
+targets recorded on this date, and should be refreshed if the release slips.
+
+| Target          | Near-floor reference | Current release verification | Method                                                |
+| --------------- | -------------------- | ---------------------------- | ----------------------------------------------------- |
+| Chrome desktop  | Chrome 128           | Chrome 151                   | Automated Ubuntu full-system-suite lane               |
+| Edge desktop    | Edge 128             | Edge 151                     | Manual Chromium release check (same engine as Chrome) |
+| Chrome Android  | Chrome 128           | Chrome 151 on Android        | Manual real-device check                              |
+| Firefox desktop | Firefox 128 ESR      | Firefox 153                  | Automated Ubuntu priority-smoke lane                  |
+| Safari macOS    | Safari 18            | Safari 26.5                  | Automated `macos-latest` priority-smoke lane          |
+| Safari iOS      | Safari 18 / iOS 18   | Safari 26.5 / iOS 26.5       | Manual real-device release check                      |
+
+The automated matrix intentionally tests current Chrome, Firefox, and macOS
+Safari rather than downloading historical binaries. Chrome runs the full
+system suite. Firefox and Safari run `bin/browser-smoke`, the single maintained
+priority lane for Dialog, Sheet, CommandPalette, Dropdown/AppearancePicker,
+Accordion, Hotwire lifecycle, Typeset contracts, and date-family input
+behavior. Chrome DevTools emulation remains Chrome-only coverage and is not
+presented as cross-engine verification. Priority smoke lanes run with one
+worker; Chrome retains the full suite's normal parallelism.
+
+Before release, manually repeat those flows on one current Android Chrome and
+one current iPhone Safari, including narrow layout, VoiceOver/TalkBack where
+available, real form submission, and month/week ISO values. Record device OS,
+browser build, date, and any reduced-baseline behavior in the release notes.
+Do not describe the near-floor or iOS rows as automated coverage.
+
+The Firefox 128 ESR and older Safari behavior that cannot be installed
+reliably on GitHub-hosted runners is represented by capability-focused tests:
+stripping Invoker Commands and exercising Nitro fallbacks, plus the documented
+native month/week degradation. These branch simulations supplement, but do not
+replace, the dated real-browser checks.