@exponential_app/eui 0.0.0-stage → 0.2.0

package/dist/types/src/types.d.ts

@@ -0,0 +1,320 @@
+export type PropType = `string` | `markdown` | `number` | `boolean` | `enum` | `icon` | `color` | `style` | `array` | `object` | `date` | `url`;
+export interface PropSchema {
+    type: PropType;
+    /** Model-facing. VAPP-106: ABSENT at runtime on the runtime catalog (`coreCatalog`) until
+     *  `describeCatalog()` attaches it; typed present because its readers (the prompt, the schema
+     *  emitter, the docs, an extension's validation) always see it attached. */
+    description: string;
+    required?: boolean;
+    default?: unknown;
+    /** Accepts an A2UI data binding `{path}` or a function call instead of a literal. */
+    bindable?: boolean;
+    /** Round 1: ALSO accepts `{base, sm?, md?, lg?, xl?}` (keys = the
+     *  `$breakpoint` token names); the macro expander emits the media blocks. */
+    responsive?: boolean;
+    /** `enum`: the name of a shared list in `enums`, or … */
+    enum?: string;
+    /** … an inline list of values. */
+    values?: readonly (string | number)[];
+    /** `number`: the inclusive bounds a literal must respect (R8 F51: a
+     *  Rating's `max` stops at 100); both validators refuse a value outside. */
+    minimum?: number;
+    maximum?: number;
+    /** `array`: the item schema. */
+    items?: PropSchema;
+    /** `object`: the name of a shared shape in `defs`; none = any object. */
+    shape?: string;
+}
+export interface DefSchema {
+    /** Model-facing. VAPP-106: ABSENT at runtime on the runtime catalog (`coreCatalog`) until
+     *  `describeCatalog()` attaches it; typed present because its readers (the prompt, the schema
+     *  emitter, the docs, an extension's validation) always see it attached. */
+    description: string;
+    properties: Record<string, PropSchema>;
+}
+export type ComponentKind = `native` | `macro`;
+export type ChildrenRule = `none` | `one` | `many`;
+export interface ComponentDef {
+    kind: ComponentKind;
+    group: string;
+    lite: boolean;
+    children: ChildrenRule;
+    /** Named child slots; `["*"]` = any slot name (Table cell templates). */
+    slots?: readonly string[];
+    /** Round 1: `row` = every slot is a per-ROW cell template (Table): the bind
+     *  pass leaves it unbound and the painter binds it once per row with the
+     *  row as its data scope (src/dynamic.ts bindRowSlot). */
+    slotScope?: `row`;
+    /** Never offered to a model (the Unknown placeholder, TreeGuides = a Row part). */
+    hidden?: boolean;
+    /** `planned` = in the catalog, painters land later. */
+    status?: string;
+    /** Model-facing. VAPP-106: ABSENT at runtime on the runtime catalog (`coreCatalog`) until
+     *  `describeCatalog()` attaches it; typed present because its readers (the prompt, the schema
+     *  emitter, the docs, an extension's validation) always see it attached. */
+    description: string;
+    props: Record<string, PropSchema>;
+    events?: readonly string[];
+    /** The docs' and the fixtures' specimen props; absent on the runtime catalog like `description`. */
+    example?: Record<string, unknown>;
+}
+export interface CatalogSource {
+    id: string;
+    liteId: string;
+    name: string;
+    version: string;
+    unknownComponent: string;
+    enums: Record<string, readonly string[]>;
+    defs: Record<string, DefSchema>;
+    functions: {
+        names: readonly string[];
+        core: Record<string, CoreFunctionDef>;
+        basic: Record<string, FunctionSignature>;
+    };
+    /** Round 1: `<Component>.<part>[.<variant>]` → the icons.json name a
+     *  renderer draws for a part it owns (`$comment` aside). */
+    builtinIcons: Record<string, string>;
+    components: Record<string, ComponentDef>;
+}
+/** Round 4: a basic function's signature (core.catalog.json `functions.basic`). */
+export interface FunctionSignature {
+    /** Argument name → its type (`number`, `string`, `boolean`, `array`, `object`, `any`). */
+    args: Record<string, string>;
+    returns: string;
+}
+/** Round 1: one core function (core.catalog.json `functions.core`). */
+export interface CoreFunctionDef {
+    /** Model-facing. VAPP-106: ABSENT at runtime on the runtime catalog (`coreCatalog`) until
+     *  `describeCatalog()` attaches it; typed present because its readers (the prompt, the schema
+     *  emitter, the docs, an extension's validation) always see it attached. */
+    description: string;
+    /** Argument name → its type (`number`, `string`, `boolean`, `array`, `object`, `any`). */
+    args: Record<string, string>;
+    returns: string;
+}
+/** A child entry of a macro template: a part, the author's children
+ *  (`$children`) or one of the author's slots spliced in place (`$slot:name`). */
+export type MacroChild = MacroTemplate | `$children` | `$slot:${string}`;
+/** A macro template node (catalog/macros.json). */
+export interface MacroTemplate {
+    part: string;
+    component: string;
+    props?: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    children?: MacroChild[];
+    /** `$slot:name` copies the author's slot; a template node builds a part. */
+    slots?: Record<string, string | MacroTemplate>;
+    $if?: unknown;
+    $any?: unknown[];
+    $each?: string;
+    $as?: string;
+    $on?: Record<string, string>;
+    $context?: Record<string, unknown>;
+    $recipe?: Record<string, unknown>;
+    /** Round 1 two-way binding: per part event, the macro prop a bound author
+     *  value is written back to (`set`) and the template value it takes. */
+    $set?: Record<string, {
+        prop: string;
+        value: unknown;
+    }>;
+    /** Round 1 (docs/round-1-contract.md §6): the part's accessibility — a
+     *  machine-readable `role` (catalog/a11y.json `roles`), its states and an
+     *  accessible name — evaluated like any template value (bound inputs emit
+     *  calls) into the expanded node's `accessibility`. */
+    $a11y?: Record<string, unknown>;
+}
+export interface MacroDef {
+    recipeProps: readonly string[];
+    root: MacroTemplate;
+}
+/** An extension catalog: its own id, extending the core, with components and
+ *  the macro templates for its macro components. */
+export interface ExtensionDef {
+    id: string;
+    name: string;
+    /** VAPP-161: `MAJOR.MINOR.PATCH`, what a package's `extensions` entry
+     *  is checked against (caret); unset = satisfies any. */
+    version?: string;
+    extends: string;
+    enums?: Record<string, readonly string[]>;
+    defs?: Record<string, DefSchema>;
+    components: Record<string, ComponentDef>;
+    macros?: Record<string, MacroDef>;
+}
+/** An A2UI v0.9 data binding or function call, passed through untouched. */
+export interface DataBinding {
+    path: string;
+}
+export interface FunctionCall {
+    call: string;
+    args?: Record<string, unknown>;
+    returnType?: string;
+}
+/** An A2UI v0.9 Action: a server event or a client function. Round 1: the
+ *  expander may emit BOTH (a routed event plus a `set` write); a renderer
+ *  evaluates the function args and the event context first, then runs the
+ *  function, then dispatches the event. */
+export interface Action {
+    event?: {
+        name: string;
+        context?: Record<string, unknown>;
+    };
+    /** A2UI v0.9's client function action (round 4: the ONLY key). */
+    functionCall?: FunctionCall;
+}
+/** A data-driven child list: one `component` per item at `path`; `key` = a
+ *  pointer relative to the item that identifies it (reordering keeps the
+ *  item's state), the index when absent. */
+export interface ChildTemplate {
+    component: string;
+    path: string;
+    key?: string;
+}
+/** The wire form of a template child list (A2UI's `{componentId, path}`,
+ *  plus round 1's optional `key`). */
+export interface WireChildTemplate {
+    componentId: string;
+    path: string;
+    key?: string;
+}
+/** The common `visible` value: a literal boolean or a dynamic value the
+ *  renderer resolves (truthiness as `expr.ts truthy`: undefined, null, false
+ *  and "" hide; 0 shows). Absent = visible. */
+export type Visible = boolean | DataBinding | FunctionCall;
+/** A2UI's AccessibilityAttributes: `label`/`description` are DynamicStrings
+ *  (a literal, a binding or a call; the bind pass resolves them). */
+export interface AuthoredAccessibility {
+    label?: unknown;
+    description?: unknown;
+}
+/** Round 1 (docs/round-1-contract.md §6): the accessibility a NORMALIZED node
+ *  carries: the author's label/description, plus what a macro part's `$a11y`
+ *  adds (an author's label/description on a macro win over its root's). Every
+ *  value may be dynamic until the bind pass. A painter maps `role` (one of
+ *  catalog/a11y.json `roles`) and the states onto the platform: ARIA
+ *  role/aria-*, SwiftUI traits/values, Compose semantics, AccessKit. */
+export interface NodeAccessibility extends AuthoredAccessibility {
+    /** One of `A11Y_ROLES`; absent = the component's own (a11y.json). */
+    role?: unknown;
+    /** Heading level 1..6 (role heading). */
+    level?: unknown;
+    /** A disclosure's state (aria-expanded). */
+    expanded?: unknown;
+    /** `page`, `step` or false (aria-current). */
+    current?: unknown;
+    /** A selected option, tab or row (aria-selected). */
+    selected?: unknown;
+    /** A toggle button's state (aria-pressed). */
+    pressed?: unknown;
+    /** A checkbox/radio state (aria-checked). */
+    checked?: unknown;
+    /** Progressbar/meter/slider values (aria-valuenow/min/max). */
+    valueNow?: unknown;
+    valueMin?: unknown;
+    valueMax?: unknown;
+    /** True = out of the accessibility tree (decorative). */
+    hidden?: unknown;
+    /** True = focus lands here when the enclosing dialog opens. */
+    autoFocus?: unknown;
+}
+/** A node as it rides A2UI's `updateComponents`: props at the top level,
+ *  children by id. The core catalog keeps that convention. */
+export interface FlatComponent {
+    id: string;
+    component: string;
+    children?: string[] | WireChildTemplate;
+    slots?: Record<string, string>;
+    on?: Record<string, Action>;
+    style?: Record<string, unknown>;
+    visible?: Visible;
+    accessibility?: AuthoredAccessibility;
+    [prop: string]: unknown;
+}
+/** A node of the NORMALIZED tree every painter reads: core vocabulary, props
+ *  under `props`, children nested, macros expanded (`recipe` names the macro
+ *  part a theme styles). */
+export interface UiNode {
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    /** Round 1: falsy once resolved = the node is not rendered and takes no
+     *  layout space; the expander sets it for a part whose `$if` was bound. */
+    visible?: Visible;
+    on?: Record<string, Action>;
+    accessibility?: NodeAccessibility;
+    children: UiNode[];
+    slots?: Record<string, UiNode>;
+    template?: ChildTemplate;
+    /** `authored` (VAPP-163, expansion roots only): the top-level style keys
+     *  written ON the macro node, sorted; they win over the part recipe. */
+    recipe?: {
+        macro: string;
+        part: string;
+        props: Record<string, unknown>;
+        authored?: string[];
+    };
+}
+/** The nested authoring form (fixtures, kitchen sink): the same as UiNode
+ *  minus what the reducer fills in. */
+export interface NestedNode {
+    id: string;
+    component: string;
+    props?: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    visible?: Visible;
+    on?: Record<string, Action>;
+    accessibility?: AuthoredAccessibility;
+    children?: NestedNode[];
+    slots?: Record<string, NestedNode>;
+    template?: ChildTemplate;
+}
+export interface ReduceIssue {
+    id: string;
+    message: string;
+}
+/** Round 1 (docs/round-1-contract.md §4–6): what a host sets per surface.
+ *  Every field is optional; the defaults are what a renderer assumes. */
+export interface SurfaceSettings {
+    /** BCP 47; drives the format functions, calendar names, the week start
+     *  and the text direction (catalog/locale.json). Default `en-US`. */
+    locale?: string;
+    /** Round 2: the IANA zone instants format in (the host Formatter's;
+     *  default the platform's; the English fallback and the fixtures: UTC). */
+    timeZone?: string;
+    /** Built-in UI string overrides by id (catalog/strings.json). */
+    strings?: Record<string, string>;
+    /** `system` (default) = the platform's light/dark preference. */
+    mode?: `light` | `dark` | `system`;
+    /** Scales `$control.*` and `$spacing.*` by the theme's `$density.*`. */
+    density?: `compact` | `default` | `comfortable`;
+    /** `system` (default) = the platform's high-contrast setting; `high`
+     *  forces the theme's `contrast` overlays. */
+    contrast?: `normal` | `high` | `system`;
+    /** The theme id (a built-in or one the host loaded). */
+    theme?: string;
+}
+/** Round 1 (catalog/a11y.json `commands`): what a host may ask of a live
+ *  surface. */
+export type SurfaceCommand = {
+    focus: {
+        id: string;
+    };
+} | {
+    announce: {
+        text: string;
+        live?: `polite` | `assertive`;
+    };
+} | {
+    scrollIntoView: {
+        id: string;
+    };
+}
+/** Round 2: bring item `index` (data order) of List/Table `id` into view. */
+ | {
+    scrollToIndex: {
+        id: string;
+        index: number;
+        align?: `start` | `center` | `end` | `nearest`;
+    };
+};

package/dist/types/src/validate.d.ts

@@ -0,0 +1,31 @@
+import { isDynamic } from "./expr.js";
+import type { ComponentDef, ExtensionDef } from "./types.js";
+export interface PropIssue {
+    path: string;
+    message: string;
+}
+export { isDynamic };
+/** A function name a surface may call: a catalog function, or a HOST
+ *  function, which is always namespaced (`app.toast`, `harness.openIssue`). */
+export declare function isCallableName(name: string): boolean;
+/** What validateProps leaves out, round 4 (VAPP-103): the node's `style`
+ *  (whitelisted keys, known tokens, `$color.*` colours), every function a
+ *  prop (along its schema: never inside DATA), `visible` or an `on` action
+ *  calls, and a Table's slot columns (each `type: slot` column names one of
+ *  the node's slots). In this order; the Rust core
+ *  (`validate::validate_node`) reports the same issues. */
+export declare function validateNode(node: {
+    component: string;
+    props: Record<string, unknown>;
+    style?: unknown;
+    visible?: unknown;
+    on?: Record<string, unknown>;
+    slots?: Record<string, unknown>;
+}, options?: {
+    extensions?: readonly ExtensionDef[];
+}): PropIssue[];
+/** Every issue in a node's props against its component definition. */
+export declare function validateProps(def: ComponentDef, props: Record<string, unknown>, options?: {
+    path?: string;
+    extensions?: readonly ExtensionDef[];
+}): PropIssue[];

package/dist/types/src/voice-wave.d.ts

@@ -0,0 +1,181 @@
+export declare const VOICE_WAVE: {
+    $comment: string;
+    steps: number;
+    radius: number[];
+    harmonics: number[][];
+    phase0: number[];
+    ringAmp: number[];
+    ampBase: number;
+    ampLevel: number;
+    thinkingAmp: number;
+    phaseSpeed: number;
+    fillAlpha: number[];
+    strokeAlpha: number[];
+    strokeWidth: number[];
+    childScale: number;
+    childScaleLarge: number;
+    maxBands: number;
+    bars: {
+        $comment: string;
+        count: number;
+        minFraction: number;
+        envelope: number;
+        shapeFreq: number;
+        shapeBase: number;
+        sizes: {
+            sm: {
+                height: number;
+                barWidth: number;
+                gap: number;
+            };
+            md: {
+                height: number;
+                barWidth: number;
+                gap: number;
+            };
+            lg: {
+                height: number;
+                barWidth: number;
+                gap: number;
+            };
+            xl: {
+                height: number;
+                barWidth: number;
+                gap: number;
+            };
+        };
+    };
+};
+export declare const VOICE_WAVE_ACTIVITIES: readonly ["idle", "listening", "thinking", "speaking", "muted"];
+export type VoiceWaveActivity = (typeof VOICE_WAVE_ACTIVITIES)[number];
+export declare const VOICE_WAVE_RINGS: readonly ["outer", "mid", "inner"];
+export type VoiceWaveRingName = (typeof VOICE_WAVE_RINGS)[number];
+export interface VoiceWaveInput {
+    /** The box edge in px (the root recipe's width). */
+    size: number;
+    activity: VoiceWaveActivity;
+    /** 0..1; clamped. */
+    level?: number;
+    /** 0..1 each; the first `maxBands` count, clamped. */
+    bands?: readonly number[];
+    /** Seconds since the wave started animating (ignored when idle or muted). */
+    elapsed?: number;
+    reducedMotion?: boolean;
+    /** The one child's own laid-out size (the core centres it at that size). */
+    child?: {
+        width: number;
+        height: number;
+    };
+}
+/** Where the painter draws the child: its own box scaled about the wave's
+ *  centre by `scale` = min(1, childSize / its longer edge), never up; 0 =
+ *  kept in the tree but not painted (`sm`). */
+export interface VoiceWaveChildBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+}
+export interface VoiceWaveRing {
+    /** The recipe part that colours it. */
+    part: VoiceWaveRingName;
+    /** `steps + 1` points, x/y in px from the box's top-left (the last repeats the first). */
+    points: Array<[number, number]>;
+    fillAlpha: number;
+    strokeAlpha: number;
+    strokeWidth: number;
+}
+export interface VoiceWave {
+    rings: VoiceWaveRing[];
+    /** The centre child's edge in px; 0 = the child is not painted (`sm`). */
+    childSize: number;
+    /** The phase the rings were drawn at (radians). */
+    phase: number;
+    /** Present when the input gave the child's size. */
+    child?: VoiceWaveChildBox;
+}
+/** The phase a painter draws at `elapsed` seconds. */
+export declare function voiceWavePhase(raw: VoiceWaveActivity, elapsed: number, reducedMotion?: boolean): number;
+/** The child's edge for a box `size` (the size enum's px, sm 32 · md 56 · lg 160 · xl 200). */
+export declare function voiceWaveChildSize(size: number): number;
+/** The child's painted box in a wave of edge `size` (see VoiceWaveChildBox). */
+export declare function voiceWaveChildBox(size: number, child: {
+    width: number;
+    height: number;
+}): VoiceWaveChildBox;
+/** The three rings for one frame. Coordinates are rounded to 0.01 px. */
+/** The activity as the catalog names it; anything else (a bound string, a
+ *  typo) is `idle`, in every renderer (the Rust core: `#[serde(other)]`). */
+export declare function voiceWaveActivity(value: unknown): VoiceWaveActivity;
+export declare function voiceWave(raw: VoiceWaveInput): VoiceWave;
+/** An SVG path (`M … L … Z`) for a ring: what the web painters set as `d`. */
+export declare function voiceWavePath(ring: VoiceWaveRing): string;
+export declare const VOICE_WAVE_BARS: {
+    $comment: string;
+    count: number;
+    minFraction: number;
+    envelope: number;
+    shapeFreq: number;
+    shapeBase: number;
+    sizes: {
+        sm: {
+            height: number;
+            barWidth: number;
+            gap: number;
+        };
+        md: {
+            height: number;
+            barWidth: number;
+            gap: number;
+        };
+        lg: {
+            height: number;
+            barWidth: number;
+            gap: number;
+        };
+        xl: {
+            height: number;
+            barWidth: number;
+            gap: number;
+        };
+    };
+};
+export declare const VOICE_WAVE_SIZES: readonly ["sm", "md", "lg", "xl"];
+export type VoiceWaveSizeName = (typeof VOICE_WAVE_SIZES)[number];
+export declare const VOICE_WAVE_VARIANTS: readonly ["ring", "bars"];
+export type VoiceWaveVariant = (typeof VOICE_WAVE_VARIANTS)[number];
+/** The variant as the catalog names it; anything else is `ring`. */
+export declare function voiceWaveVariant(value: unknown): VoiceWaveVariant;
+export interface VoiceWaveBarsInput {
+    /** The size class (an unknown one is `md`). */
+    size: VoiceWaveSizeName;
+    activity: VoiceWaveActivity;
+    level?: number;
+    bands?: readonly number[];
+    elapsed?: number;
+    reducedMotion?: boolean;
+}
+export interface VoiceWaveBar {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+}
+export interface VoiceWaveBars {
+    /** The root box: count × barWidth + (count − 1) × gap wide, `height` tall. */
+    width: number;
+    height: number;
+    phase: number;
+    bars: VoiceWaveBar[];
+}
+/** The box of a `bars` meter for a size class. */
+export declare function voiceWaveBarsBox(raw: unknown): {
+    width: number;
+    height: number;
+    barWidth: number;
+    gap: number;
+};
+/** The bars for one frame (style.json `voiceWave.bars` $comment). */
+export declare function voiceWaveBars(raw: VoiceWaveBarsInput): VoiceWaveBars;

package/dist/types/src/web/base-css.d.ts

@@ -0,0 +1 @@
+export declare const BASE_CSS: string;

package/dist/types/src/web/box-css.d.ts

@@ -0,0 +1,63 @@
+import { type FontSpec, type ResolvedTheme, type UiNode } from "@exponential_app/eui";
+export declare const nodeClass: (id: string) => string;
+export declare const surfaceClass: (surfaceId: string) => string;
+/** Ids are author strings; keep the class usable in a selector. */
+export declare function cssEscape(text: string): string;
+export declare function walkNodes(root: UiNode): Generator<UiNode>;
+/** One dynamic style value of a node: where it sits and its variable. */
+export interface DynamicStyleEntry {
+    /** `--xd-<n>`, numbered in walk order (base keys, then each block). */
+    name: string;
+    /** The condition key (`@media …`, `:hover`) or `` for the base style. */
+    block: string;
+    key: string;
+    value: unknown;
+}
+/** The node's dynamic style values in the order the sheet numbers them. */
+export declare function dynamicStyleEntries(style: Record<string, unknown> | undefined): DynamicStyleEntry[];
+/** A JS-evaluated condition (height / orientation): its `data-xq` token. */
+export declare function queryToken(key: string): string;
+export interface NodeSheet {
+    css: string;
+    /** The resolved condition keys the surface must evaluate itself and list
+     *  in `data-xq` when they hold (height, orientation). */
+    queries: string[];
+    /** VAPP-152: each styled node's rules by id, in walk order (`css` is
+     *  their concatenation inside the `xui-node` layer). VAPP-163: a node
+     *  with authored keys appends `AUTHOR_SEP` + its `xui-author` rules;
+     *  `layeredCss` splits them into the two layers. */
+    chunks: ReadonlyMap<string, string>;
+}
+/** The key a surface evaluates itself for a `@media` block (size values
+ *  resolved to px: `@media (min-width: 768px)`); null = never matches. */
+export declare function resolvedMediaKey(key: string, theme: ResolvedTheme | undefined): string | null;
+/** A node's own `direction` (round 2 §2): its base style's, then every
+ *  MATCHING `@media` block's in source order (later wins), as
+ *  `resolveConditions` flattens it; `matches` = the surface's `data-xq`. */
+export declare function styleDirection(style: Record<string, unknown> | undefined, theme: ResolvedTheme | undefined, matches: (resolvedKey: string) => boolean): `ltr` | `rtl` | undefined;
+/** VAPP-163: separates a chunk's `xui-node` rules from its `xui-author`
+ *  rules (NUL never survives in CSS, so it never occurs in a rule). */
+export declare const AUTHOR_SEP = "\0";
+/** Chunks (`NodeSheet.chunks`) as one stylesheet: every node's rules in the
+ *  `xui-node` layer, then the authored ones in `xui-author`. */
+export declare function layeredCss(chunks: Iterable<string>): string;
+/** The node sheet for one tree (plus the template subtrees it renders). */
+export declare function compileNodeSheet(roots: readonly UiNode[], surfaceId: string, theme?: ResolvedTheme, fonts?: Record<string, FontSpec>): NodeSheet;
+/** VAPP-152: one `<style>` of the node sheet: the rules of some nodes. */
+export interface NodeSheetBatch {
+    readonly chunks: ReadonlyMap<string, string>;
+    readonly css: string;
+}
+/** VAPP-152: the node sheet as `<style>` batches, the last ones kept. A
+ *  rewritten stylesheet makes Chromium re-match every node its rules
+ *  select, so a batch whose rules are all unchanged keeps its OBJECT (the
+ *  renderers leave its element alone), a batch with a changed or removed
+ *  node is rewritten in place, and the new nodes' rules land in ONE new
+ *  batch at the end (a streamed card restyles only itself). A batch at
+ *  least as large as the one before it merges into it (a binary counter:
+ *  at most log2(n) batches, each node rewritten O(log n) times). Rules of
+ *  different nodes never select the same element, so the order of the
+ *  batches does not change the cascade. */
+export declare function nodeSheetBatches(prev: readonly NodeSheetBatch[], chunks: ReadonlyMap<string, string>): NodeSheetBatch[];
+/** The node sheet's CSS for one tree (the VAPP-87 entry point). */
+export declare function nodeSheet(root: UiNode, surfaceId: string, fontsOrTheme?: Record<string, FontSpec> | ResolvedTheme, extra?: readonly UiNode[]): string;

package/dist/types/src/web/coerce.d.ts

@@ -0,0 +1,32 @@
+export declare const str: (v: unknown, fallback?: string) => string;
+export declare const num: (v: unknown, fallback?: number) => number;
+export declare const bool: (v: unknown) => boolean;
+export declare const arr: <T>(v: unknown) => T[];
+/** An array of OBJECTS (options, items, tabs, columns, rows…): entries that
+ *  are not objects (`options: [null]`) are skipped, never painted. */
+export declare const objects: <T>(v: unknown) => T[];
+/** A built-in PHRASE with placeholders (`removeItem` = `Remove {name}`):
+ *  the surface's string table entry when it carries `id` (word order is the
+ *  translation's), else `fallback()`, the round-1 composition kept until
+ *  catalog/strings.json ships the id. */
+export declare function phrase(ctx: {
+    strings: Readonly<Record<string, string>>;
+    t: (id: string, params?: Record<string, unknown>) => string;
+}, id: string, params: Record<string, unknown>, fallback: () => string): string;
+/** A byte count in the surface locale with a LOCALIZED unit (1024 steps,
+ *  `Intl.NumberFormat` `style: "unit"`, e.g. `1,5 kB` / `١٫٥ ك.بايت`). */
+export declare function formatFileSize(bytes: number, locale: string): string;
+/** Does a file match an `accept` list (`image/*,.pdf`)? */
+export declare function acceptsFile(accept: string, file: {
+    name: string;
+    type: string;
+}): boolean;
+/** A control's `checks` evaluated: EVERY failing message, in order (a
+ *  check without one says `$string.invalidValue`: pass the surface's). */
+export declare function failingChecks(checks: unknown, fallback?: string): string[];
+/** The first failing message, or null (kept for hosts that used it). */
+export declare function failingCheck(checks: unknown, fallback?: string): string | null;
+/** The icons.json name a renderer draws for an owned part. */
+export declare function builtinIconName(slot: string): string;
+/** Space-joined element ids (`aria-describedby`), undefined when none. */
+export declare function joinIds(...ids: (string | undefined | false)[]): string | undefined;

package/dist/types/src/web/custom-icons.generated.d.ts

@@ -0,0 +1,4 @@
+/** One Lucide icon node: an element name and its attributes. */
+export type CustomIconNode = [string, Record<string, string>][];
+/** icons.json `custom` + `imported` names -> their Lucide icon nodes. */
+export declare const CUSTOM_ICON_NODES: Record<string, CustomIconNode>;