@pieai/swimmer-ui-kit 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.8.0
+
+### Added
+
+- **`<LiquidMetalButton>`**, a decision-surface CTA with two renderers and
+  one set of tokens. Default is CSS (zero WebGL contexts). It upgrades to
+  the ThreeUI dispersion shader (MIT, inlined — not the iframe wrapper)
+  only when webgl2 is available, `prefers-reduced-motion` is not `reduce`,
+  the button is on screen, and a process-wide budget (default **2**,
+  `setLiquidMetalContextBudget`) still has a slot. Exhausted budget, a
+  missing webgl2, or reduced motion stays on CSS without throwing. Hidden
+  tabs pause RAF rather than destroying the context.
+
+  Use it on checkout, sign-up, unlock, landing CTA. Do not use it on
+  reading, queues, forms, or the map. More than two on a page means the
+  page is the wrong place.
+
+  Colours are `--game-ui-liquid-metal-face` / `--ink` (defined on both
+  light and night so they cannot inherit an inverting ink) plus the
+  existing accent; the effect knobs are `--game-ui-liquid-metal-dispersion`,
+  `--sweep-speed`, and `--rest`.
+
 ## 1.7.0
 
 ### Fixed

package/NOTICE

@@ -0,0 +1,38 @@
+Third-party notices
+===================
+
+Liquid-metal dispersion shader
+------------------------------
+Portions of the WebGL2 renderer in `src/liquidMetalWebGL.ts` are adapted
+from ThreeUI (https://github.com/MengTo/threeui), Copyright (c) 2026
+Meng To, licensed under the MIT License.
+
+The upstream ships the shader inside a standalone HTML page and embeds
+that page in an iframe. This package inlines the shader so colours can
+follow `--game-ui-*` tokens, adds a CSS renderer as the default, and
+caps simultaneous WebGL contexts.
+
+The MIT License text for that material:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Fonts
+-----
+Baloo 2 and Geist Variable are licensed under the SIL Open Font License.
+See `src/fonts/OFL-Baloo2.txt` and `src/fonts/OFL-Geist.txt`.

package/README.md

@@ -48,7 +48,8 @@ import '@pieai/swimmer-ui-kit/tailwind.css';
 
 ## What's inside
 
-- **~60 components** across: core controls (`GameButton`, `GameTabs`,
+- **~60 components** across: core controls (`GameButton`,
+  `LiquidMetalButton`, `GameTabs`,
   `GameSlider`, `GameToggle`, `GameForms` inputs…), panels and windows
   (`GamePanel`, `GameCollapsiblePanel`, `GameWindowPanel`, `GameModal` on
   native `<dialog>`), HUD/shell surfaces (`GameShell`, `GameHud`,

package/dist/index.d.ts

@@ -78,6 +78,9 @@ export declare const CLAY_COLOR_TOKENS: {
     /** Official HUD-on-scene glass fill (matches SupaLuv stage chrome). */
     readonly overlayGlass: "rgba(12, 14, 20, 0.72)";
     readonly overlayGlassText: "#fff6ee";
+    /** Liquid-metal plate fill (light). Dedicated so it cannot inherit ink-deep, which inverts on night. */
+    readonly liquidMetalFace: "#3a2518";
+    readonly liquidMetalInk: "#fff8ec";
 };
 
 export declare const CLAY_ELEVATION_TOKENS: {
@@ -265,6 +268,23 @@ export declare const CLAY_LAYER_TOKENS: {
     readonly toast: "var(--game-ui-z-toast)";
 };
 
+/**
+ * Effect knobs for `<LiquidMetalButton>`. Face/ink are real colours (both
+ * themes must set them); accent aliases `--game-ui-accent` so a host can
+ * retint just this button without rebranding every primary.
+ */
+declare const CLAY_LIQUID_METAL_TOKENS: {
+    readonly face: "var(--game-ui-liquid-metal-face)";
+    readonly ink: "var(--game-ui-liquid-metal-ink)";
+    readonly accent: "var(--game-ui-liquid-metal-accent)";
+    readonly dispersion: "var(--game-ui-liquid-metal-dispersion)";
+    readonly sweepSpeed: "var(--game-ui-liquid-metal-sweep-speed)";
+    readonly rest: "var(--game-ui-liquid-metal-rest)";
+    readonly bloom: "var(--game-ui-liquid-metal-bloom)";
+};
+export { CLAY_LIQUID_METAL_TOKENS }
+export { CLAY_LIQUID_METAL_TOKENS as GAME_UI_LIQUID_METAL_TOKENS }
+
 export declare const CLAY_MOTION_TOKENS: {
     readonly fast: "var(--game-ui-motion-fast)";
     readonly base: "var(--game-ui-motion-base)";
@@ -396,6 +416,9 @@ export declare const CLAY_UI_TOKENS: {
         /** Official HUD-on-scene glass fill (matches SupaLuv stage chrome). */
         readonly overlayGlass: "rgba(12, 14, 20, 0.72)";
         readonly overlayGlassText: "#fff6ee";
+        /** Liquid-metal plate fill (light). Dedicated so it cannot inherit ink-deep, which inverts on night. */
+        readonly liquidMetalFace: "#3a2518";
+        readonly liquidMetalInk: "#fff8ec";
     };
     readonly semantic: {
         readonly background: "var(--game-ui-bg)";
@@ -520,6 +543,15 @@ export declare const CLAY_UI_TOKENS: {
         readonly focusRing: "var(--game-ui-overlay-glass-focus-ring)";
         readonly primaryFill: "var(--game-ui-overlay-glass-primary-fill)";
     };
+    readonly liquidMetal: {
+        readonly face: "var(--game-ui-liquid-metal-face)";
+        readonly ink: "var(--game-ui-liquid-metal-ink)";
+        readonly accent: "var(--game-ui-liquid-metal-accent)";
+        readonly dispersion: "var(--game-ui-liquid-metal-dispersion)";
+        readonly sweepSpeed: "var(--game-ui-liquid-metal-sweep-speed)";
+        readonly rest: "var(--game-ui-liquid-metal-rest)";
+        readonly bloom: "var(--game-ui-liquid-metal-bloom)";
+    };
 };
 
 export declare type ClayAssetGroup = keyof typeof CLAY_ASSETS;
@@ -557,6 +589,18 @@ export declare type ClayIconStyle = 'game' | 'line';
 
 export declare type ClayTokenCategory = keyof typeof CLAY_UI_TOKENS;
 
+/**
+ * Process-wide ledger for liquid-metal WebGL2 contexts.
+ *
+ * Chrome gives a tab about 16 contexts (Android about 8) and silently
+ * kills the oldest when the cap is hit. In University that oldest context
+ * is the 3D world map. These buttons are allowed to light up a shader,
+ * but they are not allowed to evict the map — so the default budget is
+ * 2, hosts can raise or lower it, and a button that cannot get a slot
+ * stays on the CSS renderer without throwing.
+ */
+export declare const DEFAULT_LIQUID_METAL_CONTEXT_BUDGET = 2;
+
 export declare function FirstSessionHud({ authenticated, batteryCount, className, dailyStreak, iconSlots, labels, onHistory, onSettings, onWardrobe, playerName, }: FirstSessionHudProps): ReactNode;
 
 export declare interface FirstSessionHudIconSlots {
@@ -661,7 +705,7 @@ export declare const GAME_UI_TARGETS: {
  * to check its own CSS for the same completeness instead of eyeballing it —
  * see "自定义第三主题" in design-system-guide.md for a usage example.
  */
-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"];
+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 iconSm: "var(--game-ui-asset-icon-sm)";
@@ -1880,6 +1924,28 @@ export declare function getClayIconStyles(icon: ClayIconName): ClayIconStyle[];
 
 export declare function getClaySourceAssetPath(icon: ClayIconName, style?: ClayIconStyle): string;
 
+export declare function getLiquidMetalContextBudget(): {
+    limit: number;
+    used: number;
+};
+
+export declare function LiquidMetalButton({ children, className, onClick, sound, type, renderer, ...props }: LiquidMetalButtonProps): ReactNode;
+
+export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    children: ReactNode;
+    sound?: GameInteractionSoundOptions | false;
+    /**
+     * `auto` (default) starts on CSS and upgrades to WebGL when the four
+     * gates pass. `css` never spends a context — needed so a side-by-side
+     * demo can show the fallback without the CSS column taking the slot
+     * the WebGL column needs. `webgl` still respects the gates; it is not
+     * a way to bypass reduced-motion or the budget.
+     */
+    renderer?: LiquidMetalRendererMode;
+}
+
+export declare type LiquidMetalRendererMode = 'auto' | 'css' | 'webgl';
+
 export declare function playGameInteractionSound(options?: GameInteractionSoundOptions): boolean;
 
 export declare function playGameInteractionSoundForContext(audioContext: GameInteractionAudioContext, options?: GameInteractionSoundOptions): boolean;
@@ -1904,4 +1970,6 @@ export declare function setClayAssetBasePath(basePath: string): void;
  */
 export declare function setClayAssetMode(mode: ClayAssetMode): void;
 
+export declare function setLiquidMetalContextBudget(nextLimit: number): void;
+
 export { }