From e24599a4edd1541332ea3a398a4b825993aa4700 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Tue, 19 May 2026 17:30:24 +0300
Subject: [PATCH 1/7] Created root README

---
 README.md | 376 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 347 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 9c6ffd20..6f9f5008 100644
--- a/README.md
+++ b/README.md
@@ -1,56 +1,374 @@
-# Interact Monorepo
+# Wix Interact
 
-This repository hosts the Interact library, accompanying docs, and any supporting applications. It is structured as an npm workspace-powered monorepo with the following layout:
+Web-native animation and interaction libraries — declarative, AI-ready, framework-agnostic.
 
-- `packages/` for publishable libraries (starting with the core Interact library).
-- `apps/` for documentation, demos, and future experience-specific frontends.
-- Shared root tooling such as TypeScript configs, linting, and scripts.
+[![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)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@wix/interact)](https://bundlephobia.com/package/@wix/interact)
 
-## Getting Started
+## What is Interact?
 
-### Install dependencies
+**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`
+- **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
+
+**Live site:** [wix.github.io/interact](https://wix.github.io/interact/) · **Examples gallery:** [wix.github.io/interact/examples.html](https://wix.github.io/interact/examples.html)
+
+## Packages
+
+| Package | Version | Description | Links |
+| --- | --- | --- | --- |
+| [`@wix/interact`](https://www.npmjs.com/package/@wix/interact) | 2.2.2 | Declarative interaction layer (main package) | [README](packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact) |
+| [`@wix/motion`](https://www.npmjs.com/package/@wix/motion) | 2.1.5 | Low-level animation engine | [README](packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion) |
+| [`@wix/motion-presets`](https://www.npmjs.com/package/@wix/motion-presets) | 1.0.2 | Ready-made animation presets | [npm](https://www.npmjs.com/package/@wix/motion-presets) · [preset rules](packages/motion-presets/rules/presets/presets-main.md) |
 
-```bash
-yarn install
 ```
+@wix/motion ← @wix/interact (declarative layer)
+@wix/motion ← @wix/motion-presets (ready-made effects)
+```
+
+## Quick Start
 
-### Building
+Install the interaction layer and presets (presets are required when using `namedEffect`):
 
 ```bash
-yarn build
+npm install @wix/interact @wix/motion-presets
 ```
 
-### Testing
+All examples below share this config — a `viewEnter` entrance using the `FadeIn` preset:
 
-```bash
-yarn test
+```typescript
+import type { InteractConfig } from '@wix/interact';
+
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'hero',
+      trigger: 'viewEnter',
+      params: { threshold: 0.2 },
+      effects: [{ effectId: 'hero-fade' }],
+    },
+  ],
+  effects: {
+    'hero-fade': {
+      duration: 800,
+      easing: 'ease-out',
+      fill: 'both',
+      triggerType: 'once',
+      namedEffect: { type: 'FadeIn' },
+    },
+  },
+};
 ```
 
-## Running demo app
+> **Accuracy notes:** `effects` at the config top level is a reusable `Record<string, Effect>`. `add` and `remove` are standalone imports, not instance methods. Call `Interact.registerEffects(presets)` before `Interact.create()` when using `namedEffect`. `<interact-element>` must wrap exactly one child (the library targets `.firstElementChild`).
 
-```bash
-yarn dev:demo
+### Web Components (recommended)
+
+Pre-render CSS with `generate()` to avoid a flash of unstyled content on entrance animations, then boot the runtime:
+
+```typescript
+import { Interact, generate } from '@wix/interact/web';
+import * as presets from '@wix/motion-presets';
+
+Interact.registerEffects(presets);
+
+const css = generate(config, true); // `true` = use :first-child selectors for <interact-element>
+document.head.insertAdjacentHTML('beforeend', `<style id="interact-critical">${css}</style>`);
+
+Interact.create(config);
 ```
 
-## Running documentation app
+```html
+<interact-element data-interact-key="hero" data-interact-initial="true">
+  <section class="hero">
+    <h1>Hello, Interact</h1>
+  </section>
+</interact-element>
+```
 
-```bash
-yarn dev:docs
+```css
+/* Optional — keep the custom element from affecting layout */
+interact-element {
+  display: contents;
+}
+```
+
+### React
+
+Wrap `Interact.create()` in `useEffect` and destroy on cleanup. Use `<Interaction>` instead of raw elements:
+
+```tsx
+import { useEffect } from 'react';
+import { Interact, Interaction } from '@wix/interact/react';
+import * as presets from '@wix/motion-presets';
+
+function App() {
+  useEffect(() => {
+    Interact.registerEffects(presets);
+    const instance = Interact.create(config);
+
+    return () => {
+      instance.destroy();
+    };
+  }, []);
+
+  return (
+    <Interaction tagName="section" interactKey="hero" initial className="hero">
+      <h1>Hello, Interact</h1>
+    </Interaction>
+  );
+}
+```
+
+Inject `generate(config, false)` output into your document shell (e.g. Remix `links`, Next.js layout `<head>`) the same way as the Web Components example.
+
+### Vanilla JS
+
+```typescript
+import { Interact, add } from '@wix/interact';
+import * as presets from '@wix/motion-presets';
+
+Interact.registerEffects(presets);
+Interact.create(config);
+
+const hero = document.querySelector('.hero') as HTMLElement;
+add(hero, 'hero');
+```
+
+```html
+<section data-interact-key="hero" data-interact-initial="true" class="hero">
+  <h1>Hello, Interact</h1>
+</section>
+```
+
+Call `add(element, key)` after the element exists in the DOM. Use `remove(key)` to unregister a key.
+
+## Common Patterns
+
+Config-only recipes — each is a valid `InteractConfig` shape. Register presets before `Interact.create()` when using `namedEffect`.
+
+### Entrance animation
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'card',
+      trigger: 'viewEnter',
+      params: { threshold: 0.15 },
+      effects: [{ effectId: 'card-float' }],
+    },
+  ],
+  effects: {
+    'card-float': {
+      duration: 900,
+      easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+      fill: 'both',
+      triggerType: 'once',
+      namedEffect: { type: 'FloatIn', direction: 'bottom' },
+    },
+  },
+};
+```
+
+Set `data-interact-initial="true"` (or `initial` on `<Interaction>`) and inject `generate(config)` CSS for FOUC prevention.
+
+### Click effect
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'button',
+      trigger: 'click',
+      effects: [
+        {
+          key: 'button',
+          triggerType: 'once',
+          fill: 'backwards',
+          duration: 400,
+          easing: 'ease-out',
+          keyframeEffect: {
+            name: 'button-pop',
+            keyframes: [
+              { transform: 'scale(1)' },
+              { transform: 'scale(0.92)' },
+              { transform: 'scale(1)' },
+            ],
+          },
+        },
+      ],
+    },
+  ],
+};
+```
+
+Use `trigger: 'activate'` instead of `click` for keyboard-accessible activation (Enter / Space).
+
+### Scroll-driven parallax
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'parallax-bg',
+      trigger: 'viewProgress',
+      effects: [
+        {
+          key: 'parallax-bg',
+          namedEffect: { type: 'ParallaxScroll', speed: 0.5, range: 'continuous' },
+          rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
+          rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
+          easing: 'linear',
+          fill: 'both',
+        },
+      ],
+    },
+  ],
+};
+```
+
+Replace `overflow: hidden` with `overflow: clip` on ancestors between the element and the scroll container — `hidden` breaks `ViewTimeline`.
+
+### Hover toggle (CSS transition)
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'card',
+      trigger: 'hover',
+      effects: [
+        {
+          key: 'card',
+          stateAction: 'toggle',
+          transition: {
+            duration: 200,
+            easing: 'ease-out',
+            styleProperties: [
+              { name: 'transform', value: 'scale(1.08)' },
+              { name: 'boxShadow', value: '0 12px 24px rgb(0 0 0 / 0.12)' },
+            ],
+          },
+        },
+      ],
+    },
+  ],
+};
+```
+
+Use `trigger: 'interest'` for accessible hover (mouse + keyboard focus).
+
+### Pointer-driven custom effect
+
+```typescript
+const config: InteractConfig = {
+  interactions: [
+    {
+      key: 'spotlight',
+      trigger: 'pointerMove',
+      params: { hitArea: 'root' },
+      effects: [
+        {
+          key: 'spotlight',
+          customEffect: (element, progress) => {
+            const x = progress.x * 100;
+            const y = progress.y * 100;
+            (element as HTMLElement).style.background = `radial-gradient(circle at ${x}% ${y}%, rgba(255,255,255,0.15), transparent 50%)`;
+          },
+        },
+      ],
+    },
+  ],
+};
+```
+
+## Configuration Schema
+
+```typescript
+type InteractConfig = {
+  interactions: Interaction[]; // REQUIRED
+  effects?: Record<string, Effect>;
+  sequences?: Record<string, SequenceConfig>;
+  conditions?: Record<string, Condition>;
+};
+
+type Interaction = InteractionTrigger & {
+  effects?: (Effect | EffectRef)[];
+  sequences?: (SequenceConfig | SequenceConfigRef)[];
+};
+
+// Triggers: hover | click | interest | activate | viewEnter | viewProgress |
+//           pointerMove | pageVisible | animationEnd
+
+// Effect discriminant (one per effect): keyframeEffect | namedEffect |
+//   customEffect | transition | transitionProperties
 ```
 
-## Tooling
+Each interaction needs at least one of `effects` or `sequences`. Types: [`config.ts`](packages/interact/src/types/config.ts). Full spec: [`full-lean.md`](packages/interact/rules/full-lean.md).
 
-- `yarn lint` – runs ESLint across all packages and apps using the shared config.
-- `yarn format` – formats the repo with Prettier's shared settings.
-- `yarn format:check` – verifies formatting without writing changes.
+## AI and Agent Support
 
-## Contributing
+### Rules files
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+**@wix/interact** (also on [GitHub Pages /rules/](https://wix.github.io/interact/rules/integration.md)):
+
+- [`integration.md`](packages/interact/rules/integration.md) — entry points, FOUC, static API
+- [`full-lean.md`](packages/interact/rules/full-lean.md) — complete config spec
+- [`viewenter.md`](packages/interact/rules/viewenter.md) · [`viewprogress.md`](packages/interact/rules/viewprogress.md)
+- [`hover.md`](packages/interact/rules/hover.md) · [`click.md`](packages/interact/rules/click.md) · [`pointermove.md`](packages/interact/rules/pointermove.md)
+
+**@wix/motion-presets** (repo only):
+
+- [`presets-main.md`](packages/motion-presets/rules/presets/presets-main.md) · [`entrance-presets.md`](packages/motion-presets/rules/presets/entrance-presets.md) · [`scroll-presets.md`](packages/motion-presets/rules/presets/scroll-presets.md) · [`ongoing-presets.md`](packages/motion-presets/rules/presets/ongoing-presets.md) · [`mouse-presets.md`](packages/motion-presets/rules/presets/mouse-presets.md)
+
+### Config generation guidelines
+
+- Always call `Interact.registerEffects(presets)` before `Interact.create()` when using `namedEffect`
+- 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'`, also set `initial` on the element to prevent FOUC
+
+### Repository agent context
+
+For monorepo layout, dependency graph, and CLI conventions, see [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md).
+
+## Live Demo and Documentation
+
+- [Landing page](https://wix.github.io/interact/)
+- [Examples gallery](https://wix.github.io/interact/examples.html)
+- [Documentation](https://wix.github.io/interact/docs/)
+- [Playground](https://wix.github.io/interact/playground/)
+
+## Development
+
+**Prerequisites:** Node.js ≥ 18, Yarn 4.10.3. Use the repo’s Node version:
+
+```bash
+nvm use
+yarn install
+yarn build
+yarn test
+```
+
+**Local apps:**
+
+```bash
+yarn dev:website    # landing + examples (http://localhost:3000)
+yarn dev:docs       # documentation app
+yarn dev:demo       # interactive demo app
+yarn workspace @wix/interact-playground run dev   # preset playground
+```
 
-- Setting up your development environment
-- Reporting bugs and proposing features
-- Pull request process and code standards
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow and standards.
 
 ## License
 

From c605e283a896c2d30e9014feffaed648021b6771 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Tue, 19 May 2026 17:32:19 +0300
Subject: [PATCH 2/7] Fixed format

---
 README.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 6f9f5008..dad3e26c 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew
 
 ## 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.
+**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`
@@ -22,11 +22,11 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew
 
 ## Packages
 
-| Package | Version | Description | Links |
-| --- | --- | --- | --- |
-| [`@wix/interact`](https://www.npmjs.com/package/@wix/interact) | 2.2.2 | Declarative interaction layer (main package) | [README](packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact) |
-| [`@wix/motion`](https://www.npmjs.com/package/@wix/motion) | 2.1.5 | Low-level animation engine | [README](packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion) |
-| [`@wix/motion-presets`](https://www.npmjs.com/package/@wix/motion-presets) | 1.0.2 | Ready-made animation presets | [npm](https://www.npmjs.com/package/@wix/motion-presets) · [preset rules](packages/motion-presets/rules/presets/presets-main.md) |
+| Package                                                                    | Version | Description                                  | Links                                                                                                                            |
+| -------------------------------------------------------------------------- | ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| [`@wix/interact`](https://www.npmjs.com/package/@wix/interact)             | 2.2.2   | Declarative interaction layer (main package) | [README](packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact)                                       |
+| [`@wix/motion`](https://www.npmjs.com/package/@wix/motion)                 | 2.1.5   | Low-level animation engine                   | [README](packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion)                                           |
+| [`@wix/motion-presets`](https://www.npmjs.com/package/@wix/motion-presets) | 1.0.2   | Ready-made animation presets                 | [npm](https://www.npmjs.com/package/@wix/motion-presets) · [preset rules](packages/motion-presets/rules/presets/presets-main.md) |
 
 ```
 @wix/motion ← @wix/interact (declarative layer)
@@ -281,7 +281,8 @@ const config: InteractConfig = {
           customEffect: (element, progress) => {
             const x = progress.x * 100;
             const y = progress.y * 100;
-            (element as HTMLElement).style.background = `radial-gradient(circle at ${x}% ${y}%, rgba(255,255,255,0.15), transparent 50%)`;
+            (element as HTMLElement).style.background =
+              `radial-gradient(circle at ${x}% ${y}%, rgba(255,255,255,0.15), transparent 50%)`;
           },
         },
       ],

From 2ae97b535859d89ce77148b266fbb493ca5d2670 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Wed, 20 May 2026 11:39:16 +0300
Subject: [PATCH 3/7] Small fixes

---
 README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index dad3e26c..6cd7e962 100644
--- a/README.md
+++ b/README.md
@@ -223,7 +223,7 @@ const config: InteractConfig = {
       effects: [
         {
           key: 'parallax-bg',
-          namedEffect: { type: 'ParallaxScroll', speed: 0.5, range: 'continuous' },
+          namedEffect: { type: 'ParallaxScroll', speed: 0.5 },
           rangeStart: { name: 'cover', offset: { unit: 'percentage', value: 0 } },
           rangeEnd: { name: 'cover', offset: { unit: 'percentage', value: 100 } },
           easing: 'linear',
@@ -282,7 +282,7 @@ const config: InteractConfig = {
             const x = progress.x * 100;
             const y = progress.y * 100;
             (element as HTMLElement).style.background =
-              `radial-gradient(circle at ${x}% ${y}%, rgba(255,255,255,0.15), transparent 50%)`;
+              `radial-gradient(circle at ${x}% ${y}%, rgb(255 255 255 / 0.15), transparent 50%)`;
           },
         },
       ],
@@ -307,7 +307,7 @@ type Interaction = InteractionTrigger & {
 };
 
 // Triggers: hover | click | interest | activate | viewEnter | viewProgress |
-//           pointerMove | pageVisible | animationEnd
+//           pointerMove | animationEnd
 
 // Effect discriminant (one per effect): keyframeEffect | namedEffect |
 //   customEffect | transition | transitionProperties
@@ -330,7 +330,7 @@ Each interaction needs at least one of `effects` or `sequences`. Types: [`config
 
 - [`presets-main.md`](packages/motion-presets/rules/presets/presets-main.md) · [`entrance-presets.md`](packages/motion-presets/rules/presets/entrance-presets.md) · [`scroll-presets.md`](packages/motion-presets/rules/presets/scroll-presets.md) · [`ongoing-presets.md`](packages/motion-presets/rules/presets/ongoing-presets.md) · [`mouse-presets.md`](packages/motion-presets/rules/presets/mouse-presets.md)
 
-### Config generation guidelines
+### AI generation guidelines
 
 - Always call `Interact.registerEffects(presets)` before `Interact.create()` when using `namedEffect`
 - Do not invent `namedEffect` types — use only registered presets (see preset rules above)
@@ -351,7 +351,7 @@ For monorepo layout, dependency graph, and CLI conventions, see [`AGENTS.md`](AG
 
 ## Development
 
-**Prerequisites:** Node.js ≥ 18, Yarn 4.10.3. Use the repo’s Node version:
+**Prerequisites:** Node.js ≥ 18. Use the repo’s Node version:
 
 ```bash
 nvm use
@@ -365,8 +365,8 @@ yarn test
 ```bash
 yarn dev:website    # landing + examples (http://localhost:3000)
 yarn dev:docs       # documentation app
-yarn dev:demo       # interactive demo app
-yarn workspace @wix/interact-playground run dev   # preset playground
+yarn dev:demo       # test demo app
+yarn workspace @wix/interact-playground run dev   # interactive playground
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow and standards.

From b92bbc09aed5d5c7f6c376e0b59e06114688ae71 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Wed, 20 May 2026 17:36:27 +0300
Subject: [PATCH 4/7] Fixed links and some cleanup

---
 README.md | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 6cd7e962..38c367d6 100644
--- a/README.md
+++ b/README.md
@@ -22,11 +22,11 @@ Web-native animation and interaction libraries — declarative, AI-ready, framew
 
 ## Packages
 
-| Package                                                                    | Version | Description                                  | Links                                                                                                                            |
-| -------------------------------------------------------------------------- | ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| [`@wix/interact`](https://www.npmjs.com/package/@wix/interact)             | 2.2.2   | Declarative interaction layer (main package) | [README](packages/interact/README.md) · [npm](https://www.npmjs.com/package/@wix/interact)                                       |
-| [`@wix/motion`](https://www.npmjs.com/package/@wix/motion)                 | 2.1.5   | Low-level animation engine                   | [README](packages/motion/README.md) · [npm](https://www.npmjs.com/package/@wix/motion)                                           |
-| [`@wix/motion-presets`](https://www.npmjs.com/package/@wix/motion-presets) | 1.0.2   | Ready-made animation presets                 | [npm](https://www.npmjs.com/package/@wix/motion-presets) · [preset rules](packages/motion-presets/rules/presets/presets-main.md) |
+| Package                                                                    | Version | Description                                  | Links                                                                                                                                            |
+| -------------------------------------------------------------------------- | ------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`@wix/interact`](https://www.npmjs.com/package/@wix/interact)             | 2.2.2   | 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://www.npmjs.com/package/@wix/motion)                 | 2.1.5   | 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://www.npmjs.com/package/@wix/motion-presets) | 1.0.2   | 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) |
 
 ```
 @wix/motion ← @wix/interact (declarative layer)
@@ -313,7 +313,7 @@ type Interaction = InteractionTrigger & {
 //   customEffect | transition | transitionProperties
 ```
 
-Each interaction needs at least one of `effects` or `sequences`. Types: [`config.ts`](packages/interact/src/types/config.ts). Full spec: [`full-lean.md`](packages/interact/rules/full-lean.md).
+Each interaction needs at least one of `effects` or `sequences`. Full spec: [`full-lean.md`](https://wix.github.io/interact/rules/full-lean.md).
 
 ## AI and Agent Support
 
@@ -321,14 +321,14 @@ Each interaction needs at least one of `effects` or `sequences`. Types: [`config
 
 **@wix/interact** (also on [GitHub Pages /rules/](https://wix.github.io/interact/rules/integration.md)):
 
-- [`integration.md`](packages/interact/rules/integration.md) — entry points, FOUC, static API
-- [`full-lean.md`](packages/interact/rules/full-lean.md) — complete config spec
-- [`viewenter.md`](packages/interact/rules/viewenter.md) · [`viewprogress.md`](packages/interact/rules/viewprogress.md)
-- [`hover.md`](packages/interact/rules/hover.md) · [`click.md`](packages/interact/rules/click.md) · [`pointermove.md`](packages/interact/rules/pointermove.md)
+- [`integration.md`](https://wix.github.io/interact/rules/integration.md) — entry points, FOUC, static API
+- [`full-lean.md`](https://wix.github.io/interact/rules/full-lean.md) — complete config spec
+- [`viewenter.md`](https://wix.github.io/interact/rules/viewenter.md) · [`viewprogress.md`](https://wix.github.io/interact/rules/viewprogress.md)
+- [`hover.md`](https://wix.github.io/interact/rules/hover.md) · [`click.md`](https://wix.github.io/interact/rules/click.md) · [`pointermove.md`](https://wix.github.io/interact/rules/pointermove.md)
 
 **@wix/motion-presets** (repo only):
 
-- [`presets-main.md`](packages/motion-presets/rules/presets/presets-main.md) · [`entrance-presets.md`](packages/motion-presets/rules/presets/entrance-presets.md) · [`scroll-presets.md`](packages/motion-presets/rules/presets/scroll-presets.md) · [`ongoing-presets.md`](packages/motion-presets/rules/presets/ongoing-presets.md) · [`mouse-presets.md`](packages/motion-presets/rules/presets/mouse-presets.md)
+- [`presets-main.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/presets-main.md) · [`entrance-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/entrance-presets.md) · [`scroll-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/scroll-presets.md) · [`ongoing-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/ongoing-presets.md) · [`mouse-presets.md`](https://github.com/wix/interact/blob/master/packages/motion-presets/rules/presets/mouse-presets.md)
 
 ### AI generation guidelines
 
@@ -340,11 +340,11 @@ Each interaction needs at least one of `effects` or `sequences`. Types: [`config
 
 ### Repository agent context
 
-For monorepo layout, dependency graph, and CLI conventions, see [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md).
+For monorepo layout, dependency graph, and CLI conventions, see [`AGENTS.md`](https://github.com/wix/interact/blob/master/AGENTS.md) and [`CLAUDE.md`](https://github.com/wix/interact/blob/master/CLAUDE.md).
 
 ## Live Demo and Documentation
 
-- [Landing page](https://wix.github.io/interact/)
+- [Website](https://wix.github.io/interact/)
 - [Examples gallery](https://wix.github.io/interact/examples.html)
 - [Documentation](https://wix.github.io/interact/docs/)
 - [Playground](https://wix.github.io/interact/playground/)
@@ -369,8 +369,8 @@ yarn dev:demo       # test demo app
 yarn workspace @wix/interact-playground run dev   # interactive playground
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow and standards.
+See [CONTRIBUTING.md](https://github.com/wix/interact/blob/master/CONTRIBUTING.md) for contribution workflow and standards.
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/wix/interact/blob/master/LICENSE)

From f3b12ba583f33c923de6670b0c4a28622b212962 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Wed, 20 May 2026 17:43:33 +0300
Subject: [PATCH 5/7] Moved accuracy notes to LLM guidelines

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 38c367d6..9fe13808 100644
--- a/README.md
+++ b/README.md
@@ -67,8 +67,6 @@ const config: InteractConfig = {
 };
 ```
 
-> **Accuracy notes:** `effects` at the config top level is a reusable `Record<string, Effect>`. `add` and `remove` are standalone imports, not instance methods. Call `Interact.registerEffects(presets)` before `Interact.create()` when using `namedEffect`. `<interact-element>` must wrap exactly one child (the library targets `.firstElementChild`).
-
 ### Web Components (recommended)
 
 Pre-render CSS with `generate()` to avoid a flash of unstyled content on entrance animations, then boot the runtime:
@@ -337,6 +335,8 @@ Each interaction needs at least one of `effects` or `sequences`. Full spec: [`fu
 - 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'`, also set `initial` on the element to prevent FOUC
+- `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).
 
 ### Repository agent context
 

From 5ed2177eeb16ab82da865b396246144c4df3fbff Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Wed, 20 May 2026 17:53:27 +0300
Subject: [PATCH 6/7] Improve Web Components integration example

---
 README.md | 38 ++++++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 9fe13808..1a7c65d0 100644
--- a/README.md
+++ b/README.md
@@ -69,17 +69,38 @@ const config: InteractConfig = {
 
 ### Web Components (recommended)
 
-Pre-render CSS with `generate()` to avoid a flash of unstyled content on entrance animations, then boot the runtime:
+Pre-render CSS with `generate()` to avoid a flash of unstyled content on entrance animations:
 
 ```typescript
-import { Interact, generate } from '@wix/interact/web';
+import { generate } from '@wix/interact';
+
+const css = generate(config, true); // `true` = use :first-child as default selectors
+
+// then inject into <head>
+```
+
+In HTML template add:
+
+```html
+<head>
+  <style>
+    ${css}
+    /* Optional — keep the custom element from affecting layout */
+    interact-element {
+      display: contents;
+    }
+  </style>
+</head>
+```
+
+Then boot the runtime:
+
+```typescript
+import { Interact } from '@wix/interact/web';
 import * as presets from '@wix/motion-presets';
 
 Interact.registerEffects(presets);
 
-const css = generate(config, true); // `true` = use :first-child selectors for <interact-element>
-document.head.insertAdjacentHTML('beforeend', `<style id="interact-critical">${css}</style>`);
-
 Interact.create(config);
 ```
 
@@ -91,13 +112,6 @@ Interact.create(config);
 </interact-element>
 ```
 
-```css
-/* Optional — keep the custom element from affecting layout */
-interact-element {
-  display: contents;
-}
-```
-
 ### React
 
 Wrap `Interact.create()` in `useEffect` and destroy on cleanup. Use `<Interaction>` instead of raw elements:

From abe2a29c79504624c21f0c149b981ebc045339d5 Mon Sep 17 00:00:00 2001
From: Yehonatan Daniv <maggotfish@gmail.com>
Date: Wed, 20 May 2026 17:56:57 +0300
Subject: [PATCH 7/7] Improved text

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1a7c65d0..d2984d89 100644
--- a/README.md
+++ b/README.md
@@ -139,7 +139,7 @@ function App() {
 }
 ```
 
-Inject `generate(config, false)` output into your document shell (e.g. Remix `links`, Next.js layout `<head>`) the same way as the Web Components example.
+Inject `generate(config, false)` output into your document's `<head>` (e.g. Remix `links`, Next.js layout `<head>`) the same way as the Web Components example.
 
 ### Vanilla JS