@kromatv/sdk 0.1.39-canary.3579809

package/types/ui/src/lib/player/sheet-slide.web.d.ts

@@ -0,0 +1,5 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+/** The sheet's transform: home when `open`, parked `by` pixels down the screen
+ * when not. Plain styles, so it rides on the `Animated.View` the native half
+ * needs. */
+export declare function useSheetSlide(open: boolean, by: number): StyleProp<ViewStyle>;

package/types/ui/src/lib/player/stage-ratio.d.ts

@@ -0,0 +1,4 @@
+/** The stage's width / height. A native shell IS the screen it draws on, so what
+ * the chrome measured of the window already is the stage's own shape. See the
+ * `.web` half for why a browser cannot assume that. */
+export declare function useStageRatio(_stageId: string, measured: number): number;

package/types/ui/src/lib/player/stage-ratio.web.d.ts

@@ -0,0 +1,2 @@
+/** The stage's width / height, read off the element the chrome draws on. */
+export declare function useStageRatio(stageId: string, measured: number): number;

package/types/ui/src/lib/player/stage-zoom.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import { Animated } from 'react-native';
+import type { StageCard } from '#ui/components/organisms/player/lib/stage-card';
+/** The settings card's corner radius, in canvas pixels. */
+export declare const CARD_RADIUS = 72;
+/** The radius the picture's box may round itself to: 0 where a rounded clip
+ * would cost the video its surface, and the mask cuts the corners instead. */
+export declare function cardCorner(radius: number): number;
+/** The stage's shrink progress, 0 full screen to 1 on the card. On the UI
+ * thread: a scale is one of the two properties the native driver takes, and the
+ * slowest box we support cannot spare a JS frame per frame. `active` is what
+ * keeps a surface that does not scale from running it at all. */
+export declare function useStageZoom(settingsShrink: boolean, active: boolean): Animated.Value;
+/** The stage's transform onto the settings card. */
+export declare function zoomStyle(zoom: Animated.Value, card: StageCard, width: number, _shrink: boolean): {
+    transform: ({
+        translateX: Animated.AnimatedInterpolation<string | number>;
+        scale?: undefined;
+    } | {
+        translateX?: undefined;
+        scale: Animated.AnimatedInterpolation<string | number>;
+    })[];
+};
+/** The frame that cuts the card's corners over the picture. Every native
+ * surface takes it: an AVPlayerLayer is not clipped by a rounded ancestor
+ * either, so on Apple TV the card came out square-cornered. */
+export declare function StageCornerMask({ zoom }: Readonly<{
+    zoom: Animated.Value;
+}>): ReactNode;

package/types/ui/src/lib/player/stage-zoom.web.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import { Animated, type ViewStyle } from 'react-native';
+import type { StageCard } from '#ui/components/organisms/player/lib/stage-card';
+/** The settings card's corner radius, in canvas pixels. */
+export declare const CARD_RADIUS = 72;
+/** The radius the picture's box rounds itself to: the browser box clips its own
+ * child element. */
+export declare function cardCorner(radius: number): number;
+/** The stage's shrink progress. Never animated in a browser: the transform is a
+ * CSS transition (see `zoomStyle`). */
+export declare function useStageZoom(settingsShrink: boolean, _active: boolean): Animated.Value;
+/** The stage's transform onto the settings card. */
+export declare function zoomStyle(_zoom: Animated.Value, card: StageCard, _width: number, shrink: boolean): ViewStyle;
+/** Nothing in a browser: the picture's box rounds its own corners. */
+export declare function StageCornerMask(_props: Readonly<{
+    zoom: Animated.Value;
+}>): ReactNode;

package/types/ui/src/lib/player/subtitle-edge.d.ts

@@ -0,0 +1,3 @@
+import type { TextStyle } from 'react-native';
+import type { SubEdge } from '#ui/components/organisms/player/lib/subtitle-appearance';
+export declare function edgeStyle(edge: SubEdge): TextStyle;

package/types/ui/src/lib/player/subtitle-edge.web.d.ts

@@ -0,0 +1,3 @@
+import type { TextStyle } from 'react-native';
+import type { SubEdge } from '#ui/components/organisms/player/lib/subtitle-appearance';
+export declare function edgeStyle(edge: SubEdge): TextStyle;

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

@@ -0,0 +1,8 @@
+import { type PlayerKeysParams } from '#ui/components/organisms/player/lib/player-keys';
+/**
+ * Route the TV remote into the player; the native mirror of `usePlayerKeys.web.ts`
+ * (same routing, different source: Metro picks this file, Vite the `.web` one).
+ * No `preventDefault`: a claimed TV event has no default to suppress.
+ */
+export declare function usePlayerKeys(params: Readonly<PlayerKeysParams>): void;
+export type { PlayerKeysParams };

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

@@ -0,0 +1,8 @@
+import { type PlayerKeysParams } from '#ui/components/organisms/player/lib/player-keys';
+/** The single window keydown router. One stable listener always sees the latest
+ * render, so re-renders never re-subscribe. It listens in the capture phase and
+ * stops every press it routes, so the spatial navigator and the screen behind
+ * the player never act on the same press. A field holding the caret keeps its
+ * keys, and a chord with Meta, Control or Alt stays the browser's. */
+export declare function usePlayerKeys(params: Readonly<PlayerKeysParams>): void;
+export type { PlayerKeysParams };

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

@@ -0,0 +1,2 @@
+/** Spread onto any player-chrome Pressable. See the file header for why. */
+export { UNFOCUSABLE as VIRTUAL_FOCUS } from '#ui/lib/focus-types';

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

@@ -0,0 +1,3 @@
+/** No-op on the web: there is no OS focus engine to opt out of, and the player
+ * already routes every key itself. See virtual-focus.ts for the native half. */
+export declare const VIRTUAL_FOCUS: {};

package/types/ui/src/lib/pointer-face.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/** A native control's painted face: a plain animated view on a pointerless television, the `renderTouch` pressable elsewhere, told whether it must stay unfocusable. */
+export declare function PointerFace({ style, render, renderTouch, }: Readonly<{
+    style: StyleProp<ViewStyle>[];
+    render: (pressed: boolean) => ReactNode;
+    renderTouch: (unfocusable: boolean) => ReactNode;
+}>): ReactNode;

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+declare function Portal({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/** Web-only: see `portal.web.tsx`. Native draws in place either way. */
+declare function PortalHost({ children }: Readonly<{
+    container: Element | null;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export { Portal, PortalHost };

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

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+declare function Portal({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/**
+ * Send the portals opened under it into `container` instead of `<body>`.
+ *
+ * For a React root that is not the app's: a tool mounted beside the page in its
+ * own element stacks above it, and a popover that left for `<body>` would be
+ * painted underneath the thing that opened it. `null` is the document, which is
+ * what every shell wants and what a portal does with no host above it.
+ */
+declare function PortalHost({ container, children, }: Readonly<{
+    container: Element | null;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export { Portal, PortalHost };

package/types/ui/src/lib/prefetch-image.d.ts

@@ -0,0 +1,2 @@
+/** Warm the image cache with `url`; resolves true once it is cached, false on failure. */
+export declare function prefetchImage(url: string): Promise<boolean>;

package/types/ui/src/lib/prefetch-image.web.d.ts

@@ -0,0 +1,2 @@
+/** Warm the image cache with `url` and decode it; resolves true once it can paint at once. */
+export declare function prefetchImage(url: string): Promise<boolean>;

package/types/ui/src/lib/prefetch-queue.d.ts

@@ -0,0 +1,15 @@
+export interface PrefetchQueueOptions {
+    /** Fetches and decodes one image; resolves true when it is ready to draw. */
+    prefetch: (uri: string) => Promise<boolean>;
+    /** Most fetches in flight at once. */
+    concurrency: number;
+    /** Runs a step when the device is idle. Defaults to running it at once. */
+    schedule?: (run: () => void) => void;
+}
+/** A low-priority image prefetcher that only ever works on the latest wish list. */
+export interface PrefetchQueue {
+    /** Replace what is wanted, nearest first. Anything no longer listed and not started is dropped. */
+    want: (uris: readonly string[]) => void;
+}
+/** Prefetch images a few at a time, skipping what is already ready and what stopped being wanted. */
+export declare function createPrefetchQueue({ prefetch, concurrency, schedule, }: PrefetchQueueOptions): PrefetchQueue;

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;
+/** The guard survives screen transitions within its owning app root. */
+export declare function createPressGuard(): {
+    armPressGuard(ms?: number): void;
+    pressGuardActive: () => boolean;
+    clearPressGuard(): void;
+};

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

@@ -0,0 +1,3 @@
+import { Pressable } from 'react-native';
+/** The pressable a touch control renders: animated, so the native press dip rides an Animated value. */
+export declare const PressHost: typeof Pressable;

package/types/ui/src/lib/press-host.web.d.ts

@@ -0,0 +1,2 @@
+/** The pressable a touch control renders: plain, so its style array paints as classes and the dip is a CSS transition. */
+export { Pressable as PressHost } from 'react-native';

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/remote-keys.d.ts

@@ -0,0 +1,26 @@
+export type RemoteKey = 'Up' | 'Down' | 'Left' | 'Right' | 'Enter' | 'Back' | 'Play' | 'Pause' | 'PlayPause' | 'Next' | 'Prev' | 'Stop' | 'Rewind' | 'FastForward' | 'ColorRed' | 'ColorGreen' | 'ColorYellow' | 'ColorBlue';
+/** Resolve a KeyboardEvent into a logical remote key, or null if unmapped. */
+export declare function resolveRemoteKey(e: KeyboardEvent): RemoteKey | null;
+/** A remote-key handler. Return `false` to mark the key *unhandled* (so the event
+ * keeps its default e.g. let a text field own ◀ ▶ / Enter); anything else
+ * (incl. `undefined`) counts as handled and the event is `preventDefault`-ed. */
+export type RemoteKeyHandler = (e: KeyboardEvent) => unknown;
+/** Declarative key → action table: `{ Enter: () => …, Back: () => … }`. */
+export type RemoteKeyMap = Partial<Record<RemoteKey, RemoteKeyHandler>>;
+/**
+ * Resolve a keydown and dispatch it through a {@link RemoteKeyMap} so screens
+ * declare *what* each key does instead of hand-rolling a `switch` with the same
+ * resolve / auto-repeat / `preventDefault` plumbing every time. Returns the
+ * resolved key (or null), so callers can fall through on unbound keys.
+ *
+ * `ignoreRepeat` lists keys whose auto-repeat is swallowed (discrete OK actions:
+ * a held OK that entered a screen must not re-fire on the next one).
+ */
+export declare function dispatchRemoteKey(e: KeyboardEvent, map: RemoteKeyMap, opts?: {
+    ignoreRepeat?: readonly RemoteKey[];
+}): RemoteKey | null;
+/**
+ * On Tizen the media/colour keys must be explicitly registered before the
+ * platform delivers them. No-op everywhere else. Call once at boot.
+ */
+export declare function registerTvMediaKeys(): void;

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

@@ -0,0 +1,7 @@
+import type { createFocusProbe } from './focus-here';
+import type { createFocusMirror } from './focus-mirror';
+export interface RemoteTransportOptions {
+    enabled: boolean;
+    probe: ReturnType<typeof createFocusProbe>;
+    mirror: ReturnType<typeof createFocusMirror>;
+}

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

@@ -0,0 +1,10 @@
+import type { ReportCategory } from '@kromatv/client/reports';
+import type { MessageKey } from '@kromatv/i18n';
+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/reveal-contexts.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+import { type View } from 'react-native';
+type Anchor = RefObject<View | null>;
+declare const PageScrollContext: import("react").Context<((anchor: Anchor) => void) | null>;
+declare const RowContext: import("react").Context<Anchor | null>;
+declare const RailScrollContext: import("react").Context<((anchor: Anchor) => void) | null>;
+export type { Anchor };
+export { PageScrollContext, RailScrollContext, RowContext };

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/safe-image-url.d.ts

@@ -0,0 +1,4 @@
+/** An artwork URL safe to hand to an `<img src>`, or null. Server-supplied
+ * poster and backdrop URLs are third-party input; anything with a scheme must be
+ * one that only ever paints (blocks `javascript:` and other DOM-sink schemes). */
+export declare function safeImageUrl(url: string | null | undefined): string | null;

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/scope-carrier.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+/** Native styles resolve through context, which a portal keeps: nothing to carry. */
+export declare function ScopeCarrier({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/src/lib/scope-carrier.web.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+/**
+ * Re-stamps the nearest styling root's marks around content that renders
+ * outside that root's element: a portal under `<body>`, a `<Modal>`'s own
+ * container. Without it the content reads the document's ground and the
+ * base breakpoint, whatever its root says.
+ */
+export declare function ScopeCarrier({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;

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

@@ -0,0 +1,5 @@
+export declare function useScrollLock(_locked: boolean): void;
+/** Native has no document to lock. */
+export declare function createScrollLock(): {
+    hold: () => () => void;
+};

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

@@ -0,0 +1,6 @@
+/** One document host shares this lease across all overlays in its tree. */
+export declare function createScrollLock(): {
+    hold(): () => void;
+};
+/** Freeze the host page until the last overlay releases its lease. */
+export declare function useScrollLock(locked: boolean): void;

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/** Content inside a page scroller that dissolves to transparent as it scrolls up past `inset` below the scroller's top edge, over the next 160 px: a real mask, so whatever is truly behind it shows. Nothing on native, which has no mask. */
+export declare function ScrollMask({ style, children, }: Readonly<{
+    inset: number;
+    style?: StyleProp<ViewStyle>;
+    children: ReactNode;
+}>): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/** Content inside a page scroller that dissolves to transparent as it scrolls up past `inset` below the scroller's top edge, over the next 160 px: a real mask, so whatever is truly behind it shows. Nothing on native, which has no mask. */
+export declare function ScrollMask({ inset, style, children, }: Readonly<{
+    inset: number;
+    style?: StyleProp<ViewStyle>;
+    children: ReactNode;
+}>): import("react").JSX.Element;

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

@@ -0,0 +1,20 @@
+interface PageMetrics {
+    top: number;
+    offsetFromStart: number;
+    viewport: number;
+    content: number;
+}
+declare function pageOffset({ top, offsetFromStart, viewport, content }: PageMetrics): number;
+interface NearestMetrics {
+    top: number;
+    size: number;
+    current: number;
+    margin: number;
+    viewport: number;
+    content: number;
+}
+/** The offset that shows a row whole with `margin` to spare, moving the page
+ *  only when the row is not already there. */
+declare function nearestOffset({ top, size, current, margin, viewport, content }: NearestMetrics): number;
+export type { NearestMetrics, PageMetrics };
+export { nearestOffset, pageOffset };

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

@@ -0,0 +1,20 @@
+import { type ViewStyle } from 'react-native';
+/**
+ * A scroll view clips at its own edges, and the ring of a focused control stands
+ * outside the control - so a control flush with an edge loses that side of its
+ * ring (the leftmost poster of a results grid, every time). The scroller reaches
+ * RING_ROOM further out and its content is padded back in by the same amount:
+ * the content lands exactly where it did, with room around it for a ring.
+ *
+ * A row reaches out on all four sides: its first tile IS flush with the start
+ * edge, and nothing of the app's sits beside a row for the extra reach to show
+ * through. A page only reaches out sideways - above and below it is the screen's
+ * own chrome, and a hole in the clip there would show the scrolled-off rows
+ * through it (see organisms/virtual/clip). A page's first row gets its room from
+ * the top padding of its content instead.
+ */
+declare function ringRoom(style: ViewStyle | undefined, content: ViewStyle | undefined, horizontal: boolean): {
+    box: ViewStyle;
+    content: ViewStyle;
+};
+export { ringRoom };

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

@@ -0,0 +1,2 @@
+/** Where the nearest page scroller reports leaving or returning to its start, when it has no `onScrolledChange` of its own. */
+export declare const ScrolledReport: import("react").Context<((scrolled: boolean) => void) | null>;

package/types/ui/src/lib/scrub-gesture-types.d.ts

@@ -0,0 +1,10 @@
+import type { GestureResponderHandlers } from 'react-native';
+/** What a vertical scrub reports: the offset from the target's top edge, and its end. */
+export interface ScrubGestureOptions {
+    onScrub: (offsetY: number) => void;
+    onEnd: () => void;
+    /** Pixels a touch travels before it is a scrub rather than a tap. */
+    slop: number;
+}
+/** Spread onto the target; null where the scrub is wired another way or not at all. */
+export type ScrubHandlers = GestureResponderHandlers | null;

package/types/ui/src/lib/scrub-gesture.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from 'react';
+import { type View } from 'react-native';
+import type { ScrubGestureOptions, ScrubHandlers } from './scrub-gesture-types';
+/** A vertical drag along `target`, reported as offsets from its top edge. */
+export declare function useScrubGesture(target: RefObject<View | null>, { onScrub, onEnd, slop }: ScrubGestureOptions): ScrubHandlers;

package/types/ui/src/lib/scrub-gesture.web.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from 'react';
+import type { View } from 'react-native';
+import type { ScrubGestureOptions, ScrubHandlers } from './scrub-gesture-types';
+/** A vertical drag along `target`, reported as offsets from its top edge. */
+export declare function useScrubGesture(target: RefObject<View | null>, { onScrub, onEnd }: ScrubGestureOptions): ScrubHandlers;

package/types/ui/src/lib/seam-keys-types.d.ts

@@ -0,0 +1,11 @@
+import type { GroupOrientation } from '#ui/lib/group-shape';
+interface ResizableKeysOptions {
+    /** While true the seam owns the four directions, and nothing else moves. */
+    held: boolean;
+    orientation: GroupOrientation;
+    /** `-1` towards the start of the group (left, up), `1` towards its end. */
+    onNudge: (towards: -1 | 1) => void;
+    /** Select, Escape or Back: the reader is done. */
+    onRelease: () => void;
+}
+export type { ResizableKeysOptions };

package/types/ui/src/lib/seam-keys.d.ts

@@ -0,0 +1,3 @@
+import type { ResizableKeysOptions } from './seam-keys-types';
+declare function useResizableKeys({ held, orientation, onNudge, onRelease }: ResizableKeysOptions): void;
+export { useResizableKeys };

package/types/ui/src/lib/seam-keys.web.d.ts

@@ -0,0 +1,3 @@
+import type { ResizableKeysOptions } from './seam-keys-types';
+declare function useResizableKeys({ held, orientation, onNudge, onRelease }: ResizableKeysOptions): void;
+export { useResizableKeys };

package/types/ui/src/lib/session-flag.d.ts

@@ -0,0 +1,7 @@
+/** A flag that lasts as long as this launch's session storage, and reads unset where there is none. */
+export interface SessionFlag {
+    isSet(): boolean;
+    set(): void;
+}
+/** The session flag stored under `key`. */
+export declare function sessionFlag(key: string): SessionFlag;

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 '@kromatv/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>;