@octanejs/zag 0.0.1

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,59 @@
+# @octanejs/zag
+
+[Zag](https://zagjs.com/) state-machine bindings for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+This package ports `@zag-js/react@1.42.0` onto Octane while reusing the
+framework-agnostic `@zag-js/core`, `@zag-js/store`, `@zag-js/types`, and
+`@zag-js/utils` packages unchanged. It is the runtime substrate for Octane
+ports of component libraries built on Zag, including Ark UI and Chakra UI.
+
+Change the framework adapter import while keeping machine definitions and
+connect functions on their existing `@zag-js/*` packages:
+
+```ts
+// before
+import { normalizeProps, useMachine } from '@zag-js/react';
+
+// after
+import { normalizeProps, useMachine } from '@octanejs/zag';
+```
+
+```tsx
+import { normalizeProps, useMachine } from '@octanejs/zag';
+import * as toggle from '@zag-js/toggle';
+
+export function Toggle() @{
+  const service = useMachine(toggle.machine, { id: 'example' });
+  const api = toggle.connect(service, normalizeProps);
+
+  <button {...api.getRootProps()}>{api.pressed ? 'On' : 'Off'}</button>
+}
+```
+
+## API
+
+The public surface matches `@zag-js/react@1.42.0`:
+
+- `useMachine` runs a Zag machine with Octane hooks.
+- `normalizeProps` types Zag-generated host props for Octane JSX.
+- `Portal` renders into `document.body` or a supplied container and supports
+  disabled and server-rendered in-place output.
+- `mergeProps` is re-exported from `@zag-js/core`.
+- `useSyncExternalStore` is re-exported from Octane.
+
+The adapter forwards Octane's compiler-assigned hook slots through every
+composed hook and through Zag's indirect `bindable` and `track` callbacks.
+Distinct machines and bindable context values therefore remain independent.
+
+## Verification
+
+Behavioral tests cover transitions, bindable context, independent hook call
+sites, multi-child portals, disabled portals, and server rendering. A
+differential test runs the same machine through this package and
+`@zag-js/react@1.42.0` and compares the state/context trace. Published source
+and dependency checks ensure React is development-only.
+
+Current scope and verification status are tracked in the generated
+[bindings status table](../../docs/bindings-status.md), sourced from this
+package's [`status.json`](./status.json).

package/UPSTREAM.md

@@ -0,0 +1,76 @@
+# @zag-js/react upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Package | `@zag-js/react` |
+| Version | `1.42.0` |
+| Canonical tag commit | `df65e4c87c75a1c84eb6eb08a8e30dac0e1bb77f` |
+| Supported upstream range | exactly `1.42.0` |
+| React oracle | `19.2.7` with `@types/react@19.2.7` and `@types/react-dom@19.2.3` (`catalog:zag-react-oracle`) |
+| Testing Library oracle | `@testing-library/react@16.3.2` (`catalog:zag-react-oracle`; satisfies upstream `^16.3.2`) |
+| jsdom oracle | `29.0.1` (`catalog:zag-react-oracle`; satisfies upstream `^29.0.1`) |
+| Vendored tree integrity | `sha256:037f857d00462559b9790acc2214c818678eb9d61970d6c394dc26dcfcd1516d` (`packages/zag/upstream/SHA256SUMS`) |
+| License | MIT, © Chakra UI |
+
+Repository: `https://github.com/chakra-ui/zag.git`. The npm artifact publishes
+compiled `dist/` output. The framework adapter source and its Vitest suite at
+this pin live under `packages/frameworks/react` in the canonical repository and
+are vendored byte-exact at `packages/zag/upstream/` (MIT). Framework-agnostic
+`@zag-js/core`, `@zag-js/store`, `@zag-js/types`, and `@zag-js/utils` at the same
+version are reused unchanged and are not reimplemented here.
+
+## Runtime export crosswalk
+
+| Upstream export | Octane disposition | Evidence |
+|---|---|---|
+| `useMachine` | Ported to Octane hooks in `src/machine.ts` | `tests/upstream/machine.test.ts`, `tests/upstream/nested-states.test.ts`, `tests/differential/machine.test.ts` |
+| `normalizeProps` | Ported in `src/normalize-props.ts` with documented text-host event rewrite | Framework-contract: `tests/conformance/upstream-surface.test.ts`. Not an upstream-suite identity; see Intentional divergences. |
+| `Portal` | Ported in `src/portal.ts` | Differential: `tests/differential/portal.test.ts`. Framework-contract / SSR pins: `tests/conformance/machine.test.ts`, `tests/ssr/server.test.ts` (not counted as React-parity identities). |
+| `mergeProps` | Re-exported from `@zag-js/core` | Structural export inventory in `tests/conformance/upstream-surface.test.ts` |
+| `useSyncExternalStore` | Re-exported from Octane | Structural export inventory in `tests/conformance/upstream-surface.test.ts` |
+
+## Intentional divergences
+
+- **Text-host `onChange` → `onInput`.** Upstream `normalizeProps` is an identity
+  normalizer. Octane rewrites React-style text-entry `onChange` to native
+  `onInput` for `normalizeProps.textarea` and `normalizeProps.input` when the
+  type is a text-entry host (`text`/`search`/`url`/`tel`/`password`/`email`/
+  `number`, plus missing/invalid types that HTML defaults to text).
+  `<select>` and non-text inputs (`checkbox`/`radio`/`file`/`date`/`range`/
+  …) keep native `onChange`. Upstream has no cases for this export; the rewrite
+  is pinned by `tests/conformance/upstream-surface.test.ts` and recorded in
+  `status.json`.
+- **Portal ref / children shape.** Container refs use Octane's structural
+  `{ current: HTMLElement | null }` rather than `React.RefObject`. Compiled
+  Octane children blocks portal as one unit so component scope is preserved;
+  ordinary value children keep upstream's per-child portal behavior. Mount /
+  disabled / root-node behavior is compared against `@zag-js/react@1.42.0` in
+  `tests/differential/portal.test.ts`.
+
+## Test-suite disposition
+
+Upstream `@zag-js/react` ships a Vitest runtime suite under
+`packages/frameworks/react/tests` at this pin (`machine.test.ts`,
+`nested-states.test.ts`, `strict-mode.test.tsx`, plus `render.ts`,
+`vite.config.ts`, and `vitest.setup.ts`). That suite is recorded as present and
+locked under `packages/zag/upstream/`.
+
+| Upstream artifact | Disposition | Octane location / notes |
+|---|---|---|
+| `tests/machine.test.ts` | Ported one-for-one | `tests/upstream/machine.test.ts` |
+| `tests/nested-states.test.ts` | Ported one-for-one | `tests/upstream/nested-states.test.ts` |
+| `tests/strict-mode.test.tsx` | Out of scope for adapted Octane lane | React StrictMode double-invoke is an intentional Octane non-feature; still executed in the pristine React lane. Exact pristine case IDs and rationale are locked in `audit/runtime-case-dispositions.json` and checked by the pristine→adapted inventory crosswalk. |
+| `tests/render.ts` | Ported helper | `tests/upstream/render.ts` |
+
+Parity evidence:
+
+- pristine full suite: `zag-pristine` Vitest project / `tests/upstream-original.test.ts`
+- adapted full suite: `zag` Vitest project / `tests/upstream/**/*.test.ts`
+- differential (supplementary): `zag-differential` / `tests/differential/*.test.ts`
+- pristine types: `packages/zag/audit/type-probes` via `tsc`
+- adapted types: `packages/zag/typetests` via `tsrx-tsc`
+
+Conformance and SSR tests remain ordinary `zag` / `zag-ssr` package coverage and
+are not counted as adapted upstream-suite identities.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@octanejs/zag",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Zag state-machine bindings for Octane, backed by the framework-agnostic @zag-js core packages.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/zag"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@zag-js/core": "1.42.0",
+    "@zag-js/store": "1.42.0",
+    "@zag-js/types": "1.42.0",
+    "@zag-js/utils": "1.42.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.35"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.56",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "@zag-js/react": "1.42.0",
+    "esbuild": "^0.28.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "vitest": "^4.1.10",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@vitejs/plugin-react": "^6.0.3",
+    "jsdom": "29.0.1",
+    "octane": "0.1.35",
+    "@octanejs/testing-library": "0.1.32"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project zag --project zag-differential --project zag-ssr --project zag-pristine",
+    "test:upstream": "node scripts/run-pristine-upstream.mjs",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json",
+    "upstream:verify": "node scripts/verify-upstream.mjs"
+  }
+}

package/src/bindable.ts

@@ -0,0 +1,86 @@
+import type { Bindable, BindableParams } from '@zag-js/core';
+import { isFunction } from '@zag-js/utils';
+import { flushSync, useEffect, useRef, useState } from 'octane';
+
+import { subSlot } from './internal';
+import { useSafeLayoutEffect } from './use-layout-effect';
+
+function useBindableValue<T>(
+	props: () => BindableParams<T>,
+	slot: symbol | undefined,
+): Bindable<T> {
+	const initial = props().value ?? props().defaultValue;
+	const eq = props().isEqual ?? Object.is;
+
+	const [initialValue] = useState(initial, subSlot(slot, 'initial'));
+	const [value, setValue] = useState(initialValue, subSlot(slot, 'value'));
+	const controlled = props().value !== undefined;
+
+	const valueRef = useRef(value, subSlot(slot, 'value-ref'));
+	valueRef.current = controlled ? props().value : value;
+
+	const prevValue = useRef(valueRef.current, subSlot(slot, 'previous-value'));
+	useSafeLayoutEffect(
+		() => {
+			prevValue.current = valueRef.current;
+		},
+		[value, props().value],
+		subSlot(slot, 'sync-previous'),
+	);
+
+	const setFn = (nextValue: T | ((prev: T) => T)) => {
+		const previous = prevValue.current;
+		const next = isFunction(nextValue) ? nextValue(previous as T) : nextValue;
+
+		if (props().debug) {
+			console.log(`[bindable > ${props().debug}] setValue`, { next, prev: previous });
+		}
+
+		// Controlled values stay pinned to props().value (re-synced each render).
+		// Uncontrolled updates advance valueRef immediately so mid-transition
+		// action chains read the value set() already wrote.
+		if (!controlled) {
+			valueRef.current = next;
+			prevValue.current = next;
+			setValue(next);
+		}
+		if (!eq(next, previous)) props().onChange?.(next, previous);
+	};
+
+	return {
+		initial: initialValue,
+		ref: valueRef,
+		get() {
+			return (controlled ? props().value : valueRef.current) as T;
+		},
+		set(nextValue: T | ((prev: T) => T)) {
+			const execute = props().sync ? flushSync : (run: () => void) => run();
+			execute(() => setFn(nextValue));
+		},
+		invoke(nextValue: T, previousValue: T) {
+			props().onChange?.(nextValue, previousValue);
+		},
+		hash(nextValue: T) {
+			return props().hash?.(nextValue) ?? String(nextValue);
+		},
+	};
+}
+
+function cleanup(fn: VoidFunction, slot?: symbol) {
+	useEffect(() => fn, [], subSlot(slot, 'cleanup'));
+}
+
+function bindableRef<T>(defaultValue: T, slot?: symbol) {
+	const value = useRef(defaultValue, subSlot(slot, 'ref'));
+	return {
+		get: () => value.current,
+		set: (next: T) => {
+			value.current = next;
+		},
+	};
+}
+
+export const useBindable = Object.assign(
+	<T>(props: () => BindableParams<T>, slot?: symbol) => useBindableValue(props, slot),
+	{ cleanup, ref: bindableRef },
+);

package/src/index.ts

@@ -0,0 +1,5 @@
+export { mergeProps } from '@zag-js/core';
+export { useSyncExternalStore } from 'octane';
+export * from './machine';
+export * from './normalize-props';
+export * from './portal';

package/src/internal.ts

@@ -0,0 +1,32 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareSlotCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareSlotCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/zag:${tag}`);
+			bareSlotCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}
+
+export function splitSlot(args: unknown[]): [unknown[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/machine.ts

@@ -0,0 +1,352 @@
+import type {
+	ActionsOrFn,
+	Bindable,
+	BindableContext,
+	BindableRefs,
+	ChooseFn,
+	ComputedFn,
+	EffectsOrFn,
+	GuardFn,
+	Machine,
+	MachineSchema,
+	Params,
+	Service,
+} from '@zag-js/core';
+import {
+	createScope,
+	findTransition,
+	getExitEnterStates,
+	hasTag,
+	INIT_STATE,
+	MachineStatus,
+	matchesState,
+	resolveStateValue,
+} from '@zag-js/core';
+import { callAll, compact, ensure, isFunction, isString, toArray, warn } from '@zag-js/utils';
+import { flushSync, useMemo, useRef } from 'octane';
+
+import { useBindable } from './bindable';
+import { splitSlot, subSlot } from './internal';
+import { useRefs } from './refs';
+import { useTrack } from './track';
+import { useSafeLayoutEffect } from './use-layout-effect';
+
+export function useMachine<T extends MachineSchema>(
+	machine: Machine<T>,
+	userProps?: Partial<T['props']>,
+): Service<T>;
+export function useMachine<T extends MachineSchema>(...rawArgs: unknown[]): Service<T> {
+	const [args, slot] = splitSlot(rawArgs);
+	const [machine, suppliedProps = {}] = args as [Machine<T>, Partial<T['props']>?];
+	const userProps = suppliedProps ?? {};
+
+	const scope = useMemo(
+		() => {
+			const { id, ids, getRootNode } = userProps as any;
+			return createScope({ id, ids, getRootNode });
+		},
+		[userProps],
+		subSlot(slot, 'scope'),
+	);
+
+	const debug = (...args: any[]) => {
+		if (machine.debug) console.log(...args);
+	};
+
+	const props: any = machine.props?.({ props: compact(userProps), scope }) ?? userProps;
+	const prop = useProp(props, subSlot(slot, 'prop'));
+
+	let bindableIndex = 0;
+	let cleanupIndex = 0;
+	let bindableRefIndex = 0;
+	const bindable = Object.assign(
+		<TValue>(params: () => any) =>
+			useBindable<TValue>(params, subSlot(slot, `context-bindable:${bindableIndex++}`)),
+		{
+			cleanup: (fn: VoidFunction) =>
+				useBindable.cleanup(fn, subSlot(slot, `context-cleanup:${cleanupIndex++}`)),
+			ref: <TValue>(defaultValue: TValue) =>
+				useBindable.ref(defaultValue, subSlot(slot, `context-ref:${bindableRefIndex++}`)),
+		},
+	) as typeof useBindable;
+
+	const context = machine.context?.({
+		prop,
+		bindable,
+		scope,
+		flush,
+		getContext() {
+			return ctx as any;
+		},
+		getComputed() {
+			return computed as any;
+		},
+		getRefs() {
+			return refs as any;
+		},
+		getEvent() {
+			return getEvent();
+		},
+	});
+
+	const contextRef = useLiveRef<any>(context, subSlot(slot, 'context'));
+	const ctx: BindableContext<T> = {
+		get(key) {
+			return contextRef.current?.[key].ref.current;
+		},
+		set(key, value) {
+			contextRef.current?.[key].set(value);
+		},
+		initial(key) {
+			return contextRef.current?.[key].initial;
+		},
+		hash(key) {
+			const current = contextRef.current?.[key].ref.current;
+			return contextRef.current?.[key].hash(current);
+		},
+	};
+
+	const effects = useRef(new Map<string, VoidFunction>(), subSlot(slot, 'effects'));
+	const transitionRef = useRef<any>(null, subSlot(slot, 'transition'));
+	const previousEventRef = useRef<any>(null, subSlot(slot, 'previous-event'));
+	const eventRef = useRef<any>({ type: '' }, subSlot(slot, 'event'));
+
+	const getEvent = () => ({
+		...eventRef.current,
+		current() {
+			return eventRef.current;
+		},
+		previous() {
+			return previousEventRef.current;
+		},
+	});
+
+	const getState = () => ({
+		...state,
+		matches(...values: T['state'][]) {
+			return values.some((value) => matchesState(state.ref.current as string, value as string));
+		},
+		hasTag(tag: T['tag']) {
+			return hasTag(machine, state.ref.current, tag);
+		},
+	});
+
+	const refs: BindableRefs<T> = useRefs(
+		machine.refs?.({ prop, context: ctx }) ?? {},
+		subSlot(slot, 'refs'),
+	);
+
+	let trackIndex = 0;
+	const track = (deps: any[], trackedEffect: VoidFunction) =>
+		useTrack(deps, trackedEffect, subSlot(slot, `track:${trackIndex++}`));
+
+	const getParams = (): Params<T> => ({
+		state: getState(),
+		context: ctx,
+		event: getEvent(),
+		prop,
+		send,
+		action,
+		guard,
+		track,
+		refs,
+		computed,
+		flush,
+		scope,
+		choose,
+	});
+
+	const action = (keys: ActionsOrFn<T> | undefined) => {
+		const strings = isFunction(keys) ? keys(getParams()) : keys;
+		if (!strings) return;
+		const functions = strings.map((key) => {
+			const fn = machine.implementations?.actions?.[key];
+			if (!fn) warn(`[zag-js] No implementation found for action "${JSON.stringify(key)}"`);
+			return fn;
+		});
+		for (const fn of functions) fn?.(getParams());
+	};
+
+	const guard = (key: T['guard'] | GuardFn<T>) => {
+		if (isFunction(key)) return key(getParams());
+		const fn = machine.implementations?.guards?.[key];
+		if (!fn) warn(`[zag-js] No implementation found for guard "${JSON.stringify(key)}"`);
+		return fn?.(getParams());
+	};
+
+	const effect = (keys: EffectsOrFn<T> | undefined) => {
+		const strings = isFunction(keys) ? keys(getParams()) : keys;
+		if (!strings) return;
+		const functions = strings.map((key) => {
+			const fn = machine.implementations?.effects?.[key];
+			if (!fn) warn(`[zag-js] No implementation found for effect "${JSON.stringify(key)}"`);
+			return fn;
+		});
+		const cleanups: VoidFunction[] = [];
+		for (const fn of functions) {
+			const cleanup = fn?.(getParams());
+			if (cleanup) cleanups.push(cleanup);
+		}
+		return () => cleanups.forEach((cleanup) => cleanup?.());
+	};
+
+	const choose: ChooseFn<T> = (transitions) =>
+		toArray(transitions).find((transition) => {
+			let result = !transition.guard;
+			if (isString(transition.guard)) result = !!guard(transition.guard);
+			else if (isFunction(transition.guard)) result = transition.guard(getParams());
+			return result;
+		});
+
+	const computed: ComputedFn<T> = (key) => {
+		ensure(machine.computed, () => '[zag-js] No computed object found on machine');
+		const fn = machine.computed[key];
+		return fn({
+			context: ctx as any,
+			event: getEvent(),
+			prop,
+			refs,
+			scope,
+			computed: computed as any,
+		});
+	};
+
+	const state = useBindable(
+		() => ({
+			defaultValue: resolveStateValue(machine, machine.initialState({ prop })),
+			onChange(nextState, previousState) {
+				const { exiting, entering } = getExitEnterStates(
+					machine,
+					previousState,
+					nextState,
+					transitionRef.current?.reenter,
+				);
+
+				exiting.forEach((item) => {
+					effects.current.get(item.path)?.();
+					effects.current.delete(item.path);
+				});
+				exiting.forEach((item) => action(item.state?.exit));
+				action(transitionRef.current?.actions);
+
+				entering.forEach((item) => {
+					const cleanup = effect(item.state?.effects);
+					if (!cleanup) return;
+					const existing = effects.current.get(item.path);
+					effects.current.set(item.path, existing ? callAll(existing, cleanup) : cleanup);
+				});
+
+				if (previousState === INIT_STATE) {
+					action(machine.entry);
+					const cleanup = effect(machine.effects);
+					if (cleanup) {
+						const existing = effects.current.get(INIT_STATE);
+						effects.current.set(INIT_STATE, existing ? callAll(existing, cleanup) : cleanup);
+					}
+				}
+
+				entering.forEach((item) => action(item.state?.entry));
+			},
+		}),
+		subSlot(slot, 'state'),
+	);
+
+	const hydratedStateRef = useRef<string | undefined>(undefined, subSlot(slot, 'hydrated-state'));
+	const statusRef = useRef(MachineStatus.NotStarted, subSlot(slot, 'status'));
+
+	useSafeLayoutEffect(
+		() => {
+			let cancelled = false;
+			let didStart = false;
+			queueMicrotask(() => {
+				if (cancelled) return;
+				const started = statusRef.current === MachineStatus.Started;
+				didStart = true;
+				statusRef.current = MachineStatus.Started;
+				debug(started ? 'rehydrating...' : 'initializing...');
+				const initialState = hydratedStateRef.current ?? state.initial!;
+				state.invoke(initialState, started ? state.get() : INIT_STATE);
+			});
+
+			const functions = effects.current;
+			return () => {
+				cancelled = true;
+				const currentState = getCurrentState();
+				debug('unmounting...');
+				hydratedStateRef.current = currentState;
+				statusRef.current = MachineStatus.Stopped;
+				functions.forEach((fn) => fn?.());
+				effects.current = new Map();
+				transitionRef.current = null;
+
+				queueMicrotask(() => {
+					if (didStart) action(machine.exit);
+					statusRef.current = MachineStatus.Stopped;
+				});
+			};
+		},
+		[],
+		subSlot(slot, 'lifecycle'),
+	);
+
+	const getCurrentState = () =>
+		'ref' in state ? state.ref.current : (state as Bindable<string>).get();
+
+	const send = (event: any) => {
+		queueMicrotask(() => {
+			if (statusRef.current !== MachineStatus.Started) return;
+
+			previousEventRef.current = eventRef.current;
+			eventRef.current = event;
+			const currentState = getCurrentState();
+			const { transitions, source } = findTransition(machine, currentState, event.type as string);
+			const transition = choose(transitions);
+			if (!transition) return;
+
+			transitionRef.current = transition;
+			const target = resolveStateValue(machine, transition.target ?? currentState, source);
+			debug('transition', event.type, transition.target || currentState, `(${transition.actions})`);
+
+			if (target !== currentState) {
+				flushSync(() => state.set(target));
+			} else if (transition.reenter) {
+				state.invoke(currentState, currentState);
+			} else {
+				action(transition.actions ?? []);
+			}
+		});
+	};
+
+	machine.watch?.(getParams());
+
+	return {
+		state: getState(),
+		send,
+		context: ctx,
+		prop,
+		scope,
+		refs,
+		computed,
+		event: getEvent(),
+		getStatus: () => statusRef.current,
+	} as Service<T>;
+}
+
+function useLiveRef<T>(value: T, slot: symbol) {
+	const ref = useRef(value, slot);
+	ref.current = value;
+	return ref;
+}
+
+function useProp<T>(value: T, slot: symbol) {
+	const ref = useLiveRef(value, slot);
+	return function get<K extends keyof T>(key: K): T[K] {
+		return ref.current[key];
+	};
+}
+
+function flush(fn: VoidFunction) {
+	queueMicrotask(() => {
+		flushSync(() => fn());
+	});
+}

package/src/normalize-props.ts

@@ -0,0 +1,68 @@
+import { createNormalizer } from '@zag-js/types';
+import type { JSX } from 'octane/jsx-runtime';
+
+export type PropTypes = JSX.IntrinsicElements & {
+	element: JSX.IntrinsicElements['div'];
+	style: Exclude<JSX.IntrinsicElements['div']['style'], string | undefined>;
+};
+
+// Match Octane's text-entry contract (native-change-diagnostics): only these
+// input types treat React-style onChange as per-edit onInput. Everything in
+// NON_TEXT_INPUT_TYPES keeps native onChange; unknown types follow HTML's
+// invalid-value default and are treated as text.
+const TEXT_ENTRY_TYPES = new Set(['email', 'number', 'password', 'search', 'tel', 'text', 'url']);
+const NON_TEXT_INPUT_TYPES = new Set([
+	'button',
+	'checkbox',
+	'color',
+	'date',
+	'datetime-local',
+	'file',
+	'hidden',
+	'image',
+	'month',
+	'radio',
+	'range',
+	'reset',
+	'submit',
+	'time',
+	'week',
+]);
+
+function isTextHostElement(elementKey: string, props: Record<string, unknown>): boolean {
+	if (elementKey === 'textarea') return true;
+	if (elementKey !== 'input') return false;
+	const type = typeof props.type === 'string' ? props.type.toLowerCase() : 'text';
+	if (TEXT_ENTRY_TYPES.has(type)) return true;
+	if (NON_TEXT_INPUT_TYPES.has(type)) return false;
+	return true;
+}
+
+function rewriteTextHostOnChange(
+	elementKey: string,
+	value: Record<string, unknown>,
+): Record<string, unknown> {
+	if (!isTextHostElement(elementKey, value)) return value;
+	if (typeof value.onChange !== 'function' || value.onInput !== undefined) return value;
+	const { onChange, ...rest } = value;
+	return { ...rest, onInput: onChange };
+}
+
+type ZagNormalizeProps = ReturnType<typeof createNormalizer<PropTypes>>;
+
+function createOctaneNormalizer(): ZagNormalizeProps {
+	return new Proxy({} as ZagNormalizeProps, {
+		get(_target, key) {
+			if (key === 'style') {
+				return function styleProps(props: PropTypes['style']) {
+					return props;
+				};
+			}
+			return function normalizeElementProps(value: Record<string, unknown>) {
+				return rewriteTextHostOnChange(String(key), value);
+			};
+		},
+	});
+}
+
+export const normalizeProps = createOctaneNormalizer();

package/src/portal.ts

@@ -0,0 +1,49 @@
+import {
+	Children,
+	createElement,
+	createPortal,
+	Fragment,
+	isChildrenBlock,
+	useLayoutEffect,
+	useState,
+} from 'octane';
+import type { OctaneNode } from 'octane';
+import { subSlot } from './internal';
+
+export interface PortalProps {
+	disabled?: boolean | undefined;
+	container?: { current: HTMLElement | null } | undefined;
+	getRootNode?: (() => ShadowRoot | Document | Node) | undefined;
+	children?: OctaneNode;
+}
+
+const PORTAL_SLOT = Symbol.for('@octanejs/zag/Portal');
+
+export const Portal = (props: PortalProps) => {
+	const { children, container, disabled, getRootNode } = props;
+	const [mounted, setMounted] = useState(false, subSlot(PORTAL_SLOT, 'mounted'));
+
+	useLayoutEffect(
+		() => {
+			setMounted(true);
+		},
+		[],
+		subSlot(PORTAL_SLOT, 'mount-effect'),
+	);
+
+	if (!mounted || typeof window === 'undefined' || disabled) {
+		return createElement(Fragment, null, children);
+	}
+
+	const rootNode = getRootNode?.();
+	const doc =
+		rootNode?.nodeType === Node.DOCUMENT_NODE
+			? (rootNode as Document)
+			: (rootNode?.ownerDocument ?? document);
+	const mountNode = container?.current ?? doc.body;
+	if (isChildrenBlock(children)) {
+		return createPortal(children, mountNode);
+	}
+	const portals = Children.map(children, (child) => createPortal(child, mountNode));
+	return createElement(Fragment, null, portals);
+};

package/src/refs.ts

@@ -0,0 +1,15 @@
+import { useRef } from 'octane';
+
+import { subSlot } from './internal';
+
+export function useRefs<T>(refs: T, slot?: symbol) {
+	const ref = useRef(refs, subSlot(slot, 'refs'));
+	return {
+		get<K extends keyof T>(key: K): T[K] {
+			return ref.current[key];
+		},
+		set<K extends keyof T>(key: K, value: T[K]) {
+			ref.current[key] = value;
+		},
+	};
+}

package/src/track.ts

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from 'octane';
+
+import { subSlot } from './internal';
+
+export const useTrack = (deps: any[], effect: VoidFunction, slot?: symbol) => {
+	const render = useRef(false, subSlot(slot, 'render'));
+	const called = useRef(false, subSlot(slot, 'called'));
+
+	useEffect(
+		() => {
+			const run = render.current && called.current;
+			if (run) return effect();
+			called.current = true;
+		},
+		[
+			...(deps ?? []).map((dependency) =>
+				typeof dependency === 'function' ? dependency() : dependency,
+			),
+		],
+		subSlot(slot, 'tracked-effect'),
+	);
+
+	useEffect(
+		() => {
+			render.current = true;
+			return () => {
+				render.current = false;
+			};
+		},
+		[],
+		subSlot(slot, 'mount-effect'),
+	);
+};

package/src/use-layout-effect.ts

@@ -0,0 +1,4 @@
+import { useEffect, useLayoutEffect } from 'octane';
+
+export const useSafeLayoutEffect =
+	typeof globalThis.document !== 'undefined' ? useLayoutEffect : useEffect;