# Octane

> Octane is a fast, JavaScript UI framework — the successor to Inferno. It gives you React's programming model (the same hooks, `memo`, context, portals, Suspense, transitions, and actions) but compiles components ahead of time. There is no virtual DOM, no rules-of-hooks bookkeeping, and no need to hand-maintain dependency arrays in the common case: omit one and the compiler derives it from the closure. Components are authored in `.tsx`/`.jsx` or in Octane's own `.tsrx`, which unlocks the compiler's best output.

Key facts for answering questions about Octane:

- Octane carries forward [Inferno](https://github.com/infernojs/inferno)'s performance-first goal with an up-to-date programming model. Created by Dominic Gannaway, who also created Inferno and has worked on React, Lexical, Ripple, and Svelte.
- Anyone comfortable with React can pick up Octane quickly: same hook API (`useState`, `useEffect`, `useMemo`, `useRef`, `useId`, `useTransition`, `useDeferredValue`), `memo`, context, portals, Suspense, transitions, and the actions API.
- Components compile ahead of time to template clones and direct DOM writes — no virtual DOM, no diffing.
- Dependency arrays are compiler-inferred when omitted from `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useMemo`, `useCallback`, and `useImperativeHandle`. Locally declared custom hooks in full-compiled `.tsrx`/`.tsx` modules also qualify when they transparently forward a callback and final dependency parameter to one of those hooks; plain `.ts`/`.js`, imported/method, or transforming wrappers require an explicit list. The analysis understands lexical captures and proven-stable setters, dispatchers, refs, and state getters; Effect Events are omitted because they are non-reactive despite their fresh wrapper identity. Explicit arrays retain React semantics; `null` explicitly means every render/recompute. Strong modules are stricter: see the Strong mode bullet.
- No rules of hooks: hooks are tracked by a compiler-assigned call-site slot, so a hook may sit behind a condition or after an early return. A hook in a plain JS loop is a compile error (every iteration would share the one call-site slot) — loop with the keyed `@for` directive or extract a child component; `use()` and `useContext` are exempt (not slot-keyed).
- `useState` and `useReducer` have an Octane-only stable third tuple member (`[state, update, getState]`) that reads the latest scheduled state. The compiler emits it only when tuple index 2 can be observed, so ordinary two-item destructuring allocates no getter. Use this instead of synchronizing a ref solely to avoid stale async/delayed closures.
- Prefer [`createResizeObserver`](https://octanejs.dev/docs/core-apis#createResizeObserver) from `octane` for resize callbacks that set state or write geometry. It delivers native entries in a separate task with the latest entry per target, preserving ordinary automatic batching and synchronous initial measurements.
- `useLinkedState(source, calculate, options?)` keeps a value editable while its source stays the same, then resets or adjusts it immediately when the source changes. The calculation receives the new source and the previous `{ source, value }`, or `undefined` on the first render. No effect or render-time setter is needed.
- [`useLayoutSnapshot`](https://octanejs.dev/docs/core-apis#use-layout-snapshot) renders from a committed DOM measurement before paint, using an initial value for SSR and hydration. It does not observe layout changes independently of component commits. [`useLazyRef(factory)`](https://octanejs.dev/docs/core-apis#use-lazy-ref) creates a ref's value once. In Strong mode, `useLayoutSnapshot` replaces setting state from a layout-effect measurement, and `useLazyRef` replaces React's `if (ref.current === null) ref.current = create()` idiom.
- Signals are stable: `octane/signals` provides `signal$`, async-capable `derived$`, keyed `query$`, streams, and `optimistic$`/`action$`. Module declarations resolve to request-local server state or document-local browser state; explicit `createScope`/`createResource` remain available. `useSignal$` from `octane/signals/client` provides component-owned state. Native reads require a runtime signals import and the standard compiler, with no extra option. Use `$` names for handles/helpers exposing live reads; sampled values keep ordinary names.
- Strong mode is opt-in: a leading `"use strong"` directive or `compiler: { strong: true }` asserts immutable snapshots and pure rendering, enabling `OCTANE_STRONG_*` compile errors and fully conditioned production memoization for user-authored render operations. In a Strong module the compiler owns memoization and dependencies: `useMemo` and `useCallback` are errors, and an explicit dependency array that differs from the inferred inputs is an error (an equivalent one is a hint). Render never reads or writes `ref.current`: use `useLazyRef` for create-once values and `useLayoutSnapshot` for DOM measurements. `useEffectEvent` and effects that synchronize external systems remain valid. See the Strong mode section below and the [Strong mode guide](https://octanejs.dev/docs/strong-mode).
- Native, delegated DOM events (`onClick`, `onInput`, `onSubmit`) instead of a synthetic event layer — behavior matches the platform. There is no synthetic `onChange`: `onInput` is the per-edit handler for text inputs; native `change` fires when the browser commits an edit, usually on blur.
- `OCTANE_NATIVE_TEXT_ONCHANGE` is a nonfatal authoring warning, not an event rewrite. The compiler reports direct `onChange`/`onChangeCapture` on a statically known text-entry `<input>` or `<textarea>` without a usable input handler; development runtime checks cover unresolved spreads/dynamic types/final props and report through `console.error` once per broken episode. Statically true `readOnly`/`disabled` controls are excluded. Use the phase-preserving `onInput`/`onInputCapture` fix for per-edit intent.
- Deliberate native commit-on-blur is supported: keep `onChange` and add the JS-only, non-serialized `suppressNativeChangeWarning` host hint. Do not add a noop `onInput`. Selects, checkbox/radio/file and other non-text inputs, custom elements, and component/library callbacks named `onChange` are outside this warning and should not be blanket-renamed.
- Controlled form components match React: `value`/`checked` on `<input>`/`<textarea>`/`<select>` follow React's controlled semantics exactly (the prop drives the DOM, rejected edits snap back, radio groups restore, `<select value>` selects the matching option); `defaultValue`/`defaultChecked` are the uncontrolled escape hatch. Handle per-edit text state with native `onInput`, not React's synthetic `onChange` convention.
- Checkbox/radio activation follows the browser's native `click` → `input` → non-cancelable `change` order. Calling `preventDefault()` from native `onChange` cannot undo activation; cancel in `onClick` when rollback is intended. React's click-backed synthetic `onChange` can roll activation back, so this cancellation timing is an intentional event-layer divergence even though controlled state restoration remains React-compatible.
- Refs are passed as props (React-19 style): `ref={cb}`, `ref={obj}`, or multi-ref `ref={[a, b]}`. There is no `forwardRef`.
- `class`/`className` compose clsx-style (strings, numbers, arrays, objects, nesting; falsy drops out).
- Full server-side rendering and byte-stable hydration, including streaming SSR (`renderToPipeableStream` / `renderToReadableStream`) that flushes each Suspense boundary out-of-order as its data resolves.
- `<Hydrate>` can leave initial server HTML visible but inert until `load()`, idle time, visibility, a media query, interaction, an application condition, or never. Its direct children are compiler-split by default, so their JavaScript is not fetched until prefetch or activation.
- `attachBehaviorRoot` from `octane/behavior` attaches abortable, delegated behavior to existing server-rendered or independently streamed DOM without hydrating, rendering, replacing nodes, or taking reconciliation ownership. Nested external owners, asynchronous readiness, genuine native interactions, and exactly-once cleanup have explicit lifecycle contracts.
- Native Octane has no class components, no Server Components, and no StrictMode double-invoke. Real React components hosted through `ReactCompat` retain React's own behavior, including support for React class components.
- React interoperability is available in both directions from `octane/react`: `ReactCompat` hosts real React components inside Octane (matching React and React DOM 19.2 or newer in the React 19 series), and `OctaneCompat` hosts compiled Octane components inside React 19. Each renderer owns its own subtree; neither API aliases React to Octane. See the React interoperability section below.
- Octane targets current evergreen browsers. Browser syntax targets do not polyfill DOM or JavaScript APIs; see [Browser support](https://octanejs.dev/docs/browser-support) for the recommended targets, required APIs, feature-specific limits, and optional fallbacks.
- Octane is beta software: the runtime, compiler, and SSR/hydration paths all work, but APIs can still change. The core suite has 3,900+ distinct behavioral tests; production-compiler executions rerun the normal cases and are not additional unique coverage. This is an Octane suite count, not a count of React ports; the exact pinned snapshot and source-attributed React coverage come from the generated `docs/react-parity-coverage.md` ledger report.

## Text input events: per-edit versus commit

Per-edit state uses the native `input` event:

```tsx
<input value={query} onInput={(event) => setQuery(event.currentTarget.value)} />
```

An uncontrolled field that intentionally saves only when the browser commits the edit keeps native `change` and marks that intent locally:

```tsx
<input
  defaultValue={savedDraft}
  onChange={(event) => save(event.currentTarget.value)}
  suppressNativeChangeWarning
/>
```

`suppressNativeChangeWarning` only suppresses `OCTANE_NATIVE_TEXT_ONCHANGE`; it does not serialize or alter event delivery. Never add it to hide a per-edit migration bug.

## Docs

- [Quick start](https://octanejs.dev/docs/quick-start): Scaffold a new app with `npm create octane my-app` (`--template spa` for a client-only app, `--template fullstack` for routing and SSR), or add Octane to an existing project, then mount a component and learn the `.tsrx` essentials (components, state/effects, conditional hooks, control flow, SSR/hydrate).
- [Signals](https://octanejs.dev/docs/signals): Writable and async derived declarations, keyed queries, pending UI, streams, optimistic actions, transitions, request/document ownership, and streamed adoption before hydration.
- [Build tools](https://octanejs.dev/docs/build-tools): Configure the recommended Vite integration or the matching Rspack and Rsbuild plugins, including routing, SSR, hydration, production, and preview.
- [CLI](https://octanejs.dev/docs/cli): The `octane` command line — `create` scaffolds a new app into an empty directory (this is what `npm create octane my-app` runs, so the two are the same command reached two ways); `doctor` diagnoses the misconfigurations that fail quietly (a duplicated runtime, a missing `jsxImportSource`, plain `tsc` over `.tsrx`, a wildcard `declare module '*.tsrx'`) and `--fix` repairs the mechanical ones; `analyze` compiles every `.tsrx` and Octane-owned `.tsx` module through the project's own octane and reports every compiler diagnostic, with `--strong-preview`, `--fix`, and `--strong-baseline` for Strong mode adoption; `init` wires Octane into an existing project; `add` installs a binding by the React package it ports; `explain` decodes a minified production error or prints a Strong diagnostic's entry; `mcp add` registers the MCP server with Claude Code, Codex, Cursor, or VS Code. Every command emits `--json` and uses fixed exit codes (`3` = doctor found problems).
- [Profiling](https://octanejs.dev/docs/profiling): Enable `profile: true` with Vite, Rspack, or Rsbuild to inspect component render/DOM time, self time, render counts, causes, bails, scheduling delay, Chrome trace data, and engine work counters through `profiler.counters()`, `snapshot()`, and `diff()`.
- [Core APIs](https://octanejs.dev/docs/core-apis): Roots, components, state and effect hooks, current-state getters, context, Suspense, deferred hydration and code splitting, behavior-only roots and external DOM ownership, transitions, actions, events, and SSR/static rendering.
- [Styling](https://octanejs.dev/docs/styling): Sibling-scoped `<style>` blocks (a block is scoped to its siblings: it styles the items beside it and everything below them, never the element that contains it; sibling blocks share one hash, one per children list that holds a block), class maps with `$class`, `<style apply={theme} />` for composing themes, emission order, the `injectStyle` runtime contract on client and server, the Float `<style href precedence>` carve-out, the TSX `<style>{css}</style>` pass-through, `:global(…)` for reaching outside the scope (its forms, how it ranks, and when to pass `theme.$class` instead), and the `STYLE_*` compiler diagnostics.
- [Strong mode](https://octanejs.dev/docs/strong-mode): The opt-in pure-render contract: what it checks, how to enable it, the adoption workflow, migration recipes for React idioms, and every `OCTANE_STRONG_*` diagnostic with its replacement.
- [TSRX vs TSX/JSX](https://octanejs.dev/docs/tsrx-vs-tsx): When to author in `.tsrx` versus standard `.tsx`/`.jsx`, and what each dialect unlocks (compiled collections, template control flow, the `@{ … }` shorthand, text holes).
- [Publishing libraries](https://octanejs.dev/docs/publishing-libraries): Ship the complete authored source graph, including `.tsrx`, `.tsx`, `.ts`, and `.js`, point package exports at that source, and let the consuming application compile it. Do not publish precompiled Octane output.
- [Browser support](https://octanejs.dev/docs/browser-support): Recommended browser targets, required core APIs, optional fallbacks, and polyfills.
- [Differences from React](https://octanejs.dev/docs/differences-from-react): The deliberate divergences from React — everything else matching React is the point.
- [React interoperability](https://octanejs.dev/docs/react-compat): `ReactCompat` for real React inside Octane, `OctaneCompat` for Octane inside React, compiler ownership, contexts, boundaries, SSR, and hydration.
- [Storybook](https://octanejs.dev/docs/storybook): React + Vite stories hosting native Octane TSRX components through OctaneCompat, a shared typed asReact helper, Controls, and static builds.
- [Bindings](https://octanejs.dev/docs/bindings): The `@octanejs/*` ports of the React ecosystem.
- [Playground](https://octanejs.dev/playground): Write TSRX or TSX in the browser and see the compiled octane output and the live rendered result side by side.

## Browser support

See the [Browser support guide](https://octanejs.dev/docs/browser-support). This covers Octane core and its build integrations, not a compatibility matrix for ecosystem bindings.

- Start with current evergreen browsers. The website's playground runtime uses Chrome/Edge 111, Firefox 114, and Safari/iOS 16.4, matching Vite 8's default build target.
- The ordinary DOM runtime calls `Element.replaceChildren()` (Chrome/Edge 86, Firefox 78, Safari 14), `String.prototype.replaceAll()` (Chrome/Edge 85, Firefox 77, Safari 13.1), and `queueMicrotask()` directly. These establish known API lower bounds, not a guarantee that every Octane feature works in those versions. An older Chromium engine can fail on a later hydration or cleanup path even when initial loading succeeded.
- These requirements and fallbacks describe current Octane. Releases 0.1.9–0.1.34 also used `Object.hasOwn()` in ordinary component capability checks; 0.1.35 removed that dependency and added browser scheduling, observer, media-query, and mobile-input compatibility fixes. Check the installed version and changelog before applying current guidance to an older release.
- Function form actions need `SubmitEvent.submitter` for button-level actions and submitted button data; Safari needs 15.4 for full support. Core `module server` RPC uses `fetch` and a serializer that requires `Object.hasOwn()` (Chrome/Edge 93, Firefox 92, Safari 15.4). Rich RPC values require their corresponding constructors in the receiving browser.
- Deferred hydration and behavior roots use `AbortController` and, for streamed-DOM observation, `MutationObserver`. Preserving custom abort reasons needs `AbortSignal.reason` (Chrome/Edge 98, Firefox 97, Safari 15.4). Native HTML features such as `inert` can need their own polyfills.
- View-transition animation and `Element.moveBefore()` are feature-detected. `idle()` falls back to a timer without `requestIdleCallback`; `visible()` activates immediately without `IntersectionObserver`; `media()` supports legacy media-query listeners. Browser-side Web Streams are not an unconditional hydration requirement: `ReadableStream` and `TextEncoder` are needed where `renderToReadableStream` executes, normally the server.
- The core package publishes modern ESM. Configure the consuming application's final syntax target and load missing API polyfills before the application. Rsbuild's `modules` target maps to Chrome 87, Edge 88, Firefox 78, Safari/iOS 14, and Samsung Internet 14; this does not certify RPC, form actions, or application dependencies on those browsers.

## Authoring TSRX

- A component is any function used at a `<F/>` site — not a special declaration. It renders whatever it returns: a JSX root, a primitive (coerced to text), `null`, or an array.
- `@{ … }` is shorthand for returning JSX — `function f() @{ … }` desugars to `function f() { … return <jsx> }` — so setup (hooks, locals) can sit next to the output. The `@{ … }` scope ends with exactly one output node (a JSX element or fragment `<>…</>`).
- Dynamic text holes use a cast: `{expr as string}`. The cast is optional when the expression is provably a string (a string/template literal, a `+`-concatenation involving a string, or a local tracked back to a string); required otherwise. A bare `{expr}` that isn't provably a string is a renderable hole.
- Template control flow uses directive blocks: `@if (c) { } @else { }`, `@for (const x of xs; key x.id) { } @empty { }`, `@switch (v) { @case (a) { } @default { } }`, and `@try { } @pending { } @catch (e) { }`. Plain JS control flow stays in setup.
- `.tsrx`'s `@for` compiles a rendered list to a keyed fast path (a compiled per-item body + the raw array) instead of allocating a descriptor per row — the main reason to prefer `.tsrx` for collection-heavy UI.
- A `<style>` block is a child of an element or a fragment and is scoped to its siblings, not to the `@{ … }` body around it: the block styles the items beside it and everything below them; it never styles the element that contains it. The compiler adds the block's hash to its selectors and adds the same hash class to the elements the block reaches, so the selectors match only there. To style an element, make the block and the element fragment siblings (`<><style>.card{…}</style><article class="card">…</article></>`); a block inside `<article>` styles the article's other children only. A `@{ … }` body or directive body holds exactly one output node and a block is an output node, so a block beside the output node is the multiple-outputs parser error and a lone block as the output is `STYLE_STANDALONE_NEEDS_FRAGMENT` — wrap both in a fragment, in `@if`/`@for` branches too. Every children list holding a block is a sibling scope with its own hash class; sibling blocks share one; nested scopes get their own; an element gets every enclosing hash class outer→inner, so outer rules reach nested scopes and inner rules never reach out. Blocks hold static CSS (runtime values go through custom properties); the only attributes are `ref` and `apply`; `:global(…)` reaches outside the scope (below).
- Raw CSS in `<style>` is TSRX template syntax: a standalone block is allowed only lexically inside a `@{ … }` body or an `@if`/`@for`/`@switch`/`@try` body, at any depth of elements, fragments, holes, callbacks, or templates assigned there. In a plain `return <…>` function or a module-scope element it is `STYLE_STANDALONE_OUTSIDE_TEMPLATE`. Plain TSX keeps the TSX rule: `<style>{css}</style>` is an ordinary element the compiler passes through untouched — no scope, hash, or injection.
- Assigning a block (`const theme = <style>…</style>`) yields a class map: `$class` (the block's hash, preceded by any applied themes' classes) plus one key per class selector whose value is `hash className`. Every assigned block is a theme and keeps every selector; elements carrying a class-map entry also match its element rules because the entry includes the hash. `$class` is a reserved key, and a bare standalone `<style>` statement at module scope is an error — assign it.
- `<style apply={theme} />` adds `theme.$class` to the items beside it and everything below them (never to the element that contains it); a `<style apply={theme}>…</style>` with CSS in it also declares that scope's block. `apply={[a, b]}` composes in order, a theme may apply another theme, and a theme must be declared before the block that applies it. A same-module theme becomes a string literal (the element's static HTML is still built once, up front); an imported theme is read at runtime through `theme.$class`. Final class list: authored classes, scope hashes outer→inner, applied theme classes.
- `apply` is the whole-scope form; to opt single elements into a theme, give them `class={theme.$class}` and leave `apply` out: only the elements carrying the class match the theme's element/descendant rules, siblings stay untouched, and a child component can take the class through a prop (`<Card parentClass={theme.$class} />`, then `<article class={parentClass}>`), where it lands before the child's own scope hash. `class={[a.$class, b.$class]}` is the per-element counterpart of `apply={[a, b]}`, and the two forms compose.
- `:global(…)` unscopes the wrapped part of a selector; the rest stays scoped, and it may sit only at the start or end (`.card :global(.x) .title` is `CSS_GLOBAL_PLACEMENT`). Bare `:global(.toast)` → `.toast`, a page-wide rule that matches anywhere like a global stylesheet; prefixed `.card :global(.note)` → `.card.<hash> .note`, only below your scoped `.card` (a child component's internals included), never upward; leading `:global(.theme-dark) .card` → `.theme-dark .card.<hash>`, your element under a page-level class; compound `.card:global(.is-open)` → `.card.<hash>.is-open`, your element with a class a library toggles. Block form: `:global { .toast { … } body { … } }` → `.toast { … } body { … }` (the wrapper is dropped, left as a comment; every rule inside is page-wide, the way to write several page-level rules at once, same advice as bare). Nested under a scoped rule, `.card { :global { .note { … } } }` → `.card.<hash> { .note { … } }`: the same reach as `.card :global(.note)` with the prefix written once, and the recommended way to style several classes of a child you cannot change; `.card { :global(.note) { … } }` gives the same output, while plain nesting `.card { .note { … } }` → `.card.<hash> { .note.<hash> { … } }` scopes both parts. Choose: own elements → a block beside them; a child you own → pass `theme.$class` or a class-map entry as a prop (visible dependency, the child picks the elements, a rename cannot silently break the parent, the hash keeps the rule on the carriers); a child you cannot change (third-party component, rendered HTML/markdown) → `.wrapper :global(.their-class)` with a scoped selector in front; page-level state → `:global(.theme-dark) .card` or `:global([data-theme='dark']) .card`; page-wide rules (`body`, resets, fonts) → a linked `.css` file, never a bare `:global`. Ranking: a scoped rule hashes only its first compound and adds `:where(.<hash>)` (no specificity) to the rest, so scoped `.note.<hash>` (0,2,0) and any `theme.$class`/class-map rule beat a bare `:global(.note)` (0,1,0), and prefixed `.card.<hash> .note` (0,3,0) beats the child's own `.note.<hash>`; at equal specificity the later sheet wins.
- A block inside an `@if`/`@for` branch styles only the elements that branch renders, but its CSS is always part of the module's stylesheet whichever branch renders, because CSS is static; only the hash class follows the branch, so rules wanted everywhere go outside the branch. CSS comes out in source order, outer scope first (an applied theme before the block that applies it, a scope's blocks together, nested scopes after their parent), and the compiled module carries one `injectStyle(hash, css)` call per scope — at module scope on the client (runs at module evaluation, deduped by hash, one `<style data-octane>` per sheet) and at the top of each component body on the server (a request collects only the sheets it rendered, returned as the `css` field). The CSS rides inside the compiled JavaScript; no bundler sees a virtual CSS module. `<style href precedence>` is a Float resource, not a scoped block. Style errors are compile errors carrying `STYLE_APPLY_VALUE`, `STYLE_APPLY_TARGET`, `STYLE_APPLY_BEFORE_DECLARATION`, `STYLE_APPLY_DUPLICATE`, `STYLE_APPLY_UNSUPPORTED_HOST`, `STYLE_RESERVED_CLASS_KEY`, `STYLE_STANDALONE_AT_MODULE_SCOPE`, `STYLE_STANDALONE_OUTSIDE_TEMPLATE`, `STYLE_STANDALONE_NEEDS_FRAGMENT`, `STYLE_UNKNOWN_ATTRIBUTE`, or `CSS_GLOBAL_PLACEMENT`.

## React interoperability

Both boundaries are named exports from `octane/react`:

- `ReactCompat` hosts one real React component inside Octane. Install matching `react` and `react-dom` versions, 19.2 or newer in the React 19 series. React owns the island's hooks, state, events, refs, and descendants; Octane owns the surrounding template.
- `OctaneCompat` hosts one compiled Octane component inside React 19: `<OctaneCompat><NativePanel /></OctaneCompat>`. The child stays an Octane component with native events and Octane hooks.

Prefer the child form for a React component in an Octane template:

```tsrx
// App.tsrx — compiled by Octane.
import { ReactCompat } from 'octane/react';
import { Counter } from './Counter.react';

export function App() @{
	<ReactCompat><Counter start={3} /></ReactCompat>
}
```

```tsx
/** @jsxImportSource react */
// Counter.react.tsx — compiled by React's JSX transform.
import { useState } from 'react';

export function Counter({ start }: { start: number }) {
	const [count, setCount] = useState(start);
	return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

Use both compilers in a mixed build, with `requireDirective: true` on the Octane integration. `.tsrx` belongs to Octane; mark Octane-owned `.tsx` and native hook/context helper modules with `/** @jsxImportSource octane */`. React-owned `.tsx` stays with React's JSX transform and `/** @jsxImportSource react */`. Do not alias React or React DOM to Octane. See [compiler setup](https://github.com/octanejs/octane/blob/main/docs/react-compat.md#compiler-ownership).

- `ReactCompat` also accepts `<ReactCompat component={Counter} props={{ start: 3 }} />`; do not combine that form with an element child. One function, class, `memo`, `lazy`, or `forwardRef` component is accepted. Put fragments, DOM elements, arrays, or multiple roots inside a React component. Props and refs retain their types at the child call site. React children passed through props must be React renderables, not Octane template blocks.
- Project native context into React explicitly: define `themeBridge = bridgeReactContext(OctaneTheme, ReactTheme)` once, then pass `contexts={[themeBridge]}` to `ReactCompat`. React descendants read `ReactTheme` with React's `use` or `useContext`. Keep source/target identities and their order stable, or replace the boundary key. This differs from `OctaneCompat`, where Octane's `use` or `useContext` can read a real React context directly; no reverse mapping is needed for that direction.
- `ReactCompat` creates one React root inside a `div`, so place it only where a div is valid. Prop updates preserve React state and nodes; changing the child key/type replaces the component, and changing the outer boundary key replaces the whole root. Prefer one useful React subtree over a boundary for every small widget.
- React work starts or updates after the Octane host commits. Octane `flushSync()` does not flush the separate React root, and an Octane transition is not a transaction shared with React. React-local transitions keep React's behavior. Authored React Suspense and error boundaries handle their own descendants first; escaped suspension and render/effect errors reach the nearest Octane pending/catch boundary. Event-handler errors follow React's normal reporting. During projected pending work, new parent props/context snapshots publish on reveal; delete the boundary or change its outer key to replace a pending island.
- Both server implementations use `octane/react/server`; Octane's server compiler retargets `octane/react` automatically. React-owned server entries that bypass that compiler must select the server entry explicitly. To produce complete React server HTML, `ReactCompat` needs an owned Octane asynchronous or streaming render request. It buffers each complete React island up to 8 MiB and hydrates it with React `hydrateRoot`. A surrounding Octane stream may send its fallback while waiting; React's own progressive reveal scripts are not streamed separately. A synchronous Octane render can emit an outer fallback but cannot await the React island. The request owns cancellation, abort, timeout, and cleanup. Nested React→OctaneCompat→ReactCompat server rendering is unsupported; client nesting works in both directions.

The [full ReactCompat reference](https://github.com/octanejs/octane/blob/main/docs/react-compat.md) documents visibility, cleanup, hydration, context, and update limits. The [playground](https://octanejs.dev/playground) includes **ReactCompat in Octane (multi-file)** and **OctaneCompat in React (multi-file)** examples. These adapters coordinate separate renderer commits; they do not provide atomic cross-root commits or universal compatibility with every React integration.

## Deferred hydration

`Hydrate` is an experimental core API for initial server-rendered content. It preserves visible server HTML while postponing component execution, refs, effects, and events. A boundary first mounted after the app is already running renders normally on the client.

Import the component from `octane` and strategies from `octane/hydration`:

```tsrx
import { Hydrate } from 'octane';
import { visible } from 'octane/hydration';

export function ProductPage() @{
	<Hydrate when={visible({ rootMargin: '400px' })}>
		<Reviews />
	</Hydrate>
}
```

Every boundary makes three performance decisions:

- `when` (required) controls when preserved server HTML becomes interactive. Available strategies are `load()`, `idle({ timeout? })`, `visible({ rootMargin?, threshold? })`, `media(query)`, `interaction({ events? })`, `condition(booleanOrGetter)`, and `never()`. `interaction()` replays the triggering event. A function form such as `when={() => window.matchMedia('(pointer: coarse)').matches ? interaction() : visible()}` may choose a strategy from client-only information; it is not called on the server and must return synchronously.
- `split` defaults to `true`. The compiler extracts direct children into a generated chunk, and Vite/Rsbuild do not eagerly module-preload that JavaScript. Use the literal `split={false}` when the code is already required elsewhere or a separate request is not worthwhile:

```tsrx
import { idle } from 'octane/hydration';

<Hydrate when={idle()} split={false}>
	<SmallBadge />
</Hydrate>
```

- `prefetch` starts the split chunk or custom preparation before `when` activates the boundary. Strategy prefetching accepts `load()`, `idle()`, `visible()`, `media()`, or `interaction()`; `condition()`, `never()`, and function-form strategies are activation-only. A strategy prefetch loads code but leaves the DOM inert:

```tsrx
import { idle, interaction } from 'octane/hydration';

<Hydrate when={interaction()} prefetch={idle()}>
	<RecommendationEditor />
</Hydrate>
```

A procedural prefetch can prepare code and data. Awaited work blocks activation if `when` resolves first; `signal` aborts when the boundary is removed:

```tsrx
<Hydrate
	when={visible()}
	prefetch={async ({ preload, signal }) => {
		await preload();
		await warmReviews({ signal });
	}}
>
	<Reviews />
</Hydrate>
```

The procedural context also exposes `waitFor(strategy)` for the same five prefetch strategies and the persistent boundary `element`. Procedural prefetch works with either split mode; strategy prefetch requires splitting.

The remaining public props are `fallback`, client-only loading UI for a later client mount or suspension, and `onHydrated`, called once after the child successfully commits on the client, including a client-only mount. Initial server HTML remains visible while its strategy or first activation suspension waits; `fallback` does not replace it. `children` is the server-rendered subtree. See the [Core APIs guide](https://octanejs.dev/docs/core-apis#deferred-hydration) and [complete deferred hydration reference](https://github.com/octanejs/octane/blob/main/docs/deferred-hydration.md).

## Behavior-only roots and external ownership

`<Hydrate split={false} when={never()}>` preserves externally managed server DOM without a wrapper, but its descendant client component graph is deliberately erased, so component event handlers inside that range never attach. Use `attachBehaviorRoot` to add separately owned behavior without creating a component root or claiming reconciliation ownership:

```ts
import { attachBehaviorRoot } from 'octane/behavior';
import { articleStream } from './article-stream.js';

const lifetime = new AbortController();
const owner = Symbol('article stream');
const root = attachBehaviorRoot(document.querySelector('#app')!, {
	signal: lifetime.signal,
});

root.registerExternalRange(document.querySelector('#article')!, {
	owner,
	ready: articleStream.allReady,
});

let activateAnnotation: (event: Event, element: Element) => void;
let observeAnnotation: (element: Element, signal: AbortSignal) => () => void;

root.registerBehavior({
	id: 'article-annotations',
	owner,
	target: '[data-annotation]',
	events: ['click'],
	ready: import('./annotations.js').then((module) => {
		activateAnnotation = module.activateAnnotation;
		observeAnnotation = module.observeAnnotation;
	}),
	adopt(element, { signal }) {
		return observeAnnotation(element, signal);
	},
	handleEvent(event, element) {
		activateAnnotation(event, element);
	},
});

await root.ready;
root.dispose(); // Abort behavior and preserve the existing DOM.
```

- Import the focused, renderer-free entry from `octane/behavior`, or import the same API and public types from `octane`. Behavior roots neither render nor hydrate; existing nodes, protected attributes, HTML/SVG/MathML namespaces, and independent streamed updates remain externally owned. Selector targets discover subsequently inserted matching elements.
- `registerExternalRange(element, { owner, ready?, signal?, replace? })` explicitly declares external ownership. The closest registered nested range wins. A second owner for the same element requires `replace: true`; an already-aborted replacement never evicts a live owner. Root and range identity are scoped to their document and container.
- `registerBehavior({ target, adopt, id?, owner?, events?, ready?, dependencies?, conflicts?, signal?, handleEvent? })` accepts a selector or element. `adopt(element, { signal, event?, range? })` may return synchronous or asynchronous cleanup; named dependencies must already exist and conflicts or duplicate IDs fail deterministically. Adoption waits for behavior, dependency, and matching range readiness.
- Delegated interactions are observed immediately, including before asynchronously loaded behavior or externally streamed ranges become ready. `handleEvent` receives the exact original same-document `Event` and its genuine `isTrusted` value; Octane never redispatches it, invents trusted events, repeats native link/form activation, or restores expired transient user activation. This direct delivery is distinct from `<Hydrate when={interaction()}>` hydration replay.
- `root.ready` snapshots active ranges and behaviors; each registration exposes its own `ready`, `signal`, and idempotent `dispose()`. Root cancellation aborts pending work, ignores stale async completions, disconnects listeners/observers, and runs adopted cleanup exactly once. `root.dispose()` preserves DOM by default; use `root.dispose({ preserveDOM: false })` only to explicitly clear descendants. Replacing a live root on the same container requires `attachBehaviorRoot(container, { replace: true })`.

See the [behavior-only roots guide](https://octanejs.dev/docs/core-apis#behavior-only-roots) and [complete external ownership reference](https://github.com/octanejs/octane/blob/main/docs/deferred-hydration.md#behavior-only-roots-and-external-ownership).

## Core state APIs

- `useState(initial)` returns `[state, setState, getState]`. `setState` accepts a value or functional update; `getState()` is stable and reads the latest scheduled hook-cell value without rendering. Omitting the third destructured member keeps the existing lean runtime path.
- `useReducer(reducer, initialArg, init?)` returns `[state, dispatch, getState]`. The third call argument remains the optional lazy initializer; the third tuple member is the current-state getter.
- `useLinkedState(source, calculate, options?)` returns `[value, setValue, getValue]`. `calculate(source, previous)` receives `undefined` initially and the previous `{ source, value }` when the source changes. `sourceEqual` and `valueEqual` default to `Object.is`; pass custom functions in `options` when needed. A source change updates the value during that same render without an effect, a render-time setter, or a replay.
- During pending work a state getter can be newer than the committed DOM. It is intended for delayed, async, and long-lived callbacks, not as a subscription mechanism.
- [`useLazyRef(factory)`](https://octanejs.dev/docs/core-apis#use-lazy-ref) creates a mutable ref whose initial value comes from `factory`, called when the ref's hook cell is created; later renders keep the same ref. `useRef(callback)` stores the function itself. The factory runs during render and may run again for retries, abandoned work, remounts, and separately for SSR and hydration; keep it free of side effects and use an effect for subscriptions or resources needing cleanup. Strong mode checks it like a lazy `useState` initializer: it may read a clock, randomness, or browser state, but may not schedule work. In Strong mode it replaces React's `if (ref.current === null) ref.current = create()` idiom, which reads and writes the ref during render. The experimental Valdi writer's existing adapter ABI does not support this hook.

## Layout snapshots

`useLayoutSnapshot(measure, options?)` returns `options.initial` on the first render, during SSR, and on the first hydration render; without an initial value it returns `undefined`. The initial value is mount-only. After the DOM and refs commit, and before paint, `measure` runs on each committed render of the component that reaches the hook. An unequal measurement updates the snapshot and can trigger another measurement. Equality defaults to `Object.is`; use `options.equal(previous, next)` to compare values such as freshly allocated objects. Without an initial value, `previous` may be `undefined`.

The callback is for synchronous measurements, not state writes or resource acquisition, and its result must converge. It runs in hook order with the component's other layout effects, so declare it after any `useLayoutEffect` that changes the DOM it measures. The hook does not subscribe to layout changes; for changes that happen independently of component commits, have an observer callback update state so the component commits and measures again. It is supported by the DOM renderer; the experimental universal and Valdi renderers do not support it. In Strong mode it replaces `useLayoutEffect(() => setWidth(el.current.offsetWidth))`, which Strong rejects as `OCTANE_STRONG_EFFECT_STATE_UPDATE`. See [Measure committed layout](https://octanejs.dev/docs/core-apis#use-layout-snapshot).

## ResizeObserver callbacks

Prefer [`createResizeObserver(callback, realmCtor?)`](https://octanejs.dev/docs/core-apis#createResizeObserver) from `octane` when resize callbacks set state, trigger layout updates, or write geometry. The callback receives native `ResizeObserverEntry` objects and the native observer in a separate task, coalescing the latest entry per target. Ordinary microtask batching remains unchanged. Keep required initial measurements synchronous:

```ts
import { createResizeObserver, useLayoutEffect } from 'octane';

// Inside a component with a panelRef and setWidth state setter.
useLayoutEffect(() => {
	const element = panelRef.current;
	if (!element) return;
	const measure = () => setWidth(element.getBoundingClientRect().width);
	measure();
	const observer = createResizeObserver(measure);
	observer.observe(element);
	return () => observer.disconnect();
});
```

Use the returned instance's `observe`, `unobserve`, and `disconnect` methods for lifecycle ownership. `unobserve(target)` removes that target's queued entries; `disconnect()` cancels queued delivery. The optional second argument is a `ResizeObserver` constructor from the observed element's realm, such as an iframe window.

`IntersectionObserver` already delivers callbacks in a separate task. Preserve native `MutationObserver` microtask ordering, narrow its observed subtree and mutation types, and guard callbacks that mutate what they observe; do not automatically wrap all observers.

Nonconvergent size feedback still needs a bounded layout algorithm. Observers owned by a dependency need a library adapter that uses the helper; creating another observer does not change their delivery.

## Signals

Signals are a stable API and work with the standard Octane compiler and its Vite, Rspack, and Rsbuild integrations. Every module consuming native signal reads needs its own runtime import from `octane/signals`, `octane/signals/client`, or `octane/signals/server`; a type-only import or `$` name alone is insufficient. No `nativeReads` option is required. Import `signal$`, `derived$`, `query$`, `skip`, `optimistic$`, and `action$` from `octane/signals`; import `useSignal$` from `octane/signals/client` for component-local state. Server compilation selects `octane/signals/server` for the local hook automatically.

`OCTANE_NATIVE_SIGNAL_IMPORT` reports a missing runtime import when the compiler can identify a native signal read during rendering from locally available signal types. Opaque cross-module or untyped values may escape the diagnostic; the import is still required for reactive reads. Use `import 'octane/signals';` when no named signals API is needed.

### Declarations, async derivations, and queries

`signal$(initial)` is writable; `derived$(compute)` is read-only and accepts an immediate value, Promise, async iterable, or Promise of an async iterable. Synchronous calculations remain immediate. Module declarations resolve to request-local cells on the server and document-local cells in the browser. Stable compiler-identified feature instances own their instance declarations. Browser modules need no renderer root; server reads/writes require a request owner. Unmounting one root does not dispose document-global state.

The compiler supplies declaration identities. Optional trailing `{ key }` options provide explicit identity: `signal$('', { key: 'draft' })`, `derived$(compute, { key: 'label' })`, and `query$(select, load, { key: 'user' })`. Uncompiled declarations require nonempty explicit keys. `signal$('draft')` stores a string, not a positional key. Function initial values are data; setters retain updater semantics, so `handler$.set(() => nextHandler)` stores a function.

```ts
// user-data.ts — compile with Octane.
import { derived$, query$, signal$, skip } from 'octane/signals';

export type User = { id: number; name: string; revision: number };
export const selectedId$ = signal$<number | null>(1);
export const user$ = query$<number, User>(
  () => selectedId$.get() ?? skip,
  async (id, { signal }) => {
    const response = await fetch(`/api/users/${id}`, { signal });
    if (!response.ok) throw new Error(`User request failed: ${response.status}`);
    return response.json() as Promise<User>;
  },
);
export const locale$ = signal$('en');
export const greeting$ = derived$(async ({ read, signal }) => {
  const user = await read(user$);
  const locale = await read(locale$); // Dependency tracked after await.
  const response = await fetch(`/api/greeting/${user.id}?locale=${encodeURIComponent(locale)}`, {
    signal,
  });
  if (!response.ok) throw new Error(`Greeting request failed: ${response.status}`);
  return response.text();
});
```

- `query$(select, load)` tracks its synchronous selector; the loader is untracked and starts only after selection succeeds. Canonically equal selected arguments deduplicate within the owner. `skip` means no request and an `idle` snapshot; `undefined` is a valid argument. Strict idle reads throw `SignalIdleError`.
- `user$.refetch()` retains a usable same-selection value with `refreshing: true`; `user$.reset()` makes strict reads pending. Loaders receive `{ signal, previous }`, with an optional prior ready value. Changed selection, refetch/reset, or disposal revokes obsolete publication even when cancellation is ignored.
- Async `derived$` uses its attempt-bound `read(handle$)` to await and track dependencies, including after `await`. Dependency changes abort the attempt and invalidate obsolete resolutions, errors, yields, and completion. The compiler supports proven async native reads; opaque helpers use explicit `read`. There is no ambient dependency context across arbitrary async code.
- For streams, use `query$(select, load, { kind: 'stream' })` or return an async iterable from `derived$` (no `kind` option needed there). Before first yield the source is pending/connecting; yields are ready/open; completion retains the last value with closed/complete. Completing without a yield is an error. Cancellation requests abort and iterator closure. Promises of iterables are unwrapped before publishing.

For example, given an application `watchNotifications(id, signal)` returning `AsyncIterable<Notification>`:

```ts
import { query$, skip } from 'octane/signals';
import { selectedId$ } from './user-data';
import { watchNotifications } from './api';

type Notification = { text: string };
export const notification$ = query$<number, Notification>(
  () => selectedId$.get() ?? skip,
  (id, { signal }) => watchNotifications(id, signal),
  { kind: 'stream' },
);
```

The component below needs its own `import 'octane/signals';` because importing a handle from `./user-data` does not enable native-read compilation. Handle idle separately, then use a pending/error boundary:

```tsrx
import 'octane/signals';
import { user$ } from './user-data';

export function UserCard() @{
  <section>
    @if (user$.snapshot().status === 'idle') {
      <p>Choose a user.</p>
    } @else {
      @try {
        <p>{user$.get().name as string}</p>
      } @pending {
        <p>Loading user…</p>
      } @catch (error) {
        <p role="alert">{String(error)}</p>
      }
    }
  </section>
}
```

### Local state and explicit scopes

```tsrx
import { useSignal$ } from 'octane/signals/client';

export function Counter() @{
  const count$ = useSignal$(0);
  <button onClick={() => count$.set((count) => count + 1)}>{String(count$.get())}</button>
}
```

Native reads during rendering subscribe the render scope. The compiler recognizes signal imports and `$` capability names, including handles passed through props and imported helpers. Name handles, properties, and helpers that return handles or expose live reads with a trailing `$`: `count$`, `props.user$`, `readCount$()`. Sampled values have ordinary names. Effects and event callbacks read imperatively and do not create render subscriptions.

`useSignal$(initial)` accepts a value or lazy initializer and returns a stable writable handle. Its compiler-assigned hook slot owns it; unmounting disposes it. Conditional hooks work; use keyed `@for` or a child component for loops. Local derived and async hooks are not available.

For manually managed shared state, create a scope at the data owner's lifetime boundary, pass handles through props/context, and dispose it when that owner ends:

```ts
import { createResource, createScope, query } from 'octane/signals';

const account = createScope({ scopeKey: 'account' });
const userId$ = account.signal$('user-id', 1);
const doubled$ = account.derived$('doubled', () => userId$.get() * 2);
const fetchUser = query('user', async (id: number, { signal }) => {
  const response = await fetch(`/api/users/${id}`, { signal });
  if (!response.ok) throw new Error(`User request failed: ${response.status}`);
  return response.json() as Promise<{ id: number; name: string }>;
});
const user$ = createResource(account, 'user', () => fetchUser(userId$.get()));
```

- `scope.signal$(key, initial)` creates writable state; `.set(value)` or `.set(updater)` uses `Object.is` equality. Replace objects/arrays; deep mutation is not tracked.
- `scope.derived$(key, compute)` tracks synchronous reads and requires a synchronous callback; use the declaration `derived$` for async computation. A computation may read another scope's handles without owning them.
- Keys are nonempty strings unique within a scope. Equal textual `scopeKey` values do not share live state. `scope.get(handle$)` and `scope.set(handle$, value)` require the handle to belong to that scope.
- Writes are immediately readable. `scope.batch(fn)` delays notifications until the outer synchronous batch ends. `scope.action(fn)` wraps a function with that batching rule and preserves `this`, arguments, and the result. Neither rolls back writes or batches across `await`. Writes during rendering, derived evaluation, updater callbacks, and historical adoption are rejected.
- `handle$.subscribe(notify)` returns an unsubscribe function and does not notify initially. `scope.dispose()` is idempotent, cancels requests/streams, and releases subscriptions and retained state. Escaped handles then throw `ScopeDisposedError`. Unmounting one consumer does not dispose an explicit shared scope.
- `createResource(scope, key, describe)` replaces the removed `scope.asyncSignal$` method and eagerly tracks the synchronous request-selection callback. The query loader is untracked, receives `{ signal: AbortSignal }`, and cannot publish obsolete results after selection changes, retry, or disposal. Equivalent query arguments share in-flight work within one scope; there is no idle cache of historical keys. Reusing a query key with an incompatible loader is rejected. Native `query$` declarations remain owner-optional, and query-free scopes do not retain producer implementation.
- `resource$.retry()` refreshes while preserving a usable current value; `retry({ pending: true })` makes strict reads suspend. A shared request retries for all its selectors. Data retry and UI error-boundary reset are separate operations.
- `query(key, loader, { kind: 'stream' })` accepts an async iterable or a promise of one. First yield changes pending/connecting to ready/open. Completion retains the last value and marks closed/complete; completion without a yield is an error. Cancellation requests abort and iterator closure.

Availability is explicit:

| Read | Contract |
| --- | --- |
| `handle$.get()` | Ready value, pending thenable, or thrown idle/source error. Handle idle explicitly; use `@try`/`@pending`/`@catch` or `Suspense`/`ErrorBoundary` for pending/error UI. |
| `handle$.latest(fallback)` | Whole last successful calculation, or fallback; omitted fallback means `undefined`. Never hides disposed owners or invalid adoption frames. |
| `handle$.snapshot()` | Immutable `idle`/`ready`/`pending`/`error` record; ready has `value`, error has `error`. Also includes `refreshing`, `connection`, `complete`, and optional `requestKey`. |
| `scope.isPending(read)` | Whether that expression suspends; ordinary errors still throw. A successful `latest(fallback)` is not pending even while a strict read would suspend. |

`undefined`, `null`, `false`, and empty strings are usable values. A retained result need not have appeared in committed UI. Keep its identity, values, and commands in the same derived result; do not combine an old user's retained card with a new user's delete command. Retained results remain valid only while their contributing owners are alive.

Inferred `useMemo(() => count$.get())` tracks native reads and preserves subscriptions across cache hits. Explicit arrays are never rewritten: `[count$]` sees only the stable handle. Sample during render (`const count = count$.get()`) and use `[count]` for explicit memos/effects. Known live reads hidden in a memo with fixed dependencies are diagnosed; `null` keeps its every-render meaning. Compile custom hooks through Octane as well.

### Optimistic actions and transitions

`optimistic$(source$)` layers operation-owned tentative state over a writable or query source. Write inside `action$`. This example uses the `User` query above and application-provided `updateUser` (returning a server-revisioned `User`) and `mayHaveReachedServer` (classifying ambiguous transport failures):

```ts
import { action$, optimistic$ } from 'octane/signals';
import { user$ } from './user-data';
import { mayHaveReachedServer, updateUser } from './api';

export const visibleUser$ = optimistic$(user$, {
  compareAuthority: (incoming, current) => incoming.revision - current.revision,
});
export const saveUser = action$('user.save', async (operation, name: string) => {
  const id = user$.get().id;
  visibleUser$.set((user) => ({ ...user, name }));
  try {
    const saved = await updateUser({ id, name, operationId: operation.id });
    operation.adopt(saved);
  } catch (error) {
    if (mayHaveReachedServer(error)) return operation.uncertain();
    throw error;
  }
});
```

Render `visibleUser$.get()` and invoke `saveUser(name)` from an event/form action, handling its result or error. The first write pins the owner and exact query selection generation. Late adoption cannot overwrite a different selection, including A→B→A. Definitive rejection removes only its own overlay. `compareAuthority` must be pure and finite; positive means newer, while zero/negative settles without replacing authority. Receipts for revisions 2 then 1 retain revision 2. This policy governs action receipts, not independently fetched/streamed updates.

The synchronous action prefix is batched. Opaque code after `await` uses `operation.set(visibleUser$, update)`, because ambient operation state is synchronous. `operation.uncertain()` retains the overlay and returns an uncertain receipt; an `OCTANE_RPC_UNCERTAIN` error becomes `ActionUncertainError`. `isActionUncertain` recognizes either form. No mutation retry, durable idempotency, or receipt storage is automatic. Retain the operation for reconciliation; after an authorized receipt lookup, call `adopt(value)` or `reject()`. Deferred handlers must receive inputs captured when the command occurred, not reread a newer draft.

Native setters inside an explicit renderer `startTransition`/`useTransition` Action stage a private candidate: committed reads, public subscriptions, and affected DOM bindings keep old values until presentation can accept the candidate. For example, in a client event handler: `startTransition(() => selectedId$.set(2))` (import from `octane`). Urgent edits stay live and superseded work cannot publish. This supports local writable/derived/query producers and local streams after first value; receiver-owned server streams and historical adoption frames currently reject transition participation. `scope.action` alone only batches synchronous writes.

### SSR, streamed results, and early controls

Module declarations use the server request owner; explicit scopes must be created per request. Match scope/signal identities between server and client. Distinct owners in one presented graph need distinct scope keys. Native completed reads serialize ready values, retained `latest` values, and ready snapshots. Hydration adopts historical values without rewinding live state. A matching completed resource seed avoids a duplicate client load; an incomplete ready resource in seed-only transport starts a quiet client attempt. Server-local `useSignal$` state lasts one render pass and is not shared-state seed data.

`scope.serialize()` returns a `ScopeSeed`. For explicit embedding, `scope.beginAdoption(seed)` returns a frame with synchronous `run(read)`, `retain()` for another lease, and `release()` for cleanup. Query arguments and serialized values accept undefined, null, booleans, finite numbers, strings, dense arrays, and acyclic plain objects with enumerable string data properties. Arguments are copied/frozen and object keys canonicalized. Cycles, sparse arrays, accessors, symbols, custom prototypes, and nonfinite numbers are rejected.

Ready-state seeds do not transport pending producers or error objects. Completed server output directly sampling a pending/error snapshot or displaying an `isPending` result is unsupported by ready-state transport and diagnosed; use a boundary or a serializable `latest` projection. Pending/catch arms without seedable data render fresh within their owned hydration range.

Streamed-result delivery is a separate channel: accepted results may arrive before the query module loads. Matching document/instance/selection/attempt identities attach to the later query without a duplicate browser request; changed selections or retired owners reject obsolete channels. For custom hosts, bootstrap before importing modules that read document signals:

```ts
import { bindSignalControl } from 'octane/signals';
import {
  bootstrapStreamedSignalResults,
  type NativeSignalManifest,
} from 'octane/hydration/streamed-signals';

export async function attachEditor(bootstrap: {
  buildId: string;
  documentId: string;
  initialSignals: NativeSignalManifest;
}) {
  const page = bootstrapStreamedSignalResults(bootstrap);
  try {
    const { draft$ } = await import('./draft-state');
    const textarea = document.querySelector<HTMLTextAreaElement>('#draft')!;
    const stop = bindSignalControl(textarea, 'value', draft$);
    return {
      signalOwner: page.signalOwner,
      releaseControl: stop, // Before transferring this node to an island.
      dispose() { // Only when the document owner ends.
        stop();
        page.dispose();
      },
    };
  } catch (error) {
    page.dispose();
    throw error;
  }
}
```

The host supplies matching build/document identities and the initial response's native manifest, installs it once before live reads, and uses the same bundled signal engine for early/later consumers. Early edits win; late/duplicate initial installation throws. Server hosts emit `earlySignalBootstrapScript({ nonce })` from `octane/server` before controls/results and use `earlySignalBootstrap: 'external'` on fragment renderers. Capture itself needs no module; live derivations need the signal engine. Keep cached HTML and client/server compiler output from matching builds.

`bootstrapStreamedSignalResults` accepts results without DOM placement. Choose `bootstrapStreamedSignalHydration` instead when using `receiver.registerRegion` to place streamed HTML; use one bootstrap per document. Later roots join the returned `signalOwner`; custom owners require explicit `runWithSignalOwner` around behavior callbacks. `bindSignalControl` projects `value` on text inputs/textareas/selects or `checked` on checkboxes/radios; writable handles adopt captured edits and receive native writeback, while readonly handles only project (without setting HTML `readOnly`). It creates no renderer root and does not reconcile or replace nodes. In the example, `./draft-state` exports a compiled `signal$('')`. Call `releaseControl()` before replacing the node or handing it to an island; call `dispose()` only when the document owner ends. See the [integration reference](https://github.com/octanejs/octane/blob/main/docs/deferred-hydration.md#compiled-presentation-on-existing-dom) for compiled bindings and lifecycle details.

Native rendering supports DOM client/server. Deep stores, local derived/async hooks, cross-root atomic reveal, and native reads in non-DOM renderers remain outside the API. Declaration `derived$` supports async callbacks; explicit `scope.derived$` does not.

`scope.inspect()` reports metadata without evaluating dormant computations or exposing values/callbacks. `createScope({ scopeKey, debug: { traceLimit: 256 } })` enables bounded tracing; profiling builds expose native reads in DevTools. Public errors include `ScopeDisposedError`, `SignalCycleError`, `SignalFrameError`, `SignalIdleError`, `SignalSerializationError`, `SignalStreamError`, `SignalWriteError`, and `ActionUncertainError`. The separate `@octanejs/alien-signals` binding keeps its existing API. See the [guide](https://octanejs.dev/docs/signals) and [full reference](https://github.com/octanejs/octane/blob/main/docs/signals.md).

## Strong mode

Strong mode is an opt-in compiler contract. A Strong module asserts that rendering reads immutable snapshots (props, state, context) and is pure: the same inputs produce the same output, with no state updates, scheduled work, clock or random reads, or `ref.current` access during render. The compiler rejects the violations it can prove with `OCTANE_STRONG_*` compile errors, and it owns memoization and dependency inference. Compatibility mode, the default, keeps React semantics, including `useMemo`, `useCallback`, and explicit dependency arrays.

Enable it per module with `"use strong"` before the imports; comments, other directives, and a leading `@jsxImportSource` pragma may precede it, and a directive anywhere else reports `OCTANE_STRONG_DIRECTIVE_PLACEMENT`. Or set `compiler: { strong: true }` in `octane.config.ts` for all application-owned modules. Vite, Rspack, and Rsbuild also accept `strong: true` as a plugin option; it wins over the config file, standalone Rspack needs it, and `octane analyze` cannot see it, so prefer the config file. Installed dependencies keep their own mode unless their source opts in. Strong compiles `.tsrx`, `.ts`, and `.js` only: a `.tsx` or `.jsx` module it reaches reports `OCTANE_STRONG_TSX_MODULE`, so convert it to `.tsrx`. Strong `.tsrx` selects the branded `trustHTML` JSX types automatically.

In a Strong module:

- `useMemo` and `useCallback` may control their own dependencies. Explicit lists are preserved, omitted lists are inferred, and `null` recomputes on every render. The compiler also caches eligible plain `const` calculations and callbacks automatically.
- Omit dependency arrays. An explicit array that differs from the inferred inputs, or cannot be proven equivalent, is an error; an equivalent array is a hint that never fails a build (`OCTANE_STRONG_EXPLICIT_DEPENDENCIES`). `null` dependencies are an error (`OCTANE_STRONG_UNTRACKED_EFFECT`).
- Render never reads or writes `ref.current` (`OCTANE_STRONG_RENDER_REF_READ`, `OCTANE_STRONG_RENDER_REF_WRITE`). Create a value once with `useLazyRef(() => create())` instead of `if (ref.current === null) ref.current = create()`.
- Effect setup never updates state synchronously (`OCTANE_STRONG_EFFECT_STATE_UPDATE`). Render a DOM measurement from `useLayoutSnapshot(measure, { initial })` instead of setting state in a layout effect, and use `useLinkedState` when state follows a prop.
- Event handlers update state as usual. Effects synchronize external systems and release what they acquire in cleanup. Read the latest props from an effect with `useEffectEvent`.
- Effect setup may read or write a ref's `current` and call a state getter; neither subscribes to changes. Read the state snapshot when the effect should re-run as state changes. Reading a reassigned module `let` or `var` in setup still reports `OCTANE_STRONG_EFFECT_HIDDEN_DEPENDENCY`.
- Resource cleanup analysis follows same-module helpers and `useEffectEvent` callbacks called during setup with that call's arguments. Return their disposer from the effect: `useLayoutEffect(() => start())` returns the cleanup, while `useLayoutEffect(() => { start(); })` discards it. Imported helpers remain opaque, including resources acquired internally and cleanup they return. See the [resource cleanup reference](https://github.com/octanejs/octane/blob/main/docs/strong-compiler-checks.md#effect-cleanup) for proof limits.

Adoption workflow for an existing app:

1. `octane analyze --strong-preview` reports what Strong would report for modules that are not Strong yet, grouped by code; those findings do not fail the run.
2. `octane analyze --strong-preview --fix` applies the compiler's mechanical rewrites: the lazy-ref idiom becomes `useLazyRef`, and `useMemo`/`useCallback` become plain declarations. Without `--strong-preview`, `--fix` rewrites only modules that are already Strong; `--dry-run` lists the fixes without writing them.
3. Add `"use strong"` module by module and fix each finding with the recipes below. `octane analyze` reports every Strong finding in a file, each Strong compile error ends with a link to its docs entry, and `octane explain <CODE>` prints that entry. The `@octanejs/mcp-server` MCP server has an `octane_strong_explain` tool and a `migrate-to-strong` skill. `collectDiagnostics(source, filename, { strong: true })` from `octane/compiler` returns every diagnostic for one module instead of throwing the first.
4. `octane analyze --strong-baseline init` writes `octane-strong-baseline.json` with every module that is not Strong yet. While it exists, `octane analyze` fails when a module leaves Strong mode or a new module is not Strong (`OCTANE_STRONG_COVERAGE_REGRESSION`); `octane analyze --strong-baseline update` removes converted names and never adds one.
5. When every application module is Strong, set `compiler: { strong: true }`.

<!-- strong-diagnostics:llms:start (generated by `pnpm strong:diagnostics` from packages/octane/src/compiler/strong-diagnostics.js) -->

Migration recipes, React idiom → Strong replacement:

- Create a value once: `if (ref.current === null) ref.current = new Store();` → `const ref = useLazyRef(() => new Store());`
- Render from a DOM measurement: `useLayoutEffect(() => setWidth(el.current.offsetWidth));` → `const width = useLayoutSnapshot(() => el.current?.offsetWidth ?? 0, { initial: 0 });`
- Measure an element from a callback ref: `<span ref={(el) => { if (el) setWidth(el.offsetWidth); }}>` → `const width = useLayoutSnapshot(() => el.current?.offsetWidth ?? 0, { initial: 0 });`
- Read the latest props from an effect: `const latest = useRef(onTick); latest.current = onTick;` → `const tick = useEffectEvent(onTick);`
- Keep editable state in sync with a prop: `useEffect(() => setName(user.name), [user.name]);` → `const [name, setName] = useLinkedState(user.id, () => user.name);`
- Render live browser state: `const wide = window.innerWidth > 800;` → `const wide = useSyncExternalStore(subscribe, getWide, () => false);`
- Generate an element ID: `const id = 'field-' + Math.random();` → `const id = useId();`
- Load data in an effect: `useEffect(() => { load(id).then(setData); }, [id]);` → `let ignore = false; load(id).then((p) => { if (!ignore) setName(p.name); }); return () => { ignore = true; };`
- Re-render when an external store changes: `const [, forceUpdate] = useReducer((x) => x + 1, 0);` → `const value = useSyncExternalStore(store.subscribe, store.get, store.get);`
- Render trusted HTML: `dangerouslySetInnerHTML={{ __html: html }}` → `dangerouslySetInnerHTML={trustHTML(sanitize(html))}`

Every Strong diagnostic and its replacement:

Effects, state, and dependencies:

- `OCTANE_STRONG_EFFECT_STATE_UPDATE`: Derive the value during render, or use `useLinkedState` when state follows another value. When the effect copies a measurement of the committed DOM into state, render from `useLayoutSnapshot` instead. `requestAnimationFrame`, timers with a positive delay, and external subscription callbacks remain event-driven.
- `OCTANE_STRONG_REF_STATE_UPDATE`: Pass a ref object to keep the element, and read it from effects and event handlers. When the callback copies a measurement of the element into state, render from `useLayoutSnapshot` instead. `requestAnimationFrame`, timers with a positive delay, and observer or listener callbacks the ref attaches remain event-driven.
- `OCTANE_STRONG_EFFECT_DATA_FETCH`: Read asynchronous render data with `use()` or a query binding. For external synchronization, abort an `AbortController` whose `signal` is passed to the request, or set a flag declared in the effect from its cleanup and check it before the update.
- `OCTANE_STRONG_EFFECT_HIDDEN_DEPENDENCY`: Keep the value in state, a prop, or context and read its snapshot, or move the non-reactive read into a `useEffectEvent` callback. Octane never double-invokes effects, so `didInit` guards are unnecessary.
- `OCTANE_STRONG_EFFECT_RESOURCE_LEAK`: Release it in the returned cleanup. Acquire resources for a snapshot in a separate effect.
- `OCTANE_STRONG_LAYOUT_SNAPSHOT_ASYNC`: Return the measurement synchronously, and read asynchronous render data with `use()` or a query binding.
- `OCTANE_STRONG_EFFECT_CHAIN`: Derive the value during render, use `useLinkedState`, or combine the external synchronization in one effect. External subscription and timer callbacks remain event-driven updates.
- `OCTANE_STRONG_UNLINKED_PROP_STATE`: Use `useLinkedState(source, reconcile)` for state that follows a source. Use `useState(() => initialValue)` or an explicit third `useReducer` initializer for a deliberate initial capture.
- `OCTANE_STRONG_EXPLICIT_DEPENDENCIES`: Omit the dependency argument.
- `OCTANE_STRONG_UNTRACKED_EFFECT`: Omit the argument so the compiler tracks reactive inputs. Declare and finish assigning what the hook reads before calling it, or keep a changing value in state or a ref.
- `OCTANE_STRONG_EFFECT_EVENT_DEPENDENCY`: Remove it. Effect Events are non-reactive, so they never belong in dependencies.
- `OCTANE_STRONG_AUTOMATIC_MEMO_UNSUPPORTED`: Compile the module through the normal Octane integration, or keep it in compatibility mode.

State values, updaters, and subscriptions:

- `OCTANE_STRONG_IMPURE_UPDATER`: Do the side effect or nondeterministic read in the event handler, effect, or Action, and pass its result in: `const now = Date.now(); setValue((current) => current + now)`.
- `OCTANE_STRONG_SNAPSHOT_MUTATION`: Pass a new value, for example `setItems([...items, item])` or `setItems((current) => [...current, item])`. Keep mutable objects in `useRef`, or create one with `useLazyRef`.
- `OCTANE_STRONG_STALE_STATE_UPDATE`: Use the updater form, `setValue((current) => current + 1)`, compute from the state a reducer receives, or read the latest value with the state getter (the third tuple member).
- `OCTANE_STRONG_WRITE_ONLY_STATE`: Subscribe with `useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)` and render its snapshot, or remove the unused state.
- `OCTANE_STRONG_UNCACHED_STORE_SNAPSHOT`: Return a value the store keeps, such as its current state object, or read each field with its own `useSyncExternalStore` call.

Render snapshots and determinism:

- `OCTANE_STRONG_RENDER_STATE_UPDATE`: Update state in an event handler, or use `useLinkedState` when state needs to reset or change with another value.
- `OCTANE_STRONG_RENDER_STATE_GETTER_CALL`: Render from the first tuple member. Call the getter in an event, effect, or deferred callback for the latest scheduled state.
- `OCTANE_STRONG_RENDER_REF_READ`: Read the ref in an event or effect, or render from state or `useLinkedState`. Create a value once with `useLazyRef(() => value)`, and render from a DOM measurement with `useLayoutSnapshot`. Pass the ref itself to a `ref` prop as usual.
- `OCTANE_STRONG_RENDER_REF_WRITE`: Create a value once with `useLazyRef(() => create())`. Read the latest props or state from an effect with `useEffectEvent`. Otherwise move the write to an event or effect, or express the value as state. `octane analyze --fix` rewrites the lazy initialization idiom.
- `OCTANE_STRONG_RENDER_MODULE_STATE_READ`: Move the changing value into state or context, or pass an immutable snapshot as a prop.
- `OCTANE_STRONG_RENDER_AMBIENT_READ`: Subscribe with `useSyncExternalStore` and a server snapshot for live browser state. Read a one-time value in an effect or a lazy `useState` initializer; lazy initializers also run during server rendering, so guard browser APIs there and keep server and client output the same.
- `OCTANE_STRONG_RENDER_SNAPSHOT_MUTATION`: Derive a local copy, or pass a new value to the state updater from an event.
- `OCTANE_STRONG_RETAINED_ROW_MUTATION`: Build mutable data before the `@for`, or derive each row only from its item. Fresh setup-local and row-local scratch data remain valid.
- `OCTANE_STRONG_RENDER_IMPURE_CALL`: Read time or randomness in an event handler or effect and store the result in state, or pass it in as a prop. Use `useId()` for element IDs. Give each list item a stable ID from its data, such as `item.id`.
- `OCTANE_STRONG_RENDER_LOCALE_FORMAT`: Pass an explicit locale and time zone, for example `toLocaleString('en-US', { timeZone: 'UTC' })` or `new Intl.DateTimeFormat(locale, { timeZone })`. Otherwise format in an event or effect and render the stored text.
- `OCTANE_STRONG_RENDER_SIDE_EFFECT`: Schedule the work from an event handler, or from an effect that cancels it in cleanup. Defining a callback that schedules later stays valid; calling it during render does not.
- `OCTANE_STRONG_RENDER_EFFECT_EVENT_CALL`: Call it from an effect, or from a later event or subscription callback.

Lists, templates, and compatibility APIs:

- `OCTANE_STRONG_MAP_JSX`: Use `@for` with a stable item key. Data-only mapping remains valid.
- `OCTANE_STRONG_INDEX_KEY`: Use an item ID that survives insertion, removal, and reordering. Looking up an item ID, such as `items[index].id`, remains valid.
- `OCTANE_STRONG_SINGLE_ITEM_FOR`: To remount a subtree when a value changes, wrap it in `<Fragment key={value}>…</Fragment>` or put `key` on its only element or component. To render one value, render it directly. Literals with two or more items and spreads stay valid.
- `OCTANE_STRONG_HOOK_LOCALITY`: Move the hook into that block, before the JSX or local effect that uses its value. Hooks used only by conditional, keyed, switch, or try arms may stay in the parent scope to keep that lifetime.
- `OCTANE_STRONG_EVENT_HANDLER_LOCALITY`: Move the handler into that block, before the JSX that uses it, or inline it.
- `OCTANE_STRONG_DIRECTIVE_PLACEMENT`: Move `"use strong"` to the top of the file, before imports or other code.
- `OCTANE_STRONG_TSX_MODULE`: Rename the module to `.tsrx` and write its markup as template JSX, with `@if`, `@for`, `@switch`, and `@try` blocks for control flow. A module without JSX can be `.ts` or `.js`; `root.render(App, props)` renders an entry point without JSX.
- `OCTANE_STRONG_SUPPRESSION_PROP`: Fix the mismatch or use the intended native event. Component props with these names are unaffected.
- `OCTANE_NATIVE_TEXT_ONCHANGE`: Use `onInput` for per-edit changes. Native checkbox, radio, and select `onChange` semantics stay valid.
- `OCTANE_STRONG_COMPAT_IMPORT`: Use normal Octane scheduling and component semantics.
- `OCTANE_STRONG_ELEMENT_API`: Write template JSX, pass the component itself (`icon={Plus}`), or pass a `() => @{ … }` render function. Type-only imports such as `ElementDescriptor` stay valid.

DOM ownership and trusted HTML:

- `OCTANE_STRONG_MANAGED_DOM_WRITE`: Render the value from state or props in the template.
- `OCTANE_STRONG_RAW_HTML_WRITE`: Use `dangerouslySetInnerHTML={trustHTML(html)}` for trusted or already sanitized HTML.
- `OCTANE_STRONG_OWN_MARKUP_QUERY`: Attach a ref to the element and use `ref.current` in the event or effect.
- `OCTANE_STRONG_UNTRUSTED_HTML`: Pass `trustHTML(html)` after applying the application's sanitization policy. `trustHTML` marks trust and does not sanitize.

Coverage:

- `OCTANE_STRONG_COVERAGE_REGRESSION`: Add `"use strong"` before its imports, or enable `compiler.strong`, and fix what Strong then reports.
- `OCTANE_STRONG_COVERAGE_STALE`: Run `octane analyze --strong-baseline update`.

Each code is documented at https://octanejs.dev/docs/strong-mode#<code-in-kebab-case>.

<!-- strong-diagnostics:llms:end -->

`"use strong"` is also an author assertion that rendering is referentially transparent. Production client builds memoize every user-authored render operation on that assumption, including local, imported, member, computed, and call-produced callees, callback-bearing calls, construction, and tagged templates. A `use*` name is not a purity oracle and does not reintroduce Rules of Hooks; actual hooks stay in component or custom-hook setup. The analysis is deliberately bounded: it follows local aliases, helpers, and known callbacks, and an unknown call is assumed pure instead of disabling Strong memoization. A call that hides ref contents, a state getter, mutable module or global data, a live external store, a clock, randomness, or mutation violates the contract; keep live accessors in compatibility mode, or pass an actual snapshot into a separate Strong component. Do not rely on render evaluation counts: production, development, HMR, profiling, server rendering, hydration, retries, and aborted work can evaluate different amounts of code.

See the [Strong mode guide](https://octanejs.dev/docs/strong-mode).

## Dependency-taking hooks

- `useEffect`, `useLayoutEffect`, and `useInsertionEffect` infer dependencies from the setup closure when the second argument is omitted.
- `useMemo` and `useCallback` infer dependencies from the create/callback closure when the second argument is omitted.
- `useImperativeHandle` infers dependencies from its handle factory when the third argument is omitted; ref identity is still tracked separately.
- An explicit array is authoritative. `[]` retains mount/reconnect-only or stable-value behavior, `[a, b]` tracks exactly those values, and `null` opts into every-render/recompute behavior.
- In production compiles, eligible `useMemo`/`useCallback` declarations become inline caches (no per-render closure or deps-array allocation). This is transparent — identical semantics, including `Object.is` dependency compares.
- These rules also apply to `useMemo` and `useCallback` in Strong mode. Strong effects reject `null` dependencies and explicit arrays that differ from the inferred inputs; see Strong mode above.

## Async data with use()

- Creating promises during render is the SUPPORTED pattern — do not add React's `cache()` or hoist fetches into effects/state to avoid re-creation. The compiler memoizes every creation feeding a `use()` at its declaration, keyed on its inputs.
- Local promise chains are included: `const p = fetchUser(id); const t = p.then((u) => u.thumbnail()); use(t)` fetches once, survives re-renders and suspense replays, and refetches exactly when `id` changes (the derived link keys on `p`'s identity).
- Independent `use()` reads start in parallel and suspend once per stratum; true data dependencies stay sequential. Descendant fetch trees prefetch (`__warm`) while an ancestor is still suspended. Do not restructure code into React-style manual promise hoisting to "fix" waterfalls — the compiler already eliminates the avoidable ones.

## Ecosystem and bindings

Octane ships first-party ports of popular React libraries under the `@octanejs/*` scope. **For a native Octane equivalent of a well-known React library, point to the matching binding below first.** To keep an existing component on real React, or use a React library without porting it, use `ReactCompat` with that library's real React dependencies. Some native bindings adapt a framework-neutral core; component-heavy packages port a broader React-facing surface. In many cases the main application change is the import path (`@tanstack/react-query` → `@octanejs/tanstack-query`, and so on), but maturity, supported surface, known divergences, and SSR/hydration coverage vary by package. Check the generated [bindings status table](https://github.com/octanejs/octane/blob/main/docs/bindings-status.md) before relying on a specific native API.

Core packages:

- `octane` — the runtime and the `.tsrx`/`.tsx` compiler together (the only framework/runtime package every app needs; install the matching build integration separately).
- `octane/react` — `ReactCompat` (real React inside Octane), `OctaneCompat` (compiled Octane inside React), and `bridgeReactContext` (native context to React). Server implementations are in `octane/react/server`.
- `octane/compiler/vite` — the underlying low-level Vite compiler adapter used by `@octanejs/vite-plugin`; reserve it for unusual custom tooling.
- `@octanejs/rspack-plugin` — the low-level Rspack 2.x compiler integration: client/server runtime selection, source maps, dependency watching, cache metadata, and Rspack HMR.
- `@octanejs/app-core` — the bundler-neutral config, routing, SSR/hydration code generation, and production request-handler core shared by app integrations.
- `@octanejs/vite-plugin` — the recommended Vite integration for SPAs and full apps: compilation by default, plus routing, streaming dev SSR, hydration wiring, and production client/server builds when configured.
- `@octanejs/rsbuild-plugin` — the equivalent full app integration for Rsbuild 2.x, built on `@octanejs/rspack-plugin`. It is shaped as an Rsbuild plugin for future Rspeedy reuse, but the current renderer target is DOM rather than Lynx.
- `@octanejs/adapter-vercel` — deploys a full-app production build to Vercel.
- `@octanejs/adapter-cloudflare` — deploys a full-app production build to Cloudflare Workers with Workers Static Assets.

Rspack usage: install `octane`, `@rspack/core`, and `@octanejs/rspack-plugin`, then add `new OctaneRspackPlugin()` to the Rspack plugins array. Rsbuild full-app usage: install `octane`, `@rsbuild/core`, and `@octanejs/rsbuild-plugin`, then add `pluginOctane()` to `rsbuild.config.ts`; add declarative `RenderRoute`/`ServerRoute` entries in `octane.config.ts` for routing, SSR, hydration, RPC, production builds, and preview.

Mixed toolchains: by default Octane owns every project `.tsrx`/`.tsx` module. In a codebase where another framework's toolchain also compiles `.tsx` (including either `ReactCompat` or `OctaneCompat` from `octane/react`), pass `requireDirective: true` to the Vite, Rspack, or Rsbuild integration. The rule is two lines: a project `.tsrx` is Octane's by extension (no marker needed — nothing else compiles the syntax); a project `.tsx`/`.ts`/`.js` is Octane's only when it opens with a leading `/** @jsxImportSource octane */` pragma comment — full compilation for `.tsx`, octane hook slotting for `.ts`/`.js` (the shape for custom octane hooks shared across islands). In a `.tsx` the pragma is the same comment TypeScript reads for per-file JSX typing, so one marker both types the file and routes it; in a JSX-less `.ts`/`.js` module TypeScript ignores it, so there it acts purely as the Octane ownership marker. A pragma naming a registered renderer's intrinsics module (e.g. `@octanejs/three/intrinsics`) claims the file the same way; a pragma pointing at a foreign source (`react`, `@emotion/react`, …) claims nothing, and unmarked project modules pass through to the host framework's own pipeline (with a warning when they import from `octane` — usually a forgotten pragma). A project routing some `.tsrx` through another tsrx compiler (such as `@tsrx/react`) lists those paths in the integration's `exclude` option — excluded paths are never Octane's; installed packages keep their package-manifest decision (hook slotting included) so bindings need no pragmas.

Profiling usage: pass `profile: true` to `octane()` for Vite, `new OctaneRspackPlugin()` for Rspack, or `pluginOctane()` for Rsbuild. When using `@octanejs/mdx`, pass the same value to `octaneMdx()`. Profiling is client-only and independent of HMR/dev metadata. Profile builds add bounded component events, schedule-to-render delay, and Chrome custom tracks; normal builds omit compiler metadata and specialize the runtime with profiling disabled. Use `globalThis.__OCTANE_PROFILER__` in DevTools, or import `profiler` from `octane/profiling` in profiling-only application tooling, for summaries, recent render causes, raw events, and Chrome Trace Event export. An explicit `octane/profiling` import keeps the recorder module in that build even when `profile` is false. Octane's duration is component render plus synchronous DOM work; inclusive time contains descendants and self time subtracts nested component spans. Raw props/state/actions/DOM values and absolute paths are not retained by default.

Engine counters: `profiler.counters()` returns session totals (shorthand for `profiler.snapshot().counters`). To measure an interaction, take `const before = profiler.snapshot()`, perform the interaction and wait for it to finish, then inspect `profiler.diff(before, profiler.snapshot()).counters`. Counters cover component attempts and outcomes, bailouts, Blocks created/unmounted, directive arms kept/swapped, boundary fallbacks/catches, scheduler drains, root commits, and rollback work. They count attempted work, including work later rolled back, and survive event-buffer eviction; `clear()` resets them. Unsupported counters are absent rather than zero. `diff()` rejects incompatible schemas, builds, or renderer sets, snapshots taken with recording off or across `stop()`/`clear()`, and reversed snapshot order.

Profile builds disable compiler optimizations reserved for production, so counter totals describe the generic program: compare two profile builds of the same app, not a profile build against optimized production output. Timings include instrumentation overhead. Without an explicit `octane/profiling` import, optimized non-profile bundles remove the recorder, counters, clock reads, and profiling allocations; Vite dev also removes the disabled branches and recorder. Other unminified development output can retain dead branches, but they never run. See the [profiling guide](https://octanejs.dev/docs/profiling).

Bindings — reach for these when asked about the React equivalent:

- **Shared state** — `@octanejs/alien-signals`, `@octanejs/zustand`, `@octanejs/valtio`, `@octanejs/jotai`, `@octanejs/mobx`, `@octanejs/rxjs`, `@octanejs/redux`, `@octanejs/redux-toolkit`, `@octanejs/tanstack-store`, `@octanejs/xstate`, and `@octanejs/xstate-store`.
- **AI, data, and routing** — `@octanejs/tanstack-ai`, `@octanejs/apollo-client`, `@octanejs/livestore`, `@octanejs/dexie`, `@octanejs/swr`, `@octanejs/tanstack-query`, `@octanejs/tanstack-query-devtools`, `@octanejs/tanstack-db`, `@octanejs/tanstack-router`, `@octanejs/tanstack-router-ssr-query`, `@octanejs/remix-router`, `@octanejs/inertia`, `@octanejs/nuqs`, `@octanejs/better-auth`, and `@octanejs/wouter`.
- **Web3** — `@octanejs/wagmi`, `@octanejs/rainbowkit`, and `@octanejs/solana-kit`.
- **UI and interaction** — `@octanejs/radix`, `@octanejs/zag`, `@octanejs/vaul`, `@octanejs/base-ui`, `@octanejs/base-ui-utils`, `@octanejs/aria`, `@octanejs/mantine-hooks`, `@octanejs/embla-carousel`, `@octanejs/floating-ui`, `@octanejs/animejs`, `@octanejs/gsap`, `@octanejs/popper`, `@octanejs/motion`, `@octanejs/spring`, `@octanejs/dnd-kit`, `@octanejs/sonner`, `@octanejs/draggable`, `@octanejs/resizable-panels`, `@octanejs/select`, `@octanejs/react-error-boundary`, `@octanejs/transition-group`, `@octanejs/day-picker`, `@octanejs/textarea-autosize`, `@octanejs/colorful`, `@octanejs/cmdk`, `@octanejs/shadcn`, `@octanejs/lucide`, `@octanejs/phosphor-icons`, `@octanejs/usehooks-ts`, `@octanejs/intersection-observer`, `@tanstack/octane-hotkeys`, `@tanstack/octane-pacer`, `@octanejs/stick-to-bottom`, `@octanejs/image-crop`, `@octanejs/content-loader`, `@octanejs/to-print`, `@octanejs/calendar`, `@octanejs/auto-animate`, `@octanejs/thinking-orbs`, `@octanejs/waypoint`, and `@octanejs/xyflow`.
- **Forms and content** — `@octanejs/formisch`, `@octanejs/hook-form`, `@octanejs/input-otp`, `@octanejs/dropzone`, `@octanejs/tanstack-form`, `@octanejs/email`, `@octanejs/email-cli`, `@octanejs/lexical`, `@octanejs/tiptap`, `@octanejs/blocknote`, `@octanejs/markdown`, `@octanejs/streamdown`, `@octanejs/pdf`, `@octanejs/monaco-editor`, `@octanejs/syntax-highlighter`, `@octanejs/mdx`, `@octanejs/i18next`, and `@octanejs/html-react-parser`.
- **Sanity content** — `@octanejs/portabletext`, `@octanejs/sanity-loader`, `@octanejs/sanity-icons`, and `@octanejs/sanity-logos`.
- **Data-heavy screens** — `@tanstack/octane-table`, `@octanejs/tanstack-virtual`, `@octanejs/window`, `@octanejs/recharts`, `@octanejs/visx`, and `@octanejs/react-map-gl`.
- **Web 3D** — `@octanejs/three` and `@octanejs/drei`.
- **Terminal UI** — `@octanejs/ink` and `@octanejs/opentui`.
- **Desktop** — `@octanejs/tauri` and `@octanejs/electron`.
- **Styling, tests, and devtools** — `@octanejs/stylex`, `@octanejs/styled-components`, `@octanejs/testing-library`, `@octanejs/octane-is`, `@octanejs/tanstack-devtools`, `@octanejs/tanstack-query-devtools`, and `@octanejs/devtools`.

Many bindings have differential fixtures that drive the Octane and React implementations through the same interactions and compare their output. Others are verified through their framework-neutral cores, focused behavioral and SSR suites, or public-surface and type checks. The generated status table records the evidence and remaining gaps package by package.

Ports are held to a pinned-release standard rather than written from upstream documentation: a binding targets one immutable upstream release, works from that release's React-facing source kept beside the Octane implementation (so the two read together and the next upgrade is a reviewable diff), accounts for every upstream export as ported, reused verbatim from a framework-neutral core, a divergence, or an explicit gap, runs that release's own test suite where it ships one (framework-neutral suites unmodified, React-binding suites ported case by case) rather than only tests written around the port, and records whatever parity cannot reach as a divergence with a behavioral test. Older bindings are being brought up to that bar package by package, so the generated status table remains the place to check a specific package's covered surface and known divergences. Creating a native binding for a package that has none follows that same porting workflow. Hosting its existing React component with `ReactCompat` does not require a native port.

## Source

- [GitHub repository](https://github.com/octanejs/octane): Runtime, compiler, SSR, bindings, and the full test suite.