@octanejs/gsap 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway and Octane contributors
+
+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,56 @@
+# @octanejs/gsap
+
+GSAP lifecycle integration for Octane. It mirrors the official `@gsap/react`
+`useGSAP` contract while using compiler-selected Octane hook slots.
+
+```bash
+pnpm add @octanejs/gsap gsap
+```
+
+```tsrx
+import gsap from 'gsap';
+import { useGSAP } from '@octanejs/gsap';
+import { useRef } from 'octane';
+
+function AnimatedCard() @{
+	const scope = useRef<HTMLDivElement>(null);
+	const { contextSafe } = useGSAP(
+		() => {
+			gsap.from('.card', { y: 24, opacity: 0, stagger: 0.08 });
+		},
+		{ scope },
+	);
+
+	const pulse = contextSafe(() => {
+		gsap.to('.card', { scale: 1.05, yoyo: true, repeat: 1 });
+	});
+
+	<div ref={scope}>
+		<button onClick={pulse}>Pulse</button>
+		<div class="card">Scoped animation</div>
+	</div>
+}
+```
+
+## Contract
+
+`useGSAP` accepts the same callback, dependency-array, and config forms as
+`@gsap/react` 2.1.2. Config supports `scope`, `dependencies`, and
+`revertOnUpdate`. The returned `context` and `contextSafe` identities remain
+stable for the component lifetime, and GSAP context cleanup runs on dependency
+replacement and unmount.
+
+`useGSAP.register(gsapInstance)` selects a GSAP instance explicitly.
+`useGSAP.headless` is `true`, matching the upstream package contract.
+
+## SSR
+
+Server rendering returns stable context helpers but does not execute animation
+effects. Hydration activates the normal client lifecycle.
+
+## Licensing
+
+This adapter is independently authored and MIT licensed. GSAP is a peer
+dependency and is not copied or redistributed here. GSAP uses its own
+no-charge license; review the [GSAP licensing terms](https://gsap.com/licensing/)
+for your use case.

package/UPSTREAM.md

@@ -0,0 +1,64 @@
+# Upstream provenance
+
+`@octanejs/gsap` ports the React-facing adapter published as `@gsap/react@2.1.2`.
+
+| Field | Pin |
+| --- | --- |
+| Package | `@gsap/react` |
+| Version and supported range | `2.1.2` exactly |
+| Canonical tag | `greensock/react@2.1.2` |
+| Tag commit | `b7f44ca767eb93390f965d6f19679e2b77be7966` |
+| Framework-neutral peer/oracle | `gsap@3.15.0` (compatible with upstream's `^3.12.5` peer range) |
+
+## Source boundary and licensing
+
+The canonical tag contains one React-facing source module, `src/index.js`, its
+declaration file at `types/index.d.ts`, built artifacts, the README, and package
+metadata. The tag contains no tests, test configuration, fixtures, snapshots,
+or test scripts.
+
+The upstream package declares `SEE LICENSE AT https://gsap.com/standard-license`,
+and its source header says it is subject to the GSAP Standard License. It is
+therefore inspected at the immutable commit above but is not vendored or
+redistributed here. The Octane adapter is independently authored and MIT
+licensed; GSAP remains an external peer dependency.
+
+The Octane replacement mirrors the sole upstream source module at `src/index.ts`.
+`src/internal.ts` contains only Octane's compiler hook-slot adapter and has no
+upstream counterpart.
+
+## Export crosswalk
+
+| Upstream surface | Octane status | Evidence |
+| --- | --- | --- |
+| `useGSAP(callback?, dependenciesOrConfig?)` | Ported. Callback, positional dependency, and config signatures are supported. | `tests/use-gsap.test.ts`; `tests/differential/parity.test.ts`; `typetests/adapted/types.test-d.ts` |
+| Returned `context` | Ported with stable component-lifetime identity. | `tests/use-gsap.test.ts`; `tests/differential/parity.test.ts` |
+| Returned `contextSafe` | Ported with stable identity and GSAP context registration. | `tests/use-gsap.test.ts`; `tests/differential/parity.test.ts` |
+| Config `scope` | Ported for selector, element, and ref-like values. | `tests/_fixtures/app.tsrx`; `typetests/adapted/types.test-d.ts` |
+| Config `dependencies` | Ported, including upstream's distinction between an absent property and explicit `undefined` or `null`. | `tests/use-gsap.test.ts` |
+| Config `revertOnUpdate` | Ported. | `tests/use-gsap.test.ts`; `tests/differential/parity.test.ts` |
+| `useGSAP.register(core)` | Ported. | `tests/use-gsap.test.ts`; `typetests/adapted/types.test-d.ts` |
+| `useGSAP.headless === true` | Ported. | `tests/use-gsap.test.ts`; `typetests/adapted/types.test-d.ts` |
+
+There are no silent or open export gaps at this pin.
+
+## Test and type disposition
+
+Upstream `2.1.2` ships no runtime or type test suite in either the canonical tag
+or the published package metadata, so there is no pristine suite to run or adapt.
+Parity evidence is therefore repo-authored and registered in
+`audit/react-parity.json`:
+
+- `gsap-differential` — the same lifecycle fixture through Octane and published
+  `@gsap/react` 2.1.2 via the shared differential rig (required runtime oracle)
+- pristine/adapted type lanes under `typetests/{pristine,adapted}/`
+
+The ordinary `tests/use-gsap.test.ts` and SSR cases remain unpaired
+framework-contract tests in the general shards; they are not parity-owned.
+
+The upstream declaration contains a single `useGSAP` overload. Its accepted
+callback/config forms are covered one-for-one in the type lanes, with negative
+controls for an invalid callback and invalid scope. Static `register` and
+`headless` are present in runtime source but omitted from the upstream
+declaration; the Octane package intentionally types them because they are part
+of the published runtime contract.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@octanejs/gsap",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "GSAP lifecycle bindings for Octane — the useGSAP hook over the framework-agnostic GSAP core.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/gsap"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "UPSTREAM.md",
+    "status.json"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "gsap": "^3.12.5",
+    "octane": "0.1.32"
+  },
+  "devDependencies": {
+    "@gsap/react": "2.1.2",
+    "@tsrx/react": "^0.2.56",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.1",
+    "gsap": "3.15.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vitest": "^4.1.10",
+    "octane": "0.1.32"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project gsap --project gsap-ssr --project gsap-differential"
+  }
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+import gsap from 'gsap';
+import { useEffect, useLayoutEffect, useRef } from 'octane';
+import { splitSlot, subSlot } from './internal.ts';
+
+type AnyFunction = (...args: any[]) => any;
+export type ContextSafeFunction = <T extends AnyFunction>(func: T) => T;
+export type ContextFunction = (
+	context: gsap.Context,
+	contextSafe: ContextSafeFunction,
+) => AnyFunction | unknown | void;
+
+interface RefLike<T> {
+	current: T | null;
+}
+
+export interface UseGSAPConfig {
+	scope?: RefLike<Element> | Element | string;
+	dependencies?: unknown[];
+	revertOnUpdate?: boolean;
+}
+
+export interface UseGSAPReturn {
+	context: gsap.Context;
+	contextSafe: ContextSafeFunction;
+}
+
+interface UseGSAP {
+	(callback?: ContextFunction, dependencies?: unknown[]): UseGSAPReturn;
+	(callback?: ContextFunction, config?: UseGSAPConfig): UseGSAPReturn;
+	(config?: UseGSAPConfig): UseGSAPReturn;
+	register(core: typeof gsap): void;
+	headless: true;
+}
+
+const useIsomorphicLayoutEffect = typeof document !== 'undefined' ? useLayoutEffect : useEffect;
+const emptyDependencies: unknown[] = [];
+const defaultConfig: UseGSAPConfig = {};
+let activeGSAP = gsap;
+
+function isConfig(value: unknown): value is UseGSAPConfig {
+	return value !== null && !Array.isArray(value) && typeof value === 'object';
+}
+
+const useGSAPImpl = (...rawArgs: unknown[]): UseGSAPReturn => {
+	const [args, slot] = splitSlot(rawArgs);
+	let callback = args[0] as ContextFunction | UseGSAPConfig | undefined;
+	let dependencies: unknown[] | UseGSAPConfig | null | undefined = (
+		args[1] === undefined ? emptyDependencies : args[1]
+	) as unknown[] | UseGSAPConfig | null;
+	let config = defaultConfig;
+
+	if (isConfig(callback)) {
+		config = callback;
+		callback = undefined;
+		dependencies = 'dependencies' in config ? config.dependencies : emptyDependencies;
+	} else if (isConfig(dependencies)) {
+		config = dependencies;
+		dependencies = 'dependencies' in config ? config.dependencies : emptyDependencies;
+	}
+
+	if (callback !== undefined && typeof callback !== 'function') {
+		console.warn('First parameter must be a function or config object');
+	}
+
+	const { scope, revertOnUpdate } = config;
+	const mounted = useRef(false, subSlot(slot, 'mounted'));
+	const context = useRef(
+		activeGSAP.context(() => {}, scope),
+		subSlot(slot, 'context'),
+	);
+	const contextSafe = useRef<ContextSafeFunction>(
+		(func) =>
+			(context.current.add as unknown as (name: null, callback: AnyFunction) => AnyFunction)(
+				null,
+				func,
+			) as typeof func,
+		subSlot(slot, 'context-safe'),
+	);
+	const resolvedDependencies = dependencies as unknown[] | null | undefined;
+	const deferCleanup =
+		resolvedDependencies != null && resolvedDependencies.length > 0 && revertOnUpdate !== true;
+
+	useIsomorphicLayoutEffect(
+		() => {
+			mounted.current = true;
+			return () => context.current.revert();
+		},
+		emptyDependencies,
+		subSlot(slot, 'mount-cleanup'),
+	);
+
+	useIsomorphicLayoutEffect(
+		() => {
+			if (typeof callback === 'function') context.current.add(callback, scope);
+			if (!deferCleanup || !mounted.current) {
+				return () => context.current.revert();
+			}
+		},
+		resolvedDependencies,
+		subSlot(slot, 'callback'),
+	);
+
+	return {
+		context: context.current,
+		contextSafe: contextSafe.current,
+	};
+};
+
+export const useGSAP = useGSAPImpl as UseGSAP;
+
+useGSAP.register = (core) => {
+	activeGSAP = core;
+};
+useGSAP.headless = true;

package/src/internal.ts

@@ -0,0 +1,24 @@
+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) bareSlotCache.set(tag, (bare = Symbol.for('@octanejs/gsap:' + tag)));
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let derived = byTag.get(tag);
+	if (derived === undefined) {
+		byTag.set(tag, (derived = Symbol.for((slot.description ?? '@octanejs/gsap') + ':' + tag)));
+	}
+	return derived;
+}
+
+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/status.json

@@ -0,0 +1,23 @@
+{
+  "upstream": {
+    "package": "@gsap/react",
+    "version": "2.1.2",
+    "source": "https://github.com/greensock/react/tree/2.1.2",
+    "tagCommit": "b7f44ca767eb93390f965d6f19679e2b77be7966",
+    "license": "GSAP Standard License"
+  },
+  "peer": {
+    "package": "gsap",
+    "version": "3.15.0",
+    "license": "GSAP Standard No Charge License"
+  },
+  "surface": "Full useGSAP hook contract: callback, dependency-array and config signatures; scoped contexts; contextSafe; revertOnUpdate; register; and headless.",
+  "divergences": [
+    "The adapter imports Octane hooks and uses compiler-selected manual hook slots instead of React hooks.",
+    "GSAP remains an external peer dependency and is not redistributed by this MIT-licensed adapter."
+  ],
+  "ssr": "Server rendering creates stable context helpers without running GSAP effects. Client hydration activates the standard lifecycle.",
+  "verified": "2026-08-02",
+  "supportedExports": ["useGSAP"],
+  "unsupported": []
+}