@kromatv/sdk 0.1.39-canary.3579809

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

@@ -0,0 +1,27 @@
+export * from './airdate';
+export * from './browse';
+export * from './compat';
+export * from './discover';
+export * from './format';
+export * from './genre';
+export * from './genre-art';
+export * from './genre-glyph';
+export * from './handoff';
+export * from './hevc';
+export * from './i18n';
+export * from './lang';
+export * from './master-fetch';
+export * from './match';
+export * from './notification-labels';
+export * from './people';
+export * from './permissions';
+export * from './person-facts';
+export * from './picture-label';
+export * from './platform';
+export * from './playback-buffer';
+export * from './playback-stall';
+export * from './playback-wait';
+export * from './player';
+export * from './push-labels';
+export * from './slug';
+export * from './subtitles';

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

@@ -0,0 +1,11 @@
+import type { MessageKey } from '@kromatv/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,62 @@
+import type { MessageKey, Translate } from '@kromatv/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;
+    title?: string | null;
+    forced?: 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, and a full track wins
+ * over a forced one, which carries only the lines spoken in another language. */
+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 '@kromatv/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/master-fetch.d.ts

@@ -0,0 +1,18 @@
+/** Seconds: a position at or under this is the top of the film, where an anchored
+ * master starts by itself and no seek is owed. */
+export declare const AT_FILM_START_SEC = 0.5;
+/**
+ * Asks for an anchored master, again while the server answers 503: a playlist
+ * ffmpeg has not written yet while its session keeps running. The last answer is
+ * handed back whatever it is. Abort `signal` once the anchor this was asked for
+ * is abandoned, so a master nobody is waiting for cannot retire the session of
+ * the anchor that replaced it.
+ */
+export declare function fetchMaster(url: string, signal?: AbortSignal): Promise<Response>;
+/** The real start of an anchored master: the server seeks to the keyframe
+ * at-or-before the requested anchor (`-noaccurate_seek`) and reports it via
+ * the `X-Hls-Start` header. Using the requested anchor as `baseSec` would
+ * drift the absolute clock by up to one GOP, desyncing the progress bar and
+ * every subtitle cue after a resume/seek/audio switch. A master that never
+ * answers, or answers without naming its start, keeps the requested anchor. */
+export declare function resolveMasterStart(url: string, requested: number): Promise<number>;

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 '@kromatv/client/notifications';
+import type { MessageKey } from '@kromatv/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 '@kromatv/client/media';
+import type { Translate } from '@kromatv/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 '@kromatv/client/accounts';
+import type { MessageKey } from '@kromatv/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 '@kromatv/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/picture-label.d.ts

@@ -0,0 +1,11 @@
+import type { VideoTrack } from '@kromatv/client/media';
+type HdrTraits = Pick<VideoTrack, 'hdr' | 'hdrFormat'>;
+/** The HDR system a picture carries, by the name a viewer knows it by: `HDR`
+ * where the file says HDR without saying which, null for SDR. */
+export declare function hdrLabel(video: HdrTraits | null | undefined): string | null;
+export declare function pictureFormat(video: Pick<VideoTrack, 'codec' | 'bitDepth'> & HdrTraits): string;
+/** The player's quality badge: the HDR system, else what the catalogue's badge
+ * names, and a bit depth above 8, e.g. `Dolby Vision · 10-bit`. Null for an
+ * 8-bit SDR picture that nothing else sets apart. */
+export declare function pictureBadge(video: VideoTrack | null | undefined): string | null;
+export {};

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,79 @@
+import type { MediaItem } from '@kromatv/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 Shaka config for a remux of `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.
+ *
+ * Segments land at their own timestamps, not at the playlist's `EXTINF` sum.
+ * ffmpeg rounds `EXTINF` to the millisecond, and writes a copied video's a few
+ * frames off its fragments, so Shaka's default opens a hole or an overlap at
+ * every cut: Chrome discards the frames an overlap replaces along with every
+ * frame decoded from them, and an open-GOP source cannot decode across a hole.
+ * This relies on the remux's fragments counting from zero, as ffmpeg's fMP4
+ * output does under `-copyts`.
+ */
+export declare function shakaConfig(plan: BufferPlan): {
+    streaming: {
+        bufferingGoal: number;
+        bufferBehind: number;
+        rebufferingGoal: number;
+        gapDetectionThreshold: number;
+        stallThreshold: number;
+        stallSkip: number;
+    };
+    manifest: {
+        hls: {
+            ignoreManifestTimestampsInSegmentsMode: boolean;
+        };
+    };
+};

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

@@ -0,0 +1,95 @@
+/** 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;
+        response?: {
+            code?: number;
+        };
+    }) => void): void;
+    startLoad(): void;
+    recoverMediaError(): void;
+}
+/** What a server's refusal to hand over a stream amounts to. */
+export type StreamRefusal = 'denied' | 'missing';
+/** The refusal an HTTP status is, or null for one a retry may still get past. */
+export declare function streamRefusal(status: number): StreamRefusal | null;
+/**
+ * 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. A
+ * request the server refused (see `streamRefusal`) goes to `onRefused` instead,
+ * since reloading it would only be refused again.
+ */
+export declare function attachHlsRecovery(hlsClass: HlsClassLike, hls: HlsInstanceLike, onGiveUp: () => void, onRefused?: (status: number) => void): void;

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

@@ -0,0 +1,35 @@
+/** Why a picture that should be on screen, or moving, is not: `loading` until
+ * the frame asked for is there, `buffering` when a playing film ran out of data. */
+export type WaitReason = 'loading' | 'buffering';
+/** One read of a media element, with what the player meant it to be doing. */
+export interface WaitSample {
+    /** A play is wanted: the element is playing, or is about to be told to. */
+    intent: boolean;
+    /** A source is on its way and not yet on the element. */
+    attaching: boolean;
+    readyState: number;
+    networkState: number;
+    seeking: boolean;
+    ended: boolean;
+    /** The playhead has sat still while the element was playing (see `playheadWatch`). */
+    frozen: boolean;
+}
+/**
+ * What the viewer is waiting on, or null when there is nothing to wait for:
+ * playing, paused on a frame, or finished. Read off the element's own state
+ * rather than its events, so a remount, a seek while paused or a load that never
+ * fires `waiting` still counts.
+ */
+export declare function waitReason(s: WaitSample): WaitReason | null;
+/** Watches the clock of an element that should be playing. */
+export interface PlayheadWatch {
+    observe(currentTime: number, playing: boolean, nowMs: number): boolean;
+}
+/**
+ * Tells a stopped playhead from a moving one, which `readyState` cannot: an MSE
+ * element parked at the end of what it has appended can go on reporting
+ * `HAVE_ENOUGH_DATA` while nothing moves. `observe` answers true once an element
+ * that is playing has not moved its clock for `FROZEN_MS`; a pause starts the
+ * count over.
+ */
+export declare function playheadWatch(): PlayheadWatch;

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

@@ -0,0 +1,22 @@
+import type { KromaClient } from '@kromatv/client';
+import type { MediaItem } from '@kromatv/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 '@kromatv/client/notifications';
+import type { MessageKey } from '@kromatv/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/ask-for-title.d.ts

@@ -0,0 +1,14 @@
+import type { KromaClient } from '@kromatv/client';
+import type { RequestKind, RequestStatus } from '@kromatv/client/requests';
+export interface AskedTitle {
+    kind: RequestKind;
+    tmdbId: number;
+    requestStatus: RequestStatus | null;
+}
+export interface TitleAsk {
+    status: RequestStatus | null;
+    asking: boolean;
+    failed: boolean;
+    ask: () => void;
+}
+export declare function useAskForTitle(client: Pick<KromaClient, 'requests'> | null, title: Readonly<AskedTitle>): TitleAsk;

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

@@ -0,0 +1,52 @@
+import type { Translate } from '@kromatv/i18n';
+import type { DiscoveredTv, FinalRefusal, GrantRefusal, GrantResult } from '../handoff';
+/** 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,10 @@
+export type { AskedTitle, TitleAsk } from './ask-for-title';
+export { useAskForTitle } from './ask-for-title';
+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';
+export type { HeldSeekTransport } from './seek-hold';
+export { useHeldSeek } from './seek-hold';