Merge branch 'master' of github.com:wix/interact into reduced-motion-fix

Author: ameerf-wix

.cursor/plans/fix_entrance_fouc_fc913a84.plan.md

@@ -0,0 +1,43 @@
+---
+name: Fix entrance FOUC
+overview: Prevent delayed entrance flashes without changing IntersectionObserver geometry by making the transient neutral styles author-important, using real zero delays, and giving entrance effects backwards fill by default. Align validation, documentation, and Interactor guidance with the runtime behavior.
+todos:
+  - id: important-initial-css
+    content: Emit author-important transient FOUC declarations and preserve true zero animation delays
+    status: completed
+  - id: entrance-fill-defaults
+    content: Default every entrance preset descriptor to backwards fill while preserving explicit overrides
+    status: completed
+  - id: validation-guidance
+    content: Add backwards-fill validation guidance and align Interact docs, rules, and Interactor skill
+    status: completed
+  - id: regression-tests
+    content: Cover CSS serialization, timing, all entrance presets, validator behavior, and run targeted verification
+    status: completed
+isProject: false
+---
+
+# Fix Delayed Entrance FOUC
+
+## Implementation
+
+- Extend the internal declaration shape in [`packages/interact/src/types/css.ts`](packages/interact/src/types/css.ts) with an `important` flag and serialize it in [`packages/interact/src/core/cssUtils.ts`](packages/interact/src/core/cssUtils.ts). Mark every [`DEFAULT_INITIAL`](packages/interact/src/core/css.ts) declaration important so `visibility: hidden` and neutral transform properties override pre-trigger animation values, while retaining the existing `:not([data-interact-enter])` lifecycle.
+- In [`packages/motion/src/api/cssAnimations.ts`](packages/motion/src/api/cssAnimations.ts), replace the synthetic `delay || 1` fallback with `delay ?? 0`. Do not add the proposed `0.1ms` initial override, because it would alter computed sequence timing and could move a playing animation back from its active phase into its delay phase.
+- Add a small `getEntranceFill()` helper in [`packages/motion-presets/src/utils.ts`](packages/motion-presets/src/utils.ts), returning `options.fill ?? 'backwards'`. Apply it after `...options` to every animation descriptor in all 19 modules under [`packages/motion-presets/src/library/entrance/`](packages/motion-presets/src/library/entrance/) so both CSS and WAAPI paths default to backwards fill while explicit `none`, `forwards`, or `both` values remain authoritative.
+
+## Validation and guidance
+
+- Add an informational `RECOMMENDED_FILL_BACKWARDS` semantic check in [`packages/interact-validate/src/semantic/recommendedPatterns.ts`](packages/interact-validate/src/semantic/recommendedPatterns.ts), wire it through [`collectSemanticWarnings.ts`](packages/interact-validate/src/semantic/collectSemanticWarnings.ts) and [`errors.ts`](packages/interact-validate/src/errors.ts), and recommend explicit `backwards` or `both` for effective `viewEnter`/`once` animation effects, including nested sequence effects. Keep this advisory so preset defaults remain a safety net rather than a schema requirement.
+- Update the authoritative entrance/FOUC guidance and generated CSS examples in [`packages/interact/rules/viewenter.md`](packages/interact/rules/viewenter.md), [`packages/interact/rules/full-lean.md`](packages/interact/rules/full-lean.md), [`packages/interact/docs/api/functions.md`](packages/interact/docs/api/functions.md), and [`packages/interact/docs/examples/entrance-animations.md`](packages/interact/docs/examples/entrance-animations.md): explain the important neutral pre-trigger rule, use `fill: 'backwards'` for `once`, and reserve `both` for effects that must retain their final keyframe.
+- Update the repository Interactor source in [`skills/interactor/SKILL.md`](skills/interactor/SKILL.md) plus its `config-schema`, `triggers`, `integration-recipes`, and `validate` references. Make explicit backwards fill an invariant in generated `viewEnter`/`once` configs and update the relevant eval expectation; do not manually edit external installed skill snapshots.
+
+## Regression coverage
+
+- Update [`packages/interact/test/css.spec.ts`](packages/interact/test/css.spec.ts) and [`cssUtils.spec.ts`](packages/interact/test/cssUtils.spec.ts) to verify important initial declarations are emitted only for eligible same-element `viewEnter`/`once` effects and disappear from the post-start selector.
+- Update [`packages/motion/test/motion.spec.ts`](packages/motion/test/motion.spec.ts) to assert omitted/zero delay produces `0ms`, while positive delays remain unchanged.
+- Add centralized entrance-preset tests covering all 19 exports: every generated descriptor defaults to `backwards`, and an explicit fill value is preserved. Retain existing per-preset behavior tests and add coverage for the currently untested `ExpandIn` export through this matrix.
+- Add validator tests for direct effects, referenced registry effects, sequence effects, implicit `once`, accepted `backwards`/`both`, and informational severity/category overrides.
+
+## Verification
+
+- Run `nvm use`, then targeted tests and type checks for `@wix/motion`, `@wix/motion-presets`, `@wix/interact`, and `@wix/interact-validate`; finish with repository lint/format checks for touched files.

.github/workflows/release-splittext.yml

@@ -80,6 +80,14 @@ jobs:
       - name: Build splittext package
         run: yarn workspace @wix/splittext build
 
+      # @wix/interact is a devDependency used only by the plugin-bridge integration test —
+      # splittext itself neither builds nor runs against it (note the build step above runs first).
+      - name: Build motion package (test-only dependency of @wix/interact)
+        run: yarn workspace @wix/motion build
+
+      - name: Build interact package (test-only dependency)
+        run: yarn workspace @wix/interact build
+
       - name: Test splittext package
         run: yarn workspace @wix/splittext test
 

CHANGELOG.md

@@ -10,6 +10,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/splittext
 
+### [0.2.0] - unreleased
+
+#### Added
+
+- `@wix/splittext/plugin` entry points: `splitTextPlugin` for `Interact.use()`, and `splitTextStyle` for `generate()` (#275)
+- `hideUntilReady`: `splitTextStyle` hides the container until the runtime split sets `data-splittext-ready` (#275)
+
 ### [0.1.2] - 2026-07-14
 
 #### Added
@@ -26,6 +33,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact-validate
 
+### [0.2.0] - unreleased
+
+#### Added
+
+- Plugin fields: `$`-prefixed keys on interactions and effects are accepted; every other unknown key is still reported as `SCHEMA_UNRECOGNIZED_KEYS` (#275)
+
+#### Changed
+
+- `KEYFRAME_PROP_NOT_CAMEL_CASE` (rule category `KEYFRAME_STYLE`) is replaced by `INVALID_CSS_PROPERTY_NAME` (rule category `CSS_PROPERTY_NAME`): both camelCase and kebab-case CSS property names are valid input, so only names that are neither are reported, and the check now covers `transition.styleProperties` / `transitionProperties` names in addition to `keyframeEffect` keyframes
+- `severityOverrides` keyed on `KEYFRAME_STYLE` are now silently ignored. Rename the key to `CSS_PROPERTY_NAME` to keep an override in effect
+
+### [0.1.2] - 2026-07-29
+
+#### Added
+
+- `RECOMMENDED_FILL_BACKWARDS` semantic check nudging `viewEnter` + `once` keyframe/named effects without FOUC hiding rules to set `fill: 'backwards'` or `'both'` (#277)
+
+#### Changed
+
+- README rule catalog updated for `RECOMMENDED_FILL_BACKWARDS` (#277)
+
 ### [0.1.1] - 2026-07-14
 
 #### Added
@@ -53,17 +81,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact
 
-### [2.6.0] - 2026-07-28
+### [2.6.0] - unreleased
 
 #### Added
 
+- Generic plugin bridge: `Interact.use(name, plugin)` registers a plugin, and a `$<name>` field on an interaction or effect (#275)
+- `generate()` accepts a `plugins` option — a map of plugin name → build-time style generator (#275)
 - Reduced motion is now detected from the browser: `Interact.forceReducedMotion` reads `prefers-reduced-motion` unless it was set explicitly, and the browser setting is re-read as each interaction is bound
 - `generate()` accepts a third `options` argument and emits `@media (prefers-reduced-motion: reduce)` overrides by default — animations that run once collapse to `1ms` and land on their end state, perpetual and scroll-driven animations are turned off, transitions are dropped. Pass `{ reducedMotion: false }` to opt out
 
 #### Changed
 
+- `generate(config, options?)`: the second argument now accepts an options bag — `{ useFirstChild?, plugins? }` — exported as the `GenerateOptions` (#275)
+- CSS property names may be authored in either camelCase or kebab-case in `transition.styleProperties`, `transitionProperties` and `keyframeEffect.keyframes`; state-effect properties are normalized to kebab-case for the generated CSS (state rules and the `transition:` shorthand) and keyframes to camelCase for WAAPI
 - `Interact.forceReducedMotion = false` now means "ignore the browser setting and animate" instead of "use the default"; assign `undefined` to go back to browser detection
 
+#### Fixed
+
+- camelCase property names in `transition.styleProperties` / `transitionProperties` are now normalized to kebab-case
+- CSS custom properties in keyframes (e.g. `--fooBar`) are no longer lower-cased when emitted into `@keyframes`
+- Vendor-prefixed keyframe properties (e.g. `webkitTextStroke`) now emit a valid CSS property name (`-webkit-text-stroke`)
+
+### [2.5.5] - 2026-07-29
+
+#### Fixed
+
+- Entrance FOUC prevention: `generate()` initial rules now emit `!important` on transform neutralization declarations so they override inline styles until the animation starts (#277)
+
+#### Changed
+
+- `viewEnter` rules and docs recommend `fill: 'backwards'` (or `'both'`) for entrance animations; CSS rule declarations support an optional `important` flag (#277)
+
 ### [2.5.4] - 2026-07-16
 
 #### Fixed
@@ -270,12 +318,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 #### Added
 
+- `toCSSPropertyName()`, `toWAAPIPropertyName()` and `normalizeKeyframes()` utilities for converting CSS property names between their CSS and WAAPI forms
 - `getCSSAnimation()` accepts a `{ reducedMotion }` option so generated CSS can express the same reduced-motion behavior as the Web Animations path — animations that run once collapse to a `1ms` duration, while perpetual and scrub-driven animations are skipped
 
 #### Changed
 
+- Keyframe property names may be authored in either camelCase or kebab-case and are normalized to WAAPI's camelCase on every animation path — `keyframeEffect`, presets, and effects registered via `registerEffects()`
 - The reduced-motion rule shared by the Web Animations and CSS paths lives in a single `getReducedMotionOptions()` helper
 
+### [2.1.8] - 2026-07-29
+
+#### Added
+
+- `getWebAnimation()` accepts SVG elements (and any `Element`) as keyframe targets, not only `HTMLElement` (#280)
+
+#### Changed
+
+- `getCSSAnimation()` delay serialization: use `0ms` when `delay` is `0` instead of previously defaulting to `1ms` (#277)
+
 ### [2.1.7] - 2026-05-29
 
 #### Added
@@ -354,6 +414,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/motion-presets
 
+### [1.0.4] - 2026-07-29
+
+#### Changed
+
+- Entrance presets default to `fill: 'backwards'` via `getEntranceFill()` unless overridden (#277)
+
 ### [1.0.3] - 2026-05-29
 
 #### Changed

apps/demo/package.json

@@ -7,11 +7,11 @@
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
-    "lint": "tsc --noEmit",
-    "test": "vitest run"
+    "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@wix/interact": "^2.5.4",
+    "@wix/interact": "^2.5.5",
+    "@wix/splittext": "^0.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },

apps/demo/src/plugins/splitText.ts

@@ -0,0 +1,29 @@
+/**
+ * Demo-side glue for the reusable `@wix/splittext` Interact plugin.
+ *
+ * The plugin itself now lives in `@wix/splittext/plugin`, which ships WITHOUT a dependency on
+ * `@wix/interact` so the two packages stay decoupled. This file is where the demo — the one place
+ * that depends on BOTH — "resolves the typing":
+ *
+ *  1. It binds the package's structurally-typed callbacks to Interact's real `InteractPlugin` /
+ *     `InteractPluginStyleGenerator` contract. The assignments below double as a compile-time
+ *     check that `@wix/splittext/plugin` stays compatible with `@wix/interact`.
+ *  2. It ties the `$splitText` config field to {@link SplitTextPluginConfig} via declaration
+ *     merging on `InteractPluginConfigMap`, so demo configs get autocomplete + checking.
+ */
+import type { InteractPlugin, InteractPluginStyleGenerator } from '@wix/interact';
+import {
+  splitTextPlugin as splitTextPluginImpl,
+  splitTextStyle as splitTextStyleImpl,
+  type SplitTextPluginConfig,
+} from '@wix/splittext/plugin';
+
+export const splitTextPlugin: InteractPlugin = splitTextPluginImpl;
+export const splitTextStyle: InteractPluginStyleGenerator = splitTextStyleImpl;
+export type { SplitTextPluginConfig };
+
+declare module '@wix/interact' {
+  interface InteractPluginConfigMap {
+    splitText: SplitTextPluginConfig;
+  }
+}

apps/demo/tsconfig.json

@@ -8,7 +8,8 @@
       "@/*": ["./src/*"],
       "@wix/interact/web": ["../../packages/interact/src/web"],
       "@wix/interact/react": ["../../packages/interact/src/react"],
-      "@wix/interact": ["../../packages/interact/src/index"]
+      "@wix/interact": ["../../packages/interact/src/index"],
+      "@wix/splittext/plugin": ["../../packages/splittext/dist/types/plugin/index"]
     }
   },
   "include": ["src"],

apps/docs/package.json

@@ -11,7 +11,7 @@
     "test": "echo 'No tests yet'"
   },
   "dependencies": {
-    "@wix/interact": "^2.5.4",
+    "@wix/interact": "^2.5.5",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-markdown": "^9.0.1",

apps/playground/SPEC.md

@@ -339,7 +339,7 @@ For authoring custom `keyframeEffect` animations (`{ name: string; keyframes: Ke
   - Optional `offset` (0–1, step 0.01) — shown for 3+ keyframes
   - CSS property/value rows with text inputs
   - Property name autocomplete via `<datalist>` (opacity, transform, background-color, clip-path, filter, border-radius, etc.)
-  - Kebab-case input auto-converts to camelCase on blur (Web Animations API requirement)
+  - Kebab-case input auto-converts to camelCase on blur (display preference — Interact accepts either casing)
   - Add/remove property rows (min 1 per keyframe)
 - **Add Keyframe** button — appends an empty keyframe
 - Remove keyframe button (min 1 keyframe enforced)

apps/playground/package.json

@@ -10,8 +10,8 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
-    "@wix/interact": "^2.5.4",
-    "@wix/motion-presets": "^1.0.3"
+    "@wix/interact": "^2.5.5",
+    "@wix/motion-presets": "^1.0.4"
   },
   "devDependencies": {
     "typescript": "^5.9.3",