@pieai/swimmer-ui-kit 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## Unreleased
+
+## 2.12.0 — 2026-09-29
+
+- Add optional `useGameCardOrientation` and the bounded `GameCardTilt` input
+  on `GameCollectibleCard`. One explicitly enabled hook serves the active card
+  in an album. Mounting does not request permission or subscribe to a sensor.
+  Secure context, denial, late permission, page visibility and reduced motion
+  have explicit state and cleanup; no sensor samples or consent are stored.
+- Preserve pointer/keyboard flipping and all omitted-prop behavior. A pointer
+  on the card wins over device tilt; reduced motion zeros both immediately.
+  Drag classification still applies under reduced motion, and a keyboard or
+  assistive click is not suppressed by a stale pointer gesture.
+- Add an opt-in Storybook example and isolated browser sensor-contract tests.
+  Synthetic sensor/permission cases are not physical-device permission evidence.
+
+## 2.11.0 — 2026-09-28
+
+Minor: University's V7 opening screen and card album, and the liquid fix
+NerveKit 0.6 pairs with.
+
+- Add `GameSplash`, the opening and scene-change screen: rotating selling
+  lines with a highlighted phrase, a progress bar that tracks real readiness,
+  and an enter button offered only once ready (the tap that also lets a web
+  page start sound). `mode="transition"` shows one line and the bar with no
+  button; `useGameSplashDelay` shows it only after a wait outlasts its delay.
+  All text comes from the product. First consumer: University's V7 opening.
+- Add `GameCollectibleCard` and `GameCollectibleCardSlot`: a printed card that
+  tilts toward the pointer with a glare that follows it and flips on a tap
+  (a drag that tilted it is not a tap). Framed by rarity: `common` silver,
+  `rare` violet with a gem, `legendary` gold with a crown, a foil kept off the
+  words, and an optional `spotlight` light turning behind it for the reveal.
+  The slot shows an uncollected card and what unlocks it. Card inks are theme
+  tokens (`--game-ui-collect-card-*`) that stay the same on every theme; band
+  inks meet 4.5:1. Reduced motion drops tilt, shine and the turning light.
+- Add `playGameCardRevealSound`: a synthesized flip, with bell notes for the
+  rarer cards. First consumer: University's V7 card album.
+- Fix the optional liquid styles yielding to the host: `liquid-presence.css`
+  now sits in `@layer swimmer-ui` like the main styles, so a product's
+  unlayered rules win without special selectors. `LiquidAnchor` reports the
+  area it occupies to the family's destination labels, which step around open
+  panels instead of needing a host z-index workaround. A `GameButton` with
+  `data-game-ui-control="liquid-presence"` lets its liquid body paint the
+  button and keeps native interaction. Paired with NerveKit 0.6.
+
 ## 2.10.0 — 2026-09-24
 
 Minor: publish the reviewed optional liquid interaction surface required by

package/dist/index.d.ts

@@ -1431,6 +1431,14 @@ export declare interface GameCardFanProps {
     label: string;
 }
 
+export declare type GameCardOrientationStatus = 'unavailable' | 'off' | 'requesting' | 'enabled' | 'denied';
+
+/** Normalized card tilt; zero is level, -1 and 1 are the bounded extremes. */
+export declare interface GameCardTilt {
+    readonly x: number;
+    readonly y: number;
+}
+
 export declare function GameCheckbox({ className, label, ...props }: GameCheckboxProps): ReactNode;
 
 export declare interface GameCheckboxProps extends Pick<InputHTMLAttributes<HTMLInputElement>, 'checked' | 'defaultChecked' | 'disabled' | 'name' | 'onChange' | 'required' | 'value'> {
@@ -1460,6 +1468,70 @@ export declare interface GameCollapsiblePanelProps extends Omit<HTMLAttributes<H
     tone?: 'default' | 'strong';
 }
 
+/**
+ * A collectible card: tilts toward the pointer with a glare that follows it,
+ * flips on a tap, and is framed by rarity. Built for a card album where
+ * collecting and reviewing are the same act, but it holds nothing about
+ * learning: every word and picture comes from the product.
+ *
+ * Under reduced motion the card does not tilt, shine or spin its light, and a
+ * flip is instant.
+ */
+export declare function GameCollectibleCard({ rarity, title, caption, setLabel, rarityLabel, art, pips, sticker, back, label, faceDown, defaultFaceDown, onFlip, spotlight, sound, tilt: externalTilt, className, }: GameCollectibleCardProps): ReactNode;
+
+export declare interface GameCollectibleCardProps {
+    readonly rarity: GameCollectibleCardRarity;
+    /** The card's name, large on the face. */
+    readonly title: string;
+    /** One line under the name. */
+    readonly caption?: string;
+    /** The set it belongs to, on the band at the top. */
+    readonly setLabel?: string;
+    /** The rarity's short word, in the band's chip. */
+    readonly rarityLabel?: string;
+    /** The illustration; the product supplies it. */
+    readonly art?: ReactNode;
+    /** A row of pips under the caption, such as progress toward the next rarity. */
+    readonly pips?: {
+        readonly filled: number;
+        readonly total: number;
+    };
+    /** A sticker on the corner, such as "NEW!". */
+    readonly sticker?: string;
+    /** The back of the card; the kit draws a plain emblem when omitted. */
+    readonly back?: ReactNode;
+    /** The full accessible name, including what a tap does. */
+    readonly label: string;
+    /** Controlled: whether the back is showing. */
+    readonly faceDown?: boolean;
+    /** Uncontrolled start. */
+    readonly defaultFaceDown?: boolean;
+    readonly onFlip?: (faceDown: boolean) => void;
+    /** A soft light turns behind the card: the moment the rarest card is revealed. */
+    readonly spotlight?: boolean;
+    /** Play a synthesized flip sound; browsers allow it only after the page has been tapped. */
+    readonly sound?: boolean;
+    /** Optional normalized tilt from one explicitly enabled sensor owner. A
+     * pointer on this card takes precedence; reduced motion always wins. */
+    readonly tilt?: GameCardTilt | null;
+    readonly className?: string;
+}
+
+/**
+ * How rare the card is, which is how it is framed: `common` a plain silver
+ * frame, `rare` a violet frame with a gem set in the top, `legendary` a gold
+ * frame with a crown, a foil that shifts as the card tilts and a soft light
+ * behind it. The product decides what earns each; the kit only draws them.
+ */
+export declare type GameCollectibleCardRarity = 'common' | 'rare' | 'legendary';
+
+/** A card not collected yet: its place in the set, and what unlocks it. Not interactive. */
+export declare function GameCollectibleCardSlot({ label, className, }: {
+    /** What unlocks it, shown on the slot and read as its name. */
+    readonly label: string;
+    readonly className?: string;
+}): ReactNode;
+
 export declare function GameCompactGameDrawer({ children, className, closeIcon, closeLabel, disabled, label, onOpenChange, open, panelId: providedPanelId, title, triggerIcon, triggerLabel, variant, 'data-testid': testId, }: GameCompactGameDrawerProps): ReactNode;
 
 export declare interface GameCompactGameDrawerProps {
@@ -2067,6 +2139,53 @@ export declare interface GameSliderProps extends Pick<InputHTMLAttributes<HTMLIn
     onChange?: (value: number) => void;
 }
 
+/**
+ * The opening screen and the scene-change screen, one look for both.
+ *
+ * Its whole job is to make the wait worth watching and honest: the lines say
+ * what the product is for, the bar tracks what is really loading, and entering
+ * is offered only when the thing behind it is complete — nobody is held back
+ * for effect, and nobody walks into a half-drawn scene.
+ */
+export declare function GameSplash({ title, lines, progress, progressLabel, ready, mode, startLabel, onStart, autoStart, lineSeconds, className, }: GameSplashProps): ReactNode;
+
+/**
+ * One selling line on the splash. `highlight` is a word or phrase inside
+ * `text` that lights up as the line appears; the product supplies both in the
+ * learner's language, the kit supplies none.
+ */
+export declare interface GameSplashLine {
+    readonly text: string;
+    readonly highlight?: string;
+}
+
+export declare interface GameSplashProps {
+    /** The product's name, shown large. */
+    readonly title: string;
+    /** Two or three lines a visit; they take turns while the product loads. */
+    readonly lines: readonly GameSplashLine[];
+    /** Real readiness, 0 to 1. Never a timer: a bar stuck at 99% is worse than none. */
+    readonly progress: number;
+    /** What the bar says, including the number if the product wants it shown. */
+    readonly progressLabel: string;
+    /** Everything the first screen needs has arrived and drawn once. */
+    readonly ready: boolean;
+    /**
+     * `opening`: the first screen, with a tap to enter once ready (the tap is
+     * also what lets a web page start sound). `transition`: the same look over a
+     * scene change, one line and the bar, no button.
+     */
+    readonly mode?: 'opening' | 'transition';
+    /** The enter button's text, opening mode only. */
+    readonly startLabel?: string;
+    readonly onStart?: () => void;
+    /** Enter by itself when ready, for app shells that need no gesture for sound. */
+    readonly autoStart?: boolean;
+    /** Seconds each line stays before the next. */
+    readonly lineSeconds?: number;
+    readonly className?: string;
+}
+
 export declare function GameStageTile({ badge, className, icon, kicker, selected, summary, title, tone, type, ...props }: GameStageTileProps): ReactNode;
 
 export declare interface GameStageTileProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -2710,6 +2829,15 @@ export declare interface MorphTuning {
     advanced?: Partial<EvolveOptions>;
 }
 
+export declare function playGameCardRevealSound(rarity: 'common' | 'rare' | 'legendary', options?: GameInteractionSoundOptions): boolean;
+
+/**
+ * A card turning over: a short falling sweep, and for a rarer card one or two
+ * bell notes after it. Synthesized, so nothing is downloaded; like every kit
+ * sound, the browser lets it play only once the page has been interacted with.
+ */
+export declare function playGameCardRevealSoundForContext(audioContext: GameInteractionAudioContext, rarity: 'common' | 'rare' | 'legendary', options?: GameInteractionSoundOptions): boolean;
+
 export declare function playGameInteractionSound(options?: GameInteractionSoundOptions): boolean;
 
 export declare function playGameInteractionSoundForContext(audioContext: GameInteractionAudioContext, options?: GameInteractionSoundOptions): boolean;
@@ -2776,4 +2904,24 @@ declare type Transition = TransitionPreset | SpringConfig | {
 
 declare type TransitionPreset = 'snappy' | 'smooth' | 'bouncy' | 'wobbly';
 
+/** One optional sensor owner for an album or preview, NOT one per card.
+ * Call enable from a real user action, then pass tilt only to the active card.
+ * No permission, storage, microphone, motion sensor or network request occurs
+ * on mount. Reduced motion cancels consent in flight and requires a new action;
+ * hiding the page pauses samples and recalibrates on return. */
+export declare function useGameCardOrientation(): {
+    status: GameCardOrientationStatus;
+    tilt: GameCardTilt | null;
+    enable: () => Promise<boolean>;
+    disable: () => void;
+    reducedMotion: boolean;
+};
+
+/**
+ * Whether a waiting screen should appear yet: only once `waiting` has stayed
+ * true for `delayMs` without a break. A scene change that finishes inside the
+ * delay never shows the screen at all.
+ */
+export declare function useGameSplashDelay(waiting: boolean, delayMs?: number): boolean;
+
 export { }