solid_objects 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8876ae7a3b7de88ef10870bf9fb32e73e74969571a6b1f21e83cd88f3933ee
-  data.tar.gz: 6c72ffa8e6e77b6f50b2a2c3f76c470aa136cac490006316810751175a391e5d
+  metadata.gz: 4f761acc1e99fba4f747cddd191fc0547ee80c7a30f2e03859f24ff22ab0dd70
+  data.tar.gz: 4ed7f4a52926a5276fa04804ce8fbc142a0c4d9b70641b23b27dc07175956b5e
 SHA512:
-  metadata.gz: e66ea0877bc3dd4e45726ea6361650c0fc02ba1ee0fd6dc00c0588f8080626b687d113fcf02941ff2466146adfa10e8cd8a27026b660509d62e8ca425fbe5fcb
-  data.tar.gz: 11a6f7c4e27551cfe4389e58edfacbd10c1b05ab17d0e6cbcc75f25f375257fe959237a5beb076d18941c89d33c76239444de57c2d8cb9d185ff33b239752d64
+  metadata.gz: 0c63ed0b033d8028041c51c08f4d0bdb8667ab8560d469907474327bbc1536ea561ce00b062ae38f56fc72ded1e9498ecffc55d77bdc4efeaad2d6ffa8953e25
+  data.tar.gz: 9aaa0d27ab02b23c4aa95b05cec82ea4463851f51d2ae9d778058aa93fbaa3a7b6e0c66c3ba3b52efbd3ecefa5079f23bf9d37fe12a9481b0b8b65ecc6b2847b

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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
+  result observation retries by the original invocation deadline.
+- Load host application actors from `app/actors` before CLI workers start,
+  including development environments with eager loading disabled.
+
 ## 0.4.2 - 2026-08-07
 
 - Decode Action Cable broadcast payloads before parsing observable invalidations

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
@@ -588,9 +635,9 @@ polling as the fallback. A timeout never cancels the durable invocation.
 durable status, mailbox blocker, and activation-owner diagnostics without
 including message arguments. The configured timeout also bounds adapter
 database lock waits from the enqueue attempt through result observation.
-PostgreSQL uses transaction lock and statement timeouts, SQLite uses its busy
-timeout, and MySQL uses its execution timeout plus InnoDB's one-second minimum
-lock-wait granularity.
+PostgreSQL uses transaction lock and statement timeouts, SQLite retries busy
+coordination operations only until the original call deadline, and MySQL uses
+its execution timeout plus InnoDB's one-second minimum lock-wait granularity.
 
 The durable call can finish after its original caller gives up. Reauthorize and
 recover its eventual result through the durable message identity:
@@ -896,6 +943,11 @@ and marks process rows stopped on graceful shutdown. A hard-killed worker's
 claimed turn is recovered after its process heartbeat or activation lease
 becomes stale.
 
+Before any role starts, the CLI loads actors from the host application's
+`app/actors` directories through Rails' main autoloader. This works when
+development eager loading is disabled and does not require actor references in
+an initializer.
+
 See the [operations guide](docs/operations.md) for monitoring, reconciliation,
 shutdown, retention, and backup guidance.
 

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
 
@@ -155,10 +163,13 @@ Timeout raises `SolidObjects::SyncTimeout` but does not cancel the message.
 The exception reports actor identity, message ID and sequence, durable status,
 an earlier mailbox blocker, and activation-owner metadata without exposing
 arguments. Its `message_reference` can reauthorize and wait for the eventual
-result. Adapter lock/query deadlines cover the durable enqueue and coordination
-transactions. If enqueue cannot commit, `SyncEnqueueTimeout` is raised and no
-message reference exists. MySQL lock waits have one-second InnoDB granularity.
-Ruby handlers that already started are not preempted.
+result. Adapter lock/query deadlines cover the durable enqueue, caller-process
+registration and heartbeat, activation coordination, and result observation.
+SQLite retries busy coordination operations only within the original call
+deadline and reports `waiting_on=database_contention` when the database cannot
+be inspected at timeout. If enqueue cannot commit, `SyncEnqueueTimeout` is
+raised and no message reference exists. MySQL lock waits have one-second InnoDB
+granularity. Ruby handlers that already started are not preempted.
 
 A synchronous call made while the Solid Objects connection already has an open
 transaction raises `SolidObjects::SyncInsideTransaction` before the message is

data/docs/operations.md

@@ -23,6 +23,12 @@ Start all configured roles:
 bundle exec solid_objects start
 ```
 
+The command loads the host application's `app/actors` directories before
+starting any runtime role, even when Rails eager loading is disabled. Actors in
+the conventional directory do not need initializer references. The targeted
+loader participates in Rails preparation callbacks so a development reload can
+replace a registered actor class without loading unrelated application code.
+
 Inspect process records and clean stale ownership:
 
 ```bash