@pieai/swimmer-ui-kit 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.4.0 — 2026-08-22
+
+The kit shipped an icon set that no consumer could see. Nothing was broken and
+nothing errored, which was the problem: with no setup the kit draws lettered
+placeholder squares, and a placeholder that looks deliberate gets shipped. A
+product could put eight identical coloured squares in its navigation and never
+file a bug, because it reads as a design choice rather than a missing step.
+
+The sculpted PNGs were never missing — 350 files travel inside the package, in
+`dist/assets`. What was missing was any route from there to a path the host
+actually serves. `CLAY_ASSET_BASE_PATH` names an absolute URL on the
+*consumer's* origin, and nothing copied, exported or explained it. The kit's own
+Storybook worked throughout, because its assets sit in `public/`.
+
+### Added
+
+- `swimmer-ui-assets [dir] [--base=…] [--force]` — a `bin` that copies the
+  sculpted set into a host's static root. Bundler-agnostic and explicit; no
+  postinstall, because a package that writes into your repo on install is worse
+  than the problem it solves.
+- `"./assets/*"` export, so bundler-based consumers can import an individual
+  file and get a content-hashed URL instead of copying the whole tree.
+- `setClayAssetBasePath()` / `getClayAssetBasePath()` for a CDN or a sub-path
+  deploy. Resolution rebases on the way out, so the variant table stays a
+  single source of truth.
+- A one-time `console.warn` the first time a placeholder is actually drawn,
+  naming the two commands that fix it, and `acknowledgeClayPlaceholders()` for
+  anyone using them on purpose.
+
+### Changed
+
+- README states plainly that the default is placeholders rather than the icon
+  set, and records that the sculpted family is 96px art which cannot take a
+  `currentColor` tint — so it is the wrong family for a dense nav rail or
+  toolbar however correctly it is served.
+
+### Compatibility
+
+Additive only. Defaults are unchanged, so every existing consumer renders
+exactly what it rendered before and gains one console line telling it why.
+
+## 1.3.2 — 2026-08-17
+
+Follows 1.3.1 with the contrast work that release only half did. The new off
+state paired a muted track with a `--game-ui-panel-strong` bead, which is a
+light colour on the light theme and a dark one on night — so on night the bead
+measured 1.8:1 against its own track and all but disappeared in exactly the
+state it had just been added to show.
+
+### Fixed
+
+- The off track is now an inset well (`--game-ui-surface` plus
+  `--game-ui-shadow-inset`) rather than a muted fill, so off and on differ in
+  form — recessed versus filled — and not only in hue. That difference is the
+  kit's own existing vocabulary; `.game-ui-progress-track` is drawn the same
+  way.
+- The bead is `--game-ui-text`, the one token guaranteed to read against every
+  surface its own theme defines, replacing `--game-ui-panel-strong`, which
+  tracks the surface and therefore inverts between themes. Measured on night:
+  13.1:1 bead against the off track, up from 1.8:1, and 6.1:1 between the two
+  track colours.
+- The regression test now asserts the bead's inset offset flips sign between
+  the two states. Position is the half of the state that survives both palettes
+  and both kinds of colour vision, and it is also the half a future edit is
+  most likely to drop.
+
 ## 1.3.1 — 2026-08-17
 
 Gives `<GameToggle>` a visible off state. Since the component shipped, its
@@ -17,12 +83,9 @@ readers the truth and told everyone else nothing.
 
 - `.game-ui-toggle-track` now has two states. Off is a muted track with the
   bead inset on the left; on fills the track with `--game-ui-secondary` and
-  moves the bead to the right. State is carried by the bead's position as well
-  as by colour, so it survives readers who cannot separate the two hues.
-- The bead is now opaque `--game-ui-panel-strong` rather than a 62% mix of it.
-  It is the mark that says which side the switch is sitting on, so it has to
-  clear the 3:1 non-text contrast floor against the track in both states, and a
-  translucent bead over an unknown track colour cannot promise that.
+  moves the bead to the right, so the state is carried by position as well as
+  by colour.
+- The bead is opaque rather than a 62% mix of the panel colour.
 - `.game-ui-toggle-track` joins the `prefers-reduced-motion: reduce` list, so
   the state change is instant for readers who asked for that.
 

package/README.md

@@ -71,10 +71,29 @@ import '@pieai/swimmer-ui-kit/tailwind.css';
 - **Official themes**: light (default) and `night`
   (`<html data-game-ui-theme="night">`). Downstream theming = overriding
   semantic tokens; see the design system guide.
-- **Clay assets**: inline SVG mode by default (no asset hosting needed);
-  `setClayAssetMode('source')` switches to the sculpted PNG set, which
-  ships in `dist/assets/` for hosts to copy under
-  `/assets/game/ui/clay/…`.
+- **Clay assets**: two lines of setup, and **skipping them is not a no-op**.
+  Out of the box the kit draws *placeholders* — one rounded square per icon
+  with a letter in it — not the icon set. They exist so a fresh install
+  renders something instead of a broken image, and they are not shippable.
+  The real sculpted PNGs travel inside the package and need serving:
+
+  ```bash
+  npx swimmer-ui-assets public      # copies dist/assets into your static root
+  ```
+  ```ts
+  import { setClayAssetMode } from '@pieai/swimmer-ui-kit';
+  setClayAssetMode('source');       // once, at your entry
+  ```
+
+  Serving them somewhere else — a CDN, a sub-path deploy — is
+  `setClayAssetBasePath('/my/path')`, and `swimmer-ui-assets public --base=/my/path`
+  mirrors the layout to match. If you *want* placeholders, say so with
+  `acknowledgeClayPlaceholders()` and the console notice goes quiet.
+
+  Note on sizing: the sculpted family is 96px art. Below roughly 24px it turns
+  to mud, and being PNG it cannot take a `currentColor` tint, so it is the
+  wrong family for a dense navigation rail or toolbar. Use the `line` style
+  there, or your own glyphs.
 - **Audio helper**: `playGameInteractionSound` (SSR-safe, opt-in via the
   `sound` prop on `GameButton`).
 

package/bin/swimmer-ui-assets.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Copy the sculpted clay asset set out of the package and into a directory the
+// consuming app actually serves.
+//
+// The kit resolves sculpted icons to absolute URLs under CLAY_ASSET_BASE_PATH
+// ('/assets/game/ui/clay/…'), which is a path on the *host's* origin. The files
+// themselves ship inside the package, in dist/assets. Nothing was closing that
+// gap, so every consumer had to discover it, and the default placeholder mode
+// meant the failure looked like a design choice rather than a missing step.
+//
+// Usage: swimmer-ui-assets [targetDir] [--base=/assets/game/ui/clay/...] [--force]
+//   targetDir  where the host serves static files from. Default "public".
+//   --base     the URL path to mirror under targetDir. Defaults to the kit's
+//              CLAY_ASSET_BASE_PATH, which is what setClayAssetMode('source')
+//              expects with no further configuration.
+//   --force    overwrite files that already exist (default: skip them).
+//
+// After running this, call setClayAssetMode('source') once at your app entry.
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_BASE = '/assets/game/ui/clay/phase03-clay-kit';
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const positional = args.filter((a) => !a.startsWith('--'));
+
+// Two different paths that are easy to conflate: where the files sit inside
+// this package (fixed, mirrors the default URL under dist/) and where the host
+// will serve them from (--base, defaults to the same thing so the common case
+// needs no configuration).
+const trim = (p) => p.replace(/^\/+|\/+$/g, '');
+const baseFlag = args.find((a) => a.startsWith('--base='));
+const servedBase = trim(baseFlag ? baseFlag.slice('--base='.length) : DEFAULT_BASE);
+const targetRoot = resolve(process.cwd(), positional[0] ?? 'public');
+const force = flags.has('--force');
+
+const source = join(packageRoot, 'dist', trim(DEFAULT_BASE));
+if (!existsSync(source)) {
+  console.error(`swimmer-ui-assets: nothing to copy — ${source} does not exist.`);
+  console.error('This package may have been installed without its dist/assets tree.');
+  process.exit(1);
+}
+
+const destination = join(targetRoot, servedBase);
+
+function count(dir) {
+  let files = 0;
+  let bytes = 0;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      const inner = count(full);
+      files += inner.files;
+      bytes += inner.bytes;
+    } else {
+      files += 1;
+      bytes += stat.size;
+    }
+  }
+  return { files, bytes };
+}
+
+const { files, bytes } = count(source);
+
+mkdirSync(dirname(destination), { recursive: true });
+cpSync(source, destination, { recursive: true, force, errorOnExist: false });
+
+const megabytes = (bytes / 1024 / 1024).toFixed(1);
+console.log(`swimmer-ui-assets: copied ${files} files (${megabytes} MB)`);
+console.log(`  from  ${source}`);
+console.log(`  to    ${destination}`);
+console.log('');
+console.log('Now call this once at your app entry, or the kit keeps drawing placeholders:');
+console.log("  import { setClayAssetMode } from '@pieai/swimmer-ui-kit';");
+console.log("  setClayAssetMode('source');");
+if (!force) {
+  console.log('');
+  console.log('Existing files were left alone. Re-run with --force to overwrite.');
+}

package/dist/index.d.ts

@@ -6,6 +6,9 @@ import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 
+/** Opt in to placeholders on purpose, and stop being told about it. */
+export declare function acknowledgeClayPlaceholders(): void;
+
 export declare const CLAY_ASSET_BASE_PATH: "/assets/game/ui/clay/phase03-clay-kit";
 
 export declare const CLAY_ASSET_SIZE_TOKENS: {
@@ -1852,6 +1855,8 @@ export declare interface GameWindowPanelProps extends Omit<HTMLAttributes<HTMLEl
 
 export declare type GameWindowState = 'normal' | 'minimized' | 'maximized';
 
+export declare function getClayAssetBasePath(): string;
+
 export declare function getClayAssetMode(): ClayAssetMode;
 
 export declare function getClayCatalogPaths(): typeof CLAY_ASSETS.catalog;
@@ -1867,11 +1872,23 @@ export declare function playGameInteractionSound(options?: GameInteractionSoundO
 
 export declare function playGameInteractionSoundForContext(audioContext: GameInteractionAudioContext, options?: GameInteractionSoundOptions): boolean;
 
+/**
+ * Point the sculpted set at somewhere other than the default path — a CDN, a
+ * sub-path deploy, a host whose static root is not `/`. Pass no trailing slash.
+ *
+ * The copy command mirrors the default layout, so a consumer that runs
+ * `swimmer-ui-assets public` never needs this.
+ */
+export declare function setClayAssetBasePath(basePath: string): void;
+
 /**
  * Switch how clay icons resolve globally.
- * - 'inline' (default): zero-dependency SVG placeholders, no assets required.
- * - 'source': the real clay game-icon PNG paths under CLAY_ASSET_BASE_PATH.
- *   The host app must serve those assets (e.g. copy them into its public/).
+ * - 'inline' (default): lettered placeholders. They are not the icon set —
+ *   every one is the same rounded square with a different glyph and colour.
+ *   They exist so a fresh install renders *something* rather than a broken
+ *   image, and shipping them is a bug.
+ * - 'source': the real sculpted PNGs under the base path. Get the files there
+ *   with `npx swimmer-ui-assets <publicDir>`.
  */
 export declare function setClayAssetMode(mode: ClayAssetMode): void;