Code React

code-react

React in this repo is a thin layer over a framework-agnostic engine. These conventions protect that thinness — where logic is allowed to live, and where test landmarks land in the DOM — so the React layer stays replaceable and easy to read.

Hooks live at the edge

React hooks must not appear in the main system — the canvas engine, reducers, document model, font manager, presentation engine, command handlers, anything that represents domain state or compute logic. Hooks live only at the React edge: small use-* adapters that bridge engine state into components, plus component-local UI state.

The reason is that hooks cannot be tested, cannot be benchmarked, and cannot be reasoned about by inspection once their composition crosses more than a couple of layers. In a complex editor — where one render is a chain of conditional effects, memoized derivations, and re-entrant subscriptions — the execution order and re-render layering are the behavior. A subtle ordering change, a missed dep, a state read one tick later, and the user-visible UX shifts. Features you tuned will get silently dropped — no failing test, no benchmark regression, no noisy error to alert you. By the time someone notices, the regression is weeks deep and no bisect helps, because nothing was ever measurable.

The escape is not "test your hooks better," not "be more careful with deps," not "add a renderHook suite." It is don't use hooks for anything load-bearing in the first place. The rule is prevention, not discipline — discipline fails at the third layer of composition; prevention does not. Logic that matters lives in a class or namespace where the execution order is explicit, the contract is testable, and the hot path is benchmarkable. The hook is reduced to a wire — short enough that you can verify it by sight, and small enough that not testing it is honest.

A hook is acceptable in exactly two situations:

1. Not testing it is honest. The hook calls useSyncExternalStore, useContext, or a useEffect lifecycle, with no branch and no derivation. The test would be tautological.
2. The spec would be longer than the code. The hook is short enough that no test could catch a bug the code couldn't already reveal at sight.

If a hook fails both — branching logic, derivations, coordination across effects, anything you would want to benchmark or assert on — extract the logic out, test and benchmark it there, and reduce the hook to a three-line call site.

A pair of examples pins the boundary:

• Fine. useState and hooks for component-local UI state — hover, focus, open/closed, the in-flight value of an input about to be committed. The spec is the code; not testing it is honest.
• Never. Hooks for features layered on top of a rich-text or canvas runtime — a slash-menu, mention picker, inline toolbar plugin, anything that composes with the host editor's state machine. Even when the host (e.g. tiptap, lexical) is hook-friendly, your features run on an execution order you do not own. Build them as classes or namespaces against the host's imperative API; React renders the result.

The split is structural, not lint-enforced. The engine package must not import React. The React bindings consume the engine through its public surface — never the reverse — so the engine stays replaceable and the bindings stay verifiable by sight. A use-* that wires useSyncExternalStore, useContext, or a disposal useEffect to the engine is the entire allowed shape; anything more is engine logic in the wrong package.