@kromatv/sdk 0.1.40-canary.0

package/types/ui/src/core/breakpoint-cascade.d.ts

@@ -0,0 +1,45 @@
+import { type BreakpointName } from '#ui/core/tokens/layout';
+/**
+ * A value stated per breakpoint, mobile-first: `base` is mandatory and applies
+ * until the next breakpoint the object names. A missing middle step inherits
+ * from below, never from above.
+ */
+export type Breakpoints<T> = {
+    base: T;
+} & {
+    [K in Exclude<BreakpointName, 'base'>]?: T;
+};
+/** Any value in the vocabulary: one value, or one per breakpoint. */
+export type Responsive<T> = T | Breakpoints<T>;
+export declare const LAST_BREAKPOINT: number;
+/**
+ * The attribute the store writes on the document root: a declaration a build
+ * compiled paints through `:root[data-kroma-bp~="md"]` rather than a media
+ * query, so the classes and the resolver never disagree about the step.
+ */
+export declare const BREAKPOINT_ATTRIBUTE = "data-kroma-bp";
+/** Every step reached at `index`, which is what the attribute carries: `~=`
+ *  then matches a step from where it starts upwards, as the cascade does. */
+export declare function stepsReached(index: number): string;
+/** The step a design width falls in, as a position in {@link BREAKPOINTS}. */
+export declare function breakpointAt(width: number): number;
+/**
+ * Which breakpoints a value names, as a bitmask, and 0 for anything that is not
+ * a breakpoint object - a plain value, an Animated node, a transform array.
+ * Zero is the whole zero-cost path: it is what keeps a flat declaration off the
+ * breakpoint axis, exactly as an empty state mask keeps it off the state axis.
+ */
+export declare function breakpointBits(value: unknown): number;
+/** The value at a breakpoint, mobile-first. A value naming no breakpoint at all
+ *  passes through, so an Animated node stays itself. */
+export declare function valueAt(value: object, index: number): unknown;
+/**
+ * The step a declaration naming `mask` actually resolves at when the surface
+ * is at `index`: the widest breakpoint it names at or below that one, and 0
+ * when it names none.
+ *
+ * This is the cache-key axis. Two widths a declaration cannot tell apart share
+ * one entry, and a declaration with no responsive value at all keys on 0
+ * forever - so it mints exactly the one entry it does today.
+ */
+export declare function stepAt(mask: number, index: number): number;

package/types/ui/src/core/breakpoint.d.ts

@@ -0,0 +1,21 @@
+import { type BreakpointName } from '#ui/core/tokens';
+export type { Breakpoints, Responsive } from '#ui/core/breakpoint-cascade';
+export { breakpointBits, valueAt } from '#ui/core/breakpoint-cascade';
+/** The active breakpoint as a position in {@link BREAKPOINTS}, which is what
+ *  the cascade and every cache key are expressed in. */
+export declare function breakpointIndex(): number;
+/** The active breakpoint. */
+export declare function currentBreakpoint(): BreakpointName;
+/**
+ * States the width every declaration resolves against, for a surface whose own
+ * size is not the design's: `<TvStage>` paints a fixed `CANVAS.width` canvas
+ * however small the window it is scaled into. Call it with nothing to follow
+ * the viewport again.
+ */
+export declare function pinDesignWidth(width?: number): void;
+/** Subscribe to breakpoint CROSSINGS; returns the unsubscribe. A resize that
+ *  stays inside one step notifies nobody. */
+export declare function subscribeBreakpoint(listener: () => void): () => void;
+/** The step a declaration naming `mask` resolves at, against the active
+ *  breakpoint unless `at` says otherwise; see {@link stepAt}. */
+export declare function breakpointStep(mask: number, at?: number): number;

package/types/ui/src/core/color.d.ts

@@ -0,0 +1,21 @@
+import type { ColorToken } from '#ui/core/tokens';
+import { withAlpha } from '#ui/core/tokens/colors';
+export { withAlpha };
+declare const BARE: {
+    readonly white: '#FFFFFF';
+    readonly black: '#000000';
+};
+export type ColorBase = ColorToken | keyof typeof BARE;
+/**
+ * A colour. Deliberately not `ColorToken | (string & {})`: that escape hatch
+ * made every string legal, so `bg: 'acent'` compiled and painted nothing, since
+ * `color()` returns an unrecognised value verbatim and React Native ignores a
+ * colour it cannot parse.
+ */
+export type ColorValue = ColorBase | `${ColorBase}/${number}` | `#${string}` | `rgb(${string})` | `rgba(${string})` | `hsl(${string})` | `hsla(${string})` | 'transparent' | 'currentColor';
+/** Resolves a token name through the palette and anything else verbatim. A
+ *  trailing `/NN` is Tailwind's alpha syntax and means NN percent opacity. */
+export declare function color(value: string): string;
+/** Style keys whose value is a colour. A recipe slot that feeds an <Icon> writes
+ *  `color`, which is not a shorthand, and must still resolve `accent/45`. */
+export declare const COLOR_KEYS: ReadonlySet<string>;

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

@@ -0,0 +1,20 @@
+export type { Breakpoints, Responsive } from './breakpoint';
+export { breakpointIndex, currentBreakpoint, pinDesignWidth } from './breakpoint';
+export type { ColorValue } from './color';
+export { color, withAlpha } from './color';
+export { normalize } from './normalize';
+export { sv, svFor } from './recipe';
+export { boxStyle, declaredBreakpoints, splitShorthand } from './shorthand-resolve';
+export type { BoxStyleProps, TextLayoutProps } from './shorthands';
+export { TEXT_STYLE_PROPS } from './shorthands';
+export { stabilise } from './stabilise';
+export type { SvState, SvStateName } from './states';
+export { registered, sharedStyle, style, styles } from './styles';
+export type { RingToken, Theme, ThemeOverrides, ThemeTokens } from './theme';
+export { activeTheme, applyTheme, createTheme, groundShade, KROMA, KROMA_LIGHT, onPaper, onThemeChange, radiusValue, setTheme, themed, themedCache, themeVersion, } from './theme';
+export type { ThemeMode } from './theme-mode';
+export { applyMode, readMode, resolveMode, writeMode } from './theme-mode';
+export * from './tokens';
+export type { AnySv, Resolved, StyleDecl, Variant, VariantProps, VariantSource, } from './types';
+export { useBreakpoint, useBreakpointStep } from './use-breakpoint';
+export { ThemeProvider, useSystemGround, useTheme } from './use-theme';

package/types/ui/src/core/normalize.d.ts

@@ -0,0 +1,21 @@
+import { type SvStateName } from '#ui/core/states';
+export interface Split {
+    rest: Record<string, unknown>;
+    states: Partial<Record<SvStateName, Record<string, unknown>>>;
+    declared: SvStateName[];
+    breakpoints: number;
+}
+export declare function split(decl: Record<string, unknown> | undefined, index: number): Split | undefined;
+/**
+ * Rewrites one layer into React Native longhands, resolving shorthands, colours
+ * and, against the breakpoint at `index`, any value stated per breakpoint.
+ *
+ * Per LAYER, which is what makes merging correct: merging authored keys would
+ * leave `{ px: 18 }` and `{ p: 12 }` both alive, and the resolver would then
+ * pick by specificity rather than by order, so an earlier base would beat a
+ * later variant. Once every layer speaks longhand, `Object.assign` is the
+ * conflict resolution - last write wins, per property, like CSS.
+ *
+ * A layer the build already compiled is its own canonical form.
+ */
+export declare function normalize(decl: Record<string, unknown>, index: number): Record<string, unknown>;

package/types/ui/src/core/recipe.d.ts

@@ -0,0 +1,21 @@
+import type { FlatVariantGroups, SlotShapes, StyleDecl, StyleSlots, SvConfig, SvFlatConfig, SvFn, VariantGroups } from '#ui/core/types';
+/** Single slot: `base` plus flat variant options, which is most components. */
+export declare function sv<const V extends FlatVariantGroups = Record<string, never>>(config: SvFlatConfig<V>): SvFn<{
+    root: StyleDecl;
+}, V>;
+/** Named slots, all painted. Only the names are inferred, never the shapes: a
+ *  variant option paints keys the base never mentioned. */
+export declare function sv<S extends Record<string, StyleDecl>, const V extends VariantGroups<StyleSlots<S>> = Record<string, never>>(config: SvConfig<StyleSlots<S>, V> & {
+    slots: S;
+}): SvFn<StyleSlots<S>, V>;
+/**
+ * Names the slot shapes up front, for a recipe with a slot that feeds a
+ * component's props rather than its style:
+ *
+ *   svFor<{ root: StyleDecl; icon: IconProps }>()({ slots: { … }, variants: { … } })
+ *
+ * Curried because TypeScript has no partial type-argument inference: naming the
+ * shapes inline would forfeit inference of the variant groups, and every option
+ * name would widen to `string`.
+ */
+export declare function svFor<P extends SlotShapes>(): <const V extends VariantGroups<P> = Record<string, never>>(config: SvConfig<P, V>) => SvFn<P, V>;

package/types/ui/src/core/shorthand-resolve.d.ts

@@ -0,0 +1,54 @@
+import type { ViewStyle } from 'react-native';
+import { type BoxStyleProps } from '#ui/core/shorthands';
+import type { FontToken, TypeRole } from '#ui/core/tokens';
+/**
+ * Split a prop bag into the shorthands and everything else.
+ *
+ * Every consumer needs exactly this partition - <Box> and <Text> to tell a style
+ * prop from a real host prop, a recipe to tell what needs resolving from what
+ * passes through - so the rule for recognising a shorthand lives in one place.
+ *
+ * `key` canonicalises the caller's prop order, so `row gap={4}` and `gap={4} row`
+ * are one entry in whatever cache the caller keys on it; it is empty when nothing
+ * needs resolving.
+ */
+export declare function splitShorthand(props: Readonly<Record<string, unknown>>, names?: ReadonlySet<string>): {
+    shorthand: Record<string, unknown>;
+    rest: Record<string, unknown>;
+    /** Whether any shorthand was found, so a caller can skip the resolver. */
+    any: boolean;
+    key: string;
+    /** The breakpoints the bag names, 0 when it names none; see
+     *  {@link breakpointBits}. */
+    breakpoints: number;
+};
+/**
+ * Which breakpoints a whole declaration names, for a consumer that compiles one
+ * ahead of time (a recipe layer, a `styles()` value) and has to know whether it
+ * belongs on the breakpoint axis at all.
+ */
+export declare function declaredBreakpoints(decl: Readonly<Record<string, unknown>>, names?: ReadonlySet<string>): number;
+/**
+ * Resolves a prop bag into React Native longhands at a breakpoint. A bag
+ * stating nothing per breakpoint resolves the same at every index.
+ */
+export declare function boxStyle(p: Readonly<BoxStyleProps>, index: number): ViewStyle;
+/**
+ * The text half of the vocabulary. Only a style DECLARATION speaks it (a recipe
+ * layer, a `styles()` value); it is deliberately not part of `BoxStyleProps`,
+ * because a <Box> is a View and a View cannot paint type.
+ */
+export interface TextStyleProps {
+    /** A whole type role, spread under the rest of the layer, so
+     *  `{ text: 'label', fontSize: 13 }` is the label role at 13px. */
+    text?: TypeRole;
+    /** Font family by token name; wins over the family `text` brought in. */
+    font?: FontToken;
+}
+/**
+ * Resolves the text shorthands of one layer, consuming their keys, or nothing
+ * if it has none. Membership-checked against the theme, not just typeof: a slot
+ * that feeds a component's PROPS may carry a `text` of its own, and that one
+ * must pass through untouched.
+ */
+export declare function textStyle(decl: Record<string, unknown>): Record<string, unknown> | undefined;

package/types/ui/src/core/shorthands.d.ts

@@ -0,0 +1,187 @@
+import type { DimensionValue, TextStyle, ViewStyle } from 'react-native';
+import type { Responsive } from '#ui/core/breakpoint';
+import { type ColorValue } from '#ui/core/color';
+import { type RingToken } from '#ui/core/theme';
+import type { ShadowToken } from '#ui/core/tokens/effects';
+import { type CornerValue } from '#ui/core/tokens/layout';
+export type Spacing = Responsive<DimensionValue>;
+export type Size = Responsive<DimensionValue>;
+export type Flag = Responsive<boolean>;
+export type Align = Responsive<NonNullable<ViewStyle['alignItems']>>;
+export type Justify = Responsive<NonNullable<ViewStyle['justifyContent']>>;
+export interface BoxStyleProps {
+    flex?: Responsive<boolean | number>;
+    row?: Flag;
+    wrap?: Flag;
+    center?: Flag;
+    align?: Align;
+    justify?: Justify;
+    self?: Responsive<NonNullable<ViewStyle['alignSelf']>>;
+    shrink?: Responsive<number>;
+    grow?: Responsive<number>;
+    basis?: Size;
+    gap?: Spacing;
+    /** The gap along one axis only, for a wrapping row whose columns and rows
+     *  breathe differently. Both are real React Native style keys, so they mean
+     *  the same thing on every target. */
+    gapX?: Spacing;
+    gapY?: Spacing;
+    /** How WRAPPED lines are packed against the cross axis. `align` positions the
+     *  items inside their line; this positions the lines. */
+    alignContent?: Responsive<NonNullable<ViewStyle['alignContent']>>;
+    between?: Flag;
+    w?: Size;
+    h?: Size;
+    minW?: Size;
+    minH?: Size;
+    maxW?: Size;
+    maxH?: Size;
+    aspect?: Responsive<number>;
+    fill?: Flag;
+    absolute?: Flag;
+    top?: Size;
+    right?: Size;
+    bottom?: Size;
+    left?: Size;
+    z?: Responsive<number>;
+    p?: Spacing;
+    px?: Spacing;
+    py?: Spacing;
+    pt?: Spacing;
+    pr?: Spacing;
+    pb?: Spacing;
+    pl?: Spacing;
+    m?: Spacing;
+    mx?: Spacing;
+    my?: Spacing;
+    mt?: Spacing;
+    mr?: Spacing;
+    mb?: Spacing;
+    ml?: Spacing;
+    bg?: Responsive<ColorValue>;
+    /** A radius token, a raw px value, or `'circle'`; see {@link CornerValue}. */
+    radius?: Responsive<CornerValue>;
+    border?: Responsive<ColorValue>;
+    borderWidth?: Responsive<number>;
+    shadow?: Responsive<ShadowToken>;
+    /** The focus treatment, derived from the theme's accent. */
+    ring?: Responsive<RingToken>;
+    opacity?: Responsive<number>;
+    overflow?: Responsive<NonNullable<ViewStyle['overflow']>>;
+    /** Paints into its own stacking context, so a blend or a z-index inside cannot
+     *  reach the page behind it. Browser targets only; native has no equivalent. */
+    isolate?: Flag;
+}
+/** The rows a React Native <Text> honours: it lays ITSELF out, so the container
+ *  rows (`row`, `gap`, `align`) and the surface paints (`bg`, `radius`, `border`)
+ *  stay on <Box>. */
+declare const TEXT_LAYOUT_ROWS: readonly ["flex", "self", "shrink", "grow", "basis", "w", "h", "minW", "minH", "maxW", "maxH", "absolute", "top", "right", "bottom", "left", "z", "p", "px", "py", "pt", "pr", "pb", "pl", "m", "mx", "my", "mt", "mr", "mb", "ml", "opacity"];
+/**
+ * The text half of the layout vocabulary: what <Text> takes as props.
+ *
+ * `textAlign` is spelled in full because `align` already means `alignItems` on
+ * <Box>, and one name means one role across the kit.
+ */
+export interface TextLayoutProps extends Pick<BoxStyleProps, (typeof TEXT_LAYOUT_ROWS)[number]> {
+    textAlign?: Responsive<NonNullable<TextStyle['textAlign']>>;
+}
+export type Rule = string | readonly string[] | Readonly<Record<string, unknown>> | ((value: unknown) => Readonly<Record<string, unknown>>);
+/**
+ * The `satisfies` below is what makes the interfaces and the table one source of
+ * truth: a prop added to `BoxStyleProps` or `TextLayoutProps` and forgotten here
+ * is a compile error. Without that link they drift silently and in two different
+ * ways - <Box> and <Text> forward the unknown name to the host node as a DOM
+ * attribute, and a recipe emits it verbatim as a bogus style key.
+ */
+export declare const RULES: {
+    readonly fill: {
+        readonly position: 'absolute';
+        readonly top: 0;
+        readonly left: 0;
+        readonly right: 0;
+        readonly bottom: 0;
+    };
+    readonly flex: (v: unknown) => {
+        flex: unknown;
+    };
+    readonly row: {
+        readonly flexDirection: 'row';
+    };
+    readonly wrap: {
+        readonly flexWrap: 'wrap';
+    };
+    readonly center: {
+        readonly alignItems: 'center';
+        readonly justifyContent: 'center';
+    };
+    readonly between: {
+        readonly justifyContent: 'space-between';
+    };
+    readonly align: 'alignItems';
+    readonly justify: 'justifyContent';
+    readonly self: 'alignSelf';
+    readonly shrink: 'flexShrink';
+    readonly grow: 'flexGrow';
+    readonly basis: 'flexBasis';
+    readonly gap: 'gap';
+    readonly gapX: 'columnGap';
+    readonly gapY: 'rowGap';
+    readonly alignContent: 'alignContent';
+    readonly w: 'width';
+    readonly h: 'height';
+    readonly minW: 'minWidth';
+    readonly minH: 'minHeight';
+    readonly maxW: 'maxWidth';
+    readonly maxH: 'maxHeight';
+    readonly aspect: 'aspectRatio';
+    readonly absolute: {
+        readonly position: 'absolute';
+    };
+    readonly top: 'top';
+    readonly right: 'right';
+    readonly bottom: 'bottom';
+    readonly left: 'left';
+    readonly z: 'zIndex';
+    readonly p: readonly ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft"];
+    readonly px: readonly ["paddingLeft", "paddingRight"];
+    readonly py: readonly ["paddingTop", "paddingBottom"];
+    readonly pt: 'paddingTop';
+    readonly pr: 'paddingRight';
+    readonly pb: 'paddingBottom';
+    readonly pl: 'paddingLeft';
+    readonly m: readonly ["marginTop", "marginRight", "marginBottom", "marginLeft"];
+    readonly mx: readonly ["marginLeft", "marginRight"];
+    readonly my: readonly ["marginTop", "marginBottom"];
+    readonly mt: 'marginTop';
+    readonly mr: 'marginRight';
+    readonly mb: 'marginBottom';
+    readonly ml: 'marginLeft';
+    readonly bg: (v: unknown) => {
+        backgroundColor: string;
+    };
+    readonly radius: (v: unknown) => {
+        borderRadius: number;
+    };
+    readonly border: (v: unknown) => {
+        borderColor: string;
+        borderWidth: number;
+    };
+    readonly borderWidth: 'borderWidth';
+    readonly shadow: (v: unknown) => {
+        boxShadow: string;
+    };
+    readonly ring: (v: unknown) => {};
+    readonly opacity: 'opacity';
+    readonly overflow: 'overflow';
+    readonly isolate: {
+        readonly isolation: 'isolate';
+    };
+    readonly textAlign: 'textAlign';
+};
+export declare const RULE_KEYS: (keyof typeof RULES)[];
+/** The shorthand names as a lookup, shared by <Box>'s prop split and the
+ *  resolver. */
+export declare const BOX_STYLE_PROPS: ReadonlySet<string>;
+/** The subset <Text> speaks, in the table's own cascade order. */
+export declare const TEXT_STYLE_PROPS: ReadonlySet<string>;
+export {};

package/types/ui/src/core/stabilise.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Registers a merged value, with its keys in a canonical order: React Native's
+ * own shorthands first, then everything else alphabetically.
+ *
+ * Registration is what makes react-native-web compile the declarations into
+ * atomic classes rather than re-serialise them onto every element. It hands the
+ * same object back, so the result is still a plain style a caller can read.
+ *
+ * An order that varied with which layers contributed would mean an unstable
+ * stylesheet between builds. Sorting alone is not enough, see `RN_SHORTHANDS`.
+ *
+ * A value the build compiled is registered already and comes back untouched.
+ */
+export declare function stabilise(merged: Record<string, unknown>): Record<string, unknown>;

package/types/ui/src/core/states.d.ts

@@ -0,0 +1,16 @@
+/** In cascade order. `active` is deliberately absent: a toggle's pressed-in
+ *  reading is owned by the component's props, not the pointer, so it is a
+ *  variant - which is also what lets it carry its own `_hover`. */
+export declare const SV_STATES: readonly ['hover', 'focus', 'press', 'disabled'];
+export type SvStateName = (typeof SV_STATES)[number];
+export type SvState = Partial<Record<SvStateName, boolean>>;
+export type StateKey = `_${SvStateName}`;
+export declare const STATE_KEYS: ReadonlySet<string>;
+export declare const STATE_BIT: Readonly<Record<SvStateName, number>>;
+/** Which states a recipe declares. A caller always passes all four, so without
+ *  a mask a recipe with no `_hover` mints separate hovered and unhovered cache
+ *  entries holding identical styles. */
+export declare function maskOf(declared: Iterable<SvStateName>): number;
+/** The state half of a cache key. Only states in `mask` contribute, so two calls
+ *  differing solely in a state the recipe ignores share one entry. */
+export declare function stateSuffix(state: SvState | undefined, mask: number): string;

package/types/ui/src/core/styles.d.ts

@@ -0,0 +1,59 @@
+import { type StyleProp } from 'react-native';
+import type { AnyStyle, StyleDecl } from '#ui/core/types';
+export type Styles<S> = {
+    readonly [K in keyof S]: AnyStyle;
+};
+/**
+ * Resolve a named set of styles, once per theme, on first use - and once more
+ * per breakpoint the set actually names, which is never for a set that names
+ * none.
+ *
+ * Shaped like `StyleSheet.create` so it reads the way React Native already
+ * does, but speaking the kit's vocabulary (shorthands, colour tokens and the
+ * `/NN` alpha suffix) and returning one lowercase binding instead of a spread
+ * of shouting constants:
+ *
+ *   const s = styles({
+ *     row: { row: true, align: 'center', gap: 6, px: 8, radius: 'sm' },
+ *     label: { fontSize: 13, color: 'textMuted' },
+ *   });
+ *
+ *   <Box style={s.row}><Text style={s.label} /></Box>
+ *
+ * Each value goes through `StyleSheet.create`, so react-native-web compiles it
+ * to atomic CSS classes shared with every other style that declares the same
+ * thing, rather than re-serialising it onto each element.
+ *
+ * The binding is a live view: reading `s.row` resolves against the ACTIVE
+ * theme and breakpoint, and either swap hands back fresh objects (a new
+ * identity is what makes react-native-web recompile them). Read properties off
+ * it at render time; a value copied out and held keeps the theme it was read
+ * under. Nothing here re-renders a component - a set that changes with the
+ * breakpoint is read by one that follows it (`useBreakpoint`, or <Box>).
+ */
+export declare function styles<const S extends Record<string, StyleDecl>>(decls: S): Styles<S>;
+/** One style, for the handful of places a set of one would be noise. Resolved
+ *  against the theme active at the first read. A caller that must follow a
+ *  swap uses `styles()` and reads at render time. */
+export declare function style<const T extends StyleDecl>(decl: T): AnyStyle;
+/**
+ * A style a third party rebuilt as a plain object, registered again by its
+ * content: a router's link spreads the style the kit hands it into its own
+ * active-state style, and the fresh object it makes is registered by nothing,
+ * so the browser paints every property of it inline. Keyed on the content,
+ * every link carrying the same paint shares one entry and one set of classes.
+ */
+export declare function registered(style: StyleProp<AnyStyle>): AnyStyle;
+/**
+ * A style shared by identity with every caller passing the same `key`, for the
+ * values a render computes rather than declares.
+ *
+ * Registered like `styles`, and shared by identity on top of that: styleq keys
+ * its compiled-style cache on the leaf object, so resolving one per render is a
+ * guaranteed miss even once the declaration compiles to a class.
+ *
+ * The key identifies the DECLARATION, so one stating a value per breakpoint
+ * carries the step it was resolved at (see <Text>); the breakpoint is not part
+ * of the key by itself, which is what keeps a flat declaration at one entry.
+ */
+export declare function sharedStyle(key: string, decl: StyleDecl): AnyStyle;

package/types/ui/src/core/theme-create.d.ts

@@ -0,0 +1,64 @@
+import type { TextStyle } from 'react-native';
+import { type ColorToken } from '#ui/core/tokens/colors';
+import { motion, type RingStyle, type ShadowToken } from '#ui/core/tokens/effects';
+import { gutter, type RadiusToken, rhythm, space } from '#ui/core/tokens/layout';
+import { type FontToken, type TypeRole, type TypeSpec, tracking } from '#ui/core/tokens/typography';
+/** The token modules author values `as const`; a theme's slots take any value
+ *  of the same shape, not only the KROMA literal. */
+type Widen<T> = T extends number ? number : T extends string ? string : T extends readonly (infer U)[] ? readonly Widen<U>[] : {
+    [K in keyof T]: Widen<T[K]>;
+};
+export interface ThemeTokens {
+    colors: Record<ColorToken, string>;
+    radius: Record<RadiusToken, number>;
+    shadow: Record<ShadowToken, string>;
+    fonts: Record<FontToken, string>;
+    typeSpec: Record<TypeRole, TypeSpec>;
+    motion: Widen<typeof motion>;
+    gutter: Widen<typeof gutter>;
+    space: Widen<typeof space>;
+    rhythm: Widen<typeof rhythm>;
+    tracking: Widen<typeof tracking>;
+}
+export interface Theme extends ThemeTokens {
+    /** Derived from `typeSpec` + `fonts`; never authored directly. */
+    type: Record<TypeRole, TextStyle>;
+    /** Derived from the accent; never authored directly. The glow pairs carry the
+     *  accent bloom the player's focus treatment adds to the plain ring. */
+    ring: {
+        focus: RingStyle;
+        focusSm: RingStyle;
+        focusLift: RingStyle;
+        focusGlow: RingStyle;
+        focusGlowSm: RingStyle;
+        /** The soft wide wash, for a control whose focus must read as a glow on a
+         *  thin shape (the seek bar's track) rather than a crisp outline. */
+        focusWash: RingStyle;
+        /** The ring, inward: for a control flush with whatever clips it. */
+        focusInset: RingStyle;
+        /** The ring, on the edge: for a row that abuts its neighbours. */
+        focusEdge: RingStyle;
+    };
+    /** Derived from the accent wash; never authored directly. */
+    glow: {
+        accent: string;
+        play: string;
+    };
+}
+/** What the `ring:` shorthand accepts. */
+export type RingToken = keyof Theme['ring'];
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/** What `createTheme` accepts: any slice of any group. A name the base does not
+ *  have needs its registry augmented first, which is what keeps it typed at
+ *  every use site rather than only here. */
+export type ThemeOverrides = {
+    [G in keyof ThemeTokens]?: DeepPartial<ThemeTokens[G]>;
+};
+/** The default theme, straight from the token modules. */
+export declare const KROMA: Theme;
+/** KROMA on a warm paper ground. */
+export declare const KROMA_LIGHT: Theme;
+export declare function createTheme(overrides: ThemeOverrides, base?: Theme): Theme;
+export {};

package/types/ui/src/core/theme-mode.d.ts

@@ -0,0 +1,15 @@
+export type ThemeMode = 'system' | 'light' | 'dark';
+export declare const THEME_COOKIE = "kroma-theme";
+export declare const isThemeMode: (v: unknown) => v is ThemeMode;
+/** The ground a mode resolves to right now. Anything `system` cannot be told
+ *  about reads as dark, the product's default ground. */
+export declare function resolveMode(mode: ThemeMode): 'light' | 'dark';
+export declare function readMode(cookie?: string): ThemeMode;
+/**
+ * Stamps the ground on the document, which on a browser is the whole switch:
+ * every colour is a custom property, so `[data-theme]` repaints without a
+ * re-render, and `system` is stamped as ABSENCE for the media query to answer.
+ * React Native has no cascade, so there the store moves instead.
+ */
+export declare function applyMode(mode: ThemeMode): void;
+export declare function writeMode(mode: ThemeMode): void;

package/types/ui/src/core/theme.d.ts

@@ -0,0 +1,72 @@
+import { type Theme } from '#ui/core/theme-create';
+import { type CornerValue } from '#ui/core/tokens/layout';
+export * from '#ui/core/theme-create';
+export declare function activeTheme(): Theme;
+/**
+ * Whether a theme paints on paper.
+ *
+ * Always false on a browser, where the cascade owns the ground: this answers
+ * for what the cascade cannot reach, a native blur view needing its own tint.
+ */
+export declare function onPaper(theme?: Theme): boolean;
+/**
+ * The active ground at an alpha, for the gradients artwork fades into. Unlike
+ * `shade()`, which is always the dark ground, this one follows the theme.
+ *
+ * Read it during render: a value taken at module scope freezes to the ground
+ * that happened to be active at import.
+ */
+export declare function groundShade(alpha: number): string;
+/**
+ * A corner in px, for the places that need the number rather than a style
+ * declaration: a <Frost> layer clipping itself, a nested corner, an animated
+ * value. `side` is the box's own side and only `'circle'` reads it.
+ */
+export declare function radiusValue(corner: CornerValue, side?: number): number;
+/** Monotonic; bumped by every `setTheme`. Anything that caches resolved styles
+ *  keys on it (see recipe.ts, styles.ts, box-style.ts). */
+export declare function themeVersion(): number;
+/**
+ * Swaps the active theme, pinned: the store holds it as written, so every
+ * resolved value is this theme's whatever the document's ground says. That is
+ * what `KROMA_LIGHT` means on a browser, and the only shape a platform without
+ * a cascade has.
+ *
+ * Reach for `applyTheme` on a browser instead, unless pinning is the point.
+ */
+export declare function setTheme(theme: Theme, light?: Theme): void;
+/**
+ * Applies a theme through the CASCADE where there is one, which on a browser is
+ * every token but the handful the store owns (see `STORE_TOKENS`).
+ *
+ * A theme that restates nothing but colour therefore costs one stylesheet write
+ * and NOTHING else - no version bump, no re-render, no remount - because the
+ * properties it redefines are the same ones every resolved style already points
+ * at. Only a theme that moves a radius, a face or a type scale reaches the
+ * store, and only that theme pays for the tree to render again.
+ *
+ * `light` is the theme's paper half, for one that restates the ground itself;
+ * without it the theme paints the same values in both grounds. Off the browser
+ * there is no cascade to apply anything to, so this is `setTheme`.
+ */
+export declare function applyTheme(theme: Theme, light?: Theme): void;
+/** Subscribe to theme swaps; returns the unsubscribe. Shaped for
+ *  `useSyncExternalStore`, which is exactly what `useTheme` feeds it to. */
+export declare function onThemeChange(listener: () => void): () => void;
+/**
+ * A value derived from the theme, memoised per swap: call the returned function
+ * at use time and it recomputes only when the theme has changed. This is how a
+ * module holds something theme-flavoured (a gradient string, a paint bundle)
+ * without freezing it to the palette of module-load time.
+ */
+export declare function themed<T>(make: (theme: Theme) => T): () => T;
+/**
+ * The same, keyed: many values behind one memo, emptied on every swap. What a
+ * resolved style, a resolved <Box> prop bag and a resolved icon paint are kept
+ * in.
+ *
+ * Capped, because the key is the caller's and one built from a measured number
+ * would otherwise mint an entry forever; past the cap it computes correctly and
+ * stops remembering.
+ */
+export declare function themedCache<T>(limit: number): (key: string, make: () => T) => T;