@kromatv/sdk 0.1.40-canary.0

package/types/core/src/index.d.ts

@@ -0,0 +1,25 @@
+export * from './airdate';
+export * from './browse';
+export * from './compat';
+export * from './discover';
+export * from './format';
+export * from './genre';
+export * from './genre-art';
+export * from './handoff';
+export * from './hevc';
+export * from './i18n';
+export * from './intl';
+export * from './lang';
+export * from './match';
+export * from './notification-labels';
+export * from './people';
+export * from './permissions';
+export * from './person-facts';
+export * from './platform';
+export * from './playback-buffer';
+export * from './playback-stall';
+export * from './player';
+export * from './push-labels';
+export * from './remote';
+export * from './slug';
+export * from './subtitles';

package/types/core/src/intl.d.ts

@@ -0,0 +1,28 @@
+import type { Locale, Translate } from '@kroma/i18n';
+/** A fixed-point number with the locale's decimal separator: `1,5` in French,
+ *  `1.5` in English. Grouping is off: these sit in tabular columns beside a
+ *  unit, where a thousands separator reads as a second number. */
+export declare function decimal(n: number, locale: Locale, digits?: number): string;
+/** A byte size in the locale's units: `1,5 Go` in French, `1.5 GB` in English.
+ *  Zero and negatives render as the smallest unit rather than empty. */
+export declare function formatBytes(bytes: number, locale: Locale): string;
+/** A throughput figure, one decimal, no unit: the caller supplies `Mb/s`. */
+export declare function formatMbps(n: number, locale: Locale): string;
+/** A scrub-bar timecode, `1:04:07` or `4:07`, with no leading hours under one
+ *  hour. Digits only, so no locale. */
+export declare function formatTimecode(seconds: number): string;
+/** {@link formatTimecode} fed milliseconds, which is what the APIs return. */
+export declare function formatTimecodeMs(ms: number): string;
+/** Hours with one decimal for a chart axis: `14,3 h`. */
+export declare function formatHours(ms: number, locale: Locale): string;
+/** Watch time from milliseconds, to the minute: `4 h 29 min` / `65 min`. */
+export declare function formatDuration(t: Translate, ms: number): string;
+/** How long the server has been up, at the coarsest useful scale:
+ *  `18 j 04 h` / `4 h 12 min` / `8 min`. */
+export declare function formatUptime(t: Translate, seconds: number): string;
+/** A timestamp written out in full: the date and the time of day, in the
+ *  locale's own order. Where [`formatElapsed`] answers "how long ago", this
+ *  answers "when", which is what a log wants: two rows a minute apart both read
+ *  "2 days ago", and a reader auditing a history needs to tell them apart. */
+export declare function formatStamp(locale: Locale, at: string | number | null | undefined): string | null;
+export declare function formatElapsed(t: Translate, locale: Locale, at: string | number | null | undefined, now?: number): string;

package/types/core/src/lang-table.d.ts

@@ -0,0 +1,11 @@
+import type { MessageKey } from './i18n';
+export declare const LANG_ALIAS: Record<string, string>;
+/** A language the catalog has a name for, derived from the `lang.*` message
+ * keys so the list and the catalog cannot drift. */
+export type LangCode = LangSuffix<MessageKey>;
+type LangSuffix<K> = K extends `lang.${infer C}` ? C : never;
+/** Every language a client offers as an audio or subtitle preference. The six
+ * region-tagged entries are the dub variants {@link titleLangVariant} reads out
+ * of a track title. */
+export declare const PREF_LANGS: readonly ["aa", "ab", "ae", "af", "ak", "am", "an", "ar", "as", "av", "ay", "az", "ba", "be", "bg", "bi", "bm", "bn", "bo", "br", "bs", "ca", "ce", "ch", "co", "cr", "cs", "cu", "cv", "cy", "da", "de", "dv", "dz", "ee", "el", "en", "eo", "es", "es-419", "es-ES", "et", "eu", "fa", "ff", "fi", "fj", "fo", "fr", "fr-CA", "fr-FR", "fy", "ga", "gd", "gl", "gn", "gu", "gv", "ha", "he", "hi", "ho", "hr", "ht", "hu", "hy", "hz", "ia", "id", "ie", "ig", "ii", "ik", "io", "is", "it", "iu", "ja", "jv", "ka", "kg", "ki", "kj", "kk", "kl", "km", "kn", "ko", "kr", "ks", "ku", "kv", "kw", "ky", "la", "lb", "lg", "li", "ln", "lo", "lt", "lu", "lv", "mg", "mh", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "na", "nb", "nd", "ne", "ng", "nl", "nn", "no", "nr", "nv", "ny", "oc", "oj", "om", "or", "os", "pa", "pi", "pl", "ps", "pt", "pt-BR", "pt-PT", "qu", "rm", "rn", "ro", "ru", "rw", "sa", "sc", "sd", "se", "sg", "si", "sk", "sl", "sm", "sn", "so", "sq", "sr", "ss", "st", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "tn", "to", "tr", "ts", "tt", "ty", "ug", "uk", "ur", "uz", "ve", "vi", "vo", "wa", "wo", "xh", "yi", "yo", "za", "zh", "zu", "fil", "yue", "ceb", "haw", "hmn"];
+export {};

package/types/core/src/lang.d.ts

@@ -0,0 +1,59 @@
+import type { MessageKey, Translate } from './i18n';
+import { type LangCode } from './lang-table';
+export { type LangCode, PREF_LANGS } from './lang-table';
+/**
+ * Canonical base for a language code: `"eng"` → `"en"`, `"pt-BR"` → `"pt"`.
+ * An unknown three-letter code is returned unchanged rather than truncated -
+ * chopping `"swe"` to `"sw"` would claim Swedish is Swahili.
+ */
+export declare function langBase(code?: string | null): string | null;
+export declare function matchesLang(pref: string | null | undefined, code?: string | null): boolean;
+/** "No preference": stored as `null` on the account, but a select needs a
+ * value, so the pickers use this sentinel. */
+export declare const LANG_NO_PREF = "none";
+export declare const LANG_OFF = "off";
+/**
+ * The most specific code in {@link PREF_LANGS} a language tag maps onto, or
+ * null. Specific first: `fr-CA` is offered so a Quebec preference stays Quebec,
+ * `pt-AO` is not so an Angolan track resolves to plain Portuguese.
+ */
+export declare function offeredLang(code?: string | null): LangCode | null;
+export declare function langKey(code?: string | null): MessageKey | null;
+export interface LangOption {
+    code: LangCode;
+    label: string;
+}
+/** {@link PREF_LANGS} as picker rows, labelled for `locale` and sorted by label
+ * with that locale's collator. Built fresh per call. */
+export declare function langOptions(t: Translate, locale?: string): LangOption[];
+export interface AudioCandidate {
+    index: number;
+    language?: string | null;
+    title?: string | null;
+}
+/**
+ * The dub variant a track's title betrays, as a full language tag, or null.
+ * Containers cannot say it any other way - VFF and VFQ both declare
+ * `language: fre`. Bare "VF" names no side and stays null.
+ */
+export declare function titleLangVariant(title?: string | null): string | null;
+export declare function langRegion(code?: string | null): string | null;
+/**
+ * A track's declared language refined by the variant its title betrays
+ * (`('fre', 'VFF AC3 5.1')` → `'fr-FR'`). The variant only refines a matching
+ * base: an English track titled "VFF" is a mislabel, not a French track.
+ */
+export declare function refineTrackLang(language?: string | null, title?: string | null): string | null;
+export interface SubtitleCandidate {
+    index: number;
+    language?: string | null;
+    url?: string | null;
+    generated?: boolean;
+}
+/** Index of the audio track matching `pref`, or null (the caller then keeps the
+ * file's default). A pref carrying a region ranks the language's tracks: exact
+ * variant, then a track naming no variant, then the opposite one. */
+export declare function preferredAudioIndex(tracks: readonly AudioCandidate[], pref?: string | null): number | null;
+/** Index of the subtitle track to auto-enable for `pref`, or null. Only
+ * renderable, non-generated tracks are ever auto-enabled. */
+export declare function preferredSubIndex(subs: readonly SubtitleCandidate[], pref?: string | null): number | null;

package/types/core/src/local-ip.d.ts

@@ -0,0 +1,2 @@
+/** Best-effort local IPv4: Tizen/webOS network APIs, then a WebRTC fallback. */
+export declare function getLocalIPv4(): Promise<string | null>;

package/types/core/src/locales/catalogs.d.ts

@@ -0,0 +1,2 @@
+export declare const catalogs: Record<string, Readonly<Record<string, string>>>;
+export declare const lazy: {};

package/types/core/src/locales/catalogs.web.d.ts

@@ -0,0 +1,3 @@
+import { type Catalog } from '@kroma/i18n';
+export declare const catalogs: Record<string, Readonly<Record<string, string>>>;
+export declare const lazy: Record<string, Record<string, () => Promise<Catalog>>>;

package/types/core/src/locales/default-locale.d.ts

@@ -0,0 +1,3 @@
+/** The locale whose catalogs are complete: every other one falls back to it,
+ *  and its files type the keys. Read by the engine and by the Vite plugin. */
+export declare const DEFAULT_LOCALE_CODE = "fr";

package/types/core/src/match.d.ts

@@ -0,0 +1,14 @@
+type Predicate<T> = (value: T) => boolean;
+type Produce<T, R> = R | ((value: T) => R);
+declare class Matcher<T, R = never> {
+    private readonly value;
+    private done;
+    private result;
+    constructor(value: T);
+    /** `cond` is a predicate, or a value compared with `===`. */
+    when<U>(cond: Predicate<T> | T, produce: Produce<T, U>): Matcher<T, R | U>;
+    otherwise<U>(fallback: Produce<T, U>): R | U;
+}
+/** First match wins, and only the winning branch's producer is evaluated. */
+export declare function match<T>(value: T): Matcher<T>;
+export {};

package/types/core/src/notification-labels.d.ts

@@ -0,0 +1,47 @@
+import type { Notification, NotificationCategory } from '@kroma/client/notifications';
+import type { MessageKey } from './i18n';
+/** The five preference buckets, named as a reader sees them in their settings. */
+export declare const NOTIFICATION_CATEGORY_LABEL: Record<NotificationCategory, MessageKey>;
+/** Which heading a row sits under. */
+export type NotificationDay = 'today' | 'yesterday' | 'earlier';
+export declare const NOTIFICATION_DAY_LABEL: Record<NotificationDay, MessageKey>;
+/** Calendar days, not elapsed hours: "yesterday" has to mean yesterday at
+ * 23:50 too. Stepping back a day through `startOfDay` keeps it right across a
+ * DST boundary, where "now minus 24h" is off by an hour. */
+export declare function notificationDayOf(at: number, now: number): NotificationDay;
+/** Runs of consecutive same-day rows, in the order the server sent them: the
+ * list stays newest-first and is never re-sorted underneath the reader. */
+export declare function groupNotificationsByDay(items: Notification[]): {
+    day: NotificationDay;
+    items: Notification[];
+}[];
+/** One entry of the reader's list: a notification plus every repeat of it that
+ * was folded in. `items` is newest-first and always holds at least `head`, so a
+ * run of one is an ordinary row. */
+export interface NotificationRun {
+    key: string;
+    head: Notification;
+    items: Notification[];
+    /** How many of `items` are still unread; the run reads as unread above zero. */
+    unread: number;
+}
+/**
+ * What makes two rows "the same thing said again".
+ *
+ * The wire carries rendered sentences, not the params behind them, so the event
+ * plus the words it produced IS the identity available to a client: eleven
+ * failures of one job read identically, failures of two different jobs do not.
+ * Deriving it from the text rather than from an id also means a module's own
+ * event groups without the module having to opt in.
+ */
+export declare function notificationRepeatKey(item: Notification): string;
+/**
+ * Fold repeats of one event into a single entry, each anchored where its NEWEST
+ * member sat: an inbox holding eleven copies of one failed job reads as one row
+ * that happened eleven times, and the list stays newest-first.
+ *
+ * Repeats are collected across the whole input rather than only when adjacent,
+ * because a job that fails every five minutes is interleaved with whatever else
+ * arrived in between. Call it per day group, so a fold never crosses a heading.
+ */
+export declare function groupNotificationRepeats(items: Notification[]): NotificationRun[];

package/types/core/src/people.d.ts

@@ -0,0 +1,33 @@
+import type { CrewMember, Metadata } from '@kroma/client/media';
+import type { Translate } from './i18n';
+/** The crew credits that stand for a title's authorship: a film's directors, a
+ * show's creators, in the order the provider listed them. */
+export declare function directorsOf(crew: readonly CrewMember[] | null | undefined): CrewMember[];
+/** The URL segment one person is reached by: the provider's id when their
+ * credit kept one, the folded name when it did not. Every credit stored before
+ * the id was kept has none, which is why a person URL is not always a number. */
+export declare function personSegment(person: Readonly<{
+    name: string;
+    tmdbId?: number | null;
+}>): string;
+/** Does `meta` credit `name` in its cast OR key crew? `name` is a display name
+ * or a URL slug. */
+export declare function creditsPerson(meta: Metadata | null | undefined, name: string): boolean;
+/** One person's involvement aggregated across a set of titles' metadata: whether
+ * they appear in any cast, the distinct crew jobs they held (e.g. `Director`), and
+ * the best profile photo found among the matching credits. */
+export interface PersonInvolvement {
+    acted: boolean;
+    jobs: string[];
+    profileUrl: string | null;
+}
+/** Aggregate {@link PersonInvolvement} for `name` over many titles' metadata. */
+export declare function personInvolvement(metas: ReadonlyArray<Metadata | null | undefined>, name: string): PersonInvolvement;
+/** The spelling titles' metadata holds for a person, recovered from the slug or
+ * the differently-cased name a URL carried. Falls back to `name`. */
+export declare function personDisplayName(metas: ReadonlyArray<Metadata | null | undefined>, name: string): string;
+/** Localized role chips for a person: "Acteur" for any cast credit, then each
+ * distinct crew job (known jobs translated; anything else shown verbatim). */
+export declare function roleLabels(t: Translate, inv: PersonInvolvement): string[];
+/** The localized label for a single crew job (verbatim when unknown). */
+export declare function jobLabel(t: Translate, job: string): string;

package/types/core/src/permissions.d.ts

@@ -0,0 +1,10 @@
+import type { Permission } from '@kroma/client/accounts';
+import type { MessageKey } from './i18n';
+export interface PermissionMeta {
+    key: Permission;
+    labelKey: MessageKey;
+    hintKey: MessageKey;
+}
+/** All grantable permissions, in display order. Keep in sync with the Rust
+ * `Permission` enum (`server/src/domain/accounts.rs`). */
+export declare const PERMISSIONS: readonly PermissionMeta[];

package/types/core/src/person-facts.d.ts

@@ -0,0 +1,23 @@
+import type { Translate } from './i18n';
+/** Whole years between two `YYYY-MM-DD` dates, null when unparseable. */
+export declare function personAge(birthday: string | null | undefined, deathday?: string | null, today?: Date): number | null;
+/** Falls back to the raw string when the runtime has no Intl data. */
+export declare function formatDay(day: string | null | undefined, locale?: string): string | null;
+export interface PersonFact {
+    key: 'born' | 'died' | 'birthplace' | 'knownFor';
+    label: string;
+    value: string;
+}
+/** Only the facts the provider actually filled in, so a client renders the
+ * list as-is. */
+export declare function personFacts(t: Translate, detail: PersonDetailFacts | null | undefined, locale?: string): PersonFact[];
+export interface PersonDetailFacts {
+    biography?: string | null;
+    birthday?: string | null;
+    deathday?: string | null;
+    placeOfBirth?: string | null;
+    knownFor?: string | null;
+}
+/** Localizes TMDB's `known_for_department` vocabulary; an untranslated
+ * department passes through verbatim. */
+export declare function departmentLabel(t: Translate, department: string | null | undefined): string | null;

package/types/core/src/platform.d.ts

@@ -0,0 +1,7 @@
+/** Samsung Tizen: the UA carries "Tizen" and the platform injects the `tizen`
+ * web-API bridge (used by discover.ts / remote.ts). */
+export declare function isTizenRuntime(ua: string): boolean;
+/** LG webOS: firmwares disagree on the spelling, "Web0S" with a digit zero on
+ * the TVs and "webOS" elsewhere, and the platform injects the `webOS` service
+ * bridge (used by discover.ts). Both spellings and the bridge count. */
+export declare function isWebOsRuntime(ua: string): boolean;

package/types/core/src/playback-buffer.d.ts

@@ -0,0 +1,64 @@
+import type { MediaItem } from '@kroma/client/media';
+/** What one title's buffer may grow to, from [`bufferPlan`]. */
+export interface BufferPlan {
+    /** Forward goal (s), sized so its bytes stay inside the budget. */
+    forwardSec: number;
+    /** Kept behind the playhead (s). */
+    backSec: number;
+    /** Byte ceiling, for the engines that take one. */
+    maxBytes: number;
+}
+/**
+ * The buffer budget for a stream running at `bitrateBps`. A 4 Mb/s web-dl gets
+ * minutes; an 80 Mb/s remux gets the seconds that fit in the same bytes, because
+ * asking for minutes of one only buys a film-long fight with the browser's quota.
+ */
+export declare function bufferPlan(bitrateBps?: number | null): BufferPlan;
+/** The plan for the file of `item` that will play. */
+export declare function itemBufferPlan(item: MediaItem): BufferPlan;
+/**
+ * The furthest point the playhead can reach from `t` without waiting on a
+ * download: the end of the range holding it, carried across every hole the
+ * engines skip. `0` when nothing reachable covers `t`.
+ *
+ * `ranges.end(ranges.length - 1)` answers a different question - the far side of
+ * a hole the playhead may be stalled against - and so reads as a healthy buffer
+ * at exactly the moment the picture freezes.
+ */
+export declare function reachableBufferEnd(ranges: TimeRanges, t: number): number;
+/**
+ * Whether the playhead can be moved to `t` without waiting on a download. The
+ * question a seek asks before moving in place rather than re-anchoring, and the
+ * reason it is not `seekable`: that over-reports the whole runtime long before
+ * the remux has produced it.
+ */
+export declare function isPlayableAt(ranges: TimeRanges, t: number): boolean;
+/**
+ * hls.js constructor options for `plan`. The gap numbers are the point: hls.js
+ * defaults to a 0.1 s `maxBufferHole` and waits 2 s before nudging one, which on
+ * a keyframe-cut remux is a frozen picture at a segment boundary.
+ */
+export declare function hlsBufferConfig(plan: BufferPlan): {
+    maxBufferLength: number;
+    maxMaxBufferLength: number;
+    maxBufferSize: number;
+    backBufferLength: number;
+    maxBufferHole: number;
+    highBufferWatchdogPeriod: number;
+    nudgeOffset: number;
+    nudgeMaxRetry: number;
+};
+/**
+ * The `streaming` half of a Shaka config for `plan`. Shaka bounds its buffer in
+ * seconds only, so `forwardSec` is the whole of what keeps it inside the byte
+ * budget; its stall detector otherwise sits on a hole for a full second before
+ * stepping over it.
+ */
+export declare function shakaStreamingConfig(plan: BufferPlan): {
+    bufferingGoal: number;
+    bufferBehind: number;
+    rebufferingGoal: number;
+    gapDetectionThreshold: number;
+    stallThreshold: number;
+    stallSkip: number;
+};

package/types/core/src/playback-stall.d.ts

@@ -0,0 +1,86 @@
+/** How often [`StallWatch.observe`] expects to be fed. */
+export declare const STALL_POLL_MS = 500;
+export declare const STALL_NUDGE_SEC = 0.1;
+/**
+ * One poll of a media element. `currentTime` and `bufferedEnd` need only share a
+ * clock, so either the element's own or an anchored absolute one will do.
+ */
+export interface StallSample {
+    currentTime: number;
+    bufferedEnd: number;
+    paused: boolean;
+    ended?: boolean;
+    seeking?: boolean;
+    /** The element's `readyState`, where the backend has one. A backend that
+     * exposes none is taken at its buffer's word. */
+    readyState?: number;
+}
+/** What to do about a stall, in ascending cost. */
+export type StallStep = 'nudge' | 'recover' | 'restart';
+/** What one sample amounts to: whether the playhead is stuck with something left
+ * to play, and the rung to take about it. `step` is `null` on every sample but
+ * the one that hands a rung out, which is one per `STALL_MS`. */
+export interface StallVerdict {
+    step: StallStep | null;
+    stalled: boolean;
+}
+/** Watches one element for a playhead that has stopped with buffer ahead of it.
+ * The ladder resets only when playback actually resumes. */
+export interface StallWatch {
+    observe(sample: StallSample, nowMs: number): StallVerdict;
+}
+export declare function stallWatch(): StallWatch;
+/**
+ * Whatever is playing, as a stall driver needs it: one sample per poll, and one
+ * way to carry out each rung of the ladder. `sample` answers `null` where there
+ * is nothing to read yet, or where the backend reports no buffered range and so
+ * cannot tell a stall from an honest rebuffer. `recover` answers `false` when it
+ * has no recovery of its own and the driver should restart instead.
+ */
+export interface StallTarget {
+    sample(): StallSample | null;
+    nudge(): void;
+    recover(): boolean;
+    restart(): void;
+}
+/**
+ * Polls `target` every [`STALL_POLL_MS`] and works a stuck playhead back up the
+ * ladder, holding a restart to one per 30 seconds. `onStalled` is handed whether
+ * the playhead is stuck with something left to play, which is what the chrome
+ * shows as buffering. Returns the stop function.
+ */
+export declare function driveStallRecovery(target: StallTarget, onStalled: (stalled: boolean) => void): () => void;
+/** The Shaka slice a stall recovery drives. */
+export interface ShakaRecoverable {
+    retryStreaming(retryDelaySeconds?: number): boolean;
+}
+/**
+ * The MSE recovery rung, for whichever engine is attached: ask Shaka to retry
+ * the stream, else ask hls.js to recover its media error. `false` where neither
+ * is attached and the caller should reach for a fresh source instead.
+ */
+export declare function recoverMse(shaka: ShakaRecoverable | null, hls: Pick<HlsInstanceLike, 'recoverMediaError'> | null): boolean;
+export interface HlsClassLike {
+    Events: {
+        ERROR: string;
+    };
+    ErrorTypes: {
+        NETWORK_ERROR: string;
+        MEDIA_ERROR: string;
+    };
+}
+export interface HlsInstanceLike {
+    on(event: string, listener: (event: string, data: {
+        type: string;
+        fatal: boolean;
+    }) => void): void;
+    startLoad(): void;
+    recoverMediaError(): void;
+}
+/**
+ * Recover the fatal errors hls.js hands back to its caller. Its own action for a
+ * stalled buffer is to do nothing, so an unhandled `bufferStalledError` is a
+ * frozen picture over a full buffer, permanently. `onGiveUp` runs once the same
+ * class of failure has survived `MAX_RECOVERIES` attempts inside a minute.
+ */
+export declare function attachHlsRecovery(hlsClass: HlsClassLike, hls: HlsInstanceLike, onGiveUp: () => void): void;

package/types/core/src/player.d.ts

@@ -0,0 +1,22 @@
+import type { KromaClient } from '@kroma/client';
+import type { MediaItem } from '@kroma/client/media';
+import { type DirectPlayVerdict } from './hevc';
+export interface AttachOptions {
+    startMs?: number;
+    autoplay?: boolean;
+}
+/**
+ * Points a `<video>` at the server's range-streamed original file: no MSE, no
+ * transcoding, the device decodes the source codec natively. Returns the verdict
+ * so the caller can warn when the codec is unsupported.
+ */
+export declare function attachDirectPlay(video: HTMLVideoElement, client: KromaClient, item: MediaItem, opts?: AttachOptions): DirectPlayVerdict;
+/**
+ * The picture's display ratio (width / height) as the CATALOG declares it, or
+ * undefined when the item carries no usable dimensions. Storage geometry, so an
+ * anamorphic source is off by its pixel ratio: a player that can read the
+ * decoder's own size should report that instead and keep this as the seed.
+ */
+export declare function declaredAspect(item: MediaItem): number | undefined;
+/** Formats a runtime as `"2h08"` or `"47min"`. */
+export declare function formatRuntime(durationMs: number | null | undefined): string;

package/types/core/src/push-labels.d.ts

@@ -0,0 +1,6 @@
+import type { PushBlocker } from '@kroma/client/notifications';
+import type { MessageKey } from './i18n';
+/** The message explaining each reason push is unavailable. */
+export declare const PUSH_BLOCKER_LABEL: Record<PushBlocker, MessageKey>;
+/** Whether a thrown error names a blocker, so a caller can look up its copy. */
+export declare function blockerOf(error: unknown): PushBlocker | null;

package/types/core/src/react/handoff-picker.d.ts

@@ -0,0 +1,52 @@
+import type { DiscoveredTv, FinalRefusal, GrantRefusal, GrantResult } from '../handoff';
+import type { Translate } from '../i18n';
+/** How long a finished row keeps saying how it finished. `useNearbyTvs` cannot
+ *  know when the reader has read it, so the picker decides, and it decides that
+ *  a confirmation which never leaves is worse than none. */
+export declare const HANDOFF_OUTCOME_MS = 4000;
+export type HandoffOutcome = 'done' | FinalRefusal;
+export interface HandoffAttempt {
+    device: DiscoveredTv;
+    /** null while the grant is still in flight. */
+    outcome: HandoffOutcome | null;
+}
+export interface HandoffPickerOptions {
+    devices: readonly DiscoveredTv[];
+    connect: (device: DiscoveredTv, check?: string) => Promise<GrantResult>;
+    /** Told how a grant ended, for a shell that answers with more than pixels. */
+    onSettled?: (result: 'granted' | 'refused') => void;
+}
+export interface HandoffPicker {
+    /** The devices to draw, tapped row first: it is the one the reader just acted
+     *  on, and the list beneath it may reorder as televisions come and go. */
+    rows: DiscoveredTv[];
+    /** The one television being asked for its check string, if any. */
+    asking: DiscoveredTv | null;
+    /** How the tap on `device` ended, or null if it is not the tapped row. */
+    outcomeFor: (device: DiscoveredTv) => HandoffOutcome | null;
+    /** Tap a row: asks for the check string first when the beacon needs one. */
+    start: (device: DiscoveredTv) => void;
+    /** Grant outright, with a check string when one was asked for. */
+    grant: (device: DiscoveredTv, check?: string) => Promise<GrantResult>;
+    stopAsking: () => void;
+}
+export declare function useHandoffPicker(opts: HandoffPickerOptions): HandoffPicker;
+export interface CheckPromptOptions {
+    device: DiscoveredTv;
+    onGrant: (device: DiscoveredTv, check: string) => Promise<GrantResult>;
+}
+export interface CheckPrompt {
+    code: string;
+    setCode: (next: string) => void;
+    busy: boolean;
+    /** The last refusal, which is also what makes the field read as invalid. */
+    refused: GrantRefusal | null;
+    submit: (value: string) => Promise<void>;
+}
+/** The five characters, typed. The code is uppercased on the way in on both
+ *  shells: the alphabet has letters in it, a desktop browser capitalizes
+ *  nothing by itself, and what a phone keyboard does is a habit rather than a
+ *  guarantee. */
+export declare function useCheckPrompt(opts: CheckPromptOptions): CheckPrompt;
+/** The line under a row's name: what it is doing, or how it ended. */
+export declare function handoffRowHint(device: DiscoveredTv, busy: boolean, outcome: HandoffOutcome | null, t: Translate): string;

package/types/core/src/react/index.d.ts

@@ -0,0 +1,6 @@
+export type { CheckPrompt, CheckPromptOptions, HandoffAttempt, HandoffOutcome, HandoffPicker, HandoffPickerOptions, } from './handoff-picker';
+export { HANDOFF_OUTCOME_MS, handoffRowHint, useCheckPrompt, useHandoffPicker, } from './handoff-picker';
+export type { LangPatch, LangPrefs, LangPrefsHost, LangPrefUser } from './lang-prefs';
+export { normalizeLangPref, prefValue, useLangPrefs } from './lang-prefs';
+export type { NearbyTvs } from './nearby-tvs';
+export { useNearbyTvs } from './nearby-tvs';

package/types/core/src/react/lang-prefs.d.ts

@@ -0,0 +1,35 @@
+/** The slice of the account the preferences live on. */
+export interface LangPrefUser {
+    audioLanguage?: string | null;
+    subtitleLanguage?: string | null;
+}
+export interface LangPatch {
+    audioLanguage?: string | null;
+    subtitleLanguage?: string | null;
+}
+/** What the HOST app provides: its session's user, its optimistic local
+ * update, and the account PATCH. Nothing here knows which app it is. */
+export interface LangPrefsHost {
+    user: LangPrefUser | null | undefined;
+    updateUser(patch: LangPatch): void;
+    updateAccount(patch: LangPatch): Promise<unknown>;
+}
+export interface LangPrefs {
+    audio: string | null;
+    subtitle: string | null;
+    setAudio: (code: string | null) => void;
+    setSubtitle: (code: string | null) => void;
+}
+/** Read + write the account's playback language preferences, optimistically. */
+export declare function useLangPrefs(host: LangPrefsHost): LangPrefs;
+/** Stored form of a preference: a canonical language code, the `off` sentinel,
+ * or null (no preference); the `none` sentinel the pickers use is a UI value,
+ * never a stored one. A region survives normalization (`fr-FR` stays `fr-FR`)
+ * so a viewer who picked the VFF track isn't handed the VFQ one next time. */
+export declare function normalizeLangPref(code: string | null | undefined): string | null;
+/** The value a settings row shows for a stored preference (null → `none`).
+ * The most specific offered code, not the base, so a viewer who picked the
+ * VFQ track sees `fr-CA` ticked rather than a plain "Français" that would
+ * discard the variant on re-save. A region nobody offers still falls back to
+ * the base, so the picker never comes up with nothing selected. */
+export declare function prefValue(stored: string | null): string;

package/types/core/src/react/nearby-tvs.d.ts

@@ -0,0 +1,31 @@
+import type { KromaClient } from '@kroma/client';
+import type { DiscoveredTv, GrantResult, LanDiscoveryBridge } from '../handoff';
+export interface NearbyTvsOptions {
+    /** Null stands the watcher down: no session yet, or the screen is not up. */
+    client: KromaClient | null;
+    /** This device's own DNS-SD stack, when it has one. A phone that can browse
+     * finds TVs the server could not place beside it, and grants them with the
+     * proof it heard rather than an address the server had to reason about. */
+    lan?: LanDiscoveryBridge;
+}
+export interface NearbyTvs {
+    /** Every TV this device could find, merged across the ways it looked and
+     * sorted by name. Empty when none are waiting, and empty for a caller the
+     * server cannot place beside one either. */
+    devices: DiscoveredTv[];
+    /** The TV a grant is in flight for, or null. */
+    connecting: DiscoveredTv | null;
+    /**
+     * Sign that TV in, and say how it went. A row with `confirmRequired` needs
+     * the check string that TV is printing on its own screen; sent without one
+     * the server answers `checkRequired` rather than granting, and `checkRetryable`
+     * says which refusals leave the beacon standing for another code.
+     *
+     * The outcome comes back from the call rather than from a piece of state,
+     * because two identical refusals in a row are two answers and would be one
+     * state change.
+     */
+    connect: (device: DiscoveredTv, check?: string) => Promise<GrantResult>;
+}
+/** Watch for nearby TVs while the picker is open. */
+export declare function useNearbyTvs(opts: NearbyTvsOptions): NearbyTvs;

package/types/core/src/remote.d.ts

@@ -0,0 +1,26 @@
+export type RemoteKey = 'Up' | 'Down' | 'Left' | 'Right' | 'Enter' | 'Back' | 'Play' | 'Pause' | 'PlayPause' | 'Next' | 'Prev' | 'Stop' | 'Rewind' | 'FastForward' | 'ColorRed' | 'ColorGreen' | 'ColorYellow' | 'ColorBlue';
+/** Resolve a KeyboardEvent into a logical remote key, or null if unmapped. */
+export declare function resolveRemoteKey(e: KeyboardEvent): RemoteKey | null;
+/** A remote-key handler. Return `false` to mark the key *unhandled* (so the event
+ * keeps its default e.g. let a text field own ◀ ▶ / Enter); anything else
+ * (incl. `undefined`) counts as handled and the event is `preventDefault`-ed. */
+export type RemoteKeyHandler = (e: KeyboardEvent) => unknown;
+/** Declarative key → action table: `{ Enter: () => …, Back: () => … }`. */
+export type RemoteKeyMap = Partial<Record<RemoteKey, RemoteKeyHandler>>;
+/**
+ * Resolve a keydown and dispatch it through a {@link RemoteKeyMap} so screens
+ * declare *what* each key does instead of hand-rolling a `switch` with the same
+ * resolve / auto-repeat / `preventDefault` plumbing every time. Returns the
+ * resolved key (or null), so callers can fall through on unbound keys.
+ *
+ * `ignoreRepeat` lists keys whose auto-repeat is swallowed (discrete OK actions:
+ * a held OK that entered a screen must not re-fire on the next one).
+ */
+export declare function dispatchRemoteKey(e: KeyboardEvent, map: RemoteKeyMap, opts?: {
+    ignoreRepeat?: readonly RemoteKey[];
+}): RemoteKey | null;
+/**
+ * On Tizen the media/colour keys must be explicitly registered before the
+ * platform delivers them. No-op everywhere else. Call once at boot.
+ */
+export declare function registerTvMediaKeys(): void;