@kromatv/sdk 0.1.39-canary.3579809

package/types/ui/src/lib/splash-motion.d.ts

@@ -0,0 +1,25 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface DriftSpec {
+    /** Travel as a fraction of the measured box, per axis. */
+    x: number;
+    y: number;
+    /** The constant overscan that keeps an edge out of frame while it pans. Held
+     *  still rather than animated: a scale in flight makes a compositor
+     *  re-rasterise the layer on every frame. */
+    zoom: number;
+    /** How long the pan takes to cross its travel, in ms. */
+    ms: number;
+    /** The measured box the fractions are taken against. React Native cannot
+     *  interpret a percentage inside a transform, so the native half needs the
+     *  pixels; the web half ignores these and lets CSS take the percentage. */
+    width: number;
+    height: number;
+}
+/**
+ * The drift for the artwork layer: a slow pan across a frame held oversized for
+ * it, one way, from the moment the layer mounts. Belongs on an `Animated.View` - it carries an
+ * `Animated.Value`, which is why it is cast rather than typed.
+ */
+export declare function useDrift(spec: Readonly<DriftSpec>): StyleProp<ViewStyle>;
+/** The colour grade for the artwork. A CSS filter, so the panel has none. */
+export declare const GRADE: StyleProp<ViewStyle>;

package/types/ui/src/lib/splash-motion.web.d.ts

@@ -0,0 +1,26 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { DriftSpec } from './splash-motion';
+/** react-native-web's keyframe extension, absent from React Native's style types. */
+export type CssDrift = ViewStyle & {
+    animationKeyframes?: Record<string, {
+        transform?: string;
+    }>[];
+    animationTimingFunction?: string;
+    animationDuration?: string;
+    animationIterationCount?: string;
+    animationFillMode?: string;
+    willChange?: string;
+};
+/**
+ * The drift for the artwork layer: a slow pan across a frame held oversized for
+ * it, one way, from the moment the layer mounts. Plain styles, so it rides on the `Animated.View`
+ * the native half needs.
+ */
+export declare function useDrift(spec: Readonly<DriftSpec>): StyleProp<ViewStyle>;
+/** The colour grade for the artwork.
+ *
+ * It rides the IMAGE, never the drifting view above it: a filter is re-run over
+ * whatever its element renders, so on the animated node it re-graded a
+ * full-screen still every frame it moved. Held on something that never moves,
+ * it is rasterised once and the drift transforms the result. */
+export declare const GRADE: StyleProp<ViewStyle>;

package/types/ui/src/lib/stable-callback.d.ts

@@ -0,0 +1,9 @@
+/** One function identity, forever, whose body always sees the latest render's
+ *  values. Reach for it when the FUNCTION ITSELF is a prop, and a moving
+ *  identity would re-render a memoised child or a whole list.
+ *
+ *  `useEffectEvent` is not a substitute: React returns a NEW closure from it on
+ *  every render (`updateEvent` in react-dom), which is why React's own advice is
+ *  not to pass an effect event to another component. Keep effect events for
+ *  reading fresh values inside an effect. */
+export declare function useStableCallback<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;

package/types/ui/src/lib/static-text.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type TextStyle } from 'react-native';
+type StaticRest = {
+    children?: string | number | Array<string | number>;
+    testID?: string;
+};
+/** React Native has no cheaper host than its Text, so every string is one. */
+export declare function isStaticText(_rest: Readonly<Record<string, unknown>>): _rest is StaticRest;
+interface StaticTextProps {
+    style?: StyleProp<TextStyle>;
+    lines?: number;
+    children?: ReactNode;
+    testID?: string;
+}
+/** The Text a string renders as. */
+export declare function StaticText({ style, lines, children, testID }: Readonly<StaticTextProps>): import("react").JSX.Element;
+export {};

package/types/ui/src/lib/static-text.web.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+import { type StyleProp, type TextStyle } from 'react-native';
+type StaticRest = {
+    children?: string | number | Array<string | number>;
+    testID?: string;
+};
+/** Whether a string can skip react-native-web's Text: nothing beside its
+ *  children and `testID`, and children that are only strings and numbers. */
+export declare function isStaticText(rest: Readonly<Record<string, unknown>>): rest is StaticRest;
+interface StaticTextProps {
+    style?: StyleProp<TextStyle>;
+    lines?: number;
+    children?: ReactNode;
+    testID?: string;
+}
+/** The `<div>` a react-native-web Text renders, for a string that needs nothing
+ *  else from it. Inside another Text it is that Text's span, as before. */
+export declare function StaticText({ style, lines, children, testID }: Readonly<StaticTextProps>): import("react").JSX.Element;
+export {};

package/types/ui/src/lib/static-view.d.ts

@@ -0,0 +1,3 @@
+/** React Native has no cheaper host than its View, so every box is one. */
+export declare function isStaticHost(_rest: Readonly<Record<string, unknown>>): boolean;
+export { View as StaticView } from 'react-native';

package/types/ui/src/lib/static-view.web.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/** Whether a box with no ref can skip react-native-web's View: nothing beside
+ *  its style and children but `testID` and `dataSet`. */
+export declare function isStaticHost(rest: Readonly<Record<string, unknown>>): boolean;
+interface StaticViewProps {
+    style?: StyleProp<ViewStyle>;
+    children?: ReactNode;
+    testID?: string;
+    dataSet?: Record<string, string | number | undefined>;
+}
+/** The `<div>` a react-native-web View renders, for a box that needs nothing
+ *  else from it. */
+export declare function StaticView({ style, children, testID, dataSet }: Readonly<StaticViewProps>): import("react").JSX.Element;
+export {};

package/types/ui/src/lib/surface-bands.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+interface SurfaceParts {
+    header: unknown;
+    panel: unknown;
+    footer: unknown;
+}
+interface SurfaceBands {
+    header: ReactNode;
+    panel: ReactNode;
+    footer: ReactNode;
+    /** Everything that claimed no band, which a Root hands to the panel it draws
+     *  for itself. */
+    loose: ReactNode[];
+}
+/**
+ * The three bands of an overlay surface, taken from its DIRECT children.
+ * Yoga has no `order` and a container cannot read its own subtree, so a Root
+ * that wants its header pinned above a scrolling panel sorts what it was given
+ * (see DESIGN.md §2). <Dialog> and <Drawer> are both this.
+ *
+ * A band holding nothing is not a band: a surface whose footer is written
+ * around a condition draws no shelf on the pass where the condition is false.
+ */
+declare function surfaceBands(children: ReactNode, parts: Readonly<SurfaceParts>): SurfaceBands;
+export type { SurfaceBands };
+export { surfaceBands };

package/types/ui/src/lib/surface-presentation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Where an anchored surface's content appears: `panel` hangs it off the
+ * trigger, `dialog` puts it over the screen, and `auto` asks the platform - a
+ * dialog under a D-pad, a panel under a pointer.
+ */
+type SurfacePresentation = 'auto' | 'panel' | 'dialog';
+type ResolvedPresentation = Exclude<SurfacePresentation, 'auto'>;
+/** Resolves one surface: what it was asked for, else what the shell said, else
+ *  the platform - a dialog inside a <FocusScope>, where a D-pad drives, and a
+ *  panel outside one. */
+declare function useSurfacePresentation(asked?: SurfacePresentation): ResolvedPresentation;
+export type { ResolvedPresentation, SurfacePresentation };
+export { useSurfacePresentation };

package/types/ui/src/lib/surface-shell.d.ts

@@ -0,0 +1,29 @@
+type SurfaceWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * THE overlay ladder: how wide a `<Dialog>` or a `<Drawer>` may be, by the
+ * densest thing it holds rather than by a number a call site invented. A panel
+ * that picks its own width is how eight of them ended up between 460 and 768
+ * with no rule telling them apart, and how a list of rows that each carry a
+ * hint came to wrap onto three lines beside half a screen of nothing.
+ *
+ * | `xs` | a rail: a column of destinations, nothing beside anything |
+ * | `sm` | a question and its answer |
+ * | `md` | a form: fields stacked, one control per line |
+ * | `lg` | rows that each carry a hint, or a form beside a list |
+ * | `xl` | a grid, or a browser |
+ *
+ * Read it where the number itself is needed (a virtualised row measuring
+ * itself against the panel); write the STEP everywhere else.
+ */
+export declare const SURFACE_WIDTH: Record<SurfaceWidth, number>;
+/** The gutter a `<Dialog>`'s three bands share on a window wide enough for it. */
+export declare const DIALOG_PAD = 40;
+/** The gutter a `<Dialog>`'s three bands share. 40 frames a panel on a desk;
+ *  on a 390pt phone it would leave a 278pt column, so a narrow window keeps
+ *  20. */
+export declare function dialogPad(windowWidth: number): number;
+/** The frame a floating surface keeps from the screen's edges. 64 frames a
+ *  television; on a phone it would cost a third of the width the panel has to
+ *  say anything in, so a narrow window keeps 16. */
+export declare function surfaceGutter(windowWidth: number): number;
+export type { SurfaceWidth };

package/types/ui/src/lib/svg.d.ts

@@ -0,0 +1 @@
+export { Circle, default as Svg, Ellipse, G, Line, Path, Polygon, Polyline, Rect, SvgXml, } from 'react-native-svg';

package/types/ui/src/lib/svg.web.d.ts

@@ -0,0 +1,17 @@
+import type { SVGProps } from 'react';
+type El<T> = (props: SVGProps<T>) => React.ReactElement;
+export declare const Svg: El<SVGSVGElement>;
+export declare const Path: El<SVGPathElement>;
+export declare const Circle: El<SVGCircleElement>;
+export declare const Rect: El<SVGRectElement>;
+export declare const Line: El<SVGLineElement>;
+export declare const Polyline: El<SVGPolylineElement>;
+export declare const Polygon: El<SVGPolygonElement>;
+export declare const Ellipse: El<SVGEllipseElement>;
+export declare const G: El<SVGGElement>;
+export declare function SvgXml({ xml, width, height, }: Readonly<{
+    xml: string | null;
+    width?: number | string;
+    height?: number | string;
+}>): import("react").JSX.Element | null;
+export {};

package/types/ui/src/lib/theme-audio.d.ts

@@ -0,0 +1,8 @@
+import { type SessionStorage } from '@kromatv/client';
+export declare const TARGET_VOLUME = 0.35;
+export declare const FADE_IN_MS = 900;
+export declare const FADE_OUT_MS = 600;
+/** The stored mute preference. Safe everywhere: a device with no store reads
+ * as unmuted, which is the design's default. */
+export declare function readThemeMuted(storage?: SessionStorage | null): boolean;
+export declare function writeThemeMuted(muted: boolean, storage?: SessionStorage | null): void;

package/types/ui/src/lib/top-fade-band.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+/** A copy of the backdrop over the top edge: while `active`, it hides scrolled content above `inset` and fades it back in over the next 160 px. `offset` is how far below the backdrop's origin the band's parent sits; no `children` fades to the ground colour. Nothing on native, which has no mask. */
+export declare function TopFadeBand(_props: Readonly<{
+    inset: number;
+    active: boolean;
+    offset?: number;
+    children?: ReactNode;
+}>): null;

package/types/ui/src/lib/top-fade-band.web.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+/** A copy of the backdrop over the top edge: while `active`, it hides scrolled content above `inset` and fades it back in over the next 160 px. `offset` is how far below the backdrop's origin the band's parent sits; no `children` fades to the ground colour. Nothing on native, which has no mask. */
+export declare function TopFadeBand({ inset, active, offset, children, }: Readonly<{
+    inset: number;
+    active: boolean;
+    offset?: number;
+    children?: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/src/lib/top-fade.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/** A page scroller's frame: once the `FocusScroll` or `VirtualGrid` inside it leaves its start, what scrolls up dissolves into `backdrop` (the screen's own layers, laid out against the frame's parent; the ground colour when omitted), hidden above `inset` and faded in below it. */
+export declare function TopFade({ inset, backdrop, style, children, }: Readonly<{
+    inset?: number;
+    backdrop?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/src/lib/trailing-row.d.ts

@@ -0,0 +1,2 @@
+/** The row a grid's mounted window trails behind the focus; here it is the focus itself. */
+export declare function useTrailingRow(focused: number, _settleMs: number): number;

package/types/ui/src/lib/trailing-row.web.d.ts

@@ -0,0 +1,2 @@
+/** The row a grid's mounted window trails behind the focus, caught up once presses settle. */
+export declare function useTrailingRow(focused: number, settleMs: number): number;

package/types/ui/src/lib/tv-remote.d.ts

@@ -0,0 +1,9 @@
+import { type HWEvent } from 'react-native';
+/**
+ * Whether this event is the trailing half of a press and should be ignored.
+ *
+ * Android TV reports a press as two events (`0` down, `1` up); tvOS reports one
+ * and stamps it `1` anyway, so a bare `eventKeyAction === 1` filter drops every
+ * key on Apple TV.
+ */
+export declare function isRemoteKeyUp(evt: HWEvent): boolean;

package/types/ui/src/lib/use-complete-once.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a stable `report(value)`. Call it whenever the buffer changes - from
+ * an event handler, or from an effect keyed on the value - and it fires
+ * `onComplete` on the transition into a full buffer and never again until the
+ * buffer drops back below `length`.
+ *
+ * `length` and `onComplete` are read through a ref rather than closed over, so
+ * the returned function keeps one identity for the field's lifetime: an effect
+ * that depends on it does not re-run every time the parent re-renders with a
+ * fresh callback.
+ */
+export declare function useCompleteOnce(length: number, onComplete?: (value: string) => void): (value: string) => void;

package/types/ui/src/lib/use-controllable.d.ts

@@ -0,0 +1 @@
+export declare function useControllable<T>(controlled: T | undefined, defaultValue: T, onChange?: (next: T) => void): [T, (next: T) => void];

package/types/ui/src/lib/use-copy.d.ts

@@ -0,0 +1,20 @@
+/** What a copy control is currently saying. `failed` exists because a refused
+ * write is common (see {@link useCopy}) and a control that silently does nothing
+ * is the one outcome a reader cannot tell apart from a broken build. */
+type CopyState = 'idle' | 'copied' | 'failed';
+interface Copier {
+    /** False where the platform has no clipboard at all - a television, a phone.
+     * A control renders NOTHING there rather than a dead affordance. It starts
+     * true on every web target, prerendered or not, so a hydrating page and its
+     * markup agree, and is re-read once the document is there. */
+    available: boolean;
+    /** `copied` or `failed` for a beat after an attempt, then `idle` again. Call
+     * sites index their label, glyph and ink off it. */
+    state: CopyState;
+    copy: (text: string | undefined) => void;
+}
+/** The clipboard where the platform has one, a write, and a tick that reverts
+ * on its own. */
+declare function useCopy(): Copier;
+export type { CopyState };
+export { useCopy };

package/types/ui/src/lib/use-fade-rise.d.ts

@@ -0,0 +1,12 @@
+import { type ViewStyle } from 'react-native';
+export declare const FADE_MS = 180;
+export interface FadeRise {
+    mounted: boolean;
+    style: ViewStyle;
+}
+/**
+ * A short fade with a small rise, cut to nothing where the platform asks for less
+ * motion. `mounted` stays true through the exit, so a caller stops drawing once it
+ * is false rather than holding an invisible surface over the stage.
+ */
+export declare function useFadeRise(shown: boolean): FadeRise;

package/types/ui/src/lib/use-focus-mirror.d.ts

@@ -0,0 +1,4 @@
+/** A ref for a control whose focus is state rather than platform focus: while
+ *  `focused`, the document's focus sits on the element it is attached to (see
+ *  lib/focus-mirror). */
+export declare function useFocusMirror(focused: boolean): (element: unknown) => void;

package/types/ui/src/lib/use-focused-row.d.ts

@@ -0,0 +1,5 @@
+import type { View } from 'react-native';
+/** The host ref of a row whose focus is a prop rather than the platform's (a
+ *  player panel's rows): while `focused`, the document's focus sits on it (see
+ *  lib/focus-mirror) and the page it scrolls in shows it whole. */
+export declare function useFocusedRow(focused: boolean): (view: View | null) => void;

package/types/ui/src/lib/use-foreground.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether the app is the one on screen. One hook for every shell: the platform
+ * answers on tvOS, Android TV and the phones, and react-native-web answers from
+ * the Page Visibility API on the browser televisions and the web client.
+ *
+ * `inactive` counts as in front: it is the app switcher and the pull-down shade
+ * on iOS, a second of nothing rather than a departure.
+ */
+export declare function useForeground(): boolean;

package/types/ui/src/lib/use-growing-count.d.ts

@@ -0,0 +1,12 @@
+interface GrowingCount {
+    /** How many items to render right now. */
+    count: number;
+    /** True for the items near the end of what is rendered: give those a
+     *  `onFocus={grow}` and the next chunk arrives before they run out. */
+    isNearEnd: (index: number) => boolean;
+    /** Render the next chunk. */
+    grow: () => void;
+}
+declare function useGrowingCount(total: number, step: number): GrowingCount;
+export type { GrowingCount };
+export { useGrowingCount };

package/types/ui/src/lib/use-menu-keys.d.ts

@@ -0,0 +1,3 @@
+export declare function useMenuKeys(): {
+    hold(): () => void;
+};

package/types/ui/src/lib/use-prefetch-ahead.d.ts

@@ -0,0 +1,3 @@
+/** Fetch and decode `uris` in order, a few at a time when the device is idle, so
+ *  artwork drawn next is ready before it is shown. A new list replaces the old. */
+export declare function usePrefetchAhead(uris: readonly string[]): void;

package/types/ui/src/lib/use-reveal-on-focus.d.ts

@@ -0,0 +1,15 @@
+import { type View } from 'react-native';
+import { type Anchor } from '#ui/lib/reveal-contexts';
+/**
+ * What a control uses to ask to be shown when it takes the focus: the page
+ * reveals its row (or the control when it is in none), the rail the control.
+ */
+declare function useRevealOnFocus(self: Anchor): () => void;
+/** {@link useRevealOnFocus} for a caller that already holds the input source's `pointerDriving`. */
+declare function useRevealOnFocusBy(self: Anchor, pointerDriving: () => boolean): () => void;
+/**
+ * The anchor of a row whose focus is a prop rather than the navigator's (a
+ * player panel's rows): the page reveals it the moment `focused` turns true.
+ */
+declare function useRevealWhenFocused(focused: boolean): (view: View | null) => void;
+export { useRevealOnFocus, useRevealOnFocusBy, useRevealWhenFocused };

package/types/ui/src/lib/use-settled-value.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `value`, held back until it has stood still for `delayMs`. The first value is
+ * taken at once; every later one waits.
+ */
+export declare function useSettledValue<T>(value: T, delayMs: number): T;

package/types/ui/src/lib/veil-bitmap.d.ts

@@ -0,0 +1,15 @@
+interface Stop {
+    color: string;
+    at: number | null;
+}
+interface Ramp {
+    angle: number;
+    stops: Stop[];
+}
+/** The `linear-gradient(...)` list a veil is written as, or null for anything
+ *  else (a radial gradient, a length stop), which the caller paints as CSS. */
+export declare function parseRamps(css: string): Ramp[] | null;
+/** The ramp drawn once into a small PNG, as a data URL, or null where there is
+ *  no canvas to draw it with or the ramp is not one this can draw. */
+export declare function veilBitmap(css: string): string | null;
+export {};

package/types/ui/src/lib/veil-layer.d.ts

@@ -0,0 +1,4 @@
+/** The ramp as a gradient React Native draws itself. */
+export declare function VeilLayer({ ramp }: Readonly<{
+    ramp: string;
+}>): import("react").JSX.Element;

package/types/ui/src/lib/veil-layer.web.d.ts

@@ -0,0 +1,4 @@
+/** The ramp drawn once into a small bitmap stretched over the box, or as CSS where it cannot be drawn. */
+export declare function VeilLayer({ ramp }: Readonly<{
+    ramp: string;
+}>): import("react").JSX.Element;

package/types/ui/src/lib/web-layers.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { type StyleScope } from '#ui/core';
+import type { Radius } from '#ui/core/tokens/layout';
+interface WebLayersArgs {
+    src: string | null;
+    under: string | null;
+    alt: string;
+    fit: 'cover' | 'contain';
+    position: string;
+    radius: Radius | undefined;
+    priority: boolean;
+    duration: number;
+    errored: boolean;
+    layered: boolean;
+    markLoaded: () => void;
+    onCovered: ((src: string) => void) | undefined;
+    onLoad: (() => void) | undefined;
+    onError: () => void;
+}
+declare function webLayers(at: Readonly<WebLayersArgs>, scope: StyleScope): ReactNode;
+export { webLayers };

package/types/ui/src/lib/wheel-pan.d.ts

@@ -0,0 +1,7 @@
+import type { RefObject } from 'react';
+import type { ScrollView, View } from 'react-native';
+type WheelHost = RefObject<View | ScrollView | null>;
+/** No-op off the web. */
+declare function useWheelTravel(_ref: WheelHost, _onTravel: (delta: number) => void, _enabled?: boolean): void;
+export type { WheelHost };
+export { useWheelTravel };

package/types/ui/src/lib/wheel-pan.web.d.ts

@@ -0,0 +1,11 @@
+import { type RefObject } from 'react';
+import type { ScrollView, View } from 'react-native';
+type WheelHost = RefObject<View | ScrollView | null>;
+/**
+ * Reports raw px along whichever axis moved more and consumes the gesture.
+ * Only for a list that owns its surface's scroll entirely; anything that
+ * scrolls one axis while the page owns the other must be a real scroller.
+ */
+declare function useWheelTravel(ref: WheelHost, onTravel: (delta: number) => void, enabled?: boolean): void;
+export type { WheelHost };
+export { useWheelTravel };

package/types/ui/src/lib/wheel-paths.d.ts

@@ -0,0 +1,5 @@
+export declare const KROMA_WHEEL_COLORS: readonly ['#F2685C', '#F4B642', '#5FBF8F', '#4F9DE0', '#6366F1', '#A855F7'];
+export declare const KROMA_WHEEL_SEGMENTS: readonly ['M50 35 L50 6 A44 44 0 0 1 88 28 L62.99 42.5 A15 15 0 0 0 50 35 Z', 'M62.99 42.5 L88 28 A44 44 0 0 1 88 72 L62.99 57.5 A15 15 0 0 0 62.99 42.5 Z', 'M62.99 57.5 L88 72 A44 44 0 0 1 50 94 L50 65 A15 15 0 0 0 62.99 57.5 Z', 'M50 65 L50 94 A44 44 0 0 1 12 72 L37.01 57.5 A15 15 0 0 0 50 65 Z', 'M37.01 57.5 L12 72 A44 44 0 0 1 12 28 L37.01 42.5 A15 15 0 0 0 37.01 57.5 Z', 'M37.01 42.5 L12 28 A44 44 0 0 1 50 6 L50 35 A15 15 0 0 0 37.01 42.5 Z'];
+export type WheelSpin = 'idle' | 'loading';
+export declare const WHEEL_SPIN_MS: Record<WheelSpin, number>;
+export declare const WHEEL_VIEWBOX = "6 6 88 88";

package/types/ui/src/native-film.d.ts

@@ -0,0 +1,2 @@
+export type { NativeFilmProps } from './lib/native-film';
+export { NativeFilm } from './lib/native-film';

package/types/ui/src/services/account-storage.d.ts

@@ -0,0 +1,17 @@
+/** Session persistence follows the same root backend as UI preferences. */
+export declare function useAccountStorage(): {
+    loadSession: () => import("@kromatv/client/accounts").StoredSession | null;
+    saveSession: (session: import("@kromatv/client/accounts").StoredSession) => void;
+    clearSession: () => void;
+    loadAccounts: (serverUrl?: string) => import("@kromatv/client/accounts").StoredSession[];
+    forgetAccount: (userId: import("@kromatv/client/accounts").UserId, serverUrl?: string) => void;
+    loadServers: () => import("@kromatv/client/accounts").SavedServer[];
+    saveServer: (server: {
+        url: string;
+        name?: string | null;
+        lastUsedAt?: number;
+    }) => import("@kromatv/client/accounts").SavedServer[];
+    touchServer: (url: string) => void;
+    forgetServer: (url: string) => void;
+    migrateStorage: () => void;
+};

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

@@ -0,0 +1,16 @@
+import type { KromaClient } from '@kromatv/client';
+import type { ItemId, Section } from '@kromatv/client/media';
+export interface UseAiSuggestOptions {
+    /** Gate polling (web waits for auth to hydrate). Default `true`. */
+    active?: boolean;
+}
+export interface UseAiSuggestResult {
+    /** The generated section once it arrives (items may be empty), else `null`. */
+    section: Section | null;
+    /** True once the server has answered that it is generating, until the section
+     * lands or polling gives up; false before its first answer. */
+    pending: boolean;
+    /** Elapsed-time progress estimate (0..1) for a spinner while `pending`. */
+    progress: number;
+}
+export declare function useAiSuggest(client: KromaClient, id: ItemId, { active }?: UseAiSuggestOptions): UseAiSuggestResult;

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

@@ -0,0 +1,41 @@
+import type { AuthResult, StoredSession, User, UserId } from '@kromatv/client/accounts';
+import { type KromaClient } from '@kromatv/client';
+/** Outcome of an {@link AuthSession.activate}. `needsPin` asks the UI to collect
+ * the profile PIN and call `activate` again with it; `retryAfter` (seconds) is
+ * set when the PIN was rate-limited (429) so the UI can show a cooldown;
+ * `unreachable` means the server never answered, which says nothing about the
+ * token, so the UI should offer a retry rather than route to a full re-login. */
+export type ActivateResult = {
+    ok: true;
+} | {
+    ok: false;
+    needsPin: boolean;
+    error?: string;
+    retryAfter?: number;
+    unreachable?: boolean;
+};
+export interface AuthSession {
+    /** The active account (access token + user), or null when signed out. */
+    session: StoredSession | null;
+    /** The signed-in user (null when signed out). */
+    user: User | null;
+    /** Accounts remembered on this device switchable via {@link activate}. */
+    accounts: StoredSession[];
+    /** True once storage hydration + the boot token exchange have run. */
+    ready: boolean;
+    /** Persist a login/register result (access token + first session) and sign in. */
+    apply: (res: AuthResult) => void;
+    /** Switch into a remembered account by exchanging its access token for a
+     * session. Pass `pin` for a PIN-locked profile (required on switch-in). */
+    activate: (s: StoredSession, pin?: string) => Promise<ActivateResult>;
+    /** Back to the picker WITHOUT forgetting the account: drop the in-memory
+     * session and re-lock the access token so the next switch-in re-prompts. */
+    switchProfile: () => void;
+    /** Forget a remembered account on this device (revokes it when it's active). */
+    forget: (userId: UserId) => void;
+    /** Fully sign out of the current account (revoke tokens + forget this device). */
+    logout: () => Promise<void>;
+    /** Merge a patch into the active user, persisting it to the stored session. */
+    updateUser: (patch: Partial<User>) => void;
+}
+export declare function useAuthSession(client: KromaClient | null): AuthSession;

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

@@ -0,0 +1,36 @@
+import type { DeviceId } from '@kromatv/client';
+import type { CastCommand, CastReceiver } from '@kromatv/client/cast';
+import type { ItemId } from '@kromatv/client/media';
+import type { DiscoveredTv } from '@kromatv/core';
+/** Why an order did not reach a television, as a message key. `cast.titleGone`
+ * is the title's failure rather than the set's, so the sender keeps driving it. */
+export type CastFailure = 'cast.gone' | 'cast.titleGone' | 'cast.failed';
+/** What a sender can do with the TV it is driving. */
+export interface Cast {
+    /** Live receivers on this server, the caller's own devices first. */
+    receivers: CastReceiver[];
+    /** Televisions heard in the room that have no account yet, so cannot be cast
+     * to until someone gives them one. Empty on a shell that cannot listen to its
+     * own link, which is every shell without the native module. */
+    pairable: DiscoveredTv[];
+    /** The receiver this sender is driving, or null when playing locally. */
+    active: CastReceiver | null;
+    /** Whether any TV is available to cast to (drives the button's visibility). */
+    available: boolean;
+    /** The active receiver's position, interpolated between heartbeats (ms). */
+    positionMs: number;
+    /** Start driving a receiver (or `null` to go back to local playback). */
+    select: (receiverId: DeviceId | null) => void;
+    /** Start a title on `receiverId`, and drive that TV from now on. */
+    playOn: (receiverId: DeviceId, itemId: ItemId, positionMs?: number) => Promise<CastFailure | null>;
+    /** Send an order to the active receiver. */
+    send: (command: CastCommand) => Promise<CastFailure | null>;
+    /** The last failure, or `cast.kicked` where the television let this remote go,
+     * which is not a failure exactly. Cleared on the next success. */
+    error: CastFailure | 'cast.kicked' | null;
+}
+declare const CastCtx: import("react").Context<Cast | null>;
+/** The cast session. Outside a provider it reads as "no TVs", so a screen can
+ * use it unconditionally on a client that never mounted one. */
+export declare function useCast(): Cast;
+export { CastCtx };

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

@@ -0,0 +1,23 @@
+import type { DeviceId } from '@kromatv/client';
+import type { CastReceiver } from '@kromatv/client/cast';
+import type { ServerEvent } from '@kromatv/client/events';
+import type { Dispatch, SetStateAction } from 'react';
+import type { Cast } from './cast-context';
+import type { PositionBase } from './cast-position';
+/** The state a [`applyCastEvent`] fold writes through. Grouped rather than
+ * passed positionally: four same-shaped setters in a row is an argument list
+ * nobody can read, and two of them are only touched by one event. */
+interface CastEventSetters {
+    receivers: Dispatch<SetStateAction<CastReceiver[]>>;
+    activeId: Dispatch<SetStateAction<DeviceId | null>>;
+    error: Dispatch<SetStateAction<Cast['error']>>;
+    base: Dispatch<SetStateAction<PositionBase | null>>;
+}
+/** Fold one bus event into the roster / position state.
+ *
+ * At module scope rather than inside the effect: rows arrive whole (a play or
+ * pause on one TV costs every sender a patch instead of a refetch), and keeping
+ * the fold here means the effect stays a flat wiring step.
+ */
+declare function applyCastEvent(e: ServerEvent, set: CastEventSetters): void;
+export { applyCastEvent };