@syncedco/motion 0.1.0

package/docs/RECIPES.md

@@ -0,0 +1,115 @@
+# Motion recipe system
+
+Motion recipes are the shared interface used by the DOM runtime, CLI, MCP
+server, gallery, inspector, and framework adapters.
+They make an effect discoverable and testable without limiting a project-owned
+recipe to a fixed list of visual ideas.
+
+## Contract
+
+Create recipes with `defineMotionRecipe()`. A recipe declares:
+
+- a stable kebab-case id, semantic intent, family, and tags;
+- a root selector and root-scoped semantic slots;
+- bounded parameters and supported triggers;
+- reduced-motion, no-JavaScript, and accessibility behavior;
+- performance cost and plugin dependencies;
+- preview and fixture metadata; and
+- either a declarative timeline or typed `setup(context)` implementation.
+
+The validator rejects document-global roots such as `body`, incomplete numeric
+parameters, missing fallbacks, and declarative layout animation that has not
+explicitly opted into the high-cost path.
+
+## Runtime specs and authoring metadata
+
+A recipe manifest serves two audiences with very different needs. The browser
+reads the root selector, slots, parameters, triggers, reduced-motion strategy,
+performance class, dependencies and `setup`. Humans and agents read the title,
+description, intent, family, tags, accessibility notes, no-JavaScript
+behaviour, preview settings and fixture markup.
+
+The second group is roughly sixty percent of the payload and none of it is used
+while animating, so the two are stored separately:
+
+| Module | Contents | Imported by |
+| --- | --- | --- |
+| `src/recipes/specs.js` | Lean runtime specs, one named export per recipe | The browser runtime |
+| `src/recipes/authoring.js` | Prose, preview data, fixture markup | CLI, MCP server, gallery, inspector, docs |
+| `src/recipes/builtins.js` | The two merged into complete manifests | Tooling |
+| `src/recipes/runtime-registry.js` | A registry over the lean specs | `createSyncedMotion` |
+
+This is why the registry has a mode:
+
+```js
+createMotionRegistry(recipes)                      // 'complete' -- the default
+createMotionRegistry(specs, { mode: 'runtime' })   // lean specs
+```
+
+`complete` requires the full manifest and is what `defineMotionRecipe` uses by
+default, so a recipe you write yourself must still declare its fallbacks and
+fixtures. `runtime` validates only what the browser reads.
+
+Because each spec is a separate named export annotated `/* @__PURE__ */`, a page
+that imports three recipes bundles three recipes. When adding a recipe, annotate
+both the `spec(...)` call and the nested `setupFactory(...)` call, or bundlers
+will retain all sixty; `npm run size:check` will fail if you forget.
+
+After changing any recipe, regenerate the reference:
+
+```bash
+npm run docs:build
+```
+
+## Registry and service seam
+
+`createMotionRegistry(recipes)` owns registration, id resolution, validation,
+and the serializable public catalog. `createMotionService(registry)` exposes
+catalog, recipe lookup, deterministic suggestion, validation, and motion-plan
+data without performing file or process side effects. The CLI and MCP server
+must use this service rather than reimplementing catalog logic.
+
+The built-in registry contains sixty stable recipe IDs across twelve families:
+reveals/entrances, split-text/typography, scroll/parallax, pinned storytelling,
+horizontal galleries, hover/focus/pointer, navigation/overlay, media/mask/clip,
+loops/progress/ambient, FLIP/layout, SVG/path/morph, and page-load/route.
+Every family contains five implemented recipes.
+
+## Preview fixtures
+
+Every recipe owns at least one serializable fixture. `preview.fixture` must
+resolve to a unique fixture ID. A fixture declares a label, semantic markup,
+and optional bounded parameter values. Its markup must contain exactly one
+recipe root and every required slot inside that root. This contract lets the
+gallery and agents render previews without maintaining a second ID map.
+
+```js
+preview: { fixture: 'default', viewport: 'standard', activation: 'auto' },
+fixtures: [{
+  id: 'default',
+  label: 'Default',
+  markup: '<section data-motion-example><p data-motion-item>Readable content</p></section>',
+  parameters: {},
+}]
+```
+
+## Runtime lifecycle
+
+`createMotionRuntime()` resolves matching recipe roots, verifies required slots,
+and mounts recipes inside those roots. It exposes:
+
+- `mount()` and `mountRecipe()`;
+- `refresh()` for layout-dependent trigger recalculation;
+- `inspect()` for registered, mounted, skipped, and failed recipes; and
+- `destroy()` for deterministic teardown.
+
+The runtime uses `gsap.matchMedia()` so responsive and reduced-motion contexts
+are reverted together. A missing slot skips animation but does not hide or
+remove authored content. `createSyncedMotion()` remains supported while the
+existing attribute patterns are migrated onto recipe manifests.
+
+## Ownership
+
+Recipes orchestrate motion and semantic state. They do not own typography,
+spacing, colour, layout, or final component presentation. Those remain Synced
+Flow and consuming-project responsibilities.

package/docs/TOOLING.md

@@ -0,0 +1,65 @@
+# CLI and MCP tools
+
+Synced Motion ships a local `synced-motion` executable. Human-facing text is
+the default; pass `--json` when an agent or build tool needs stable structured
+data.
+
+```bash
+npx synced-motion --help            # every command
+npx synced-motion <command> --help  # one command in detail
+npx synced-motion --version
+```
+
+## Commands
+
+- `add <id...>` prints ready-to-paste markup for one or more recipes,
+  including every required slot. The command writes nothing; redirect it
+  where you want it.
+
+  ```bash
+  npx synced-motion add reveal-rise
+  npx synced-motion add pinned-steps marquee > partials/motion.html
+  ```
+
+  When a recipe needs an optional GSAP plugin, `add` says so on stderr, so the
+  markup can still be piped cleanly.
+- `catalog` lists registered recipe manifests.
+- `recipe <id>` returns one manifest.
+- `suggest "<brief>"` ranks recipes using deterministic catalog metadata.
+- `plan <id...>` returns roots, slots, defaults, reduced-motion behavior, and
+  performance metadata for an integration.
+- `scan --file <path>` finds registered hooks and missing required slots.
+- `compose "<brief>" --file <path>` combines deterministic suggestions, a
+  recipe plan, markup diagnostics, and performance warnings.
+- `validate` validates the active registry; pass `--file <recipe.json>` to validate a custom declarative recipe.
+- `doctor` checks that the registry and service are usable.
+- `init --agents` installs project config, scripts, and managed AI guidance.
+- `agents install|status` manages only the marked Synced Motion guidance block.
+- `mcp` starts the project-local stdio MCP server.
+
+The 1.0 catalog contains sixty implemented and verified recipes: five recipes
+in each of twelve families. Placeholder or no-op entries are rejected from the
+launch catalog. The CLI, MCP server, public service, gallery, and inspector all
+read the same source registry.
+
+## MCP server
+
+Start the server with:
+
+```bash
+npx synced-motion mcp
+```
+
+It exposes:
+
+- `motion_catalog`
+- `motion_recipe`
+- `motion_suggest`
+- `motion_validate`
+- `motion_plan`
+- `motion_scan`
+- `motion_compose`
+
+These tools call the same service module as the CLI. Protocol tests connect an
+MCP client over an in-memory transport and execute the real server tool surface.
+The server runs locally over stdio and does not require a hosted AI provider.

package/docs/WEBFLOW-MIGRATION.md

@@ -0,0 +1,39 @@
+# Migrating a Webflow experience
+
+## Inventory first
+
+Capture every page-load, click, hover, scroll, pin, scrub, reveal, and menu interaction. Record trigger, target, start/end position, duration, ease, stagger, and reduced-motion behavior.
+
+## Replace generated identity
+
+Replace opaque Webflow interaction attributes with readable semantic hooks:
+
+```html
+<!-- Before -->
+<a data-wf-element-id="645ee970-6c97-eea3-d61b-013ab5a5f236">...</a>
+
+<!-- After -->
+<a data-motion-step-link>...</a>
+```
+
+## Preserve ownership boundaries
+
+- Convert Webflow variables to Synced Flow tokens.
+- Convert utility layout to `sf-*` primitives.
+- Keep unique editorial section classes in the consuming site.
+- Make state controllers work before adding GSAP presentation.
+- Toggle semantic state instead of animating final brand colors inline.
+
+## Removal order
+
+1. Rebuild one interaction locally.
+2. Verify it against the reference in both scroll directions.
+3. Disable the equivalent Webflow interaction.
+4. Remove its generated IDs and overrides.
+5. Repeat until the Webflow runtime owns no behavior.
+6. Remove Webflow JavaScript and jQuery.
+7. Remove unused compatibility CSS and metadata.
+8. Run browser, accessibility, reduced-motion, performance, and build checks.
+
+Never remove the Webflow runtime before replacing and verifying every behavior it owns.
+

package/package.json

@@ -0,0 +1,167 @@
+{
+  "name": "@syncedco/motion",
+  "version": "0.1.0",
+  "description": "Accessible, framework-neutral scroll and interaction animation for the web. Sixty validated GSAP recipes with reduced-motion, no-JS and cleanup behaviour built into the contract.",
+  "type": "module",
+  "author": "Scott Mackey",
+  "homepage": "https://github.com/SyncedCo/synced-motion#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SyncedCo/synced-motion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SyncedCo/synced-motion/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "files": [
+    "bin",
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "TRADEMARKS.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "synced-motion": "./bin/synced-motion.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./full": {
+      "types": "./dist/full.d.ts",
+      "import": "./dist/full.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js"
+    },
+    "./recipes": {
+      "types": "./dist/recipes.d.ts",
+      "import": "./dist/recipes.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./lenis": {
+      "types": "./dist/lenis.d.ts",
+      "import": "./dist/lenis.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte.d.ts",
+      "import": "./dist/svelte.js"
+    },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "import": "./dist/astro.js"
+    },
+    "./wordpress": {
+      "types": "./dist/wordpress.d.ts",
+      "import": "./dist/wordpress.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-declarations.mjs",
+    "dev": "vite example",
+    "gallery": "vite example --open /gallery/",
+    "cli": "node ./bin/synced-motion.mjs",
+    "mcp": "node ./bin/synced-motion.mjs mcp",
+    "motion:validate": "node ./bin/synced-motion.mjs validate",
+    "motion:doctor": "node ./bin/synced-motion.mjs doctor",
+    "motion:mcp": "node ./bin/synced-motion.mjs mcp",
+    "mcp:check": "node scripts/check-mcp.mjs",
+    "flow:build": "synced-flow build",
+    "flow:check": "synced-flow build --check",
+    "flow:lint": "synced-flow lint",
+    "flow:doctor": "synced-flow doctor",
+    "flow:watch": "synced-flow watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:browser": "playwright test",
+    "test:browser:ui": "playwright test --ui",
+    "units:check": "node scripts/check-units.mjs",
+    "types:check": "node scripts/check-declarations.mjs",
+    "size:check": "node scripts/check-size.mjs",
+    "docs:build": "node scripts/build-docs.mjs",
+    "docs:check": "node scripts/build-docs.mjs --check",
+    "gallery:build": "vite build --config example/gallery/vite.config.js",
+    "check": "npm run flow:check && npm run flow:lint && npm run flow:doctor && npm run units:check && npm run test && npm run build && npm run types:check && npm run size:check && npm run docs:check && npm run motion:validate && npm run motion:doctor && npm run mcp:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "animation",
+    "gsap",
+    "scrolltrigger",
+    "lenis",
+    "synced-flow",
+    "motion",
+    "scroll-animation"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@gsap/react": ">=2.1.0",
+    "gsap": ">=3.13.0",
+    "react": ">=18.0.0",
+    "vue": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@gsap/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "lenis": "^1.3.25",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@gsap/react": "^2.1.2",
+    "@playwright/test": "^1.62.0",
+    "@syncedco/flow": "^0.3.2",
+    "axe-core": "^4.12.1",
+    "gsap": "^3.15.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.7",
+    "tsup": "^8.5.1",
+    "typescript": "5.7.3",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10",
+    "vue": "^3.5.40"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  }
+}