@pieai/swimmer-ui-kit 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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

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'> {
@@ -1469,7 +1477,7 @@ export declare interface GameCollapsiblePanelProps extends Omit<HTMLAttributes<H
  * 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, className, }: GameCollectibleCardProps): ReactNode;
+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;
@@ -1503,6 +1511,9 @@ export declare interface GameCollectibleCardProps {
     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;
 }
 
@@ -2893,6 +2904,19 @@ 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