solid_objects 0.4.3 → 0.5.1

data/docs/realtime.md

@@ -28,11 +28,37 @@ never influence partial resolution. The older
 `actor.component(:summary, partial: "server/chosen/path")` form remains
 available for initial-only static rendering.
 
-The partial receives exactly two component locals:
+The partial receives these built-in component locals:
 
 - `actor`, which exposes the declared observables as deeply frozen ordinary
   Ruby values plus `actor_id` and `reference`; and
 - `authorization_context`, the context for this initial render or refresh.
+- `component_key`, the signed string or integer key, or `nil` for an unkeyed
+  component.
+
+Applications can declare additional JSON-compatible locals. They are
+normalized, signed into the component token, deeply frozen, and supplied on
+both the initial render and every refresh:
+
+```erb
+<% @players.each do |player| %>
+  <%= actor.component :player,
+    key: player.id,
+    observes: %i[players life_totals],
+    locals: { player_id: player.id } %>
+<% end %>
+```
+
+This resolves every instance to the same `_player.html.erb` partial while
+giving each one a distinct opaque DOM target. The `(component name, key)` pair
+must be unique within one `solid_object` scope. An unkeyed component retains
+the existing target and uniqueness behavior.
+
+Local names must be valid Ruby local identifiers. `actor`,
+`authorization_context`, and `component_key` are reserved. Local values must
+use the same safe JSON value set as actor messages. Tokens are limited to
+16 KiB and one subscription accepts at most 50 components, so locals should be
+small identifiers or rendering options rather than copied actor state.
 
 `actor.state` is unavailable in reactive components. Reading an observable not
 listed in `observes:` raises `UnknownComponentDependency`. This keeps
@@ -51,6 +77,39 @@ Arrays, hashes, loops, conditionals, nested markup, and host helper output are
 normal ERB. Escaping remains Action View's responsibility; Solid Objects never
 marks actor strings as HTML safe.
 
+## Replace and morph refreshes
+
+Reactive components use `refresh: :replace` by default. The existing path
+replaces the target with a Turbo Frame whose signed URL performs the authorized
+request-time render.
+
+Use `refresh: :morph` when preserving unchanged DOM nodes matters:
+
+```erb
+<%= actor.component :battlefield,
+  key: player.id,
+  observes: %i[battlefields zone_counts],
+  locals: { player_id: player.id },
+  refresh: :morph %>
+```
+
+Morph invalidations append a short-lived gem-owned browser element to the
+actor scope. It fetches the same signed component endpoint with normal
+same-origin cookies, aborts an older request for the same keyed target, and
+converts the authorized response into Turbo's scoped
+`replace method="morph"`. Before applying it, the browser compares the
+response's `(instance_id, state_revision)` with the current target. An older
+response cannot overwrite newer HTML.
+
+The engine exposes the `solid_objects/component_refresh` module through the
+host asset pipeline and `solid_object` includes it only when the scope contains
+a morph component. No host Stimulus controller, custom channel, custom stream
+action, or polling loop is required. Default Propshaft and Sprockets
+applications discover the namespaced engine asset. Applications created with
+`--skip-asset-pipeline` should keep the default replace strategy unless they
+explicitly serve the module. Turbo's normal morph rules still apply; use
+`data-turbo-permanent` for elements that must never be changed.
+
 ## Authorization
 
 The HTML contains a signed actor identity token. Signing prevents modification;
@@ -61,9 +120,10 @@ approval.
 Initial scalar and component reads call `authorize_query` with the context
 passed to `solid_object`. The refresh controller resolves a new request context
 through `component_authorization_context`, then calls `authorize_query` again
-for the component name and every declared dependency. The default resolver
-supplies the engine controller; applications commonly resolve it to
-`Current.user`:
+for the component name and every declared dependency. Keyed registrations pass
+their `component_key` plus all declared locals as `arguments` at both
+boundaries. The default resolver supplies the engine controller; applications
+commonly resolve it to `Current.user`:
 
 ```ruby
 configuration.component_authorization_context = ->(controller:) { Current.user }
@@ -77,8 +137,10 @@ The three contexts are intentionally different:
 | Action Cable subscription | The authenticated Cable connection |
 | Component refresh | Value returned by `component_authorization_context` for the engine controller request |
 
-Do not substitute a signed token for any of them. Never authorize solely from
-actor ID, token possession, stream name, component name, or DOM ID.
+Do not substitute a signed token for any of them. Keys and locals are visible
+to the browser and signed for integrity, not encrypted or authorized. Never
+authorize solely from actor ID, token possession, stream name, component name,
+component key, locals, or DOM ID.
 
 ## Broadcast durability
 
@@ -96,10 +158,11 @@ authorized browser requests affected components through the engine endpoint
 with its normal cookies. Responses are `private, no-store`.
 
 Several changed dependencies from one message sequence produce one logical
-refresh for a component. An unrelated observable does not refresh it. If a
-newer invalidation arrives while a Turbo Frame request is in flight, the new
-frame replaces the old frame element; the detached older response has no
-current target.
+refresh for each keyed component registration. An unrelated observable does
+not refresh it. If a newer invalidation arrives while a replace request is in
+flight, the new frame replaces the old frame element; the detached older
+response has no current target. Morph requests are coalesced per target with an
+`AbortController` and perform a final client-side revision comparison.
 
 If Cable delivery is lost, reconnecting `ActorChannel` transmits replacements
 from current actor state. It compares the signed component revision with the
@@ -111,8 +174,8 @@ truth.
 
 The component endpoint rejects a requested revision newer than the committed
 snapshot. This is a final server-side guard; browser safety primarily comes
-from monotonic channel filtering and replacing the entire Turbo Frame
-generation.
+from monotonic channel filtering plus replace-frame detachment or morph
+response revision fencing.
 
 ## Cost model
 
@@ -120,7 +183,9 @@ The durable row cost is unchanged: one broadcast row per changed observable,
 containing its JSON value and the message/instance references needed to derive
 invalidation metadata. No rendered document is stored. Each affected component
 adds one authorized GET and one partial render per non-coalesced state
-revision. Scalar observables remain the cheaper path for one text value.
+revision. A repeated keyed component adds one GET and render per key. Signed
+locals increase page and Cable subscription bytes but do not create durable
+rows. Scalar observables remain the cheaper path for one text value.
 
 ## Deployment
 

data/docs/roadmap.md

@@ -15,8 +15,8 @@
 - Transactional effects with success/failure actor messages
 - Actor-to-actor asynchronous outbox delivery
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
-- Durable observable invalidations, scalar Turbo replacement, and authorized
-  request-time ERB component refresh
+- Durable observable invalidations, scalar Turbo replacement, keyed ERB
+  components, signed component locals, and authorized replace or morph refresh
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
@@ -36,9 +36,10 @@
   role or run periodic maintenance automatically.
 - Wake-up strategy: in-process signaling plus durable polling and injection are
   implemented; PostgreSQL `LISTEN/NOTIFY` and optional Redis adapters are not.
-- Realtime: scalar and dependency-driven ERB component replacement,
-  personalized refresh authorization, revision fencing, coalescing, and
-  reconnect convergence are implemented; Turbo append actions are not.
+- Realtime: scalar and dependency-driven keyed ERB component replacement or
+  morphing, personalized refresh authorization, revision fencing, coalescing,
+  and reconnect convergence are implemented; application-directed Turbo
+  append intents are not.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   distributed per-actor rate limits and global admission control do not.
 - Administration: actor and dead-letter views plus policy hooks exist; richer

data/examples/application/app/views/chat_rooms/show.html.erb

@@ -4,5 +4,7 @@
     <%= room.presence %>
   </p>
 
-  <%= room.component :messages, observes: :recent_messages %>
+  <%= room.component :messages,
+    observes: :recent_messages,
+    refresh: :morph %>
 <% end %>

data/lib/solid_objects/actor_view.rb

@@ -37,10 +37,20 @@ module SolidObjects
       )
     end
 
-    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?) -> untyped
-    def component(name, observes: nil, partial: nil)
+    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
+    def component(
+      name,
+      observes: nil,
+      partial: nil,
+      key: nil,
+      locals: {},
+      refresh: :replace
+    )
       component_name = normalized_component_name(name)
-      return static_component(component_name, partial:) unless observes
+      unless observes
+        validate_static_options!(key:, locals:, refresh:)
+        return static_component(component_name, partial:)
+      end
       if partial
         raise ArgumentError,
           "reactive components resolve partials by actor and component name"
@@ -48,19 +58,21 @@ module SolidObjects
 
       dependencies = normalized_dependencies(observes)
       validate_dependencies!(dependencies)
-      ensure_unique_component!(component_name)
       refresh_path = component_path_resolver.call(view_context:)
       registration = ComponentRegistration.issue(
         reference:,
         component_name:,
+        component_key: key,
         dependencies:,
+        locals:,
+        refresh_method: refresh,
         snapshot:,
         refresh_path:
       )
+      ensure_unique_component!(registration)
       rendered = ComponentRenderer.new(
         snapshot:,
-        component_name:,
-        dependencies:,
+        registration:,
         view_context:,
         authorization_context:
       ).call
@@ -68,9 +80,10 @@ module SolidObjects
       view_context.content_tag(
         :"turbo-frame",
         rendered,
-        id: DomIdentity.component(reference, component_name),
+        id: registration.dom_id,
         data: {
-          solid_objects_revision: "#{snapshot.instance_id}:#{snapshot.revision}"
+          solid_objects_revision: "#{snapshot.instance_id}:#{snapshot.revision}",
+          solid_objects_refresh: registration.refresh_method
         }
       )
     end
@@ -85,6 +98,11 @@ module SolidObjects
       observable_names.dup
     end
 
+    # @rbs () -> bool
+    def morph_components?
+      component_registrations.any?(&:morph?)
+    end
+
     # @rbs () -> State
     def state
       snapshot.actor.state
@@ -183,14 +201,23 @@ module SolidObjects
         "unknown observable dependency #{unknown.inspect} for #{reference.actor_type}"
     end
 
-    # @rbs (String) -> void
-    def ensure_unique_component!(component_name)
-      return unless component_registrations.any? do |registration|
-        registration.component_name == component_name
+    # @rbs (ComponentRegistration) -> void
+    def ensure_unique_component!(registration)
+      return unless component_registrations.any? do |existing_registration|
+        existing_registration.dom_id == registration.dom_id
       end
 
       raise ArgumentError,
-        "component #{component_name.inspect} is already rendered in this solid_object scope"
+        "component #{registration.component_name.inspect} with key " \
+          "#{registration.component_key.inspect} is already rendered in this solid_object scope"
+    end
+
+    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
+    def validate_static_options!(key:, locals:, refresh:)
+      return if key.nil? && locals.empty? && refresh.to_s == "replace"
+
+      raise ArgumentError,
+        "key, locals, and refresh require an observable component"
     end
 
     # @rbs () -> Proc | ComponentPathResolver

data/lib/solid_objects/component_registration.rb

@@ -6,7 +6,10 @@ module SolidObjects
   class ComponentRegistration
     # @rbs @reference: Reference
     # @rbs @component_name: String
+    # @rbs @component_key: String | Integer?
     # @rbs @dependencies: Array[String]
+    # @rbs @locals: Hash[String, untyped]
+    # @rbs @refresh_method: String
     # @rbs @instance_id: Integer
     # @rbs @revision: Integer
     # @rbs @refresh_path: String
@@ -14,17 +17,23 @@ module SolidObjects
 
     attr_reader :reference,
       :component_name,
+      :component_key,
       :dependencies,
+      :locals,
+      :refresh_method,
       :instance_id,
       :revision,
       :refresh_path,
       :token
 
-    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
+    # @rbs (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
     def initialize(
       reference:,
       component_name:,
+      component_key:,
       dependencies:,
+      locals:,
+      refresh_method:,
       instance_id:,
       revision:,
       refresh_path:,
@@ -32,7 +41,10 @@ module SolidObjects
     )
       @reference = reference
       @component_name = component_name
+      @component_key = component_key
       @dependencies = dependencies.freeze
+      @locals = Serialization.readonly_copy(locals)
+      @refresh_method = refresh_method
       @instance_id = instance_id
       @revision = revision
       @refresh_path = refresh_path
@@ -40,30 +52,43 @@ module SolidObjects
     end
 
     class << self
-      # @rbs (reference: Reference, component_name: String, dependencies: Array[String], snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
-      def issue(reference:, component_name:, dependencies:, snapshot:, refresh_path:)
+      # @rbs (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
+      def issue(
+        reference:,
+        component_name:,
+        component_key:,
+        dependencies:,
+        locals:,
+        refresh_method:,
+        snapshot:,
+        refresh_path:
+      )
         token = ComponentToken.generate(
           reference:,
           component_name:,
+          component_key:,
           dependencies:,
+          locals:,
+          refresh_method:,
           instance_id: snapshot.instance_id,
           revision: snapshot.revision,
           refresh_path:
         )
-        new(
-          reference:,
-          component_name:,
-          dependencies:,
-          instance_id: snapshot.instance_id,
-          revision: snapshot.revision,
-          refresh_path:,
-          token:
-        )
+        build(ComponentToken.verify(token), token:)
       end
 
       # @rbs (String) -> ComponentRegistration
       def from_token(token)
         payload = ComponentToken.verify(token)
+        build(payload, token:)
+      rescue UnknownActorType, UnknownComponentDependency => error
+        raise InvalidComponentToken, error.message
+      end
+
+      private
+
+      # @rbs (Hash[String, untyped], token: String) -> ComponentRegistration
+      def build(payload, token:)
         reference = Reference.new(
           actor_type: payload.fetch("actor_type"),
           actor_id: payload.fetch("actor_id")
@@ -73,18 +98,17 @@ module SolidObjects
         new(
           reference:,
           component_name: payload.fetch("component_name"),
+          component_key: payload["component_key"],
           dependencies:,
+          locals: payload.fetch("locals"),
+          refresh_method: payload.fetch("refresh_method"),
           instance_id: payload.fetch("instance_id"),
           revision: payload.fetch("revision"),
           refresh_path: payload.fetch("refresh_path"),
           token:
         )
-      rescue UnknownActorType, UnknownComponentDependency => error
-        raise InvalidComponentToken, error.message
       end
 
-      private
-
       # @rbs (Reference, Array[String]) -> void
       def validate_dependencies!(reference, dependencies)
         actor_class = SolidObjects.registry.fetch(reference.actor_type)
@@ -104,6 +128,27 @@ module SolidObjects
       [ instance_id, revision ]
     end
 
+    # @rbs () -> String
+    def dom_id
+      DomIdentity.component(
+        reference,
+        component_name,
+        key: component_key
+      )
+    end
+
+    # @rbs () -> bool
+    def morph?
+      refresh_method == "morph"
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def authorization_arguments
+      return locals unless component_key
+
+      locals.merge("component_key" => component_key).freeze
+    end
+
     # @rbs (Integer, Integer) -> String
     def refresh_url(instance_id, revision)
       query = URI.encode_www_form(

data/lib/solid_objects/component_renderer.rb

@@ -3,46 +3,44 @@
 module SolidObjects
   class ComponentRenderer
     # @rbs @snapshot: ActorSnapshot
-    # @rbs @component_name: String
-    # @rbs @dependencies: Array[String]
+    # @rbs @registration: ComponentRegistration
     # @rbs @view_context: untyped
     # @rbs @authorization_context: untyped
 
-    # @rbs (snapshot: ActorSnapshot, component_name: String, dependencies: Array[String], view_context: untyped, authorization_context: untyped) -> void
+    # @rbs (snapshot: ActorSnapshot, registration: ComponentRegistration, view_context: untyped, authorization_context: untyped) -> void
     def initialize(
       snapshot:,
-      component_name:,
-      dependencies:,
+      registration:,
       view_context:,
       authorization_context:
     )
       @snapshot = snapshot
-      @component_name = component_name
-      @dependencies = dependencies
+      @registration = registration
       @view_context = view_context
       @authorization_context = authorization_context
     end
 
     # @rbs () -> untyped
     def call
-      [ component_name, *dependencies ].uniq.each do |authorization_name|
+      [ registration.component_name, *registration.dependencies ].uniq.each do |authorization_name|
         authorize_read!(authorization_name)
       end
       actor = ComponentView.new(
         snapshot:,
-        dependencies:,
+        dependencies: registration.dependencies,
         authorization_context:
       )
       view_context.render(
         partial: default_partial,
-        locals: {
+        locals: registration.locals.transform_keys(&:to_sym).merge(
           actor:,
-          authorization_context:
-        }
+          authorization_context:,
+          component_key: registration.component_key
+        )
       )
     rescue ActionView::MissingTemplate
       raise UnknownComponent,
-        "unknown component #{component_name.inspect} for #{snapshot.reference.actor_type}"
+        "unknown component #{registration.component_name.inspect} for #{snapshot.reference.actor_type}"
     rescue ActionView::Template::Error => error
       raise error.cause if error.cause.is_a?(SolidObjects::Error)
 
@@ -52,8 +50,7 @@ module SolidObjects
     private
 
     attr_reader :snapshot,
-      :component_name,
-      :dependencies,
+      :registration,
       :view_context,
       :authorization_context
 
@@ -63,7 +60,7 @@ module SolidObjects
         actor_type: snapshot.reference.actor_type,
         actor_id: snapshot.reference.actor_id,
         message_name: observable_name,
-        arguments: {},
+        arguments: registration.authorization_arguments,
         authorization_context:
       )
       return if authorized
@@ -76,7 +73,7 @@ module SolidObjects
       actor_name = snapshot.actor_class.name
       raise InvalidActor, "anonymous actors cannot render reactive components" unless actor_name
 
-      "actors/#{actor_name.underscore}/#{component_name}"
+      "actors/#{actor_name.underscore}/#{registration.component_name}"
     end
   end
 end

data/lib/solid_objects/component_subscriptions.rb

@@ -28,7 +28,7 @@ module SolidObjects
           validate_identity!(registration, reference)
         end
       end
-      if registrations.map(&:component_name).uniq.length != registrations.length
+      if registrations.map(&:dom_id).uniq.length != registrations.length
         raise InvalidComponentToken, "duplicate actor component registration"
       end
 
@@ -39,7 +39,7 @@ module SolidObjects
     def initialize(registrations)
       @registrations = registrations
       @revisions = registrations.to_h do |registration|
-        [ registration.component_name, registration.revision_key ]
+        [ registration.dom_id, registration.revision_key ]
       end
     end
 
@@ -51,7 +51,7 @@ module SolidObjects
       registrations.filter_map do |registration|
         next unless registration.dependencies.include?(observable_name)
         next unless newer_revision?(
-          registration.component_name,
+          registration.dom_id,
           instance_id,
           revision
         )
@@ -64,7 +64,7 @@ module SolidObjects
     def reconnect_refreshes(snapshot)
       registrations.filter_map do |registration|
         next unless newer_revision?(
-          registration.component_name,
+          registration.dom_id,
           snapshot.instance_id,
           snapshot.revision
         )
@@ -92,7 +92,7 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def refresh(registration, instance_id, revision)
-      revisions[registration.component_name] = [ instance_id, revision ]
+      revisions[registration.dom_id] = [ instance_id, revision ]
       TurboStreamRenderer.component_refresh(
         registration,
         instance_id,
@@ -101,8 +101,8 @@ module SolidObjects
     end
 
     # @rbs (String, Integer, Integer) -> bool
-    def newer_revision?(component_name, instance_id, revision)
-      current = revisions.fetch(component_name)
+    def newer_revision?(dom_id, instance_id, revision)
+      current = revisions.fetch(dom_id)
       (current <=> [ instance_id, revision ]) == -1
     end
   end