diff --git a/skills/interactor/SKILL.md b/skills/interactor/SKILL.md index fabf975e..cb00014d 100644 --- a/skills/interactor/SKILL.md +++ b/skills/interactor/SKILL.md @@ -1,6 +1,6 @@ --- name: interactor -description: 'Install, integrate, and configure Interact — @wix/interact — declarative interactions library — to add or edit hover/click/view triggered, scroll-driven, and pointer-driven animations on a webpage or web app. Use whenever the user wants to add or change animations, in general, or with @wix/interact or @wix/motion(-presets); wire animations to scroll, viewport-enter, hover, click, or mouse-move; build entrance / parallax / stagger / tilt / reveal effects; install or set up @wix/interact (vanilla JS, React, or Web Components); or edit an existing interact config. Trigger even on phrasings like "fade in on scroll", "parallax background", "stagger the cards in", "hover-scale the button", or "tilt toward the mouse" in a project using these packages. Do NOT use for other animation libraries.' +description: 'Use when user asks to add/edit motion without specific library, or with @wix/interact - hover, click, view/scroll triggered, scroll-driven, and pointer-driven animations for web. Wire animations to user interactions; install or set up @wix/interact; or edit an existing interact config. Do NOT use for other animation libraries.' --- # Interactor — build interactions with @wix/interact @@ -39,11 +39,8 @@ full schema, the preset catalog, and per-trigger rules. Don't try to hold it all in your head; the references are the source of truth. For static or pre-rendered output (agent-authored HTML, SSG, static export), -prefer generating all CSS after validation at generation/build time and embedding -it in the shipped HTML. If only part of the config is available then, split the -config: generate and embed the static part at generation time, and generate the -runtime-dependent part in the browser. If splitting is impractical, generating -the complete CSS at runtime is an acceptable fallback. +follow the canonical CSS generation policy in +`references/integration-recipes.md`. --- @@ -60,10 +57,8 @@ npm install -D @wix/interact-validate # optional — permanent dev/CI config g A no-build / plain-HTML site can skip npm and import Interact from a CDN for runtime wiring — see the CDN recipe in `references/integration-recipes.md`. -Prefer producing CSS from `generate()` at **generation time** (Node scratch -script) and embedding it before deploy. Split out runtime-dependent interactions -when necessary, or fall back to runtime generation. CDN pages skip the validate -package install; the agent validates configs without shipping the validator. +CDN pages skip the validate package install; the agent validates configs without +shipping the validator. --- @@ -73,8 +68,8 @@ package install; the agent validates configs without shipping the validator. import and a couple of flags). Decision procedure: 1. **React / Next / any JSX project** (a `package.json` with `react`, `.jsx`/`.tsx` files) → use `@wix/interact/react` with the `` component. -2. **Static / pre-rendered HTML** (agent-generated `.html`, SSG export, Astro/Eleventy/Hugo output) → use `@wix/interact/web` with ``. Prefer running `generate()` in a build/generation script and embedding CSS in the HTML output. Split static and runtime-dependent config when needed; fall back to runtime generation if it cannot be pre-generated. -3. **Plain HTML, no bundler** (hand-edited static `.html`, CDN runtime) → same as (2): pre-bake as much CSS as possible at generation time; use the CDN at runtime for `create()` and any CSS that could not be generated earlier. +2. **Static / pre-rendered HTML** (agent-generated `.html`, SSG export, Astro/Eleventy/Hugo output) → use `@wix/interact/web` with `` and follow the canonical CSS policy in `references/integration-recipes.md`. +3. **Plain HTML, no bundler** (hand-edited static `.html`, CDN runtime) → same as (2), using the CDN recipe for runtime wiring. 4. **Bundled vanilla JS / other framework** (Vite/Webpack but no React, or Vue/Svelte/Angular) → use `@wix/interact/web` (Web Components are framework-agnostic) **or** the base `@wix/interact` vanilla API. Prefer `/web` unless the user wants to control binding manually. If you can't tell, ask the user which framework the page uses. The full @@ -87,27 +82,23 @@ Prefer two phases — **generation/build** (all CSS possible) and **runtime** ```ts // Generation/build script (Node, SSG, agent scratch) -import { generate } from '@wix/interact/web'; // or /react, or '@wix/interact' +import { Interact, generate } from '@wix/interact/web'; // or /react, or '@wix/interact' import { FadeIn } from '@wix/motion-presets'; Interact.registerEffects({ FadeIn }); // BEFORE generate() — see invariants const css = generate(config, /* useFirstChild */ true); // true=web, false=react/vanilla -// Write css into the HTML output — see CSS delivery below +// Deliver css according to the canonical policy in integration-recipes.md ``` ```ts // Runtime (browser bundle / CDN module) import { Interact } from '@wix/interact/web'; -// If needed, generate and inject CSS for the runtime-only config before create(). const instance = Interact.create(config); // wire triggers ``` -**CSS delivery** — embed the `generate()` string in the shipped HTML using one of: - -- `` in `` (preferred) -- `` in `` (write `interact.css` as a separate file) -- `` or `` at the **start of ``** when render-blocking is needed to prevent FOUC +For CSS delivery and runtime-only configs, follow the canonical policy in +`references/integration-recipes.md`. (For CDN/quick-start, `import * as presets` + `registerEffects(presets)` is fine at generation time — selective imports just keep bundled apps lean. See `references/presets.md`.) @@ -188,9 +179,8 @@ construct the config statically: every `severity: 'error'`, then **remove** the call, import, any `esm.sh` import, and any temp devDep. Prefer a dev-only validation script when the config builder module is importable in isolation (no removal step). Full loop in - `references/validate.md`. For static site output where config is derivable at - build time (per-page data, CMS at build), run `generate()` in the build step — - not in the browser bundle. + `references/validate.md`. For static site output, follow the canonical CSS + generation policy in `references/integration-recipes.md`. - **Permanent guard (opt-in, separate):** leaving `assertValidInteractConfig` in shipped code as a devDependency CI gate is only when scaffolding a new project or the user explicitly asks — do not conflate with the temporary injection above. @@ -240,18 +230,10 @@ animation no-ops. Apply them every time, even if you don't open a reference file (``) entry point, `false` for **vanilla** and **React**. Backwards = the FOUC-prevention selectors target the wrong node and break. -3. **FOUC prevention — prefer pre-rendered `generate()` CSS.** For static/pre-rendered - sites, generate and embed as much CSS as possible at build/generation time — in - `` (`` in `` (preferred) -- `` in `` (write `interact.css` as a separate file) -- `` or `` at the **start of ``** when render-blocking is needed to prevent FOUC - **`useFirstChild`:** `true` for the **web** (``) entry point — selectors target `:first-child`; `false` for **vanilla** and **React**. The default is `true`, so vanilla/React callers must pass `false` explicitly. @@ -377,10 +367,8 @@ the generated rules hide the child targets on their own — no extra markup on t trigger element. For `repeat`/`alternate`/`state`, inline the starting keyframe and use `fill: 'both'`. `viewProgress` needs no FOUC rules. -FOUC prevention works best when `generate()` output is embedded in the HTML at -build/generation time. For runtime-generated portions, inject the CSS before the -corresponding `Interact.create()` call and before revealing initially hidden -content. +For when and where to emit this CSS, follow the canonical static/pre-rendered +policy in `references/integration-recipes.md`. For the web entry point, `interact-element { display: contents; }` is **optional** — add it if you don't want the custom-element wrapper to participate in layout (the diff --git a/skills/interactor/references/integration-recipes.md b/skills/interactor/references/integration-recipes.md index 1c49cd4e..d346b64f 100644 --- a/skills/interactor/references/integration-recipes.md +++ b/skills/interactor/references/integration-recipes.md @@ -9,16 +9,29 @@ Shared rules that apply to **every** recipe: - `Interact.registerEffects(presets)` runs **before** `generate()` / `create()`. - `generate(config, useFirstChild)`: `true` for **web**, `false` for **vanilla/React**. -- **Prefer pre-rendering all CSS at build/generation time** for static or - pre-rendered output. If some interactions depend on runtime-only data, split - them into a separate config and generate/inject that CSS before its - `Interact.create()` call. If splitting is impractical, runtime generation for - the complete config is an acceptable fallback. Embed pre-generated CSS in - `` (`` in `` (preferred) +- `` in `` +- `` or + `` at the + **start of ``** when render-blocking is needed to prevent FOUC + +If some interactions depend on runtime-only data, split them into a separate +config: pre-generate the static config, then generate and inject the +runtime-dependent config in the browser before its `Interact.create()` call. If +splitting is impractical, generating the complete CSS at runtime is an acceptable +fallback; apply it before revealing initially hidden content. + --- ## A. Web Components — `@wix/interact/web` @@ -75,17 +88,9 @@ export const instance = Interact.create(config); // binds s au ## B. CDN / no build step — `@wix/interact/web` via [esm.sh](https://esm.sh) -For a static `.html` page with no bundler, prefer pre-rendering the complete CSS -at generation time (Node scratch script) and embedding it before deploy. If part -of the config is only available in the browser, split and generate that part at -runtime before `create()`; if splitting is impractical, generate the complete -config at runtime. - -Embed the pre-generated CSS using one of: - -- `` in `` (preferred) -- `` in `` -- `` or `` at the **start of ``** when render-blocking is needed to prevent FOUC +For a static `.html` page with no bundler, follow the +[canonical CSS generation policy](#css-generation-policy-for-static-and-pre-rendered-output); +a Node scratch script can pre-generate the CSS before deploy. ```html @@ -198,11 +203,10 @@ export function Hero() { valid intrinsic props for `tagName`. For an element you don't want to wrap, use `createInteractRef(key)` on a plain element that carries `data-interact-key`. -For SSR frameworks (Next, Remix), prefer calling `generate(config, false)` during -render/build and emitting the CSS in `` (`