Synapse/docs/adr/0021-rfx-managed-frontend-state.md

ADR 0021: RFX-managed Frontend State

Date: 2026-06-03 Status: Accepted

Context

ADR 0019 replaced Rum with HSX and moved the UI runtime onto React 19. The frontend now has a React-compatible component runtime, but application state is still managed by frontend.state through a large global atom plus many nested atoms.

The current state layer has several responsibilities mixed together:

• frontend.state/state stores the main application map.
• Many values inside that map are themselves atoms, for example editor, selection, RTC, PDF, command palette, scroll, and other high-churn UI refs.
• frontend.state/use-sub provides React subscriptions by wrapping the global atom or a nested atom with logseq.shui.hooks/use-atom.
• frontend.state/get-state, set-state!, and update-state! are used across handlers, components, workers, plugins, mobile code, and Electron integration.
• frontend.state/pub-event! publishes vectors to a core.async channel stored at :system/events.
• frontend.handler.events consumes that channel and routes events through a defmulti.
• Worker DB queries and component subscriptions use a separate reactive layer in frontend.db.react and frontend.db.hooks.
• Several subsystems use Missionary flows or direct atom watches for runtime state that is not just component state.

This makes UI reactivity explicit enough for React hooks, but the ownership is still split between path cursors, nested atoms, a global event channel, and a large set of imperative helpers. A code scan showed the size of the migration surface:

• about 178 state/use-sub call sites under src/main/frontend;
• about 310 set-state! or update-state! call sites under src/main/frontend;
• about 190 pub-event! call sites under src/main/frontend;
• about 102 frontend.handler.events/handle methods.

RFX is a better fit for the next step because it keeps the re-frame style architecture while using React Context and hooks instead of Reagent. It provides scoped app instances, use-sub, dispatch, reg-sub, reg-event-db, reg-event-fx, effects, coeffects, snapshots, and a queue. Logseq has already forked RFX and added root deps.edn support on logseq/rfx branch logseq/fork, commit d37aaceb37fcaf969c5cd04646dfdb985d65d3c2.

The migration must not destabilize editor input, block trees, DB worker transactions, RTC, plugin APIs, Electron IPC, mobile native flows, or DataScript query subscriptions.

Decision

Adopt RFX as the frontend application state and event runtime.

Add RFX to the main frontend dependency root from the Logseq fork:

io.github.logseq/rfx
{:git/url "https://github.com/logseq/rfx.git"
 :git/sha "d37aaceb37fcaf969c5cd04646dfdb985d65d3c2"}

Create a Logseq-owned RFX context, store, and registry. The context should be provided near the root render in frontend.core, around page/current-page. The RFX instance must be initialized during frontend startup before event handling starts.

Replace frontend.state as the state owner in one coordinated migration. Existing non-hook public entry points may remain as thin call-through APIs only when they preserve caller compatibility without keeping state outside RFX:

• get-state
• set-state!
• update-state!
• pub-event!
• focused helpers such as get-current-repo, set-current-repo!, get-config, editor helpers, selection helpers, and RTC helpers

Replace all frontend.state/use-sub and focused hook call sites with rfx/use-sub or Logseq-owned domain hooks backed by RFX subscriptions. Do not keep frontend.state/use-sub as a compatibility wrapper. get-state, set-state!, update-state!, and focused non-hook helpers should read snapshots or dispatch RFX events instead of mutating the old global atom.

Use one source of truth:

• Frontend application state is plain data in the RFX app db and is updated through RFX events.
• Nested atoms must not remain as the representation for application state. Convert nested atom state to plain values and path updates during the migration.
• Missionary flows and direct atom watches must not remain as state propagation paths for frontend application state. Replace them with RFX subscriptions, events, effects, and coeffects.
• Imperative resources such as DOM nodes, editor handles, timers, external worker objects, Electron handles, and plugin runtime handles stay outside the RFX app db. They may be held in refs only when they are not renderable application state and do not drive UI subscriptions directly.

Migrate every frontend state domain and its event handlers in the same change. Do not land partial domain migrations. State-only migrations that still rely on frontend.handler.events/handle for writes are rejected, and event-only migrations whose render state still lives behind legacy path cursors are also rejected.

pub-event! may remain as the public promise-returning compatibility API for callers, but it should dispatch into RFX instead of writing to :system/events. It must route to explicit rfx/reg-event-db or rfx/reg-event-fx registrations and resolve or reject the deferred promise from the RFX event result. Do not keep a bridge that invokes the existing frontend.handler.events/handle multimethod.

Use RFX to replace flow-based frontend state propagation. DataScript execution and worker-owned invalidation can remain worker responsibilities, but UI-facing query result state and refresh orchestration should be exposed through RFX subscriptions and events instead of Missionary flows or atom watches.

Migration Shape

The migration should be one coordinated replacement of the frontend state and event runtime.

1. Add the RFX dependency and create a small frontend.rfx namespace that owns the app context, registry, initialization, dispatch helpers, and root provider.
2. Move the initial plain app state map construction out of the defonce state expression into a reusable function.
3. Move all frontend application state domains to plain RFX app-db values, including route state, graph/current repo state, search, modals, sidebars, theme flags, auth tokens, import/loading state, editor state, selection, command palette, PDF, RTC UI state, plugin UI state, Electron UI state, and mobile UI state.
4. Replace all frontend.handler.events/handle methods with explicit rfx/reg-event-db or rfx/reg-event-fx registrations. Keep event ids domain-scoped and register effects/coeffects for DB worker calls, RTC, plugins, Electron IPC, mobile native calls, and async error capture.
5. Replace :system/events with RFX dispatch behind pub-event! and remove the core.async event channel.
6. Replace Missionary flows and direct atom watches that propagate frontend application state with RFX subscriptions, events, effects, and coeffects.
7. Replace all frontend.state/use-sub and focused state hook call sites with rfx/use-sub or domain hooks backed by rfx/reg-sub.
8. Remove nested atoms, path cursors, and legacy hook paths for application state. Keep refs only for imperative resources that do not represent renderable state.
9. Update tests in the same change so every moved domain has coverage for state reads, event-driven writes, async effects, and promise resolution.

Each domain should have a clear owner namespace, subscription ids, event ids, effects, coeffects, and test coverage.

Consequences

State ownership becomes explicit. Components subscribe through React-safe RFX hooks, while non-view code can use RFX snapshots and dispatch against the same instance.

Tests and isolated UI surfaces can create scoped RFX contexts instead of mutating the global frontend.state/state atom. This matches the context model introduced by the HSX migration.

The event system gains a uniform event/effect/coeffect shape and immediately replaces the core.async channel plus defmulti dispatch path.

The migration cannot be a mechanical atom swap. Nested atom mutation does not automatically notify RFX subscriptions. State must move to plain values, and writes must move to RFX events.

Compatibility wrappers may remain only as public API aliases that call into RFX. They must not retain separate storage, separate event dispatch, Missionary flow state propagation, or direct atom-watch state propagation.

RFX effects that run async work must preserve existing error reporting behavior, including :capture-error and promise rejection paths used by callers of pub-event!.

Rejected Alternatives

Keep frontend.state As-is

This avoids migration cost but leaves Logseq with a custom subscription system after the React 19 and HSX migration. It also keeps event routing separate from state updates and does not give isolated RFX contexts for tests or component development.

Replace Only pub-event!

Moving events to RFX while leaving render state on path cursors would improve event structure, but components would still subscribe through the custom atom layer. It would not solve the state ownership problem.

Migrate Domain-by-Domain

An incremental domain migration would leave two state and event runtimes active for too long. That would preserve the current split ownership across RFX, legacy path cursors, Missionary flows, atom watches, the core.async event channel, and defmulti handlers. The migration should replace all frontend application state domains and handlers together.

Migrate State Without Event Handlers

Moving state keys to RFX while keeping their writes in frontend.handler.events/handle would preserve the current split ownership in a new form. RFX-managed state must be written through RFX events, so state and event handlers should move together.

Keep frontend.state/use-sub As A Wrapper

Keeping frontend.state/use-sub as a compatibility hook would preserve the old subscription boundary and make it harder to see which code is using RFX subscriptions directly. All hook call sites should move to rfx/use-sub or domain hooks backed by RFX.

Keep Missionary Flows For Frontend State

Keeping Missionary flows or atom watches as frontend state propagation would leave RFX as only a partial store. Worker internals can still use their own runtime mechanisms, but UI-facing state should be expressed through RFX subscriptions and events.

Keep DataScript Query Reactivity Outside RFX

Keeping frontend.db.react and frontend.db.hooks/use-query as a separate UI-facing subscription layer would leave another flow-like state runtime beside RFX. Query execution and worker invalidation may stay in the DB worker, but the frontend-facing subscription and refresh contract should be mediated through RFX.

Verification

Before accepting the migration, verify:

• root rendering is wrapped in the Logseq RFX context;
• no frontend.state/use-sub call sites remain;
• direct rfx/use-sub and domain hook call sites obey React hook ordering;
• RFX-managed keys re-render components after set-state!, update-state!, and event handlers update them;
• all frontend application state domains update through RFX events, with no remaining legacy defmethod handle write path;
• no Missionary flow or direct atom watch remains as a frontend application state propagation path;
• non-managed refs are limited to imperative resources and do not drive UI subscriptions directly;
• pub-event! still returns a promise that resolves or rejects with the event result;
• event errors are logged and reported through the existing capture path;
• graph switching, route changes, theme toggles, sidebars, modals, settings, search, import progress, login state, plugin UI, Electron IPC, mobile tabs, RTC indicator, editor editing, and block selection keep prior behavior;
• UI-facing DB query result subscriptions and refresh orchestration go through RFX, while worker-owned query execution and invalidation keep prior behavior;
• no React hook-order warnings, invalid element warnings, or missed subscription updates appear in Chrome;
• focused unit tests cover every state domain, event registration, effect, coeffect, non-hook compatibility wrapper, and replaced flow path;
• bb dev:lint-and-test passes;
• relevant app or CLI E2E tests pass for graph switch, editor input, selection, sidebar, settings, plugin, and sync surfaces touched by the migrated keys.