activeadmin-react 0.1.0.alpha1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92cba0113794ff8883e09e5bf1cfad4b498c705bf97fdabcf2c461c2d320e04c
-  data.tar.gz: 54dbdaed377bcd530612b4077ad9364b167b7a268438b09d8d038ff15d798052
+  metadata.gz: '0250683b92e883cd5386b556c1b0b3ca2db12e9d27e2fb6401360575a1de33f5'
+  data.tar.gz: 66d6cfd94df946bda32b5f8ef8821a2a15f1ecdc6c211777c2b141e558e0e26a
 SHA512:
-  metadata.gz: 3aead5075fda511f7d0ce83ae644860eb2831432c93c99aeab3a68b5b8c07d513049237d1826db73b2bd79971d45845db449e4a113f09d874e8d709893ce95ee
-  data.tar.gz: dff36285667c02f65f3a52fe0f24ef0f52a5428e8be2640dd142f837b4cb42b4eeb799a3f7a18e119ea4a49c0c3c9ccda73bd16054b1ad6f5d18f157a1b2c87c
+  metadata.gz: b01d4e7a51fe68600e13bfc8c994d8e64b4efcfa68e5fb7e71ff3b887a39294d6e2f16e4c62fa1af9e9da5e2af132c600475a1e1c53b643c219f6b19920e19f0
+  data.tar.gz: fac7bcd73de4ded661e73c07eeb088d6058227ff79eaffe83c62a97531ecde687468ce0004dd6f9a81e6246cc41d27eee4279b9d509f88a23bdb919b11f8544e

data/CHANGELOG.md

@@ -4,6 +4,45 @@
 
 All notable changes to ActiveAdmin React are recorded here. During ordinary pre-1.0 development, PATCH releases contain fixes and small compatible improvements; MINOR releases may contain new capabilities, meaningful API evolution, and documented breaking changes.
 
+## Unreleased
+
+## 0.3.0 — 2026-09-19
+
+This release advances the MINOR line because it adds a public TypeScript contract for
+the packaged JavaScript API without changing runtime behavior.
+
+### Added
+
+- Packaged `index.d.ts` declarations now cover every public registry, runtime,
+  protocol, Cable, resumable-subscription, and operation export.
+- Strict independent-consumer verification now proves supported usage typechecks and
+  representative invalid usage fails without a host-owned ambient declaration.
+
+### Changed
+
+- The minimum supported ActiveAdmin version is now `4.0.0.beta23`, which raises
+  the minimum supported Ruby version to 3.3.
+
+## 0.2.0 — 2026-09-19
+
+First ordinary pre-1.0 release after the initial Rodeo dogfooding prerelease. This
+release advances the MINOR line because it adds reusable Action Cable delivery and
+resumable-subscription capabilities alongside compatibility and lifecycle fixes.
+
+### Added
+
+- `subscribeResumable` now provides fixed resume, monotonic cursor, deduplication, protocol-error, and idempotent cleanup mechanics for application-owned Action Cable streams.
+- `ActiveAdmin::React::Cable.broadcast` now provides an observable, payload-safe best-effort delivery boundary with an immutable `BroadcastResult`.
+
+### Changed
+
+- Ordinary pre-1.0 releases now use unsuffixed `0.MINOR.PATCH` versions; prerelease suffixes are reserved for explicitly authorized major-release stabilization trains.
+
+### Fixed
+
+- React islands now unmount before Turbo replaces rendered content and remount after `turbo:render`, including `422` form validation responses.
+- Rails 8.1.3.1 integration and browser validation now constrain the test-only JSON dependency below 3 until Rails supports JSON 3 keyword arguments.
+
 ## 0.1.0.alpha1 — 2026-09-05
 
 First integrated prerelease for Rodeo dogfooding. Public Ruby and JavaScript contracts

data/README.md

@@ -11,10 +11,10 @@ ActiveAdmin React keeps administrative pages Rails-first and server-rendered whi
 Add the gem to a Rails application that uses ActiveAdmin:
 
 ```ruby
-gem "activeadmin-react", "0.1.0.alpha1", require: "active_admin/react"
+gem "activeadmin-react", "0.3.0", require: "active_admin/react"
 ```
 
-Then run `bundle install`. The gem requires Ruby 3.2 or newer, Rails 8.x, and ActiveAdmin `4.0.0.beta22` or newer within the 4.x line. The JavaScript runtime uses the React 18/19 `createRoot` API; the host supplies `react` and `react-dom` and remains responsible for compiling and serving browser assets.
+Then run `bundle install`. The gem requires Ruby 3.3 or newer, Rails 8.x, and ActiveAdmin `4.0.0.beta23` or newer within the 4.x line. The JavaScript runtime uses the React 18/19 `createRoot` API; the host supplies `react` and `react-dom` and remains responsible for compiling and serving browser assets.
 
 ## Render an island from Arbre
 
@@ -41,7 +41,7 @@ The mount owns the `data-react-component` and `data-react-props` attributes. Oth
 
 ## Register and start components
 
-The packaged JavaScript entrypoint is `app/javascript/active_admin/react/index.js`. Configure the host's Vite, esbuild, or equivalent resolver so `active_admin/react` points to that file inside the installed gem. For example, Vite can derive the gem root with `bundle show activeadmin-react`:
+The packaged JavaScript entrypoint is `app/javascript/active_admin/react/index.js`. Its sibling `index.d.ts` describes every public registry, runtime, protocol, Cable, and operation export. Configure the host's Vite, esbuild, or equivalent resolver so `active_admin/react` points to that file inside the installed gem. For example, Vite can derive the gem root with `bundle show activeadmin-react`:
 
 ```js
 import { execFileSync } from "node:child_process"
@@ -61,6 +61,29 @@ export default defineConfig({
 })
 ```
 
+TypeScript must resolve the same import to the containing directory so it discovers
+`index.d.ts`; do not maintain a host-owned ambient declaration. For a vendored or
+otherwise stable gem path, add a compiler path such as:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "active_admin/react": [
+        "vendor/bundle/ruby/4.0.0/gems/activeadmin-react-0.3.0/app/javascript/active_admin/react"
+      ]
+    }
+  }
+}
+```
+
+Generate or update that path from `bundle show activeadmin-react` when the bundle
+location changes. The declarations reference the official React types, so TypeScript
+hosts provide versions of `@types/react` and `@types/react-dom` matching their React
+runtime. See the [TypeScript consumer contract](docs/typescript.md) for the supported
+types and an independent strict-mode verification pattern.
+
 Register every component before starting the runtime:
 
 ```js
@@ -71,7 +94,7 @@ registerComponent("OrdersTable", OrdersTable)
 start()
 ```
 
-`start()` mounts every `[data-react-component]` island, mounts newly rendered pages after `turbo:load`, and unmounts roots before Turbo caches the page. Repeated calls are safe. `stop()` removes the Turbo listeners and unmounts tracked roots. Duplicate component names, unknown components, and malformed JSON props fail loudly.
+`start()` mounts every `[data-react-component]` island, mounts newly rendered pages after `turbo:load`, and unmounts roots before Turbo caches the page. It also unmounts before `turbo:before-render` and remounts after `turbo:render`, covering form validation responses that replace page content without a new Turbo visit. Repeated calls are safe. `stop()` removes the Turbo listeners and unmounts tracked roots. Duplicate component names, unknown components, and malformed JSON props fail loudly.
 
 The shipped modules use package-style relative imports intended for a JavaScript build tool. Copying the directory directly into an importmap or serving it to browsers without a resolver is not currently a supported integration path.
 
@@ -102,6 +125,58 @@ end
 
 `ActiveAdmin::React::Contributions.diagnostics` returns entries sorted by namespace, component name, and owner. An installer can query `ActiveAdmin::React::Contributions.registry.registered?("OrdersTable")` before registering inside a reload hook. `ActiveAdmin::React::Contributions.reset!` creates a fresh registry for test isolation. Metadata hashes, arrays, sets, and strings are recursively copied and frozen during registration, so later changes to caller-owned values cannot alter registered state and diagnostics cannot mutate it. Other metadata values must be immutable objects supplied by the contributor.
 
+## Generic resumable Action Cable streams
+
+`subscribeResumable` owns only the common client transport mechanics for an application-owned, monotonically sequenced stream. The server still owns authorization, replay queries, and ordering replay before buffered live delivery:
+
+```js
+import { subscribeResumable } from "active_admin/react"
+
+const cursor = {
+  current: () => latestSequence,
+  advance: (sequence) => { latestSequence = sequence }
+}
+
+const subscription = subscribeResumable({
+  consumer,
+  channel: "AuditEventsChannel",
+  params: { audit_id: auditId },
+  cursor,
+  parse(raw) {
+    const event = parseAuditEvent(raw)
+    return { event, sequence: event.sequence }
+  },
+  onEvent: (event) => applyAuditEvent(event),
+  onStatus: (status, details) => reportConnection(status, details),
+  onProtocolError: (error, raw) => reportMalformedDelivery(error, raw)
+})
+
+return () => subscription.unsubscribe()
+```
+
+Every connection performs the fixed `resume` action with `{ after_sequence: cursor.current() }`. Cursors and parsed sequences must be non-negative safe integers. Duplicate and stale sequences are ignored. A fresh event reaches `onEvent` before the cursor advances, so a failing handler leaves the delivery eligible for replay. Protocol errors throw when `onProtocolError` is omitted. Cleanup is idempotent and unsubscribes only this subscription; shared consumers are never disconnected.
+
+The helper deliberately excludes domain reduction, terminal-state behavior, rendering, retry policy, configurable resume actions, reset/epoch semantics, authorization, and server replay implementation. See the [resumable subscription contract](docs/resumable-subscriptions.md).
+
+## Best-effort Action Cable delivery
+
+Persist durable application truth before broadcasting its live projection. `ActiveAdmin::React::Cable.broadcast` contains transport failures and returns an immutable result instead of allowing Action Cable availability to change committed domain state:
+
+```ruby
+result = ActiveAdmin::React::Cable.broadcast(
+  stream: operation.broadcast_key,
+  payload: event.envelope,
+  context: { workflow: "operation", event_id: event.id }
+)
+
+result.success? # true when Action Cable accepted the broadcast
+result.error    # the rescued transport error, or nil
+```
+
+Failures emit `broadcast_failure.active_admin_react` through `ActiveSupport::Notifications` and write one Rails error log. Diagnostics contain the stream, caller-supplied context, and error, but never the payload. Keep context bounded and non-sensitive. Logger and notification-subscriber failures are themselves contained so live delivery cannot become authoritative through observability.
+
+The helper does not provide persistence, transactions, jobs, retries, replay, or domain state. See the [Cable delivery contract](docs/cable-delivery.md) before adopting it.
+
 ## Asynchronous Action Cable operations
 
 Action Cable transports operation state; application jobs and services own the expensive work. Each event uses a server-owned operation identifier, idempotency key, and monotonic sequence:

data/RELEASES.md

@@ -8,24 +8,33 @@ maturity determine when a release is ready.
 
 ## Pre-1.0 versions
 
-Development uses ordinary `0.MINOR.PATCH` versions, with explicit `0.MINOR.PATCH.alphaN`
-and `0.MINOR.PATCH.betaN` prereleases when authorized. The first integrated prerelease
-is `0.1.0.alpha1`. Prerelease numbers start at 1 and have no leading zeroes.
-
-- Increment PATCH for fixes and small backward-compatible improvements.
-- Increment MINOR for new capabilities, meaningful API evolution, and documented breaking
-  changes while the public API remains unstable under Semantic Versioning's `0.y.z` rules.
+Development uses ordinary `0.MINOR.PATCH` versions. The first integrated dogfooding
+prerelease was `0.1.0.alpha1`; subsequent ordinary pre-1.0 development does not use
+`alpha`, `beta`, or `rc` suffixes.
+
+- Increment MINOR and reset PATCH to zero for new capabilities, meaningful API evolution,
+  and documented breaking changes while the public API remains unstable under Semantic
+  Versioning's `0.y.z` rules.
+- Increment PATCH within the current MINOR line for fixes and small backward-compatible
+  improvements.
 - Keep Rodeo-specific business behavior outside the gem. Rodeo dogfooding supplies the
   primary evidence for whether generally useful contracts are ready to stabilize.
 - Track ActiveAdmin 4 closely and consider generally useful ActiveAdmin or Arbre fixes for
   upstream contribution instead of permanent private patches.
 
-## Path to 1.0
+## Major-release stabilization
+
+Reserve `alphaN`, `betaN`, and `rcN` suffixes for an explicitly authorized major-release
+stabilization train. For the eventual path to `1.0.0`, begin that train only when Rodeo
+dogfooding indicates that the Ruby API, JavaScript adapter protocol, security guidance,
+packaging, and compatibility policy are ready to stabilize. Prerelease numbers start at
+1 and have no leading zeroes. Publish `1.0.0` only after the authorized stabilization
+phases are complete and only release-blocking defects remain.
 
-Move to `1.0.0.rc1` only when Rodeo dogfooding indicates that the Ruby API, JavaScript
-adapter protocol, security guidance, packaging, and compatibility policy are ready to
-stabilize. Publish additional candidates as `1.0.0.rcN` when needed, then publish `1.0.0`
-after only release-blocking defects remain.
+Authorization of a major-release train includes reviewed updates to the tag guard,
+workflow trigger, and protected `release` environment. The current executable policy
+admits ordinary `v0.MINOR.PATCH` tags and the previously authorized future
+`v1.0.0.rcN` shape; it does not admit suffixed `0.x` tags.
 
 The stable release guarantees an Arbre-native mounting API, deterministic React lifecycle,
 documented React and ActiveAdmin compatibility, Action Cable-friendly asynchronous
@@ -37,8 +46,9 @@ public APIs.
 1. Merge the entire reviewed stack into `master`.
 2. Ensure CI is green at the exact release commit.
 3. Update `ActiveAdmin::React::VERSION` and release notes.
-4. Tag that exact commit with the matching `v0.MINOR.PATCH`, optional `.alphaN` or
-   `.betaN` suffix, or future `v1.0.0.rcN` tag. Numeric components have no leading zeroes.
+4. Tag an ordinary pre-1.0 release as exactly `v0.MINOR.PATCH`. Use `.alphaN`, `.betaN`,
+   or `.rcN` only for an explicitly authorized major-release stabilization train. Numeric
+   components and prerelease counters have no leading zeroes.
 5. Let GitHub Actions publish through RubyGems Trusted Publishing and the `release`
    environment.
 6. Verify the gem is installable and its provenance is visible on RubyGems.org.

data/app/javascript/active_admin/react/index.d.ts

@@ -0,0 +1,225 @@
+// app/javascript/active_admin/react/index.d.ts
+
+import type { ComponentType } from "react"
+import type { Root } from "react-dom/client"
+
+export type ComponentName = string | number
+export type ComponentProps = Record<string, unknown>
+
+export function registerComponent<Props = ComponentProps>(
+  name: ComponentName,
+  component: ComponentType<Props>
+): void
+export function resolveComponent<Props = ComponentProps>(name: ComponentName): ComponentType<Props> | undefined
+export function clearComponents(): void
+
+export type MountRoot = Document | Element
+
+export function mountElement(element: HTMLElement): Root
+export function mountAll(root?: MountRoot): void
+export function unmountElement(element: HTMLElement): void
+export function unmountAll(root?: MountRoot): void
+export function start(): void
+export function stop(): void
+
+export const OPERATION_STATES: readonly [
+  "pending",
+  "queued",
+  "running",
+  "retrying",
+  "completed",
+  "failed",
+  "cancelled"
+]
+export const TERMINAL_OPERATION_STATES: readonly ["completed", "failed", "cancelled"]
+
+export type OperationStateName = (typeof OPERATION_STATES)[number]
+export type TerminalOperationStateName = (typeof TERMINAL_OPERATION_STATES)[number]
+export type OperationIgnoredReason = "duplicate" | "operation_mismatch" | "out_of_order" | "terminal"
+
+export interface OperationError<Details = unknown> {
+  code: string | null
+  message: string | null
+  retryable: boolean
+  details: Details | null
+}
+
+export interface OperationEvent<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> {
+  operationId: string | null
+  id: string | null
+  idempotencyKey: string | null
+  sequence: number | null
+  state: OperationStateName | "unknown"
+  progress: number | null
+  message: string | null
+  result: Result | null
+  resultMetadata: ResultMetadata | null
+  error: OperationError<ErrorDetails> | null
+  occurredAt: string | null
+}
+
+export interface OperationEventInput<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> {
+  operation_id?: string | null
+  operationId?: string | null
+  event_id?: string | null
+  eventId?: string | null
+  id?: string | null
+  idempotency_key?: string | null
+  idempotencyKey?: string | null
+  sequence?: number | string | null
+  state?: string | null
+  progress?: number | string | null
+  message?: string | null
+  result?: Result | null
+  result_metadata?: ResultMetadata | null
+  resultMetadata?: ResultMetadata | null
+  error?: string | Partial<OperationError<ErrorDetails>> | null
+  occurred_at?: string | null
+  occurredAt?: string | null
+}
+
+export class OperationProtocolError extends Error {
+  constructor(issues: string[])
+  issues: string[]
+}
+
+export function normalizeEvent<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown>(
+  event?: OperationEventInput<Result, ResultMetadata, ErrorDetails> | null
+): OperationEvent<Result, ResultMetadata, ErrorDetails>
+export function validateOperationEvent<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown>(
+  event: unknown
+): OperationEvent<Result, ResultMetadata, ErrorDetails>
+
+export interface OperationStateInitial<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown>
+  extends OperationEventInput<Result, ResultMetadata, ErrorDetails> {
+  occurredAt?: string | null
+}
+
+export interface AppliedOperationEvent<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> {
+  applied: true
+  reason: null
+  value: OperationEvent<Result, ResultMetadata, ErrorDetails>
+}
+
+export interface IgnoredOperationEvent<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> {
+  applied: false
+  reason: OperationIgnoredReason
+  value: OperationEvent<Result, ResultMetadata, ErrorDetails>
+}
+
+export type OperationEventOutcome<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> =
+  | AppliedOperationEvent<Result, ResultMetadata, ErrorDetails>
+  | IgnoredOperationEvent<Result, ResultMetadata, ErrorDetails>
+
+export class OperationState<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> {
+  constructor(initial?: OperationStateInitial<Result, ResultMetadata, ErrorDetails>)
+  value: OperationEvent<Result, ResultMetadata, ErrorDetails>
+  readonly lastSequence: number | null
+  apply(event: OperationEventInput<Result, ResultMetadata, ErrorDetails>): OperationEvent<Result, ResultMetadata, ErrorDetails>
+  applyEvent(event: OperationEventInput<Result, ResultMetadata, ErrorDetails>): OperationEventOutcome<Result, ResultMetadata, ErrorDetails>
+  ignored(reason: OperationIgnoredReason): IgnoredOperationEvent<Result, ResultMetadata, ErrorDetails>
+  operationMismatch(event: OperationEvent<Result, ResultMetadata, ErrorDetails>): boolean
+  outOfOrder(event: OperationEvent<Result, ResultMetadata, ErrorDetails>): boolean
+  terminal(): boolean
+}
+
+export interface OperationAccessibility {
+  role: "alert" | "status"
+  "aria-live": "assertive" | "polite"
+  "aria-busy": boolean
+}
+
+export function operationAccessibility(
+  operation?: OperationState | Pick<OperationEvent, "state"> | null
+): OperationAccessibility
+
+export type CableIdentifier = { channel: string } & Record<string, unknown>
+
+export interface CableSubscription {
+  perform(action: string, data?: Record<string, unknown>): unknown
+  unsubscribe(): void
+}
+
+export interface CableCallbacks<Raw = unknown> {
+  connected(): void
+  disconnected(details?: unknown): void
+  rejected(): void
+  received(raw: Raw): void
+}
+
+export interface CableConsumer<Raw = unknown> {
+  subscriptions: {
+    create(identifier: CableIdentifier, callbacks: CableCallbacks<Raw>): CableSubscription
+  }
+}
+
+export interface SubscribeToOperationOptions<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown> {
+  consumer: CableConsumer
+  channel: string
+  params?: Record<string, unknown>
+  operationState?: OperationState<Result, ResultMetadata, ErrorDetails> | null
+  strict?: boolean
+  resume?: boolean
+  onEvent?: (
+    event: OperationEvent<Result, ResultMetadata, ErrorDetails>,
+    current: OperationEvent<Result, ResultMetadata, ErrorDetails>
+  ) => void
+  onIgnoredEvent?: (
+    event: OperationEvent<Result, ResultMetadata, ErrorDetails>,
+    reason: OperationIgnoredReason
+  ) => void
+  onProtocolError?: (error: unknown, raw: unknown) => void
+  onConnected?: (details: { resumeFrom: number | null }) => void
+  onDisconnected?: (details?: unknown) => void
+  onRejected?: () => void
+}
+
+export function subscribeToOperation<Result = unknown, ResultMetadata = unknown, ErrorDetails = unknown>(
+  options: SubscribeToOperationOptions<Result, ResultMetadata, ErrorDetails>
+): CableSubscription
+
+export interface RequestOperationCancellationOptions {
+  url: string
+  operationId: string
+  csrfToken?: string | null
+  fetchImpl?: typeof fetch
+}
+
+export function requestOperationCancellation<Response = unknown>(
+  options: RequestOperationCancellationOptions
+): Promise<Response>
+
+export class OperationCancellationError<Response = unknown> extends Error {
+  constructor(status: number, response: Response)
+  status: number
+  response: Response
+}
+
+export interface ResumableCursor {
+  current(): number
+  advance(sequence: number): void
+}
+
+export interface ParsedDelivery<Event> {
+  event: Event
+  sequence: number
+}
+
+export type ResumableStatus = "connected" | "disconnected" | "rejected"
+
+export interface ResumableSubscription {
+  unsubscribe(): void
+}
+
+export interface SubscribeResumableOptions<Event> {
+  consumer: CableConsumer
+  channel: string
+  params?: Record<string, unknown>
+  cursor: ResumableCursor
+  parse(raw: unknown): ParsedDelivery<Event>
+  onEvent(event: Event): void
+  onStatus?: (status: ResumableStatus, details?: unknown) => void
+  onProtocolError?: (error: Error, raw: unknown) => void
+}
+
+export function subscribeResumable<Event>(options: SubscribeResumableOptions<Event>): ResumableSubscription

data/app/javascript/active_admin/react/index.js

@@ -4,6 +4,7 @@ export { clearComponents, registerComponent, resolveComponent } from "./registry
 export { mountAll, mountElement, start, stop, unmountAll, unmountElement } from "./runtime"
 export { OperationCancellationError, requestOperationCancellation, subscribeToOperation } from "./cable"
 export { OperationState, operationAccessibility } from "./operation"
+export { subscribeResumable } from "./resumable"
 export {
   normalizeEvent,
   OPERATION_STATES,

data/app/javascript/active_admin/react/resumable.js

@@ -0,0 +1,133 @@
+// app/javascript/active_admin/react/resumable.js
+
+/**
+ * @typedef {object} ResumableCursor
+ * @property {() => number} current
+ * @property {(sequence: number) => void} advance
+ */
+
+/**
+ * @template Event
+ * @typedef {object} ParsedDelivery
+ * @property {Event} event
+ * @property {number} sequence
+ */
+
+/** @typedef {"connected" | "disconnected" | "rejected"} ResumableStatus */
+
+/**
+ * @typedef {object} ResumableSubscription
+ * @property {() => void} unsubscribe
+ */
+
+/**
+ * Subscribe to an application-owned, monotonically sequenced Action Cable stream.
+ *
+ * @template Event
+ * @param {object} options
+ * @param {{ subscriptions: { create: Function } }} options.consumer
+ * @param {string} options.channel
+ * @param {Record<string, unknown>} [options.params]
+ * @param {ResumableCursor} options.cursor
+ * @param {(raw: unknown) => ParsedDelivery<Event>} options.parse
+ * @param {(event: Event) => void} options.onEvent
+ * @param {(status: ResumableStatus, details?: unknown) => void} [options.onStatus]
+ * @param {(error: Error, raw: unknown) => void} [options.onProtocolError]
+ * @returns {ResumableSubscription}
+ */
+export function subscribeResumable({
+  consumer,
+  channel,
+  params = {},
+  cursor,
+  parse,
+  onEvent,
+  onStatus,
+  onProtocolError
+}) {
+  validateDependencies({ consumer, channel, cursor, parse, onEvent })
+
+  let subscription
+  let unsubscribed = false
+
+  const reportProtocolError = (error, raw) => {
+    const normalized = error instanceof Error ? error : new Error(String(error))
+    if (onProtocolError) {
+      onProtocolError(normalized, raw)
+      return
+    }
+    throw normalized
+  }
+
+  const readCursor = (raw) => {
+    try {
+      return safeSequence(cursor.current(), "cursor.current()")
+    } catch (error) {
+      reportProtocolError(error, raw)
+      return null
+    }
+  }
+
+  subscription = consumer.subscriptions.create({ ...params, channel }, {
+    connected() {
+      const current = readCursor(undefined)
+      if (current === null) return
+
+      subscription.perform("resume", { after_sequence: current })
+      onStatus?.("connected")
+    },
+    disconnected(details) {
+      onStatus?.("disconnected", details)
+    },
+    rejected() {
+      onStatus?.("rejected")
+    },
+    received(raw) {
+      let parsed
+      let current
+
+      try {
+        parsed = parse(raw)
+        safeSequence(parsed?.sequence, "parsed sequence")
+        current = safeSequence(cursor.current(), "cursor.current()")
+      } catch (error) {
+        reportProtocolError(error, raw)
+        return
+      }
+
+      if (parsed.sequence <= current) return
+
+      onEvent(parsed.event)
+
+      try {
+        cursor.advance(parsed.sequence)
+      } catch (error) {
+        reportProtocolError(error, raw)
+      }
+    }
+  })
+
+  return {
+    unsubscribe() {
+      if (unsubscribed) return
+
+      unsubscribed = true
+      subscription.unsubscribe()
+    }
+  }
+}
+
+function validateDependencies({ consumer, channel, cursor, parse, onEvent }) {
+  if (typeof consumer?.subscriptions?.create !== "function") throw new Error("consumer is required")
+  if (typeof channel !== "string" || channel.trim().length === 0) throw new Error("channel is required")
+  if (typeof cursor?.current !== "function" || typeof cursor?.advance !== "function") {
+    throw new Error("cursor is required")
+  }
+  if (typeof parse !== "function") throw new Error("parse is required")
+  if (typeof onEvent !== "function") throw new Error("onEvent is required")
+}
+
+function safeSequence(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative safe integer`)
+  return value
+}

data/app/javascript/active_admin/react/runtime.js

@@ -16,10 +16,18 @@ function mountOnTurboLoad() {
   mountAll()
 }
 
+function mountAfterTurboRender() {
+  mountAll()
+}
+
 function unmountBeforeTurboCache() {
   unmountAll()
 }
 
+function unmountBeforeTurboRender() {
+  unmountAll()
+}
+
 function propsFor(element) {
   const raw = element.dataset.reactProps || "{}"
   return JSON.parse(raw)
@@ -60,6 +68,8 @@ export function start() {
   mountAll()
   document.addEventListener("turbo:load", mountOnTurboLoad)
   document.addEventListener("turbo:before-cache", unmountBeforeTurboCache)
+  document.addEventListener("turbo:before-render", unmountBeforeTurboRender)
+  document.addEventListener("turbo:render", mountAfterTurboRender)
   started = true
 }
 
@@ -69,5 +79,7 @@ export function stop() {
   unmountAll()
   document.removeEventListener("turbo:load", mountOnTurboLoad)
   document.removeEventListener("turbo:before-cache", unmountBeforeTurboCache)
+  document.removeEventListener("turbo:before-render", unmountBeforeTurboRender)
+  document.removeEventListener("turbo:render", mountAfterTurboRender)
   started = false
 }

data/docs/README.md

@@ -3,8 +3,11 @@
 # Documentation
 
 - [Project README](../README.md) — installation, compatibility, public APIs, supported asset integration, security, development, and troubleshooting.
+- [TypeScript consumer contract](typescript.md) — declaration discovery, public type coverage, and strict consumer verification.
+- [Resumable subscription contract](resumable-subscriptions.md) — generic Action Cable resume, cursor, protocol-error, and ownership semantics.
+- [Cable delivery contract](cable-delivery.md) — best-effort broadcast semantics, diagnostics, privacy, and host ownership.
 - [Release process](releasing.md) — maintainer validation, RubyGems Trusted Publishing, failure handling, and post-release verification.
-- [Release policy](../RELEASES.md) — ordinary pre-1.0 versioning and the path to `1.0.0.rcN` and `1.0.0`.
+- [Release policy](../RELEASES.md) — unsuffixed ordinary pre-1.0 versions and explicitly authorized major-release stabilization trains.
 - [Changelog](../CHANGELOG.md) — release notes for shipped and upcoming versions.
 - [MIT License](../LICENSE.txt) — terms for using and distributing ActiveAdmin React.
 

data/docs/cable-delivery.md

@@ -0,0 +1,35 @@
+<!-- docs/cable-delivery.md -->
+
+# Best-effort Action Cable delivery
+
+`ActiveAdmin::React::Cable.broadcast` is a narrow boundary for live projections of state that the host application has already committed. Action Cable improves responsiveness; it is never the source of truth.
+
+## Contract
+
+```ruby
+result = ActiveAdmin::React::Cable.broadcast(
+  stream: "operations:report-123",
+  payload: { type: "progress", sequence: 7 },
+  context: { workflow: "operation", event_id: 42 }
+)
+```
+
+The method attempts exactly one `ActionCable.server.broadcast`. It returns a frozen `ActiveAdmin::React::Cable::BroadcastResult`: `success?` is true with a nil `error` after the adapter accepts the broadcast; otherwise `success?` is false and `error` is the rescued `StandardError`.
+
+Broadcast after the transaction or lock that establishes durable truth. Never place persistence, enqueueing, or other authoritative work inside this failure boundary. The helper intentionally owns no retries, jobs, transactions, replay, event storage, or payload schema.
+
+## Failure observability
+
+A failed broadcast produces two best-effort diagnostics:
+
+- one `broadcast_failure.active_admin_react` notification with `stream`, `context`, and `error`;
+- one Rails error log with the same bounded diagnostic identity.
+
+The payload is never attached or logged by the helper. Context is caller-controlled, so keep it small and exclude credentials, personal information, tenant secrets, and full records. If logging or a notification subscriber fails, that diagnostic failure is contained and the original broadcast error remains available on the returned result.
+
+Success notifications, custom adapters, callbacks, configurable rescue classes, and retry options are outside the v1 contract. Add them only after independent dogfood evidence demonstrates a stable need.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/releasing.md

@@ -31,7 +31,7 @@ Before tagging, confirm every required GitHub Actions quality and package job is
 
 ## Publishing
 
-Create a tag that exactly matches the gem version with a leading `v`: `v0.MINOR.PATCH`, or an authorized prerelease `v0.MINOR.PATCH.alphaN` or `v0.MINOR.PATCH.betaN`. The first integrated prerelease is `v0.1.0.alpha1`. When Rodeo dogfooding indicates readiness to converge on 1.0, use `v1.0.0.rcN`. All numeric components have no leading zeroes, and prerelease `N` starts at 1. Other suffixes, `0.x` release candidates, `1.0.0` alpha/beta versions, and build metadata are rejected by the guard.
+Create an ordinary pre-1.0 tag that exactly matches the gem version with a leading `v`: `v0.MINOR.PATCH`. The historical first integrated dogfooding prerelease was `v0.1.0.alpha1`; ordinary `0.x` development no longer uses `alpha`, `beta`, or `rc` suffixes. Reserve those suffixes for an explicitly authorized major-release stabilization train. The current guard also permits the previously authorized future `v1.0.0.rcN` shape. All numeric components have no leading zeroes, prerelease `N` starts at 1, and suffixed `0.x` versions, unauthorized major prereleases, arbitrary suffixes, and build metadata are rejected.
 
 Push the tag only from the reviewed `master` commit. The tag-triggered `.github/workflows/release.yml` job checks out that commit and publishes through the protected `release` environment and RubyGems Trusted Publishing. Approving that environment deployment authorizes publication; local validation never does.
 

data/docs/resumable-subscriptions.md

@@ -0,0 +1,56 @@
+<!-- docs/resumable-subscriptions.md -->
+
+# Resumable Action Cable subscriptions
+
+`subscribeResumable` provides a narrow client-side lifecycle for application-owned streams with monotonically increasing integer sequences. It does not define a domain event schema.
+
+## Public contract
+
+The host supplies an Action Cable consumer, channel, optional identifier parameters, a cursor, a parser, and an event handler:
+
+```js
+const result = subscribeResumable({
+  consumer,
+  channel: "EventsChannel",
+  params: { stream_id: streamId },
+  cursor: {
+    current: () => latestSequence,
+    advance: (sequence) => { latestSequence = sequence }
+  },
+  parse: (raw) => ({ event: validateEvent(raw), sequence: raw.sequence }),
+  onEvent: (event) => applyEvent(event)
+})
+```
+
+The channel name supplied by `channel` always wins over a `channel` key in `params`. On initial connection and every reconnect, the helper performs exactly:
+
+```js
+subscription.perform("resume", { after_sequence: cursor.current() })
+```
+
+The `resume` action name and `after_sequence` parameter are fixed v1 protocol. The server authorizes the stream, queries durable events after that cursor, and orders replay before buffered live delivery.
+
+## Cursor and delivery semantics
+
+`cursor.current()` and every sequence returned by `parse` must be non-negative JavaScript safe integers. A parsed sequence less than or equal to the current cursor is ignored.
+
+For a fresh sequence, the helper calls `onEvent(event)` first. It calls `cursor.advance(sequence)` only after the handler returns successfully. A handler exception remains loud and leaves the cursor unchanged, allowing the host's replay contract to redeliver the event.
+
+Parsing failures, invalid cursor values, invalid parsed sequences, and cursor callback failures are protocol errors. When `onProtocolError` is supplied, it receives `(error, raw)`; otherwise the error is thrown. Domain handler and lifecycle callback failures are not converted into protocol errors.
+
+## Lifecycle and ownership
+
+One optional status callback receives `"connected"`, `"disconnected"`, or `"rejected"`; disconnect details are passed as its second argument. The returned `unsubscribe()` is idempotent and removes only the created subscription. It never disconnects the consumer because a host may share one consumer among many islands or streams.
+
+The host calls `unsubscribe()` from its React effect cleanup. The helper relies on Action Cable's existing reconnect behavior and adds no retry or backoff policy.
+
+## Deliberate exclusions
+
+The v1 API does not own domain reducers, terminal states, React state, rendering, consumer construction, authorization, replay storage, transactions, configurable action names, ignored-event callbacks, per-lifecycle callbacks, or reset/epoch semantics. A workflow that resets its sequence must establish a new stream identity or adopt a durable monotonic sequence before using this helper.
+
+`subscribeToOperation` remains a separate compatibility API with its existing operation-specific protocol.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/typescript.md

@@ -0,0 +1,46 @@
+<!-- docs/typescript.md -->
+
+# TypeScript consumer contract
+
+ActiveAdmin React packages `index.d.ts` beside its supported
+`app/javascript/active_admin/react/index.js` entrypoint. The declarations cover every
+runtime export from that entrypoint and export the reusable option, event, result,
+cursor, and Action Cable structural types used by those APIs.
+
+## Declaration discovery
+
+Keep the runtime build-tool alias pointed at `index.js`. Configure TypeScript's
+`active_admin/react` path to the containing `app/javascript/active_admin/react`
+directory so the compiler selects `index.d.ts`. A host should derive the installed gem
+root from `bundle show activeadmin-react`; a vendored bundle may use its stable relative
+path directly.
+
+Do not copy the declaration into the host or add an ambient
+`declare module "active_admin/react"` workaround. That would detach the application
+contract from the installed gem version. The declaration imports official React types,
+so the host provides `@types/react` and `@types/react-dom` versions compatible with its
+React runtime.
+
+## Public typing boundary
+
+The declarations describe component registration and mounting, Turbo lifecycle
+control, operation normalization and reduction, cancellation, operation subscriptions,
+and generic resumable subscriptions. Known option and result shapes use named types;
+application-owned payloads remain generic rather than being widened to a gem-owned
+domain schema.
+
+`CableConsumer` and `CableSubscription` are structural contracts. Hosts may pass the
+corresponding Action Cable objects without an adapter. `subscribeResumable<Event>`
+types the parsed delivery and handler with the host's event type while retaining the
+fixed non-negative safe-integer cursor protocol documented in
+[Resumable Action Cable subscriptions](resumable-subscriptions.md).
+
+The repository's strict independent consumer imports only `active_admin/react`. Its
+valid usage must typecheck, while separately compiled marked invalid calls must produce
+TypeScript diagnostics. Gem package and isolated-install validation also require the
+declaration file to be present.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/lib/active_admin/react/cable.rb

@@ -0,0 +1,58 @@
+# lib/active_admin/react/cable.rb
+# frozen_string_literal: true
+
+require 'action_cable'
+require 'active_support/notifications'
+
+module ActiveAdmin
+  module React
+    # Delivers non-authoritative Action Cable projections without changing durable application truth.
+    module Cable
+      FAILURE_EVENT = 'broadcast_failure.active_admin_react'
+
+      # Immutable outcome of one best-effort broadcast attempt.
+      class BroadcastResult
+        attr_reader :error
+
+        def initialize(error:)
+          @error = error
+          freeze
+        end
+
+        def success?
+          error.nil?
+        end
+      end
+
+      module_function
+
+      def broadcast(stream:, payload:, context: {})
+        ActionCable.server.broadcast(stream, payload)
+        BroadcastResult.new(error: nil)
+      rescue StandardError => e
+        report_failure(stream:, context:, error: e)
+        BroadcastResult.new(error: e)
+      end
+
+      def report_failure(stream:, context:, error:)
+        safely do
+          Rails.logger.error(
+            "ActiveAdmin React Cable broadcast failed: stream=#{stream.inspect} " \
+            "context=#{context.inspect} error=#{error.class}: #{error.message}"
+          )
+        end
+        safely do
+          ActiveSupport::Notifications.instrument(FAILURE_EVENT, stream:, context:, error:)
+        end
+      end
+      private_class_method :report_failure
+
+      def safely
+        yield
+      rescue StandardError
+        nil
+      end
+      private_class_method :safely
+    end
+  end
+end

data/lib/active_admin/react/version.rb

@@ -3,6 +3,6 @@
 
 module ActiveAdmin
   module React
-    VERSION = '0.1.0.alpha1'
+    VERSION = '0.3.0'
   end
 end

data/lib/active_admin/react.rb

@@ -2,6 +2,7 @@
 
 require 'active_admin'
 require_relative 'react/arbre'
+require_relative 'react/cable'
 require_relative 'react/contributions'
 require_relative 'react/mount'
 require_relative 'react/registry'

data/sig/active_admin/react.rbs

@@ -2,6 +2,19 @@
 
 module ActiveAdmin
   module React
+    module Cable
+      FAILURE_EVENT: String
+
+      class BroadcastResult
+        attr_reader error: StandardError?
+
+        def initialize: (error: StandardError?) -> void
+        def success?: () -> bool
+      end
+
+      def self.broadcast: (stream: String, payload: Hash[String | Symbol, untyped], ?context: Hash[String | Symbol, untyped]) -> BroadcastResult
+    end
+
     class Registry
       class Entry
         attr_reader name: String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeadmin-react
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha1
+  version: 0.3.0
 platform: ruby
 authors:
 - Stan Carver II
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0.beta22
+        version: 4.0.0.beta23
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0.beta22
+        version: 4.0.0.beta23
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
@@ -62,15 +62,21 @@ files:
 - README.md
 - RELEASES.md
 - app/javascript/active_admin/react/cable.js
+- app/javascript/active_admin/react/index.d.ts
 - app/javascript/active_admin/react/index.js
 - app/javascript/active_admin/react/operation.js
 - app/javascript/active_admin/react/protocol.js
 - app/javascript/active_admin/react/registry.js
+- app/javascript/active_admin/react/resumable.js
 - app/javascript/active_admin/react/runtime.js
 - docs/README.md
+- docs/cable-delivery.md
 - docs/releasing.md
+- docs/resumable-subscriptions.md
+- docs/typescript.md
 - lib/active_admin/react.rb
 - lib/active_admin/react/arbre.rb
+- lib/active_admin/react/cable.rb
 - lib/active_admin/react/contributions.rb
 - lib/active_admin/react/mount.rb
 - lib/active_admin/react/registry.rb
@@ -81,11 +87,11 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/scarver2/activeadmin-react/issues
-  changelog_uri: https://github.com/scarver2/activeadmin-react/blob/v0.1.0.alpha1/CHANGELOG.md
-  documentation_uri: https://github.com/scarver2/activeadmin-react/blob/v0.1.0.alpha1/README.md
+  changelog_uri: https://github.com/scarver2/activeadmin-react/blob/v0.3.0/CHANGELOG.md
+  documentation_uri: https://github.com/scarver2/activeadmin-react/blob/v0.3.0/README.md
   homepage_uri: https://github.com/scarver2/activeadmin-react
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/scarver2/activeadmin-react/tree/v0.1.0.alpha1
+  source_code_uri: https://github.com/scarver2/activeadmin-react/tree/v0.3.0
 rdoc_options: []
 require_paths:
 - lib
@@ -93,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="