@pieai/swimmer-ui-kit 1.9.0 → 1.10.1

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.10.1
+
+### Fixed
+
+- **`<LiquidGroup>` threw where `window` exists and `matchMedia` does not.**
+  The reduced-motion hook guarded on `typeof window === 'undefined'`, which is
+  true in node and false in jsdom — and jsdom has no `matchMedia`. Any consumer
+  testing in jsdom, and any server render that shims `window`, hit a TypeError
+  inside a `useState` initializer. Both the initializer and the subscription now
+  ask for the function itself. The kit's own suite runs in node, so the middle
+  case had never been exercised; a regression test now pins it.
+
+## 1.10.0
+
+### Added
+
+- **`motion="follow"` for selection and progress.** `<LiquidGroup>` now carries
+  the donor's Move surface through the token layer and shared animation and
+  filter-area budgets. It is used only by `GameSegmentedControl`'s selected
+  indicator and `GameProgress`'s leading edge; the shared clock sleeps
+  completely at rest.
+- **Optional static waviness on `<LiquidGroup>`.** The new group-level
+  `waviness` and `wavinessFreq` knobs adapt the pinned liquid-gooey noise
+  displacement so merged silhouettes read as fluid instead of as two rounded
+  rectangles. The displaced `shape` feeds both SVG shadow passes and the final
+  SVG raster shadow, so the shadow follows the same edge. The token default is
+  `0` to preserve existing output; the recommended brand preset is `6px` at
+  `0.018`, with `3px`/`0.022` and `10px`/`0.014` available as conservative and
+  bold points on the same intensity axis. The noise is fixed-seed and static,
+  so it adds no idle animation clock. Its maximum displacement is reserved in
+  the filter region and counted by the 480,000 px² budget.
+
+### Fixed
+
+- **`<LiquidGroup>` drew nothing under React StrictMode.** The effect cleanup
+  marked the memoized engine disposed for good, so StrictMode's second mount
+  acquired its budget, reported an active group, and then returned early from
+  `wake()`. The merged path's `d` stayed empty, which meant every app rendering
+  under StrictMode — that is, every app we ship — got no Morph and no Move at
+  all, with nothing in the console to say so. `register()` now revives a
+  disposed engine and resets the observer and listener state with it, a
+  StrictMode regression test asserts the path is not empty, and the
+  budget-exhausted path warns once in development instead of degrading in
+  silence. Storybook runs with StrictMode on.
+
 ## 1.9.0
 
 ### Added
@@ -21,6 +66,14 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
   merge — that is the bug this prop exists to remove, and the story documents
   it as a rule rather than a preference.
 
+### Fixed
+
+- **The `LiquidGroup` stories now demonstrate the supported composition.** The
+  demo buttons reset their browser border and background so they do not paint
+  hard-edged content-layer circles over the merged silhouette. The stories now
+  show the continuous outline on `LiquidGroup`, with a dedicated
+  `stroke` + `shadow` example that makes the group-owned treatment explicit.
+
 ## 1.8.1
 
 ### Fixed

package/NOTICE

@@ -40,15 +40,28 @@ implementation informed by the `liquid-gooey` package in the Libraries
 repository (https://github.com/Jakubantalik/Libraries/tree/main/packages/liquid-gooey),
 Copyright (c) 2026 Jakub Antalik, licensed under the MIT License.
 
+The reviewed upstream state is pinned in `donors-individual-lock.json` at commit
+`3862ffa345217443b63696a8c331a0664eea4b04`; the package source lives at
+`packages/liquid-gooey/` in that repository. The combined-workspace review
+checkout is `<portfolio-root>/_donors-individual/for_SwimmerUIKit/` and is not
+packaged or loaded at runtime.
+
 We took the donor's morph-specific ideas and small implementation patterns:
 the SVG silhouette/content split, the Gaussian-blur plus alpha color-matrix
 filter, rounded-rectangle geometry, token-compatible shadow passes, and spring
-to easing compilation. We did not take its move, melt, bend, or dissolve
-systems, its general observer, or its image-melt engine. We changed the
-implementation for this kit by making fill and shadow values token-driven,
-adding a process-wide animated-group and filter-area budget, and putting the
-shared requestAnimationFrame clock to sleep after stillness. The actual
-interactive content remains outside the filtered SVG layer.
+to easing compilation. We also adapted its Move center spring, velocity-axis
+stretch, and lagging tail/mid-droplet physics for the selected segmented
+indicator and progress leading edge. This package now directly adapts the
+donor's group-level `waviness` / `wavinessFreq` filter pass: a fixed-seed
+`feTurbulence` field and `feDisplacementMap` move the silhouette before its
+shadow passes consume it, so the shadow follows the same edge. We did not take
+the donor's melt, bend, or dissolve systems, its general observer, or its
+image-melt engine. We changed the implementation for this kit by making fill
+and shadow values token-driven, keeping waviness static with a shipped-off
+token default, adding a process-wide animated-group and filter-area budget
+that includes the displacement slack, and putting the shared
+requestAnimationFrame clock to sleep after stillness. The actual interactive
+content remains outside the filtered SVG layer.
 
 The MIT License text for that material:
 

package/dist/index.d.ts

@@ -268,6 +268,45 @@ export declare const CLAY_LAYER_TOKENS: {
     readonly toast: "var(--game-ui-z-toast)";
 };
 
+/**
+ * Token references for the adopted liquid-gooey Move physics. The values are
+ * deliberately numeric custom properties so a host theme can tune the feel
+ * without putting physics constants in the engine.
+ */
+declare const CLAY_LIQUID_GOOEY_TOKENS: {
+    readonly moveStiffness: "var(--game-ui-liquid-gooey-move-stiffness)";
+    readonly moveDamping: "var(--game-ui-liquid-gooey-move-damping)";
+    readonly moveStretch: "var(--game-ui-liquid-gooey-move-stretch)";
+    readonly moveTail: "var(--game-ui-liquid-gooey-move-tail)";
+    readonly moveForce: "var(--game-ui-liquid-gooey-move-force)";
+    readonly moveTailSpringStiffness: "var(--game-ui-liquid-gooey-move-tail-spring-stiffness)";
+    readonly moveTailSpringDamping: "var(--game-ui-liquid-gooey-move-tail-spring-damping)";
+    readonly moveStretchSpeed: "var(--game-ui-liquid-gooey-move-stretch-speed)";
+    readonly moveStretchSquash: "var(--game-ui-liquid-gooey-move-stretch-squash)";
+    readonly moveSpeedThreshold: "var(--game-ui-liquid-gooey-move-speed-threshold)";
+    readonly moveTailOnsetSpeed: "var(--game-ui-liquid-gooey-move-tail-onset-speed)";
+    readonly moveTailOnsetRange: "var(--game-ui-liquid-gooey-move-tail-onset-range)";
+    readonly moveTailRamp: "var(--game-ui-liquid-gooey-move-tail-ramp)";
+    readonly moveTailMinRadius: "var(--game-ui-liquid-gooey-move-tail-min-radius)";
+    readonly moveTailWobble: "var(--game-ui-liquid-gooey-move-tail-wobble)";
+    readonly moveTailPhaseSpeed: "var(--game-ui-liquid-gooey-move-tail-phase-speed)";
+    readonly moveTailMidpointA: "var(--game-ui-liquid-gooey-move-tail-midpoint-a)";
+    readonly moveTailMidpointB: "var(--game-ui-liquid-gooey-move-tail-midpoint-b)";
+    readonly moveTailMidRadiusA: "var(--game-ui-liquid-gooey-move-tail-mid-radius-a)";
+    readonly moveTailMidRadiusB: "var(--game-ui-liquid-gooey-move-tail-mid-radius-b)";
+    readonly moveTailWobblePhase: "var(--game-ui-liquid-gooey-move-tail-wobble-phase)";
+    readonly moveMinPerpendicular: "var(--game-ui-liquid-gooey-move-min-perpendicular)";
+    readonly moveLagBase: "var(--game-ui-liquid-gooey-move-lag-base)";
+    readonly moveLagForce: "var(--game-ui-liquid-gooey-move-lag-force)";
+    readonly moveSettleDistance: "var(--game-ui-liquid-gooey-move-settle-distance)";
+    readonly moveSettleSpeed: "var(--game-ui-liquid-gooey-move-settle-speed)";
+    readonly moveIntegrationRate: "var(--game-ui-liquid-gooey-move-integration-rate)";
+    readonly waviness: "var(--game-ui-liquid-gooey-waviness)";
+    readonly wavinessFreq: "var(--game-ui-liquid-gooey-waviness-freq)";
+};
+export { CLAY_LIQUID_GOOEY_TOKENS }
+export { CLAY_LIQUID_GOOEY_TOKENS as GAME_UI_LIQUID_GOOEY_TOKENS }
+
 /**
  * Effect knobs for `<LiquidMetalButton>`. Face/ink are real colours (both
  * themes must set them); accent aliases `--game-ui-accent` so a host can
@@ -552,6 +591,37 @@ export declare const CLAY_UI_TOKENS: {
         readonly rest: "var(--game-ui-liquid-metal-rest)";
         readonly bloom: "var(--game-ui-liquid-metal-bloom)";
     };
+    readonly liquidGooey: {
+        readonly moveStiffness: "var(--game-ui-liquid-gooey-move-stiffness)";
+        readonly moveDamping: "var(--game-ui-liquid-gooey-move-damping)";
+        readonly moveStretch: "var(--game-ui-liquid-gooey-move-stretch)";
+        readonly moveTail: "var(--game-ui-liquid-gooey-move-tail)";
+        readonly moveForce: "var(--game-ui-liquid-gooey-move-force)";
+        readonly moveTailSpringStiffness: "var(--game-ui-liquid-gooey-move-tail-spring-stiffness)";
+        readonly moveTailSpringDamping: "var(--game-ui-liquid-gooey-move-tail-spring-damping)";
+        readonly moveStretchSpeed: "var(--game-ui-liquid-gooey-move-stretch-speed)";
+        readonly moveStretchSquash: "var(--game-ui-liquid-gooey-move-stretch-squash)";
+        readonly moveSpeedThreshold: "var(--game-ui-liquid-gooey-move-speed-threshold)";
+        readonly moveTailOnsetSpeed: "var(--game-ui-liquid-gooey-move-tail-onset-speed)";
+        readonly moveTailOnsetRange: "var(--game-ui-liquid-gooey-move-tail-onset-range)";
+        readonly moveTailRamp: "var(--game-ui-liquid-gooey-move-tail-ramp)";
+        readonly moveTailMinRadius: "var(--game-ui-liquid-gooey-move-tail-min-radius)";
+        readonly moveTailWobble: "var(--game-ui-liquid-gooey-move-tail-wobble)";
+        readonly moveTailPhaseSpeed: "var(--game-ui-liquid-gooey-move-tail-phase-speed)";
+        readonly moveTailMidpointA: "var(--game-ui-liquid-gooey-move-tail-midpoint-a)";
+        readonly moveTailMidpointB: "var(--game-ui-liquid-gooey-move-tail-midpoint-b)";
+        readonly moveTailMidRadiusA: "var(--game-ui-liquid-gooey-move-tail-mid-radius-a)";
+        readonly moveTailMidRadiusB: "var(--game-ui-liquid-gooey-move-tail-mid-radius-b)";
+        readonly moveTailWobblePhase: "var(--game-ui-liquid-gooey-move-tail-wobble-phase)";
+        readonly moveMinPerpendicular: "var(--game-ui-liquid-gooey-move-min-perpendicular)";
+        readonly moveLagBase: "var(--game-ui-liquid-gooey-move-lag-base)";
+        readonly moveLagForce: "var(--game-ui-liquid-gooey-move-lag-force)";
+        readonly moveSettleDistance: "var(--game-ui-liquid-gooey-move-settle-distance)";
+        readonly moveSettleSpeed: "var(--game-ui-liquid-gooey-move-settle-speed)";
+        readonly moveIntegrationRate: "var(--game-ui-liquid-gooey-move-integration-rate)";
+        readonly waviness: "var(--game-ui-liquid-gooey-waviness)";
+        readonly wavinessFreq: "var(--game-ui-liquid-gooey-waviness-freq)";
+    };
 };
 
 export declare type ClayAssetGroup = keyof typeof CLAY_ASSETS;
@@ -722,6 +792,35 @@ export declare const GAME_UI_TARGETS: {
 export declare const GAME_UI_THEME_CONTRACT: readonly ["--game-ui-bg", "--game-ui-surface", "--game-ui-surface-raised", "--game-ui-panel", "--game-ui-panel-strong", "--game-ui-panel-deep", "--game-ui-text", "--game-ui-text-muted", "--game-ui-accent", "--game-ui-accent-bright", "--game-ui-secondary", "--game-ui-success", "--game-ui-success-bright", "--game-ui-danger", "--game-ui-danger-bright", "--game-ui-warning", "--game-ui-focus-ring", "--game-ui-border-subtle", "--game-ui-border-strong", "--game-ui-disabled", "--game-ui-ink-deep", "--game-ui-border-ink", "--game-ui-wood", "--game-ui-ink-title", "--game-ui-ink-heading", "--game-ui-liquid-metal-face", "--game-ui-liquid-metal-ink"];
 
 export declare const GAME_UI_TOKENS: {
+    readonly moveStiffness: "var(--game-ui-liquid-gooey-move-stiffness)";
+    readonly moveDamping: "var(--game-ui-liquid-gooey-move-damping)";
+    readonly moveStretch: "var(--game-ui-liquid-gooey-move-stretch)";
+    readonly moveTail: "var(--game-ui-liquid-gooey-move-tail)";
+    readonly moveForce: "var(--game-ui-liquid-gooey-move-force)";
+    readonly moveTailSpringStiffness: "var(--game-ui-liquid-gooey-move-tail-spring-stiffness)";
+    readonly moveTailSpringDamping: "var(--game-ui-liquid-gooey-move-tail-spring-damping)";
+    readonly moveStretchSpeed: "var(--game-ui-liquid-gooey-move-stretch-speed)";
+    readonly moveStretchSquash: "var(--game-ui-liquid-gooey-move-stretch-squash)";
+    readonly moveSpeedThreshold: "var(--game-ui-liquid-gooey-move-speed-threshold)";
+    readonly moveTailOnsetSpeed: "var(--game-ui-liquid-gooey-move-tail-onset-speed)";
+    readonly moveTailOnsetRange: "var(--game-ui-liquid-gooey-move-tail-onset-range)";
+    readonly moveTailRamp: "var(--game-ui-liquid-gooey-move-tail-ramp)";
+    readonly moveTailMinRadius: "var(--game-ui-liquid-gooey-move-tail-min-radius)";
+    readonly moveTailWobble: "var(--game-ui-liquid-gooey-move-tail-wobble)";
+    readonly moveTailPhaseSpeed: "var(--game-ui-liquid-gooey-move-tail-phase-speed)";
+    readonly moveTailMidpointA: "var(--game-ui-liquid-gooey-move-tail-midpoint-a)";
+    readonly moveTailMidpointB: "var(--game-ui-liquid-gooey-move-tail-midpoint-b)";
+    readonly moveTailMidRadiusA: "var(--game-ui-liquid-gooey-move-tail-mid-radius-a)";
+    readonly moveTailMidRadiusB: "var(--game-ui-liquid-gooey-move-tail-mid-radius-b)";
+    readonly moveTailWobblePhase: "var(--game-ui-liquid-gooey-move-tail-wobble-phase)";
+    readonly moveMinPerpendicular: "var(--game-ui-liquid-gooey-move-min-perpendicular)";
+    readonly moveLagBase: "var(--game-ui-liquid-gooey-move-lag-base)";
+    readonly moveLagForce: "var(--game-ui-liquid-gooey-move-lag-force)";
+    readonly moveSettleDistance: "var(--game-ui-liquid-gooey-move-settle-distance)";
+    readonly moveSettleSpeed: "var(--game-ui-liquid-gooey-move-settle-speed)";
+    readonly moveIntegrationRate: "var(--game-ui-liquid-gooey-move-integration-rate)";
+    readonly waviness: "var(--game-ui-liquid-gooey-waviness)";
+    readonly wavinessFreq: "var(--game-ui-liquid-gooey-waviness-freq)";
     readonly iconSm: "var(--game-ui-asset-icon-sm)";
     readonly iconMd: "var(--game-ui-asset-icon-md)";
     readonly iconLg: "var(--game-ui-asset-icon-lg)";
@@ -1956,10 +2055,36 @@ declare interface LiquidGooeyBudgetState {
     activeGroups: number;
 }
 
+/**
+ * Merges nearby item silhouettes into one shape while leaving their content
+ * accessible and unfiltered. Do NOT add border, outline, or box-shadow to
+ * children directly; pass the shared treatment to <LiquidGroup>.
+ */
 export declare const LiquidGroup: ForwardRefExoticComponent<LiquidGroupProps & RefAttributes<HTMLDivElement>> & {
     Item: ForwardRefExoticComponent<LiquidItemProps & RefAttributes<HTMLDivElement>>;
 };
 
+/**
+ * A shared liquid silhouette behind crisp item content.
+ *
+ * Put the visual treatment on the group: `fill`, `stroke`, and `shadow` are
+ * rebuilt on the merged silhouette. Do NOT add border, outline, or box-shadow
+ * to children directly; those styles live on the content layer and cannot
+ * merge with the liquid shape.
+ *
+ * Its motion vocabulary is intentionally small and semantic:
+ *
+ * | gesture | meaning |
+ * | --- | --- |
+ * | **merge** (Morph) | two things become one: reward settling, collecting, confirming |
+ * | **follow** (Move) | selection, progress, dragging |
+ * | **dissolve** | replacement, transition |
+ * | **still** | THE DEFAULT |
+ *
+ * Liquid appears only on a state change the user caused. There is no ambient,
+ * idle, or decorative liquid; keep the filter-area budget visible when more
+ * than one group is on a screen.
+ */
 export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     children: ReactNode;
     /** Goo blur sigma in px. Larger values bridge larger gaps. */
@@ -1974,13 +2099,26 @@ export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivEle
     shadow?: string;
     /** Optional stroke syntax rebuilt on the merged silhouette. Note: Do NOT add border to children directly! */
     stroke?: string;
-    /** Deterministic reduced-motion override for previews; auto follows the OS. */
-    motion?: 'auto' | 'reduced';
+    /** Max px the liquid boundary undulates. Defaults to the CSS token (0). */
+    waviness?: number;
+    /** Noise frequency of the undulation; lower values make longer waves. */
+    wavinessFreq?: number;
+    /**
+     * `auto` follows the existing component transition clock, `follow` adopts
+     * the Move surface for an explicit user-caused selection/progress gesture,
+     * and `reduced` snaps. Still remains the house default gesture.
+     */
+    motion?: 'auto' | 'follow' | 'reduced';
 }
 
 export declare const LiquidItem: ForwardRefExoticComponent<LiquidItemProps & RefAttributes<HTMLDivElement>>;
 
 export declare interface LiquidItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Crisp content rendered above the merged silhouette. Do NOT add border,
+     * outline, or box-shadow to children directly; put the shared treatment on
+     * the parent <LiquidGroup> instead.
+     */
     children: ReactNode;
     /** Mirrored translation applied to the content wrapper and SVG silhouette. */
     x?: number;