Rewrite README for the Motion pakcage

README.md

@@ -1,19 +1,21 @@
+<!-- AI: full docs index at https://wix.github.io/interact/llms.txt -->
+
 # Wix Interact
 
 Web-native animation and interaction libraries — declarative, AI-ready, framework-agnostic.
 
 [![npm version](https://img.shields.io/npm/v/@wix/interact)](https://www.npmjs.com/package/@wix/interact)
 [![npm version](https://img.shields.io/npm/v/@wix/motion)](https://www.npmjs.com/package/@wix/motion)
 [![npm version](https://img.shields.io/npm/v/@wix/motion-presets)](https://www.npmjs.com/package/@wix/motion-presets)
-[![license](https://img.shields.io/npm/l/@wix/interact)](LICENSE)
+[![license](https://img.shields.io/npm/l/@wix/interact)](https://github.com/wix/interact/blob/master/LICENSE)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/interact)](https://bundlephobia.com/package/@wix/interact)
 
 ## What is Interact?
 
 **Wix Interact** (`@wix/interact`) is a declarative interaction layer on top of **@wix/motion**. You describe _when_ something should animate and _what_ should happen in a JSON config — no manual event listeners, no imperative animation wiring.
 
 - **Config-driven** — bind triggers (`viewEnter`, `click`, `hover`, `viewProgress`, `pointerMove`, and more) to effects in one `InteractConfig` object
-- **Built on native browser APIs** — Web Animations API, `ViewTimeline`, pointer tracking, and CSS; with an optional custom animation runtime via `@wix/motion`
+- **Built on native browser APIs** — Web Animations API, `ViewTimeline`, pointer tracking, and CSS.
 - **Three entry points** — Web Components (`@wix/interact/web`), React (`@wix/interact/react`), and vanilla JS (`@wix/interact`)
 - **Ready-made presets** — entrance, scroll, pointer, loop, and micro-interactions from `@wix/motion-presets`
 - **SSR-friendly CSS** — `generate(config)` emits complete CSS for the whole config (keyframes, view-timeline, transitions, FOUC rules) so animations can be ready before JS runs
@@ -22,11 +24,11 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew
 
 ## Packages
 
-| Package                                                                                       | Description                                  | Links                                                                                                                                            |
-| --------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [`@wix/interact`](https://github.com/wix/interact/blob/master/packages/interact/)             | Declarative interaction layer (main package) | [README](https://github.com/wix/interact/blob/master/packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact)           |
-| [`@wix/motion`](https://github.com/wix/interact/blob/master/packages/motion/)                 | Low-level animation engine                   | [README](https://github.com/wix/interact/blob/master/packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion)               |
-| [`@wix/motion-presets`](https://github.com/wix/interact/blob/master/packages/motion-presets/) | Ready-made animation presets                 | [README](https://github.com/wix/interact/blob/master/packages/motion-presets/README.md) [npm](https://www.npmjs.com/package/@wix/motion-presets) |
+| Package                                                                                      | Description                                  | Links                                                                                                                                  |
+| -------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@wix/interact`](https://github.com/wix/interact/blob/master/packages/interact/)            | Declarative interaction layer (main package) | [README](https://github.com/wix/interact/blob/master/packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact) |
+| [`@wix/motion`](https://github.com/wix/interact/blob/master/packages/motion/)                | Low-level animation engine                   | [README](https://github.com/wix/interact/blob/master/packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion)     |
+| [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) | Ready-made animation presets                 | [npm](https://www.npmjs.com/package/@wix/motion-presets)                                                                               |
 
 ```
 @wix/motion ← @wix/interact (declarative layer)
@@ -120,9 +122,10 @@ import { useEffect } from 'react';
 import { Interact, Interaction } from '@wix/interact/react';
 import * as presets from '@wix/motion-presets';
 
+Interact.registerEffects(presets);
+
 function App() {
   useEffect(() => {
-    Interact.registerEffects(presets);
     const instance = Interact.create(config);
 
     return () => {
@@ -187,7 +190,7 @@ const config: InteractConfig = {
 };
 ```
 
-Inject the styles returned from `generate(config)` into `<head>` for FOUC prevention.
+FOUC prevention requires injecting the output of `generate(config)` into `<head>`.
 
 ### Click effect
 
@@ -229,7 +232,7 @@ const config: InteractConfig = {
       trigger: 'viewProgress',
       effects: [
         {
-          namedEffect: { type: 'ParallaxScroll', speed: 0.5 },
+          namedEffect: { type: 'ParallaxScroll', parallaxFactor: 0.5 },
           rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
           rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
           easing: 'linear',
@@ -333,6 +336,11 @@ type Interaction = {
 
 ## AI and Agent Support
 
+AI agents can discover @wix/interact documentation through:
+
+- **[llms.txt](https://wix.github.io/interact/llms.txt)** — structured docs index ([llms.txt standard](https://llmstxt.org/))
+- **[llms-full.txt](https://wix.github.io/interact/llms-full.txt)** — all rules in a single file
+
 ### Rules files
 
 **@wix/interact**:
@@ -355,7 +363,7 @@ type Interaction = {
 - Do not invent `namedEffect` types — use only registered presets (see preset rules above)
 - Do not attach DOM event listeners manually — express behavior through `trigger` and config
 - For `viewProgress`, avoid `overflow: hidden` on ancestors; use `overflow: clip` instead
-- Call `generate(config)` at build time or on the server and inject CSS into `<head>`. For `viewEnter` + `triggerType: 'once'`, to prevent FOUC
+- Call `generate(config)` at build time or on the server and inject CSS into `<head>`
 - `effects` at the config top level is a reusable `Record<string, Effect>`
 - `<interact-element>` should wrap exactly one child (the library targets `.firstElementChild` by default).
 

packages/interact/README.md

@@ -1,3 +1,5 @@
+<!-- AI: full docs index at https://wix.github.io/interact/llms.txt -->
+
 # @wix/interact
 
 Declarative, configuration-driven interaction library — web-native, AI-ready, and framework-agnostic.
@@ -9,12 +11,12 @@ Declarative, configuration-driven interaction library — web-native, AI-ready,
 
 ## Why Interact?
 
-- **Declerative** — Define trigger-to-effect bindings in JSON; no imperative event wiring
+- **Declarative** — Define trigger-to-effect bindings in JSON; no imperative event wiring
 - **Web-native** — Built on CSS, WAAPI, ViewTimeline, and DOM APIs; supports DOM management via Custom Elements
 - **Framework-agnostic** — Web Components and vanilla JS integrations; React integration included
 - **AI-ready** — JSON configs are machine-readable and provide guardrails; LLMs can generate and agents can validate them
 - **CSS generation** — `generate(config)` emits complete CSS for the whole config (`@keyframes`, `view-timeline`, transitions, FOUC rules)
-- **Preset ecosystem** — Plug in [`@wix/motion-presets`](../motion-presets/README.md) for 80+ ready-made effects.
+- **Preset ecosystem** — Plug in [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) for 75+ ready-made effects.
 - **Accessible** — Built-in `activate` (click + keyboard) and `interest` (hover + focus) trigger variants
 
 ## Install
@@ -39,9 +41,9 @@ npm install @wix/motion-presets
 
 ```ts
 import { Interact, generate, type InteractConfig } from '@wix/interact/web';
-import * as presets from '@wix/motion-presets'; // optional
+import * as presets from '@wix/motion-presets'; // required when using namedEffect
 
-Interact.registerEffects(presets); // optional
+Interact.registerEffects(presets); // required when using namedEffect
 
 const config: InteractConfig = {
   interactions: [
@@ -62,7 +64,7 @@ const config: InteractConfig = {
 };
 
 // render styles  - e.g. for SSR
-const interactCSS = generate(config, false);
+const interactCSS = generate(config, true);
 
 // run on client - e.g. on pagereveal event
 const instance = Interact.create(config);
@@ -132,7 +134,7 @@ export function Hero() {
 }
 ```
 
-### Using vaniall JS - no handling for DOM changes
+### Using Vanilla JS (you manage element lifecycle)
 
 **Vanilla JS** — bind elements after they exist in the DOM:
 
@@ -167,14 +169,14 @@ Config ─┬─► Interact.create() ─► Trigger Observers ─► Effect Eng
 ```
 
 `generate(config)` runs at build time or on the server to emit complete CSS for the entire config — maximizing offload of effect creation, binding, and running to the browser.
-Interact also uses native effect triggering, i.e. `view-timeline`, as it becomes more widely supported
+Interact also generates native `view-timeline` CSS declarations, so browsers that support it can drive scroll animations entirely without JS.
 
 The `InteractConfig` shape:
 
 ```ts
 type InteractConfig = {
   interactions: Interaction[]; // trigger → effect bindings
-  effects: ?Record<string, Effect>; // reusable effect definitions
+  effects?: Record<string, Effect>; // reusable effect definitions
   sequences?: Record<string, SequenceConfig>; // staggered multi-effect timelines
   conditions?: Record<string, Condition>; // media / selector gates
 };
@@ -314,8 +316,9 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf
   effects: {
     'lift': {
       keyframeEffect: {
+        name: 'lift',
         keyframes: [
-          { transform: 'transformY(-80px)', boxShadow: '0 8px 16px rgb(0 0 0 / 0.15)' },
+          { transform: 'translateY(-80px)', boxShadow: '0 8px 16px rgb(0 0 0 / 0.15)' },
         ],
       },
       duration: 200,
@@ -345,6 +348,7 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf
   effects: {
     'follow-x': {
       keyframeEffect: {
+        name: 'follow-x',
         keyframes: [
           { transform: 'rotateY(-45deg)' },
           { transform: 'rotateY(0px)' },
@@ -356,6 +360,7 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf
     },
     'follow-y': {
       keyframeEffect: {
+        name: 'follow-y',
         keyframes: [
           { transform: 'rotateX(45deg)' },
           { transform: 'rotateX(0px)' },
@@ -397,14 +402,19 @@ Each example is a complete `InteractConfig` — pass it to `Interact.create(conf
 - **Same element as source and target with `viewEnter`** — Must use `triggerType: 'once'`. Other types cause re-entry loops.
 - **Hit-area shift on `hover` / `pointerMove`** — Animating size/position of the hovered element shifts the hit area and causes jitter. Instead, animate a child via `selector` or a different `key`.
 - **`registerEffects()` must run before `Interact.create()`/`generate()`** when using `namedEffect`.
-- **FOUC prevention requires** — `generate(config)` injected into `<head>`.
+- **FOUC prevention** — requires injecting the output of `generate(config)` into `<head>`.
 - **`generate(config, useFirstChild)`** — Pass `true` for `<interact-element>` (web), `false` for vanilla and React `<Interaction>`.
 - **`<interact-element>` must wrap exactly one child** — the library targets `:first-child` by default.
 
 ## AI & Agent Support
 
 Interact's JSON-config surface is the differentiator: configs are serializable, schema-typed, and validate-able (guardrails) — no imperative DOM logic for an LLM to hallucinate.
 
+AI agents can discover @wix/interact documentation through:
+
+- **[llms.txt](https://wix.github.io/interact/llms.txt)** — structured docs index ([llms.txt standard](https://llmstxt.org/))
+- **[llms-full.txt](https://wix.github.io/interact/llms-full.txt)** — all rules in a single file
+
 **Rules files** ship with the package under [`rules/`](https://github.com/wix/interact/tree/master/packages/interact/rules) — point your agent at them:
 
 - [`rules/full-lean.md`](https://wix.github.io/interact/rules/full-lean.md) — complete config spec, pitfalls, and constraints
@@ -427,23 +437,23 @@ Interact's JSON-config surface is the differentiator: configs are serializable,
 
 - Modern browsers with the Web Animations API (Baseline).
 - `adoptedStyleSheets` (used by `transition` / `transitionProperties`): Chrome 73+, Firefox 101+, Safari 16.4+, Edge 79+.
-- ViewTimeline: Chrome 115+; polyfilled via [`fizban`](https://github.com/wix/fizban) elsewhere.
+- ViewTimeline: Chrome 115+; polyfilled via [`fizban`](https://github.com/wix-incubator/fizban) elsewhere.
 
 ## Related Packages
 
 - [`@wix/motion`](https://github.com/wix/interact/tree/master/packages/motion) — low-level animation engine underneath Interact.
 - [`@wix/motion-presets`](https://github.com/wix/interact/tree/master/packages/motion-presets) — ready-made effect catalog (entrance, scroll, hover, pointer).
-- [`fizban`](https://github.com/wix/fizban) — scroll-driven animation polyfill (bundled dependency).
-- [`kuliso`](https://github.com/wix/kuliso) — pointer-driven animation polyfill (bundled dependency).
+- [`fizban`](https://github.com/wix-incubator/fizban) — scroll-driven animation polyfill (bundled dependency).
+- [`kuliso`](https://github.com/wix-incubator/kuliso) — pointer-driven animation polyfill (bundled dependency).
 
 ## Documentation
 
-- [**Getting Started**](https://wix.github.io/interact/docs/guides/getting-started.md)
-- [**API Reference**](https://wix.github.io/interact/docs/api/README.md) — `Interact` class, `InteractionController`, standalone functions, types
-- [**Guides**](https://wix.github.io/interact/docs/guides/README.md) — triggers, effects, configuration, state, conditions, sequences
-- [**Examples**](https://wix.github.io/interact/docs/examples/README.md) — entrance, click, hover, list patterns
-- [**Web Components**](https://wix.github.io/interact/docs/guides/custom-elements.md) - integration via custom elements
-- [**React Integration**](https://wix.github.io/interact/docs/integration/react.md) - React integration
+- [**Getting Started**](https://wix.github.io/interact/docs/#/guides/getting-started)
+- [**API Reference**](https://wix.github.io/interact/docs/#/api) — `Interact` class, `InteractionController`, standalone functions, types
+- [**Guides**](https://wix.github.io/interact/docs/#/guides) — triggers, effects, configuration, state, conditions, sequences
+- [**Examples**](https://wix.github.io/interact/docs/#/examples) — entrance, click, hover, list patterns
+- [**Web Components**](https://wix.github.io/interact/docs/#/guides/custom-elements) — integration via custom elements
+- [**React Integration**](https://wix.github.io/interact/docs/#/integration/react) — React integration
 
 ## License
 

packages/interact/package.json

@@ -6,6 +6,8 @@
   "main": "dist/cjs/index.js",
   "module": "dist/es/index.js",
   "types": "dist/types/index.d.ts",
+  "llms": "https://wix.github.io/interact/llms.txt",
+  "llmsFull": "https://wix.github.io/interact/llms-full.txt",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",