@kromatv/sdk 0.1.40-canary.0

package/types/ui/src/components/organisms/player/hooks/use-drag-track.d.ts

@@ -0,0 +1,22 @@
+import type { LayoutChangeEvent, View } from 'react-native';
+interface DragTrack {
+    /** Put on the track view, alongside `onLayout`. */
+    ref: React.RefObject<View | null>;
+    onLayout: (e: LayoutChangeEvent) => void;
+    /** Re-read the on-screen box. Call as a gesture begins: it is the last moment
+     *  before the number matters, and the stage may have been resized since. */
+    measure: () => void;
+    /** The track's width in canvas units, as state, for anything that renders. */
+    width: number;
+    /** A pointer's `locationX`, relative to the track, as an offset in canvas
+     *  units. Null until the track has been measured. */
+    offsetOf: (locationX: number) => number | null;
+}
+/**
+ * Every layer inside the track should be `pointerEvents: 'none'`, so the track is
+ * always the event's target and `locationX` is relative to the track itself
+ * rather than to whichever fill happened to be under the finger.
+ */
+declare function useDragTrack(): DragTrack;
+export type { DragTrack };
+export { useDragTrack };

package/types/ui/src/components/organisms/player/hooks/use-grid-focus.d.ts

@@ -0,0 +1,19 @@
+import type { RemoteKey } from '@kroma/core';
+export interface GridFocusOptions {
+    count: number;
+    cols: number;
+    initial?: number;
+    onActivate?: (index: number) => void;
+    onBack?: () => void;
+    onExit?: (edge: 'top' | 'bottom') => void;
+}
+export interface GridFocus {
+    index: number;
+    setIndex: (i: number) => void;
+    onKey: (key: RemoteKey) => boolean;
+    hover: (i: number) => () => void;
+    /** Bumps on every D-pad move but not on hover: scrolling the focused card into
+     *  view on hover would shift the layout under the cursor. */
+    keyNonce: number;
+}
+export declare function useGridFocus(opts: GridFocusOptions): GridFocus;

package/types/ui/src/components/organisms/player/hooks/use-idle-cursor.d.ts

@@ -0,0 +1,7 @@
+/** The player root's element id, which the idle-cursor rule hooks onto. */
+export declare const PLAYER_ROOT_ID = "kroma-player";
+/**
+ * Takes the pointer away while the chrome is away, and gives it back with it -
+ * what YouTube's `ytp-autohide` does. A no-op on a target with no document.
+ */
+export declare function useIdleCursor(hidden: boolean): void;

package/types/ui/src/components/organisms/player/hooks/use-list-focus.d.ts

@@ -0,0 +1,40 @@
+import type { RemoteKey } from '@kroma/core';
+/**
+ * Reusable 1-D focus for a list of controls, driving BOTH the D-pad and the
+ * mouse from one index. Every selection panel (Quality, Audio, Speed, Subtitles)
+ * and every "value row" surface (subtitle appearance, the AI-gen wizard) uses
+ * it, so the focus-ring behaviour is identical everywhere.
+ *
+ * - vertical   : ▲▼ move the row, ◀▶ call `onHorizontal` (value rows) or `onExit`.
+ * - horizontal : ◀▶ move, ▲▼ call `onExit`.
+ * `onKey` returns whether the key was consumed.
+ */
+export interface ListFocusOptions {
+    count: number;
+    orientation?: 'vertical' | 'horizontal';
+    initial?: number;
+    /** OK/Enter on the focused index. */
+    onActivate?: (index: number) => void;
+    /** Back / Escape (dismiss the surface). */
+    onBack?: () => void;
+    /** Moving off an edge: `before` = ▲/◀ past the first, `after` = ▼/▶ past the last. */
+    onExit?: (edge: 'before' | 'after') => void;
+    /** Cross-axis nudge (▲▼ list → ◀▶ adjusts the focused row's value). */
+    onHorizontal?: (index: number, dir: -1 | 1) => void;
+    /** A control ABOVE the list - the panel's Back button - reached by ▲ from the
+     *  first row, and run by OK there. Without it that button is pointer-only and
+     *  a remote cannot reach it at all. While it holds the focus, `index` is -1,
+     *  which is what the panel renders it lit from.
+     *
+     *  A list inside a <SettingsPanel> sub-view inherits this from the panel (see
+     *  lib/panel-header) and does not pass it. */
+    header?: () => void;
+}
+export interface ListFocus {
+    index: number;
+    setIndex: (i: number) => void;
+    onKey: (key: RemoteKey) => boolean;
+    /** Hover handler for row `i` (mouse moves focus, per §15). */
+    hover: (i: number) => () => void;
+}
+export declare function useListFocus(opts: ListFocusOptions): ListFocus;

package/types/ui/src/components/organisms/player/hooks/use-player-credits.d.ts

@@ -0,0 +1,22 @@
+import type { Marker } from '@kroma/client/media';
+export interface CreditsState {
+    show: boolean;
+    secondsLeft: number;
+    total: number;
+    cancel: () => void;
+}
+/**
+ * Credits-aware next-episode autoplay (§11). Shows the card once playback enters
+ * the `credits` marker (or the last {@link CREDITS_TAIL}s when unmarked), runs a
+ * fixed 5s countdown that advances at 0, and also advances on the real end. The
+ * countdown is frozen during a scrub, so seeking near the end never teleports.
+ */
+export declare function usePlayerCredits(opts: {
+    markers?: readonly Marker[];
+    dur: number;
+    cur: number;
+    seeking: boolean;
+    endedNonce: number;
+    hasNext: boolean;
+    onAdvance: () => void;
+}): CreditsState;

package/types/ui/src/components/organisms/player/hooks/use-player-ending.d.ts

@@ -0,0 +1,37 @@
+import type { Marker } from '@kroma/client/media';
+import type { RemoteKey } from '@kroma/core';
+import type { PostPlayFocus, PostPlayItem } from '#ui/components/organisms/player/parts/post-play';
+import type { UpNextItem } from '#ui/components/organisms/player/parts/up-next-sheet';
+import type { PlayerController } from '#ui/components/organisms/player/types';
+import { type CreditsState } from './use-player-credits';
+export interface PlayerEnding {
+    credits: CreditsState;
+    creditsFocus: 'play' | 'cancel';
+    onCreditsKey: (key: RemoteKey) => boolean;
+    /** Whether the end screen has the stage, which it only ever takes with a film
+     *  to offer on it. */
+    over: boolean;
+    postPlayFocus: PostPlayFocus;
+    onPostPlayKey: (key: RemoteKey) => void;
+    playOffer: () => void;
+    goHome: () => void;
+}
+/**
+ * Everything the player does as a film runs out (§10, §11), which is two
+ * mutually exclusive things: with an episode queued the credits card counts
+ * down to it, and with none the end raises the post-play screen or leaves.
+ * Both hang off the same `endedNonce`, which is why they are one hook.
+ */
+export declare function usePlayerEnding(opts: {
+    controller: PlayerController;
+    markers?: readonly Marker[];
+    postPlay?: PostPlayItem | null;
+    onPlayNext?: () => void;
+    onPlayItem?: (item: UpNextItem) => void;
+    onGoHome?: () => void;
+    /** Leave the player: the post-play's fallback home, and where an end with
+     *  nothing to offer goes. */
+    onLeave: () => void;
+    /** Called before the end screen rises, so it never covers an open panel. */
+    onClearOverlay: () => void;
+}): PlayerEnding;

package/types/ui/src/components/organisms/player/hooks/use-player-keys.d.ts

@@ -0,0 +1,8 @@
+import { type PlayerKeysParams } from '#ui/components/organisms/player/lib/player-keys';
+/**
+ * Route the TV remote into the player; the native mirror of `usePlayerKeys.web.ts`
+ * (same routing, different source: Metro picks this file, Vite the `.web` one).
+ * No `preventDefault`: a claimed TV event has no default to suppress.
+ */
+export declare function usePlayerKeys(params: Readonly<PlayerKeysParams>): void;
+export type { PlayerKeysParams };

package/types/ui/src/components/organisms/player/hooks/use-player-keys.web.d.ts

@@ -0,0 +1,5 @@
+import { type PlayerKeysParams } from '#ui/components/organisms/player/lib/player-keys';
+/** The single window keydown router. One stable listener always sees the latest
+ * render, so re-renders never re-subscribe. */
+export declare function usePlayerKeys(params: Readonly<PlayerKeysParams>): void;
+export type { PlayerKeysParams };

package/types/ui/src/components/organisms/player/hooks/use-player-nav.d.ts

@@ -0,0 +1,58 @@
+import type { RemoteKey } from '@kroma/core';
+import type { ControlId, Overlay, Zone } from '#ui/components/organisms/player/lib/nav';
+import type { PlayerCloseReason } from '#ui/components/organisms/player/types';
+/** Actions the top-level machine invokes; the shell wires them to the controller. */
+export interface PlayerNavActions {
+    togglePlay(): void;
+    /** Discrete seek, -1 = back / +1 = forward (±10 s), from the progress zone or
+     *  the rewind/forward transport buttons. */
+    seekNudge(dir: -1 | 1): void;
+    onNext(): void;
+    hasNext: boolean;
+    /** Volume ±5 % (§4b) when the volume control is focused. */
+    volumeNudge(dir: -1 | 1): void;
+    toggleMute(): void;
+    togglePip(): void;
+    toggleFullscreen(): void;
+    /** Hand this film to a TV. Only reachable when `flags.cast` is on, which the
+     *  host sets while a receiver is live. */
+    onCast?(): void;
+    /** Leave the player, told why: OK on the back button, Back at the top level,
+     *  or the Stop media key. */
+    onExit(reason: PlayerCloseReason): void;
+}
+export interface PlayerNav {
+    revealed: boolean;
+    zone: Zone;
+    overlay: Overlay;
+    controls: readonly ControlId[];
+    /** The focused control id, or null when the progress zone / a panel is active. */
+    focusedControl: ControlId | null;
+    /** Route a logical key. The shell calls this after giving any open panel first
+     *  refusal. */
+    handleKey(key: RemoteKey): void;
+    /** Reveal the chrome + (re)arm the auto-hide timer (pointer move / any key). */
+    poke(): void;
+    /** Re-arm the auto-hide timer WITHOUT revealing the chrome. Used by immersive
+     *  media shortcuts so repeated arrow presses don't flash the UI. */
+    rearmHide(): void;
+    openOverlay(o: Exclude<Overlay, null>): void;
+    closeOverlay(): void;
+    /** Run a control's action (shared by mouse click and D-pad OK). */
+    activate(id: ControlId): void;
+    /** Mouse focus helpers (hover moves focus, §15). */
+    focusControl(id: ControlId): void;
+    focusProgress(): void;
+}
+/**
+ * The unified navigation state machine (§3): three-zone D-pad + pointer focus,
+ * feature-flag-aware control stops, "▲ from the progress bar hides the UI", and
+ * the auto-hiding chrome. It owns zone/overlay/focus; panels manage their own
+ * internal focus (see useListFocus / useGridFocus) and the shell routes keys to
+ * the open panel first.
+ *
+ * `controls` must be exactly the row as drawn (see ../lib/metrics
+ * `chromeMetrics`): the machine steps through only the controls on screen, so a
+ * shed control never keeps a focus stop nobody can see.
+ */
+export declare function usePlayerNav(playing: boolean, actions: PlayerNavActions, controls: readonly ControlId[]): PlayerNav;

package/types/ui/src/components/organisms/player/hooks/use-player-outro.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What happens when a film reaches its end with nothing queued behind it (§10).
+ * A next episode is the credits countdown's business (see usePlayerCredits);
+ * this covers everything else, so the player never parks on a dead frame: it
+ * offers the next film to watch, and with none to offer it leaves.
+ */
+export declare function usePlayerOutro(opts: {
+    endedNonce: number;
+    hasNext: boolean;
+    /** Whether there is a film to offer. False leaves instead. */
+    canOffer: boolean;
+    onOffer: () => void;
+    onLeave: () => void;
+}): void;

package/types/ui/src/components/organisms/player/hooks/use-seek-nudge.d.ts

@@ -0,0 +1,8 @@
+import type { PlayerController } from '#ui/components/organisms/player/types';
+/**
+ * A directional seek that ramps while the button is held.
+ *
+ * Returns the `seekNudge(dir)` the nav machine calls for ◀ / ▶ on the progress
+ * bar and for the rewind / forward transport buttons.
+ */
+export declare function useSeekNudge(controller: PlayerController): (dir: -1 | 1) => void;

package/types/ui/src/components/organisms/player/index.d.ts

@@ -0,0 +1,22 @@
+export { PLAYER_ROOT_ID } from './hooks/use-idle-cursor';
+export { AUDIO_FILTER_KEY, audioFilterLabels, storedAudioFilter, useAudioFilter, } from './lib/audio-filter';
+export { currentChapter, currentChapterIndex, normalizeChapters } from './lib/chapters';
+export { endsAtClock, pct } from './lib/fmt';
+export { buildLeanStats, type LeanStatsInput, type LeanStatsVideoHandle, } from './lib/lean-stats';
+export { type SeekBarPaint, seekBar } from './lib/style';
+export { DEFAULT_SUB_APPEARANCE, migrateAppearance, SUB_COLORS, SUB_EDGES, SUB_FONTS, type SubEdge, type SubFont, type SubSize, type SubtitleAppearance, subtitleStyle, subtitleWindowStyle, useSubtitleAppearance, withOpacity, } from './lib/subtitle-appearance';
+export type { CreditsCardItem } from './parts/credits-card';
+export { POST_PLAY_ART_W, type PostPlayItem } from './parts/post-play';
+export type { SubtitleGenBundle, SubtitleGenRequest } from './parts/settings-panel/settings/gen';
+export { PICTURE_ID as PLAYER_PICTURE_ID, STAGE_ID as PLAYER_STAGE_ID } from './parts/stage/stage';
+export { StatsPanel } from './parts/stats-panel';
+export { SUBTITLE_LAYER_ID as PLAYER_SUBTITLE_ID } from './parts/subtitle-renderer/subtitle-renderer';
+export type { SurfaceRadius } from './parts/surface-radius';
+export { SurfaceRadiusProvider, useSurfaceRadius } from './parts/surface-radius';
+export { UP_NEXT_ART_W } from './parts/up-next-card';
+export type { UpNextData, UpNextItem } from './parts/up-next-sheet';
+export type { PlayerRootProps } from './player';
+export { Player } from './player';
+export type { PlayerActionsProps, PlayerMediaProps, PlayerPanelProps } from './player-parts';
+export type { AudioFilterMode, Chapter, PlaneRect, PlayerCloseDetails, PlayerCloseReason, PlayerController, PlayerFlags, PlayerMeter, PlayerQuality, PlayerStats, PlayerSub, PlayerSurface, } from './types';
+export { TV_FLAGS, WEB_FLAGS } from './types';

package/types/ui/src/components/organisms/player/lib/audio-filter.d.ts

@@ -0,0 +1,15 @@
+import type { MessageKey, Translate } from '@kroma/core';
+import { type RefObject } from 'react';
+import type { AudioFilterMode } from '#ui/components/organisms/player/types';
+export declare const AUDIO_FILTER_KEY: Record<AudioFilterMode, MessageKey>;
+export declare function audioFilterLabels(t: Translate): Record<AudioFilterMode, string>;
+/** Synchronous, so a native engine can apply the remembered mode at
+ * construction, before React state has hydrated. `off` without storage/DOM. */
+export declare function storedAudioFilter(): AudioFilterMode;
+/** `remountKey` must change whenever the parent remounts the <video>, so the
+ * graph re-attaches to the fresh element. */
+export declare function useAudioFilter(videoRef: RefObject<HTMLVideoElement | null>, remountKey: string): {
+    mode: AudioFilterMode;
+    setMode: (m: AudioFilterMode) => void;
+    supported: boolean;
+};

package/types/ui/src/components/organisms/player/lib/chapters.d.ts

@@ -0,0 +1,16 @@
+import type { Chapter } from '#ui/components/organisms/player/types';
+/**
+ * The chapter model behind the progress bar (§1). Real chapter data passes
+ * through normalized; with none, the bar degrades to a single continuous
+ * segment. Intro/credits markers are drawn as ticks independent of chapters.
+ */
+/**
+ * Sort, clamp and gap-fill raw chapter data into a clean, contiguous list.
+ * Returns `[]` when there is nothing meaningful to segment (0/1 chapters), so
+ * the bar renders as a plain progress bar.
+ */
+export declare function normalizeChapters(raw: readonly Chapter[] | null | undefined, durMs: number): Chapter[];
+/** Index of the chapter containing `posMs`, or -1 when there are no chapters. */
+export declare function currentChapterIndex(chapters: readonly Chapter[], posMs: number): number;
+/** Convenience: the chapter object at `posMs`, or null. */
+export declare function currentChapter(chapters: readonly Chapter[], posMs: number): Chapter | null;

package/types/ui/src/components/organisms/player/lib/chart-geometry.d.ts

@@ -0,0 +1,46 @@
+export declare const CHART_WINDOW = 80;
+export interface ChartBox {
+    /** Drawable width. `x = width` is the newest sample. */
+    width: number;
+    height: number;
+    /** Vertical inset, so a 2px stroke never clips against the extremes. */
+    padY: number;
+    /** Samples across the full width. Defaults to CHART_WINDOW. */
+    window?: number;
+}
+export interface Extent {
+    min: number;
+    max: number;
+}
+/**
+ * The value range every series in one chart shares, so two series (e.g.
+ * bandwidth and bitrate) can be read against each other without inventing a
+ * crossover that isn't in the data. `reference` widens the range so a floor
+ * line is never drawn outside the box; a flat series gets a symmetric ±1
+ * instead of dividing by zero.
+ */
+export declare function extentOf(series: readonly (readonly number[])[], reference?: number): Extent;
+/** Sample index → x. Right-anchored: the newest sample sits at `box.width`. */
+export declare function xAt(index: number, count: number, box: ChartBox): number;
+/** Value → y. Larger values sit higher, which is why this inverts. */
+export declare function yAt(value: number, extent: Extent, box: ChartBox): number;
+/** Quantise to 0.1px: finer precision is invisible at this size, and the shorter
+ * `d` string is what actually crosses into the renderer on every tick. */
+export declare function px(n: number): number;
+/**
+ * `d` for one open trace. Empty when there is not yet enough to draw a line -
+ * a single sample is a dot's worth of information and reads as a glitch.
+ */
+export declare function seriesPath(data: readonly number[], extent: Extent, box: ChartBox): string;
+/**
+ * `d` for the closed band between two traces: the headroom between the
+ * bandwidth a connection is delivering and the bitrate it's asking for. Drawn
+ * filled so a closing gap (an impending stall) reads at a glance.
+ */
+export declare function bandPath(upper: readonly number[], lower: readonly number[], extent: Extent, box: ChartBox): string;
+/** Where the newest sample landed, for the "now" end dot. Null when there is
+ * nothing drawn to anchor it to. */
+export declare function endPoint(data: readonly number[], extent: Extent, box: ChartBox): {
+    x: number;
+    y: number;
+} | null;

package/types/ui/src/components/organisms/player/lib/fmt.d.ts

@@ -0,0 +1,19 @@
+/** Player-chrome formatting helpers shared by web + TV. */
+import { clamp01 } from '#ui/components/atoms/progress';
+/**
+ * Wall-clock time the current playback will finish, given the remaining
+ * milliseconds (§1, "fin à 22h38"). Localized: 24h `22h38` for fr, `10:38 PM`
+ * for en. Empty string when the runtime is unknown.
+ */
+export declare function endsAtClock(remainingMs: number | null | undefined, locale?: string): string;
+/** The kit's one clamp (the progress atom's), re-exported for the chrome. */
+export { clamp01 };
+/** Percentage (0–100) of `value` within `total`, clamped and safe when total=0. */
+export declare function pct(value: number, total: number): number;
+export declare const VOLUME_GAMMA = 3;
+/** The loudest a track can play: audio volume is a [0,1] amplitude. */
+export declare const VOLUME_MAX = 1;
+/** Slider position [0,1] → audio volume [0,1] (perceptual). */
+export declare function sliderToVolume(position: number): number;
+/** Audio volume [0,1] → slider position [0,1] (inverse of {@link sliderToVolume}). */
+export declare function volumeToSlider(volume: number): number;

package/types/ui/src/components/organisms/player/lib/lean-stats.d.ts

@@ -0,0 +1,34 @@
+import type { AudioTrack, MediaItem } from '@kroma/client/media';
+import type { Translate } from '@kroma/core';
+import type { PlayerStats } from '#ui/components/organisms/player/types';
+/** Typed structurally so React Native surfaces can satisfy it with no DOM lib. */
+export interface LeanStatsVideoHandle {
+    videoWidth: number;
+    videoHeight: number;
+    getVideoPlaybackQuality?: () => {
+        droppedVideoFrames: number;
+        totalVideoFrames: number;
+    };
+}
+export interface LeanStatsInput {
+    item: MediaItem;
+    cur: number;
+    dur: number;
+    bufEnd: number | null;
+    audioTracks: AudioTrack[];
+    audioIndex: number;
+    /** Null for native planes (AVPlay / mpv / exo / AVPlayer). */
+    video: LeanStatsVideoHandle | null;
+    /** The forward buffer a healthy stream keeps on THIS player, which is what
+     *  the meter is read against. Defaults to ten seconds; a player whose cache
+     *  window is a second and a half by design reads permanently critical against
+     *  a single constant. */
+    bufferTarget?: number;
+    mode: string;
+    t: Translate;
+    extra?: NonNullable<PlayerStats['extra']>;
+    meters?: NonNullable<PlayerStats['meters']>;
+}
+/** Dropped frames appear only when an in-page <video> is present; the buffer is
+ * a live meter rather than a row, because its history is the diagnostic. */
+export declare function buildLeanStats(s: LeanStatsInput): PlayerStats;

package/types/ui/src/components/organisms/player/lib/metrics.d.ts

@@ -0,0 +1,40 @@
+import type { ControlId } from './nav';
+export declare const CONTROL_SIZE: Record<ControlId, number>;
+export declare const VOLUME_RAIL = 96;
+export declare const TRANSPORT_GAP = 20;
+export declare const CLUSTER_GAP = 14;
+export declare const GUTTER = 34;
+export declare const TRANSPORT_HEIGHT = 164;
+export declare const ROW_GAP = 24;
+export declare const isTransport: (id: ControlId) => boolean;
+export declare const MIN_SCALE = 0.78;
+export interface ChromeMetrics {
+    scale: number;
+    controls: ControlId[];
+    rail: boolean;
+    overflow: ControlId[];
+    clusterWidth: number;
+}
+/**
+ * How the control row fits `stageWidth`: draw it as large as the stage allows,
+ * and where that would take a circle below the touch-target floor, shed a
+ * control and ask again. The row never wraps onto a second line. The returned
+ * `controls` is both what is drawn and what the nav machine steps through, so
+ * nothing focusable is ever off screen.
+ */
+export declare function chromeMetrics(row: readonly ControlId[], stageWidth: number): ChromeMetrics;
+export declare function px(scale: number, size: number): number;
+export type Px = (size: number) => number;
+export declare const scaler: (scale: number) => Px;
+export declare const PANEL_FRACTION = 0.44;
+export declare const PANEL_MAX = 720;
+export declare const PANEL_MIN = 420;
+export declare const CARD_MARGIN = 64;
+export declare const MIN_CARD_SCALE = 0.2;
+export interface PanelGeometry {
+    width: number;
+    covers: boolean;
+}
+/** Where the settings panel sits on this stage, and whether the video still has
+ * somewhere to shrink to beside it. */
+export declare function panelGeometry(stageWidth: number): PanelGeometry;

package/types/ui/src/components/organisms/player/lib/nav-keys.d.ts

@@ -0,0 +1,19 @@
+import type { RemoteKey } from '@kroma/core';
+import type { Dispatch, SetStateAction } from 'react';
+import type { PlayerNavActions } from '#ui/components/organisms/player/hooks/use-player-nav';
+import type { ControlId, Overlay, Zone } from './nav';
+interface DpadContext {
+    a: PlayerNavActions;
+    zone: Zone;
+    focused: ControlId | undefined;
+    controlsLen: number;
+    setZone: Dispatch<SetStateAction<Zone>>;
+    setControlIndex: Dispatch<SetStateAction<number>>;
+    setRevealed: Dispatch<SetStateAction<boolean>>;
+    clearHide: () => void;
+    openOverlay: (o: Exclude<Overlay, null>) => void;
+    activate: (id: ControlId) => void;
+}
+declare function handleMediaKey(key: RemoteKey, a: PlayerNavActions): boolean;
+declare function handleDpadKey(key: RemoteKey, ctx: DpadContext): void;
+export { handleDpadKey, handleMediaKey };

package/types/ui/src/components/organisms/player/lib/nav.d.ts

@@ -0,0 +1,38 @@
+import type { RemoteKey } from '@kroma/core';
+import type { PlayerFlags } from '#ui/components/organisms/player/types';
+/**
+ * The unified input model. ONE navigation contract drives both the D-pad (TV
+ * remote) and the mouse (hover = focus, click = OK), so every control responds
+ * to both without per-platform branches (§15). Logical keys come from
+ * `@kroma/core` `resolveRemoteKey`, shared with the rest of the TV shell.
+ */
+export type { RemoteKey } from '@kroma/core';
+/** The vertical zones the player is split into (§3), top to bottom. The bottom
+ * "À suivre" zone is the {@link Overlay} `sheet`, opened by ▼ from the controls
+ * (never on hover).
+ *
+ * `back` is the top chrome's round Back button. It is a ZONE rather than a
+ * control because this player drives its own D-pad chain instead of the
+ * spatial navigator: anything not named here cannot be reached at all, which
+ * is exactly how the Back button spent its life unreachable by ▲. */
+export type Zone = 'back' | 'progress' | 'controls';
+/** An open panel that captures navigation until dismissed. */
+export type Overlay = 'settings' | 'audio' | 'subtitles' | 'sheet' | null;
+/**
+ * Every focusable control in the middle row, in visual order. The cluster stops
+ * (`volume`, `pip`, `fullscreen`) are gated by feature flags a disabled flag
+ * removes the control AND its focus stop (§4c), computed by {@link controlOrder}.
+ */
+export type ControlId = 'rewind' | 'play' | 'forward' | 'next' | 'volume' | 'subtitles' | 'audio' | 'settings' | 'cast' | 'pip' | 'fullscreen';
+/** Build the present control row from the flags + whether there's a next episode.
+ * Absent controls leave no gap and no trapped D-pad stop. */
+export declare function controlOrder(flags: PlayerFlags, hasNext: boolean): ControlId[];
+/**
+ * Imperative handle an open panel exposes so the player shell can route D-pad
+ * keys into it (useImperativeHandle). `onKey` returns true when the panel
+ * consumed the key (so the shell stops), false to let the shell handle it (e.g.
+ * an unhandled Back bubbles up to close the panel).
+ */
+export interface PanelHandle {
+    onKey(key: RemoteKey): boolean;
+}

package/types/ui/src/components/organisms/player/lib/panel-header.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+export interface PanelHeader {
+    /** OK on the header: what the Back button does. */
+    activate: () => void;
+    /** Whether the header currently holds the focus. */
+    report: (focused: boolean) => void;
+}
+export declare function usePanelHeader(): PanelHeader | null;
+export declare function PanelHeaderProvider({ value, children, }: Readonly<{
+    value: PanelHeader;
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/src/components/organisms/player/lib/panel-slide.d.ts

@@ -0,0 +1,16 @@
+/** How long the picture takes to reach the settings card, and the panel to
+ *  reach its edge. One number for both, so the two read as one movement. */
+export declare const CARD_MS = 340;
+export interface PanelSlide {
+    mounted: boolean;
+    shown: boolean;
+    /** Bumped on every open. Keyed on, it starts the panel's own state fresh
+     *  while the wrapper stays mounted long enough for the exit to play. */
+    run: number;
+}
+/**
+ * Keeps the settings panel in the tree while it leaves, so the picture expands
+ * from under a panel that is still sliding out rather than one that vanished a
+ * frame earlier.
+ */
+export declare function usePanelSlide(open: boolean): PanelSlide;

package/types/ui/src/components/organisms/player/lib/player-keys.d.ts

@@ -0,0 +1,44 @@
+import type { RemoteKey } from '@kroma/core';
+import type { RefObject } from 'react';
+import type { PlayerNav } from '#ui/components/organisms/player/hooks/use-player-nav';
+import type { PlayerController, PlayerFlags } from '#ui/components/organisms/player/types';
+import type { PanelHandle } from './nav';
+export interface PlayerKeysParams {
+    nav: PlayerNav;
+    controller: PlayerController;
+    flags: PlayerFlags;
+    panelRef: RefObject<PanelHandle | null>;
+    locked: boolean;
+    intro?: {
+        active: boolean;
+        onSkip: () => void;
+    };
+    credits?: {
+        active: boolean;
+        onKey: (key: RemoteKey) => boolean;
+    };
+    /** The end-of-film screen. While it is up there is no film left to drive, so
+     *  it takes every key rather than getting first refusal on some. */
+    postPlay?: {
+        active: boolean;
+        onKey: (key: RemoteKey) => void;
+    };
+}
+/**
+ * Which way Tab walks from where the player currently is.
+ *
+ * The chrome is NOT on the spatial navigator - it cannot be, since tvOS's own
+ * focus engine would adopt it in parallel with this machine (see
+ * lib/virtual-focus) - so a keyboard's Tab reaches it the same way a remote
+ * does: as a direction. Along the thing being walked, which is a row for the
+ * transport controls and the up-next grid, and a column for everything else.
+ */
+export declare function tabDirection(nav: PlayerNav, backwards: boolean): RemoteKey;
+/**
+ * Route one logical remote key (§3, §15). While locked only Back / OK get
+ * through, and both mean "dismiss". The end-of-film screen takes everything.
+ * Otherwise the chrome reveals first and swallows the key (§16), then the
+ * panel, skip-intro and credits card each get first refusal before the nav
+ * machine sees it.
+ */
+export declare function routeRemoteKey(p: Readonly<PlayerKeysParams>, key: RemoteKey): void;

package/types/ui/src/components/organisms/player/lib/seek-track.d.ts

@@ -0,0 +1,19 @@
+/** Just enough of a chapter to lay one out. */
+interface TrackSegment {
+    startMs: number;
+    endMs: number;
+}
+declare const SEGMENT_GAP = 4;
+/** Each segment's width in px: the track's width, less the gaps, shared out in
+ * proportion to how long each chapter runs. This is what the layout produces
+ * from `flex={span}`, computed here so the maths can be checked without one. */
+declare function segmentWidths(segs: readonly TrackSegment[], trackWidth: number): number[];
+/** Where a moment in the film sits on the track, in px from its left edge.
+ * A time inside a gap (there are none - gaps sit exactly on chapter boundaries)
+ * resolves to the boundary itself. */
+declare function offsetAt(ms: number, segs: readonly TrackSegment[], trackWidth: number): number;
+/** The inverse: the moment under a pixel. A press in a gap lands on the start of
+ * the segment after it, which is the chapter boundary the user aimed at. */
+declare function msAtOffset(x: number, segs: readonly TrackSegment[], trackWidth: number): number;
+export type { TrackSegment };
+export { msAtOffset, offsetAt, SEGMENT_GAP, segmentWidths };

package/types/ui/src/components/organisms/player/lib/stage-card.d.ts

@@ -0,0 +1,31 @@
+import type { PlaneRect } from '../types';
+/** A rectangle on the stage, as fractions of the stage's own width and height. */
+export interface StageRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface StageCard {
+    /** The picture's box on the un-shrunken stage, or null while the stage is
+     *  unmeasured or the media has not declared its shape - the surface fills the
+     *  stage then, which is what the shrink assumed before aspects were known. */
+    picture: StageRect | null;
+    scale: number;
+    /** The horizontal transform origin, as a fraction of the stage width, that
+     *  makes `scale` land the picture on the card. The vertical origin is always
+     *  the middle: the picture is centred there, and the card is too. */
+    origin: number;
+    /** The same landing expressed for a scale about the DEFAULT origin: how far
+     *  to move the stage sideways afterwards, as a fraction of its width. What
+     *  Android uses, because a `transformOrigin` blanks a transformed view there. */
+    shift: number;
+    /** The same card as viewport fractions, for a native plane that cannot be
+     *  transformed and is moved with `setPlaneRect` instead. */
+    rect: PlaneRect;
+}
+/** The picture on a `width` x `height` stage, and the card it shrinks into
+ * beside the settings panel. `aspect` is the picture's display ratio (w/h); with
+ * none the picture is the whole stage, which is what the shrink used to assume.
+ * The two sizes are only ever read as a ratio, so their unit does not matter. */
+export declare function stageCard(width: number, height: number, aspect?: number): StageCard;