@pieai/swimmer-ui-kit 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -3,6 +3,133 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 2.6.0 — 2026-09-12
+
+Minor: new optional material selection and native controls. Existing root
+exports and export-map paths remain; omitted options retain prior defaults.
+
+### Added
+
+- `LiquidFinish` and optional `liquidFinish="matte" | "glossy"` across
+  LiquidGroup/LiquidSurface, GameButton, GameIconButton, GameToggle,
+  GameSegmentedControl, GameProgress and GameSelect. Both finishes reuse the
+  existing renderer; matte removes the specular pass, not motion or shadows.
+  Explicit LiquidGroup `gloss` remains the advanced override.
+- Liquid icon buttons and switch thumbs; GameSelect uses a real native select
+  with optional liquid closed-field decoration, form/reset/ref/optgroup support,
+  invalid semantics and ordinary disabled/multiple/list modes. The popup remains
+  platform-native; this is not a searchable combobox or custom liquid listbox.
+- Optional flat, filter-free progress and segmented surfaces. Slider forwards
+  native step, disabled, name and id.
+- A beginner catalog at the site root: 12 shared recipe groups, 6 liquid control
+  categories, matte/glossy comparison, theme/state selection, actual interaction,
+  complete copyable/typechecked React examples and shareable configuration URLs.
+  Storybook uses the same recipes. The old reference remains at `/?view=reference`
+  and old `#game-ui-preview-*` links still open it.
+
+### Fixed and intentionally changed
+
+- Press decoration ignores secondary pointer buttons and key repeat, clears on
+  lost capture/cancellation/blur, resets through disabled, and honors `static`.
+  Native content and hit targets never inherit the squash transform.
+- The liquid button's native element no longer picks up the ordinary button's
+  independent CSS `scale` on press or hover lift; only the silhouette moves.
+- Pointer feedback survives macOS WebKit's native pointerdown-then-blur ordering;
+  a true window deactivation still cancels the gesture. No focus is forced onto
+  the native control to hide this platform difference.
+- Progress ARIA values now agree with the clamped visible value, including invalid
+  maxima and non-finite input. Forced-colors decoration falls back to system UI.
+- `GameInput` and `GameTextArea` now expose `invalid` through `aria-invalid`,
+  like the new select; an explicit ARIA value still wins.
+- Select decoration is a sibling of the persistent native field. Disabling,
+  changing material or switching single/list presentation must not remount the
+  select and lose an uncontrolled choice or replace its forwarded DOM ref.
+  Catalog material/state adjustments likewise preserve the current example's
+  entered values instead of silently resetting the recipe.
+- Disabled icon buttons, switches and segmented options now have a quiet,
+  non-hovering treatment. Disabled segmented controls retain the selected option
+  on a flat surface instead of reserving animated liquid groups.
+  Inherited native fieldset disabling also hides button/icon/switch/select decoration.
+- The liquid form page selects experiments instead of mounting every form, size,
+  tone and state simultaneously. At most two liquid groups are mounted; the shared
+  budget was not increased and the twelve forms were not removed or retuned.
+
+### Consumer action
+
+Pin the new version and run your own product gates. New materials/controls are
+opt-in; University was not modified. Do not remove its destination/route transition
+when adopting kit buttons. See the upgrade playbook for adoption and rollback.
+No new runtime dependency, ambient clock, donor observer, image optimization or
+commercial donor preset is introduced by this release.
+
+## 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
@@ -271,7 +398,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,18 +9,26 @@ 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`
-- Live catalog: `pnpm dev` (preview page) and `pnpm storybook`
+  [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)
+- [Interactive catalog](https://swimmer-ui-kit.pieaistudio.com/): real controls,
+  matte/glossy comparison, theme/state selectors and copyable React examples.
+- [Full reference](https://swimmer-ui-kit.pieaistudio.com/?view=reference) and
+  [liquid form laboratory](https://swimmer-ui-kit.pieaistudio.com/liquid.html).
+  Local: `pnpm dev` and `pnpm storybook`.
 
 ## Install
 
 ```json
 {
   "dependencies": {
-    "@pieai/swimmer-ui-kit": "2.1.0"
+    "@pieai/swimmer-ui-kit": "2.6.0"
   }
 }
 ```
@@ -48,7 +56,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 +153,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

@@ -5,6 +5,7 @@ import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { SelectHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 
 /** Opt in to placeholders on purpose, and stop being told about it. */
@@ -1376,10 +1377,14 @@ 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, liquidFinish, 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;
+    /** Named liquid material. Only used with surface="liquid"; omitted keeps the current look. */
+    liquidFinish?: LiquidFinish;
     sound?: GameInteractionSoundOptions | false;
     /** Disable the scale-on-press feedback where the motion would distract. */
     static?: boolean;
@@ -1725,11 +1730,13 @@ export declare interface GameHudProps {
     label: string;
 }
 
-export declare function GameIconButton({ children, className, label, type, ...props }: GameIconButtonProps): ReactNode;
+export declare function GameIconButton({ children, className, label, surface, liquidFinish, type, ...props }: GameIconButtonProps): ReactNode;
 
 export declare interface GameIconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     children: ReactNode;
     label: string;
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
 }
 
 export declare const GameInput: ForwardRefExoticComponent<GameInputProps & RefAttributes<HTMLInputElement>>;
@@ -1910,9 +1917,12 @@ export declare interface GamePlacementToolbarProps {
     title: string;
 }
 
-export declare function GameProgress({ className, label, max, showValue, tone, value, valueLabel, }: GameProgressProps): ReactNode;
+export declare function GameProgress({ className, label, max, showValue, tone, value, valueLabel, surface, liquidFinish, }: GameProgressProps): ReactNode;
 
 export declare interface GameProgressProps {
+    /** Defaults to the existing liquid leading edge. Flat adds no SVG filter. */
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
     /** Current value, between 0 and `max`. */
     value: number;
     max?: number;
@@ -1978,13 +1988,17 @@ export declare const GameSceneHudLayout: typeof GameShell;
 
 export declare type GameSceneHudLayoutProps = GameShellProps;
 
-export declare function GameSegmentedControl({ activeId, label, onSelect, options, }: GameSegmentedControlProps): ReactNode;
+export declare function GameSegmentedControl({ activeId, label, onSelect, options, surface, liquidFinish, disabled, }: GameSegmentedControlProps): ReactNode;
 
 export declare interface GameSegmentedControlProps {
     activeId: string;
     label: string;
     onSelect?: (id: string) => void;
     options: readonly GameSegmentedOption[];
+    /** Existing default is liquid. Flat provides a quiet, filter-free option. */
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
+    disabled?: boolean;
 }
 
 declare interface GameSegmentedOption {
@@ -1992,6 +2006,20 @@ declare interface GameSegmentedOption {
     label: string;
 }
 
+/**
+ * Native select, not a custom listbox state machine. Options/optgroups, form
+ * submission, reset, keyboard and the mobile picker remain browser-owned.
+ * Liquid paints only the closed single-select field. Disabled/multiple/list
+ * modes use the ordinary surface; we do not pretend to animate an OS popup.
+ */
+export declare const GameSelect: ForwardRefExoticComponent<GameSelectProps & RefAttributes<HTMLSelectElement>>;
+
+export declare interface GameSelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+    invalid?: boolean;
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
+}
+
 export declare function GameShell({ assetLibrary, bottomBar, children, className, density, hud, layout, movementPad, overlay, sidePanel, title, }: GameShellProps): ReactNode;
 
 export declare interface GameShellProps {
@@ -2016,9 +2044,9 @@ export declare interface GameShellProps {
     title: string;
 }
 
-export declare function GameSlider({ label, max, min, onChange, value }: GameSliderProps): ReactNode;
+export declare function GameSlider({ label, max, min, step, disabled, name, id, onChange, value, }: GameSliderProps): ReactNode;
 
-export declare interface GameSliderProps extends Pick<InputHTMLAttributes<HTMLInputElement>, 'max' | 'min' | 'value'> {
+export declare interface GameSliderProps extends Pick<InputHTMLAttributes<HTMLInputElement>, 'max' | 'min' | 'value' | 'step' | 'disabled' | 'name' | 'id'> {
     label: string;
     onChange?: (value: number) => void;
 }
@@ -2198,11 +2226,13 @@ export declare interface GameToastProps {
     tone?: 'info' | 'success' | 'danger';
 }
 
-export declare function GameToggle({ checked, disabled, label, onClick }: GameToggleProps): ReactNode;
+export declare function GameToggle({ checked, disabled, label, onClick, surface, liquidFinish, }: GameToggleProps): ReactNode;
 
 export declare interface GameToggleProps extends Pick<ButtonHTMLAttributes<HTMLButtonElement>, 'disabled' | 'onClick'> {
     checked: boolean;
     label: string;
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
 }
 
 export declare function GameTooltip({ children, label }: GameTooltipProps): ReactNode;
@@ -2352,6 +2382,9 @@ export declare const LIQUID_FORMS: Readonly<Record<LiquidForm, LiquidFormSpec>>;
  */
 export declare const LIQUID_GOOEY_WAVINESS_MAX_FRACTION = 0.3;
 
+/** Material is independent of a widget's meaning and a form's motion. */
+export declare type LiquidFinish = 'matte' | 'glossy';
+
 /**
  * The named looks.
  *
@@ -2530,6 +2563,8 @@ export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivEle
      * curved surface so it reads as a material rather than as a silhouette.
      */
     gloss?: number;
+    /** Optional named finish. An explicit raw gloss wins; omitted preserves the old rendering. */
+    liquidFinish?: LiquidFinish;
     /** Surface fill. Defaults to the kit's theme surface token. */
     fill?: string;
     /** Extra filter-region slack in px for the silhouette's painted edges. */
@@ -2622,10 +2657,12 @@ export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTM
 
 export declare type LiquidMetalRendererMode = 'auto' | 'css' | 'webgl';
 
-export declare function LiquidSurface({ children, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
+export declare function LiquidSurface({ children, liquidFinish, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
 
 export declare interface LiquidSurfaceProps {
     children: ReactNode;
+    /** Omitted keeps the form's existing lighting; matte and glossy share the same motion. */
+    liquidFinish?: LiquidFinish;
     /** Which named look. Defaults to the press form, the one a control wants. */
     form?: LiquidForm;
     /**