@kromatv/sdk 0.1.40-canary.0

package/types/ui/src/services/cast-position.d.ts

@@ -0,0 +1,14 @@
+import type { CastReceiver } from '@kroma/client/cast';
+/** What a receiver last reported, and when this sender heard it. */
+interface PositionBase {
+    id: string;
+    positionMs: number;
+    playing: boolean;
+    at: number;
+}
+/** Where the TV is *now*: what it last told us, plus the wall time since. The
+ * roster snapshot and the position event race, so the fresher of the two wins,
+ * and the result never runs past the title's own duration. */
+declare function livePosition(active: CastReceiver | null, base: PositionBase | null, playing: boolean): number;
+export type { PositionBase };
+export { livePosition };

package/types/ui/src/services/cast.d.ts

@@ -0,0 +1,20 @@
+import { type KromaClient } from '@kroma/client';
+import type { LanDiscoveryBridge } from '@kroma/core';
+import { type ReactNode } from 'react';
+export interface CastProviderProps {
+    /** Null while a shell is still resolving its session; treated as "not yet". */
+    client: KromaClient | null;
+    /** Gates everything on being signed in - the roster needs a session. */
+    enabled: boolean;
+    /** What this device calls itself on the TV's list of remotes ("iPhone",
+     * "Chrome"). Shown across the room, so it should be a thing, not a session id. */
+    deviceName: string;
+    /** This device's DNS-SD stack, when the shell has one. It makes a television
+     * appear the moment it is heard rather than on the next beat, and surfaces
+     * the ones with no account at all. */
+    lan?: LanDiscoveryBridge;
+    children: ReactNode;
+}
+export declare function CastProvider({ client, enabled, deviceName, lan, children, }: Readonly<CastProviderProps>): import("react").JSX.Element;
+export type { Cast } from './cast-context';
+export { useCast } from './cast-context';

package/types/ui/src/services/format.d.ts

@@ -0,0 +1,25 @@
+export interface Format {
+    /** A byte size in the locale's units: `1,5 Go` / `1.5 GB`. */
+    bytes: (bytes: number) => string;
+    /** A fixed-point number with the locale's separator. One decimal by default. */
+    decimal: (n: number, digits?: number) => string;
+    /** How long ago a timestamp was, in words, from an ISO string or epoch
+     *  milliseconds. Null reads as "never". */
+    elapsed: (at: string | number | null | undefined) => string;
+    /** A timestamp in full, date and time of day, for a log where "2 days ago"
+     *  would collapse rows a reader needs to tell apart. Null where there is no
+     *  readable timestamp, so a caller picks its own dash. */
+    stamp: (at: string | number | null | undefined) => string | null;
+    /** Uptime at the coarsest useful scale, from seconds. */
+    uptime: (seconds: number) => string;
+    /** Watch time to the minute, from milliseconds. */
+    duration: (ms: number) => string;
+    /** Hours with one decimal for a chart axis, from milliseconds. */
+    hours: (ms: number) => string;
+    /** A throughput figure, one decimal, no unit. */
+    mbps: (n: number) => string;
+    /** A scrub-bar timecode, from milliseconds. */
+    timecode: (ms: number) => string;
+}
+/** Every value formatter, bound to the locale on screen. */
+export declare function useFormat(): Format;

package/types/ui/src/services/i18n.d.ts

@@ -0,0 +1,18 @@
+import { type Locale, type Translate } from '@kroma/core';
+import { type ReactNode } from 'react';
+export { useI18n, useLocale, useScopedT, useSetLocale, useT } from '@kroma/i18n/react';
+export interface I18nProviderProps {
+    locale: Locale;
+    onLocaleChange?: (locale: Locale) => void;
+    children: ReactNode;
+}
+export declare function I18nProvider({ locale, onLocaleChange, children }: Readonly<I18nProviderProps>): import("react").JSX.Element;
+/** Like `useLocale`, but standing alone: outside an <I18nProvider> it is the
+ * default locale rather than a throw. What a kit component formatting a number
+ * reaches for, and the reason knowing the locale must not drag the catalogs in. */
+export declare function useLocaleDefault(): Locale;
+/** Like `useT`, but standing alone: outside an <I18nProvider> it speaks the
+ * default locale instead of throwing. For the kit's own chrome (an overlay
+ * backdrop's accessible name), which must not make the provider a mount
+ * requirement for every consumer of a dialog. */
+export declare function useTDefault(): Translate;

package/types/ui/src/services/locale.d.ts

@@ -0,0 +1,18 @@
+import { type KromaClient } from '@kroma/client';
+import { type Locale } from '@kroma/core';
+import { type ReactNode } from 'react';
+export interface LocaleProviderProps {
+    /** API client whose Accept-Language is kept in sync. Null before a server is reached. */
+    client: KromaClient | null;
+    /** The signed-in account's language preference, or null/undefined when signed out. */
+    accountLanguage?: string | null;
+    /** Persist a manual change to the signed-in account. Omit when signed out. */
+    onAccountChange?: (locale: Locale) => void;
+    /** Mirror the locale onto `<html lang>`. Every DOM target wants this, the
+     * browser TVs included: `lang` is what a set's screen reader reads to decide
+     * how to PRONOUNCE the interface. No-ops where there is no document, so a
+     * native target may pass it harmlessly. */
+    syncHtmlLang?: boolean;
+    children: ReactNode;
+}
+export declare function LocaleProvider({ client, accountLanguage, onAccountChange, syncHtmlLang, children, }: Readonly<LocaleProviderProps>): import("react").JSX.Element;

package/types/ui/src/services/playback.d.ts

@@ -0,0 +1,49 @@
+import { type KromaClient } from '@kroma/client';
+import type { ItemId } from '@kroma/client/media';
+import { type RefObject } from 'react';
+export interface PlaybackHeartbeatParams {
+    client: KromaClient;
+    /** Gates pinging (web: signed-in; TV: `client.hasAuth`). */
+    enabled: boolean;
+    itemId: ItemId;
+    durationMs: number | null;
+    /** Absolute current position in seconds (offset-aware on the web seamless stream). */
+    getPosition: () => number;
+    /** Absolute position the surface has buffered up to, in seconds, where it can
+     * say. Omitted from the ping when absent or undefined. */
+    getBuffered?: () => number | undefined;
+    /** The current transport state (`buffering` = playing but stalled/rebuffering). */
+    getState: () => 'playing' | 'paused' | 'buffering';
+    /** Label of the audio track the viewer has selected (omit → keep server default). */
+    getAudio?: () => string | undefined;
+    /** Label of the selected subtitle track, or an "off" label (omit → unchanged). */
+    getSubtitle?: () => string | undefined;
+    mode: 'direct' | 'remux' | 'transcode';
+    player: string;
+    device: string;
+    /** Base URL for the live-events stream (web: apiBase(); TV: client.baseUrl). */
+    eventsBaseUrl: string;
+    /** Where the event socket reads its bearer, when the shared in-memory session
+     * is not the right source. The TV keeps its bearer on its client (it is
+     * multi-server), so it passes that; web and phone leave this unset. Without it
+     * the TV's socket handshake carries no credential and is refused - which left
+     * the admin-stop event relying entirely on its 410-on-ping fallback. */
+    eventsToken?: () => string | undefined;
+    /** Session-id platform prefix, e.g. `'web'` | `'tv'`. */
+    idPrefix: string;
+    /** Fired the first time the session is terminated (admin stop, or a 410). */
+    onTerminated: (message: string) => void;
+    /** Element whose play/pause events trigger a prompt heartbeat (TV). */
+    videoRef?: RefObject<HTMLVideoElement | null>;
+    /** A value that, when it changes, triggers a prompt heartbeat (web passes its
+     * React `playing` state). Omit to rely solely on `videoRef`. */
+    pingSignal?: unknown;
+}
+/**
+ * A session id keys ONE row in the server's live "now playing" registry. It is
+ * never an auth token: `/playback/stop` only ends a session the requesting
+ * account owns, so the id needs uniqueness, not unpredictability. Clock plus a
+ * per-process counter gives that on every target, the same shape as the phone
+ * client's `newSessionId`.
+ */
+export declare function usePlaybackHeartbeat(params: PlaybackHeartbeatParams): void;

package/types/ui/src/services/storyboard.d.ts

@@ -0,0 +1,33 @@
+import type { KromaClient } from '@kroma/client';
+import type { ItemId } from '@kroma/client/media';
+/**
+ * One preview tile, scaled to a requested display width, expressed as geometry
+ * rather than CSS `background-position`: React Native's `experimental_backgroundImage`
+ * takes gradients, not `url()`, so that spelling renders nothing on Apple TV.
+ */
+export interface StoryboardTile {
+    width: number;
+    height: number;
+    sheet: string;
+    /** The sheet's own pixel size - draw at this size and scale by `scale`; asking
+     *  the decoder for `sheetWidth * scale` pixels can exceed the GPU's texture
+     *  limit and the thumbnail comes out empty. */
+    sheetWidth: number;
+    sheetHeight: number;
+    /** Offset to bring this tile into the window (<= 0). */
+    offsetX: number;
+    offsetY: number;
+    /** Display size over source size: `width / tileW`. */
+    scale: number;
+}
+export interface Storyboard {
+    ready: boolean;
+    tile: (sec: number, displayW: number) => StoryboardTile | null;
+}
+/**
+ * Loads an item's scrub-bar storyboard for the seek preview. `generate: false`
+ * (dashboard thumbnails) does a single fetch and never awaits lazy generation.
+ */
+export declare function useStoryboard(client: KromaClient, itemId: ItemId, { generate }?: {
+    generate?: boolean;
+}): Storyboard;

package/types/ui/src/services/subtitleGenerations.d.ts

@@ -0,0 +1,13 @@
+import type { KromaClient } from '@kroma/client';
+import type { ItemId } from '@kroma/client/media';
+import type { GenerationId, SubtitleGeneration, SubtitleId } from '@kroma/client/subtitles';
+export interface SubtitleGenerationsOptions {
+    active?: boolean;
+    onComplete: (subId: SubtitleId) => void;
+}
+export interface SubtitleGenerationsResult {
+    generations: SubtitleGeneration[];
+    cancel: (genId: GenerationId) => void;
+    refresh: () => void;
+}
+export declare function useSubtitleGenerations(client: KromaClient, itemId: ItemId, { active, onComplete }: SubtitleGenerationsOptions): SubtitleGenerationsResult;

package/types/ui/src/services/themeAudio.d.ts

@@ -0,0 +1,19 @@
+/** Same shape as the native half, so callers need no platform branch. */
+export interface ThemeAudio {
+    /** Whether a theme is available gates whether the mute toggle renders. */
+    active: boolean;
+    muted: boolean;
+    toggle: () => void;
+}
+/**
+ * Plex-style theme playback for a detail page: loops `themeUrl` at a low volume,
+ * fading in once it can play and fading out + stopping on unmount (i.e. when the
+ * user hits Play or navigates away).
+ *
+ * Browsers gate autoplay-with-sound behind a user gesture arriving on this page
+ * via a click usually satisfies that, and a one-shot pointer/key fallback covers
+ * the rest. The mute preference is persisted per device so it survives the trip
+ * between pages; React state mirrors it only for the toggle icon (kept SSR-safe
+ * by starting unmuted and syncing on mount).
+ */
+export declare function useThemeAudio(themeUrl: string | null | undefined): ThemeAudio;

package/types/ui/src/services/themeAudio.native.d.ts

@@ -0,0 +1,8 @@
+/** Same shape as the web half, so callers need no platform branch. */
+export interface ThemeAudio {
+    active: boolean;
+    muted: boolean;
+    toggle: () => void;
+}
+/** Loops `themeUrl` quietly, fading in once it can play and out on the way out. */
+export declare function useThemeAudio(themeUrl: string | null | undefined): ThemeAudio;

package/types/ui/src/ssr.d.ts

@@ -0,0 +1,20 @@
+type Fetch = (request: Request) => Response | Promise<Response>;
+/**
+ * Stamps the visitor's stored ground on `<html>` before the document leaves the
+ * server, so a page that will be light never paints dark first.
+ *
+ * `system` is left unstamped on purpose: the token sheet resolves it through
+ * `prefers-color-scheme`, live and without a line of script.
+ */
+export declare function withTheme(handler: Fetch): Fetch;
+/**
+ * Puts the kit's compiled stylesheet in the document the server sends, since
+ * react-native-web otherwise only injects its atomic CSS on hydration.
+ *
+ * The response is buffered rather than streamed: a recipe compiles on its first
+ * render, so the rules a page needs exist only after `</head>` would have been
+ * flushed. The element carries the WHOLE sheet under the id react-native-web
+ * looks for, or the client adopts an empty one and mints every rule again.
+ */
+export declare function withKitStyles(handler: Fetch): Fetch;
+export {};

package/types/ui/src/styles/motion.d.ts

@@ -0,0 +1,2 @@
+import { type SheetEntry } from './sheet.ts';
+export declare const MOTION: readonly SheetEntry[];

package/types/ui/src/styles/page.d.ts

@@ -0,0 +1,2 @@
+import { type SheetEntry } from './sheet.ts';
+export declare const PAGE: readonly SheetEntry[];

package/types/ui/src/styles/reset.d.ts

@@ -0,0 +1,2 @@
+import { type SheetEntry } from './sheet.ts';
+export declare const RESET: readonly SheetEntry[];

package/types/ui/src/styles/sheet.d.ts

@@ -0,0 +1,18 @@
+/** A declaration's value. A number is written verbatim, so a unit is a string. */
+type StyleValue = string | number;
+type Declarations = Readonly<Record<string, StyleValue>>;
+export interface StyleRule {
+    readonly select: readonly string[];
+    readonly declare: Declarations;
+}
+export interface GroupRule {
+    readonly at: string;
+    readonly rules: readonly StyleRule[];
+}
+export type SheetEntry = StyleRule | GroupRule;
+export declare const rule: (select: string | readonly string[], declare: Declarations) => StyleRule;
+export declare const atMedia: (query: string, rules: readonly StyleRule[]) => GroupRule;
+/** An animation, its steps written as rules whose selector is the offset. */
+export declare const keyframes: (name: string, steps: readonly StyleRule[]) => GroupRule;
+export declare const sheetCss: (entries: readonly SheetEntry[]) => string;
+export {};

package/types/ui/src/testing.d.ts

@@ -0,0 +1,27 @@
+import { type ReactElement } from 'react';
+import type { LayoutRectangle } from 'react-native';
+/** Whether this screen already has a focus owner, and how a test says one has
+ * arrived. An app can only assert "the new screen gets to choose again" through
+ * these: `autoFocus` is honoured or ignored on the strength of that one flag
+ * (see lib/focus-entry), and no rendered output shows it. */
+export { focusSettled, markFocusSettled } from './lib/focus-entry';
+/** What an element declares for `property`, inline or through the classes its
+ * styles compiled to, as written: a control paints with classes, so `el.style`
+ * reads nothing of it, and jsdom's computed style drops `z-index` and every
+ * `var()`. Null when nothing declares it. */
+export declare function declared(el: Element, property: string): string | null;
+/** Whether an element wears the focus ring: the outline the kit draws around
+ * the control that has the focus (see tokens/effects). */
+export declare function wearsRing(el: Element | null | undefined): boolean;
+/** Wrap a tree in the same navigator and locale a real screen runs inside.
+ * English, because an assertion reads better against the words in the test. */
+export declare function onScreen(ui: ReactElement): ReactElement;
+/** The node under `root` that measures itself, i.e. the one react-native-web
+ * gave an `onLayout`. Throws unless there is exactly one, so a caller measuring
+ * "the" box cannot silently start measuring a different one. */
+export declare function measuring(root: Element): Element;
+/** Hand a rendered node the box a browser would have measured, firing the
+ * `onLayout` it was given. react-native-web reports layout through a
+ * ResizeObserver, which jsdom does not implement, so nothing a component
+ * computes from its own size happens in a test until this says it did. */
+export declare function layout(node: Element, box: Partial<LayoutRectangle>): void;

package/types/ui/src/workbench-config.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderSpec } from '@kroma/workbench';
+import type { ReactNode } from 'react';
+type Locale = 'en' | 'fr';
+export declare const KROMA_WORKBENCH: {
+    title: string;
+    brand: ReactNode;
+    provider: ProviderSpec<Locale>;
+};
+export {};