Synapse/docs/adr/0018-rum-hooks-refactor.md

ADR 0018: Complete Rum Hooks Refactor

Date: 2026-05-29 Status: Proposed

Context

Logseq frontend, mobile, and shui UI code still relies on Rum mixins and old Rum lifecycle maps for state, subscriptions, query registration, event listeners, memoization, DOM effects, and cleanup.

The current master tree has broad usage:

• 542 rum/defc components and 120 rum/defcs components under src/main and deps/shui/src.
• 100 rum/local usages.
• Heavy use of rum/reactive, rum/static, db-mixins/query, mixins/container-id, custom lifecycle maps, and :should-update.
• Shared mixin definitions in src/main/frontend/mixins.cljs and src/main/frontend/db_mixins.cljs.
• Existing hook wrappers in deps/shui/src/logseq/shui/hooks.cljs, with selected atom hooks re-exported from src/main/frontend/rum.cljs.

Mixins hide side effects and make component behavior harder to reason about. The most sensitive cases are editor focus and cursor handling, block tree rendering, reactive query refresh, plugin rendering, PDF/code integrations, and mobile mount/unmount effects.

Decision

Replace all existing Rum mixins and Rum lifecycle maps with hook-based component code as a complete refactor.

The migration uses one explicit hook path for state, effects, subscriptions, event listeners, query registration, memoization, and cleanup. The old mixin namespaces must be removed by the end of the refactor, not left as wrappers or compatibility shims.

The migration applies to:

• src/main/frontend/
• src/main/mobile/
• deps/shui/src/

The refactor is not complete until there is no behavior regression and no performance regression on the affected UI paths. Any replacement hook must match the old lifecycle timing, subscription semantics, cleanup behavior, and memoization characteristics where those characteristics were observable.

Replacement code must use public React/Rum hook APIs only. It must not depend on Rum internals such as rum/*reactions*, private dynamic bindings, or reimplementations of rum/reactive under another name.

Hook Foundation

Add hook APIs before migrating broad component areas. These hooks are the new implementation path, not an adapter layer over the old mixin namespaces.

1. Add subscription hooks for render-time rum/react, util/react, and state/sub usage:
   • frontend.state/use-sub
   • frontend.state/use-sub-config
   • frontend.state/use-sub-editing?
   • keep frontend.rum/use-atom and frontend.rum/use-atom-in as the atom-level APIs.
2. Replace db-mixins/query with an explicit hook-backed query scope. db-mixins/query currently binds frontend.db.react/*query-component* and *reactive-queries* during render, then removes the component token on unmount. The replacement should create a stable component token with use-ref, register cleanup with use-effect!, and bind query tracking while rendering the body.
3. Replace rum/local with:
   • rum/use-state for values that affect rendering;
   • rum/use-ref for mutable values that should not trigger rendering;
   • frontend.rum/use-atom only where the state is intentionally atom-shaped and shared with existing functions.
4. Replace event mixins with hook APIs:
   • use-event-listener
   • use-window-keydown
   • use-window-keyup
   • use-hide-on-esc-or-outside
   • use-modal-state
5. Replace mixins/container-id with an explicit use-container-id hook that derives from the same stable key currently built in the mixin.

Lifecycle Mapping

Rum lifecycle maps are migrated directly to hooks:

• :init: use lazy use-state, use-ref, or pure let bindings. Do not move side effects here.
• :will-mount: use use-effect! or use-layout-effect! with an empty dependency vector.
• :did-mount: use use-effect! [] for subscriptions, timers, and network work; use use-layout-effect! [] for focus, sizing, and DOM measurement.
• :did-update: use use-effect! with explicit dependencies. Use a first-render guard only when old behavior intentionally skipped mount.
• :will-update: derive values during render, or use a previous-value ref plus effect when side effects are required.
• :will-unmount: return cleanup from the effect that created the resource.
• :wrap-render: replace with explicit wrapper functions, macros, profiling calls, or error-boundary components.
• :should-update and rum/static: replace with smaller memoized child components, React.memo, or no memoization if the old optimization is not meaningful.
• :did-catch: keep explicit class-based error boundaries where needed. React hooks cannot replace render error boundaries.

Migration Order

Phase 1: Hook Foundation

1. Add state subscription, event listener, container id, and query-scope hooks.
2. Add focused tests for subscription cleanup and query cleanup.
3. Add a lint/search check that blocks new Rum mixin usage.
4. Migrate one small component from each behavior category:
   • one rum/local component;
   • one lifecycle component;
   • one db-mixins/query component;
   • one rum/reactive component.

Phase 2: Low-Risk Leaf Components

Migrate components without editor focus, query refresh, plugin rendering, or PDF behavior.

Good first targets:

• src/main/frontend/components/avatar.cljs
• src/main/frontend/components/window_controls.cljs
• src/main/frontend/components/find_in_page.cljs
• src/main/frontend/components/selection.cljs
• simple src/main/mobile/components/* components
• simple deps/shui/src/logseq/shui/* components

For each file, remove mixins, convert rum/defcs to rum/defc when the state parameter is gone, and use hooks for subscriptions and effects.

Phase 3: Shared Query Components

Migrate components that combine rum/reactive and db-mixins/query.

Targets include:

• page and block references;
• property values;
• query result views;
• journal and all-pages views;
• right sidebar block/page renderers.

Every react/q consumer should move from util/react or rum/react to a hook subscription. Query cleanup must be verified by checking frontend.db.react component maps after mount/unmount.

Phase 4: Editor, Block Tree, and Navigation

Migrate the high-risk rendering core in small PRs by behavior:

1. Editor search and autocomplete lifecycles.
2. Editor input event listeners and cursor restoration.
3. Block content/edit switching.
4. Asset rendering and upload/download state.
5. Block container query scope and sidebar state.
6. Page mount/update side effects.
7. Header/sidebar collaboration and recent-highlight behavior.

Primary files:

• src/main/frontend/components/editor.cljs
• src/main/frontend/components/block.cljs
• src/main/frontend/components/page.cljs
• src/main/frontend/components/header.cljs
• src/main/frontend/components/container.cljs

Use use-layout-effect! for focus, selection, size, and scroll effects that depend on mount/update ordering.

Phase 5: Extensions and Heavy Integrations

Migrate extension components after core hooks are stable:

• src/main/frontend/extensions/code.cljs
• src/main/frontend/extensions/fsrs.cljs
• src/main/frontend/extensions/latex.cljs
• src/main/frontend/extensions/pdf/core.cljs
• src/main/frontend/extensions/video/youtube.cljs

These contain third-party DOM integrations, delayed rendering, timers, and external cleanup. Prefer one integration per PR.

Phase 6: Remove Old Mixin API

After all usage is gone:

1. Delete src/main/frontend/mixins.cljs; move any still-needed non-mixin helper logic into hook-focused namespaces before deletion.
2. Delete src/main/frontend/db_mixins.cljs.
3. Remove unused rum/reactive, rum/static, rum/local, and lifecycle map imports/usages.
4. Keep a permanent lint or CI search check blocking:
   • rum/reactive
   • rum/static
   • rum/local
   • rum/defcs
   • lifecycle keys in Rum component declarations
   • frontend.mixins
   • frontend.db-mixins

Consequences

• Component side effects become explicit and locally inspectable through hooks.
• Query refresh cleanup must preserve stable component identity, or query state can leak.
• Subscription hooks need explicit dependency handling to avoid stale renders.
• Editor focus and cursor behavior can regress if layout-sensitive work moves to normal effects.
• Removing rum/static and :should-update may change render frequency. Hot paths need smaller memoized children or measured React.memo usage.
• Error boundaries remain a class-component concern and must be represented as explicit boundary components.
• The refactor has a hard cleanup boundary: frontend.mixins and frontend.db-mixins must not remain in the final tree.
• Performance-sensitive paths need before/after evidence when their memoization, subscription, or render frequency changes.

Verification

Each migration batch should run the narrowest relevant checks first, then broader checks for shared behavior:

• focused hook tests for subscription and query cleanup;
• namespace-level unit tests where present;
• smoke compile for frontend and mobile targets;
• manual smoke checks for page load, block edit, slash command, page search, block search, toggle block, drag block, right sidebar, asset block, query blocks, PDF, code block rendering, flashcards, and YouTube embeds;
• app E2E tests for affected UI flows must pass. Run bb test from clj-e2e/, or bb -f clj-e2e/bb.edn test from the repo root;
• CLI E2E tests must pass when a migration batch touches CLI-facing behavior, command rendering, graph import/export behavior, or shared code used by the CLI. Run bb -f cli-e2e/bb.edn test --skip-build from the repo root after building when needed;
• render-count or profiling checks for hot paths whose rum/static, :should-update, query subscription, or editor/block rendering behavior changes;
• bb dev:lint-and-test before merging broad shared changes.

Completion Criteria

• No rum/reactive, rum/static, rum/local, rum/defcs, frontend.mixins, or frontend.db-mixins usage remains in application component code.
• src/main/frontend/mixins.cljs and src/main/frontend/db_mixins.cljs are removed from the repository.
• No Rum lifecycle maps remain in component declarations.
• Query subscriptions mount, refresh, and unmount without leaking entries.
• Editor, block tree, page navigation, right sidebar, properties, query results, PDF, code, and mobile surfaces pass focused smoke checks.
• No known behavior regressions remain open against the affected UI paths.
• No known performance regressions remain open against the affected hot paths.
• Relevant app E2E tests pass for every affected UI flow.
• CLI E2E tests pass for batches that affect CLI-facing shared behavior.
• bb dev:lint-and-test passes.

Follow-up Work

1. Implement the hook foundation and tests.
2. Add the lint/search guard for new mixin usage.
3. Migrate low-risk leaf components first.
4. Migrate query-scope components outside the editor/block tree.
5. Migrate the editor, block tree, page, header, and container components.
6. Migrate extension integrations.
7. Delete old mixin namespaces and enforce the permanent ban.
8. Capture before/after performance evidence for editor, block tree, page load, right sidebar, query result, and PDF/code surfaces before declaring the refactor complete.