@kromatv/sdk 0.1.40-canary.0

package/types/client/src/core/http/concurrency.d.ts

@@ -0,0 +1,8 @@
+export type Concurrency = 'share' | 'latest';
+/** The policy each request runs under. `share` hands an in-flight promise to an
+ * identical call; `latest` aborts the previous call under the same key. Both are
+ * keyed per context, so two clients never share a request. */
+export declare function concurrencyGate(): <T>(key: string, options: {
+    concurrency?: Concurrency;
+    signal?: AbortSignal;
+} | undefined, task: (signal?: AbortSignal) => Promise<T>) => Promise<T>;

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

@@ -0,0 +1,6 @@
+export * from './api-error';
+export * from './path';
+export * from './preconnect';
+export * from './query';
+export * from './request-context';
+export * from './user-agent';

package/types/client/src/core/http/path.d.ts

@@ -0,0 +1,10 @@
+type Segments<P extends string> = P extends `${infer Head}/${infer Tail}` ? Head | Segments<Tail> : P;
+type NameOf<S extends string> = S extends `:${infer Name}` ? Name extends `${infer Head}.${string}` ? Head : Name : never;
+/** The parameter names a path template declares, as a union. */
+export type PathParam<P extends string> = NameOf<Segments<P>>;
+/** The `params` a path template demands: exactly its names, nothing else. */
+export type PathParams<P extends string> = Record<PathParam<P>, string | number>;
+/** Fill a path template. Every value is `encodeURIComponent`-ed, so an id
+ * carrying a slash or a space cannot reshape the URL. */
+export declare function buildPath(template: string, params?: Readonly<Record<string, string | number>>): string;
+export {};

package/types/client/src/core/http/preconnect.d.ts

@@ -0,0 +1,2 @@
+/** Add a `<link rel="preconnect">` to the server origin (no-op off-DOM / if dup). */
+export declare function preconnect(baseUrl: string): void;

package/types/client/src/core/http/query.d.ts

@@ -0,0 +1,9 @@
+/** A query as an object. The encoder is the only place a value is coerced, so a
+ * call site passes what it has and never writes `|| undefined`.
+ *
+ * `undefined`, `null`, `false` and `''` all mean "nothing to say" and drop out.
+ * An ARRAY is a value: it joins with commas and is sent even when empty, which
+ * is how `?copy=` ("decode none") stays distinct from no `copy` at all. */
+export type QueryValue = string | number | boolean | readonly string[] | null | undefined;
+export type Query = Readonly<Record<string, QueryValue>>;
+export declare function queryString(query?: Query): string;

package/types/client/src/core/http/request-context.d.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { type Concurrency } from './concurrency';
+import { type PathParam, type PathParams } from './path';
+import { type Query } from './query';
+export interface KromaClientOptions {
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch;
+    authToken?: string;
+    locale?: string;
+    userAgent?: string;
+}
+type ResponseSchema = z.ZodType;
+/** What a request carries beyond its path and its response schema: the query,
+ * the JSON body, and a `RequestInit` for the rare caller that needs an
+ * `AbortSignal` or a one-off header. */
+export interface RequestOptions {
+    query?: Query;
+    body?: unknown;
+    /** Extra request headers. A header whose value is undefined is not sent, so a
+     * caller passes what it has without building the object conditionally. */
+    headers?: Readonly<Record<string, string | undefined>>;
+    /** Abort this request. Under `concurrency: 'share'` it is ignored: a shared
+     * request belongs to every caller waiting on it, and one walking away must not
+     * cancel it for the others. */
+    signal?: AbortSignal;
+    /** What to do when the same request is already in flight. Omitted, requests are
+     * independent. `share` hands the in-flight promise to an identical call, which
+     * is what a catalogue read wants. `latest` aborts the previous call under the
+     * same key before starting this one, which is what a typeahead wants. */
+    concurrency?: Concurrency;
+    /** How this endpoint is authenticated. `bearer` (the default, so a forgotten
+     * flag fails safe) attaches the session token and spends one silent refresh on
+     * a 401. `public` sends no `Authorization` at all and never refreshes: it is
+     * what a pre-auth handshake needs, and it is why the token exchange cannot
+     * recurse. */
+    auth?: AuthMode;
+}
+export type AuthMode = 'public' | 'bearer';
+/** `params` is required exactly when the path template declares one, and its
+ * keys are exactly the names the template spells. */
+export type PathArgs<P extends string> = [PathParam<P>] extends [never] ? [options?: RequestOptions] : [options: RequestOptions & {
+    params: PathParams<P>;
+}];
+interface Verb {
+    <const P extends string, S extends ResponseSchema>(path: P, response: S, ...args: PathArgs<P>): Promise<z.output<S>>;
+    <const P extends string>(path: P, ...args: PathArgs<P>): Promise<void>;
+}
+/** The one way a domain module reaches the server. A path is a template whose
+ * parameters the compiler reads off it; a response is a zod schema, and its
+ * output type is what the caller gets, so a body the server did not shape never
+ * reaches a caller as a lie. */
+export interface RequestContext {
+    readonly baseUrl: string;
+    /** The absolute URL, for what fetches itself: a `<video>` src, an `<img>`, the
+     * native downloader, a link the user opens. */
+    url<const P extends string>(path: P, ...args: PathArgs<P>): string;
+    get: Verb;
+    post: Verb;
+    put: Verb;
+    patch: Verb;
+    delete: Verb;
+    /** Send raw bytes (an avatar, a backup archive) rather than JSON. */
+    upload: {
+        <const P extends string, S extends ResponseSchema>(path: P, file: Blob, response: S, ...args: PathArgs<P>): Promise<z.output<S>>;
+        <const P extends string>(path: P, file: Blob, ...args: PathArgs<P>): Promise<void>;
+    };
+    /** Raw bytes back, for a file download. */
+    blob<const P extends string>(path: P, ...args: PathArgs<P>): Promise<Blob>;
+    /** A `text/plain` endpoint (the server log tail). */
+    text<const P extends string>(path: P, ...args: PathArgs<P>): Promise<string>;
+    /** The response itself, for the few endpoints whose STATUS is the answer (a
+     * storyboard still being generated answers 202). Never throws on a non-2xx. */
+    send<const P extends string>(path: P, ...args: PathArgs<P>): Promise<Response>;
+    /** An absolute URL outside this server (a TMDB poster), unauthed. */
+    external(url: string): Promise<Response>;
+}
+export interface TransportConfig {
+    baseUrl: string;
+    fetchFn: typeof globalThis.fetch;
+    token(): string | undefined;
+    locale(): string | undefined;
+    /** Mint a fresh bearer after a 401, or resolve undefined to give up. */
+    refresh(): Promise<string | undefined>;
+    /** Aborts every request this context makes unless the call named its own.
+     * A query adapter builds one context per fetch and hands it the runner's
+     * signal, so an endpoint needs no signal parameter of its own. */
+    signal?: AbortSignal;
+}
+/** Wrap `fetchFn` so every request it makes carries `ua`. */
+export declare function withUserAgent(fetchFn: typeof globalThis.fetch, ua: string): typeof globalThis.fetch;
+/** The shared transport: path templates, auth and locale headers, the 64 MiB
+ * body bound, one silent refresh per 401, and a zod parse of every JSON answer. */
+export declare function createRequestContext(config: TransportConfig): RequestContext;
+export {};

package/types/client/src/core/http/user-agent.d.ts

@@ -0,0 +1,7 @@
+export interface DeviceIdentity {
+    version: string;
+    model: string;
+    os: string;
+}
+/** `Kroma/<version> (<model>; <os>)`, the User-Agent a native client sends. */
+export declare function clientUserAgent({ version, model, os }: DeviceIdentity): string;

package/types/client/src/core/ids/ids.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+/** A nominal `string` id: a `UserId` can never be passed where an `ItemId` is
+ * expected. `UserId.parse(s)` turns a raw string into one, and rejects an empty
+ * id rather than carrying it into a URL. Each id is declared by the domain that
+ * owns it; only the ones no single domain owns live here. */
+export declare function brandedId<const B extends string>(brand: B): PropertyKey extends B ? z.ZodString : z.core.$ZodBranded<z.ZodString, B, "out">;
+/** A television's stable per-install id. The same value names it on the cast
+ * roster and on a handoff beacon, so it belongs to neither and carries one
+ * brand. The shape is what `valid_device_id` (kroma-primitives) demands of every
+ * self-declared device id: 8-64 of `[A-Za-z0-9._-]`, narrow enough that a caller
+ * cannot smuggle a path segment or a control character through one. */
+export declare const DeviceId: z.core.$ZodBranded<z.ZodString, "DeviceId", "out">;
+export type DeviceId = z.infer<typeof DeviceId>;

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

@@ -0,0 +1 @@
+export * from './ids';

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

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './http';
+export * from './ids';
+export * from './session';

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

@@ -0,0 +1,3 @@
+export * from './locale';
+export * from './storage';
+export * from './token';

package/types/client/src/core/session/locale.d.ts

@@ -0,0 +1,6 @@
+/** The device-level UI locale override (what the user last picked on THIS
+ * device), or null. Used before sign-in and as a fallback when the account has
+ * no preference. */
+export declare function loadLocalePref(): string | null;
+/** Persist (or clear, with `null`) the device-level UI locale override. */
+export declare function saveLocalePref(locale: string | null): void;

package/types/client/src/core/session/storage.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * The key/value store sessions live in. Only the three methods used here are
+ * required, so a client can supply anything: the browsers pass `localStorage`
+ * (the default), and the native apps pass their own device store.
+ */
+export interface SessionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Install the device store for a platform with no `localStorage` (React
+ * Native has none; without this every save here is a silent no-op). Call it
+ * once, before the app reads a session. */
+export declare function setSessionStorage(storage: SessionStorage | null): void;
+/** Notified whenever the device store is swapped, so anything a module derived
+ * from a stored value at evaluation time can derive it again: a native shell
+ * installs its store only once the session file has been read, which is after
+ * every module has been evaluated. Returns an unsubscribe. */
+export declare function onDeviceStorageChange(listener: () => void): () => void;
+/** The device store this platform is using, or null where there is none.
+ * Exported so other per-device state (language, keyboard layout, recent
+ * searches) can share it instead of hard-coding `localStorage`. */
+export declare function deviceStorage(): SessionStorage | null;
+export declare function readRaw(key: string): string | null;
+export declare function writeRaw(key: string, value: string | null): void;
+/** The stored value at `key`, or null when it is missing or no longer matches
+ * `schema` (a blob written by an older build is dropped, never trusted). */
+export declare function readStored<S extends z.ZodType>(key: string, schema: S): z.output<S> | null;
+/** The stored array at `key`, keeping only the entries that still parse. */
+export declare function readStoredList<S extends z.ZodType>(key: string, schema: S): z.output<S>[];
+export declare function writeStored(key: string, value: unknown): void;

package/types/client/src/core/session/token.d.ts

@@ -0,0 +1,19 @@
+/** The current in-memory session bearer, or undefined when not (yet) exchanged. */
+export declare function sessionToken(): string | undefined;
+/** Set (or clear, with `undefined`) the in-memory session bearer.
+ *  `KromaClient.setAuthToken` calls this, so one call serves both. */
+export declare function setSessionToken(token: string | undefined): void;
+/** How to mint a fresh session bearer, or undefined when nothing registered one. */
+export declare function sessionRefresh(): (() => Promise<string | undefined>) | undefined;
+/** Set (or clear, with `undefined`) how a fresh session bearer is minted.
+ *  `KromaClient.setRefreshHandler` calls this; callers do not. */
+export declare function setSessionRefresh(fn?: () => Promise<string | undefined>): void;
+/** The shape returned by a session-token exchange (`accounts.exchangeToken`). */
+export interface TokenExchange<U = unknown> {
+    token: string;
+    user: U;
+}
+/** Run `exchange` unless one is already in flight, in which case share it. Only
+ * for the no-PIN boot/refresh exchange (a PIN-gated switch-in is a distinct user
+ * action and must not coalesce with the ambient boot exchange). */
+export declare function sharedTokenExchange<U>(exchange: () => Promise<TokenExchange<U>>): Promise<TokenExchange<U>>;

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

@@ -0,0 +1,3 @@
+export { domainModules } from './api/discover';
+export * from './core';
+export * from './kroma-client';

package/types/client/src/kroma-client.d.ts

@@ -0,0 +1,49 @@
+import { type Domains } from './core/client';
+import { type KromaClientOptions, type TransportConfig } from './core/http';
+/** What the client carries beyond its domains: the bearer, the locale, and the
+ * few things a platform needs to reach the server without the transport. */
+export interface ClientControls {
+    readonly baseUrl: string;
+    /** Adopt a session bearer, or clear it with `undefined`. Also publishes it to
+     * the shared session module, so the event socket (which cannot send a header
+     * and reads the bearer from there) follows without a second call. */
+    setAuthToken(token?: string): void;
+    /** When set, a 401 on a `bearer` endpoint triggers one refresh + retry before
+     * the error surfaces. */
+    setRefreshHandler(fn?: () => Promise<string | undefined>): void;
+    /** Mints a fresh bearer through the registered refresh handler and adopts it,
+     * resolving undefined when there is no handler or the session is
+     * unrecoverable. Also serves the event socket, whose refused handshake carries
+     * no readable 401 but needs the same one notion of "get me a fresh bearer". */
+    refreshSession(): Promise<string | undefined>;
+    /** Sent as `Accept-Language`; the server localises admin labels and error
+     * messages to match. */
+    setLocale(locale?: string): void;
+    /** Whether a bearer token is currently set (does not validate it). */
+    readonly hasAuth: boolean;
+    /** For the one caller that cannot send a header: the event socket, which
+     * carries it as a subprotocol. */
+    readonly sessionToken: string | undefined;
+    /** For requests that bypass the transport because the platform owns the
+     * socket (the native downloader behind `media.downloadUrl`); media-element
+     * URLs need nothing, since those routes are public because a `<video>` cannot
+     * send a header. */
+    authHeaders(): Record<string, string>;
+}
+/** The KROMA server, one namespace per domain: `client.media.items()`,
+ * `client.admin.backup.export()`, `client.accounts.passkeys.list()`. Every
+ * namespace is a table of endpoints over one shared transport, which owns the
+ * bearer, the locale and the schema parse. */
+export type KromaClient = Domains & ClientControls;
+/** The two halves a client is made of: the transport its domains fetch through,
+ * and the members that are not a domain. Exported so `@kroma/client/query` can
+ * build a client AND a second context over the same bearer and locale. */
+export declare function kromaClientParts(options: KromaClientOptions): {
+    config: TransportConfig;
+    controls: ClientControls;
+};
+/** One client over one transport. The controls are copied by DESCRIPTOR, not
+ * spread: `hasAuth` and `sessionToken` are getters, and a spread would freeze
+ * them at the value they had when the client was built. */
+export declare function assembleClient(config: TransportConfig, controls: ClientControls): KromaClient;
+export declare function createKromaClient(options: KromaClientOptions): KromaClient;

package/types/client/src/query/index.d.ts

@@ -0,0 +1,35 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Domains } from '../core/client';
+import { type KromaClientOptions } from '../core/http';
+import { type KromaClient } from '../kroma-client';
+type Read = (...args: never[]) => Promise<unknown>;
+/** The reads of one namespace, and its sub-namespaces, as query factories. A
+ * URL builder answers a string rather than a promise and is left out here; the
+ * walk below cannot tell one apart without calling it, so the runtime tree is a
+ * superset of this type and the extra members are unreachable. */
+export type Queries<T> = {
+    [K in keyof T as T[K] extends Read ? K : T[K] extends object ? K : never]: T[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => QueryFor<R> : Queries<T[K]>;
+};
+type QueryFor<R> = ReturnType<typeof queryOptions<R, Error, R, readonly unknown[]>> & {
+    queryFn: (context: {
+        signal: AbortSignal;
+    }) => Promise<R>;
+};
+/** A client that also carries its reads as query options. */
+export type QueryClient = KromaClient & {
+    query: Queries<Domains>;
+};
+/**
+ * A client that also carries every read as TanStack Query options.
+ *
+ * ```ts
+ * const client = createQueryClient({ baseUrl });
+ * const { data } = useSuspenseQuery(client.query.media.item(id)); // MediaItem
+ * ```
+ *
+ * The queries fetch through the same transport as the client, so they share its
+ * bearer, locale and 401 refresh. Each query gets a context of its own carrying
+ * the runner's `AbortSignal`, so a cancelled query cancels its request.
+ */
+export declare function createQueryClient(options: KromaClientOptions): QueryClient;
+export {};

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

@@ -0,0 +1,21 @@
+/** Whole days from today (local midnight) to a `YYYY-MM-DD` date; negative for
+ * a past date, 0 for today. */
+export declare function daysFromToday(airDate: string, now?: Date): number;
+/** Locale-aware relative air date that scales the unit (days → months → years),
+ * like Sonarr's "2 months ago" / "in 3 months", for past AND future dates.
+ * Empty for an undated value. */
+export declare function relativeAirDate(airDate: string | null, locale: string, now?: Date): string;
+/** The same string with its opening letter capitalised, for a sentence that
+ * starts with a relative date ("dans 3 jours" reading as a line of its own).
+ * `Intl.RelativeTimeFormat` has no sentence-case option and `::first-letter`
+ * has no React Native spelling. */
+export declare function sentenceCase(text: string, locale: string): string;
+/** Compact day label with the weekday, e.g. "ven. 24 juil." / "Fri, Jul 24". */
+export declare function shortDayLabel(airDate: string, locale: string): string;
+/** Dated day label, e.g. "24 juil. 2025" / "Jul 24, 2025". Carries the year,
+ * for a list spanning several of them. */
+export declare function datedDayLabel(airDate: string, locale: string): string;
+/** Month heading label, e.g. "juillet 2026" / "July 2026". */
+export declare function monthLabel(airDate: string, locale: string): string;
+/** Stable `YYYY-MM` month bucket key (locale-independent). */
+export declare function monthKey(airDate: string): string;

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

@@ -0,0 +1,45 @@
+import type { Metadata } from '@kroma/client/media';
+/** The minimal shape every browse helper reads; `MediaItem`, `Show` and the web
+ * view-models all satisfy it. */
+export interface Sortable {
+    title: string;
+    year: number | null;
+    addedAt: string;
+    metadata?: (Pick<Metadata, 'rating' | 'releaseDate' | 'genres'> & {
+        backdropUrl?: string | null;
+    }) | null;
+}
+export type SortMode = 'added' | 'release' | 'title' | 'rating';
+/** In picker order. */
+export declare const SORT_MODES: readonly SortMode[];
+export declare function isSortMode(v: unknown): v is SortMode;
+export declare function compareTitles(mode: SortMode): (a: Sortable, b: Sortable) => number;
+/** Returns a new array; never mutates the input. */
+export declare function sortTitles<T extends Sortable>(items: readonly T[], mode: SortMode): T[];
+export interface GenreCount {
+    slug: string;
+    name: string;
+    count: number;
+}
+/** One row per genre, not per spelling: a library holding both `Family` and
+ * `Familial` counts them once. `name` is the first spelling seen, which only a
+ * genre with no copy of its own ever shows. Most common first, ties broken
+ * alphabetically. */
+export declare function collectGenres(items: readonly Sortable[]): GenreCount[];
+/** Matches a display name in either language or a URL slug against the item's
+ * own spellings, so `/genre/family` finds a title stored as `Familial`. */
+export declare function hasGenre(item: Sortable, genre: string): boolean;
+/** Every fast-scroll bucket, in rail order: digits and symbols first, matching
+ * where `localeCompare` files them. */
+export declare const TITLE_LETTERS: readonly string[];
+/** The fast-scroll bucket a title files under: its first letter or digit,
+ * uppercased with diacritics folded ('É' → 'E'). Digit-led and symbol-only
+ * titles bucket under '#', mirroring how `localeCompare` orders them. */
+export declare function titleLetter(title: string): string;
+export interface LetterMark {
+    letter: string;
+    index: number;
+}
+/** The first index of each bucket present in a title-sorted list, in list
+ * order, so a fast-scroll rail can jump straight to `items[mark.index]`. */
+export declare function letterMarks(items: readonly Sortable[]): LetterMark[];

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

@@ -0,0 +1,9 @@
+/** Only the leading numeric parts matter; a trailing suffix (`-rc1`, git hash, …)
+ * is ignored. */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+export interface ClientBuild {
+    version: string;
+    minServerVersion: string;
+}
+export type CompatVerdict = 'ok' | 'server-outdated';
+export declare function checkServerCompat(client: ClientBuild, serverVersion: string): CompatVerdict;

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

@@ -0,0 +1,31 @@
+export { getLocalIPv4 } from './local-ip';
+export { type ResolvedOrigin, resolveServerOrigin } from './server-origin';
+export interface DiscoverOptions {
+    candidates?: string[];
+    timeoutMs?: number;
+    scanSubnet?: boolean;
+    port?: number;
+    concurrency?: number;
+    localIp?: string;
+    fetch?: typeof globalThis.fetch;
+    browse?: (timeoutMs: number) => Promise<Array<{
+        host: string;
+        port: number;
+        name?: string;
+    }>>;
+    browseMs?: number;
+}
+export declare const DEFAULT_DISCOVERY_CANDIDATES: string[];
+export declare function discoverServer(opts?: DiscoverOptions): Promise<string | null>;
+export interface DiscoveredServer {
+    url: string;
+    name?: string;
+    version?: string;
+    instanceId?: string;
+}
+/** Every live KROMA server on the network. Duplicate answers for one server
+ *  (its mDNS name and its IP) collapse on identity, keeping the first origin. */
+export declare function discoverServers(opts?: DiscoverOptions): Promise<DiscoveredServer[]>;
+/** Every `http://<prefix>.1..254:<port>` origin in the /24 containing `ip`,
+ *  excluding the device's own address. */
+export declare function subnetCandidates(ip: string, port?: number): string[];

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

@@ -0,0 +1,63 @@
+import { type AudioTrack, type MediaItem, type VideoTrack } from '@kroma/client/media';
+import type { Translate } from './i18n';
+/** Requests a downscaled rendition of locally-cached artwork (`?w=`, snapped to
+ * a server-side bucket) for the given DISPLAY width, through the same
+ * {@link artworkWidth} the client's own art helpers use. Remote (TMDB fallback)
+ * and non-image URLs pass through untouched. */
+export declare function sizedImageUrl(url: string | null | undefined, displayWidth: number): string | null;
+/** An artwork URL safe to hand to an `<img src>`, or null. Server-supplied poster
+ * and backdrop URLs are third-party input; anything with a scheme must be one
+ * that only ever paints (blocks `javascript:` and other DOM-sink schemes). */
+export declare function safeImageUrl(url: string | null | undefined): string | null;
+/** Rolling 31x unsigned hash, exposed raw so every derived colour (hue, avatar
+ * gradients, placeholder tilts) keys off the same value for the same string. */
+export declare function hashString(s: string): number;
+/** Deterministic hue (0-359) for a string (key-art gradients here, genre art in
+ * genre-art.ts) so the same name always lands on the same hue. */
+export declare function hueFromString(s: string): number;
+/** Deterministic poster stand-in for a title with no artwork: the same string
+ * always draws the same two-tone gradient, so a grid stays stable across
+ * reloads. A CSS string, like {@link genreTint}. */
+export declare function posterGradient(title: string): string;
+/** Deterministic two-stop key-art gradient derived from an item id. */
+export declare function posterColors(id: string): [string, string];
+export declare function codecLabel(codec: string): string;
+/** Top-right quality badge text for a video track, or null. */
+export declare function qualityBadgeForVideo(video: VideoTrack | null | undefined): string | null;
+/** Top-right quality badge text for an item, or null. */
+export declare function qualityBadge(item: MediaItem): string | null;
+/** Zero-padded season/episode tag, e.g. "S01E05" (or a range "S01E05-E06" for a
+ * multi-episode file). Empty string when the item carries no episode numbering. */
+export declare function episodeTag(item: Pick<MediaItem, 'season' | 'episode'> & {
+    episodeEnd?: number | null;
+}): string;
+/** The player header's secondary line: for an episode "Show · S01E05" (the parts
+ * that exist), else the movie meta line "2024 · 2h08 · H.265 · 4K". */
+export declare function playerSubtitle(item: MediaItem): string;
+/** Terse dot-separated metadata line, e.g. "2024 · 2h08 · H.265 · 4K". */
+export declare function metaLine(item: MediaItem): string;
+/** Resolve a metadata image path (relative `/api/...` cached art, or an
+ * absolute URL) against a KROMA origin. */
+export declare function resolveImageUrl(apiBase: string, url: string | null | undefined): string | null;
+/** Two-letter language code for a track badge, e.g. "FR" (or "ST" when unknown). */
+export declare function langCode(lang: string | null | undefined): string;
+/** Channel-layout label, e.g. 6 → "5.1", 2 → "2.0", 1 → "Mono". Null when unknown. */
+export declare function channelLabel(ch: number | null | undefined): string | null;
+/** Localized language name for an ISO code (any spelling `langBase` knows, so
+ * "fre"/"fra"/"fr-FR" all read "Français"), the upper-cased code if unknown, or
+ * null when there is no code at all. */
+export declare function langName(t: Translate, code: string | null | undefined): string | null;
+/** Concise label for a selected audio track, language first: "Français · 5.1 ·
+ * EAC3" (a stream `title` tag wins over the language name). Undefined when
+ * there is no track. */
+export declare function audioTrackLabel(t: Translate, track: AudioTrack | null | undefined): string | undefined;
+/** The commit as it should be READ - flagged when the tree it was built from had
+ * uncommitted changes, since that hash alone no longer describes the binary. */
+export declare function commitLabel(commit: string | null | undefined, dirty: boolean): string | null;
+/** `https://github.com/owner/repo` -> `github.com/owner/repo`, the same trim the
+ * server row gives its URL. A television cannot follow the link, so it is shown
+ * as something to TYPE elsewhere. */
+export declare function repoLabel(repository: string | null | undefined): string | null;
+/** The build stamp in the reader's own locale. Falls back to the raw ISO string
+ * rather than to nothing: an unparseable date is still information. */
+export declare function formatBuildDate(iso: string | null | undefined, locale: string): string | null;

package/types/core/src/genre-art.d.ts

@@ -0,0 +1,21 @@
+import { type Sortable } from './browse';
+/** Per-genre showcase pick, keyed by genre slug: a highly-rated title with
+ * real backdrop art to front each genre card. Scarcest genres are assigned
+ * first and every genre takes its best not-yet-used title, so two cards only
+ * ever share art when a genre has no unused candidate left. Deterministic
+ * across renders. Genres whose titles have no backdrop at all are simply
+ * absent from the map. */
+export declare function genreShowcases<T extends Sortable>(items: readonly T[]): Map<string, T>;
+/** The stable hue (0-359) for a genre, named or slugged: curated for the
+ * genres TMDB publishes, hashed for anything else, so every genre always gets
+ * the same colour whatever it was called when it reached us. */
+export declare function genreHue(nameOrSlug: string): number;
+/** Deterministic two-stop gradient for a genre card (same shape `posterColors`
+ * has for items). Comma-form hsl() so legacy TV engines parse it too. */
+export declare function genreColors(name: string): [string, string];
+/** The genre's vivid accent colour (caption bar / highlights). */
+export declare function genreAccent(name: string): `hsl(${string})`;
+/** Layered CSS background for the caption scrim on a genre card: a glow in the
+ * genre's hue rising from the caption corner over a neutral legibility scrim,
+ * so the artwork above keeps its true colours. Legacy-safe syntax. */
+export declare function genreTint(name: string): string;

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

@@ -0,0 +1,117 @@
+/** TMDB's ids are the same in every language, which is what makes them the
+ * identity a URL and a colour can hang off. Ordered by slug. */
+export declare const GENRES: readonly [{
+    readonly slug: 'action';
+    readonly tmdb: 28;
+    readonly glyph: 'karate';
+}, {
+    readonly slug: 'action-adventure';
+    readonly tmdb: 10759;
+    readonly glyph: 'run';
+}, {
+    readonly slug: 'adventure';
+    readonly tmdb: 12;
+    readonly glyph: 'compass';
+}, {
+    readonly slug: 'animation';
+    readonly tmdb: 16;
+    readonly glyph: 'palette';
+}, {
+    readonly slug: 'comedy';
+    readonly tmdb: 35;
+    readonly glyph: 'joker';
+}, {
+    readonly slug: 'crime';
+    readonly tmdb: 80;
+    readonly glyph: 'gavel';
+}, {
+    readonly slug: 'documentary';
+    readonly tmdb: 99;
+    readonly glyph: 'video';
+}, {
+    readonly slug: 'drama';
+    readonly tmdb: 18;
+    readonly glyph: 'masks-theater';
+}, {
+    readonly slug: 'family';
+    readonly tmdb: 10751;
+    readonly glyph: 'friends';
+}, {
+    readonly slug: 'fantasy';
+    readonly tmdb: 14;
+    readonly glyph: 'dragon';
+}, {
+    readonly slug: 'history';
+    readonly tmdb: 36;
+    readonly glyph: 'building-monument';
+}, {
+    readonly slug: 'horror';
+    readonly tmdb: 27;
+    readonly glyph: 'ghost';
+}, {
+    readonly slug: 'kids';
+    readonly tmdb: 10762;
+    readonly glyph: 'mood-kid';
+}, {
+    readonly slug: 'music';
+    readonly tmdb: 10402;
+    readonly glyph: 'music';
+}, {
+    readonly slug: 'mystery';
+    readonly tmdb: 9648;
+    readonly glyph: 'footsteps';
+}, {
+    readonly slug: 'news';
+    readonly tmdb: 10763;
+    readonly glyph: 'news';
+}, {
+    readonly slug: 'reality';
+    readonly tmdb: 10764;
+    readonly glyph: 'camera-selfie';
+}, {
+    readonly slug: 'romance';
+    readonly tmdb: 10749;
+    readonly glyph: 'heart';
+}, {
+    readonly slug: 'sci-fi-fantasy';
+    readonly tmdb: 10765;
+    readonly glyph: 'planet';
+}, {
+    readonly slug: 'science-fiction';
+    readonly tmdb: 878;
+    readonly glyph: 'ufo';
+}, {
+    readonly slug: 'soap';
+    readonly tmdb: 10766;
+    readonly glyph: 'heart-broken';
+}, {
+    readonly slug: 'talk';
+    readonly tmdb: 10767;
+    readonly glyph: 'microphone';
+}, {
+    readonly slug: 'thriller';
+    readonly tmdb: 53;
+    readonly glyph: 'spy';
+}, {
+    readonly slug: 'tv-movie';
+    readonly tmdb: 10770;
+    readonly glyph: 'device-tv-old';
+}, {
+    readonly slug: 'war';
+    readonly tmdb: 10752;
+    readonly glyph: 'tank';
+}, {
+    readonly slug: 'war-politics';
+    readonly tmdb: 10768;
+    readonly glyph: 'building-bank';
+}, {
+    readonly slug: 'western';
+    readonly tmdb: 37;
+    readonly glyph: 'cactus';
+}];
+export type GenreRow = (typeof GENRES)[number];
+export type GenreSlug = GenreRow['slug'];
+/** The copy key naming a genre, which is what `genreLabel` looks up. Assigning
+ * it to a `MessageKey` is what makes a row with no `genre.*` copy fail to
+ * compile. */
+export type GenreCopyKey = `genre.${GenreSlug}`;