@pieai/swimmer-ui-kit 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -3,6 +3,149 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 2.5.0 — 2026-09-12
+
+### Find the right component before reading the whole API
+
+- README now starts with a task-based component selection guide. A primary
+  button is `GameButton variant="primary"`; a liquid CTA adds
+  `surface="liquid"`. The documented README → recipe → live story path takes
+  no more than three steps. Preview opens with the same primary-action examples;
+  code recipes wrap and the existing showcase navigation fits narrow screens.
+  Preview-only grid, asset-path and construction-status wrapping fixes prevent
+  horizontal page overflow; anchored headings stay below the sticky navigation.
+  These shelf-layout fixes do not alter consumer component styles.
+- A TypeScript-generated inventory classifies all **272** existing named root
+  exports (**121 values / 151 types**) and links their definitions. The frozen
+  audit records actual local symbol references and read-only University imports;
+  no observed import is not evidence that a public helper is safe to remove.
+  `pnpm api:inventory` regenerates the index; `pnpm api:check` joins `verify`.
+- **No root export was removed, renamed or moved to a new package subpath.**
+  Package export routes, existing class/token names, the ESM-only / zero-runtime-
+  dependency contract and all twelve liquid forms remain intact.
+
+### A ready-to-use liquid CTA, not another liquid engine
+
+- Add optional `GameButton.fullWidth`. Both the native button and its liquid
+  silhouette fill the available row; omitted/false preserves existing layout.
+  Native disabled, submit, keyboard, focus, pointer-cancel and reduced-motion
+  behavior remain. Preview and Storybook include ordinary, liquid, full-width
+  and disabled examples, with browser and markup regression tests.
+- Reuse the existing `press` form and its non-uniform squash / `wobbly` rebound.
+  There is **no new `cta` form and no retuning of the 2.4.0 liquid engine,
+  geometry, shadows or presets**. Newcomers no longer need to assemble a CTA
+  from `LiquidGroup` physics knobs.
+
+### Documentation and evidence convergence
+
+- Retire the ambiguous `doc/` tree: preserve the six historical tutorials and
+  unimplemented 3D-icon research in `docs/archive/legacy-doc/`; reconcile the
+  active liquid-primitives and game-surface guides in `docs/reference/`.
+- Archive the extraction report, retired July upgrade plan and version-scoped
+  edge/shadow measurements. The July plan is **not** marked wholly completed.
+  Original archive bodies and all pre-existing PNG bytes/paths are retained.
+  The [relocation map](docs/archive/relocations-2.5.0.json) records every reason.
+- Keep `PRODUCT.md` and `CONCEPTS.md` as tool adapters pointing to the design
+  guide; keep `AGENTS.md`, its `CLAUDE.md` symlink and live donor provenance.
+  Label historical `artifacts/` and six `SCRATCH/` captures instead of deleting
+  evidence with unenumerated external readers. Ignore new scratch output.
+- Record the next-stage matte/glossy liquid catalog, widget coverage and donor
+  investigation in `docs/reference/liquid-next-stage-research.md`.
+  **That roadmap is research, not a shipped finish API or new widget suite.**
+
+### Consumer action: University 2.4.0 → 2.5.0
+
+Pin **all three** packages (`packages/ui`, `packages/world`, `apps/university`)
+to 2.5.0, then run the product's own gates. Existing imports need no migration.
+University was inspected read-only; it was **not** modified by this release.
+
+Migrating its custom `LiquidCtaButton` is a separate optional change:
+`width="full"` maps to `fullWidth`, while the product keeps destination
+registration, routing and `LiquidCtaTransition`. Its old uniform `scale=0.95`
+/ `bouncy` motion deliberately changes to the kit's existing `press` behavior
+only when that custom wrapper is migrated. Preserve transition source geometry,
+callback ordering and tests; do not discard the 823-line transition as if the
+kit had absorbed it. See the [upgrade playbook](docs/reference/usage-and-upgrade-playbook.md)
+for exact commands, CSS ownership, acceptance cases and rollback.
+
+This is a **minor**: additive opt-in layout and discovery, not a public-export
+restructure. Any future restructure still requires a major and compatibility path.
+
+## 2.4.0 — 2026-09-11
+
+Minor: additive. One new token, six new form names, and a cast shadow that
+every liquid body was missing.
+
+### Added
+
+- **A cast shadow on the single-body forms.** `LiquidSurface` accepted a
+  `shadow` and no form set one, so every liquid button floated: the flat button
+  standing next to it carries a solid lip *and* `--game-ui-shadow-button`, and
+  the liquid one carried neither. `press`, `settle`, `drain`, and the new
+  `swell`, `reach`, `ripple` and `set` now carry two layers each — a tight,
+  barely-offset seat that says the body is touching, and a wide low cast that
+  gives it height. Compared at device ratio 1 against the flat control, a seat
+  alone glues the body to the page and a cast alone leaves it hovering.
+
+  Every layer is outer and spreadless, which is the case
+  `compositorDropShadowFilter` lifts onto the compositor: it costs no filter
+  area and it hugs the poured outline rather than a rounded rectangle. A caller
+  that wants its own ground still passes `shadow`, and `shadow="none"` removes
+  it.
+
+- **`--game-ui-shadow-liquid-ink`.** The colour a liquid body casts, per theme.
+  It is a solid colour rather than a finished shadow, so a form states strength
+  and offset without restating the room's light. Deliberately **not** added to
+  `GAME_UI_THEME_CONTRACT`: that list is exported for downstream themes to
+  self-check, and adding an entry would turn a consumer's green check red for a
+  token they have never heard of. A theme that does not define it gets the
+  light theme's warm brown ink.
+
+- **`shadowEngaged` on a form, and a shadow that answers the gesture.** A
+  pressed body is nearer the ground, so its seat hardens and its cast collapses
+  toward it; `settle` rests mid-air with no seat at all and gains one on
+  landing, which is the moment that form exists to mark. The silhouette's
+  filter transitions, so the shadow no longer arrives before the thing casting
+  it.
+
+- **Six more forms: `set`, `swell`, `reach`, `ripple`, `split`, `bead`.** Each
+  says something none of the previous six could. `set` is the only one that
+  stops being liquid — everything else is a degree of wetness — and it snaps
+  rather than tweening, because setting is a discontinuity. `swell` is
+  attention with nothing touching it, so it is the one moving form with no
+  squash. `reach` is the only form with a direction. `ripple` says 「no」 by
+  moving and leaves its shape alone. `split` is `merge` backwards with a harder
+  edge and more recoil. `bead` is the one relationship form that pours, because
+  its bodies are the message rather than the neck between them.
+
+- **`kind` on every form, and `LiquidFormKind`.** A form is one body or a
+  relationship between siblings. `LiquidSurface` can only draw the first;
+  handing it a group form used to render a correct-looking body that silently
+  never moved, and it now warns once, in every build.
+
+- **`groupEngaged` on a form.** Group knobs that change while engaged. Only
+  `set` uses it. `blob` is path data and `gloss` is a filter pass, so neither
+  tweens — they snap, which is right for one form and a flicker for any other.
+
+- **`LIQUID_BLOB_MAX_FRACTION`.** The share of a box's shorter side a poured
+  outline may swell by (0.18). Exported because it is why one `blob` value can
+  be handed to a 44px button and a 14px meter, and a number written in three
+  places drifts in two.
+
+- **A Liquid page on the showcase site, at `/liquid.html`.** Every form live and
+  triggerable, at a control size and a meter size, on any of the four tones, in
+  both themes, with its knobs — including the derived edge width in px — written
+  out beside it.
+
+### Changed
+
+- **`GameUiPreview`'s liquid section is smaller.** It keeps what a component
+  gallery is for — `surface` is a second axis on `GameButton` — and links out to
+  the Liquid page for the vocabulary. Two shelves meant two to update and, in
+  practice, one of them lagging. Hosts that render `<GameUiPreview />` and do
+  not serve `liquid.html` will have a link that does not resolve; the section
+  otherwise stands on its own.
+
 ## 2.3.0 — 2026-09-11
 
 Minor: additive, plus one token value change on the default liquid fill.
@@ -196,7 +339,8 @@ removed member never worked makes the removal correct, not non-breaking.
   WebKit CPU-rasterises large SVG blurs. Inset and spread stay in SVG; they
   are not expressible as `drop-shadow()` and they are cheap. The pad no longer
   reserves the outer blur. Visual comparison of the segmented indicator and
-  the merged-blob story is in `SHADOW-COST.md`.
+  the merged-blob story is in `docs/archive/measurements/liquid-shadow-cost-2.0.0.md`
+  (formerly `SHADOW-COST.md`).
 
 - **Two authoring warnings were still dead in the published bundle.** 1.11.2
   unblocked the budget warnings; `LiquidGroup.Item` children-with-border and

package/README.md

@@ -9,10 +9,14 @@ Source is publicly readable. Use is governed by the
 [PieAI Limited Use License](./LICENSE), not an open-source license. The visual
 assets may not be extracted, modified, or redistributed as a standalone pack.
 
+- **Start here / 我该用哪个组件？**
+  [Primary button, liquid CTA, forms, panels and other tasks](docs/reference/component-selection-guide.md)
 - Design system truth (tokens, theming, motion, a11y):
-  `docs/reference/design-system-guide.md`
+  [Design system guide](docs/reference/design-system-guide.md)
 - Consumer onboarding / upgrade SOP / release checklist:
-  `docs/reference/usage-and-upgrade-playbook.md`
+  [Usage and upgrade playbook](docs/reference/usage-and-upgrade-playbook.md)
+- Exhaustive reference (not the starting point):
+  [Generated public API inventory](docs/reference/public-api-inventory.md)
 - Live catalog: `pnpm dev` (preview page) and `pnpm storybook`
 
 ## Install
@@ -20,7 +24,7 @@ assets may not be extracted, modified, or redistributed as a standalone pack.
 ```json
 {
   "dependencies": {
-    "@pieai/swimmer-ui-kit": "2.1.0"
+    "@pieai/swimmer-ui-kit": "2.5.0"
   }
 }
 ```
@@ -48,7 +52,7 @@ import '@pieai/swimmer-ui-kit/tailwind.css';
 
 ## What's inside
 
-- **~60 components** across: core controls (`GameButton`,
+- **Ready-to-use components** across: core controls (`GameButton`,
   `LiquidMetalButton`, `GameTabs`,
   `GameSlider`, `GameToggle`, `GameForms` inputs…), panels and windows
   (`GamePanel`, `GameCollapsiblePanel`, `GameWindowPanel`, `GameModal` on
@@ -145,10 +149,15 @@ See `CHANGELOG.md` for release history and migration notes.
 pnpm install
 pnpm dev              # preview page (token ledger + all surfaces)
 pnpm storybook        # component catalog
-pnpm typecheck && pnpm test && pnpm build && pnpm docs:check
+pnpm verify && pnpm docs:check
+pnpm api:inventory    # regenerate the public API index after a reviewed API change
 ```
 
 Releases use GitHub Actions Trusted Publishing: bump `package.json`, commit and
 push `main`, then run `gh workflow run npm-publish.yml --ref main`. The manual
 workflow is the release safety switch; it publishes to npmjs with short-lived
 OIDC credentials and provenance, without a local login or stored npm token.
+
+The former `doc/` tutorials and one-off root reports are catalogued in the
+[documentation and evidence relocation record](docs/archive/relocations-2.5.0.json). Historical
+material is retained, but installation and component selection follow the guides above.

package/dist/index.d.ts

@@ -1376,10 +1376,12 @@ export declare interface GameBuildLibraryProps {
     'data-testid'?: string | undefined;
 }
 
-export declare function GameButton({ children, className, onClick, sound, static: isStatic, surface, type, variant, ...props }: GameButtonProps): ReactNode;
+export declare function GameButton({ children, className, fullWidth, onClick, sound, static: isStatic, surface, type, variant, ...props }: GameButtonProps): ReactNode;
 
 export declare interface GameButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     children: ReactNode;
+    /** Fill the available row, including the liquid silhouette and hit target. */
+    fullWidth?: boolean;
     sound?: GameInteractionSoundOptions | false;
     /** Disable the scale-on-press feedback where the motion would distract. */
     static?: boolean;
@@ -2353,10 +2355,22 @@ export declare const LIQUID_FORMS: Readonly<Record<LiquidForm, LiquidFormSpec>>;
 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.
+ * The named looks.
+ *
+ * Bodies first, then the forms that only mean something between siblings, and
+ * within each run they are ordered by how much cohesion the liquid is losing:
+ * `set` stops being liquid at all, `press` barely deforms, `drain` stops being
+ * a shape.
+ *
+ * Six of these were the whole vocabulary until the brand needed more of it,
+ * and six is worth saying out loud as *where it got to* rather than as a
+ * complete set. A form earns its place by having something to say that none of
+ * the others says. That is the only entry requirement — and it is also why a
+ * form existing here is not permission to put it on a screen: the recorded
+ * finding is that gooey on a static solid block reads as damage, and that one
+ * screen wants one liquid element carrying one layer of intent.
  */
-export declare type LiquidForm = 'press' | 'settle' | 'merge' | 'follow' | 'fill' | 'drain';
+export declare type LiquidForm = 'set' | 'press' | 'swell' | 'settle' | 'fill' | 'reach' | 'ripple' | 'drain' | 'follow' | 'merge' | 'split' | 'bead';
 
 /** Filter-level knobs a form fixes on the group. */
 export declare interface LiquidFormGroup {
@@ -2377,6 +2391,32 @@ export declare interface LiquidFormGroup {
      */
     readonly gloss: number;
     readonly filterPadding: number;
+    /**
+     * What the body casts on the ground at rest, in CSS box-shadow syntax.
+     *
+     * Every liquid button floated before this existed: the flat button has a lip
+     * *and* `--game-ui-shadow-button`, and the liquid one had neither, which is
+     * most of why it read flatter than its own flat twin. A form is where this
+     * belongs rather than a call site, because how far a body sits off the
+     * surface is part of what the form means.
+     *
+     * Keep it to outer layers with no spread. `liquidGooeyShadow` compiles those
+     * to a CSS `drop-shadow()` on the silhouette — the compositor does the blur,
+     * the shadow hugs the poured outline rather than a rounded rectangle, and it
+     * is allowed to paint outside the filter region. Inset and spread are legal
+     * but stay inside the SVG filter and are charged against the filter-area
+     * budget, so they are a deliberate purchase, not a default.
+     */
+    readonly shadow?: string;
+    /**
+     * What it casts while the form is engaged, when that differs.
+     *
+     * A body that squashes toward the surface gets *closer* to it, and a real
+     * contact shadow answers by tightening and darkening rather than staying
+     * put. Leaving this out is fine; the rest shadow then holds through the
+     * whole gesture, which is what a form with no vertical travel wants.
+     */
+    readonly shadowEngaged?: string;
 }
 
 /**
@@ -2399,10 +2439,37 @@ export declare interface LiquidFormItem {
 /** Resolve a form into item props, with the same merge-don't-replace rule. */
 export declare function liquidFormItem(form: LiquidForm, overrides?: LiquidFormItem): LiquidFormItem;
 
+/**
+ * Whether a form describes one body or a relationship between siblings.
+ *
+ * `LiquidSurface` draws one silhouette, so it can only honour a `body` form;
+ * a `group` form says something about the space *between* items and needs a
+ * `LiquidGroup` the caller arranges. That distinction used to live in a
+ * parenthetical — `ENGAGED` carried two entries marked 「present for
+ * exhaustiveness」 — which meant picking the wrong one failed silently, by
+ * rendering a body that never moves. Naming it lets a shelf group itself, lets
+ * a caller check, and lets the kit say so out loud in development.
+ */
+export declare type LiquidFormKind = 'body' | 'group';
+
 export declare interface LiquidFormSpec {
     /** One sentence on what a viewer sees, for docs and for picking. */
     readonly summary: string;
+    /** One body, or a relationship between siblings the caller arranges. */
+    readonly kind: LiquidFormKind;
     readonly group: LiquidFormGroup;
+    /**
+     * Group knobs that change while the form is engaged.
+     *
+     * Only `set` uses this, and only because `set` is the one form whose subject
+     * is *stopping* being liquid — without it the vocabulary can say a dozen
+     * degrees of liquid and never say 「solid」. Be careful with it: `blob` is
+     * path data and `gloss` is a filter pass, so neither tweens. They snap. For
+     * `set` that snap is the gesture — a thing clicking into place — and for
+     * anything continuous it would be a flicker, which is why this is not a
+     * general-purpose second bundle.
+     */
+    readonly groupEngaged?: Partial<LiquidFormGroup>;
     readonly item: LiquidFormItem;
 }
 
@@ -2557,7 +2624,7 @@ 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 function LiquidSurface({ children, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
 
 export declare interface LiquidSurfaceProps {
     children: ReactNode;
@@ -2571,6 +2638,7 @@ export declare interface LiquidSurfaceProps {
     /** Silhouette paint. Defaults to the kit's raised surface token. */
     fill?: string;
     stroke?: string;
+    /** Overrides the form's own cast shadow. `none` removes it. */
     shadow?: string;
     /** Corner radius of the body, in px. 999 gives a pill. */
     radius?: number;