@octanejs/animejs 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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,59 @@
+# @octanejs/animejs
+
+[Anime.js](https://animejs.com) for [Octane](https://github.com/octanejs/octane).
+The package re-exports Anime.js and adds an Octane lifecycle hook for scoped DOM
+animations.
+
+The exact upstream pin, supported entry points, explicit subpath gaps, and test
+dispositions are recorded in [`UPSTREAM.md`](./UPSTREAM.md).
+
+```tsx
+import { animate, useAnimeScope } from '@octanejs/animejs';
+
+export function Logo() @{
+  const animation = useAnimeScope(() => {
+    animate('.dot', {
+      x: 160,
+      rotate: 360,
+      alternate: true,
+      loop: true,
+    });
+  }, []);
+
+  <div ref={animation.root}>
+    <div class="dot" />
+    <button onClick={() => animation.scope.current?.refresh()}>Restart</button>
+  </div>
+}
+```
+
+`useAnimeScope(setup, dependencies?)` returns stable `root` and `scope` refs.
+The scope is created after the root mounts, recreated when the dependency list
+changes, and reverted during cleanup. Effects do not run during server
+rendering.
+
+## Three.js
+
+Import the adapter subpath once before animating raw Three objects:
+
+```ts
+import { animate } from '@octanejs/animejs';
+import '@octanejs/animejs/adapters/three';
+
+animate(mesh, { x: 2, rotateY: 180 });
+```
+
+The subpath is the official Anime.js adapter, passed through unchanged.
+`@octanejs/three` exposes the real Three object through refs, so no translation
+layer is needed.
+
+Anime.js owns the object mutation; `@octanejs/three` owns rendering. An
+`always` frame loop needs no bridge. With `frameloop="demand"`, call the
+Three root's `invalidate()` from Anime.js `onRender`. With
+`frameloop="never"`, advance the Three root explicitly.
+
+## Status
+
+Current scope and verification evidence 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,77 @@
+# Anime.js upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Package | `animejs` |
+| Version | `4.5.0` |
+| Canonical tag | `v4.5.0` |
+| Canonical tag commit | `2c9cf8ea00329f6768c7d7902252ed977d75ce42` |
+| Supported upstream range | exactly `4.5.0` |
+| License | MIT, © Julian Garnier |
+
+Anime.js is framework-neutral. This package depends on the published release and
+re-exports its runtime and declarations instead of copying or modifying the
+animation engine. The npm artifact contains compiled `dist/` modules and types;
+the canonical tagged repository additionally contains source, browser suites,
+playgrounds, examples, and build configuration. Because the binding reuses the
+published core unchanged, those sources are not vendored or shipped here.
+
+## Public entry-point crosswalk
+
+| Upstream entry point | Octane disposition | Evidence |
+|---|---|---|
+| `animejs` | Reused unchanged and re-exported from the package root; `useAnimeScope` is the sole additional runtime export | `tests/exports.test.ts`, `tests/types/public-api.test-d.ts` |
+| `animejs/adapters/three` | Reused unchanged at `@octanejs/animejs/adapters/three` | `tests/exports.test.ts`, `tests/three-adapter.test.ts` |
+| `animejs/package.json` | Not re-exported; consumers may inspect the direct dependency when needed | package manifest |
+| `animejs/timer` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/animation` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/timeline` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/animatable` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/draggable` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/scope` | Explicit gap; the upstream scope API is available through the root and complemented by `useAnimeScope` | `tests/scope.test.ts` |
+| `animejs/engine` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/events` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/layout` | Explicit gap; the same APIs remain available through the supported root export | root export inventory |
+| `animejs/easings` and its six nested entry points | Explicit gap; easings are available through the supported root export | root export inventory |
+| `animejs/utils` | Explicit gap; utilities are available through the supported root export | root export inventory |
+| `animejs/svg` | Explicit gap; SVG helpers are available through the supported root export | root export inventory |
+| `animejs/text` | Explicit gap; text helpers are available through the supported root export | root export inventory |
+| `animejs/waapi` | Explicit gap; WAAPI helpers are available through the supported root export | root export inventory |
+| `animejs/adapters` | Explicit gap; only the verified Three adapter receives an Octane subpath | adapter export inventory |
+
+`tests/exports.test.ts` compares the binding namespaces with the installed
+4.5.0 namespaces in both directions. Removing, renaming, or adding an upstream
+runtime export therefore fails the test. The TypeScript fixture compiles
+representative animation, timeline, scope, engine, utility, SVG/text, WAAPI,
+and Three adapter calls through the binding's declarations.
+
+## Upstream test-suite disposition
+
+The canonical tag contains 33 executable files under `tests/suites/`. The npm
+artifact does not publish them. The 32 browser suites exercise the unchanged
+Anime.js engine and are upstream-core evidence rather than Octane binding
+fixtures: `animatables`, `animations`, `build`, `callbacks`, `colors`,
+`controls`, `directions`, `draggables`, `eases`, `engine`,
+`function-based-values`, `keyframes`, `leaks`, `parameters`, `promises`,
+`scope`, `scroll`, `seconds`, `stagger`, `svg`, `targets`, `text`, `threejs`,
+`timelines`, `timings`, `transforms`, `tweens`, `types`, `units`, `utils`,
+`values`, and `waapi`. They are not adapted because the binding does not
+replace those modules; export identity tests prove it delegates to the same
+installed implementation.
+
+The remaining `node.test.js` suite is likewise an upstream-core environment
+suite and is not copied into the package. Octane-specific evidence is classified
+as follows:
+
+- `tests/exports.test.ts`: Octane-only package-boundary contract.
+- `tests/scope.test.ts`: Octane-only lifecycle, cleanup, selector isolation,
+  registered-method, completion, refresh, and error-restoration contract.
+- `tests/ssr.test.ts`: Octane-only SSR safety contract.
+- `tests/three-adapter.test.ts`: Octane integration contract for the unchanged
+  upstream adapter and real `@octanejs/three` objects.
+- `tests/types/public-api.test-d.ts`: Octane package-declaration contract.
+
+There is no React binding or React oracle in Anime.js 4.5.0, so React/Octane
+differential and adapted React type lanes are not applicable.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@octanejs/animejs",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./src/adapters/three.ts"
+  ],
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Anime.js bindings for Octane with scoped lifecycle cleanup and Three.js adapter support.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/animejs"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "UPSTREAM.md",
+    "status.json"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapters/three": "./src/adapters/three.ts"
+  },
+  "dependencies": {
+    "animejs": "4.5.0"
+  },
+  "peerDependencies": {
+    "@types/three": ">=0.156.0",
+    "three": ">=0.156.0",
+    "octane": "0.1.31"
+  },
+  "peerDependenciesMeta": {
+    "@types/three": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/three": "0.172.0",
+    "three": "0.172.0",
+    "vitest": "^4.1.10",
+    "@octanejs/three": "0.1.24",
+    "octane": "0.1.31"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --config vitest.config.js --project animejs --project animejs-ssr",
+    "typecheck": "tsrx-tsc --noEmit"
+  }
+}

package/src/adapters/three.ts

@@ -0,0 +1 @@
+export * from 'animejs/adapters/three';

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from 'animejs';
+export { useAnimeScope, type AnimeScopeSetup, type UseAnimeScopeResult } from './useAnimeScope';

package/src/internal.ts

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

package/src/useAnimeScope.ts

@@ -0,0 +1,56 @@
+import { createScope, type Scope } from 'animejs';
+import { useEffect, useRef, useState } from 'octane';
+import { splitSlot, subSlot } from './internal';
+
+export interface UseAnimeScopeResult<
+	RootElement extends HTMLElement | SVGElement = HTMLDivElement,
+> {
+	readonly root: { current: RootElement | null };
+	readonly scope: { current: Scope | null };
+}
+
+export type AnimeScopeSetup = (scope: Scope) => void | (() => void);
+
+export function useAnimeScope<RootElement extends HTMLElement | SVGElement = HTMLDivElement>(
+	...runtime: [setup: AnimeScopeSetup, dependencies?: readonly unknown[], slot?: symbol]
+): UseAnimeScopeResult<RootElement> {
+	const [args, slot] = splitSlot(runtime);
+	const [setup, dependencies = []] = args as [AnimeScopeSetup, dependencies?: readonly unknown[]];
+	const root = useRef<RootElement | null>(null, subSlot(slot, 'root'));
+	const scope = useRef<Scope | null>(null, subSlot(slot, 'scope'));
+	const [result] = useState<UseAnimeScopeResult<RootElement>>(
+		() => ({ root, scope }),
+		subSlot(slot, 'result'),
+	);
+
+	useEffect(
+		() => {
+			if (!root.current) return;
+
+			const nextScope = createScope({ root });
+			scope.current = nextScope;
+			let setupError: unknown;
+			nextScope.add((activeScope) => {
+				try {
+					return setup(activeScope ?? nextScope);
+				} catch (error) {
+					setupError = error;
+				}
+			});
+			if (setupError !== undefined) {
+				scope.current = null;
+				nextScope.revert();
+				throw setupError;
+			}
+
+			return () => {
+				if (scope.current === nextScope) scope.current = null;
+				nextScope.revert();
+			};
+		},
+		dependencies as unknown[],
+		subSlot(slot, 'effect'),
+	);
+
+	return result;
+}

package/status.json

@@ -0,0 +1,19 @@
+{
+  "upstream": {
+    "package": "animejs",
+    "version": "4.5.0",
+    "source": "https://github.com/juliangarnier/anime/tree/v4.5.0",
+    "license": "MIT"
+  },
+  "surface": "Anime.js is re-exported unchanged; `useAnimeScope` binds scoped DOM animation setup, refresh, dependency recreation, and cleanup to Octane, and `@octanejs/animejs/adapters/three` exposes Anime.js's official Three adapter.",
+  "divergences": [
+    "`useAnimeScope` is an Octane-native lifecycle helper; it is not an upstream Anime.js API.",
+    "Only the root and `adapters/three` entry points are re-exported; other Anime.js subpaths are explicit gaps whose APIs remain available from the supported root where upstream exposes them there.",
+    "The Three adapter mutates raw objects while `@octanejs/three` retains frame-loop ownership; demand and never loops require explicit invalidation or advancement."
+  ],
+  "ssr": "Supported. The hook returns inert refs during server rendering and creates no Anime.js scope until its client effect runs.",
+  "verified": "2026-07-30",
+  "notes": [
+    "Verified with real Anime.js scopes, dependency-driven cleanup, SSR rendering, the official adapter against an @octanejs/three-owned mesh, and a DOM plus demand-loop Three playground journey."
+  ]
+}