@pieai/swimmer-ui-kit 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -3,6 +3,112 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 2.2.0 — 2026-09-11
+
+Minor, not major: nothing published is removed or renamed, and no `--game-ui-*`
+name changes. Two token **values** change, and every button in every product
+gets a visible lip — deliberately, and described under Changed.
+
+### Added
+
+- **Named liquid forms.** `LIQUID_FORMS` gives the gooey engine six looks with
+  names instead of a page of physical knobs: `press`, `settle`, `merge`,
+  `follow`, `fill`, `drain`. Each is a tested bundle of blur, contrast, outline
+  and spring, resolved through `liquidFormGroup` / `liquidFormItem`, which
+  merge overrides into a form rather than replacing it.
+
+  This layer was missing, and its absence had a measurable cost: the only
+  production consumer had to hand-tune 166 lines around a normal button to get
+  one liquid control, and the corrections it discovered never came back here.
+
+- **`LiquidSurface`.** The packaging for the single-body forms — a
+  non-interactive silhouette behind, real DOM in front and never transformed,
+  so a pressed control keeps its hit target, its focus ring and its crisp text.
+  `merge` and `follow` describe a relationship between siblings and stay with
+  `LiquidGroup`, where they belong.
+
+- **`GameButton` gains `surface="flat" | "liquid"`.** Deliberately a second
+  axis rather than a new `variant`: `variant` is a tone, and folding 'liquid'
+  into it would have made the brand's signature surface mutually exclusive with
+  saying "this action is destructive". The default path renders byte-identical
+  markup — asserted in a test — so no existing call site moves.
+
+- **`blob`: an organic silhouette drawn as geometry.** `LiquidGroup.Item`
+  takes a `blob` shape, and the single-body forms use it. The outline swells
+  outward from the control's own box along a closed Catmull-Rom spline, so it
+  is exact at every device ratio and zoom, and it is **outward-only** by
+  construction — no amplitude can push the surface inside a label's padding or
+  across a hit target.
+
+  This replaces `waviness` as the way a form gets an irregular edge, and the
+  reason is a measurement rather than a preference. Chrome resamples
+  `feDisplacementMap` with nearest-neighbour, so a displaced contour can only
+  land on whole pixels. Captured at device ratio 1 with alpha recovered from
+  two backgrounds and sampled along a straight edge, the settings shipped in
+  the 2.2.0 development line moved the outline by a constant 1.5px and varied
+  it by 0.01px across the whole side: there was no wave at all, which is
+  exactly how it looked. Raising the frequency does not fix it — it trades one
+  whole-side step for per-pixel jitter, which is the frayed edge the effect was
+  blamed for in the first place.
+
+  `waviness` and `wavinessFreq` remain exported, documented and unchanged for
+  callers who want the filter-side texture on large merging bodies, which is
+  what the donor uses it for.
+
+- **`gloss`.** Interior volume for a liquid body, from `feSpecularLighting` at
+  a grazing 22° elevation. An irregular outline around a flat fill still reads
+  as a sticker; a surface reads as a material through how it catches light. The
+  light is distant rather than positional so it does not have to be recomputed
+  from a measured box on every resize.
+
+- **`LIQUID_GOOEY_MIN_EDGE_RAMP` and `liquidGooeyEdgeContrast`.** The floor on
+  how narrow the goo threshold may leave an edge.
+
+### Changed
+
+- **Buttons have a lip.** `--game-ui-button-lip-ink` and
+  `--game-ui-button-lip-depth` add a solid, unblurred band under
+  `.game-ui-button`, and a press travels its height instead of only scaling in
+  place. This is what separates a game control from a card: a key has a height
+  you can see, and pressing it has somewhere to go.
+
+  **Blast radius: every button in every product using the kit.** Only
+  `.game-ui-button` is affected — tabs, toggles and segmented options live
+  inside other surfaces and keep their flat treatment — and `ghost` and
+  `disabled` opt out. A product that wants the old look sets
+  `--game-ui-button-lip-depth: 0px`.
+
+- **The goo threshold has a minimum edge width.** `contrast` is not a look: the
+  alpha crossing sits at a fixed 5/12 of the ramp, so contrast decides only how
+  many pixels wide the edge is. Blur 4 with contrast 24 — the pairing the one
+  production consumer had converged on — works out at 0.43px, an edge thinner
+  than the pixel drawing it, which is the definition of an aliased one.
+  `liquidGooeyEdgeContrast` now lowers contrast until the ramp is at least
+  1.3px, the width at which measured contour roughness bottoms out at the score
+  of a shape with no displacement at all.
+
+  This cannot move a silhouette, only soften how it is drawn, and it only
+  engages where an edge was too thin. `merge` and the other soft forms are
+  untouched.
+
+- **Resting `waviness` is 0 by default.** `--game-ui-liquid-gooey-waviness` was
+  6 and is now 0; the SSR fallback matches. 6 came from the donor and meant the
+  out-of-the-box look was a permanently undulating outline, which reads as a
+  rendering defect on a static rounded rectangle — University cancelled it with
+  `waviness={0}` on all eighteen surfaces that use liquid, and those overrides
+  are now unnecessary.
+
+  **Migration:** none required. A surface that genuinely wants the old molten
+  edge passes `waviness={6}`.
+
+- **Removed before release: `LIQUID_REST_EDGE_SLOPE_MAX` and
+  `liquidRestEdgeSlope`.** Added earlier in this same unreleased line, on the
+  theory that a resting edge tears when amplitude times frequency goes too
+  high. The measurement above shows the cap was not protecting the edge — it
+  was selecting frequencies low enough for the displacement to stop varying,
+  and scoring well because the feature had disappeared. Nothing shipped with
+  them, so nothing has to migrate.
+
 ## 2.1.0 — 2026-09-02
 
 ### Added

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ButtonHTMLAttributes } from 'react';
+import { CSSProperties } from 'react';
 import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
@@ -16,6 +17,17 @@ export declare interface BendTuning {
     horizontal?: number;
 }
 
+declare interface BlobShape {
+    /** Outward bulge, in px. 0 gives the plain rounded rectangle. */
+    readonly amplitude: number;
+    /** Which shape. Same seed, same silhouette, every render. */
+    readonly seed?: number;
+    /** How many swells go round the outline. 2 is lazy, 5 is busy. */
+    readonly lobes?: number;
+    /** Rotates the swells around the outline; the knob a press animates. */
+    readonly phase?: number;
+}
+
 export declare const CLAY_ASSET_BASE_PATH: "/assets/game/ui/clay/phase03-clay-kit";
 
 export declare const CLAY_ASSET_SIZE_TOKENS: {
@@ -856,16 +868,6 @@ export declare interface DissolveOptions {
 
 export declare type DissolveValue = boolean | number | DissolveOptions;
 
-/**
- * Morph shape physics adapted from `liquid-gooey` by Jakub Antalik.
- *
- * Source: https://github.com/Jakubantalik/Libraries/tree/main/packages/liquid-gooey
- * Pinned commit: 3862ffa345217443b63696a8c331a0664eea4b04
- * Copyright (c) 2026 Jakub Antalik. Licensed under the MIT License.
- * See NOTICE for the attribution and license text. This local module keeps
- * the donor's centre -> size -> corner timeline and content cross-blur, but
- * routes every tunable value through SwimmerUIKit's token layer.
- */
 declare interface EvolveOptions {
     /** Spring driving the liquid mass's centre. */
     massStiffness?: number;
@@ -1374,16 +1376,24 @@ export declare interface GameBuildLibraryProps {
     'data-testid'?: string | undefined;
 }
 
-export declare function GameButton({ children, className, onClick, sound, static: isStatic, type, variant, ...props }: GameButtonProps): ReactNode;
+export declare function GameButton({ children, className, onClick, sound, static: isStatic, surface, type, variant, ...props }: GameButtonProps): ReactNode;
 
 export declare interface GameButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     children: ReactNode;
     sound?: GameInteractionSoundOptions | false;
     /** Disable the scale-on-press feedback where the motion would distract. */
     static?: boolean;
+    /**
+     * Draw the button on a liquid body. The button itself is unchanged — same
+     * element, same classes, same hit target; a silhouette behind it does the
+     * deforming, so text stays crisp and the tap target never shrinks.
+     */
+    surface?: GameButtonSurface;
     variant?: GameButtonVariant;
 }
 
+export declare type GameButtonSurface = 'flat' | 'liquid';
+
 export declare type GameButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'success';
 
 /**
@@ -2330,6 +2340,11 @@ export declare interface ImageMeltOptions {
     waviness?: number;
 }
 
+/** Every form name, for shelves, docs and exhaustiveness checks. */
+export declare const LIQUID_FORM_NAMES: readonly LiquidForm[];
+
+export declare const LIQUID_FORMS: Readonly<Record<LiquidForm, LiquidFormSpec>>;
+
 /**
  * The default fraction is intentionally derived from the rendered surface,
  * not from the requested waviness token. A fixed pixel displacement is safe
@@ -2337,6 +2352,63 @@ export declare interface ImageMeltOptions {
  */
 export declare const LIQUID_GOOEY_WAVINESS_MAX_FRACTION = 0.3;
 
+/**
+ * The named looks, ordered by how much cohesion the liquid is losing:
+ * `press` barely deforms, `drain` stops being a shape at all.
+ */
+export declare type LiquidForm = 'press' | 'settle' | 'merge' | 'follow' | 'fill' | 'drain';
+
+/** Filter-level knobs a form fixes on the group. */
+export declare interface LiquidFormGroup {
+    readonly blur: number;
+    readonly contrast: number;
+    /**
+     * How far the outline swells outward from the control's box, in px. The
+     * bulge is outward-only, so this never eats into a label's padding, and it
+     * is clamped to 18% of the shorter side so one number suits a 44px button
+     * and a 14px meter.
+     */
+    readonly blob: number;
+    /** How many swells go round the outline. 2 is lazy, 5 is busy. */
+    readonly lobes: number;
+    /**
+     * Volume. The edge says 「liquid」 only as an outline; this is what makes the
+     * inside of the body look like a material instead of a flat sticker.
+     */
+    readonly gloss: number;
+    readonly filterPadding: number;
+}
+
+/**
+ * Resolve a form into group props, letting a caller override single knobs.
+ *
+ * Overrides are merged rather than replacing the bundle, so a surface that
+ * needs one different value does not have to restate the other three and
+ * silently drift from the form it claims to be using.
+ */
+export declare function liquidFormGroup(form: LiquidForm, overrides?: Partial<LiquidFormGroup>): LiquidFormGroup;
+
+/** Item-level behaviour a form fixes on each participating item. */
+export declare interface LiquidFormItem {
+    readonly effect?: 'morph' | 'melt' | 'bend';
+    readonly morph?: MorphTuning;
+    readonly transition?: Transition;
+    readonly dissolve?: boolean;
+}
+
+/** Resolve a form into item props, with the same merge-don't-replace rule. */
+export declare function liquidFormItem(form: LiquidForm, overrides?: LiquidFormItem): LiquidFormItem;
+
+export declare interface LiquidFormSpec {
+    /** One sentence on what a viewer sees, for docs and for picking. */
+    readonly summary: string;
+    readonly group: LiquidFormGroup;
+    readonly item: LiquidFormItem;
+}
+
+/** The one-line description of each form, for pickers and documentation. */
+export declare function liquidFormSummary(form: LiquidForm): string;
+
 declare interface LiquidGooeyBudgetOptions {
     maxAnimatedGroups?: number;
     maxFilterArea?: number;
@@ -2388,6 +2460,11 @@ export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivEle
     blur?: number;
     /** Alpha-contrast slope. Larger values make the liquid edge harder. */
     contrast?: number;
+    /**
+     * Volume. 0 leaves the body a flat colour; higher values light it as a
+     * curved surface so it reads as a material rather than as a silhouette.
+     */
+    gloss?: number;
     /** Surface fill. Defaults to the kit's theme surface token. */
     fill?: string;
     /** Extra filter-region slack in px for the silhouette's painted edges. */
@@ -2432,6 +2509,12 @@ export declare interface LiquidItemProps extends Omit<HTMLAttributes<HTMLDivElem
     delay?: number;
     /** Override the measured content border radius for the silhouette. */
     radius?: number | CornerRadii;
+    /**
+     * Pour the outline outward into an organic body instead of leaving it a
+     * rounded rectangle. The bulge is outward-only, so the silhouette always
+     * contains the content's own box however bold the amplitude gets.
+     */
+    blob?: BlobShape;
     /**
      * Select the adopted item surface behavior. Bend follows child geometry.
      * Move is a group gesture (`motion="follow"`), not an item effect.
@@ -2468,6 +2551,27 @@ export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTM
 
 export declare type LiquidMetalRendererMode = 'auto' | 'css' | 'webgl';
 
+export declare function LiquidSurface({ children, form, active, fill, stroke, shadow, radius, className, style, }: LiquidSurfaceProps): ReactNode;
+
+export declare interface LiquidSurfaceProps {
+    children: ReactNode;
+    /** Which named look. Defaults to the press form, the one a control wants. */
+    form?: LiquidForm;
+    /**
+     * Whether the form is engaged: pressed for `press`, landed for `settle`,
+     * leaving for `drain`. Ignored by forms with no engaged state.
+     */
+    active?: boolean;
+    /** Silhouette paint. Defaults to the kit's raised surface token. */
+    fill?: string;
+    stroke?: string;
+    shadow?: string;
+    /** Corner radius of the body, in px. 999 gives a pill. */
+    radius?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+
 export declare interface MorphTuning {
     /** Whether shape-change physics is enabled. The kit default is token-on. */
     shape?: boolean;