af-motion 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes for **Auto Flow Motion (`af-motion` / AF Motion)** leading into V1 Release Readiness (`1.0.0`) are documented below.
+
+---
+
+## [1.0.0] — V1 Release Candidate
+
+### Added
+- **Core Motion Engine (`af-motion`)**: Web Animations and shared `requestAnimationFrame` progress engine (`animate`, `animateProgress`), damped physical spring and inertia solvers (`animateSpring`, `animateInertia`), custom easing registry (`easings`, `registerEasing`, `getEasing`, `removeEasing`), multi-track timeline choreography (`createTimeline`), layered transform composition (`magnetic`, `tilt`, `parallax`), scroll triggers/observers (`reveal`, `stagger`, `inView`, `scrollProgress`, `scrollVelocity`, `scrollTrigger`), canvas backgrounds (`aurora`, `particleField`), and 33 built-in semantic color palettes.
+- **Optional React Bindings (`af-motion/react`)**: Framework-optional React integration providing hooks and components (`useAnimate`, `useInView`, `useMicrointeraction`, `useMotionAccessibility`, `Reveal`, `Interactive`, `AnimatedText`, `GlassSurface`) with Strict Mode and SSR compatibility.
+- **Capability Catalogue, Styles & Intelligence (`af-motion/catalogue`)**: 19 visual design styles (`visualStyleRegistry`), 5 Motion DNA personality profiles (`precise`, `playful`, `elegant`, `energetic`, `editorial-flow`), AI capability registry (`aiMotionRegistry`), offline deterministic Design-to-Motion and AI Scene Generation engines, motion quality validation/optimization (`validateMotionConfig`, `optimizeMotion`), multi-agent task planner & safe tool registry, and MCP server (`createAFMotionMCPServer`, `StdioTransport`, `InMemoryTransport`).
+- **Presets & Choreography (`af-motion/presets`)**: 39 standardized presets (`listPresets`, `getPreset`, `applyPreset`, `animatePreset`, `registerAnimationPreset`) and reusable choreography helpers.
+- **Developer CLI (`af-motion`)**: Terminal tooling (`init`, `doctor`, `validate`, `presets`, `info`, `example`) exposed via `bin/af-motion.js` and `bin/mcp-server.js`.
+- **Standalone Ecosystem Apps**: Internal interactive Studio (`studio/`), standalone interactive Documentation Hub (`docs/`), and standalone public Website (`website/`).
+- **Shared Safety & Path Containment Helpers**: `src/core/utils/safe-json.ts` (prototype-key-stripping JSON parsing, circular reference guards, JSX/attribute/CSS/comment escaping, error path redaction) and `src/cli/utils/safety.ts` (workspace-root path containment).
+
+### Security
+- Enforced workspace-root path containment (`resolveSafeWorkspacePath`) across CLI file writes (`init`, `example`, `presets --out`), blocked prototype-polluting CLI flags (`--__proto__`, `--constructor`, `--prototype`), validated `--template`/`--lang`/`--format` allowlists, and serialized preset literals in TypeScript exports.
+- Bounded MCP `StdioTransport` stdin buffer (`1 MB`), detached `stdin` listeners on `close()`, validated JSON-RPC `params` and tool arguments as plain objects, and stripped local OS filesystem paths from external MCP error messages.
+- Enforced approval boundaries (`onApprovalRequired` / `approvalGranted`), bounded workflow sizes (`MAX_WORKFLOW_TASKS = 100`, `MAX_TASK_RETRIES = 5`), real timeout cutoffs inside execution and retry loops, `64 KB` message bus payload limits, `1000`-message history bounds, and safe identifier sanitization in `SafeToolRegistry`.
+- Escaped JSX text, attributes, JS string literals, CSS values, and block comments in deterministic code generation; stripped `__proto__`, `constructor`, and `prototype` keys during JSON deserialization across 3D schemas, compositions, design systems, Motion DNA, choreographies, and visual style registries.
+
+### Fixed
+- Fixed per-frame `THREE.AmbientLight`, `DirectionalLight`, and `PointLight` reallocation/scene-graph memory leak in `createThreeRendererAdapter` (`src/3d/adapter.ts`) so existing lights are updated and excess lights removed cleanly.
+- Fixed WebGL cleanup lifecycle on `webglcontextlost` in `SceneCanvas` (`website/src/components/three/SceneCanvas.tsx`) and released temporary WebGL probe contexts via `WEBGL_lose_context` (`website/src/utils/webgl.ts`).
+- Fixed syntax error `overflow-y auto;` in `studio/studio.css` preventing Studio production builds.
+- Rejected `NaN`, `Infinity`, negative durations/repeats, array configs, and circular `transform` references cleanly inside `validateMotionConfig()`.
+
+- Resolved overloaded `classifyMotionIntent()` signature ambiguity between `animation-intelligence` (natural language/component selection) and `ai-motion-intelligence` (configuration analysis) inside `af-motion/catalogue`.
+
+### Documentation
+- Fixed four non-existent public import references in `docs/components/interactive/ReactPlayground.tsx` (`prefersReducedMotion`) and `docs/data/docs-content.ts` (`cubicBezier`, `registerCustomPalette`, `createPBRMaterial`) to reference verified public exports (`isAccessible`, `registerEasing`/`getEasing`, `registerPalette`, `getMaterial3DPreset`/`validateMaterial3D`).

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,203 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# AF Motion (Auto Flow Motion)
+
+**Version:** 1.0.0
+
+**Auto Flow Motion (AF Motion)** is a framework-independent JavaScript and TypeScript animation engine paired with optional React 19 bindings, spring and inertia physics, multi-track timelines, visual effects, 19 design styles, 33 curated palettes, 5 Motion DNA profiles, 3D/GPU tooling, deterministic AI Motion Intelligence, a developer CLI, and an offline Model Context Protocol (MCP) server.
+
+---
+
+## Core Capabilities
+
+- **Framework-Independent Core (`af-motion`)**: Web Animations API and shared `requestAnimationFrame` progress engine (`animate`, `animateProgress`), damped springs (`animateSpring`), inertia physics (`animateInertia`), custom easing registry (`easings`, `registerEasing`), multi-track timelines (`createTimeline`), layered transforms (`magnetic`, `tilt`, `parallax`), scroll triggers/observers (`reveal`, `stagger`, `inView`, `scrollProgress`, `scrollVelocity`, `scrollTrigger`), canvas backgrounds (`aurora`, `particleField`), and 33 semantic palettes.
+- **Optional React Bindings (`af-motion/react`)**: Client hooks and components (`useAnimate`, `useInView`, `useMicrointeraction`, `useMotionAccessibility`, `Reveal`, `Interactive`, `AnimatedText`, `GlassSurface`) with zero React dependency leaked into core modules.
+- **Presets & Choreography (`af-motion/presets`)**: `39` built-in motion presets (`listPresets`, `getPreset`, `applyPreset`, `animatePreset`, `registerAnimationPreset`) and synchronized cross-system choreography helpers.
+- **Catalogue, Styles, 3D & Intelligence (`af-motion/catalogue`)**: `19` visual design styles, `5` Motion DNA personalities (`precise`, `playful`, `elegant`, `energetic`, `editorial-flow`), `validateMotionConfig()`, `optimizeMotion()`, offline deterministic Design-to-Motion and Scene Generation, safe agent workflow planning, 3D scene/GPU utilities, and `createAFMotionMCPServer`.
+- **Developer CLI & MCP (`af-motion`, `af-motion-mcp`)**: Terminal commands (`init`, `doctor`, `validate`, `presets`, `info`, `example`) and stdio JSON-RPC 2.0 MCP server.
+
+---
+
+## Installation
+
+```bash
+npm install af-motion
+```
+
+`react` is an optional peer dependency (`^18.0.0 || ^19.0.0`). Vanilla JS/TS, Preset, Catalogue, CLI, and MCP workflows run without React installed.
+
+---
+
+## Quick Start
+
+### Basic DOM Animation
+
+```ts
+import { animate } from "af-motion";
+
+const controls = animate(
+  ".card",
+  { opacity: [0, 1], transform: ["translateY(16px)", "translateY(0px)"] },
+  { duration: 360, easing: "easeOutCubic" }
+);
+
+// Supports pause(), resume(), reverse(), seek(), and cancel()
+controls.cancel();
+```
+
+### React Integration (`af-motion/react`)
+
+```tsx
+"use client";
+
+import { Interactive, Reveal, useAnimate } from "af-motion/react";
+
+export function MotionCard() {
+  const { ref, animate } = useAnimate<HTMLDivElement>();
+
+  return (
+    <Reveal>
+      <Interactive>
+        <div
+          ref={ref}
+          onClick={() => animate({ opacity: [0.7, 1] }, { duration: 240 })}
+        >
+          Auto Flow Motion Card
+        </div>
+      </Interactive>
+    </Reveal>
+  );
+}
+```
+
+### Easing, Spring Physics & Timelines
+
+```ts
+import { animateSpring, createTimeline, registerEasing } from "af-motion";
+
+registerEasing("smoothStep", (t) => t * t * (3 - 2 * t));
+
+const spring = animateSpring({
+  from: 0,
+  to: 1,
+  config: { stiffness: 180, damping: 20, mass: 1 },
+  onUpdate: ({ position }) => console.log(position),
+  onComplete: () => console.log("settled"),
+});
+spring.cancel();
+
+const timeline = createTimeline()
+  .addLabel("enter", 0)
+  .add({ target: ".hero", properties: { opacity: [0, 1] }, at: "enter" })
+  .add({
+    target: ".subtitle",
+    properties: { transform: ["translateY(12px)", "translateY(0px)"] },
+    at: { previous: "end", offset: -80 },
+    options: { duration: 400 },
+  });
+
+timeline.play();
+```
+
+### Visual Effects & Cleanup
+
+```ts
+import { inView, magneticElement, parallax, tilt } from "af-motion";
+
+const mag = magneticElement(".cta-button", { strength: 0.25, distance: 120 });
+const tlt = tilt(".preview-card");
+const par = parallax(".layer", { speed: 0.2 });
+const view = inView(".reveal-section", (el) => {
+  el.classList.add("is-visible");
+  return () => el.classList.remove("is-visible");
+});
+
+// Idempotent listener & observer cleanup
+mag.destroy();
+tlt.destroy();
+par.destroy();
+view.destroy();
+```
+
+### Presets, Motion DNA & Palettes
+
+```ts
+import { animatePreset, getMotionDNA, registerPalette } from "af-motion";
+import { applyPreset, listPresets } from "af-motion/presets";
+
+const dna = getMotionDNA("precise");
+animatePreset(".panel", "slideUp", { duration: dna?.duration ?? 320 });
+
+const allPresets = listPresets();
+applyPreset(".hero-title", allPresets[0].name);
+
+registerPalette({
+  name: "Brand Obsidian",
+  primary: "#38BDF8",
+  secondary: "#0F172A",
+  accent: "#F472B6",
+});
+```
+
+### Catalogue, Validation, 3D/GPU & Offline AI Intelligence
+
+```ts
+import {
+  aiMotionRegistry,
+  createScene3D,
+  designToMotionEngine,
+  evaluateMotionQuality,
+  validateMotionConfig,
+} from "af-motion/catalogue";
+
+const searchResults = aiMotionRegistry.searchCapabilities({ term: "spring" });
+
+const report = validateMotionConfig({
+  duration: 320,
+  properties: { opacity: [0, 1], transform: ["translateY(8px)", "translateY(0px)"] },
+});
+
+const quality = evaluateMotionQuality({
+  configuration: { duration: 320, properties: { opacity: [0, 1] } },
+});
+
+const scene = createScene3D({ id: "preview-3d", autoStart: false });
+scene.destroy();
+```
+
+---
+
+## CLI & MCP Server
+
+```bash
+# Project tooling
+npx af-motion init --template vanilla-ts
+npx af-motion doctor
+npx af-motion validate af-motion.config.json
+npx af-motion presets
+npx af-motion example spring --print
+
+# Offline MCP server (stdio JSON-RPC 2.0)
+npx af-motion-mcp
+```
+
+---
+
+## Documentation, Release Notes & Source
+
+- **Source & Issues**: [github.com/Spade-2006/af-motion](https://github.com/Spade-2006/af-motion)
+- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
+- **Release Notes**: [RELEASE_NOTES.md](./RELEASE_NOTES.md)
+- **Interactive Docs App** (repository workspace): `npm run docs`
+- **Public Website App** (repository workspace): `npm run website`
+
+---
+
+## Compatibility Information
+
+- **Verified**: Node.js `v24.17.0` (`>=18.0.0` declared in `engines`), React `^19.3.1` (`StrictMode`, SSR `renderToString`, hydration), JSDOM `^26.1.0`, TypeScript `^7.0.2`.
+- **Declared / Unverified Locally**: React `^18.0.0`, Node.js `18` LTS, Bun, Deno, Next.js App Router runtime, and live Chromium/Firefox/Safari WebGL2 browser execution.
+
+---
+
+## License
+
+MIT © Satyansh Acharya

package/RELEASE_NOTES.md

@@ -0,0 +1,115 @@
+# AF Motion — V1 Release Notes (`v1.0.0`)
+
+## Product Overview
+
+**Auto Flow Motion (AF Motion)** (`af-motion`) is a framework-independent JavaScript and TypeScript animation engine paired with optional React bindings, physics solvers, 19 visual design styles, 33 built-in palettes, 5 Motion DNA profiles, 3D/GPU helpers, offline deterministic Motion Intelligence, a Model Context Protocol (MCP) server, and developer CLI tooling.
+
+---
+
+## Package Entry Points
+
+All public APIs are exposed through four official ESM subpaths (with zero runtime dependencies):
+
+| Subpath | Runtime Exports | Purpose |
+|---|---|---|
+| `af-motion` | 107 | Core WAAPI & frame engine (`animate`, `animateSpring`, `easings`, backgrounds, effects, palettes) |
+| `af-motion/react` | 289 | Optional React hooks & components (`useAnimate`, `useMicrointeraction`, `useMotionAccessibility`, `Reveal`, `Interactive`) |
+| `af-motion/catalogue` | 1,447 | Capabilities, visual styles, Motion DNA, validation, deterministic AI generation, agents, and MCP |
+| `af-motion/presets` | 97 | 39 standardized presets & recipes (`listPresets`, `getPreset`, `applyPreset`) |
+
+Additional executables:
+- `af-motion` (`bin/af-motion.js`): Developer CLI (`init`, `doctor`, `validate`, `presets`, `info`, `example`)
+- `af-motion-mcp` (`bin/mcp-server.js`): Offline stdio Model Context Protocol server
+
+---
+
+## Installation & Quick Start
+
+```bash
+npm install af-motion
+```
+
+### Core JavaScript / TypeScript
+```ts
+import { animate } from "af-motion";
+
+const controls = animate(".card", { opacity: [0, 1], transform: ["translateY(16px)", "translateY(0px)"] }, {
+  duration: 360,
+  easing: "easeOutCubic",
+});
+
+// Cancel cleanly if needed
+controls.cancel();
+```
+
+### React Integration
+```tsx
+"use client";
+
+import { Interactive, Reveal, useAnimate } from "af-motion/react";
+
+export function MotionCard() {
+  const { ref, animate } = useAnimate<HTMLDivElement>();
+
+  return (
+    <Reveal>
+      <Interactive>
+        <div
+          ref={ref}
+          onClick={() => animate({ opacity: [0.6, 1] }, { duration: 240 })}
+        >
+          Interactive Card
+        </div>
+      </Interactive>
+    </Reveal>
+  );
+}
+```
+
+### Presets & Catalogue
+```ts
+import { applyPreset, listPresets } from "af-motion/presets";
+import { aiMotionRegistry, validateMotionConfig } from "af-motion/catalogue";
+
+const presets = listPresets();
+applyPreset(".hero", presets[0].name);
+
+const capabilities = aiMotionRegistry.searchCapabilities({ term: "spring" });
+const validation = validateMotionConfig({ duration: 300, properties: { opacity: [0, 1] } });
+```
+
+### CLI Tooling
+```bash
+npx af-motion init --template vanilla-ts
+npx af-motion doctor
+npx af-motion validate af-motion.config.json
+```
+
+---
+
+## Important API Notes
+
+- **GPU-First Animation**: Animate composited properties (`transform`, `opacity`) where possible; `validateMotionConfig()` flags layout-triggering properties (`width`, `height`, `top`, `left`, `margin`) and accessibility hazards.
+- **Reduced Motion**: `animate()` and `animateSpring()` respect `prefers-reduced-motion` by default (`respectReducedMotion: true`), completing immediately at endpoints when enabled.
+- **Background-Tab Pacing**: Shared `requestAnimationFrame` loops pause automatically while `document.hidden === true`.
+- **Node Built-in Isolation**: Core, React, Catalogue, and Presets subpaths contain zero Node built-ins for browser compatibility; CLI filesystem operations remain isolated in `bin/` and `dist/cli.js`.
+
+---
+
+## Verified & Unverified Compatibility
+
+- **Verified Environments**:
+  - `Node.js v24.17.0` (CLI, MCP, ESM package resolution, Vite builds, TypeScript `^7.0.2` compilation, 38 Vitest suites / 785 tests)
+  - `React ^19.3.1` (`StrictMode`, `renderToString` SSR, client hydration, unmount cleanup)
+  - `JSDOM ^26.1.0` (DOM animations, cancellation, observer cleanup with stubbed observers, `ThreeErrorBoundary` + 2D fallback)
+- **Declared / Unverified Environments**:
+  - `React 18` (`^18.0.0` declared in `peerDependencies`, not executed locally)
+  - Live desktop/mobile browsers: `Chromium`, `Firefox`, `Safari/WebKit` (not verified in an interactive GPU browser session)
+  - `Bun`, `Deno`, `Node.js 18 LTS`, and full `Next.js` App Router server/client runtime (not installed/executed in this environment)
+
+---
+
+## Known Limitations
+
+- Real-browser visual testing (WebGL2 shader frames, live WAAPI frame timing, pointer/scroll smoothness, and clipboard permission prompts across Chrome, Firefox, and Safari) should be run in CI/target browsers prior to public npm announcement.
+- Two lazy function-level mutual reference pairs (`core/motion-choreography.ts <-> presets.ts`, `core/motion-recipe.ts <-> presets.ts`) remain intentionally in `src/`; runtime execution and Rollup/Vite bundling succeed cleanly.

package/bin/af-motion.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/**
+ * AF Motion CLI — Executable Binary Entrypoint
+ *
+ * Dispatches terminal commands to the AF Motion developer tooling engine.
+ */
+
+import { runCLI } from "../dist/cli.js";
+
+runCLI(process.argv.slice(2)).then((code) => {
+  process.exit(code ?? 0);
+}).catch((err) => {
+  console.error("Fatal CLI Error:", err);
+  process.exit(1);
+});

package/bin/mcp-server.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+/**
+ * AF Motion Model Context Protocol (MCP) Stdio Server
+ *
+ * Standalone executable entrypoint running the AF Motion MCP server over standard input/output.
+ * Compatible with Cursor, Claude Desktop, Claude Code, Antigravity, and Codex.
+ */
+
+import { createAFMotionMCPServer, StdioTransport } from "../dist/catalogue.js";
+
+const transport = new StdioTransport();
+const server = createAFMotionMCPServer({ transport });
+
+const cleanup = async () => {
+  await server.close();
+  process.exit(0);
+};
+
+process.on("SIGINT", cleanup);
+process.on("SIGTERM", cleanup);

package/dist/3d/adapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * AF Motion 3D Renderer Adapters
+ *
+ * Implements framework-independent renderer adapters, including the optional
+ * Three.js adapter and the graceful fallback Null renderer adapter.
+ */
+import type { Renderer3DAdapter, Renderer3DConfig, Scene3DCapabilities } from "./types.js";
+/**
+ * Fallback Null Renderer Adapter used when WebGL or Three.js is unavailable.
+ */
+export declare function createNullRenderer3DAdapter(): Renderer3DAdapter;
+export interface ThreeAdapterOptions {
+    /** Optional custom or injected THREE library namespace */
+    readonly THREE?: any;
+}
+/**
+ * Check if Three.js is available either in global scope or provided options.
+ */
+export declare function isThreeAvailable(customThree?: any): boolean;
+/**
+ * Create an optional Three.js Renderer Adapter.
+ * Does not force Three.js into the core bundle. If Three.js is absent,
+ * falls back gracefully.
+ */
+export declare function createThreeRendererAdapter(options?: ThreeAdapterOptions): Renderer3DAdapter;
+/**
+ * Create a suitable 3D renderer adapter based on configuration and available capabilities.
+ */
+export declare function createRenderer3DAdapter(config?: Renderer3DConfig, capabilities?: Scene3DCapabilities): Renderer3DAdapter;