@exponential-at/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,205 @@
+import type { ResolvedTheme } from "../theme-types.js";
+import type { ExtensionDef, FlatComponent, ReduceIssue, UiNode } from "../types.js";
+import type { ClientMessage, HostOp } from "./contract.js";
+import type { PackageIssue, AppPackage } from "./package.js";
+import type { FunctionDecision, FunctionPolicy, MediaOptions, MediaRequest, UrlPolicy } from "./policy.js";
+import { HostRouter } from "./router.js";
+import type { SourceResolvers } from "./sources.js";
+export type TransportStatus = `connecting` | `open` | `closed` | `error`;
+/** Messages in, client messages out. Adapters: `transports.ts`. */
+export interface Transport {
+    /** Start delivering messages; report the connection state. */
+    start(receive: (message: unknown) => void, status: (status: TransportStatus, detail?: string) => void): void;
+    send(message: ClientMessage): void | Promise<void>;
+    close(): void;
+}
+export interface FunctionCallInfo {
+    surfaceId: string;
+    componentId: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export type HostFunction = (args: Record<string, unknown>, call: FunctionCallInfo) => unknown | Promise<unknown>;
+export interface HostPolicy {
+    /** The declarative gate; `ask` decisions go to onFunctionCall. */
+    functions?: FunctionPolicy;
+    /** The consent hook: true runs the call. Unset = `ask` is denied. */
+    onFunctionCall?: (call: FunctionCallInfo) => boolean | Promise<boolean>;
+    urls?: UrlPolicy;
+    /** Opens an allowed url (default: `window.open(url, "_blank")`). */
+    openUrl?: (url: string) => void;
+    media?: MediaOptions;
+}
+export interface HostOptions {
+    transport?: Transport;
+    functions?: Record<string, HostFunction>;
+    sources?: SourceResolvers;
+    extensions?: readonly ExtensionDef[];
+    packages?: readonly AppPackage[];
+    policy?: HostPolicy;
+    /** Every client message that leaves (after the transport got it). */
+    onSend?: (message: ClientMessage) => void;
+    /** Ops the host performs (tests, logging). */
+    onOp?: (op: HostOp) => void;
+    /** Every problem the host meets (a package that failed validation, an
+     *  error it answered a message with, an invalid surface theme). A
+     *  transport-less host has no server to tell: this is where they land. */
+    onIssue?: (issue: HostIssue) => void;
+}
+/** One problem the host met; `host.issues` keeps the latest ones. */
+export interface HostIssue {
+    /** A host error code (`TEMPLATE_NOT_FOUND`…) or `PACKAGE_INVALID`. */
+    code: string;
+    message: string;
+    surfaceId?: string;
+    /** A JSON pointer (into the package or the message). */
+    path?: string;
+    packageId?: string;
+}
+/** A package passed in `HostOptions.packages` that failed validation. */
+export declare class PackageError extends Error {
+    readonly packageId: string;
+    readonly issues: PackageIssue[];
+    constructor(packageId: string, issues: PackageIssue[]);
+}
+/** A `createSurface.theme` (a built-in id or a theme JSON) → the resolved
+ *  theme, or why it is unusable. */
+export declare function resolveSurfaceTheme(input: unknown): {
+    theme: ResolvedTheme | null;
+    issues: string[];
+};
+export interface FunctionOutcome {
+    decision: FunctionDecision;
+    result?: unknown;
+    error?: string;
+}
+type Listener = () => void;
+/** One surface's state: the flat components, the data model, the reduced
+ *  tree. Mutations notify subscribers; `root` is reduced lazily. */
+export declare class SurfaceStore {
+    private extensions;
+    readonly surfaceId: string;
+    catalogId: string;
+    packageId?: string;
+    sendDataModel: boolean;
+    /** The flat components, mutated in place while nothing holds them. */
+    private list;
+    /** `list` was handed out (`components`): the next update copies first. */
+    private shared;
+    private positions;
+    data: Record<string, unknown>;
+    /** The server's `createSurface.theme`, resolved (undefined = the
+     *  renderer's own theme). */
+    theme?: ResolvedTheme;
+    private reduced;
+    private listeners;
+    version: number;
+    constructor(surfaceId: string, catalogId: string, extensions: () => readonly ExtensionDef[]);
+    /** The flat components as a SNAPSHOT: an array handed out here is never
+     *  mutated afterwards (the next update copies first), so a renderer that
+     *  keeps it sees a stable value; a stream nobody reads stays linear. */
+    get components(): readonly FlatComponent[];
+    /** The flat component with this id (undefined = none). */
+    component(id: string): FlatComponent | undefined;
+    get root(): UiNode | null;
+    get issues(): ReduceIssue[];
+    /** Round 2 §4: the reducer's lifted data templates (absent without any). */
+    get templates(): Record<string, UiNode> | undefined;
+    private reduce;
+    /** A2UI: a later update replaces components BY ID and keeps the rest
+     *  (an id → position map: a streamed surface costs linear, VAPP-103). */
+    setComponents(components: readonly FlatComponent[]): void;
+    /** Re-reduce on the next read (the extension set changed). */
+    invalidate(): void;
+    /** Write the data model at `pointer` (`undefined` removes); a refused
+     *  write (writePointer) changes nothing and returns the reason. */
+    setData(pointer: string, value: unknown): string | undefined;
+    subscribe(listener: Listener): () => void;
+    notify(): void;
+}
+export declare class ExponentialHost {
+    private options;
+    readonly router: HostRouter;
+    private stores;
+    private subscriptions;
+    /** Per surface: the FLAT component owning a failed node → that
+     *  component as it was when it failed + the node ids already reported. */
+    private paintErrors;
+    private listeners;
+    private functions;
+    private sources;
+    private extensions;
+    status: TransportStatus;
+    statusDetail?: string;
+    /** The last UNSUPPORTED_CATALOG id seen (the catalog-update banner). */
+    unsupportedCatalog?: string;
+    /** The latest problems (newest last, capped); a new array per change. */
+    issues: readonly HostIssue[];
+    constructor(options?: HostOptions);
+    /** False for a local-only host (packages, in-memory feeds): no
+     *  `host_offline` state to show. */
+    get hasTransport(): boolean;
+    get supportedCatalogIds(): string[];
+    clientCapabilities(): {
+        "v0.9": {
+            supportedCatalogIds: string[];
+        };
+    };
+    get extensionDefs(): readonly ExtensionDef[];
+    registerExtension(ext: ExtensionDef): void;
+    registerFunction(name: string, fn: HostFunction): void;
+    registerSource(scheme: string, resolver: SourceResolvers[string]): void;
+    /** Install a package; its validation issues are returned AND reported
+     *  (`issues`, `onIssue`). A package with issues is not installed. */
+    installPackage(pkg: AppPackage): PackageIssue[];
+    private report;
+    surface(id: string): SurfaceStore | undefined;
+    surfaceIds(): string[];
+    subscribe(listener: Listener): () => void;
+    private notify;
+    connect(): void;
+    close(): void;
+    /** One server message (a transport calls this; tests and in-memory hosts
+     *  may call it directly). */
+    receive(message: unknown): HostOp[];
+    send(message: ClientMessage): void;
+    private perform;
+    private unbind;
+    /** A component's server event: the A2UI client action message. */
+    action(event: {
+        surfaceId: string;
+        componentId: string;
+        name: string;
+        context?: Record<string, unknown>;
+        payload?: Record<string, unknown>;
+        timestamp?: string;
+    }): ClientMessage;
+    /** The policy decision for a call, before any consent hook. */
+    decide(surfaceId: string, name: string): FunctionDecision;
+    /** An action `functionCall` to a host function: gate, consent, run. A
+     *  built-in other than openUrl has no effect as an action. */
+    callFunction(call: FunctionCallInfo): Promise<FunctionOutcome>;
+    /** The URL policy every href passes (relative urls against the urls' or
+     *  the media `baseUrl`). */
+    urlPolicy(): UrlPolicy;
+    /** openUrl / Link through the URL policy. True when it opened. */
+    openUrl(url: string): boolean;
+    /** A renderer's painter for `componentId` failed. Reported ONCE per
+     *  surface + component id (whatever the message) as an A2UI
+     *  `RENDER_FAILED` error (and so a host issue), and not again until that
+     *  component's props change (an `updateComponents` naming it, or the
+     *  surface re-created). A part or template-instance id counts under the
+     *  flat component it belongs to (`card.body` → `card`), so the record is
+     *  bounded by the surface's components. */
+    paintError(error: {
+        surfaceId: string;
+        componentId: string;
+        message: string;
+    }): void;
+    private forgetPaintErrors;
+    /** The media policy every src passes (`policy.media`). */
+    mediaOptions(): MediaOptions | undefined;
+    /** The image loader's request (absolute url + auth headers). */
+    mediaRequest(url: string): MediaRequest | null;
+}
+export {};

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

@@ -0,0 +1,15 @@
+export interface ParsedSource {
+    /** The source as written. */
+    uri: string;
+    scheme: string;
+    name: string;
+    params: Record<string, string>;
+}
+/** `exp:issues?board=b1&limit=20` → `{scheme: "exp", name: "issues",
+ *  params: {board: "b1", limit: "20"}}`; null when it does not parse. */
+export declare function parseSource(uri: string): ParsedSource | null;
+/** What a resolver emits into: the value lands at the bound path. */
+export type SourceEmit = (value: unknown) => void;
+/** A scheme's resolver: start following `source`, return the cancel. */
+export type SourceResolver = (source: ParsedSource, emit: SourceEmit) => (() => void) | void;
+export type SourceResolvers = Record<string, SourceResolver>;

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

@@ -0,0 +1,109 @@
+import type { ClientMessage } from "./contract.js";
+import { JsonlDecoder, SseDecoder } from "./decoders.js";
+import type { Decoded } from "./decoders.js";
+import type { Transport, TransportStatus } from "./runtime.js";
+type Receive = (message: unknown) => void;
+type Status = (status: TransportStatus, detail?: string) => void;
+/** In-memory: `feed` messages in, read what the host sent from `sent`. */
+export declare class MemoryTransport implements Transport {
+    readonly sent: ClientMessage[];
+    private receiveFn?;
+    private pending;
+    onSend?: (message: ClientMessage) => void;
+    start(receive: Receive, status: Status): void;
+    feed(...messages: unknown[]): void;
+    /** JSONL text, as a stream server would send it. */
+    feedJsonl(text: string): void;
+    send(message: ClientMessage): void;
+    close(): void;
+}
+export interface HttpTransportOptions {
+    /** The stream to read (GET). */
+    url: string;
+    /** Where client messages go (POST, JSON body); default `url`. */
+    postUrl?: string;
+    headers?: Record<string, string>;
+    /** Reconnect after a drop (an error or an aborted stream), ms (0 =
+     *  never). Default 2000. */
+    reconnectMs?: number;
+    /** Reconnect after a CLEAN end of the stream too (the server resumes it).
+     *  Default false: a stream that ends is done (status `closed`). An SSE
+     *  stream that sent a `retry:` field signals this itself. */
+    resumable?: boolean;
+    fetch?: typeof fetch;
+}
+declare abstract class StreamTransport implements Transport {
+    protected options: HttpTransportOptions;
+    private controller?;
+    /** Bumped by every start/close: a loop whose generation is stale exits
+     *  (an old loop asleep in its reconnect wait never runs beside a new
+     *  one). */
+    private generation;
+    constructor(options: HttpTransportOptions);
+    protected abstract decoder(): {
+        push(chunk: string): Decoded;
+        end(): Decoded;
+        retryMs?: number;
+    };
+    protected abstract accept(): string;
+    start(receive: Receive, status: Status): void;
+    private run;
+    send(message: ClientMessage): Promise<void>;
+    close(): void;
+}
+/** A2UI JSONL over a streamed HTTP response (`application/jsonl`). */
+export declare class JsonlStreamTransport extends StreamTransport {
+    protected decoder(): JsonlDecoder;
+    protected accept(): string;
+}
+/** Server-Sent Events read through fetch (headers allowed, unlike
+ *  EventSource). */
+export declare class SseTransport extends StreamTransport {
+    protected decoder(): SseDecoder;
+    protected accept(): string;
+}
+/** One A2UI message (or JSONL) per frame; client messages go back as
+ *  frames. */
+export declare class WebSocketTransport implements Transport {
+    private options;
+    private socket?;
+    /** Bumped by every start/close: a stale socket's reconnect timer is a
+     *  no-op. */
+    private generation;
+    constructor(options: {
+        url: string;
+        protocols?: string | string[];
+        reconnectMs?: number;
+        WebSocket?: typeof WebSocket;
+    });
+    start(receive: Receive, status: Status): void;
+    send(message: ClientMessage): void;
+    close(): void;
+}
+export interface McpTransportOptions {
+    /** The MCP server's streamable-HTTP endpoint. */
+    url: string;
+    /** The tool whose result carries the surface (called once at start). */
+    tool: string;
+    arguments?: Record<string, unknown>;
+    /** The tool client messages go to; default `a2ui_event`. */
+    actionTool?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+/** A2UI over MCP: calls `tool`, delivers the A2UI resources in its result,
+ *  and sends every client message as a tools/call to `actionTool` (its
+ *  result may carry more messages). JSON-RPC over plain POST; an SSE
+ *  response body is read through the SSE decoder. */
+export declare class McpTransport implements Transport {
+    private options;
+    private id;
+    private receiveFn?;
+    private session?;
+    constructor(options: McpTransportOptions);
+    start(receive: Receive, status: Status): void;
+    send(message: ClientMessage): Promise<void>;
+    close(): void;
+    private rpc;
+}
+export {};

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

@@ -0,0 +1,63 @@
+export * from "./types.js";
+export { CORE_CATALOG_ID, CORE_LITE_CATALOG_ID, A2UI_BASIC_CATALOG_ID, A2UI_VERSION, SUPPORTED_CATALOG_IDS, UNKNOWN_COMPONENT, TOKEN_GROUPS, coreCatalog, coreMacros, catalogView, sharedCatalogView, componentDef, componentNames, coreLite, isOffered, parseTokenRef, isKnownToken, } from "./catalog.js";
+export type { CatalogView } from "./catalog.js";
+export * from "./catalog.generated.js";
+export { STYLE_KEYS, STYLE_LAYOUT_KEYS, STYLE_VISUAL_KEYS, STYLE_LAYOUT_EFFECT_KEYS, STYLE_MEDIA, STYLE_STATES, STYLE_TRANSFORM, validateStyle, create, props, parseMediaCondition, mediaMatches, resolveConditions, activeBreakpoint, styleKeyEnum, styleKeyType, } from "./style.js";
+export type { Style, StyleProps, MediaKey, StateKey, StyleIssue, Gradient, ConditionContext, MediaCondition } from "./style.js";
+export { validateProps, validateNode, isCallableName, isDynamic } from "./validate.js";
+export type { PropIssue } from "./validate.js";
+export { evalValue, evalExpr, evalCondition, evalConditionValue, truthy, isBinding, isCall, percent, valuesEqual, clampNumber, fillTemplate, filterItems, CORE_FUNCTIONS, CORE_FUNCTION_NAMES } from "./expr.js";
+export type { ExprContext, Dynamic } from "./expr.js";
+export { expandMacros, isResponsiveValue, responsiveAt, propsAt, BREAKPOINTS } from "./macros.js";
+export { resolveDynamic, isVisible, runAction, withOwnWrites, submitClosesOverlay, bindTree, readPointer, writePointer, writeTokens, POINTER_ISSUES, absolutePath, readPath, hasItem, isDataSchema, resolveProp, resolveNodeProps, hasRowSlots, rowScope, bindRowSlot, sectionScope, bindSectionHeader, BIND_FUNCTIONS, BIND_FUNCTION_NAMES } from "./dynamic.js";
+export { displayString, englishFormatter, intlFormatter, formatFunctions, formatPattern, parseDateValue, relativeTimeUnit, currencyDigits, FORMAT_FUNCTION_NAMES, ENGLISH_FORMAT_FUNCTIONS, ENGLISH_DATE_PATTERNS, ENGLISH_TIME_PATTERN, ENGLISH_DATE_TIME_JOIN, fixedOffset, intlZoneOffset } from "./format.js";
+export type { Formatter, NumberOptions, DateOptions, DateStyle, PluralCategory, RelativeUnit, ZoneOffset } from "./format.js";
+export { templateItemKeys, tableRowKeys, templateInstances, itemExtents, itemOffsets, virtualWindow, scrollOffsetForIndex, scrollOffsetForItem, instanceSegment, listSections, sectionRows, stickyHeader, templateBudget, templateSiteKey, WINDOW_OVERSCAN } from "./list.js";
+export type { TemplateInstance, TemplateBudget, WindowRange, ScrollAlign, ListSection } from "./list.js";
+export { normalizeSizes, resizePanels, keyboardResize, panelExtents, dragDelta, RESIZE_STEP, PANEL_MIN, RESIZE_HANDLE_HIT } from "./resizable.js";
+export type { PanelLimits, ResizeKey } from "./resizable.js";
+export { nodeDirections, physicalTextAlign, nodeTextAlign } from "./direction.js";
+export type { Direction, PhysicalAlign } from "./direction.js";
+export { LIMITS, MAX_COMPONENTS, MAX_DEPTH, MAX_MESSAGE_BYTES, MAX_TEMPLATE_ITEMS, MAX_POINTER_BYTES, MAX_POINTER_SEGMENTS, LIMIT_ISSUES } from "./limits.js";
+export { LAYOUT_CONSTANTS, FIELD_INTRINSIC_WIDTH, MEDIA_INTRINSIC_WIDTH, MEDIA_ASPECT_RATIO, TREE_GUIDE_COLUMN, TREE_GUIDE_RADIUS, TREE_GUIDE_BRIDGE, PENDING_DELAY_MS, SKELETON_PULSE_MS, SKELETON_OPACITY_LOW, SKELETON_OPACITY_HIGH, SKELETON_REDUCED_OPACITY, SEARCH_LIST_FADE } from "./layout.js";
+export { treeGuides, applyTreeGuides, isRowRoot } from "./tree-guides.js";
+export type { TreeGuide } from "./tree-guides.js";
+export { ANIMATIONS, ANIMATION_NAMES, ANIMATION_PROPERTIES_CSS, animatesOpacity, animationTiming, animationFrame, cubicBezier, keyframesCss, animationCss, paintedOpacity } from "./animation.js";
+export type { AnimationDef, AnimationFrame, AnimationTiming, Keyframe } from "./animation.js";
+export type { DataScope, ResolveOptions, ActionOutcome, FunctionTable, PointerWrite } from "./dynamic.js";
+export { DEFAULT_STRINGS, STRING_IDS, parseStringRef, isStringRef, stringTable, formatString, resolveString } from "./strings.js";
+export { DEFAULT_LOCALE, parseLocale, localeRegion, weekStart, textDirection, RTL_MIRRORED_ICONS, mirrorsInRtl } from "./locale.js";
+export type { LocaleParts } from "./locale.js";
+export { tokenizeCode, codeText, ansiRuns, CODE_LANGUAGES, CODE_LANGUAGE_NAMES } from "./code.js";
+export type { AnsiRun } from "./code.js";
+export { textShimmer, TEXT_SHIMMER } from "./text-shimmer.js";
+export type { TextShimmer } from "./text-shimmer.js";
+export { A11Y_ROLES, A11Y_RULES, A11Y_COMMANDS, COMPONENT_A11Y, componentA11y, isA11yRole } from "./a11y.js";
+export { chartExtent, chartSummaryParams, sparklineSummaryParams, niceTicks, seriesColor, DONUT_HOLE, WINDOW_THRESHOLD } from "./chart.js";
+export type { ChartSeries } from "./chart.js";
+export type { ComponentA11y } from "./a11y.js";
+export type { CodeToken } from "./code.js";
+export { basicMap, mapBasicComponent, mapBasicIcon, BASIC_TRANSFORM_NAMES } from "./basic-map.js";
+export type { MappedComponent } from "./basic-map.js";
+export { reduceSurface, reduceNested, preorder, RESERVED_KEYS, validVisible, slotAllowed, childTemplate } from "./reducer.js";
+export type { ReduceOptions, ReduceResult } from "./reducer.js";
+export { defineExtension, validateExtension } from "./extension.js";
+export { defineSurface, flattenSurface, ui, el, bind, call, event, run } from "./define.js";
+export type { SurfaceNode, TemplateChildren, DefineOptions, DefinedSurface, Factory } from "./define.js";
+export * from "./theme-types.js";
+export { parseColor, toHex, toThemeHex, isThemeHex, luminance, contrast } from "./color.js";
+export type { Rgba } from "./color.js";
+export { RECIPE_STATES, RECIPE_KEYS, recipeParts, macroParts, nativeRecipeProps } from "./recipes.js";
+export type { PartSpec } from "./recipes.js";
+export { MODES, DENSITIES, THEME_SCHEMA_ID, resolveMode, applyDensity, applyContrast, resolveConditionKey, easingCss, ThemeError, validateTheme, tryLoadTheme, loadTheme, resolveToken, resolveStyleValues, recipeStyle, resolveRecipe, nodeRecipeQuery, resolveNodeStyle, shadowCss, } from "./theme.js";
+export type { ThemeOptions } from "./theme.js";
+export { BUILTIN_THEMES, BUILTIN_THEME_IDS, DEFAULT_THEME_ID, neutralTheme, exponentialTheme, playfulTheme, orangeTheme, builtinTheme, builtinThemes, themeOrDefault } from "./themes.js";
+export { styleToCss, styleAttribute, gradientCss } from "./css.js";
+export { SHADCN_COLOR_VARS, importShadcnCss, themeFromImport, diffTheme, exportThemeJson, parseThemeJson, parseShadow } from "./builder.js";
+export type { ThemeImport } from "./builder.js";
+export { CONTROL_PARTS, GEOMETRY_KEYS, controlGeometry, checkGeometry, verifyPainterGeometry } from "./geometry.js";
+export type { ControlGeometry, GeometryKey, MeasuredBox, PainterOverride, GeometryIssue } from "./geometry.js";
+export { OVERLAY_OFFSET, OVERLAY_PADDING, placeOverlay } from "./overlay.js";
+export type { OverlaySide, OverlayAlign, OverlayPlacement, Rect, Size } from "./overlay.js";
+export * from "./host/index.js";
+export * from "./connector/index.js";

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

@@ -0,0 +1,20 @@
+export declare const LAYOUT_CONSTANTS: Readonly<Record<string, number>>;
+export declare const WINDOW_THRESHOLD: number;
+export declare const WINDOW_OVERSCAN: number;
+export declare const RESIZE_STEP: number;
+export declare const PANEL_MIN: number;
+export declare const RESIZE_HANDLE_HIT: number;
+export declare const FIELD_INTRINSIC_WIDTH: number;
+export declare const MEDIA_INTRINSIC_WIDTH: number;
+export declare const MEDIA_ASPECT_RATIO: number;
+export declare const TREE_GUIDE_COLUMN: number;
+/** Round 3: the elbow's corner radius and how far the guide verticals overshoot a row's top edge (paint only). */
+export declare const TREE_GUIDE_RADIUS: number;
+export declare const TREE_GUIDE_BRIDGE: number;
+/** EXP-1259: the pending Button's delay, the Skeleton's pulse and the SearchList's bottom fade (feedback-states.json, search-list.json). */
+export declare const PENDING_DELAY_MS: number;
+export declare const SKELETON_PULSE_MS: number;
+export declare const SKELETON_OPACITY_LOW: number;
+export declare const SKELETON_OPACITY_HIGH: number;
+export declare const SKELETON_REDUCED_OPACITY: number;
+export declare const SEARCH_LIST_FADE: number;

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

@@ -0,0 +1,21 @@
+export declare const LIMITS: Readonly<Record<string, number>>;
+/** Nodes the reducer places in one surface's tree (template nodes included). */
+export declare const MAX_COMPONENTS: number;
+/** Component nesting levels (the root = 1). */
+export declare const MAX_DEPTH: number;
+/** One server message as UTF-8 JSON. */
+export declare const MAX_MESSAGE_BYTES: number;
+/** Template items one surface instantiates. */
+export declare const MAX_TEMPLATE_ITEMS: number;
+/** A data pointer's length in UTF-8 bytes. */
+export declare const MAX_POINTER_BYTES: number;
+/** A data pointer's token count. */
+export declare const MAX_POINTER_SEGMENTS: number;
+/** The issue messages, byte-identical in every core. */
+export declare const LIMIT_ISSUES: {
+    readonly usedTwice: "id used twice; only its first place renders";
+    readonly depth: `nesting deeper than ${number} levels`;
+    readonly components: `surface: more than ${number} components; the rest is dropped`;
+    readonly templateItems: `template: more than ${number} items; the rest is not rendered`;
+    readonly messageBytes: `message larger than ${number} bytes`;
+};

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

@@ -0,0 +1,133 @@
+import type { ChildTemplate, ReduceIssue, UiNode } from "./types.js";
+export { WINDOW_THRESHOLD, WINDOW_OVERSCAN } from "./layout.js";
+/** The instance key of every item: the value at `keyPointer` (relative to
+ *  the item; objects as their JSON) — `#<index>` when that value is missing,
+ *  null, `` or a DUPLICATE of an earlier item's key (more `#`s until unique);
+ *  without a pointer, the index. */
+export declare function templateItemKeys(items: readonly unknown[], keyPointer?: string): string[];
+/** Table row keys: the `rowKey` FIELD (default `id`) under the same rules
+ *  (`#<index>` for missing, empty or duplicate). */
+export declare function tableRowKeys(rows: readonly unknown[], rowKey?: string): string[];
+/** A key as one instance-suffix segment: `~` → `~0`, `.` → `~1` (as JSON
+ *  pointer escapes `/`), so dotted keys never collide across nesting levels
+ *  (`a.b` + `c` vs `a` + `b.c`). */
+export declare const instanceSegment: (key: string) => string;
+export interface TemplateInstance {
+    /** The item's key (see `templateItemKeys`). */
+    key: string;
+    /** The item's data pointer: its scope (`/posts/3`). */
+    path: string;
+    index: number;
+    /** The suffix every node of the item wears: the enclosing instance's
+     *  suffix + `.<key>`, the key escaped by `instanceSegment` (`.a` for an
+     *  outer item, `.a.0` inside it, `.a~1b` for key `a.b`). A node's painted
+     *  id = its id + the suffix. */
+    instance: string;
+}
+/** The items a node's `template` renders in a data scope: one per array
+ *  item at `template.path` (relative to `scope`), keyed by `template.key`.
+ *  `instance` = the suffix of the item the template sits in (`` at the top). */
+export declare function templateInstances(data: unknown, template: ChildTemplate, scope?: string, instance?: string): TemplateInstance[];
+/** A template site's key in a `TemplateBudget`: the node holding the
+ *  template + the data scope it sits in. */
+export declare const templateSiteKey: (nodeId: string, scope: string) => string;
+export interface TemplateBudget {
+    /** Items each visited template site builds (absent = a site the walk
+     *  never reached: it sits in an item that is not built). */
+    allowed: Map<string, number>;
+    /** ONE issue per build: the template component whose next item did not
+     *  fit (`LIMIT_ISSUES.templateItems` or `LIMIT_ISSUES.components`); null =
+     *  everything fits. */
+    issue: ReduceIssue | null;
+}
+/** VAPP-103: the template items ONE surface builds, in the Rust layout
+ *  build's order (depth-first: a node's slots and static children, then its
+ *  template items, each item's own subtree, nested items included, before
+ *  the next item). The build holds `maxComponents` nodes: it starts at the
+ *  reduced root tree's own nodes (children + slots; template definitions
+ *  aside), and every item costs 1 against `maxTemplateItems` AND its
+ *  template subtree's nodes. The first item that does not fit either budget
+ *  and every later one is not built, with ONE issue on that template
+ *  component. A windowed List (more than `WINDOW_THRESHOLD` rows) mounts
+ *  its rows on demand: its items are not counted up front. Iterative. */
+export declare function templateBudget(root: UiNode, data: unknown, templateNode: (componentId: string) => UiNode | undefined): TemplateBudget;
+/** Start offsets of items laid end to end on one axis with `gap` between
+ *  them (a `divided` list adds `$control.hairline` to the gap; the divider
+ *  is centred in it): `offsets[i]` = where item i starts, `offsets[count]` =
+ *  the content length. */
+export declare function itemOffsets(extents: readonly number[], gap?: number): number[];
+/** Every item's extent on the list's axis: a measured item keeps its
+ *  extent; an unmeasured one (`null`) takes the MEAN of the measured
+ *  extents once any item is measured (the content length stays stable while
+ *  rows measure in, so a fling lands on the real end), else `row` (the
+ *  theme's `$control.row`). */
+export declare function itemExtents(measured: readonly (number | null | undefined)[], row: number): number[];
+export interface WindowRange {
+    /** First rendered item. */
+    start: number;
+    /** One past the last rendered item. */
+    end: number;
+    /** Space before `start` / after `end - 1` (the spacers). */
+    before: number;
+    after: number;
+    /** The content length. */
+    total: number;
+}
+/** The items to render for a viewport `[scroll, scroll + viewport)` on the
+ *  list's axis (both relative to the list's content start; a list without a
+ *  bounded size windows against its nearest scrolling ancestor or the host
+ *  viewport, translated into this frame): every item that intersects it
+ *  (an item ending exactly at the viewport start still counts) plus
+ *  `overscan` items on each side. Unmeasured items take `itemExtents`'s
+ *  estimate (the caller's extents). `offsets` = `itemOffsets(extents, gap)` when the
+ *  caller caches it (recompute only when an extent changes): the window is
+ *  then two binary searches, O(log n) per scroll frame. */
+export declare function virtualWindow(extents: readonly number[], gap: number, scroll: number, viewport: number, overscan?: number, offsets?: readonly number[]): WindowRange;
+export type ScrollAlign = `start` | `center` | `end` | `nearest`;
+/** The scroll offset that brings item `index` into a viewport of length
+ *  `viewport` currently at `scroll` (the `scrollToIndex` command): `start` =
+ *  its start at the viewport start (after `inset`, the pinned header's
+ *  extent), `end` = its end at the viewport end, `center` = centred,
+ *  `nearest` (default) = the smallest move that shows it whole (none when it
+ *  already is). Clamped to `[0, max(0, total - viewport)]`. `offsets` = the
+ *  cached `itemOffsets`, as for `virtualWindow`. */
+export declare function scrollOffsetForIndex(extents: readonly number[], gap: number, index: number, viewport: number, scroll: number, align?: ScrollAlign, inset?: number, offsets?: readonly number[]): number;
+export interface ListSection {
+    /** The `sectionBy` value its items share (as `displayString`; `` for
+     *  missing). */
+    value: string;
+    /** Index of the section's first item in the data. */
+    start: number;
+    count: number;
+}
+/** Consecutive template items with the same `sectionBy` value (a pointer
+ *  relative to each item) form a section; the data order is kept (sort the
+ *  data to group it). */
+export declare function listSections(items: readonly unknown[], sectionBy: string): ListSection[];
+/** The flat ROW list a sectioned list windows: a header row before each
+ *  section's items (`{header: sectionIndex}` / `{item: dataIndex}`). */
+export declare function sectionRows(sections: readonly ListSection[]): ({
+    header: number;
+} | {
+    item: number;
+})[];
+/** `scrollToIndex` on a SECTIONED list: the DATA index → its flat row
+ *  (`sectionRows`; -1 = absent → no move), then `scrollOffsetForIndex` over
+ *  the rows' extents with `inset` = the extent of the item's own section
+ *  header when headers are sticky (it pins over the item), else 0. */
+export declare function scrollOffsetForItem(rows: readonly ({
+    header: number;
+} | {
+    item: number;
+})[], rowExtents: readonly number[], gap: number, dataIndex: number, viewport: number, scroll: number, align?: ScrollAlign, stickyHeaders?: boolean, offsets?: readonly number[]): number;
+/** The sticky header at a scroll offset: the LAST header row starting at or
+ *  before `scroll` is pinned at the viewport start — pushed back by the next
+ *  header as it arrives (its offset = min(scroll, nextHeaderStart −
+ *  extent)). `rowOffsets` = itemOffsets of the flat rows; `headerRows` = the
+ *  flat indices of the header rows, ascending. Null before the first header
+ *  reaches the viewport start. Binary search: O(log headers). The pinned header is rendered even when the
+ *  window does not contain it. */
+export declare function stickyHeader(rowOffsets: readonly number[], rowExtents: readonly number[], headerRows: readonly number[], scroll: number): {
+    row: number;
+    offset: number;
+} | null;

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

@@ -0,0 +1,22 @@
+export declare const DEFAULT_LOCALE: string;
+export interface LocaleParts {
+    language: string;
+    region: string | null;
+}
+/** `pt-BR` → {pt, BR}; `zh-Hant-TW` → {zh, TW}; `de` → {de, null}. The
+ *  region = the first 2-letter or 3-digit subtag after the language; a
+ *  deprecated language code is normalised (`iw` → `he`, `ji` → `yi`, `in` →
+ *  `id`: `languageAliases`). */
+export declare function parseLocale(locale: string): LocaleParts;
+/** The region a locale's data comes from: its own, else the language's
+ *  likely region (CLDR likelySubtags), else null. */
+export declare function localeRegion(locale: string): string | null;
+/** The first day of the week, 0 = Sunday … 6 = Saturday. */
+export declare function weekStart(locale: string): number;
+/** `rtl` for the right-to-left languages, else `ltr`. */
+export declare function textDirection(locale: string): `ltr` | `rtl`;
+/** The directional glyphs (icons.json names) a painter mirrors under rtl. */
+export declare const RTL_MIRRORED_ICONS: readonly string[];
+/** True when `icon` is drawn mirrored (scaleX(-1), outermost) in this
+ *  direction. */
+export declare function mirrorsInRtl(icon: string, direction: `ltr` | `rtl`): boolean;

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

@@ -0,0 +1,29 @@
+import { isDynamic, truthy } from "./expr.js";
+import type { ExtensionDef, MacroChild, ReduceIssue, UiNode } from "./types.js";
+/** The breakpoint names in ascending order (tokens.json). */
+export declare const BREAKPOINTS: readonly string[];
+/** `{base, sm?, md?, lg?, xl?}`: an object with `base` and only breakpoint
+ *  keys besides. */
+export declare function isResponsiveValue(value: unknown): value is Record<string, unknown> & {
+    base: unknown;
+};
+/** The value a responsive prop takes at a breakpoint: the nearest defined
+ *  key at or below it, `base` under the first one. `null` = the base. */
+export declare function responsiveAt(value: Record<string, unknown> & {
+    base: unknown;
+}, breakpoint: string | null): unknown;
+/** The author's props with every responsive object replaced by its value at
+ *  `breakpoint`. */
+export declare function propsAt(props: Record<string, unknown>, breakpoint: string | null): Record<string, unknown>;
+/** The normalized tree with every macro (core + extensions) expanded into
+ *  natives, recipes attached. Pure: the input is not mutated; expansion
+ *  problems (an author function that replaces a `$set` write) are pushed to
+ *  `options.issues` when given. */
+export declare function expandMacros(root: UiNode, options?: {
+    extensions?: readonly ExtensionDef[];
+    issues?: ReduceIssue[];
+}): UiNode;
+/** True for a value the expander would keep (see expr.ts). */
+export declare const keeps: typeof truthy;
+export { isDynamic };
+export type { MacroChild };

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

@@ -0,0 +1,27 @@
+export declare const OVERLAY_OFFSET = 4;
+export declare const OVERLAY_PADDING = 8;
+export type OverlaySide = `top` | `right` | `bottom` | `left`;
+export type OverlayAlign = `start` | `center` | `end`;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface OverlayPlacement {
+    x: number;
+    y: number;
+    side: OverlaySide;
+    /** True when the preferred side was swapped for its opposite. */
+    flipped: boolean;
+}
+export declare function placeOverlay(anchor: Rect, size: Size, viewport: Size, options?: {
+    side?: OverlaySide;
+    align?: OverlayAlign;
+    offset?: number;
+    padding?: number;
+}): OverlayPlacement;