@octanejs/spring 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,53 @@
+# @octanejs/spring
+
+[React Spring](https://www.react-spring.dev/) for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+The package exposes the stable `@react-spring/web@10.1.2` surface at its root
+and Parallax from `@octanejs/spring/parallax`. It reuses React Spring's
+`rafz` scheduler and ports the framework-bound controller, hook, animated-host,
+observer, and component layers to Octane without a React runtime dependency.
+
+```tsx
+import { animated, useSpring } from '@octanejs/spring';
+
+export function Card(props) @{
+  const [styles, api] = useSpring(
+    () => ({
+      from: { opacity: 0, y: 16 },
+      to: { opacity: 1, y: 0 },
+    }),
+    [],
+  );
+
+  <animated.div style={styles} onClick={() => api.start({ to: { y: 8 } })}>
+    {props.children}
+  </animated.div>
+}
+```
+
+## Upstream
+
+The behavioral and type baseline is React Spring `v10.1.2` at commit
+`59b1e5306402d3039120e2da464b66e10b1a1aa1`. Adapted source provenance is
+recorded in [`UPSTREAM.md`](./UPSTREAM.md).
+
+## Status
+
+Supported scope, divergences, and verification are recorded in
+[`status.json`](./status.json) and the generated repository compatibility
+tables.
+
+## Verification
+
+```sh
+pnpm --dir packages/spring upstream:verify
+pnpm --dir packages/spring typecheck
+pnpm exec vitest run --project spring --project spring-ssr
+pnpm exec vitest run --project spring-browser
+pnpm packages:pack:check
+```
+
+The browser lane builds and exercises the central playground in development
+and production. The repository packed-source canary installs the root and
+Parallax subpath from their tarball alongside a packed Octane runtime.

package/UPSTREAM.md

@@ -0,0 +1,103 @@
+# React Spring upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Packages | `@react-spring/web@10.1.2`, `@react-spring/parallax@10.1.2` |
+| Supported upstream range | exactly `10.1.2` |
+| Canonical repository | `https://github.com/pmndrs/react-spring.git` |
+| Tag and commit | `v10.1.2`, `59b1e5306402d3039120e2da464b66e10b1a1aa1` |
+| Runtime oracle | React `19.2.7`, ReactDOM `19.2.7` |
+| Framework-neutral dependency | `@react-spring/rafz@10.1.2` |
+| License | MIT, © Paul Henschel and React Spring contributors |
+| Vendored inventory | 167 files; `SHA256SUMS` digest `10e6fb1c530efe9409d9f3184488bc7d57bcbae3c92ee97553859e4cd0eda993` |
+
+The npm artifacts contain compiled JavaScript, declarations, README files, and
+licenses, but not the canonical TypeScript source or test suites. The
+byte-exact source, runtime tests, type tests, package manifests, web target,
+Parallax demo, and licenses therefore come from the canonical repository at the
+tag commit. They live under `upstream/`, retain the repository layout, are
+excluded from the published `files`, and are locked file-by-file by
+`upstream/SHA256SUMS`.
+
+Run `pnpm --dir packages/spring upstream:verify` to detect a modified,
+missing, renamed, or unexpected vendored file. The verifier itself has negative
+controls in `scripts/react-parity/react-spring-upstream-lib.test.mjs`.
+
+The reusable runtime boundary is deliberately narrow: the port consumes the
+exact framework-neutral `@react-spring/rafz` package. Source under upstream
+`packages/shared`, `packages/animated`, `packages/core`, `targets/web`, and
+`packages/parallax` contains React hooks, contexts, JSX, element types, or
+`forwardRef`, so those observable contracts are adapted to Octane. The
+`packages/types` tree is the type oracle. Adapted source cites the pinned
+release, while the machine-checked test disposition inventory ties every
+upstream test file to its executable Octane evidence.
+
+## Runtime export crosswalk
+
+`tests/conformance/exports.test.ts` enforces this inventory in both directions.
+“Ported” means the public value exists in the Octane namespace; behavioral and
+type evidence is tracked separately and an export is not a release-ready claim
+until its cited lanes pass.
+
+| Upstream export | Disposition | Evidence |
+|---|---|---|
+| `Any` | Ported type sentinel | export inventory and `typetests/public-api.test-d.tsx` |
+| `BailSignal` | Ported interruption signal | export inventory and lifecycle conformance |
+| `Controller` | Ported | engine, controller, and lifecycle conformance |
+| `FrameValue` | Ported public base | animated graph and host conformance |
+| `Globals` | Ported global configuration | reduced-motion and browser conformance |
+| `Interpolation` | Ported | interpolation and animated graph conformance |
+| `Spring` | Ported to Octane render-prop component | `tests/conformance/components.test.ts` |
+| `SpringContext` | Ported to Octane context component | `tests/conformance/components.test.ts` |
+| `SpringRef` | Ported | `tests/conformance/hooks.test.ts` |
+| `SpringValue` | Ported | engine, advanced-engine, lifecycle, and public type lanes |
+| `Trail` | Ported to keyed Octane renderables | `tests/conformance/components.test.ts` |
+| `Transition` | Ported to keyed Octane renderables | `tests/conformance/components.test.ts` |
+| `a` | Ported alias | export inventory and animated-host fixture |
+| `animated` | Ported to Octane host components | `tests/conformance/prerequisite-seams.test.ts` |
+| `config` | Ported | `tests/conformance/engine.test.ts` |
+| `createInterpolator` | Ported | interpolation conformance |
+| `easings` | Ported | advanced-engine and export conformance |
+| `inferTo` | Ported | export and public type conformance |
+| `interpolate` | Ported alias | `tests/conformance/engine.test.ts` |
+| `to` | Ported | `tests/conformance/engine.test.ts` |
+| `update` | Reused from exact `rafz` | controlled frame-loop conformance |
+| `useChain` | Ported to Octane hooks | `tests/conformance/hooks.test.ts` |
+| `useInView` | Ported to native observer lifecycle | `tests/conformance/browser-hooks.test.ts` |
+| `useIsomorphicLayoutEffect` | Ported to Octane layout effect | SSR, hydration, and browser-hook lanes |
+| `useReducedMotion` | Ported to native media-query lifecycle | `tests/conformance/browser-hooks.test.ts` |
+| `useResize` | Ported to native observer lifecycle | `tests/conformance/browser-hooks.test.ts` |
+| `useScroll` | Ported to native scroll lifecycle | `tests/conformance/browser-hooks.test.ts` |
+| `useSpring` | Ported to Octane hooks | `tests/conformance/hooks.test.ts` |
+| `useSpringRef` | Ported to Octane hooks | `tests/conformance/hooks.test.ts` |
+| `useSpringValue` | Ported to Octane hooks | `tests/conformance/hooks.test.ts` |
+| `useSprings` | Ported to Octane hooks | `tests/conformance/hooks.test.ts` |
+| `useTrail` | Ported to Octane hooks | `tests/conformance/hooks.test.ts` |
+| `useTransition` | Ported with binding-owned keyed retention | `tests/conformance/transitions.test.ts` |
+| `Parallax` | Ported at `./parallax` | `tests/conformance/parallax.test.ts` |
+| `ParallaxLayer` | Ported at `./parallax` | `tests/conformance/parallax.test.ts` |
+
+`useSpringContext` remains a private helper and is intentionally absent from
+the package namespace. Native, Three, Konva, Zdog, and the all-renderer
+`react-spring` meta-package are outside this web binding rather than missing web
+exports.
+
+## Upstream test-suite disposition
+
+The pinned boundary contains the executable unit/type-test files under
+`packages/{animated,core,rafz,shared}` and `targets/web`, plus setup and the
+Parallax demo. The vendored files are the authoritative work list.
+
+Runtime identities are inventoried by the pristine Vitest lane and mapped
+one-for-one in `audit/upstream-case-dispositions.json` to an adapted identity,
+a reused-dependency note, or an explicit `awaiting-adaptation` reason. Negative
+controls reject missing/extra pristine identities, adapted title drift, and
+skipped adapted cases. Repo-authored conformance/hydration/browser suites stay
+in the ordinary shards and are not React-parity ownership.
+
+Type programs under `*.test-d.ts` / `*.test-d.tsx` run pristine via
+`audit/type-probes/tsconfig.pristine-upstream.json`. One-for-one adapted type
+counterparts live under `typetests/upstream/` and still require Octane public
+type-surface work before the adapted-types lane is green.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@octanejs/spring",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "React Spring web bindings for Octane.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/spring"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./parallax": "./src/parallax.ts"
+  },
+  "dependencies": {
+    "@react-spring/rafz": "10.1.2"
+  },
+  "peerDependencies": {
+    "octane": "0.1.35"
+  },
+  "devDependencies": {
+    "@react-spring/animated": "10.1.2",
+    "@react-spring/core": "10.1.2",
+    "@react-spring/mock-raf": "1.1.1",
+    "@react-spring/parallax": "10.1.2",
+    "@react-spring/shared": "10.1.2",
+    "@react-spring/types": "10.1.2",
+    "@react-spring/web": "^10.1.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser-playwright": "4.1.10",
+    "flush-microtasks": "1.0.1",
+    "playwright": "^1.61.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "spec.ts": "^1.1.3",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "vitest-browser-react": "^2.2.0",
+    "octane": "0.1.35"
+  },
+  "scripts": {
+    "test": "pnpm upstream:verify && vitest run --project spring",
+    "upstream:verify": "node ../../scripts/react-parity/react-spring-upstream.mjs",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsgo --noEmit -p typetests/tsconfig.json"
+  }
+}

package/src/animated/Animated.ts

@@ -0,0 +1,24 @@
+// React-free graph node ported from react-spring v10.1.2 packages/animated/src/Animated.ts.
+export abstract class Animated {
+	getPayload(): AnimatedValue<any>[] | undefined {
+		return undefined;
+	}
+	abstract getValue(): unknown;
+}
+
+export class AnimatedValue<T = number> extends Animated {
+	constructor(private value: T) {
+		super();
+	}
+	getValue(): T {
+		return this.value;
+	}
+	setValue(value: T): boolean {
+		if (Object.is(value, this.value)) return false;
+		this.value = value;
+		return true;
+	}
+	getPayload(): AnimatedValue<T>[] {
+		return [this];
+	}
+}

package/src/animated/AnimatedArray.ts

@@ -0,0 +1,26 @@
+// Ported from react-spring v10.1.2 packages/animated/src/AnimatedArray.ts.
+import { Animated, AnimatedValue } from './Animated';
+
+export class AnimatedArray<T = unknown> extends Animated {
+	readonly source: Array<AnimatedValue<T>>;
+	constructor(source: readonly T[]) {
+		super();
+		this.source = source.map((value) => new AnimatedValue(value));
+	}
+	getValue(): T[] {
+		return this.source.map((value) => value.getValue());
+	}
+	setValue(values: readonly T[]): boolean {
+		let changed = values.length !== this.source.length;
+		while (this.source.length < values.length)
+			this.source.push(new AnimatedValue(values[this.source.length]!));
+		this.source.length = values.length;
+		values.forEach((value, index) => {
+			changed = this.source[index]!.setValue(value) || changed;
+		});
+		return changed;
+	}
+	getPayload(): AnimatedValue<T>[] {
+		return this.source;
+	}
+}

package/src/animated/index.ts

@@ -0,0 +1,3 @@
+// React-free exports ported from @react-spring/animated v10.1.2.
+export * from './Animated';
+export * from './AnimatedArray';

package/src/browser.ts

@@ -0,0 +1,246 @@
+// Behavioral port of React Spring v10.1.2 browser hooks.
+import { useLayoutEffect, useState } from 'octane';
+import { SpringValue, type ControllerUpdate } from './engine';
+import { Globals } from './shared/globals';
+
+type ElementRef<T> = { current: T | null };
+
+export const useIsomorphicLayoutEffect = useLayoutEffect;
+const browserSubCache = new Map<symbol, Map<string, symbol>>();
+
+function browserSub(slot: symbol | undefined, tag: string): symbol | undefined {
+	if (slot === undefined) return undefined;
+	let tags = browserSubCache.get(slot);
+	if (tags === undefined) browserSubCache.set(slot, (tags = new Map()));
+	let value = tags.get(tag);
+	if (value === undefined) {
+		value = Symbol.for(`${slot.description ?? 'react-spring-browser'}:${tag}`);
+		tags.set(tag, value);
+	}
+	return value;
+}
+
+function browserSlot(args: any[]): symbol | undefined {
+	const tail = args[args.length - 1];
+	return typeof tail === 'symbol' ? tail : undefined;
+}
+
+function readScroll(target: Window | HTMLElement) {
+	const element = target instanceof Window ? document.documentElement : target;
+	const x = target instanceof Window ? target.scrollX : target.scrollLeft;
+	const y = target instanceof Window ? target.scrollY : target.scrollTop;
+	const width =
+		target instanceof Window
+			? element.scrollWidth - target.innerWidth
+			: element.scrollWidth - element.clientWidth;
+	const height =
+		target instanceof Window
+			? element.scrollHeight - target.innerHeight
+			: element.scrollHeight - element.clientHeight;
+	return {
+		scrollX: x,
+		scrollY: y,
+		scrollXProgress: width > 0 ? x / width : 0,
+		scrollYProgress: height > 0 ? y / height : 0,
+	};
+}
+
+export function useScroll(
+	optionsOrSlot: (ControllerUpdate<any> & { container?: ElementRef<HTMLElement> }) | symbol = {},
+	...args: any[]
+) {
+	const slot = typeof optionsOrSlot === 'symbol' ? optionsOrSlot : browserSlot(args);
+	const options = typeof optionsOrSlot === 'symbol' ? {} : optionsOrSlot;
+	const [values] = useState(
+		() => ({
+			scrollX: new SpringValue(0),
+			scrollY: new SpringValue(0),
+			scrollXProgress: new SpringValue(0),
+			scrollYProgress: new SpringValue(0),
+		}),
+		browserSub(slot, 'scroll-values'),
+	);
+	useLayoutEffect(
+		() => {
+			if (typeof window === 'undefined') return;
+			const target = options.container?.current ?? window;
+			const update = () => {
+				const next = readScroll(target);
+				for (const key of Object.keys(next) as Array<keyof typeof next>) {
+					void values[key].start({
+						to: next[key],
+						config: typeof options.config === 'function' ? options.config(key) : options.config,
+						immediate:
+							typeof options.immediate === 'function' ? options.immediate(key) : options.immediate,
+					});
+				}
+			};
+			update();
+			target.addEventListener('scroll', update, { passive: true });
+			return () => {
+				target.removeEventListener('scroll', update);
+				Object.values(values).forEach((value) => value.stop(true));
+			};
+		},
+		[options.container?.current],
+		browserSub(slot, 'scroll-effect'),
+	);
+	return values;
+}
+
+export function useResize(
+	optionsOrSlot: (ControllerUpdate<any> & { container?: ElementRef<HTMLElement> }) | symbol = {},
+	...args: any[]
+) {
+	const slot = typeof optionsOrSlot === 'symbol' ? optionsOrSlot : browserSlot(args);
+	const options = typeof optionsOrSlot === 'symbol' ? {} : optionsOrSlot;
+	const [values] = useState(
+		() => ({
+			width: new SpringValue(0),
+			height: new SpringValue(0),
+		}),
+		browserSub(slot, 'resize-values'),
+	);
+	useLayoutEffect(
+		() => {
+			if (typeof window === 'undefined') return;
+			const element = options.container?.current;
+			const update = (width: number, height: number) => {
+				for (const [key, value] of [
+					['width', width],
+					['height', height],
+				] as const) {
+					void values[key].start({
+						to: value,
+						config: typeof options.config === 'function' ? options.config(key) : options.config,
+						immediate:
+							typeof options.immediate === 'function' ? options.immediate(key) : options.immediate,
+					});
+				}
+			};
+			const stop = () => {
+				values.width.stop(true);
+				values.height.stop(true);
+			};
+			if (element === undefined || element === null) {
+				const onResize = () => update(window.innerWidth, window.innerHeight);
+				onResize();
+				window.addEventListener('resize', onResize);
+				return () => {
+					window.removeEventListener('resize', onResize);
+					stop();
+				};
+			}
+			const rect = element.getBoundingClientRect();
+			update(rect.width, rect.height);
+			if (typeof ResizeObserver === 'undefined') return stop;
+			const observer = new ResizeObserver(([entry]) => {
+				if (entry !== undefined) update(entry.contentRect.width, entry.contentRect.height);
+			});
+			observer.observe(element);
+			return () => {
+				observer.disconnect();
+				stop();
+			};
+		},
+		[options.container?.current],
+		browserSub(slot, 'resize-effect'),
+	);
+	return values;
+}
+
+export interface InViewOptions extends Omit<IntersectionObserverInit, 'root' | 'threshold'> {
+	root?: ElementRef<HTMLElement>;
+	once?: boolean;
+	amount?: 'any' | 'all' | number | number[];
+}
+
+function createInViewRef(setTarget: (target: Element | null) => void): ElementRef<Element> {
+	const state = { value: null as Element | null };
+	return {
+		get current() {
+			return state.value;
+		},
+		set current(next) {
+			if (state.value !== next) {
+				state.value = next;
+				setTarget(next);
+			}
+		},
+	};
+}
+
+export function useInView(
+	optionsOrSlot: InViewOptions | symbol = {},
+	...args: any[]
+): [ElementRef<Element>, boolean] {
+	const slot = typeof optionsOrSlot === 'symbol' ? optionsOrSlot : browserSlot(args);
+	const options = typeof optionsOrSlot === 'symbol' ? {} : optionsOrSlot;
+	const [target, setTarget] = useState<Element | null>(null, browserSub(slot, 'in-view-target'));
+	const [ref] = useState<ElementRef<Element>>(
+		function () {
+			return createInViewRef(setTarget);
+		},
+		browserSub(slot, 'in-view-ref'),
+	);
+	const [inView, setInView] = useState(false, browserSub(slot, 'in-view-value'));
+	useLayoutEffect(
+		function () {
+			if (
+				typeof IntersectionObserver === 'undefined' ||
+				target === null ||
+				(options.once && inView)
+			) {
+				return;
+			}
+			const { amount = 'any', once, root, ...observerOptions } = options;
+			const threshold = amount === 'any' ? 0 : amount === 'all' ? 1 : amount;
+			const observer = new IntersectionObserver(
+				function ([entry]) {
+					if (entry === undefined) return;
+					setInView(entry.isIntersecting);
+					if (entry.isIntersecting && once) observer.disconnect();
+				},
+				{ ...observerOptions, root: root?.current ?? null, threshold },
+			);
+			observer.observe(target);
+			return function () {
+				observer.disconnect();
+			};
+		},
+		[target, options.root?.current, options.once, options.amount, options.rootMargin],
+		browserSub(slot, 'in-view-effect'),
+	);
+	return [ref, inView];
+}
+
+export function useReducedMotion(...args: any[]): boolean | null {
+	const slot = browserSlot(args);
+	const [reduced, setReduced] = useState<boolean | null>(
+		() =>
+			typeof window === 'undefined' || typeof window.matchMedia !== 'function'
+				? null
+				: window.matchMedia('(prefers-reduced-motion)').matches,
+		browserSub(slot, 'reduced-value'),
+	);
+	useLayoutEffect(
+		() => {
+			if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+			const query = window.matchMedia('(prefers-reduced-motion)');
+			const update = () => {
+				setReduced(query.matches);
+				Globals.assign({ skipAnimation: query.matches });
+			};
+			update();
+			if (query.addEventListener) query.addEventListener('change', update);
+			else query.addListener(update);
+			return () => {
+				if (query.removeEventListener) query.removeEventListener('change', update);
+				else query.removeListener(update);
+			};
+		},
+		[],
+		browserSub(slot, 'reduced-effect'),
+	);
+	return reduced;
+}

package/src/components.tsrx

@@ -0,0 +1,60 @@
+import { createElement, Fragment, isChildrenBlock } from 'octane';
+import {
+	SpringContext as SpringContextObject,
+	type SpringContextValue,
+	useSpringContext,
+} from './context';
+import { useSpring, useTrail, useTransition } from './hooks';
+
+function itemKey(item: any, index: number): string | number {
+	return item?.key ?? item?.id ??
+		(typeof item === 'string' || typeof item === 'number' ? item : index);
+}
+
+function keyed(value: unknown, key: string | number): unknown {
+	return createElement(Fragment, { key }, value);
+}
+
+export function SpringContext(props: SpringContextValue & { children?: unknown }) @{
+	const { children, ...value } = props;
+	const inherited = useSpringContext();
+	<SpringContextObject value={{ ...inherited, ...value }}>{children}</SpringContextObject>
+}
+
+export function Spring(props: Record<string, unknown> & { children?: unknown }) @{
+	const { children, ...update } = props;
+	const styles = useSpring(update);
+	<>
+		{typeof children === 'function' && !isChildrenBlock(children) ? children(styles) : children}
+	</>
+}
+
+export function Trail(props: any) @{
+	const { children, items = [], ...update } = props;
+	const styles = useTrail(items.length, update);
+	<>
+		{typeof children === 'function' && !isChildrenBlock(children)
+			? items.map(
+					(item: any, index: number) => keyed(
+						children(item, index)(styles[index]),
+						itemKey(item, index),
+					),
+				)
+			: children}
+	</>
+}
+
+export function Transition(props: any) @{
+	const { children, items = [], ...update } = props;
+	const transitions = useTransition(items, update);
+	<>
+		{typeof children === 'function' && !isChildrenBlock(children)
+			? transitions(
+					(styles: any, item: any, transition: any, index: number) => keyed(
+						children(item, index)(styles),
+						transition.key,
+					),
+				)
+			: children}
+	</>
+}

package/src/components.tsrx.d.ts

@@ -0,0 +1,33 @@
+import type { SpringContextValue } from './context';
+import type { UseTransitionProps } from './hooks';
+import type { SpringValues } from './types/objects';
+import type { ControllerUpdate, Lookup } from './types/index';
+
+export type TrailProps<Item = any, State extends Lookup = Lookup> = ControllerUpdate<State> & {
+	items?: Item[];
+	children?:
+		((item: Item, index: number) => (styles: SpringValues<State> | undefined) => unknown) | unknown;
+};
+
+export type TransitionProps<Item = any, State extends Lookup = Lookup> = UseTransitionProps<
+	Item,
+	State
+> & {
+	items?: Item | Item[];
+	children?: ((item: Item, index: number) => (styles: SpringValues<State>) => unknown) | unknown;
+};
+
+export declare function SpringContext(
+	props: SpringContextValue & { children?: unknown },
+	scope?: unknown,
+): void;
+
+/** Implementation export; public typed overloads live in `spring-component.ts`. */
+export declare function Spring(props: Record<string, unknown> & { children?: unknown }): unknown;
+
+export declare function Trail<Item, State extends Lookup = Lookup>(
+	props: TrailProps<Item, State>,
+): void;
+export declare function Transition<Item, State extends Lookup = Lookup>(
+	props: TransitionProps<Item, State>,
+): void;

package/src/context.ts

@@ -0,0 +1,13 @@
+import { createContext, useContext } from 'octane';
+import type { ControllerUpdate } from './engine';
+
+export type SpringContextValue = Pick<
+	ControllerUpdate<Record<string, any>>,
+	'cancel' | 'config' | 'immediate' | 'pause'
+>;
+
+export const SpringContext = createContext<SpringContextValue>({});
+
+export function useSpringContext(): SpringContextValue {
+	return useContext(SpringContext);
+}