phlex-reactive 0.4.8 → 0.9.1

data/lib/phlex/reactive/doctor.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Validates a phlex-reactive install and reports ✓/✗/? per check with a fix
+    # for each failure (issue #106). Five closed issues (#3 boot/eager-load, #26
+    # route shadowing, #42 lost request, #48 unregistered controller, #57
+    # importmap 404) were pure integration papercuts that only surfaced AFTER
+    # something already broke. The doctor turns "nothing happens, why?" into an
+    # actionable checklist you run before/after setup:
+    #
+    #   bin/rails phlex_reactive:doctor
+    #
+    # Every check is a small object answering [status, message, fix]. It is
+    # READ-ONLY — it never mounts a component, mutates state, or touches the
+    # default-deny boundary; the worst it does is a throwaway sign→verify round
+    # trip and (for the component checks) iterate the loaded Streamable registry.
+    class Doctor
+      # The result of one check: a status (:ok/:fail/:unknown), a human message,
+      # and (on anything but :ok) a fix line telling the adopter what to do. A
+      # plain value object (not Data) so it takes positional status/message plus
+      # keyword name:/fix: — the shape the check builders and specs construct.
+      class Check
+        attr_reader :name, :status, :message, :fix
+
+        def initialize(status, message, name: nil, fix: nil)
+          @name = name
+          @status = status
+          @message = message
+          @fix = fix
+        end
+
+        def ok? = status == :ok
+        def fail? = status == :fail
+        def unknown? = status == :unknown
+      end
+
+      # Glyphs are plain ASCII-safe Unicode with NO ANSI color, so CI/log capture
+      # reads cleanly (issue #106 acceptance: stable plain-text output).
+      GLYPHS = { ok: "✓", fail: "✗", unknown: "?" }.freeze
+
+      # The entrypoint the rake task calls: eager-load so the component registry
+      # is populated, print the report, and return TRUE when nothing failed (an
+      # advisory `?` doesn't count) so a caller can gate its exit code on it.
+      # (Not a predicate name — this is the imperative "run + report" action that
+      # happens to return a success boolean; `io` is the conventional stream name.)
+      def self.run(io: $stdout) # rubocop:disable Naming/PredicateMethod,Naming/MethodParameterName
+        ::Rails.application.eager_load! if defined?(::Rails) && ::Rails.application
+        doctor = new
+        io.puts(doctor.report)
+        !doctor.failures?
+      end
+
+      # Run every check and return the ordered list of Check objects, memoized so
+      # report + failures? share one pass. The caller (or Doctor.run) is
+      # responsible for eager_load! so component classes are in the registry —
+      # the component checks are empty otherwise.
+      def checks
+        @checks ||= build_checks
+      end
+
+      # True when any check FAILED (a hard ✗). Advisory `?` lines are not
+      # failures — a Phlex-layout app legitimately can't verify csrf that way.
+      def failures?
+        checks.any?(&:fail?)
+      end
+
+      def build_checks
+        components = registered_components
+        [
+          route_check,
+          stimulus_check,
+          csrf_check,
+          verifier_check,
+          base_controller_check,
+          action_check(components),
+          id_check(components)
+        ]
+      end
+
+      # --- individual checks ------------------------------------------------
+
+      # Does POST <action_path> resolve to the gem's ActionsController? A host
+      # catch-all route shadows it otherwise (issue #26). Reuses the shipped
+      # guard verbatim — it already handles routes-not-yet-drawn.
+      def route_check
+        path = Phlex::Reactive.action_path
+        if Phlex::Reactive.action_route_ok?(path)
+          Check.new(:ok, "POST #{path} routes to #{Doctor.actions_controller}", name: :route)
+        else
+          Check.new(:fail, "POST #{path} does not resolve to #{Doctor.actions_controller}", name: :route,
+            fix: "A host catch-all route (match \"*path\", ...) likely shadows it. Exempt " \
+                 "#{path.delete_prefix("/")} from the catch-all, or set Phlex::Reactive.action_path " \
+                 "to an unshadowed path.")
+        end
+      end
+
+      # Is the generic `reactive` controller registered in a Stimulus entrypoint
+      # (issue #48)? Grep the candidate entrypoints for the register line; when
+      # importmap is present, additionally verify the pin resolves.
+      def stimulus_check
+        entrypoint = stimulus_registration_files.find { registers_reactive?(it) }
+        return stimulus_missing_check unless entrypoint
+
+        if importmap_pin_broken?
+          return Check.new(:fail, "reactive registered in #{relative(entrypoint)}, but the importmap " \
+                                  "pin for phlex/reactive/reactive_controller is missing", name: :stimulus,
+            fix: "The engine auto-pins it; if you overrode config/importmap.rb, add:\n  " \
+                 "pin \"phlex/reactive/reactive_controller\"")
+        end
+
+        Check.new(:ok, "reactive controller registered in #{relative(entrypoint)}", name: :stimulus)
+      end
+
+      # ADVISORY only (issue #106): grep ERB layouts AND Phlex layout files for a
+      # csrf_meta_tags reference. A hard fail would false-flag Phlex-layout apps
+      # (this gem's core audience), so a miss is :unknown, never :fail.
+      def csrf_check
+        if csrf_meta_referenced?
+          Check.new(:ok, "csrf_meta_tags found in a layout", name: :csrf)
+        else
+          Check.new(:unknown, "could not verify csrf_meta_tags in a layout", name: :csrf,
+            fix: "Confirm your layout renders csrf_meta_tags (ERB: <%= csrf_meta_tags %>; " \
+                 "Phlex: render Phlex::Rails::Helpers::CSRFMetaTags or emit the meta tags) — " \
+                 "the client reads the CSRF token from <meta name=\"csrf-token\">.")
+        end
+      end
+
+      # A throwaway sign→verify round trip proves the verifier is configured and
+      # the key round-trips (a bad secret_key_base or a purpose mismatch fails).
+      # verify legitimately stamps the version key "v" (issue #111), so we check
+      # the original entries survived rather than exact equality.
+      def verifier_check
+        payload = { "c" => "Phlex::Reactive::Doctor", "probe" => true }
+        roundtripped = Phlex::Reactive.verify(Phlex::Reactive.sign(payload))
+        if roundtripped && payload.all? { |k, v| roundtripped[k] == v }
+          Check.new(:ok, "identity verifier signs and verifies", name: :verifier)
+        else
+          Check.new(:fail, "identity verifier did not round-trip a probe payload", name: :verifier,
+            fix: "Check secret_key_base is set, or configure a dedicated " \
+                 "Phlex::Reactive.verifier = ActiveSupport::MessageVerifier.new(key).")
+        end
+      rescue => e # rubocop:disable Style/RescueStandardError
+        Check.new(:fail, "identity verifier raised: #{e.message}", name: :verifier,
+          fix: "Set secret_key_base, or configure Phlex::Reactive.verifier explicitly.")
+      end
+
+      # Does Phlex::Reactive.base_controller_name constantize (issue #48-adjacent)?
+      def base_controller_check
+        name = Phlex::Reactive.base_controller_name
+        klass = Phlex::Reactive.base_controller
+        Check.new(:ok, "base_controller_name #{name} constantizes to #{klass}", name: :base_controller)
+      rescue => e # rubocop:disable Style/RescueStandardError
+        Check.new(:fail, "base_controller_name #{Phlex::Reactive.base_controller_name.inspect} " \
+                         "does not constantize (#{e.class})", name: :base_controller,
+          fix: "Set Phlex::Reactive.base_controller_name to a controller that exists " \
+               "(e.g. \"ApplicationController\").")
+      end
+
+      # Every declared `action :name` must have a public instance method (mirrors
+      # the endpoint's public_send dispatch — a missing one 500s at click).
+      def action_check(components)
+        missing = components.flat_map { missing_action_methods(it) }
+        return Check.new(:ok, "every declared action has a public method", name: :actions) if missing.empty?
+
+        Check.new(:fail, "declared actions with no matching public method: #{missing.join(", ")}", name: :actions,
+          fix: "Define a public method for each, or remove the `action :name` declaration.")
+      end
+
+      # Flag a class that would raise NotImplementedError in #id at render: it
+      # inherits Streamable's default #id AND is NOT record-backed. A record-backed
+      # class on the default is FINE — that default shipped in #81.
+      def id_check(components)
+        offenders = components.select { default_id_without_record?(it) }.map(&:name)
+        return Check.new(:ok, "every component resolves a stable #id", name: :ids) if offenders.empty?
+
+        Check.new(:fail, "state-backed components with no #id (render raises NotImplementedError): " \
+                         "#{offenders.join(", ")}", name: :ids,
+          fix: "Add `def id = \"my-thing\"` to each — a state-backed component has no record to " \
+               "derive a default id from.")
+      end
+
+      # --- rendering --------------------------------------------------------
+
+      # The full plain-text report: a line per check, plus an indented fix under
+      # each non-passing one. No ANSI color (clean CI/log capture).
+      def report
+        lines = ["phlex-reactive doctor", ""]
+        results = checks
+        results.each { lines << render_check(it) }
+        lines << ""
+        lines << summary_line(results)
+        lines.join("\n")
+      end
+
+      # One check as "✓/✗/? message" plus an indented "→ fix" when it isn't ok.
+      def render_check(check)
+        line = "#{GLYPHS.fetch(check.status)} #{check.message}"
+        line += "\n    → #{check.fix}" if check.fix && !check.ok?
+        line
+      end
+
+      def self.actions_controller
+        "phlex/reactive/actions"
+      end
+
+      private
+
+      # A one-line tally: how many passed, failed, and are advisory/unknown.
+      def summary_line(results)
+        passed = results.count(&:ok?)
+        failed = results.count(&:fail?)
+        advisory = results.count(&:unknown?)
+        parts = ["#{passed} passed"]
+        parts << "#{failed} failed" if failed.positive?
+        parts << "#{advisory} advisory" if advisory.positive?
+        parts.join(", ")
+      end
+
+      # The registry filtered to real, CONSTANT-RESOLVABLE reactive components.
+      # A class is only invokable by the endpoint if its own name round-trips
+      # through safe_constantize (that's exactly how ActionsController#resolve_component
+      # rebuilds it from the token). So we validate only classes where
+      # name.safe_constantize is the class itself — which also excludes anonymous
+      # classes (name nil) and test fixtures that fake `def self.name` without a
+      # matching constant, keeping the whole-app scan honest.
+      def registered_components
+        Phlex::Reactive::Streamable.registered_classes.select { constant_backed_component?(it) }
+      end
+
+      def constant_backed_component?(klass)
+        reactive_component?(klass) && klass.name && klass.name.safe_constantize.equal?(klass)
+      rescue StandardError
+        false
+      end
+
+      def reactive_component?(klass)
+        klass.respond_to?(:reactive_actions) && klass.include?(Phlex::Reactive::Component)
+      rescue StandardError
+        false
+      end
+
+      # "Klass#action" for every declared action on `klass` that has no public
+      # method to dispatch to. Kept as its own method (not a nested block) so the
+      # class is a named method arg, not a shadowed `it`.
+      def missing_action_methods(klass)
+        klass.reactive_actions.keys
+          .reject { klass.public_method_defined?(it) }
+          .map { "#{klass}##{it}" }
+      end
+
+      # True when the class still uses Streamable's default #id AND has no record
+      # to back it (so the default raises). owner == Streamable means no override.
+      def default_id_without_record?(klass)
+        klass.instance_method(:id).owner == Phlex::Reactive::Streamable &&
+          !(klass.respond_to?(:reactive_record_key) && klass.reactive_record_key)
+      rescue StandardError
+        false
+      end
+
+      def stimulus_missing_check
+        Check.new(:fail, "the reactive controller is not registered in any Stimulus entrypoint", name: :stimulus,
+          fix: "Add to your entrypoint (e.g. app/javascript/controllers/index.js):\n  " \
+               "import ReactiveController from \"phlex/reactive/reactive_controller\"\n  " \
+               "application.register(\"reactive\", ReactiveController)\n" \
+               "or re-run: bin/rails generate phlex:reactive:install")
+      end
+
+      # Files that may hold the register line: the JS entrypoint candidates,
+      # importmap-style AND esbuild/bun (issue #106) — controllers/index.js,
+      # controllers/application.js, application.js — PLUS ERB layouts, since a
+      # small/importmap app often registers inline in <head> rather than in a
+      # dedicated entrypoint file. Only existing files are returned.
+      def stimulus_registration_files
+        candidates = %w[
+          app/javascript/controllers/index.js
+          app/javascript/controllers/application.js
+          app/javascript/application.js
+        ].map { app_path(it) }
+        candidates += ::Dir.glob(app_path("app/views/layouts/**/*.erb"))
+        candidates.select { File.exist?(it) }
+      end
+
+      def registers_reactive?(path)
+        File.read(path).include?('application.register("reactive", ReactiveController)')
+      rescue StandardError
+        false
+      end
+
+      # Only meaningful when importmap is in use. True when importmap is present
+      # but the reactive_controller pin is absent (the engine pins it, so this is
+      # really "someone overrode importmap.rb and dropped the pin").
+      def importmap_pin_broken?
+        return false unless defined?(::Importmap) && ::Rails.application.respond_to?(:importmap)
+
+        map = ::Rails.application.importmap
+        return false unless map
+
+        !map.packages.key?("phlex/reactive/reactive_controller")
+      rescue StandardError
+        false
+      end
+
+      # Grep ERB layouts AND Phlex layout files for a csrf_meta_tags reference.
+      def csrf_meta_referenced?
+        globs = %w[
+          app/views/**/*.erb
+          app/views/**/*.rb
+          app/components/**/*.rb
+          app/views/**/layout*.html*
+        ].map { app_path(it) }
+
+        ::Dir.glob(globs).any? do
+          File.read(it).include?("csrf_meta_tags")
+        rescue StandardError
+          false
+        end
+      rescue StandardError
+        false
+      end
+
+      def app_path(relative)
+        ::Rails.root.join(relative).to_s
+      end
+
+      def relative(path)
+        return path unless defined?(::Rails) && ::Rails.root
+
+        path.delete_prefix("#{::Rails.root}/")
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -19,15 +19,21 @@ module Phlex
         end
       end
 
-      # Make reactive_controller.js available to Propshaft/Sprockets so it can
-      # be included via the asset pipeline or pinned in importmap.
+      # Make the MINIFIED client build available to Propshaft/Sprockets so it can
+      # be fingerprinted, served, and pinned in importmap. The browser ships the
+      # minified twin (108 KB -> 22 KB for the controller; `rake build:js`), not
+      # the comment-dense source. The .min.js.map is precompiled too so devtools
+      # resolves the linked sourcemap back to the readable source on demand.
       initializer "phlex_reactive.assets" do
         if it.config.respond_to?(:assets)
           it.config.assets.paths << root.join("app/javascript").to_s
           it.config.assets.precompile += %w[
-            phlex/reactive/reactive_controller.js
-            phlex/reactive/confirm.js
-            phlex/reactive/compute.js
+            phlex/reactive/reactive_controller.min.js
+            phlex/reactive/reactive_controller.min.js.map
+            phlex/reactive/confirm.min.js
+            phlex/reactive/confirm.min.js.map
+            phlex/reactive/compute.min.js
+            phlex/reactive/compute.min.js.map
           ]
         end
       end
@@ -39,7 +45,7 @@ module Phlex
         if defined?(::Importmap::Map) && it.respond_to?(:importmap)
           it.importmap.pin(
             "phlex/reactive/reactive_controller",
-            to: "phlex/reactive/reactive_controller.js",
+            to: "phlex/reactive/reactive_controller.min.js",
             preload: true
           )
           # The overridable confirm resolver (issue #55). reactive_controller.js
@@ -52,7 +58,7 @@ module Phlex
           # "phlex/reactive/confirm"` both resolve through the import map.
           it.importmap.pin(
             "phlex/reactive/confirm",
-            to: "phlex/reactive/confirm.js",
+            to: "phlex/reactive/confirm.min.js",
             preload: true
           )
           # The client-side compute (data-binding) registry behind
@@ -62,7 +68,7 @@ module Phlex
           # "phlex/reactive/compute"` — both resolve through this pin.
           it.importmap.pin(
             "phlex/reactive/compute",
-            to: "phlex/reactive/compute.js",
+            to: "phlex/reactive/compute.min.js",
             preload: true
           )
         end
@@ -74,7 +80,7 @@ module Phlex
       # fresh after boot. See Streamable.reset_all_view_contexts!.
       config.to_prepare do
         Phlex::Reactive::Streamable.reset_all_view_contexts!
-        Phlex::Reactive.reset_flash_builder!
+        Phlex::Reactive.reset_stream_builder!
       end
 
       # Boot-time guard (issue #26): warn if the action path doesn't resolve to
@@ -84,6 +90,18 @@ module Phlex
       # a one-line log pointing at the cause. No-op when the route is fine.
       config.after_initialize do
         Phlex::Reactive.warn_unless_action_route_mounted!
+
+        # Attach the opt-in LogSubscriber (issue #107) exactly once, only when
+        # the app enabled it. attach_to is idempotent-safe here because this runs
+        # once per boot; the events fire for APMs regardless of this flag.
+        Phlex::Reactive::LogSubscriber.attach_to(:phlex_reactive) if Phlex::Reactive.log_events
+
+        # Freeze the param-type registry (issue #109): custom types register in
+        # an initializer, which has run by now, so no further registration is
+        # accepted. A schema referencing a type is validated at declaration; the
+        # frozen registry makes runtime registration a loud error rather than a
+        # never-validated type. Idempotent.
+        Phlex::Reactive.freeze_param_types!
       end
     end
   end

data/lib/phlex/reactive/js.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # An immutable, chainable builder of client-side DOM commands (issue #95) —
+    # the ops behind Component#on_client. Each verb returns a NEW frozen
+    # instance; #to_json emits the wire format the generic controller's runOps
+    # action interprets, entirely in the browser:
+    #
+    #   button(**on_client(:click, js.toggle("#menu"))) { "Menu" }
+    #   # -> data-reactive-ops-param='[["toggle",{"to":"#menu"}]]'
+    #
+    # These are declarative DOM OPERATIONS, not state: nothing is shipped back
+    # to the server, nothing is trusted from the client, and any server
+    # re-render of the component resets whatever they toggled (the LiveView
+    # JS-commands caveat — by design; use a signed action for state that must
+    # survive re-renders).
+    #
+    # Targets: a CSS selector string is resolved WITHIN the component's root by
+    # default (nested reactive roots excluded, issue #15 semantics); `:root`
+    # targets the root element itself; `global: true` opts a single op out of
+    # root scoping (document escape hatch, e.g. a page-level overlay).
+    #
+    # The op vocabulary is a fixed whitelist mirrored by the client interpreter
+    # — an op name the client doesn't know is warn-and-skipped there
+    # (client-side default-deny). Validation here is deliberately LOUD: a bad
+    # target or an empty class list raises at render time rather than silently
+    # doing nothing in the browser.
+    class JS
+      # Serialized stand-in for "the component's own root element".
+      ROOT_SENTINEL = "@root"
+
+      # The attribute-name allowlist (issue #96) — the security-critical part of
+      # the attr ops, enforced HERE at build time AND again in the client
+      # interpreter (two-sided default-deny: a hand-built ops attr must not
+      # bypass it either). Rejected:
+      #   * /\Aon/i        — event-handler attributes (onclick, onmouseover) → XSS.
+      #   * the URL set     — href/src/srcdoc/action/formaction/xlink:href can carry
+      #                       a `javascript:` payload; setting them from client ops
+      #                       is a navigation/injection surface, not a UI toggle.
+      #   * style           — inline CSS injection; use classes (add_class/...).
+      # The INTENDED surface is class ops plus boolean/state attributes:
+      #   hidden, disabled, open, selected, aria-*, data-*.
+      URL_BEARING_ATTRS = %w[href src srcdoc action formaction xlink:href].freeze
+      EVENT_HANDLER_ATTR = /\Aon/i
+
+      # The attr ops whose args carry a "name" the allowlist must gate. Used to
+      # re-validate a RAW [op, args] list (the js([...]) / broadcast_js_to([...])
+      # escape hatch) that skips the builder's build-time attr_args check.
+      ATTR_NAME_OPS = %w[set_attr remove_attr toggle_attr].freeze
+
+      # Validate a raw ops list ([[op, args], ...] as passed to js/broadcast_js_to
+      # without the builder) against the attribute allowlist, so the escape hatch
+      # gets the SAME server-side default-deny as the JS chain (defense in depth;
+      # the client also enforces it). Non-attr ops and malformed entries pass
+      # through untouched — the client interpreter default-denies unknown ops.
+      def self.assert_ops_allowed!(list)
+        Array(list).each do |op, args|
+          next unless ATTR_NAME_OPS.include?(op.to_s) && args.is_a?(::Hash)
+
+          name = args["name"] || args[:name]
+          assert_allowed_attr(name.to_s) if name
+        end
+      end
+
+      # The attribute-name allowlist (issue #96), case-insensitive. Refuses
+      # event-handler (on*), URL-bearing, and style attributes. Enforced at build
+      # time by the instance builder AND on the raw-list escape hatch — two-sided
+      # default-deny with the client interpreter.
+      def self.assert_allowed_attr(name)
+        lower = name.downcase
+        if name.match?(EVENT_HANDLER_ATTR)
+          raise ArgumentError,
+            "#{self}: attribute #{name.inspect} is an event handler (on*) — refused (XSS). " \
+            "Client attr ops target hidden/disabled/open/selected/aria-*/data-* and classes."
+        end
+        return unless URL_BEARING_ATTRS.include?(lower) || lower == "style"
+
+        raise ArgumentError,
+          "#{self}: attribute #{name.inspect} is refused — URL-bearing attributes " \
+          "(#{URL_BEARING_ATTRS.join(", ")}) and `style` can't be set from client ops " \
+          "(injection surface). Use classes for styling; target aria-*/data-*/boolean attrs."
+      end
+
+      # The accumulated [name, args] op pairs, oldest first. Frozen.
+      attr_reader :ops
+
+      def initialize(ops = [].freeze)
+        @ops = ops
+        freeze
+      end
+
+      # --- Visibility (the `hidden` attribute) ---
+      #
+      # `transition:` (issue #96) — an optional [during, from, to] class triple
+      # animated around the visibility flip: `during`+`from` are applied, then on
+      # the next frame `from`→`to` swaps, and the whole set is awaited via
+      # `animationend` (with a setTimeout fallback so a non-animated element never
+      # hangs the op chain). Omit it for the instant flip.
+
+      def show(to, global: false, transition: nil)
+        append("show", target_args(to, global:, transition:))
+      end
+
+      def hide(to, global: false, transition: nil)
+        append("hide", target_args(to, global:, transition:))
+      end
+
+      def toggle(to, global: false, transition: nil)
+        append("toggle", target_args(to, global:, transition:))
+      end
+
+      # --- Classes ---
+
+      def add_class(to, *classes, global: false)
+        append("add_class", class_args(to, classes, global:))
+      end
+
+      def remove_class(to, *classes, global: false)
+        append("remove_class", class_args(to, classes, global:))
+      end
+
+      def toggle_class(to, *classes, global: false)
+        append("toggle_class", class_args(to, classes, global:))
+      end
+
+      # --- Attributes (issue #96) — allowlisted names only ---
+      #
+      # set_attr(to, name, value) / remove_attr(to, name) / toggle_attr(to, name).
+      # The value is stringified (a Phlex-style flag rides as the string "true",
+      # never a valueless attribute). The name is checked against the allowlist at
+      # build time — an event-handler, URL-bearing, or style name raises here.
+
+      def set_attr(to, name, value, global: false)
+        append("set_attr", attr_args(to, name, global:, value:))
+      end
+
+      def remove_attr(to, name, global: false)
+        append("remove_attr", attr_args(to, name, global:))
+      end
+
+      def toggle_attr(to, name, global: false)
+        append("toggle_attr", attr_args(to, name, global:))
+      end
+
+      # --- Focus (issue #96) ---
+      #
+      # focus(to)        — focus the FIRST match of the selector.
+      # focus_first(to)  — focus the first FOCUSABLE DESCENDANT of the match
+      #                    (e.g. focus the first menuitem inside an opened menu).
+
+      def focus(to, global: false)
+        append("focus", target_args(to, global:))
+      end
+
+      def focus_first(to, global: false)
+        append("focus_first", target_args(to, global:))
+      end
+
+      # --- Dispatch a bubbling CustomEvent (issue #96) ---
+      #
+      # dispatch(name, to: nil, detail: {}) — emit a bubbling CustomEvent so other
+      # components/controllers can react to a client-only interaction without a
+      # round trip. `to:` picks the element to dispatch ON (nil → the component
+      # root, serialized as the @root sentinel so the client resolves it
+      # uniformly); `detail:` is the event's `detail` payload. The client uses raw
+      # element.dispatchEvent — the shared controller SHADOWS Stimulus's
+      # this.dispatch helper, so the interpreter must not use it.
+      def dispatch(name, to: nil, detail: {}, global: false)
+        args = { "name" => name.to_s, "to" => normalize_target(to.nil? ? :root : to), "detail" => detail }
+        args["global"] = true if global
+        append("dispatch", args.freeze)
+      end
+
+      # The wire format: a JSON array of [op, args] pairs, applied in order.
+      def to_json(*)
+        @ops.to_json
+      end
+
+      def empty?
+        @ops.empty?
+      end
+
+      private
+
+      # Immutability: every verb funnels here and returns a NEW frozen chain —
+      # a builder held in a constant or memo can never be mutated by later use.
+      def append(name, args)
+        self.class.new([*@ops, [name, args].freeze].freeze)
+      end
+
+      def target_args(to, global:, transition: nil)
+        args = { "to" => normalize_target(to) }
+        args["global"] = true if global
+        args["transition"] = normalize_transition(transition) if transition
+        args.freeze
+      end
+
+      # An attr op's args: the target, the allowlisted name, an optional
+      # (stringified) value. The name is validated LOUDLY at build time.
+      def attr_args(to, name, global:, value: :__none)
+        name = name.to_s
+        assert_allowed_attr(name)
+        args = { "to" => normalize_target(to), "name" => name }
+        args["value"] = value.to_s unless value == :__none
+        args["global"] = true if global
+        args.freeze
+      end
+
+      # Build-time attr-name allowlist for the instance builder — delegates to the
+      # shared class-method check (also used by the raw-list escape hatch).
+      def assert_allowed_attr(name)
+        self.class.assert_allowed_attr(name)
+      end
+
+      # A transition must be exactly [during, from, to] class lists (strings).
+      def normalize_transition(transition)
+        list = Array(transition)
+        unless list.size == 3
+          raise ArgumentError,
+            "#{self.class}: transition: must be [during, from, to] class lists, got #{transition.inspect}"
+        end
+
+        list.map(&:to_s).freeze
+      end
+
+      def class_args(to, classes, global:)
+        if classes.empty?
+          raise ArgumentError, "#{self.class}: a class op needs at least one class (got none for #{to.inspect})"
+        end
+
+        args = { "to" => normalize_target(to), "classes" => classes.map(&:to_s).freeze }
+        args["global"] = true if global
+        args.freeze
+      end
+
+      # :root -> the sentinel; a String passes through as a CSS selector.
+      # Anything else (a stray symbol, nil) is a bug at the call site — raise at
+      # render time instead of silently matching nothing in the browser.
+      def normalize_target(to)
+        return ROOT_SENTINEL if to == :root
+        return to if to.is_a?(String)
+
+        raise ArgumentError,
+          "#{self.class}: target must be :root or a CSS selector string, got #{to.inspect}"
+      end
+    end
+  end
+end