solid_objects 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e027a73cc399aa779d8a60acae69f3f379ce505e060123ad49d5d64dcda4809
-  data.tar.gz: 5eb1be4b51649c2c8e6056f0138f130f4f1a8cf2e55e46f86061fc82849658aa
+  metadata.gz: 4f761acc1e99fba4f747cddd191fc0547ee80c7a30f2e03859f24ff22ab0dd70
+  data.tar.gz: 4ed7f4a52926a5276fa04804ce8fbc142a0c4d9b70641b23b27dc07175956b5e
 SHA512:
-  metadata.gz: 7f36f021e2707bbd67fcca022a88a4aa70b5cc35f8175c0ee526defcfb66fb1d3113434d8f700aad1f813ca9ccf49bc6a7e59e8d7c95717f007a660ca7535bd4
-  data.tar.gz: 246e46e83aae40b366992c7c5e763dc65e00945d57b0c0e724595d2f6af0a66ea5c09d5d4dbc5f4c4bdc1ed4de6766d217560e6b376832a98afab158f82e16ea
+  metadata.gz: 0c63ed0b033d8028041c51c08f4d0bdb8667ab8560d469907474327bbc1536ea561ce00b062ae38f56fc72ded1e9498ecffc55d77bdc4efeaad2d6ffa8953e25
+  data.tar.gz: 9aaa0d27ab02b23c4aa95b05cec82ea4463851f51d2ae9d778058aa93fbaa3a7b6e0c66c3ba3b52efbd3ecefa5079f23bf9d37fe12a9481b0b8b65ecc6b2847b

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.0 - 2026-08-07
+
+- Add repeatable reactive components with signed string or integer keys and
+  JSON-compatible partial locals.
+- Add opt-in Turbo morph refreshes with superseded-request cancellation and
+  browser-side actor revision fencing.
+- Pass signed component keys and locals through request-time query
+  authorization without broadcasting personalized HTML.
+
 ## 0.4.3 - 2026-08-07
 
 - Bound SQLite caller-process registration, reuse, heartbeat, and synchronous

data/README.md

@@ -205,9 +205,42 @@ dependencies changes:
 <% end %>
 ```
 
+Component names can repeat when each instance has a stable key. Signed
+JSON-compatible locals let one conventional partial render the matching
+projection:
+
+```erb
+<%= solid_object @room, authorization_context: current_user do |room| %>
+  <% @players.each do |player| %>
+    <%= room.component :player,
+      key: player.id,
+      observes: %i[players life_totals],
+      locals: { player_id: player.id },
+      refresh: :morph %>
+  <% end %>
+<% end %>
+```
+
+The host partial still resolves only to `actors/chat_room/_player`. It receives
+`actor`, `authorization_context`, `component_key`, and the declared locals:
+
+```erb
+<article id="player_<%= player_id %>">
+  Life: <%= actor.life_totals.fetch(player_id.to_s) %>
+</article>
+```
+
+The default refresh strategy is `:replace`. `refresh: :morph` loads the
+authorized component HTML through a gem-owned browser element, rejects stale
+responses by actor revision, and applies the result using Turbo's scoped
+`replace method="morph"`. Superseded requests for the same keyed target are
+aborted. This preserves unchanged DOM nodes where Turbo's morphing rules allow
+it, including focus and `data-turbo-permanent` content.
+
 `room.component(:messages)` resolves only
 `actors/chat_room/_messages`. Its partial receives `actor` and
-`authorization_context` locals:
+`authorization_context` locals, plus a `component_key` of `nil` when the
+component is unkeyed:
 
 ```erb
 <ul>
@@ -221,7 +254,14 @@ Declared observables are deeply frozen ordinary Ruby values inside a
 component. Arrays support loops, hashes support ordinary lookup, conditionals
 work normally, and ERB still escapes user strings. A reactive component cannot
 read `actor.state`, access an undeclared observable, or choose a dynamic
-partial path.
+partial path. A component name and key pair must be unique within its
+`solid_object` scope.
+
+Component keys and locals are signed into the refresh token and cannot be
+modified without invalidating it, but they are visible to the browser and are
+not secrets. Every initial render and refresh passes the signed locals and
+`component_key` to `authorize_query` as `arguments`. Authorization must still
+bind them to the authenticated request context.
 
 That template provides initial server rendering, stable opaque DOM targets,
 and live updates after committed actor turns. One `solid_object` block makes
@@ -254,20 +294,27 @@ for the same actor without sharing either projection.
 Reconnect compares the component's signed initial revision with the latest
 actor incarnation and state revision, then refreshes stale components. Cable
 coalesces several dependency changes from one actor turn into one component
-refresh and ignores older out-of-order invalidations. A newer invalidation
-replaces an in-flight frame, so its detached older response cannot overwrite
-newer state.
+refresh and ignores older out-of-order invalidations. Replace refreshes detach
+an older in-flight frame. Morph refreshes abort the older request and compare
+the returned revision with the current target before applying HTML.
 
 Reactive components add no HTML to durable rows, but each affected component
 causes an authorized HTTP render. One actor turn still inserts one broadcast
 row per changed observable; several dependencies from that turn coalesce at
 the subscriber. Keep components bounded, declare only necessary dependencies,
-and use scalar observables for inexpensive single-value replacement.
+keep signed locals small, and use scalar observables for inexpensive
+single-value replacement. Each keyed component counts toward the 50-component
+subscription limit and carries its own signed token.
 
 Reactive views require `turbo-rails` and a working Action Cable adapter in the
 host application. The Solid Objects engine must be mounted so its signed
 component endpoint is reachable. Reactive views are optional; the actor
-runtime itself does not depend on Turbo.
+runtime itself does not depend on Turbo. Morph components automatically include
+the engine's `solid_objects/component_refresh` JavaScript module; the host does
+not need a Stimulus controller or custom stream action. The default Rails
+Propshaft and Sprockets setups discover namespaced engine assets automatically.
+An application created with `--skip-asset-pipeline` should use replace refreshes
+unless it explicitly serves that module.
 
 ```ruby
 # config/routes.rb

data/app/assets/javascripts/solid_objects/component_refresh.js

@@ -0,0 +1,124 @@
+const activeRefreshes = new Map()
+
+class SolidObjectsRefreshElement extends HTMLElement {
+  connectedCallback() {
+    if (this.dataset.started === "true") return
+
+    this.dataset.started = "true"
+    this.refresh()
+  }
+
+  disconnectedCallback() {
+    this.refreshController?.abort()
+  }
+
+  async refresh() {
+    const targetName = this.dataset.target
+    const source = this.dataset.source
+    if (!targetName || !document.getElementById(targetName) || !source) {
+      return this.remove()
+    }
+
+    const previousRefresh = activeRefreshes.get(targetName)
+    previousRefresh?.abort()
+
+    const refresh = new AbortController()
+    this.refreshController = refresh
+    activeRefreshes.set(targetName, refresh)
+
+    try {
+      const sourceUrl = this.sourceUrl(source)
+      const response = await fetch(sourceUrl, {
+        credentials: "same-origin",
+        headers: {
+          Accept: "text/html",
+          "Turbo-Frame": targetName
+        },
+        redirect: "error",
+        signal: refresh.signal
+      })
+      if (!response.ok) {
+        this.dispatchRefreshError(`http_${response.status}`)
+        return
+      }
+
+      const responseDocument = new DOMParser().parseFromString(
+        await response.text(),
+        "text/html"
+      )
+      const replacement = responseDocument.getElementById(targetName)
+      if (!replacement || replacement.tagName !== "TURBO-FRAME") {
+        this.dispatchRefreshError("missing_frame")
+        return
+      }
+      const currentTarget = document.getElementById(targetName)
+      if (!currentTarget || !newerRevision(replacement, currentTarget)) return
+
+      renderMorph(targetName, replacement)
+    } catch (error) {
+      if (error.name !== "AbortError") {
+        this.dispatchRefreshError("request_failed")
+      }
+    } finally {
+      if (activeRefreshes.get(targetName) === refresh) {
+        activeRefreshes.delete(targetName)
+      }
+      this.remove()
+    }
+  }
+
+  sourceUrl(source) {
+    const sourceUrl = new URL(source, window.location.href)
+    if (sourceUrl.origin === window.location.origin) return sourceUrl
+
+    throw new Error("cross_origin_source")
+  }
+
+  dispatchRefreshError(reason) {
+    this.dispatchEvent(
+      new CustomEvent("solid-objects:component-refresh-error", {
+        bubbles: true,
+        detail: { reason }
+      })
+    )
+  }
+}
+
+function newerRevision(candidate, current) {
+  const candidateRevision = revisionFor(candidate)
+  const currentRevision = revisionFor(current)
+  if (!candidateRevision || !currentRevision) return false
+
+  return candidateRevision[0] > currentRevision[0] ||
+    (candidateRevision[0] === currentRevision[0] &&
+      candidateRevision[1] > currentRevision[1])
+}
+
+function revisionFor(element) {
+  const revision = element.dataset.solidObjectsRevision
+  if (!revision) return
+
+  const values = revision.split(":").map(Number)
+  if (
+    values.length !== 2 ||
+    values.some((value) => !Number.isSafeInteger(value) || value < 0)
+  ) return
+
+  return values
+}
+
+function renderMorph(targetName, replacement) {
+  const stream = document.createElement("turbo-stream")
+  stream.setAttribute("action", "replace")
+  stream.setAttribute("method", "morph")
+  stream.setAttribute("target", targetName)
+
+  const template = document.createElement("template")
+  template.content.append(document.importNode(replacement, true))
+  stream.append(template)
+  document.documentElement.append(stream)
+}
+
+if (!customElements.get("solid-objects-refresh")) {
+  customElements.define("solid-objects-refresh", SolidObjectsRefreshElement)
+}

data/app/controllers/solid_objects/components_controller.rb

@@ -21,8 +21,7 @@ module SolidObjects
         .call(controller: self)
       rendered = ComponentRenderer.new(
         snapshot:,
-        component_name: registration.component_name,
-        dependencies: registration.dependencies,
+        registration:,
         view_context: component_view_context,
         authorization_context:
       ).call
@@ -67,12 +66,8 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, ActorSnapshot, untyped) -> String
     def component_frame(registration, snapshot, rendered)
-      target = DomIdentity.component(
-        registration.reference,
-        registration.component_name
-      )
       revision = "#{snapshot.instance_id}:#{snapshot.revision}"
-      %(<turbo-frame id="#{target}" data-solid-objects-revision="#{revision}">#{rendered}</turbo-frame>).html_safe
+      %(<turbo-frame id="#{registration.dom_id}" data-solid-objects-revision="#{revision}" data-solid-objects-refresh="#{registration.refresh_method}">#{rendered}</turbo-frame>).html_safe
     end
   end
 end

data/app/helpers/solid_objects/actor_helper.rb

@@ -23,10 +23,17 @@ module SolidObjects
         channel: "SolidObjects::ActorChannel",
         data: subscription_data
       )
+      refresh_client = if actor.morph_components?
+        javascript_include_tag(
+          "solid_objects/component_refresh",
+          type: "module",
+          data: { turbo_track: "reload" }
+        )
+      end
 
       content_tag(
         :div,
-        safe_join([ subscription, content ]),
+        safe_join([ refresh_client, subscription, content ].compact),
         id: DomIdentity.scope(reference)
       )
     end

data/docs/adr/0009-realtime-updates.md

@@ -11,11 +11,28 @@ Action Cable broadcasts are online-only. A transaction can roll back, a broadcas
 
 The executor evaluates declared observables before and after a successful message. Changed values create broadcast outbox records inside the message commit. A broadcast worker delivers Turbo Stream replacements after commit.
 
-One `solid_object` block creates one signed Action Cable subscription and contains stable targets for multiple observables and components. Subscription authorization runs after token verification and before streaming. Reconnect refresh reads current actor state; the broadcast stream is an optimization, not state.
+One `solid_object` block creates one signed Action Cable subscription and
+contains stable targets for multiple observables and components. Component
+names may repeat behind signed string or integer keys. Small JSON locals,
+dependencies, refresh strategy, and initial revision are signed into each
+component registration.
+
+Subscription authorization runs after token verification and before streaming.
+Every initial or request-time component render separately authorizes the
+component name and dependencies with its signed key and locals. Personalized
+HTML is never stored or broadcast.
+
+Replace refreshes use Turbo Frames. Optional morph refreshes use a gem-owned
+browser element to fetch the same authorized endpoint, abort superseded
+requests, reject stale revisions, and apply Turbo's scoped morph operation.
+Reconnect refresh reads current actor state; the broadcast stream is an
+optimization, not state.
 
 ## Consequences
 
 - Disconnected clients may miss individual broadcasts but can converge by refresh.
 - Broadcast delivery is at least once and replacements must be idempotent.
 - Actor IDs and signed stream names are identifiers, not authorization.
+- Component keys and locals are visible integrity-protected inputs, not
+  secrets or capabilities.
 - Realtime support is optional and loaded only when Action Cable and Turbo are present.

data/docs/architecture.md

@@ -473,13 +473,20 @@ emits:
 - Stable child target IDs for values and components
 - A signed actor token used by the channel subscription
 - Signed component registrations containing a conventional component name,
-  explicit observable dependencies, the initial actor incarnation/revision,
-  and a same-origin engine refresh path
+  optional string or integer key, JSON locals, explicit observable
+  dependencies, refresh strategy, the initial actor incarnation/revision, and
+  a same-origin engine refresh path
 
 ```erb
-<%= solid_object current_cart do |cart| %>
-  Cart items: <%= cart.items_count %>
-  <%= cart.component :summary, observes: %i[items checkout_status] %>
+<%= solid_object @room do |room| %>
+  Present: <%= room.presence %>
+  <% @players.each do |player| %>
+    <%= room.component :player,
+      key: player.id,
+      observes: :players,
+      locals: { player_id: player.id },
+      refresh: :morph %>
+  <% end %>
 <% end %>
 ```
 
@@ -487,9 +494,11 @@ The signed token proves integrity, not authorization. `ActorChannel#subscribed`
 
 Scalar observable calls remain direct escaped Turbo replacements. A reactive
 component resolves only `actors/<actor_class>/_<component>`, receives its
-declared observables as frozen Ruby values, and cannot read raw state or a
-dependency it did not declare. A static initial-only component can still use a
-server-selected explicit partial; a reactive component cannot.
+declared observables and signed locals as frozen Ruby values, and cannot read
+raw state or a dependency it did not declare. Repeated component names use a
+keyed digest in the DOM identity, subscription revision map, and duplicate
+check. A static initial-only component can still use a server-selected
+explicit partial; a reactive component cannot.
 
 Broadcast replacements happen after the actor transaction commits because only
 a committed broadcast outbox row can be delivered. Multiple scalar values and
@@ -502,24 +511,29 @@ dependencies do not send their values to the browser, and the stream never
 contains personalized component HTML. For each subscription, `ActorChannel`
 matches the changed observable to registered component dependencies. It
 coalesces multiple dependencies at the same message sequence and drops older
-revision pairs. A component invalidation replaces its stable target with a
-Turbo Frame whose source is the signed engine endpoint.
+revision pairs independently for every component name and key pair. A default
+component invalidation replaces its stable target with a Turbo Frame whose
+source is the signed engine endpoint. A morph invalidation appends a temporary
+gem-owned refresh element carrying the same signed URL.
 
 The browser then makes an ordinary cookie-bearing HTTP request. The engine
 controller derives a request-specific context through
 `component_authorization_context`, calls `authorize_query` for the component
-name and every declared dependency, renders the host partial from a new
-committed snapshot, and returns `private, no-store` HTML. Subscribers to the
-same actor can therefore receive different HTML without sharing it through
-Cable or the database.
+name and every declared dependency with the signed key and locals as
+authorization arguments, renders the host partial from a new committed
+snapshot, and returns `private, no-store` HTML. Subscribers to the same actor
+can therefore receive different HTML without sharing it through Cable or the
+database.
 
 Each channel subscription transmits current scalar replacements and compares
 each component's signed initial revision against the latest committed
 `(instance_id, state_revision)` pair, including after reconnect. Missing a
 broadcast therefore creates temporary staleness, not permanent divergence.
 The instance primary key distinguishes destroy-and-recreate incarnations.
-Replacing the full frame on each newer invalidation detaches an older in-flight
-frame, preventing its slower response from replacing the current generation.
+Replace refreshes detach an older in-flight frame. Morph refreshes abort a
+superseded fetch for the same target, re-read the current DOM target after the
+response arrives, compare monotonic revision pairs, and apply authorized HTML
+through Turbo's scoped morph operation only when it is newer.
 
 ## Authorization
 
@@ -540,8 +554,10 @@ No controller, channel, or administrative command treats an actor ID, message ID
 
 Initial component rendering, Cable subscription, and request-time component
 refresh deliberately use different authorization contexts. Signed component
-tokens constrain actor identity, component convention, dependencies, revision,
-and same-origin refresh path but never grant access.
+tokens constrain actor identity, component convention, optional key and
+locals, dependencies, refresh method, revision, and same-origin refresh path
+but never grant access. Keys and locals are browser-visible integrity-protected
+inputs, not encrypted capabilities.
 
 Actor IDs are bounded UTF-8 strings and never become constant names, SQL identifiers, file paths, or raw stream names.
 

data/docs/authorization.md

@@ -57,6 +57,30 @@ The stream token also signs the scalar observable targets rendered into that
 specific scope. Component-only dependencies send invalidation metadata but not
 their state value to the browser.
 
+Keyed components sign their `component_key` and declared JSON-compatible
+locals into the component token. Initial rendering and every refresh pass those
+values to `authorize_query` as `arguments`; unkeyed components without locals
+retain an empty arguments hash. This lets a policy authorize a projection such
+as one seat or player:
+
+```ruby
+configuration.authorize_query = lambda do |actor_type:, actor_id:, message_name:, arguments:, authorization_context:|
+  user = authorization_context
+  player_id = arguments["player_id"]
+
+  actor_type == "PlaymatRoom" &&
+    user.present? &&
+    user.can_view_room?(actor_id) &&
+    (player_id.nil? || user.can_view_player?(player_id))
+end
+```
+
+The values are signed but not encrypted. They are present in server-rendered
+HTML and the Cable subscription identifier, so they must not contain secrets
+or sensitive state. A valid signature proves that the server issued the
+registration; it does not prove the current user may still read it. Always
+reauthorize against the current request context.
+
 ## A tenant-aware policy
 
 Pass the authenticated user as the call context:

data/docs/correctness.md

@@ -137,10 +137,18 @@ its name and revision over Cable, not its serialized value.
 
 Cable compares `(instance_id, state_revision)` pairs, coalesces dependencies
 changed by the same turn, and ignores an older pair after a newer one. A new
-invalidation replaces the whole Turbo Frame generation. A response owned by
-the detached older frame cannot overwrite the current frame. Reconnect
-compares the component's signed initial pair with the current instance row and
-requests the latest committed snapshot when stale.
+invalidation advances each keyed component registration independently. Replace
+refreshes replace the whole Turbo Frame generation, so a response owned by the
+detached older frame cannot overwrite the current frame. Morph refreshes abort
+a superseded request for the same target and compare the response revision
+with the current DOM revision immediately before applying Turbo's scoped
+morph. Reconnect compares every component's signed initial pair with the
+current instance row and requests the latest committed snapshot when stale.
+
+Component keys, JSON locals, dependencies, and refresh strategy are covered by
+the signed registration. Keys and locals are visible to the browser and are
+passed back to `authorize_query` on every render; integrity never substitutes
+for request-specific authorization.
 
 ## Synchronous invocation
 

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 %>