@octanejs/testing-library 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @octanejs/testing-library
+
+[React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
+for the [octane](https://github.com/octanejs/octane) renderer.
+
+The split mirrors RTL's own architecture (and
+`docs/react-library-compat-plan.md` §2): **`@testing-library/dom` is
+framework-agnostic and reused verbatim** — every query, `screen`, `within`,
+`waitFor`/`waitForElementToBeRemoved`, `findBy*`, `fireEvent`, `prettyDOM`,
+`configure` — while only react-testing-library's thin React layer is ported to
+octane: `render`, `cleanup`, `renderHook`, the `act` re-export, and the
+dom-testing-library config wiring (`eventWrapper`/`asyncWrapper`) that makes
+every dispatch/wait commit octane's scheduled work before your assertions run.
+
+```ts
+import { render, screen, fireEvent, cleanup } from '@octanejs/testing-library';
+import { Counter } from './Counter.tsrx';
+
+afterEach(cleanup); // automatic when your runner exposes a global afterEach
+
+test('increments', () => {
+	render(Counter, { props: { step: 2 } });
+	fireEvent.click(screen.getByRole('button'));
+	expect(screen.getByRole('button').textContent).toBe('Count: 2');
+});
+```
+
+## API
+
+- `render(ui, options?)` → `{ container, baseElement, ...queries, rerender, unmount, asFragment, debug }`
+- `cleanup()` — unmounts everything `render` mounted (auto-registered afterEach
+  when a global `afterEach`/`teardown` exists; opt out with
+  `RTL_SKIP_AUTO_CLEANUP=true` or import `@octanejs/testing-library/pure`)
+- `renderHook(callback, { initialProps, wrapper, ... }?)` → `{ result, rerender, unmount }`
+- `act` — octane's `act`, re-exported (always async; always `await` it)
+- `fireEvent`, `screen`, `waitFor`, `within`, … — dom-testing-library, re-exported
+
+## Octane-specific surface
+
+**Components are values in plain-`.ts` tests** — there's no JSX in a `.ts`
+file, so `render` (and `rerender`) take two forms:
+
+```ts
+render(Counter, { props: { step: 2 }, wrapper: Providers }); // body + props option
+render(createElement(Counter, { step: 2 }), { wrapper: Providers }); // RTL-style element
+rerender(Counter, { step: 3 }); // rerender takes bare props as the 2nd arg
+```
+
+Same component ⇒ props update in place; a different component tears down and
+remounts — exactly RTL's rerender semantics.
+
+## Differences from react-testing-library
+
+Octane dispatches **native, delegated DOM events — there is no synthetic event
+layer** — so `fireEvent` is dom-testing-library's, deliberately *without* RTL's
+React-specific remappings:
+
+- **`fireEvent.change` fires a native `change`; `fireEvent.input` a native
+  `input`.** In React, `onChange` handlers actually run off native `input`
+  events, so RTL tests habitually drive text inputs with `fireEvent.change`.
+  In octane `onChange` means the platform `change` event (fires on
+  commit/blur), and `onInput` fires per keystroke — port such tests to
+  `fireEvent.input` (or better, `@testing-library/user-event`, which emits
+  real event sequences). There are **no controlled components**: `value` is a
+  plain attribute and inputs are native/uncontrolled, so there's no React-style
+  value re-assertion after events.
+- **No enter/leave/focus double-dispatch.** RTL's `fireEvent.mouseEnter` also
+  fires `mouseover` (and `focus` fires `focusin`, `select` fires `keyup`, …)
+  purely to feed React's plugin system, which listens to different native
+  events than the handler names suggest. Octane's `onMouseEnter` receives the
+  real `mouseenter` (non-bubbling events are capture-delegated), so
+  `fireEvent.mouseEnter` alone triggers it — no compensation needed or wanted.
+- **Commit timing is wired, not synthesized.** Octane already commits discrete
+  events (`click`, `input`, `keydown`, …) synchronously; this package
+  additionally wraps *every* `fireEvent` dispatch in `flushSync` + an effect
+  drain via dom-testing-library's `eventWrapper`, so non-discrete/programmatic
+  events also commit — with their `useEffect` cascades — before `fireEvent`
+  returns (the equivalent of RTL's `act()` around each dispatch).
+- **Host elements at the root render between comment anchors.**
+  `render(createElement('div', …))` goes through octane's value-position
+  renderer, so `container.firstChild` is a comment node — use
+  `container.firstElementChild` (or just queries). Component roots
+  (`render(App, …)`) mount their template directly, no anchors.
+- **`renderHook` and hook slots.** Octane hooks are keyed by compiler-assigned
+  call-site slots. Hook callbacks written in your test files Just Work — the
+  vite plugin's surgical pass slots base-hook calls in plain `.ts`, and
+  `.tsrx`/`.tsx` hooks are fully compiled. The harness additionally runs your
+  callback under a `withSlot` path, so calling a single pre-built binding hook
+  (`renderHook(() => useStore(api))`) works even unslotted. A hand-written
+  callback that calls **two or more base hooks directly without compilation**
+  (e.g. authored outside the vite plugin) still needs explicit slot symbols:
+  `useState(0, Symbol.for('a'))`.
+- **Not ported** (no octane equivalent, by design): `reactStrictMode` /
+  StrictMode double-render, `legacyRoot`, `onCaughtError`/`onRecoverableError`
+  root options, and RTL's `configure({reactStrictMode})` wrapper —
+  `configure`/`getConfig` here are dom-testing-library's own.
+- `hydrate: true` adopts server-rendered DOM already inside `container` via
+  octane's `hydrateRoot` (the container must hold octane SSR output).
+
+## Test-runner setup
+
+Like RTL, importing the package root auto-registers `afterEach(cleanup)` and
+arms octane's "update was not wrapped in act(...)" warning for the run — but
+only when your runner exposes **global** test hooks (vitest `globals: true`,
+jest). With `globals: false`, register it yourself:
+
+```ts
+import { cleanup } from '@octanejs/testing-library';
+import { afterEach } from 'vitest';
+afterEach(cleanup);
+```
+
+`@octanejs/testing-library/pure` skips the side effects entirely, exactly like
+`@testing-library/react/pure`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@octanejs/testing-library",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "React Testing Library for the octane renderer — reuses the framework-agnostic @testing-library/dom verbatim and ports only react-testing-library's thin React layer (render/cleanup/renderHook) onto octane's createRoot + act.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/testing-library"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./pure": "./src/pure.ts"
+  },
+  "dependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/act-environment.ts

@@ -0,0 +1,21 @@
+// Internal act()-environment bookkeeping — NOT re-exported from the package.
+//
+// Octane keeps its IS_OCTANE_ACT_ENVIRONMENT flag module-private behind a
+// write-only setter (`setIsOctaneActEnvironment`), so the current value is
+// mirrored here for the save/disable/restore dance `waitFor` needs (RTL's
+// act-compat mirrors React's IS_REACT_ACT_ENVIRONMENT global the same way).
+// The mirror is exact as long as the flag is toggled through THIS module —
+// which the auto-registering `index.ts` entry and the `pure.ts` asyncWrapper
+// both do, matching RTL's assumption about its own global.
+import { setIsOctaneActEnvironment } from 'octane';
+
+let isActEnvironment = false;
+
+export function getIsOctaneActEnvironment(): boolean {
+	return isActEnvironment;
+}
+
+export function setOctaneActEnvironment(value: boolean): void {
+	isActEnvironment = value;
+	setIsOctaneActEnvironment(value);
+}

package/src/fire-event.ts

@@ -0,0 +1,17 @@
+// `fireEvent` — dom-testing-library's, re-exported UNWRAPPED.
+//
+// react-testing-library layers remappings on top of dom-testing-library's
+// fireEvent because React's synthetic event system listens to DIFFERENT native
+// events than the handler names suggest (mouseEnter handlers run off native
+// mouseover, focus/blur off focusin/focusout, `select` is synthesized from key
+// events, `onChange` fires on native input, …), so RTL double-dispatches to
+// feed React's plugins.
+//
+// Octane has NO synthetic event layer — `onX` handlers receive the native `x`
+// event, delegated. `fireEvent.mouseEnter` therefore dispatches a real
+// `mouseenter` and octane's capture-phase delegation of non-bubbling events
+// delivers it; `fireEvent.change` fires a native `change` (NOT React's
+// input-as-change); no remapping is wanted. The commit wiring (flushSync +
+// effect drain around every dispatch) rides on dom-testing-library's
+// `eventWrapper` config hook — see pure.ts.
+export { fireEvent } from '@testing-library/dom';

package/src/index.ts

@@ -0,0 +1,45 @@
+// Default entry — `pure` plus RTL's test-framework side effects:
+//
+//  1. auto-`cleanup()` after each test when the runner exposes a global
+//     `afterEach` (or `teardown`), opt-out via RTL_SKIP_AUTO_CLEANUP;
+//  2. octane's act()-environment warning armed for the whole run when global
+//     `beforeAll`/`afterAll` exist (mirrors RTL flipping IS_REACT_ACT_ENVIRONMENT).
+//
+// NOTE: with `globals: false` runners (this repo's vitest config) none of these
+// globals exist, so both registrations are no-ops — register `afterEach(cleanup)`
+// yourself, exactly like importing `@testing-library/react/pure`.
+import { cleanup } from './pure';
+import { getIsOctaneActEnvironment, setOctaneActEnvironment } from './act-environment';
+
+type TestHook = (callback: () => void) => void;
+const globals = globalThis as {
+	afterEach?: TestHook;
+	teardown?: TestHook;
+	beforeAll?: TestHook;
+	afterAll?: TestHook;
+};
+
+if (typeof process === 'undefined' || !process.env?.RTL_SKIP_AUTO_CLEANUP) {
+	if (typeof globals.afterEach === 'function') {
+		globals.afterEach(() => {
+			cleanup();
+		});
+	} else if (typeof globals.teardown === 'function') {
+		globals.teardown(() => {
+			cleanup();
+		});
+	}
+
+	if (typeof globals.beforeAll === 'function' && typeof globals.afterAll === 'function') {
+		let previousIsActEnvironment = getIsOctaneActEnvironment();
+		globals.beforeAll(() => {
+			previousIsActEnvironment = getIsOctaneActEnvironment();
+			setOctaneActEnvironment(true);
+		});
+		globals.afterAll(() => {
+			setOctaneActEnvironment(previousIsActEnvironment);
+		});
+	}
+}
+
+export * from './pure';

package/src/pure.ts

@@ -0,0 +1,394 @@
+/**
+ * @octanejs/testing-library — the side-effect-free core (`…/pure` entry).
+ *
+ * Strategy (docs/react-library-compat-plan.md §2): `@testing-library/dom` is
+ * framework-agnostic, so it is depended on VERBATIM and re-exported wholesale
+ * (queries, `screen`, `within`, `waitFor`, `fireEvent`, `prettyDOM`, …). Only
+ * react-testing-library's thin React layer is ported here, onto octane:
+ *
+ *  - `render` / `cleanup` / `renderHook` mount through octane's `createRoot`
+ *    (or `hydrateRoot`) and commit synchronously via `flushSync` + a passive-
+ *    effect drain — the observable equivalent of RTL wrapping every render in
+ *    a synchronous React `act()`.
+ *  - dom-testing-library's config hooks are wired to octane's commit machinery
+ *    (`eventWrapper` → flushSync, `asyncWrapper` → act-environment suspension,
+ *    `unstable_advanceTimersWrapper` → octane `act`) exactly where RTL wires
+ *    them to React's act-compat.
+ *
+ * Octane-specific surface (documented in the README): components in plain-`.ts`
+ * tests are values, not JSX — so `render` accepts BOTH an element descriptor
+ * (`render(createElement(App, {x: 1}))`) and the bare component + a `props`
+ * render-option (`render(App, {props: {x: 1}})`).
+ */
+import {
+	act,
+	createElement,
+	createRoot,
+	drainPassiveEffects,
+	flushSync,
+	hasPendingWork,
+	hydrateRoot,
+	isValidElement,
+	useEffect,
+	withSlot,
+	type ComponentBody,
+	type ElementDescriptor,
+	type Root,
+} from 'octane';
+import {
+	configure as configureDTL,
+	getQueriesForElement,
+	prettyDOM,
+	queries as defaultQueries,
+} from '@testing-library/dom';
+import type { BoundFunctions, Queries } from '@testing-library/dom';
+import { getIsOctaneActEnvironment, setOctaneActEnvironment } from './act-environment';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// dom-testing-library config wiring (RTL pure.js does the same three hooks).
+// ─────────────────────────────────────────────────────────────────────────────
+
+// vitest/sinon fake timers stamp a `clock` property on the mocked setTimeout;
+// jest's legacy timer mocks stamp `_isMockFunction` (the same two probes RTL
+// ships). Used to avoid parking `asyncWrapper` on a macrotask that a fake
+// clock would never fire.
+function fakeTimersAreEnabled(): boolean {
+	const st = setTimeout as unknown as { _isMockFunction?: boolean };
+	return st._isMockFunction === true || Object.prototype.hasOwnProperty.call(setTimeout, 'clock');
+}
+
+configureDTL({
+	// `waitFor` with fake timers advances the clock through this wrapper; octane's
+	// act() drains the renders/effects each advancement schedules.
+	unstable_advanceTimersWrapper: (cb) => act(cb as () => unknown),
+	// `waitFor`/`findBy*` bodies await work that legitimately updates state outside
+	// an act() scope — suspend the "not wrapped in act(...)" warning for the
+	// duration (RTL does the same around IS_REACT_ACT_ENVIRONMENT).
+	asyncWrapper: async (cb) => {
+		const previousActEnvironment = getIsOctaneActEnvironment();
+		setOctaneActEnvironment(false);
+		try {
+			const result = await cb();
+			// Let in-flight promise reactions land before the act environment is
+			// restored (RTL's 0ms settle). Octane flushes scheduled renders on
+			// microtasks, so under a fake clock — where a real 0ms timer would never
+			// fire and library code has no handle to advance vitest's clock (unlike
+			// jest's global) — a drained microtask queue is already quiescent.
+			await new Promise<void>((resolve) => {
+				if (fakeTimersAreEnabled()) {
+					void Promise.resolve().then(() => resolve());
+				} else {
+					setTimeout(() => resolve(), 0);
+				}
+			});
+			settleSync();
+			return result;
+		} finally {
+			setOctaneActEnvironment(previousActEnvironment);
+		}
+	},
+	// Every `fireEvent` dispatch runs through here. Octane's DISCRETE delegated
+	// events (click/input/keydown/…) already commit synchronously on their own
+	// (maybeFlushDiscrete → flushSync), but fireEvent also dispatches event types
+	// with no discrete path — non-delegated or programmatic events whose updates
+	// would otherwise sit queued until the next microtask, i.e. after the test's
+	// assertion. flushSync commits those too, and the passive drain mirrors RTL's
+	// act(): effects scheduled by the event have run before fireEvent returns.
+	eventWrapper: (cb) => {
+		let result: unknown;
+		flushSync(() => {
+			result = cb();
+		});
+		settleSync();
+		return result;
+	},
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mounted-root bookkeeping (RTL pure.js's mountedContainers/mountedRootEntries):
+// a Set for the constant-time "new container?" check, an array for cleanup().
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RootEntry {
+	container: Element;
+	root: Root;
+}
+const mountedContainers = new Set<Element>();
+const mountedRootEntries: RootEntry[] = [];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UI normalization — octane's two authoring forms into one mountable element.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** What `render`/`rerender` accept: a component body, or a `createElement` result. */
+export type OctaneUI<P = any> = ComponentBody<P> | ElementDescriptor<P>;
+
+// A root can only mount a COMPONENT. `render(createElement('div', …))` (RTL's
+// `render(<div/>)`) produces a HOST descriptor, so it is returned from a pass-
+// through component and rendered by the runtime's value-position renderer.
+function ValueRoot(props: { children: unknown }): unknown {
+	return props.children;
+}
+
+function toElement<P>(ui: OctaneUI<P>, props: P | undefined): ElementDescriptor {
+	if (isValidElement(ui)) {
+		if (props !== undefined) {
+			throw new Error(
+				'render/rerender received both an element descriptor and `props` — ' +
+					'pass props through createElement(Component, props), or pass the bare component.',
+			);
+		}
+		return ui;
+	}
+	if (typeof ui !== 'function') {
+		throw new Error(
+			'render/rerender expects an octane component (a function) or an element ' +
+				`descriptor from createElement(...); received ${typeof ui}.`,
+		);
+	}
+	return createElement(ui, props);
+}
+
+function wrapUiIfNeeded(
+	element: ElementDescriptor,
+	wrapperComponent: ComponentBody<{ children: any }> | undefined,
+): ElementDescriptor {
+	return wrapperComponent ? createElement(wrapperComponent, { children: element }) : element;
+}
+
+function mountable(element: ElementDescriptor): ElementDescriptor {
+	return typeof element.type === 'string'
+		? createElement(ValueRoot, { children: element })
+		: element;
+}
+
+// Drain render ⇄ passive-effect cascades to quiescence, SYNCHRONOUSLY: each
+// round runs queued useEffect bodies (which may setState) and then commits the
+// renders they scheduled (flushSync also runs layout-effect cascades, queuing
+// the next round's passives). This is the observable behavior of RTL wrapping
+// work in a sync React `act()`. Loops on octane's scheduler-quiescence probe
+// (`hasPendingWork`) for an EXACT settle; the round cap only guards against a
+// pathological unbounded effect→setState cycle (which octane's own
+// "Too many re-renders" guard would surface anyway). Purely promise-driven work
+// (use(promise), transitions) can never settle synchronously — that's what
+// `waitFor`/`findBy*`/`act` are for, same as RTL.
+function settleSync(): void {
+	for (let i = 0; i < 50 && hasPendingWork(); i++) {
+		drainPassiveEffects();
+		flushSync(() => {});
+	}
+}
+
+// Commit a render synchronously — flushSync for the render itself, then the
+// cascade settle. Equivalent to RTL's `act(() => root.render(ui))` (sync form).
+function commitRender(root: Root, element: ElementDescriptor): void {
+	flushSync(() => {
+		root.render(element);
+	});
+	settleSync();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// render()
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RenderOptions<P = any> {
+	/** Element the UI mounts into. Defaults to a fresh <div> appended to baseElement. */
+	container?: HTMLElement;
+	/** Element the returned queries are bound to. Defaults to `container` or document.body. */
+	baseElement?: HTMLElement;
+	/** Adopt server-rendered DOM already inside `container` via octane's hydrateRoot. */
+	hydrate?: boolean;
+	/** Custom dom-testing-library queries (untyped passthrough; result is typed for the defaults). */
+	queries?: Queries;
+	/** Component rendered around the UI — must render `{props.children}` (providers etc.). */
+	wrapper?: ComponentBody<{ children: any }>;
+	/**
+	 * Octane extension: props for the `render(Component, {props})` form — in
+	 * plain-`.ts` tests a component is a VALUE, so this replaces JSX's inline
+	 * props. Ignored (an error) when `ui` is already an element descriptor.
+	 */
+	props?: P;
+}
+
+export type DebugFn = (
+	el?: Element | DocumentFragment | Array<Element | DocumentFragment>,
+	maxLength?: number,
+	options?: Parameters<typeof prettyDOM>[2],
+) => void;
+
+export type RenderResult = {
+	container: HTMLElement;
+	baseElement: HTMLElement;
+	debug: DebugFn;
+	/** Re-render (same component ⇒ props update in place, like RTL's rerender). */
+	rerender: (ui: OctaneUI, props?: any) => void;
+	unmount: () => void;
+	asFragment: () => DocumentFragment;
+} & BoundFunctions<typeof defaultQueries>;
+
+export function render<P = any>(ui: OctaneUI<P>, options: RenderOptions<P> = {}): RenderResult {
+	const { hydrate = false, props, queries, wrapper: WrapperComponent } = options;
+	let { baseElement, container } = options;
+
+	if (!baseElement) {
+		// Default to document.body (not documentElement) — matches RTL, keeps
+		// debug output free of <head> noise.
+		baseElement = options.container ?? document.body;
+	}
+	if (!container) {
+		container = baseElement.appendChild(document.createElement('div'));
+	}
+
+	const element = mountable(wrapUiIfNeeded(toElement(ui, props), WrapperComponent));
+
+	let root: Root;
+	if (!mountedContainers.has(container)) {
+		if (hydrate) {
+			// hydrateRoot adopts the server DOM during creation (it renders once,
+			// synchronously) — only the effect settle is left to do.
+			root = hydrateRoot(container, element);
+			settleSync();
+		} else {
+			root = createRoot(container);
+			commitRender(root, element);
+		}
+		mountedRootEntries.push({ container, root });
+		// Track the container regardless of whether WE created it, so cleanup()
+		// handles caller-supplied containers too (RTL does the same).
+		mountedContainers.add(container);
+	} else {
+		// Same container rendered again → reuse its root (same component updates
+		// props in place; a different component tears down and remounts).
+		root = mountedRootEntries.find((entry) => entry.container === container)!.root;
+		commitRender(root, element);
+	}
+
+	return {
+		container,
+		baseElement,
+		// prettyDOM handles DocumentFragments at runtime; its published type only
+		// admits Element, hence the casts.
+		debug: (el = baseElement, maxLength, debugOptions) =>
+			Array.isArray(el)
+				? // eslint-disable-next-line no-console
+					el.forEach((e) => console.log(prettyDOM(e as Element, maxLength, debugOptions)))
+				: // eslint-disable-next-line no-console
+					console.log(prettyDOM(el as Element, maxLength, debugOptions)),
+		unmount: () => {
+			flushSync(() => {
+				root.unmount();
+			});
+		},
+		rerender: (rerenderUi: OctaneUI, rerenderProps?: any) => {
+			// The wrapper is re-applied so component identity is stable across
+			// rerenders (same body ⇒ octane updates props in place).
+			commitRender(
+				root,
+				mountable(wrapUiIfNeeded(toElement(rerenderUi, rerenderProps), WrapperComponent)),
+			);
+		},
+		asFragment: () => document.createRange().createContextualFragment(container.innerHTML),
+		...(getQueriesForElement(baseElement, queries as any) as BoundFunctions<typeof defaultQueries>),
+	};
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// cleanup()
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function cleanup(): void {
+	for (const { root, container } of mountedRootEntries) {
+		flushSync(() => {
+			root.unmount();
+		});
+		if (container.parentNode === document.body) {
+			document.body.removeChild(container);
+		}
+	}
+	mountedRootEntries.length = 0;
+	mountedContainers.clear();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// renderHook()
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RenderHookOptions<Props> extends Omit<RenderOptions, 'props'> {
+	/** Props passed to the hook callback on the first render. */
+	initialProps?: Props;
+}
+
+export interface RenderHookResult<Result, Props> {
+	/** Latest COMMITTED hook result (recorded from an effect, like RTL). */
+	result: { current: Result };
+	rerender: (props?: Props) => void;
+	unmount: () => void;
+}
+
+// The harness component below is plain `.ts`, so its own hooks take EXPLICIT
+// slot symbols (this package is excluded from the compiler's auto-slotting
+// pass; published node_modules are skipped by it anyway). Hook state is keyed
+// per (component scope, slot), so module-level symbols are safe across
+// concurrently mounted harnesses.
+const HOOK_PATH_SLOT = Symbol.for('@octanejs/testing-library:renderHook/callback');
+const RECORD_EFFECT_SLOT = Symbol.for('@octanejs/testing-library:renderHook/record');
+
+export function renderHook<Result, Props = undefined>(
+	renderCallback: (props: Props) => Result,
+	options: RenderHookOptions<Props> = {},
+): RenderHookResult<Result, Props> {
+	const { initialProps, ...renderOptions } = options;
+	const result: { current: Result } = { current: undefined as never };
+
+	// Defined per renderHook call (RTL does the same) so each invocation gets a
+	// distinct component identity, while rerenders of THIS invocation keep it.
+	function TestComponent(props: { renderCallbackProps: Props }) {
+		// withSlot pushes a call-site path for the callback's duration: a slotless
+		// custom hook reached from here (one the compiler never saw — e.g. a
+		// binding hook called directly in a plain-`.ts` test) still resolves a
+		// hook identity, and the trailing symbol serves bindings that read their
+		// slot off the last argument. Compiled callbacks are unaffected — their
+		// explicit per-call-site slots fold into the path deterministically.
+		// (A slotless callback calling TWO+ base hooks directly still needs the
+		// compiler or explicit symbols — the path alone can't tell them apart.)
+		const pendingResult = withSlot(
+			HOOK_PATH_SLOT,
+			renderCallback as (...args: any[]) => Result,
+			props.renderCallbackProps,
+			HOOK_PATH_SLOT,
+		);
+		// Record on COMMIT (RTL records from useEffect): a render that throws
+		// never publishes a result.
+		useEffect(
+			() => {
+				result.current = pendingResult;
+			},
+			undefined,
+			RECORD_EFFECT_SLOT,
+		);
+		return null;
+	}
+
+	const { rerender: baseRerender, unmount } = render(TestComponent, {
+		...renderOptions,
+		props: { renderCallbackProps: initialProps as Props },
+	});
+
+	return {
+		result,
+		rerender: (rerenderCallbackProps?: Props) =>
+			baseRerender(TestComponent, { renderCallbackProps: rerenderCallbackProps as Props }),
+		unmount,
+	};
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports — everything dom-testing-library ships, plus the octane layer.
+// `fireEvent` is dom-testing-library's own (see fire-event.ts for why there is
+// deliberately NO react-testing-library-style event remapping on top).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export * from '@testing-library/dom';
+export { fireEvent } from './fire-event';
+export { act } from 'octane';