Rewrite README for the Motion pakcage

README.md

@@ -5,15 +5,15 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew
 [![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; optional `customEffect` adds programmatic per-frame JS callbacks for effects that go beyond what native APIs can express.
 - **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 +22,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 +120,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 +188,7 @@ const config: InteractConfig = {
 };
 ```
 
-Inject the styles returned from `generate(config)` into `<head>` for FOUC prevention.
+FOUC prevention requires two steps — (1) inject the output of `generate(config)` into `<head>`, and (2) mark each entrance-animated element with `data-interact-initial="true"` (`initial={true}` in React). Both are required.
 
 ### Click effect
 
@@ -229,7 +230,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',
@@ -355,7 +356,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>`. For `viewEnter` + `triggerType: 'once'`, to prevent FOUC, also mark elements with `data-interact-initial="true"`.
 - `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

@@ -9,12 +9,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 +39,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 +62,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 +132,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 +167,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 +314,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 +346,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 +358,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,7 +400,7 @@ 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 two steps** — (1) inject the output of `generate(config)` into `<head>`, and (2) mark each entrance-animated element with `data-interact-initial="true"` (`initial={true}` in React). Both are required.
 - **`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.
 
@@ -427,23 +430,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