@pieai/swimmer-ui-kit 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 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
+
+- **Every tooltip was invisible on the night theme.** `.game-ui-tooltip
+  [role='tooltip']` painted `background: var(--game-ui-text)` with
+  `color: var(--game-ui-text-on-dark)`. On light that is a dark chip over a
+  pale page and reads correctly. On night `--game-ui-text` flips to cream, so
+  the chip became cream-on-cream at **1.15:1**. The light theme looking right
+  is exactly why this survived. There is now a dedicated
+  `--game-ui-tooltip-surface` / `--game-ui-tooltip-ink` pair, defined per
+  theme, keeping the inverted look on light and readable on night.
+
+### Added
+
+- **`swimmer-ui-check` reports references to tokens this kit does not define.**
+  `var()` takes a fallback, so `var(--game-ui-border, #253048)` renders forever
+  against a token that does not exist — the rule looks token-driven while the
+  fallback does all the work, and no brand change can reach it. A consumer had
+  six borders in that state, in a cold blue-grey, in a warm brown app. Another
+  was the reason `--game-ui-font-mono` got added in 1.6.0.
+
+  Two things are exempt and neither is a typo: tokens the scanned files define
+  themselves (downstream theming), and tokens written from code
+  (`style={{ '--game-ui-card-offset': n }}`), found by scanning sibling
+  sources. Anything else is indistinguishable from a misspelling, and the way
+  to declare a deliberate knob is to give it a default in `:root`.
+
+- **`pnpm check:styles`, and `pnpm verify` now runs it.** The kit shipped a
+  contrast checker in 1.5.0 and never pointed it at itself, which is how the
+  tooltip above survived a release that was specifically about contrast.
+
 ## 1.6.0
 
 ### Added

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/bin/swimmer-ui-check.mjs

@@ -183,6 +183,61 @@ function themeTokens() {
   return themes;
 }
 
+/**
+ * Every `--game-ui-*` name this package defines, in any theme block.
+ *
+ * Colours only is not enough here: the gap this catches was a *font* token.
+ */
+function definedTokenNames() {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const sources = [join(packageRoot, 'dist', 'styles.css'), join(packageRoot, 'src', 'theme.css')];
+  for (const candidate of sources) {
+    try {
+      const css = readFileSync(candidate, 'utf8');
+      return new Set([...css.matchAll(/(--game-ui-[\w-]+)\s*:/g)].map((m) => m[1]));
+    } catch {
+      // try the next one
+    }
+  }
+  return null;
+}
+
+/**
+ * A `var(--game-ui-…)` naming a token this kit does not define.
+ *
+ * `var()` takes a fallback, so this never fails at runtime — the rule renders
+ * from the fallback and looks token-driven while being nothing of the sort. A
+ * consumer had six borders reading `var(--game-ui-border, #253048)` against a
+ * token that does not exist, so those borders were a cold blue-grey in an app
+ * whose theme is warm brown, for as long as the file had existed, and no brand
+ * change could ever have reached them. Another was writing
+ * `var(--game-ui-font-mono, …)` — that one turned out to be a real gap in this
+ * kit, which is the other reason to surface it rather than let the fallback
+ * hide it.
+ *
+ * Two things are not typos and are not flagged. A token the scanned files
+ * define themselves is a downstream theme override, which is how theming
+ * works. And a token written from code — `style={{ '--game-ui-card-offset': n }}`
+ * — is a per-element channel that cannot have a stylesheet default; those are
+ * found by scanning the sibling sources.
+ *
+ * Everything else is indistinguishable from a misspelling, and the way to say
+ * "this is a deliberate knob" is to declare it in `:root` with its default.
+ * That makes it discoverable and themeable instead of a secret only the
+ * fallback knows.
+ */
+function findUndefinedTokens(css, defined, ownTokens) {
+  if (!defined) return [];
+  const at = lineFinder(css);
+  const out = [];
+  for (const match of css.matchAll(/var\(\s*(--game-ui-[\w-]+)/g)) {
+    const name = match[1];
+    if (defined.has(name) || ownTokens.has(name)) continue;
+    out.push({ line: at(match.index ?? 0), name });
+  }
+  return out;
+}
+
 /**
  * A bare token reference and nothing else: `var(--game-ui-x)` or
  * `var(--game-ui-x, #fallback)`.
@@ -246,6 +301,21 @@ try {
 }
 
 const themes = themeTokens();
+const definedTokens = definedTokenNames();
+const ownTokens = new Set();
+for (const file of files) {
+  for (const match of readFileSync(file, 'utf8').matchAll(/^\s*(--game-ui-[\w-]+)\s*:/gm)) {
+    ownTokens.add(match[1]);
+  }
+}
+// Tokens written from code are a per-element channel, not a theme value.
+const codeFiles = [];
+walk(target, new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs']), codeFiles);
+for (const file of codeFiles) {
+  for (const match of readFileSync(file, 'utf8').matchAll(/['"`](--game-ui-[\w-]+)['"`]/g)) {
+    ownTokens.add(match[1]);
+  }
+}
 if (!themes || themes.size === 0) {
   console.error(
     "swimmer-ui-check: could not read this package's theme tokens, so contrast was NOT checked. " +
@@ -253,6 +323,7 @@ if (!themes || themes.size === 0) {
   );
 }
 let contrastCount = 0;
+let undefinedCount = 0;
 let violationCount = 0;
 for (const file of files) {
   const text = readFileSync(file, 'utf8');
@@ -263,6 +334,13 @@ for (const file of files) {
     );
     contrastCount += 1;
   }
+  for (const undef of findUndefinedTokens(text, definedTokens, ownTokens)) {
+    console.log(
+      `${relative(process.cwd(), file)}:${undef.line}: ${undef.name} is not a token this kit ` +
+        'defines — the var() fallback is doing all the work',
+    );
+    undefinedCount += 1;
+  }
   for (const violation of findViolations(text)) {
     console.log(
       `${relative(process.cwd(), file)}:${violation.line}: raw color literal "${violation.text}" — use var(--game-ui-*) instead`,
@@ -279,7 +357,15 @@ if (contrastCount > 0) {
   );
 }
 
-if (violationCount > 0 || contrastCount > 0) {
+if (undefinedCount > 0) {
+  console.error(
+    `\nswimmer-ui-check: ${undefinedCount} reference(s) to a token this kit does not define. ` +
+      'These never fail at runtime, because var() falls back — which is exactly why they survive. ' +
+      'Either the name is wrong, or the token is missing from the kit and should be proposed there.',
+  );
+}
+
+if (violationCount > 0 || contrastCount > 0 || undefinedCount > 0) {
   console.error(
     `\nswimmer-ui-check: ${violationCount} raw color literal(s) in ${files.length} file(s) under "${target}". ` +
       'Raw colors are expected inside :root / [data-*theme*=...] / [data-*tone*=...] token blocks ' +

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 { }