phlex-reactive 0.9.4 → 0.10.0

data/lib/phlex/reactive/client_bindings.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The blessed CLIENT-ONLY include (issue #180). A view that only shows/hides
+    # (reactive_show), filters (reactive_filter), computes client-side
+    # (reactive_compute), or runs zero-round-trip ops (on_client/js) — with NO
+    # server actions and NO signed token — includes this instead of the full
+    # Phlex::Reactive::Component.
+    #
+    # Why it exists: including the full Component pulls in Streamable, whose
+    # class/instance methods (replace/update/append/prepend/remove,
+    # to_stream_*) collide by NAME with an app's own Turbo-stream concern — so
+    # adopters cherry-picked an internal module and hand-rolled a token-less root
+    # (and defined a dummy #id "never read at render" just to keep
+    # phlex_reactive:doctor quiet). ClientBindings is that missing seam, blessed:
+    #
+    #   class ExerciseFilter < ApplicationComponent
+    #     include Phlex::Reactive::ClientBindings
+    #
+    #     reactive_scope :form
+    #     def reactive_values = { role: @role }
+    #
+    #     def view_template
+    #       div(**reactive_root) do              # token-less: no #id required
+    #         select(name: "form[role]") { role_options }
+    #         div(**reactive_show(if: { role: "individual" })) { demographics }
+    #       end
+    #     end
+    #   end
+    #
+    # It includes the DECLARATION DSL and the view Helpers, but NOT Streamable
+    # (nothing to clobber) or Identity (no token). So a ClientBindings class never
+    # enters Streamable.registered_classes and is invisible to
+    # phlex_reactive:doctor's #id check — no dummy #id, no nag.
+    #
+    # The client-only DSL macros (reactive_scope, reactive_compute) work; the
+    # SERVER-ACTION macros (action, reactive_record, reactive_state) RAISE at
+    # class-definition time — without Identity they could only silently no-op
+    # (sign nothing, dispatch nowhere), so the guard fails loudly (the guard lives
+    # in Component::DSL#require_server_actions!, keyed on Identity presence).
+    #
+    # Helpers is token-tolerant (issue #180): reactive_attrs emits a token only
+    # when reactive_token is available, and reactive_root uses #id only when
+    # defined — so the client-only view helpers work with no Identity/Streamable.
+    #
+    # The full Component includes ClientBindings too (ONE implementation of the
+    # client-only surface), then layers Streamable + Identity on top — so a
+    # token-bearing reactive_root is a SUPERSET, not a fork.
+    module ClientBindings
+      extend ActiveSupport::Concern
+
+      include Component::DSL
+      include Component::Helpers
+    end
+  end
+end

data/lib/phlex/reactive/component/dsl.rb

@@ -29,10 +29,31 @@ module Phlex
         MIRROR_ID_SELECTOR = /\A#[A-Za-z_][\w-]*\z/
 
         class_methods do
+          # Guard the three SERVER-ACTION macros (issue #180). ClientBindings
+          # includes this DSL for its client-only macros (reactive_scope,
+          # reactive_compute) but does NOT include Identity/Streamable — so a
+          # signed token is never minted and no action endpoint dispatches to
+          # this class. Declaring action/reactive_record/reactive_state there
+          # would silently no-op (an action that can never fire, a record that
+          # signs nothing). Fail LOUDLY at class-definition time instead — the
+          # default-deny posture. Keyed on Identity presence: a full
+          # Phlex::Reactive::Component includes it (passes); a ClientBindings-only
+          # class does not (raises).
+          def require_server_actions!(macro)
+            return if include?(Phlex::Reactive::Component::Identity)
+
+            raise ArgumentError,
+              "#{self}: `#{macro}` needs the full Phlex::Reactive::Component — it signs a token / " \
+              "dispatches a server action, which Phlex::Reactive::ClientBindings deliberately omits " \
+              "(client-only: no token, no endpoint). Include Phlex::Reactive::Component for actions, " \
+              "or drop `#{macro}` and use the client-only helpers (reactive_show/filter/compute, on_client)."
+          end
+
           # Declare the ActiveRecord (GlobalID-able) record this component is
           # rebuilt from. The signed token carries its GlobalID; the server
           # re-finds it on each action. State lives in the DB.
           def reactive_record(name)
+            require_server_actions!(:reactive_record)
             Registry.write_scalar(self, :record_key, name.to_sym)
           end
 
@@ -44,9 +65,24 @@ module Phlex
             Registry.resolve_scalar(self, :record_key, :reactive_record_key)
           end
 
+          # Declare (with a name) OR read (bare) a form-field NAMESPACE for this
+          # component's bindings (issue #180). With `reactive_scope :form`,
+          # reactive_show / reactive_values use bare symbols (`:director`) and the
+          # client resolves the owned field as `[name="form[director]"]`; the root
+          # emits `data-reactive-scope="form"`. Bare `reactive_scope` reads the
+          # nearest declared scope up the ancestry (nil when none) — the
+          # dual-purpose form matching reactive_compute's getter/setter. A
+          # per-binding raw string field name still passes through unscoped.
+          def reactive_scope(name = nil)
+            return Registry.resolve_scalar(self, :scope, :reactive_scope) if name.nil?
+
+            Registry.write_scalar(self, :scope, name.to_sym)
+          end
+
           # Opt into signed STATE for record-less components only.
           #   reactive_state :count, :open
           def reactive_state(*names)
+            require_server_actions!(:reactive_state)
             Registry.append(self, :state_keys, names.map(&:to_sym))
           end
 
@@ -112,6 +148,7 @@ module Phlex
           # Array params accept BOTH a JSON array and a Rails-style index hash
           # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
           def action(name, params: {})
+            require_server_actions!(:action)
             Registry.write_entry(
               self, :actions, name.to_sym,
               Action.new(name: name.to_sym, params: params, schema: Phlex::Reactive::ParamSchema.compile(params))

data/lib/phlex/reactive/component/helpers.rb

@@ -73,16 +73,24 @@ module Phlex
         # signed identity token. Spread onto the root:
         #   div(id:, **reactive_attrs) { ... }
         def reactive_attrs
-          data = {
-            controller: "reactive",
-            reactive_token_value: reactive_token
-          }
+          data = { controller: "reactive" }
+          # A CLIENT-ONLY component (Phlex::Reactive::ClientBindings, issue #180)
+          # has no Identity, so no token — the root is tokenless (show/filter/
+          # compute need no signed round trip). reactive_token is private, so the
+          # include-private `respond_to?` mirrors to_stream_token's guard.
+          data[:reactive_token_value] = reactive_token if respond_to?(:reactive_token, true)
           # Client debug mode (issue #108): stamp the flag so the generic controller
           # console.groups every dispatch. STRING "true", not boolean — Phlex renders
           # a boolean-true attr VALUELESS, which getAttribute reads as "" (falsy in
           # JS), so the client's attr check would never fire (the on()/warn_unsaved
           # precedent). Off by default → no key, no string, zero client surface.
           data[:reactive_debug] = "true" if Phlex::Reactive.debug
+          # Field-name scope (issue #180): the client prefixes bare binding field
+          # names with `scope[...]`. Omitted entirely when undeclared — byte-stable
+          # wire for unscoped components.
+          if self.class.respond_to?(:reactive_scope) && (scope = self.class.reactive_scope)
+            data[:reactive_scope] = scope.to_s
+          end
           { data: }
         end
 
@@ -112,11 +120,16 @@ module Phlex
         # guard (STRING "true" — a boolean-true attr renders valueless, which the
         # client's param reader sees as "" → falsy).
         def reactive_root(**overrides)
-          root_id = overrides.delete(:id) || id
+          # A CLIENT-ONLY component (ClientBindings, issue #180) needs no #id —
+          # there's no token to self-match by id. Use an explicit override, else
+          # #id when the component defines one, else nothing (no id attr).
+          root_id = overrides.delete(:id)
+          root_id = id if root_id.nil? && respond_to?(:id)
           track_dirty = overrides.delete(:track_dirty)
           warn_unsaved = overrides.delete(:warn_unsaved)
 
-          attrs = mix({ **reactive_attrs }, overrides, { id: root_id })
+          attrs = mix({ **reactive_attrs }, overrides)
+          attrs = mix(attrs, { id: root_id }) unless root_id.nil?
           attrs = mix(attrs, { data: { action: "input->reactive#trackDirty" } }) if track_dirty
           attrs = mix(attrs, { data: { reactive_warn_unsaved: "true" } }) if warn_unsaved
           attrs
@@ -416,45 +429,62 @@ module Phlex
           span(**mix({ data: { reactive_text: name.to_s } }, attrs)) { initial }
         end
 
-        # Value-conditional visibility (issue #161) — the x-show / data-show /
-        # wire:show equivalent, entirely client-side. Spread onto the element to
-        # show/hide; it declares which OWNED field controls it plus ONE literal
-        # predicate, and the generic controller toggles the `hidden` attribute
-        # from the field's CURRENT value on every input/change — no round trip,
-        # no token, no bespoke Stimulus controller:
-        #
-        #   div(**reactive_show(:mode, not: "off"))        { "details" }
-        #   div(**reactive_show(:kind, equals: "premium")) { "premium panel" }
-        #   div(**reactive_show(:size, in: %w[l xl]))      { "surcharge note" }
-        #   div(**reactive_show(:gift, equals: true))      { "gift message" }
-        #
-        # Exactly one predicate — equals:, not:, or in: (a list) — and every
-        # value is STRINGIFIED for a literal match against the field's value
-        # (a checkbox compares its checked state as "true"/"false", so
-        # `equals: true` is the checkbox form; a radio group reads the checked
-        # radio's value). This is a DECLARED LITERAL MATCH, never an expression
-        # — there is no eval surface (default-deny, like the op vocabulary).
-        #
-        # Scope: presentational only, strictly less powerful than the js ops —
-        # it reads an owned field (#15 ownership) and toggles `hidden` on an
-        # owned element. The client seeds visibility at connect and reconciles
-        # after a morph; render the initial `hidden:` yourself (from the same
-        # server state that renders the field) to avoid a first-paint flash.
-        # Extra attrs deep-merge over the binding (mix), like reactive_field.
-        def reactive_show(field, **options)
-          predicates = options.slice(*SHOW_PREDICATE_KEYS)
-          attrs = options.except(*SHOW_PREDICATE_KEYS)
-          unless predicates.size == 1
-            raise ArgumentError,
-              "reactive_show(#{field.inspect}) needs exactly one predicate — equals:, not:, or " \
-              "in: — got #{predicates.keys.inspect}"
-          end
-
-          key, value = normalize_show_predicate(predicates, "reactive_show(#{field.inspect})").first
-          data = { reactive_show_field: field.to_s }
-          data[:"reactive_show_#{key}"] = key == "in" ? value.to_json : value
-
-          mix({ data: }, attrs)
+        # Value-conditional visibility (issue #180) — the x-show / data-show /
+        # wire:show equivalent, entirely client-side, in ONE Ruby-native
+        # conditions language. Spread onto the element to show/hide; declare an
+        # if:/if_any:/unless: condition with where-style values, and the generic
+        # controller toggles `hidden` from the fields' CURRENT values on every
+        # input/change — no round trip, no token, no bespoke Stimulus controller.
+        #
+        # THE VALUE LANGUAGE (Phlex::Reactive::ShowConditions):
+        #   Hash    = AND (multiple keys ANDed)          if: { a: "x", b: "y" }
+        #   Array   = membership                          if: { size: %w[l xl] }
+        #   Range   = threshold (10.. / ..10 / ...10 / 10..20)  if: { qty: 10.. }
+        #   true/false = checkbox checked-state           if: { gift: true }
+        #   nil     = blank                               if: { note: nil }
+        #   unless: = negation (composes with if:/if_any:)
+        #
+        #   div(**reactive_show(unless: { mode: "off" }))          { "details" }
+        #   div(**reactive_show(if: { size: %w[l xl] }))           { "surcharge" }
+        #   div(**reactive_show(if: { qty: 10.. }))                { "bulk note" }
+        #   # OR-of-AND — director OR (shareholder AND role == "individual"):
+        #   div(**reactive_show(if_any: [
+        #     { director: true },
+        #     { shareholder: true, role: "individual" }
+        #   ]))
+        #
+        # There is no expression surface — every term is a declared literal, so
+        # the same default-deny posture as before. Everything normalizes to ONE
+        # DNF wire attr (data-reactive-show='{"any":[[term,…],…]}').
+        #
+        # FIRST PAINT is computed for you: declare reactive_values (an instance
+        # method returning { field => value }) and every binding whose fields are
+        # all provided renders the correct initial `hidden:` server-side — no
+        # per-section mirror method, no flash. An explicit `hidden:` always wins;
+        # a per-call `values:` override merges over reactive_values.
+        #
+        # `disable: true` disables the section's OWNED controls while it is hidden
+        # so a switched-away value never submits. `reactive_scope :form` lets
+        # bindings use bare field symbols ([name="form[field]"] on the client).
+        #
+        # Scope: presentational only, strictly less powerful than the js ops — it
+        # reads owned fields (#15 ownership) and toggles `hidden` (+ optionally
+        # `disabled`) on owned elements. Extra attrs deep-merge over the binding
+        # (mix), like reactive_field.
+        def reactive_show(field = nil, **options)
+          reject_legacy_show_surface!(field, options)
+
+          conditions = options.slice(*SHOW_CONDITION_KEYS)
+          disable = options.delete(:disable)
+          values_override = options.delete(:values)
+          attrs = options.except(*SHOW_CONDITION_KEYS)
+
+          groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          data = { reactive_show: { "any" => groups }.to_json }
+          data[:reactive_show_disable] = "true" if disable
+
+          result = mix({ data: }, attrs)
+          apply_first_paint_hidden(result, groups, values_override)
         end
 
         # Client-side option filtering for the searchable combobox (issue #163)
@@ -527,33 +557,35 @@ module Phlex
         # reactive_root — the client reads it off the controller element):
         #
         #   div(**mix(reactive_root, reactive_show_targets(:mode,
-        #     "#advanced-tab"   => { equals: "advanced" },
-        #     "#advanced-panel" => { equals: "advanced" },
-        #     "#basic-note"     => { not: "advanced" })))
+        #     "#advanced-tab"   => "advanced",          # equals
+        #     "#advanced-panel" => "advanced",
+        #     "#premium-note"   => %w[gold platinum]))) # membership
         #
         # Same posture as mirror: — opt-in and declared, never implicit (a plain
         # reactive_show stays root-isolated); targets are SINGLE ID SELECTORS
         # only, enforced here at declare time AND warn-and-skipped by the client
-        # interpreter (two-sided default-deny); the predicate is the same
-        # literal-only reactive_show vocabulary (exactly one of equals:/not:/
-        # in:, no expressions); and the toggle is `hidden` only — no innerHTML,
-        # no attribute freedom. The FIELD read stays owned (#15): you can only
-        # drive outside visibility from a field this root owns. A target id not
-        # on the page is silently skipped (an unrendered tab pane is normal).
+        # interpreter (two-sided default-deny); the value uses the same where-
+        # style conditions vocabulary (scalar/Array/Range, no expressions); and
+        # the toggle is `hidden` only — no innerHTML, no attribute freedom. The
+        # FIELD read stays owned (#15): you can only drive outside visibility from
+        # a field this root owns. A target id not on the page is silently skipped
+        # (an unrendered tab pane is normal). A target value is positive-only (no
+        # per-target unless:) — express "not X" as a membership Array over the
+        # remaining options.
         #
         # ONE call per root. Phlex `mix` space-joins duplicate STRING data
         # values, so a second call's JSON would concatenate into an unparseable
         # attr and the client would drop BOTH maps (it warns when that
         # happens). Several fields therefore go in ONE call via the hash form:
         #
-        #   reactive_show_targets(mode: { "#advanced-tab" => { equals: "advanced" } },
-        #                         kind: { "#premium-note" => { not: "basic" } })
+        #   reactive_show_targets(mode: { "#advanced-tab" => "advanced" },
+        #                         kind: { "#premium-note" => %w[gold platinum] })
         def reactive_show_targets(field, targets = nil)
           field_maps = targets.nil? ? field : { field => targets }
           unless field_maps.is_a?(Hash) && field_maps.any?
             raise ArgumentError,
               "reactive_show_targets needs at least one target " \
-              "(:field, \"#id\" => { equals:/not:/in: ... }), got #{field_maps.inspect}"
+              "(:field, \"#id\" => value), got #{field_maps.inspect}"
           end
 
           normalized = field_maps.to_h do |name, map|
@@ -658,12 +690,17 @@ module Phlex
           reactive_record_for_nested.update!(**nested_attributes(association, attrs), **extra)
         end
 
-        # The declared reactive_show predicates (issue #161): a literal match on
-        # the controlling field's current value. Exactly one per binding —
-        # enforced loudly at render (a dead binding must not no-op in the
-        # browser). `not`/`in` are Ruby keywords, so they arrive via **options
-        # rather than named kwargs.
-        SHOW_PREDICATE_KEYS = %i[equals not in].freeze
+        # The conditions-language kwargs (issue #180): if:/if_any:/unless: —
+        # compiled by Phlex::Reactive::ShowConditions into the DNF wire. The ONE
+        # vocabulary; there are no predicate kwargs any more.
+        SHOW_CONDITION_KEYS = %i[if if_any unless].freeze
+
+        # The removed 0.9.5 surface (issue #180 clean break): each of these
+        # kwargs — and a positional field — now raises a GUIDED error printing
+        # the if:/if_any:/unless: rewrite. Kept only to detect the legacy call
+        # shape; nothing here reaches the wire.
+        LEGACY_SHOW_PREDICATE_KEYS = %i[equals not in gte gt lte lt].freeze
+        LEGACY_SHOW_CONNECTIVE_KEYS = %i[all any].freeze
 
         # The declared optimistic-hint class ops (issue #98): the cosmetic class
         # vocabulary the client applies instantly and reverts on failure. Enforced
@@ -688,50 +725,110 @@ module Phlex
           selector
         end
 
-        # Normalize + validate ONE field's target map (issue #164): each key a
-        # single id selector (loud raise — the declare-time half of the
-        # two-sided default-deny), each value one literal predicate. Shared by
-        # both reactive_show_targets call forms.
+        # Normalize + validate ONE field's target map (issue #180): each key a
+        # single id selector (loud raise — the declare-time half of the two-sided
+        # default-deny), each value a where-style condition value (scalar/Array/
+        # Range) that compiles to ONE DNF group (terms ANDed). Shared by both
+        # reactive_show_targets call forms.
         def normalize_show_target_map(field, targets)
           unless targets.is_a?(Hash) && targets.any?
             raise ArgumentError,
               "reactive_show_targets(#{field.inspect}) needs at least one target " \
-              "(\"#id\" => { equals:/not:/in: ... }), got #{targets.inspect}"
+              "(\"#id\" => value), got #{targets.inspect}"
           end
 
-          targets.to_h do |selector, predicate|
+          targets.to_h do |selector, value|
             selector = selector.to_s
             unless selector.match?(DSL::MIRROR_ID_SELECTOR)
               raise ArgumentError,
                 "reactive_show_targets(#{field.inspect}) target #{selector.inspect} must be a single " \
                 "ID selector (\"#id\") — cross-root visibility is id-allowlisted, like mirror: (#159)"
             end
+            if value.is_a?(Hash)
+              raise ArgumentError,
+                "reactive_show_targets(#{field.inspect}) target #{selector.inspect}: the { equals: ... } " \
+                "predicate form was removed — pass a bare value (#{selector.inspect} => \"advanced\", " \
+                "=> %w[a b] for a set, => 10.. for a threshold)"
+            end
 
-            context = "reactive_show_targets(#{field.inspect}) target #{selector.inspect}"
-            [selector, normalize_show_predicate(predicate.is_a?(Hash) ? predicate : {}, context)]
+            # A target compiles to ONE group: the field-vs-value condition.
+            groups = Phlex::Reactive::ShowConditions.normalize(if: { field => value })
+            [selector, groups.first]
           end
         end
 
-        # Validate ONE declared literal show predicate (issues #161/#164) and
-        # return its wire form — { "equals" => "v" } / { "not" => "v" } /
-        # { "in" => ["a", …] } (a real array: reactive_show JSON-encodes it into
-        # its own attr; the reactive_show_targets map embeds it directly).
-        # Shared by both helpers so the vocabulary and the loud validation can
-        # never drift. `context` names the call site in the error.
-        def normalize_show_predicate(predicates, context)
-          unless predicates.size == 1 && SHOW_PREDICATE_KEYS.include?(predicates.keys.first)
+        # Reject the removed 0.9.5 reactive_show surface (issue #180 clean break)
+        # with a GUIDED error printing the if:/if_any:/unless: rewrite. A
+        # positional field, a predicate kwarg (equals:/not:/in:/gte:/…), or a
+        # connective (all:/any:) all land here before any conditions parsing.
+        def reject_legacy_show_surface!(field, options)
+          unless field.nil?
+            raise ArgumentError,
+              "reactive_show no longer takes a positional field — the conditions language is " \
+              "keyword-only: reactive_show(if: { #{field}: <value> }) (a Range is a threshold, " \
+              "an Array is a set, unless: negates). See the 0.10 upgrade notes."
+          end
+
+          if (pred = options.keys & LEGACY_SHOW_PREDICATE_KEYS).any?
+            raise ArgumentError,
+              "reactive_show(#{pred.first}: ...) was removed — use the conditions language: " \
+              "reactive_show(if: { field: value }). equals:/not: → if:/unless:, in: → an Array value, " \
+              "gte:/gt:/lte:/lt: → a Range value (10.., ..10, ...10)."
+          end
+          if (conn = options.keys & LEGACY_SHOW_CONNECTIVE_KEYS).any?
+            replacement = conn.first == :all ? "if: { … }" : "if_any: [{ … }, { … }]"
             raise ArgumentError,
-              "#{context} needs exactly one predicate — equals:, not:, or in: — " \
-              "got #{predicates.keys.inspect}"
+              "reactive_show(#{conn.first}: [...]) was removed — use #{replacement}. " \
+              "all: → if: (one AND group); any: → if_any: (OR of AND groups). Terms are now " \
+              "field => value pairs, not { field:, equals: } hashes."
           end
+        end
+
+        # Compute the first-paint `hidden:` from reactive_values (issue #180) so
+        # the author never restates the predicate as a Ruby mirror method. Fires
+        # only when EVERY field the binding references is provided (by
+        # reactive_values, merged under a per-call `values:` override); otherwise
+        # the attrs are returned untouched. An explicit `hidden:` in the caller's
+        # attrs always wins (it survives the mix, so this is a no-op then).
+        def apply_first_paint_hidden(attrs, groups, values_override)
+          return attrs if attrs.key?(:hidden)
 
-          key, value = predicates.first
-          return { key.to_s => value.to_s } unless key == :in
+          provided = show_values(values_override)
+          return attrs if provided.nil?
 
-          list = Array(value).map(&:to_s)
-          raise ArgumentError, "#{context} in: needs at least one value" if list.empty?
+          referenced = Phlex::Reactive::ShowConditions.fields(groups)
+          return attrs unless referenced.all? { provided.key?(it) }
 
-          { "in" => list }
+          visible = Phlex::Reactive::ShowConditions.match?(groups, provided)
+          attrs.merge(hidden: !visible)
+        end
+
+        # The { field => current-string-value } map the first-paint evaluator
+        # reads: reactive_values (if the component declares it) merged under a
+        # per-call values: override, both stringified the way the client reads a
+        # field (checkbox → "true"/"false", nil → ""). nil when neither source
+        # exists — first paint then no-ops (no flash guarantee is the author's,
+        # exactly as before).
+        def show_values(values_override)
+          base = respond_to?(:reactive_values) ? reactive_values : nil
+          return nil if base.nil? && values_override.nil?
+
+          merged = {}
+          merged.merge!(base) if base
+          merged.merge!(values_override) if values_override
+          merged.to_h { |name, value| [name.to_s, show_value_string(value)] }
+        end
+
+        # Stringify a reactive_values entry the way the client's #showFieldValue
+        # reports the live field: a boolean is the checkbox checked-state string,
+        # nil is blank, everything else is to_s.
+        def show_value_string(value)
+          case value
+          when true then "true"
+          when false then "false"
+          when nil then ""
+          else value.to_s
+          end
         end
 
         # True when the hint declares checked: :keep — the click-bound

data/lib/phlex/reactive/component/registry.rb

@@ -51,6 +51,8 @@ module Phlex
           collections: :@reactive_own_collections,
           computes: :@reactive_own_computes,
           record_key: :@reactive_own_record_key,
+          # Form-field namespace — reactive_scope (issue #180).
+          scope: :@reactive_own_scope,
           # Deferred reply segments — reactive_lazy (issue #165).
           lazy: :@reactive_own_lazy,
           # verify_authorized opt-out (issue #168): a scalar bare flag (skip the

data/lib/phlex/reactive/component.rb

@@ -57,13 +57,24 @@ module Phlex
     #     end
     #   end
     #
-    # Assembled from three cohesive concerns (issue #115) — one include, zero
-    # public API change:
-    #   * Component::DSL      — the five declaration registries (via
-    #     Component::Registry) + from_identity
-    #   * Component::Identity — reactive_token + the hot-path ivar precomputation
-    #   * Component::Helpers  — reply/js, reactive_attrs/root, on/on_client,
-    #     the field/select/text bindings, and the nested-attributes helpers
+    # Assembled from cohesive concerns (issue #115, restructured in #180) — one
+    # include, zero public API change. The include stack, in order:
+    #   * Phlex::Reactive::Streamable — the render/broadcast/#id surface (mixed in
+    #     first, so its methods sit below the component's own).
+    #   * Phlex::Reactive::ClientBindings — the CLIENT-ONLY surface (issue #180),
+    #     itself Component::DSL (the declaration registries via Component::Registry
+    #     + from_identity) + Component::Helpers (reply/js, reactive_attrs/root,
+    #     on/on_client, the field/select/text bindings, reactive_show/filter/
+    #     compute, and the nested-attributes helpers). ClientBindings is the ONE
+    #     implementation of that surface, shared with the standalone client-only
+    #     include; it carries NO token machinery.
+    #   * Component::Identity — reactive_token + the hot-path ivar precomputation.
+    #     Its presence is what makes the server-action macros (action/
+    #     reactive_record/reactive_state) legal here — they raise on a
+    #     ClientBindings-only class that lacks it.
+    #   * Component::Lazy — reactive_lazy (deferred initial mount, issue #165).
+    # So a full, token-bearing reactive component is a SUPERSET of a client-only
+    # one, not a fork.
     module Component
       extend ActiveSupport::Concern
       include Phlex::Reactive::Streamable
@@ -111,9 +122,12 @@ module Phlex
         end
       end
 
-      include DSL
+      # ClientBindings (issue #180) is the client-only surface (DSL + Helpers),
+      # tokenless and Streamable-free. Component includes it as the ONE
+      # implementation, then layers Identity + Lazy (and Streamable, above) on
+      # top — a token-bearing root is a superset of the client-only one.
+      include ClientBindings
       include Identity
-      include Helpers
       include Lazy
     end
   end