@kromatv/sdk 0.1.40-canary.0

package/types/ui/src/lib/press-dip.d.ts

@@ -0,0 +1,26 @@
+import type { LayoutChangeEvent } from 'react-native';
+export declare function pressScaleFor(longest: number): number;
+export declare function longestSideOf(event: LayoutChangeEvent): number;
+/** The control's longest side, kept current by the `onLayout` it hands back.
+ *  A ref rather than state: the size only matters at the moment of a press, and
+ *  a re-render on every layout pass would cost every tile in a grid. */
+export declare function useLongestSide(): {
+    longest: {
+        current: number;
+    };
+    onLayout: (event: LayoutChangeEvent) => void;
+};
+/** What both halves of the press dip hand back; the animation itself is the
+ *  platform's (Animated on native, a CSS transition on the web). A control that
+ *  does not dip hands back no `onLayout`: there is no size to read. */
+export interface PressScale {
+    pressed: boolean;
+    style: Record<string, unknown>;
+    onLayout?: (event: LayoutChangeEvent) => void;
+    onPressIn: () => void;
+    onPressOut: () => void;
+}
+/** The dip, off: the control reports its press and never sinks, so it costs
+ *  neither an animated value nor a layout read. For a screen that FOCUSES
+ *  rather than presses. */
+export declare function useFlatPress(): PressScale;

package/types/ui/src/lib/press-guard.d.ts

@@ -0,0 +1,8 @@
+/** Default window, in milliseconds. */
+export declare const PRESS_GUARD_MS = 300;
+/** Arm the guard. Called by every screen's `useFocusNav` on mount. */
+export declare function armPressGuard(ms?: number): void;
+/** True while a press should be swallowed as the tail of the previous screen's. */
+export declare function pressGuardActive(): boolean;
+/** Test seam: drop the guard so a press lands immediately. */
+export declare function clearPressGuard(): void;

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

@@ -0,0 +1,11 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { RingGeometry } from '#ui/lib/ring';
+export interface ProgressFillProps {
+    value: number;
+    style: StyleProp<ViewStyle>;
+}
+/** The arc of a <ProgressRing>, easing to a new length when the value changes. */
+export declare function ProgressArc({ centre, radius, thickness, fill, circumference, dashOffset, }: Readonly<RingGeometry>): import("react").JSX.Element;
+/** The fill of a <Progress> track, easing to `value` (0..1). `style` paints it
+ *  and pins it to the track's left edge; the trailing inset is this component's. */
+export declare function ProgressFill({ value, style }: Readonly<ProgressFillProps>): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { RingGeometry } from '#ui/lib/ring';
+export interface ProgressFillProps {
+    value: number;
+    style: StyleProp<ViewStyle>;
+}
+/** The arc of a <ProgressRing>, easing to a new length when the value changes. */
+export declare function ProgressArc({ centre, radius, thickness, fill, circumference, dashOffset, }: Readonly<RingGeometry>): import("react").JSX.Element;
+/** The fill of a <Progress> track, easing to `value` (0..1). `style` paints it
+ *  and pins it to the track's left edge; the trailing inset is this component's. */
+export declare function ProgressFill({ value, style }: Readonly<ProgressFillProps>): import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+/**
+ * True when motion should be dropped rather than merely shortened. Starts false
+ * and settles on the first answer, since the platform only reports the setting
+ * asynchronously: an animation that fires on mount plays once before the answer
+ * arrives.
+ */
+export declare function useReducedMotion(): boolean;

package/types/ui/src/lib/report-categories.d.ts

@@ -0,0 +1,10 @@
+import type { ReportCategory } from '@kroma/client/reports';
+import type { MessageKey } from '@kroma/core';
+import type { IconName } from './glyph';
+export interface ReportCategoryMeta {
+    key: ReportCategory;
+    labelKey: MessageKey;
+    hintKey: MessageKey;
+    icon: IconName;
+}
+export declare const REPORT_CATEGORIES: readonly ReportCategoryMeta[];

package/types/ui/src/lib/ring-room.d.ts

@@ -0,0 +1,27 @@
+interface RingRoom {
+    marginBlock?: number;
+    paddingBlock?: number;
+    marginInline?: number;
+    paddingInline?: number;
+    scrollPadding: number;
+}
+/**
+ * Vertical room for a focus ring inside an element that scrolls or clips: the
+ * box reaches `RING_ROOM` further out and its content is padded back in by the
+ * same amount, so the content lands exactly where it did with room around it
+ * for a ring. `inset` is the padding that edge already carried, and the reach is
+ * measured from it, so nothing moves.
+ *
+ * A scroller clips at its own edges and the ring stands OUTSIDE the control it
+ * marks, so a control flush with an edge loses that side of its ring - the first
+ * season chip under a show, every time. `scroll-padding` says the same thing for
+ * the control the scroller brings into view, where the room has scrolled away.
+ *
+ * An element that IS a card around its rows - its own edge and fill, clipping
+ * them - has no outside to reach into: its rows take the inset ring instead
+ * (`ring: 'focusInset'`, as `<ListRow.Group>`'s members do).
+ */
+export declare function ringRoomBlock(inset?: number): RingRoom;
+/** The same room on the other axis. See {@link ringRoomBlock}. */
+export declare function ringRoomInline(inset?: number): RingRoom;
+export {};

package/types/ui/src/lib/ring-scope.d.ts

@@ -0,0 +1,6 @@
+import type { RingToken } from '#ui/core/theme';
+/** Provided by a surface that clips what it holds; never used directly. */
+declare const RingScopeProvider: import("react").Provider<"focus" | "focusEdge" | "focusGlow" | "focusGlowSm" | "focusInset" | "focusLift" | "focusSm" | "focusWash" | undefined>;
+/** The ring every control in this subtree draws, unless it asks for another. */
+declare function useRingScope(): RingToken | undefined;
+export { RingScopeProvider, useRingScope };

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

@@ -0,0 +1,27 @@
+export interface RingProps {
+    /** Fill fraction, 0..1 (clamped). */
+    value?: number;
+    /** Outer diameter. */
+    size?: number;
+    thickness?: number;
+    track?: string;
+    fill?: string;
+}
+export interface RingGeometry {
+    size: number;
+    thickness: number;
+    track: string;
+    fill: string;
+    centre: number;
+    radius: number;
+    circumference: number;
+    /** How much of the circumference to hide, i.e. the unfilled remainder. */
+    dashOffset: number;
+}
+export declare function ringGeometry({ value, size, thickness, track, fill, }: Readonly<RingProps>): RingGeometry;
+/** SVG draws an arc from 3 o'clock; the design starts it at 12. */
+export declare const RING_ROTATION = "-90deg";
+/** What an indeterminate ring draws instead of a fill: a quarter of the
+ *  circumference, spun rather than grown. */
+export declare const RING_BUSY_ARC = 0.25;
+export declare const RING_SPIN_MS = 900;

package/types/ui/src/lib/sample-art.d.ts

@@ -0,0 +1,9 @@
+/** Portrait artwork, 2:3, for posters. */
+declare const POSTER_ART: readonly ["https://picsum.photos/seed/kroma-poster-1/300/450", "https://picsum.photos/seed/kroma-poster-2/300/450", "https://picsum.photos/seed/kroma-poster-3/300/450", "https://picsum.photos/seed/kroma-poster-4/300/450", "https://picsum.photos/seed/kroma-poster-5/300/450", "https://picsum.photos/seed/kroma-poster-6/300/450"];
+/** Landscape artwork, 16:9, for thumbnails, hero backdrops and `<Img>`. */
+declare const STILL_ART: readonly ["https://picsum.photos/seed/kroma-still-1/640/360", "https://picsum.photos/seed/kroma-still-2/640/360", "https://picsum.photos/seed/kroma-still-3/640/360", "https://picsum.photos/seed/kroma-still-4/640/360", "https://picsum.photos/seed/kroma-still-5/640/360", "https://picsum.photos/seed/kroma-still-6/640/360"];
+/** Stable pick, so a story that renders a grid gets variety without randomness
+ * (and so two runs of the screenshot script frame the same images). */
+declare function posterArt(at: number): string;
+declare function stillArt(at: number): string;
+export { POSTER_ART, posterArt, STILL_ART, stillArt };

package/types/ui/src/lib/scroll-lock.d.ts

@@ -0,0 +1 @@
+export declare function useScrollLock(_locked: boolean): void;

package/types/ui/src/lib/scroll-lock.web.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Freeze the page behind an overlay while `locked`, and give it back when the
+ * overlay closes or unmounts. Reference-counted: the inner of two open
+ * overlays releases nothing while the outer still holds the page.
+ */
+export declare function useScrollLock(locked: boolean): void;

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

@@ -0,0 +1,8 @@
+import { Animated, type ViewStyle } from 'react-native';
+/**
+ * A transform that shakes once every time `at` changes, and nothing at all on
+ * the first render or under reduced motion. Pass a count of refusals; the value
+ * itself is never read. The result belongs on an `Animated.View`: it carries an
+ * `Animated.Value`.
+ */
+export declare function useShake(at: number): Animated.WithAnimatedValue<ViewStyle>;

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

@@ -0,0 +1,4 @@
+import type { Animated, ViewStyle } from 'react-native';
+/** A transform that shakes once every time `at` changes, and nothing at all on
+ * the first render or under reduced motion. */
+export declare function useShake(at: number): Animated.WithAnimatedValue<ViewStyle>;

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

@@ -0,0 +1,36 @@
+import { type ReactElement, type ReactNode } from 'react';
+type AnyProps = Record<string, unknown>;
+/** The slot's props and the child's, merged under the rules above. For a kit
+ * component that merges without rendering a <Slot> element; the shells reach
+ * this through `<Slot>` itself. */
+declare function mergeSlotProps(slotProps: AnyProps, childProps: AnyProps): AnyProps;
+interface SlotProps {
+    /** Exactly one element. Text, a fragment or a list is a real mistake: there
+     *  is no single child to become. */
+    children: ReactNode;
+    [prop: string]: unknown;
+}
+/**
+ * Renders its props onto its one child. The building block behind every
+ * `asChild` prop in the kit: `<Box asChild>` is `<Slot {...boxProps}>`.
+ *
+ * ```tsx
+ * <Slot style={s.well} onPress={open}>
+ *   <Pressable onPress={track} style={s.tile} />
+ * </Slot>
+ * // one <Pressable style={[s.well, s.tile]}> that calls track, then open
+ * ```
+ */
+declare function Slot({ children, ...slotProps }: Readonly<SlotProps>): ReactElement<AnyProps, string | import("react").JSXElementConstructor<any>>;
+/**
+ * The same merge, onto an element a control took as its host: `asChild` on a
+ * control goes through here rather than through `<Slot>`, because the control
+ * has already put its own face inside the element.
+ *
+ * `style` lands flattened, alone among the props. A router's link spreads the
+ * style it is handed into its own active-state style, and spreading an array
+ * yields `{ 0: …, 1: … }`.
+ */
+declare function cloneHost(host: ReactElement, props: AnyProps): ReactElement;
+export type { SlotProps };
+export { cloneHost, mergeSlotProps, Slot };

package/types/ui/src/lib/sort-icon.d.ts

@@ -0,0 +1,5 @@
+import type { SortMode } from '@kroma/core';
+import type { IconName } from '#ui/lib/glyph';
+/** The glyph for a catalogue sort, so the same order reads the same on the web,
+ *  on a phone and across a room. */
+export declare const SORT_ICON: Record<SortMode, IconName>;

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;
+    /** One leg of the round trip, 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, out and back, forever. 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,15 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { DriftSpec } from './splash-motion';
+/**
+ * The drift for the artwork layer: a slow pan across a frame held oversized for
+ * it, out and back, forever. 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/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,17 @@
+/**
+ * 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'>;
+/** The shell's answer for every anchored surface in it. Call once at startup;
+ *  a surface's own `presentation` still wins, and `auto` hands the question
+ *  back to the platform. */
+declare function setSurfacePresentation(presentation: SurfacePresentation): void;
+/** 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 { setSurfacePresentation, useSurfacePresentation };

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

@@ -0,0 +1,21 @@
+type SurfaceWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * 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, and what its `pad` defaults to. */
+export declare const DIALOG_PAD = 40;
+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,7 @@
+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(): boolean;
+export declare function writeThemeMuted(muted: boolean): void;

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

@@ -0,0 +1,11 @@
+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;
+export declare function holdMenuKey(): void;
+export declare function releaseMenuKey(): void;

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-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-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/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/services/aiSuggest.d.ts

@@ -0,0 +1,15 @@
+import type { KromaClient } from '@kroma/client';
+import type { ItemId, Section } from '@kroma/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 while generating / waiting to start; false once terminal. */
+    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 KromaClient } from '@kroma/client';
+import { type AuthResult, type StoredSession, type User, type UserId } from '@kroma/client/accounts';
+/** 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,33 @@
+import type { DeviceId } from '@kroma/client';
+import type { CastCommand, CastReceiver } from '@kroma/client/cast';
+import type { ItemId } from '@kroma/client/media';
+import type { DiscoveredTv } from '@kroma/core';
+/** 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<boolean>;
+    /** Send an order to the active receiver. False when it failed / went away. */
+    send: (command: CastCommand) => Promise<boolean>;
+    /** The last failure, as a message key, or null. Cleared on the next success.
+     * `cast.kicked` is not a failure exactly - the TV chose to let this remote go. */
+    error: 'cast.gone' | 'cast.failed' | '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 '@kroma/client';
+import type { CastReceiver } from '@kroma/client/cast';
+import type { ServerEvent } from '@kroma/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 };

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

@@ -0,0 +1,21 @@
+import type { DiscoveredTv, LanDiscoveryBridge } from '@kroma/core';
+export interface LanCastOptions {
+    /** This device's DNS-SD stack, when it has one. Absent everywhere else, and
+     * everything below then reports nothing. */
+    lan?: LanDiscoveryBridge;
+    /** Gates on being signed in, like the roster it accelerates. */
+    enabled: boolean;
+    /** Called when a signed-in television is heard that the roster has not
+     * listed. The provider answers by refetching. */
+    onUnknownReceiver: () => void;
+    /** Whether the roster already knows a receiver id. Read at call time, so a
+     * roster change does not restart the browse. */
+    knowsReceiver: (receiverId: string) => boolean;
+}
+/** The signed-out televisions in the room, and a nudge to refetch when a
+ * signed-in one turns up that the server has not mentioned yet.
+ *
+ * Listens only while the app is in front: the browse is a multicast listener,
+ * and on Android a worker thread with it, so a phone in a pocket would
+ * otherwise pay for it for the whole signed-in session. */
+export declare function useLanCast(opts: LanCastOptions): DiscoveredTv[];