@kromatv/sdk 0.1.39-canary.3579809

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

@@ -0,0 +1,42 @@
+import type { RemoteTransportOptions } from './remote-transport-types';
+import { type Direction } from '@kromatv/spatial-nav';
+import { type NativeSyntheticEvent, type TVKeyEvent } from 'react-native';
+import type { RemoteKey } from '#ui/lib/remote-keys';
+import type { PerfSampler } from './perf';
+type Transport = 'events' | 'host';
+export declare function createRemoteTransport({ enabled }: RemoteTransportOptions): {
+    enabled: boolean;
+    typists: Set<(key: string) => void>;
+    remoteKeys: Set<(key: RemoteKey) => void>;
+    subscribe(handle: (direction: Direction) => void): () => void;
+    stepRing(direction: Direction, from: Transport, perf?: PerfSampler | null): void;
+    postRemoteDirection(direction: Direction): void;
+};
+/** Mounted by <FocusScope>. `on` lets a scope nested inside another opt out:
+ * this posts to EVERY registered navigator, so two live bridges would deliver
+ * each press twice. See <FocusScope>'s `bridge` prop. */
+export declare function useRemoteBridge(on?: boolean): void;
+/** Empty off Android, where `useTVEventHandler` above is the whole story. */
+export interface RemoteHostProps {
+    onKeyDown?: (event: NativeSyntheticEvent<TVKeyEvent>) => void;
+    onKeyUp?: (event: NativeSyntheticEvent<TVKeyEvent>) => void;
+}
+/** Spread by <FocusRoot>. `on` takes <FocusScope>'s `bridge`: the key events
+ * BUBBLE, so a scope nested inside another must not carry a second host or one
+ * press walks the ring twice. */
+export declare function useRemoteHostProps(on?: boolean): RemoteHostProps;
+/**
+ * Delivers hardware-keyboard keystrokes (e.g. a Bluetooth keyboard on Android TV)
+ * to whoever is collecting text; directions are consumed above and never reach
+ * here. Deliberately not wired to the `physicalKeyboard` capability, which swaps
+ * in a native `TextInput` and would summon the platform IME over the on-screen
+ * keyboard the remote still needs.
+ */
+export declare function useHardwareKeys(handle: (key: string) => void): void;
+/**
+ * Delivers d-pad presses to a chrome driving its own virtual focus (the
+ * player): the Android mirror of the `useTVEventHandler` the player reads on
+ * tvOS. Same effect-event identity trick as {@link useHardwareKeys}.
+ */
+export declare function useRemoteKeys(handle: (key: RemoteKey) => void): void;
+export {};

package/types/ui/src/lib/focus-remote.web.d.ts

@@ -0,0 +1,13 @@
+import type { RemoteTransportOptions } from './remote-transport-types';
+import { type Direction } from '@kromatv/spatial-nav';
+export declare function createRemoteTransport({ enabled, probe, mirror }: RemoteTransportOptions): {
+    subscribe(handle: (direction: Direction) => void): () => void;
+    postRemoteDirection(direction: Direction): void;
+    enabled: boolean;
+};
+/** A screen records its own remote latency through its app's sampler. */
+export declare function useRemoteBridge(on?: boolean): void;
+/** Nothing to subscribe to: a browser shell already reads its hardware keyboard
+ * from `document` (see @kromatv/tv's `usePhysicalTyping`). Kept so the on-screen
+ * keyboard can call the same hook on every target. */
+export declare function useHardwareKeys(_handle: (key: string) => void): void;

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+type Report = () => void;
+/** Called by `<Focusable>` when it takes the focus. */
+declare function useFocusReport(): Report | null;
+type ReporterProps = Readonly<{
+    children: ReactNode;
+} & ({
+    onFocus: Report;
+    index?: undefined;
+} | {
+    onFocus: (index: number) => void;
+    index: number;
+})>;
+/** Wrap one row item so its focus is reported without passing an index down.
+ *  With `index`, the handler is shared by every item and the reporter binds it,
+ *  so the context value stays put across re-renders of the row. */
+declare function FocusReporter(props: ReporterProps): import("react").JSX.Element;
+export { FocusReporter, useFocusReport };

package/types/ui/src/lib/focus-root.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface FocusRootProps {
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    /** Whether this navigator answers the remote at all. False for a scope that
+     *  is mounted but not in play - a parked sheet, say - whose nodes must stay
+     *  registered, in the order they registered, without taking presses meant for
+     *  something else. */
+    active?: boolean;
+    /** Whether to draw the key host below. False while a platform chrome owns the
+     *  television's focus, which is Apple TV's search screen and nothing else
+     *  (see focus-platform), and false wherever `bridge` is. */
+    keyHost?: boolean;
+    /** Whether this root carries the Android key transport. Default true; false
+     *  for a scope that reuses another root's, whose second host would deliver
+     *  each press again on the way up. See {@link ScreenScopeProps.bridge}. */
+    bridge?: boolean;
+    /** A direction the navigator handled with nothing to move to. */
+    onEdge?: (direction: string) => void;
+}
+export declare function FocusRoot({ children, style, active, keyHost, bridge, onEdge, }: Readonly<FocusRootProps>): import("react").JSX.Element;

package/types/ui/src/lib/focus-root.web.d.ts

@@ -0,0 +1,3 @@
+import type { FocusRootProps } from './focus-root';
+export type { FocusRootProps };
+export declare function FocusRoot({ children, active, onEdge }: Readonly<FocusRootProps>): import("react").JSX.Element;

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

@@ -0,0 +1,50 @@
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+interface FocusScopeProps {
+    children: ReactNode;
+    /** Applied to the screen's own box; the web root renders no element (see focus-root). */
+    style?: StyleProp<ViewStyle>;
+}
+interface ScreenScopeProps extends FocusScopeProps {
+    /** Names the SCREEN inside a scope that outlives it (e.g. persistent nav
+     *  chrome), so it re-decides where focus opens on each arrival instead of on
+     *  its own mount. Omit for the usual case: one scope per screen. */
+    entryKey?: string | number;
+    /**
+     * Mount this scope's remote transports. Default true; a scope that reuses
+     * another root's passes `false`: the event bridge fans to every registered
+     * navigator, so a second one would deliver each press twice. An
+     * `<OverlayHost>` dialog reuses the screen's, a `<Modal>`-backed one is in
+     * its own view controller and needs its own. Reusing means leaving the
+     * platform focus behind as well; see {@link FocusRootProps.keyHost}.
+     */
+    bridge?: boolean;
+    /** Whether this scope answers the remote. See {@link FocusRootProps.active}. */
+    active?: boolean;
+}
+interface FocusColumnProps extends FocusScopeProps {
+    grid?: boolean;
+}
+declare function FocusScope(props: Readonly<ScreenScopeProps>): import("react").JSX.Element;
+/**
+ * Locks the navigator this component sits in out of the remote while `active`.
+ * Called from OUTSIDE the scope it protects, so it locks the screen rather
+ * than the dialog opened over it.
+ */
+declare function useLockFocusBehind(active: boolean): void;
+/**
+ * A group of controls that belong together on one line: the nav bar, a
+ * hero's buttons, a rail. The navigator moves between groups vertically and
+ * inside a group horizontally; nothing measures anything, the shape comes
+ * from the tree.
+ */
+declare function FocusRegion({ children, style }: Readonly<FocusScopeProps>): import("react").JSX.Element;
+/**
+ * A group of controls stacked one above the other: a list of servers, an
+ * on-screen keyboard. `grid` makes a stack of `<FocusRegion>` rows behave as a
+ * grid: without it, moving down lands on each row's last-focused key (Down
+ * from T lands on A); with it, the navigator keeps the column position.
+ */
+declare function FocusColumn({ children, style, grid }: Readonly<FocusColumnProps>): import("react").JSX.Element;
+export type { FocusColumnProps, FocusScopeProps, ScreenScopeProps };
+export { FocusColumn, FocusRegion, FocusScope, useLockFocusBehind };

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

@@ -0,0 +1,42 @@
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+type Reveal = 'start' | 'nearest';
+interface FocusScrollProps {
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    contentStyle?: StyleProp<ViewStyle>;
+    /** Under `start`, where a revealed row rests below the top edge. Under
+     *  `nearest`, the room kept between the row and whichever edge it came in
+     *  from. */
+    offsetFromStart?: number;
+    /** `start` (the default) is a television's page: every revealed row comes to
+     *  rest at the same height. `nearest` is a list: the page moves only as far
+     *  as showing the row whole takes. */
+    reveal?: Reveal;
+    /** Called when the page leaves or returns to its start. */
+    onScrolledChange?: (scrolled: boolean) => void;
+}
+declare function FocusScroll(props: Readonly<FocusScrollProps>): import("react").JSX.Element;
+/**
+ * One rail, scrolled sideways by the focus. A rail inside a page leaves both
+ * live at once, and a control asks both (see {@link useRevealOnFocus}).
+ */
+declare function FocusRail(props: Readonly<FocusScrollProps>): import("react").JSX.Element;
+/**
+ * One row of a page: a place in the navigator's order fixed at first render
+ * (rows mount out of visual order), and what the page scrolls to.
+ */
+declare function FocusSlot({ children, onActive, }: Readonly<{
+    children: ReactNode;
+    onActive?: () => void;
+}>): import("react").JSX.Element;
+/**
+ * One line of a taller row, wrapped in a line-sized scroll anchor inside the
+ * slot: no navigator node, no change to the order, finer scroll granularity.
+ */
+declare function FocusLine({ children, style, }: Readonly<{
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+}>): import("react").JSX.Element;
+export type { FocusScrollProps, Reveal };
+export { FocusLine, FocusRail, FocusScroll, FocusSlot };

package/types/ui/src/lib/focus-services-context.d.ts

@@ -0,0 +1,99 @@
+export declare const FocusServicesProvider: import("react").Provider<{
+    enabled: boolean;
+    input: {
+        armPressGuard(ms?: number): void;
+        pressGuardActive: () => boolean;
+        clearPressGuard(): void;
+        holdInput(): () => void;
+        inputHeld: () => boolean;
+        clearInputHolds(): void;
+    };
+    source: {
+        pointerDriving: () => boolean;
+        retain(): () => void;
+    };
+    probe: {
+        noteFocus: (_view: unknown) => void;
+        seq: () => number;
+        box: () => import("./focus-here").FocusBox | null;
+    };
+    mirror: {
+        mirrorFocus(_view: unknown): void;
+        isMirrored(_element: unknown): boolean;
+        redeliverKey(_event: unknown): void;
+    };
+    remote: {
+        enabled: boolean;
+        typists: Set<(key: string) => void>;
+        remoteKeys: Set<(key: import("./remote-keys").RemoteKey) => void>;
+        subscribe(handle: (direction: import("@kromatv/spatial-nav").Direction) => void): () => void;
+        stepRing(direction: import("@kromatv/spatial-nav").Direction, from: "events" | "host", perf?: import("./perf").PerfSampler | null): void;
+        postRemoteDirection(direction: import("@kromatv/spatial-nav").Direction): void;
+    };
+} | null>;
+export declare const useFocusServicesParent: () => {
+    enabled: boolean;
+    input: {
+        armPressGuard(ms?: number): void;
+        pressGuardActive: () => boolean;
+        clearPressGuard(): void;
+        holdInput(): () => void;
+        inputHeld: () => boolean;
+        clearInputHolds(): void;
+    };
+    source: {
+        pointerDriving: () => boolean;
+        retain(): () => void;
+    };
+    probe: {
+        noteFocus: (_view: unknown) => void;
+        seq: () => number;
+        box: () => import("./focus-here").FocusBox | null;
+    };
+    mirror: {
+        mirrorFocus(_view: unknown): void;
+        isMirrored(_element: unknown): boolean;
+        redeliverKey(_event: unknown): void;
+    };
+    remote: {
+        enabled: boolean;
+        typists: Set<(key: string) => void>;
+        remoteKeys: Set<(key: import("./remote-keys").RemoteKey) => void>;
+        subscribe(handle: (direction: import("@kromatv/spatial-nav").Direction) => void): () => void;
+        stepRing(direction: import("@kromatv/spatial-nav").Direction, from: "events" | "host", perf?: import("./perf").PerfSampler | null): void;
+        postRemoteDirection(direction: import("@kromatv/spatial-nav").Direction): void;
+    };
+} | null;
+export declare function useFocusServices(): {
+    enabled: boolean;
+    input: {
+        armPressGuard(ms?: number): void;
+        pressGuardActive: () => boolean;
+        clearPressGuard(): void;
+        holdInput(): () => void;
+        inputHeld: () => boolean;
+        clearInputHolds(): void;
+    };
+    source: {
+        pointerDriving: () => boolean;
+        retain(): () => void;
+    };
+    probe: {
+        noteFocus: (_view: unknown) => void;
+        seq: () => number;
+        box: () => import("./focus-here").FocusBox | null;
+    };
+    mirror: {
+        mirrorFocus(_view: unknown): void;
+        isMirrored(_element: unknown): boolean;
+        redeliverKey(_event: unknown): void;
+    };
+    remote: {
+        enabled: boolean;
+        typists: Set<(key: string) => void>;
+        remoteKeys: Set<(key: import("./remote-keys").RemoteKey) => void>;
+        subscribe(handle: (direction: import("@kromatv/spatial-nav").Direction) => void): () => void;
+        stepRing(direction: import("@kromatv/spatial-nav").Direction, from: "events" | "host", perf?: import("./perf").PerfSampler | null): void;
+        postRemoteDirection(direction: import("@kromatv/spatial-nav").Direction): void;
+    };
+};

package/types/ui/src/lib/focus-services.d.ts

@@ -0,0 +1,45 @@
+/** A host owns its geometry, DOM mirror and remote subscribers. */
+export declare function createFocusServices(enabled?: boolean, input?: {
+    armPressGuard(ms?: number): void;
+    pressGuardActive: () => boolean;
+    clearPressGuard(): void;
+    holdInput(): () => void;
+    inputHeld: () => boolean;
+    clearInputHolds(): void;
+}, source?: {
+    pointerDriving: () => boolean;
+    retain(): () => void;
+}): {
+    enabled: boolean;
+    input: {
+        armPressGuard(ms?: number): void;
+        pressGuardActive: () => boolean;
+        clearPressGuard(): void;
+        holdInput(): () => void;
+        inputHeld: () => boolean;
+        clearInputHolds(): void;
+    };
+    source: {
+        pointerDriving: () => boolean;
+        retain(): () => void;
+    };
+    probe: {
+        noteFocus: (_view: unknown) => void;
+        seq: () => number;
+        box: () => import("./focus-here").FocusBox | null;
+    };
+    mirror: {
+        mirrorFocus(_view: unknown): void;
+        isMirrored(_element: unknown): boolean;
+        redeliverKey(_event: unknown): void;
+    };
+    remote: {
+        enabled: boolean;
+        typists: Set<(key: string) => void>;
+        remoteKeys: Set<(key: import("./remote-keys").RemoteKey) => void>;
+        subscribe(handle: (direction: import("@kromatv/spatial-nav").Direction) => void): () => void;
+        stepRing(direction: import("@kromatv/spatial-nav").Direction, from: "events" | "host", perf?: import("./perf").PerfSampler | null): void;
+        postRemoteDirection(direction: import("@kromatv/spatial-nav").Direction): void;
+    };
+};
+export type FocusServices = ReturnType<typeof createFocusServices>;

package/types/ui/src/lib/focus-shield.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface FocusShieldProps {
+    children: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    /** Whether the platform focus engine is kept out of the subtree. Only Apple TV
+     *  honours it; elsewhere this is a plain View. */
+    shielded: boolean;
+}
+/** A View whose subtree the television's own focus search never walks. */
+export declare function FocusShield({ children, style }: Readonly<FocusShieldProps>): import("react").JSX.Element;

package/types/ui/src/lib/focus-shield.ios.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentType } from 'react';
+import { type FocusShieldProps } from './focus-shield';
+export type { FocusShieldProps } from './focus-shield';
+/** A View whose subtree the television's own focus search never walks. */
+export declare const FocusShield: ComponentType<FocusShieldProps>;

package/types/ui/src/lib/focus-tab.d.ts

@@ -0,0 +1,12 @@
+import { type Direction } from '@kromatv/spatial-nav';
+import type { FocusBox } from './focus-here';
+/** How the walk watches the focus: a counter to tell a move from a refusal, and
+ *  a box to tell one line from the next. */
+export interface FocusProbe {
+    seq: () => number;
+    box: () => FocusBox | null;
+}
+type Send = (direction: Direction) => void;
+/** Move the focus one control along reading order; `back` for Shift+Tab. */
+export declare function walkTab(send: Send, probe: FocusProbe, back?: boolean): void;
+export {};

package/types/ui/src/lib/focus-transition.d.ts

@@ -0,0 +1,11 @@
+import { type PressScale } from '#ui/lib/press-dip';
+/** An animated `transform: scale()` that eases to `to` while focused. */
+export declare function useFocusScale(focused: boolean, to: number): Record<string, unknown>;
+/**
+ * The design's press dip (`motion.pressScale`): the control shrinks under the
+ * finger, then springs back with a touch of overshoot on release. The touch
+ * half of the focus scale above - a phone PRESSES where a television FOCUSES -
+ * wired by the kit's pressable paths so every control answers the finger the
+ * same way.
+ */
+export declare function usePressScale(): PressScale;

package/types/ui/src/lib/focus-transition.web.d.ts

@@ -0,0 +1,3 @@
+import { type PressScale } from '#ui/lib/press-dip';
+export declare function useFocusScale(focused: boolean, to: number): Record<string, unknown>;
+export declare function usePressScale(): PressScale;

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

@@ -0,0 +1,18 @@
+export interface FocusNavHandlers {
+    /** Remote Back / Escape. Return `false` to say "not handled, keep the
+     *  default"; returning nothing counts as handled. */
+    onBack?: () => void | boolean;
+    /** Remote Play / Pause / PlayPause. */
+    onPlayPause?: () => void;
+    /** Re-run the mount behaviour when this changes (e.g. a view switch). */
+    resetKey?: unknown;
+}
+/** What a control that opts out of platform focus tells the PLATFORM focus
+ * engines: skip me. react-native-tvos gates a Pressable's focusability on
+ * exactly these two (`focusable !== false && isTVSelectable !== false`);
+ * `isTVSelectable` is the tvOS spelling and not in mainline RN's types - see
+ * components/organisms/player/lib/virtual-focus.ts for the bug this prevents. */
+export declare const UNFOCUSABLE: {
+    readonly focusable: false;
+    readonly isTVSelectable: false;
+};

package/types/ui/src/lib/focus-visible.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether the current focus is one the viewer asked for, in the browser's
+ * `:focus-visible` sense: true for keys and the remote, false for a cursor that
+ * merely swept past.
+ *
+ * The spatial navigator focuses on mouse-enter once a pointer has moved and
+ * never blurs on leave, because its model keeps exactly one focus owner. Without
+ * this the amber ring parks on whatever the cursor passed last.
+ *
+ * `focus` identifies WHAT holds the focus, not merely that something does: a
+ * cluster whose selection moves between its own controls has to re-read the
+ * modality on every move, so passing a boolean there would answer for the first
+ * control and never again. A boolean is right where the control is its own
+ * focus owner.
+ *
+ * `<Focusable>` applies this to its ring and to a recipe's `_focus`. Anything
+ * resolving a recipe directly (a control whose focus visuals live on a parent,
+ * or on a `<Box>` that is not itself focusable) must ask here too, or `_focus`
+ * would mean two different things depending on how it was reached.
+ */
+export declare function useFocusVisible(focus: unknown): boolean;
+/** {@link useFocusVisible} for a caller that already holds the input source's `pointerDriving`. */
+export declare function useFocusVisibleBy(focus: unknown, pointerDriving: () => boolean): boolean;

package/types/ui/src/lib/form/index.d.ts

@@ -0,0 +1,4 @@
+export { msg } from './message';
+export type { StandardSchemaV1 } from './standard-schema';
+export type { FieldErrors, Form, FormOptions, TextBinding, ToggleBinding } from './use-form';
+export { useForm } from './use-form';

package/types/ui/src/lib/form/message.d.ts

@@ -0,0 +1,10 @@
+import { type TVars } from '@kromatv/i18n';
+type MessageLookup = (key: string, vars?: TVars) => string;
+/** Packs a message key and its interpolation vars into the single string a validator
+ *  can carry as its error, for `useForm` to unpack again through `t`. */
+declare function msg(key: string, vars?: TVars): string;
+/** Turns a validator's message into display copy: a catalog key when `t` knows it,
+ *  otherwise the message itself, and either way with `msg()`'s vars filled in. */
+declare function resolveMessage(message: string, t?: MessageLookup): string;
+export type { MessageLookup };
+export { msg, resolveMessage };

package/types/ui/src/lib/form/standard-schema.d.ts

@@ -0,0 +1,27 @@
+type StandardPathSegment = PropertyKey | {
+    readonly key: PropertyKey;
+};
+interface StandardIssue {
+    readonly message: string;
+    readonly path?: readonly StandardPathSegment[];
+}
+interface StandardResult<Output> {
+    readonly value?: Output;
+    readonly issues?: readonly StandardIssue[];
+}
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/** The first path segment of an issue, which is the field it belongs to. A whole-object
+ *  check (zod's `.refine()` on the object) has no path and belongs to the form itself. */
+declare function issueField(issue: StandardIssue): string | undefined;
+export type { StandardIssue, StandardSchemaV1 };
+export { issueField };

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

@@ -0,0 +1,59 @@
+import type { Translate } from '@kromatv/i18n';
+import { type StandardSchemaV1 } from './standard-schema';
+type StringKeys<V> = {
+    [K in keyof V]-?: V[K] extends string ? K : never;
+}[keyof V] & string;
+type BooleanKeys<V> = {
+    [K in keyof V]-?: V[K] extends boolean ? K : never;
+}[keyof V] & string;
+type FieldErrors<V> = Partial<Record<keyof V & string, string>>;
+interface TextBinding<T> {
+    /** Spread onto `<Field.Root>`: the value it holds and the message it shows. */
+    root: {
+        value: T;
+        onValueChange: (next: T) => void;
+        error: string | undefined;
+    };
+    /** Spread onto `<Field.Input>` or `<Field.Textarea>`: the return key submits. */
+    input: {
+        onSubmit: () => void;
+    };
+}
+interface ToggleBinding<T> {
+    checked: T;
+    onCheckedChange: (next: T) => void;
+}
+interface FormOptions<Values, Output> {
+    schema: StandardSchemaV1<Values, Output>;
+    defaultValues: Values;
+    onSubmit?: (values: Output) => void | Promise<void>;
+    /** Without one a message is shown as the schema wrote it; with one it is looked
+     *  up as a catalog key first. Pass `useT()`. */
+    t?: Translate;
+}
+interface Form<Values> {
+    values: Values;
+    errors: FieldErrors<Values>;
+    /** A whole-form failure: a check with no field to blame, or a throw from `onSubmit`. */
+    error: string | undefined;
+    submitting: boolean;
+    submitted: boolean;
+    field: <K extends StringKeys<Values>>(name: K) => TextBinding<Values[K]>;
+    toggle: <K extends BooleanKeys<Values>>(name: K) => ToggleBinding<Values[K]>;
+    setValue: <K extends keyof Values & string>(name: K, next: Values[K]) => void;
+    setError: (name: keyof Values & string, message?: string) => void;
+    reset: (next?: Partial<Values>) => void;
+    submit: () => Promise<void>;
+}
+/**
+ * A form over any Standard Schema validator (zod, valibot, arktype): it holds the
+ * values, runs the schema and hands each control the props it needs, so a screen
+ * writes the schema and the layout and nothing in between.
+ *
+ * Errors stay quiet until the first submit, then track every keystroke. Each one
+ * is resolved through `t`, so a schema that says `msg('form.tooShort', { min: 8 })`
+ * is translated wherever it is shown.
+ */
+declare function useForm<Values extends Record<string, unknown>, Output>({ schema, defaultValues, onSubmit, t, }: FormOptions<Values, Output>): Form<Values>;
+export type { FieldErrors, Form, FormOptions, TextBinding, ToggleBinding };
+export { useForm };

package/types/ui/src/lib/frost-coat-types.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { FrostLayer } from './gl-frost/context';
+import type { ViewStyle } from 'react-native';
+/** The two halves of a frost. Spread `style` onto the surface's own style list
+ *  and render `layer` as its first child; exactly one of them is ever set. */
+export interface FrostCoat {
+    style: ViewStyle | null;
+    layer: ReactNode;
+}
+/** The coat of a surface that wears no frost. */
+export declare const BARE: FrostCoat;
+/** Where a frost may come from: the layer under the surface, if any, and
+ *  whether that layer is the only source the kit allows. */
+export interface FrostReach {
+    layer: FrostLayer | null;
+    layerOnly: boolean;
+}

package/types/ui/src/lib/frost-coat.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentType } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type StyleScope } from '#ui/core';
+import type { FrostBackdropProps } from '#ui/components/atoms/frost';
+import { type FrostCoat, type FrostReach } from './frost-coat-types';
+/** A registered platform blur drawn as the surface's first layer, clipped to its corner. */
+export declare function frostCoat(surface: StyleProp<ViewStyle>, amount: number, tint: string | undefined, Backdrop: ComponentType<FrostBackdropProps> | null, scope: StyleScope, reach: FrostReach): FrostCoat;

package/types/ui/src/lib/frost-coat.web.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentType } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { type StyleScope } from '#ui/core';
+import type { FrostBackdropProps } from '#ui/components/atoms/frost';
+import { type FrostCoat, type FrostReach } from './frost-coat-types';
+/** The frost layer's mark where the surface sits on one; else nothing where the
+ *  kit allows only a layer, else a CSS backdrop blur, one shared coat per strength. */
+export declare function frostCoat(_surface: StyleProp<ViewStyle>, amount: number, _tint: string | undefined, _backdrop: ComponentType<FrostBackdropProps> | null, scope: StyleScope, reach: FrostReach): FrostCoat;

package/types/ui/src/lib/fuzzy-search.d.ts

@@ -0,0 +1,20 @@
+/** The query as the matcher reads it: lower-cased, with the separators dropped.
+ * Empty means there is nothing to match on, and everything is a hit. */
+declare function fuzzyQuery(query: string): string;
+/** How well `query` matches `text`, higher being better, or `null` when the
+ * query's letters are not all present in order. Separators in the query are
+ * ignored, so `player pause` scores as `playerpause` does. An empty query
+ * scores 0 against anything. */
+declare function fuzzyScore(text: string, query: string): number | null;
+/** One candidate the query matched, and how well. */
+interface FuzzyHit<T extends string> {
+    text: T;
+    score: number;
+}
+/** The candidates `query` matches, best first: a contiguous run, a match on a
+ * word boundary and a match nearer the start all score higher. A tie goes to
+ * the shorter candidate, then to the order given. An empty query returns every
+ * candidate in the order given, each scoring 0. */
+declare function fuzzySearch<T extends string>(candidates: readonly T[], query: string): FuzzyHit<T>[];
+export type { FuzzyHit };
+export { fuzzyQuery, fuzzyScore, fuzzySearch };

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

@@ -0,0 +1,4 @@
+import { type IconName } from '#ui/lib/glyph';
+/** The icon for a genre SLUG, or `undefined` when the table has none for it,
+ * or the build's glyph subset does not ship the one it names. */
+export declare function genreIcon(slug: string): IconName | undefined;

package/types/ui/src/lib/gl-frost/context.d.ts

@@ -0,0 +1,15 @@
+/** What a frost layer offers the surfaces and scrollers drawn over it. */
+export interface FrostLayer {
+    /** Draws the frost under the element `mark` sits in, until the returned call. */
+    register(mark: HTMLElement): () => void;
+    /** Scrolls `scroller` (a ScrollView ref) to `offset` in step with the frost;
+     *  false where the layer cannot, and the caller scrolls it itself. */
+    glide(scroller: unknown, horizontal: boolean, offset: number): boolean;
+}
+/** The frost layer of the nearest `<FrostSource>` that draws one. */
+export declare const FrostLayerContext: import("react").Context<FrostLayer | null>;
+/** The frost layer under this surface: its `<FrostSource>`'s, else the one the
+ *  app draws now, else null where no layer draws the frost. */
+export declare function useFrostLayer(): FrostLayer | null;
+/** Where a scroller asks its `<FrostSource>` to glide it; never the app's. */
+export declare function useFrostGlide(): FrostLayer | null;

package/types/ui/src/lib/gl-frost/engine.web.d.ts

@@ -0,0 +1,19 @@
+import type { FrostLayer } from './context';
+import { type FrostArt } from './renderer';
+/** The art a frost layer draws, as loaded pictures, and how it sits. */
+export interface FrostPicture extends FrostArt {
+    at: {
+        x: number;
+        y: number;
+    };
+    amount: number;
+}
+/** A frost layer bound to one canvas: what the surfaces use, plus its owner's controls. */
+export interface FrostEngine extends FrostLayer {
+    show(picture: FrostPicture | null): void;
+    dispose(): void;
+}
+/** Draws a screen's backdrop into `canvas` and the frost of every registered
+ *  surface over it, in the same frame those surfaces move. `onReady` hears
+ *  whether the canvas now carries the backdrop. */
+export declare function createFrostEngine(canvas: HTMLCanvasElement, root: HTMLElement, onReady: (ready: boolean) => void): FrostEngine;