nitro_kit 0.9.0 → 2.0.0.alpha.2

data/lib/nitro_kit/upgrade_smoke_test.rb

@@ -0,0 +1,403 @@
+require "active_model"
+require "nitro_kit"
+require "set"
+
+unless Rails.env.test?
+  raise "nitro_kit/upgrade_smoke_test may only be loaded in Rails test environment"
+end
+
+unless defined?(::ApplicationController)
+  raise "Nitro Kit upgrade smoke tests require the host ApplicationController"
+end
+
+module NitroKit
+  module UpgradeSmoke
+    PATH = "/_nitro_kit/upgrade_smoke"
+    FRAME_ID = "nitro-kit-upgrade-smoke"
+    SESSION_KEY = "nitro_kit_upgrade_smoke"
+
+    class Profile
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :name, :string
+
+      validates :name, presence: true, length: { minimum: 3 }
+
+      def persisted? = false
+    end
+
+    class Surface < Phlex::HTML
+      include Phlex::Rails::Helpers::FormWith
+      include Phlex::Rails::Helpers::TurboFrameTag
+
+      def initialize(profile:, revision:)
+        @profile = profile
+        @revision = revision
+      end
+
+      def view_template
+        section(data: { nitro_kit_upgrade_smoke: "surface" }) do
+          turbo_frame_tag(FRAME_ID) do
+            render_summary
+            render_form
+            render_dialog
+            render_sheet
+          end
+        end
+      end
+
+      private
+        attr_reader :profile, :revision
+
+        def render_summary
+          render NitroKit::Card.new(id: "nitro-kit-upgrade-smoke-summary") do |card|
+            card.title("Post-mutation component", level: 2)
+            card.body do
+              p(data: { nitro_kit_upgrade_smoke_value: "name" }) { profile.name }
+              render NitroKit::Badge.new("Revision #{revision}", color: :info)
+            end
+          end
+        end
+
+        def render_form
+          form_with(
+            model: profile,
+            scope: :profile,
+            url: PATH,
+            method: :patch,
+            builder: NitroKit::FormBuilder,
+            id: "nitro-kit-upgrade-smoke-form",
+            data: { turbo_frame: "_top" }
+          ) do |form|
+            form.group do
+              form.field(:name, required: true, description: "This value must survive the mutation.")
+              form.submit("Save smoke-test profile", data: { turbo_submits_with: "Saving…" })
+            end
+          end
+        end
+
+        def render_dialog
+          render NitroKit::Dialog.new(id: "nitro-kit-upgrade-smoke-dialog") do |dialog|
+            dialog.trigger("Review dialog")
+            dialog.panel(
+              title: "Upgrade dialog",
+              description: "The native dialog contract rendered through the host application."
+            ) do
+              p { "Dialog content remains available after the upgrade." }
+            end
+          end
+        end
+
+        def render_sheet
+          render NitroKit::Sheet.new(id: "nitro-kit-upgrade-smoke-sheet", side: :right) do |sheet|
+            sheet.trigger("Review sheet")
+            sheet.panel(
+              title: "Upgrade sheet",
+              description: "The native sheet contract rendered through the host application."
+            ) do
+              p { "Sheet content remains available after the upgrade." }
+            end
+          end
+        end
+    end
+
+    class Controller < ::ApplicationController
+      def show
+        render_surface(profile: current_profile, revision: current_revision)
+      end
+
+      def update
+        profile = Profile.new(profile_params)
+
+        if profile.valid?
+          session[SESSION_KEY] = { "name" => profile.name, "revision" => current_revision + 1 }
+          redirect_to PATH, status: :see_other, notice: "Smoke-test profile saved"
+        else
+          flash.now[:alert] = "Smoke-test profile needs attention"
+          render_surface(profile:, revision: current_revision, status: :unprocessable_entity)
+        end
+      end
+
+      private
+        def current_state
+          session.fetch(SESSION_KEY, { "name" => "Original workspace", "revision" => 0 })
+        end
+
+        def current_profile
+          Profile.new(name: current_state.fetch("name"))
+        end
+
+        def current_revision
+          current_state.fetch("revision")
+        end
+
+        def profile_params
+          params.require(:profile).permit(:name)
+        end
+
+        def render_surface(profile:, revision:, status: :ok)
+          render Surface.new(profile:, revision:), status:
+        end
+    end
+
+    module RouteLifecycle
+      ROUTE_BLOCK = proc do
+        get PATH, to: Controller.action(:show)
+        patch PATH, to: Controller.action(:update)
+      end
+
+      @lock = Mutex.new
+      @owners = Set.new
+
+      class << self
+        def install!(owner)
+          ensure_test_environment!
+
+          @lock.synchronize do
+            return if @owners.include?(owner)
+
+            install_routes! if @owners.empty?
+            @owners.add(owner)
+          end
+        end
+
+        def uninstall!(owner)
+          @lock.synchronize do
+            @owners.delete(owner)
+            uninstall_routes! if @owners.empty? && route_block_installed?
+          end
+        end
+
+        private
+          def install_routes!
+            collisions = %w[GET PATCH].select { |method| route_matches?(method) }
+            if collisions.any?
+              raise "Nitro Kit upgrade smoke route #{PATH} collides with host #{collisions.join("/")} routing"
+            end
+
+            Rails.application.routes.append(&ROUTE_BLOCK)
+            Rails.application.reload_routes!
+          end
+
+          def uninstall_routes!
+            append_blocks.delete(ROUTE_BLOCK)
+            Rails.application.reload_routes!
+          end
+
+          def route_matches?(method)
+            request = ActionDispatch::Request.new(
+              Rack::MockRequest.env_for(PATH, method:)
+            )
+            Rails.application.routes.router.recognize(request) { return true }
+            false
+          end
+
+          def route_block_installed?
+            append_blocks.include?(ROUTE_BLOCK)
+          end
+
+          def append_blocks
+            Rails.application.routes.instance_variable_get(:@append)
+          end
+
+          def ensure_test_environment!
+            return if Rails.env.test?
+
+            raise "Nitro Kit upgrade smoke routes may only be installed in Rails test environment"
+          end
+      end
+    end
+  end
+
+  class UpgradeSmokeTest < ActionDispatch::IntegrationTest
+    setup { UpgradeSmoke::RouteLifecycle.install!(self) }
+    setup :prepare_nitro_kit_upgrade_smoke_test
+    teardown { UpgradeSmoke::RouteLifecycle.uninstall!(self) }
+
+    def self.runnable_methods
+      self == UpgradeSmokeTest ? [] : super
+    end
+
+    test "renders forms overlays flash and one stable Turbo Frame through Rails" do
+      get UpgradeSmoke::PATH
+
+      assert_response :success
+      assert_host_installation
+      assert_select "body section[data-nk='toast']", count: 1
+      assert_select "section[data-nitro-kit-upgrade-smoke='surface'] > turbo-frame##{UpgradeSmoke::FRAME_ID}", count: 1 do
+        assert_select "form#nitro-kit-upgrade-smoke-form[action='#{UpgradeSmoke::PATH}'][method='post'][data-turbo-frame='_top']" do
+          assert_select "input[name='_method'][value='patch']"
+          assert_select "input#profile_name[name='profile[name]'][required][data-nk='input']"
+          assert_select "label[data-slot='field-label'][for='profile_name']"
+          assert_select "button[type='submit'][data-turbo-submits-with='Saving…']"
+        end
+        assert_native_overlay("dialog", title: "Upgrade dialog")
+        assert_native_overlay("sheet", title: "Upgrade sheet")
+      end
+    end
+
+    test "keeps submitted values errors feedback and the frame boundary on an invalid mutation" do
+      patch UpgradeSmoke::PATH,
+        params: { profile: { name: "x" } }
+
+      assert_response :unprocessable_entity
+      assert_select "turbo-frame##{UpgradeSmoke::FRAME_ID}", count: 1 do
+        assert_select "input#profile_name[value='x'][aria-invalid='true'][aria-describedby~='profile_name-errors']"
+        assert_select "ul#profile_name-errors[data-slot='field-error'][aria-live='assertive']:not([role]) > li", count: 1
+      end
+      assert_select "section[data-nk='toast'] [data-nk='toast-item'][data-variant='error']"
+    end
+
+    test "redirects after mutation then renders the changed value and flash from Phlex" do
+      patch UpgradeSmoke::PATH, params: { profile: { name: "Migrated workspace" } }
+
+      assert_response :see_other
+      assert_redirected_to UpgradeSmoke::PATH
+
+      follow_redirect!
+
+      assert_response :success
+      assert_select "turbo-frame##{UpgradeSmoke::FRAME_ID}", count: 1 do
+        assert_select "article#nitro-kit-upgrade-smoke-summary[data-nk='card']" do
+          assert_select "[data-nitro-kit-upgrade-smoke-value='name']", text: "Migrated workspace"
+          assert_select "[data-nk='badge']", text: "Revision 1"
+        end
+        assert_select "input#profile_name[value='Migrated workspace']"
+      end
+      assert_select "section[data-nk='toast'] [data-nk='toast-item'][data-variant='default']"
+    end
+
+    private
+      def prepare_nitro_kit_upgrade_smoke_test
+      end
+
+      def assert_host_installation
+        assert_operator UpgradeSmoke::Controller, :<, ::ApplicationController
+        assert_select "html > head link[rel='stylesheet'][href*='nitro_kit']", minimum: 1
+        assert_select "html > head script[data-nk-appearance-default]", count: 1
+        assert_select "html > head script[type='importmap'], html > head script[type='module'][src], html > head script[defer][src]",
+          minimum: 1
+
+        bootstrap = css_select("html > head script[data-nk-appearance-default]").first
+        nonced_entrypoint = css_select("html > head script[nonce]").find { |script| script != bootstrap }
+        return unless nonced_entrypoint
+
+        assert_equal nonced_entrypoint["nonce"], bootstrap["nonce"]
+      end
+
+      def assert_native_overlay(component, title:)
+        root = "[data-nk='#{component}']"
+        panel_id = "nitro-kit-upgrade-smoke-#{component}-panel"
+
+        assert_select "#{root} [data-slot='#{component}-trigger'][command='show-modal'][commandfor='#{panel_id}']"
+        assert_select "#{root} dialog##{panel_id}[data-slot='#{component}-panel']" do
+          assert_select "[data-slot='#{component}-title']", text: title
+          assert_select "[data-slot='#{component}-close'][command='close'][commandfor='#{panel_id}']"
+        end
+      end
+  end
+
+  module UpgradeSmokeSystemTests
+    extend ActiveSupport::Concern
+
+    included do
+      setup { UpgradeSmoke::RouteLifecycle.install!(self) }
+      setup :prepare_nitro_kit_upgrade_smoke_test
+      teardown { UpgradeSmoke::RouteLifecycle.uninstall!(self) }
+
+      test "submits invalid and valid mutations through Turbo in the host application" do
+        visit UpgradeSmoke::PATH
+
+        assert_host_installation
+        track_turbo_submissions
+
+        find("#profile_name").set("x")
+        find("#nitro-kit-upgrade-smoke-form button[type='submit']").click
+
+        assert_selector "#profile_name[value='x'][aria-invalid='true'][aria-describedby~='profile_name-errors']"
+        assert_selector "ul#profile_name-errors[data-slot='field-error'][aria-live='assertive']:not([role]) > li", count: 1
+        assert_selector "body section[data-nk='toast'] [data-nk='toast-item'][data-variant='error']"
+        assert_stable_frame
+
+        find("#profile_name").set("Migrated workspace")
+        find("#nitro-kit-upgrade-smoke-form button[type='submit']").click
+
+        assert_selector "[data-nitro-kit-upgrade-smoke-value='name']", text: "Migrated workspace"
+        assert_selector "[data-nk='badge']", text: "Revision 1"
+        assert_selector "#profile_name[value='Migrated workspace']"
+        assert_selector "body section[data-nk='toast'] [data-nk='toast-item'][data-variant='default']"
+        assert_stable_frame
+        assert_equal 2, evaluate_script("window.__nitroKitUpgradeSmokeTurboSubmissions")
+        assert_no_unexpected_console_errors
+      end
+
+      test "opens and closes the native Dialog and Sheet in the host browser" do
+        visit UpgradeSmoke::PATH
+
+        exercise_overlay("dialog")
+        exercise_overlay("sheet")
+      end
+    end
+
+    private
+      def prepare_nitro_kit_upgrade_smoke_test
+      end
+
+      def assert_host_installation
+        assert_selector "html head link[rel='stylesheet'][href*='nitro_kit']", visible: :all
+        assert_selector "html head script[data-nk-appearance-default]", visible: :all
+        assert evaluate_script("typeof window.Turbo !== 'undefined'"), "Turbo did not load through the host JavaScript entrypoint"
+      end
+
+      def track_turbo_submissions
+        execute_script <<~JAVASCRIPT
+          window.__nitroKitUpgradeSmokeTurboSubmissions = 0
+          document.addEventListener("turbo:submit-end", () => {
+            window.__nitroKitUpgradeSmokeTurboSubmissions += 1
+          })
+        JAVASCRIPT
+      end
+
+      def assert_stable_frame
+        assert_selector "turbo-frame##{UpgradeSmoke::FRAME_ID}", count: 1
+      end
+
+      def assert_no_unexpected_console_errors
+        browser = page.driver.browser
+        return unless browser.respond_to?(:logs)
+
+        logs = browser.logs
+        return unless logs.available_types.map(&:to_s).include?("browser")
+
+        unexpected = logs.get(:browser).select { |entry| entry.level.to_s == "SEVERE" }.reject do |entry|
+          entry.message.include?(UpgradeSmoke::PATH) && entry.message.include?("422")
+        end
+        assert_empty unexpected, "Unexpected severe browser console errors: #{unexpected.map(&:message).join("\n")}"
+      rescue StandardError
+        # Browser log collection is driver-specific; interaction assertions remain authoritative.
+      end
+
+      def exercise_overlay(component)
+        root = "#nitro-kit-upgrade-smoke-#{component}"
+        panel = "#{root} [data-slot='#{component}-panel']"
+
+        find("#{root} [data-slot='#{component}-trigger']").click
+        assert_selector "#{panel}[open]"
+        assert_selector "#{panel} [data-slot='#{component}-title']", text: "Upgrade #{component}"
+
+        find("#{panel} [data-slot='#{component}-close']").click
+        assert_no_selector "#{panel}[open]"
+
+        find("#{root} [data-slot='#{component}-trigger']").click
+        execute_script <<~JAVASCRIPT, find(panel)
+          arguments[0].dispatchEvent(new MouseEvent("click", {
+            bubbles: true,
+            clientX: -1,
+            clientY: -1
+          }))
+        JAVASCRIPT
+        assert_no_selector "#{panel}[open]"
+      end
+  end
+end

data/lib/nitro_kit/version.rb

@@ -1,3 +1,3 @@
 module NitroKit
-  VERSION = "0.9.0"
+  VERSION = "2.0.0.alpha.2"
 end

data/lib/nitro_kit.rb

@@ -1,46 +1,9 @@
-require "tailwind_merge"
+require "rails"
 require "phlex/rails"
 
-require "nitro_kit/version"
-require "nitro_kit/engine"
-require "nitro_kit/variants"
-require "nitro_kit/schema_builder"
-
 module NitroKit
-  extend SchemaBuilder
-
-  SCHEMA = build_schema do |s|
-    s.add(:accordion, js: [ :accordion ])
-    s.add(:alert)
-    s.add(:avatar)
-    s.add(:badge)
-    s.add(:button, [ :icon ], components: [ :button, :button_group ], helpers: [ :button, :button_group ])
-    s.add(:card)
-    s.add(:checkbox, [ :label ], components: [ :checkbox, :checkbox_group ])
-    s.add(
-      :combobox,
-      [ :input ],
-      js: [ :combobox ],
-      modules: [ "@floating-ui/core", "@floating-ui/dom", "@github/combobox-nav" ]
-    )
-    s.add(:datepicker)
-    s.add(:dialog, [ :button, :icon ], js: [ :dialog ])
-    s.add(:dropdown, [ :button ], js: [ :dropdown ], modules: [ "@floating-ui/core", "@floating-ui/dom" ])
-    s.add(:field, [ :label, :checkbox, :combobox, :label, :radio_button, :select, :switch, :textarea ])
-    s.add(:field_group)
-    s.add(:fieldset, [ :field_group ])
-    s.add(:form_builder, [ :field ], helpers: [ :form ])
-    s.add(:icon, gems: [ "lucide-rails" ])
-    s.add(:input)
-    s.add(:label)
-    s.add(:pagination, [ :icon, :button ])
-    s.add(:radio_button, [ :label ], components: [ :radio_button, :radio_button_group ])
-    s.add(:select)
-    s.add(:switch, js: [ :switch ])
-    s.add(:table)
-    s.add(:tabs, js: [ :tabs ])
-    s.add(:textarea)
-    s.add(:toast, js: [ :toast ])
-    s.add(:tooltip, js: [ :tooltip ], modules: [ "@floating-ui/core", "@floating-ui/dom" ])
-  end
+  extend Phlex::Kit
 end
+
+require "nitro_kit/version"
+require "nitro_kit/engine"

data/lib/rails/commands/nitro_kit/nitro_kit_command.rb

@@ -0,0 +1,42 @@
+require "rails/command"
+
+module Rails
+  module Command
+    class NitroKitCommand < Base
+      desc "doctor", "Verify the Nitro Kit 2 application and agent integration"
+      def doctor
+        checks = installation.checks
+        checks.each do |check|
+          color = { pass: :green, warn: :yellow, fail: :red }.fetch(check.status)
+          say_status(check.status.to_s.upcase, "#{check.label}: #{check.detail}", color)
+        end
+
+        exit 1 if checks.any? { _1.status == :fail }
+      end
+
+      desc "prompt", "Print the Nitro Kit 2 initialization prompt"
+      option :copy, type: :boolean, default: false,
+        desc: "Copy the prompt to the clipboard"
+      def prompt
+        if options[:copy]
+          command = installation.copy_prompt
+          say "Copied the Nitro Kit 2 initialization prompt via #{command}."
+        else
+          say installation.prompt
+        end
+      rescue RuntimeError => error
+        say_error error.message
+        exit 1
+      end
+
+      private
+        def installation
+          @installation ||= begin
+            boot_application!
+            require "nitro_kit/installation"
+            NitroKit::Installation.new(Rails.root)
+          end
+        end
+    end
+  end
+end

data/lib/tasks/nitro_kit_tasks.rake

@@ -1,4 +1,79 @@
-# desc "Explaining what the task does"
-# task :nitro_kit do
-#   # Task goes here
-# end
+require "fileutils"
+require "pathname"
+require "rake"
+
+extend Rake::DSL
+
+module NitroKit
+  module CssBundle
+    ROOT = Pathname.new(File.expand_path("../..", __dir__))
+    SOURCE_ROOT = ROOT.join("src/stylesheets/nitro_kit")
+    OUTPUT = ROOT.join("app/assets/stylesheets/nitro_kit.css")
+    FOUNDATION_SOURCES = %w[ layers.css tokens.css reset.css ].freeze
+    BANNER = <<~CSS.freeze
+      /*
+       * Nitro Kit 2.0
+       * Generated by `rake nitro_kit:css:build`. Do not edit directly.
+       */
+    CSS
+
+    module_function
+
+    def source_files
+      foundation_sources + component_sources
+    end
+
+    def compile
+      sections = source_files.map do |path|
+        <<~CSS.rstrip
+          /* Source: #{path.relative_path_from(ROOT)} */
+          #{path.read.rstrip}
+        CSS
+      end
+
+      ([ BANNER.rstrip ] + sections).join("\n\n") + "\n"
+    end
+
+    def write
+      css = compile
+
+      return false if OUTPUT.exist? && OUTPUT.read == css
+
+      FileUtils.mkdir_p(OUTPUT.dirname)
+      OUTPUT.write(css)
+      true
+    end
+
+    def current?
+      OUTPUT.exist? && OUTPUT.read == compile
+    end
+
+    def foundation_sources
+      FOUNDATION_SOURCES.map { |name| SOURCE_ROOT.join(name) }
+    end
+
+    def component_sources
+      SOURCE_ROOT.glob("components/**/*.css").sort
+    end
+  end
+end
+
+namespace :nitro_kit do
+  namespace :css do
+    desc "Build the committed Nitro Kit stylesheet"
+    task :build do
+      if NitroKit::CssBundle.write
+        puts "Wrote #{NitroKit::CssBundle::OUTPUT.relative_path_from(NitroKit::CssBundle::ROOT)}"
+      else
+        puts "Nitro Kit CSS is already up to date"
+      end
+    end
+
+    desc "Check that the committed Nitro Kit stylesheet is current"
+    task :check do
+      next if NitroKit::CssBundle.current?
+
+      abort "Nitro Kit CSS is out of date. Run `rake nitro_kit:css:build`."
+    end
+  end
+end

data/plugins/nitro-kit/.codex-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "nitro-kit",
+  "version": "0.2.0",
+  "description": "Build conventional Nitro Kit 2 Rails applications with Phlex and Hotwire.",
+  "author": {
+    "name": "Mikkel Malmberg",
+    "url": "https://nitrokit.dev"
+  },
+  "homepage": "https://nitrokit.dev",
+  "repository": "https://github.com/mikker/nitro_kit",
+  "license": "LicenseRef-NitroKit",
+  "keywords": ["rails", "phlex", "hotwire", "ui"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Nitro Kit",
+    "shortDescription": "Build Rails UI with Nitro Kit and Hotwire",
+    "longDescription": "Model conventional Rails resources, compose Nitro Kit components, and implement Hotwire interactions from the installed gem version.",
+    "developerName": "Mikkel Malmberg",
+    "category": "Developer",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://nitrokit.dev",
+    "defaultPrompt": [
+      "Build this Rails feature on the Nitro Kit Rails path.",
+      "Build this Rails interface with Nitro Kit components.",
+      "Implement this interaction with Nitro Kit and conventional Hotwire."
+    ]
+  }
+}

data/plugins/nitro-kit/skills/nitro-kit-hotwire/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: nitro-kit-hotwire
+description: Implement or refactor Nitro Kit 2 Hotwire interactions using conventional Turbo Drive, Frame, Stream, morph, form, dialog, flash, and toast patterns. Use for CRUD forms, validation, filtering, sorting, pagination, destructive confirmations, inline editing, self-submitting controls, server-rendered notifications, or any Nitro Kit interaction that should work progressively without copied controllers or custom request JavaScript.
+---
+
+# Nitro Kit Hotwire
+
+Make the server response and stable DOM boundary the interaction API. Add Stimulus only for behavior the browser, Rails, and Turbo cannot express.
+
+## Load the matching recipes
+
+1. Work from the Rails application root.
+2. Confirm `nitro_kit` appears in `Gemfile.lock`.
+3. Run `bundle show nitro_kit` and treat its output as `NITRO_KIT_ROOT`.
+4. Read `NITRO_KIT_ROOT/docs/agent_guide.md` completely.
+5. Read `NITRO_KIT_ROOT/docs/hotwire.md`, then only the matching files under `NITRO_KIT_ROOT/docs/patterns/`:
+   - query/filter/sort/paginate: `queryable_collection.md`
+   - create/update/validation: `resource_form.md`
+   - delete/revoke/archive confirmation: `destructive_action.md`
+   - notices/errors after responses: `flash_and_toast.md`
+   - row or panel edit/cancel: `inline_edit.md`
+   - application-wide confirmation and settings forms:
+     `application_foundation.md`
+6. Inspect the installed Nitro component contract used by the recipe. Never assume a recipe from another version still matches.
+
+Do not proceed with a remembered Nitro Kit 1.x API. Do not copy or recreate
+the installed gem's `nk--*` controllers under `app/javascript/controllers/nk`.
+
+## Choose the smallest Hotwire primitive
+
+1. Start with ordinary Rails navigation and forms under Turbo Drive.
+2. Add a Turbo Frame when one stable region has an independent navigation or form lifecycle.
+3. Return Turbo Streams over the request when one action must update multiple existing regions.
+4. Broadcast only when other sessions need the update.
+5. Add an application Stimulus controller only for client-only state or browser behavior not covered above.
+
+Keep frames around complete resource or collection regions, not individual buttons. Derive IDs with Rails `dom_id` or a named constant and use the same identifier in links, forms, responses, and tests.
+
+## Keep response semantics conventional
+
+- Redirect successful non-GET form submissions with `303 See Other`.
+- Render invalid HTML and Turbo submissions with `422 Unprocessable Entity` and the same invalid model instance.
+- Preserve an HTML response branch as the progressive fallback.
+- Let GET query parameters be the source of truth for filtering, sorting, and pagination.
+- Use native Nitro Dialog behavior for reviewed destructive actions. Use `data: { turbo_confirm: ... }` for compact confirmations that do not need a dialog.
+- Render flash through `NitroKit::Toast::FlashMessages`; the application owns setting the flash.
+
+## Preserve ownership
+
+- Nitro owns component markup, CSS, and its focused progressive controllers.
+- Rails owns routes, records, authorization, query policy, validation, DOM identity, and responses.
+- Hotwire owns transport and replacement.
+- Application Stimulus owns only application-specific browser behavior.
+
+Do not create a universal interaction controller, hide server behavior inside a UI component, or use Turbo Streams for a single replacement that a frame already handles.
+
+## Verify end to end
+
+Cover the HTML fallback and Turbo response in request tests. Add a system test when focus, dialog behavior, frame navigation, or multiple DOM updates are central to the interaction. Assert response status and stable frame or target IDs, not Turbo internals.
+
+Some headless browser sessions throttle `requestAnimationFrame`, which Turbo
+uses before rendering a completed visit. If a request succeeds but the page or
+frame never renders only in automation, reproduce it in a Rails system test
+before changing application code. Disable Chrome's background throttling or
+use a test-only `requestAnimationFrame` shim when necessary. Never ship that
+workaround in the application or replace a conventional Turbo flow to satisfy
+one browser driver.

data/plugins/nitro-kit/skills/nitro-kit-hotwire/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Nitro Kit Hotwire"
+  short_description: "Build conventional Nitro Kit Hotwire flows"
+  default_prompt: "Use $nitro-kit-hotwire to build this interaction with Nitro Kit and conventional Hotwire."