@exponential-at/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,112 @@
+export type PluralCategory = `zero` | `one` | `two` | `few` | `many` | `other`;
+export type DateStyle = `short` | `medium` | `long` | `full`;
+export type RelativeUnit = `second` | `minute` | `hour` | `day` | `week` | `month` | `year`;
+export interface NumberOptions {
+    /** Fixed fraction digits (min = max); absent = 0..3 for numbers, the
+     *  currency's minor digits for currencies, 0 for percents. */
+    decimals?: number;
+    /** Locale grouping separators (default true). */
+    grouping?: boolean;
+}
+export interface DateOptions {
+    /** A Unicode TR35 pattern (`MMM d, yyyy`, `HH:mm`); wins over `style`. */
+    format?: string;
+    /** A locale preset (default `medium`: `Oct 14, 2026`). */
+    style?: DateStyle;
+    /** Append the short time (`2:30 PM`) to a preset. */
+    time?: boolean;
+}
+/** What a host supplies per surface (SurfaceSettings.locale + timeZone). */
+export interface Formatter {
+    readonly locale: string;
+    number(value: number, options?: NumberOptions): string;
+    currency(value: number, currency: string, options?: NumberOptions): string;
+    /** `value` is a ratio: 0.256 → `26%`. */
+    percent(value: number, options?: {
+        decimals?: number;
+    }): string;
+    /** `value` = `yyyy-mm-dd` (a calendar day, no zone), an ISO date-time (an
+     *  instant; no offset = UTC) or epoch milliseconds; unreadable = ``. */
+    date(value: unknown, options?: DateOptions): string;
+    /** `value` as for `date`, against `now` (epoch ms). */
+    relativeTime(value: unknown, now: number): string;
+    plural(value: number): PluralCategory;
+}
+/** What a `string`/`markdown` prop shows for a bound value: strings as they
+ *  are, finite numbers as ECMAScript `Number.prototype.toString` (shortest
+ *  round trip, `-0` → `0`, exponent form below 1e-6 and from 1e21), booleans
+ *  `true`/`false`; null, undefined, non-finite numbers, objects and arrays
+ *  show nothing (``). No locale formatting (use formatNumber for that). */
+export declare function displayString(value: unknown): string;
+/** The minor digits of a currency (ISO 4217; 2 when not listed). */
+export declare function currencyDigits(code: string): number;
+/** The instant a date value names: `yyyy-mm-dd` = that calendar day (UTC
+ *  midnight, `dateOnly`), an ISO date-time (no offset = UTC), epoch ms. */
+export declare function parseDateValue(value: unknown): {
+    ms: number;
+    dateOnly: boolean;
+} | null;
+interface DateFields {
+    year: number;
+    month: number;
+    day: number;
+    weekday: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+interface DateNames {
+    months: readonly string[];
+    monthsShort: readonly string[];
+    weekdays: readonly string[];
+    weekdaysShort: readonly string[];
+    dayPeriods: readonly string[];
+}
+/** A TR35 pattern over fields: `y yy yyyy M MM MMM MMMM d dd E EEE EEEE h hh
+ *  H HH m mm s ss a`, `'quoted'` literals (`''` = an apostrophe); any other
+ *  letter run is copied as written. Digits are ASCII. */
+export declare function formatPattern(pattern: string, f: DateFields, names: DateNames): string;
+/** The en-US preset patterns (`style`), the time a preset appends and the
+ *  joiner per style (locale.json `englishFallback`). */
+export declare const ENGLISH_DATE_PATTERNS: Readonly<Record<DateStyle, string>>;
+export declare const ENGLISH_TIME_PATTERN: string;
+export declare const ENGLISH_DATE_TIME_JOIN: Readonly<Record<DateStyle, string>>;
+/** The surface zone as the English fallback sees it: the UTC offset in
+ *  minutes (east positive) in force at an instant (epoch ms). A host
+ *  without an IANA database passes its platform's local offset; the
+ *  fixtures pin a fixed one (`offsetMinutes`). */
+export type ZoneOffset = (utcMs: number) => number;
+/** A fixed offset (minutes east of UTC); `fixedOffset(0)` = UTC. */
+export declare const fixedOffset: (minutes: number) => ZoneOffset;
+/** An IANA zone's offset through Intl (TS hosts; the Rust core takes its
+ *  host's offset instead). */
+export declare function intlZoneOffset(timeZone: string): ZoneOffset;
+/** The unit a delta (value − now, ms) is shown in, and its count (truncated
+ *  toward zero): under a minute seconds, under an hour minutes, under a day
+ *  hours, under 7 days days, under 30 days weeks, under 365 days months (of
+ *  30 days), else years (of 365 days). */
+export declare function relativeTimeUnit(deltaMs: number): {
+    value: number;
+    unit: RelativeUnit;
+};
+/** The Formatter a renderer uses without a platform ICU (the Rust core's
+ *  default): Intl en-US, decided by data (catalog/locale.json
+ *  `englishFallback`). Instants show in the surface zone `zone` (default
+ *  UTC); a `yyyy-mm-dd` value is a calendar day and never shifts. */
+export declare function englishFormatter(zone?: ZoneOffset): Formatter;
+/** A Formatter on the platform's Intl in `locale` (BCP 47) and `timeZone`
+ *  (IANA; default UTC, as the fixtures pin it). Patterns use the locale's
+ *  month/weekday/day-period NAMES with ASCII digits. */
+export declare function intlFormatter(locale: string, timeZone?: string): Formatter;
+/** The bind-time format functions (A2UI basic `formatNumber`,
+ *  `formatCurrency`, `formatDate`, `pluralize` + the core `formatPercent`,
+ *  `formatRelativeTime`), all through ONE Formatter. */
+export declare const FORMAT_FUNCTION_NAMES: readonly ["formatNumber", "formatCurrency", "formatPercent", "formatDate", "formatRelativeTime", "pluralize"];
+/** The format functions over a Formatter; `now` = the clock
+ *  `formatRelativeTime` reads when its call has no `now` (a renderer
+ *  re-binds such a node at least once a minute). A value that is not a
+ *  number, a numeric string (`NUMERIC`) or a date formats to ``. */
+export declare function formatFunctions(formatter: Formatter, now?: () => number): Record<(typeof FORMAT_FUNCTION_NAMES)[number], (args: Record<string, unknown>) => unknown>;
+/** The fallback's format functions (the reference bind table's). */
+export declare const ENGLISH_FORMAT_FUNCTIONS: Record<"formatNumber" | "formatCurrency" | "formatDate" | "pluralize" | "formatPercent" | "formatRelativeTime", (args: Record<string, unknown>) => unknown>;
+export {};

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

@@ -0,0 +1,40 @@
+import type { ResolvedTheme } from "./theme-types.js";
+/** The part whose recipe sizes each control. */
+export declare const CONTROL_PARTS: Record<string, string>;
+export declare const GEOMETRY_KEYS: readonly ["width", "height", "minWidth", "minHeight", "paddingHorizontal", "paddingVertical", "padding", "gap", "borderWidth", "borderRadius"];
+export type GeometryKey = (typeof GEOMETRY_KEYS)[number];
+export type ControlGeometry = Partial<Record<GeometryKey, number>>;
+/** The numeric box of a control for a theme (mode-independent: lengths do
+ *  not change with the mode). */
+export declare function controlGeometry(theme: ResolvedTheme, component: string, props?: Record<string, unknown>, states?: readonly string[]): ControlGeometry;
+/** What a painter reports after measuring the control it drew. */
+export interface MeasuredBox {
+    width?: number;
+    height?: number;
+    paddingHorizontal?: number;
+    paddingVertical?: number;
+    borderWidth?: number;
+    borderRadius?: number;
+}
+/** A host's replacement painter for one native kind (the VAPP-91 extension
+ *  API): it may draw anything, but `measure` must return the theme's box. */
+export interface PainterOverride {
+    component: string;
+    measure(theme: ResolvedTheme, props: Record<string, unknown>, states?: readonly string[]): MeasuredBox;
+}
+export interface GeometryIssue {
+    key: string;
+    expected: number;
+    actual: number | undefined;
+}
+/** Every geometry key the theme fixes that the measured box misses or
+ *  changes (a key the theme leaves open is the painter's). */
+export declare function checkGeometry(expected: ControlGeometry, measured: MeasuredBox, tolerance?: number): GeometryIssue[];
+/** Run an override through every case the fixture holds for its kind. */
+export declare function verifyPainterGeometry(override: PainterOverride, theme: ResolvedTheme, cases: readonly {
+    props: Record<string, unknown>;
+    states?: readonly string[];
+}[]): {
+    name: string;
+    issues: GeometryIssue[];
+}[];

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

@@ -0,0 +1,188 @@
+import type { FlatComponent } from "../types.js";
+export declare const HOST_CONTRACT: {
+    $comment: string;
+    version: number;
+    a2uiVersion: string;
+    messages: {
+        $comment: string;
+        a2ui: string[];
+        extensions: string[];
+    };
+    ops: {
+        $comment: string;
+        kinds: string[];
+    };
+    clientMessages: {
+        $comment: string;
+        errorCodes: string[];
+    };
+    functions: {
+        $comment: string;
+        decisions: string[];
+        defaultPolicy: {
+            allow: never[];
+            ask: never[];
+            deny: never[];
+            default: string;
+        };
+    };
+    urls: {
+        $comment: string;
+        defaultSchemes: string[];
+        privateHosts: string[];
+        reasons: string[];
+    };
+    media: {
+        $comment: string;
+        ruleKeys: string[];
+        optionKeys: string[];
+        defaultSchemes: string[];
+        limits: {
+            maxBytes: number;
+            timeoutMs: number;
+            maxPixels: number;
+        };
+    };
+    sources: {
+        $comment: string;
+        pattern: string;
+    };
+    transport: {
+        $comment: string;
+        mcpMimeTypes: string[];
+        mcpActionTool: string;
+        sseEvents: string[];
+    };
+    negotiation: {
+        $comment: string;
+    };
+    package: {
+        $comment: string;
+        required: string[];
+    };
+    paint: {
+        $comment: string;
+        hook: string;
+        errorCode: string;
+    };
+    surface: {
+        $comment: string;
+        settings: string[];
+        formatter: string[];
+        commands: string[];
+    };
+};
+export declare const HOST_CONTRACT_VERSION: number;
+export declare const A2UI_MESSAGE_KINDS: readonly string[];
+export declare const EXTENSION_MESSAGE_KINDS: readonly string[];
+export declare const MESSAGE_KINDS: readonly string[];
+export declare const HOST_ERROR_CODES: readonly string[];
+export declare const DEFAULT_URL_SCHEMES: readonly string[];
+/** The media loader's schemes when the host lists none (no `file`). */
+export declare const DEFAULT_MEDIA_SCHEMES: readonly string[];
+/** What every image loader enforces (`media.limits`). */
+export declare const MEDIA_LIMITS: {
+    readonly maxBytes: number;
+    readonly timeoutMs: number;
+    readonly maxPixels: number;
+};
+/** The renderer → host hook a failed painter calls (`paint.hook`) and the
+ *  A2UI error code the host forwards it with (`paint.errorCode`). */
+export declare const PAINT_ERROR_HOOK: string;
+export declare const RENDER_FAILED: "RENDER_FAILED";
+export declare const MCP_MIME_TYPES: readonly string[];
+export declare const MCP_ACTION_TOOL: string;
+export declare const SSE_EVENTS: readonly string[];
+/** Round 2: what a host hands each surface (`surface`): the SurfaceSettings
+ *  keys, the Formatter's methods, the commands a live surface takes. */
+export declare const SURFACE_SETTING_KEYS: readonly string[];
+export declare const FORMATTER_METHODS: readonly string[];
+export declare const SURFACE_COMMANDS: readonly string[];
+export type HostErrorCode = `VALIDATION_FAILED` | `INVALID_MESSAGE` | `UNSUPPORTED_CATALOG` | `SURFACE_NOT_FOUND` | `TEMPLATE_NOT_FOUND` | `FUNCTION_NOT_FOUND` | `FUNCTION_DENIED` | `SOURCE_DENIED` | `RENDER_FAILED`;
+/** A server → client message: the four A2UI v0.9 kinds plus the two
+ *  Exponential UI extensions. */
+export interface ServerMessage {
+    version?: string;
+    createSurface?: {
+        surfaceId: string;
+        catalogId: string;
+        theme?: unknown;
+        sendDataModel?: boolean;
+    };
+    updateComponents?: {
+        surfaceId: string;
+        components: FlatComponent[];
+    };
+    updateDataModel?: {
+        surfaceId: string;
+        path?: string;
+        value?: unknown;
+    };
+    deleteSurface?: {
+        surfaceId: string;
+    };
+    applyTemplate?: {
+        surfaceId: string;
+        templateId: string;
+        packageId?: string;
+        data?: unknown;
+    };
+    bindDataModel?: {
+        surfaceId: string;
+        path: string;
+        source: string;
+    };
+}
+export interface ClientAction {
+    name: string;
+    surfaceId: string;
+    sourceComponentId: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+}
+export interface ClientError {
+    code: HostErrorCode | (string & {});
+    surfaceId: string;
+    message: string;
+    path?: string;
+}
+/** A client → server message (A2UI v0.9 client_to_server). */
+export type ClientMessage = {
+    version: string;
+    action: ClientAction;
+} | {
+    version: string;
+    error: ClientError;
+};
+/** What the router turns a message into; the platform host performs the
+ *  ops in order (`catalog/host.json` `ops`). */
+export type HostOp = {
+    op: `create`;
+    surfaceId: string;
+    catalogId: string;
+    theme?: unknown;
+    sendDataModel?: boolean;
+} | {
+    op: `components`;
+    surfaceId: string;
+    components: FlatComponent[];
+} | {
+    op: `data`;
+    surfaceId: string;
+    path: string;
+    value?: unknown;
+} | {
+    op: `bind`;
+    surfaceId: string;
+    path: string;
+    source: string;
+} | {
+    op: `delete`;
+    surfaceId: string;
+} | {
+    op: `send`;
+    message: ClientMessage;
+};
+export declare function errorMessage(code: HostErrorCode, surfaceId: string, message: string, path?: string): ClientMessage;
+export declare function actionMessage(action: ClientAction): ClientMessage;

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

@@ -0,0 +1,61 @@
+import type { ClientMessage } from "./contract.js";
+export interface DecodeIssue {
+    /** 1-based line (JSONL) or event (SSE) number. */
+    at: number;
+    message: string;
+}
+export interface Decoded {
+    messages: unknown[];
+    issues: DecodeIssue[];
+}
+/** One message per line. `push` takes any chunking (a line may span
+ *  chunks), `end` flushes a last line without a newline. A line past
+ *  `maxMessageBytes` is an issue (`line N: message larger than … bytes`),
+ *  never buffered. */
+export declare class JsonlDecoder {
+    private lines;
+    private line;
+    push(chunk: string): Decoded;
+    end(): Decoded;
+}
+/** A whole JSONL document (or one JSON value / a JSON array of messages). */
+export declare function decodeJsonl(text: string): Decoded;
+/** Server-Sent Events: `data:` lines join with `\n` per event, a blank line
+ *  dispatches, `:` comments and other fields are ignored (`retry:` is
+ *  kept as `retryMs`), an `event:` name
+ *  outside SSE_EVENTS drops the event. An event's data is one message or
+ *  JSONL. */
+export declare class SseDecoder {
+    /** The last `retry:` field (ms): the server resumes the stream after it
+     *  ends (a transport reconnects on a clean end only then). */
+    retryMs?: number;
+    private lines;
+    private data;
+    /** The event's data bytes so far (past `maxMessageBytes` it is dropped
+     *  and dispatches as an issue). */
+    private dataBytes;
+    private oversized;
+    private event;
+    private count;
+    push(chunk: string): Decoded;
+    end(): Decoded;
+    /** The event is past `maxMessageBytes`: forget its data (it dispatches
+     *  as an issue). */
+    private dropData;
+    private line;
+    private dispatch;
+}
+/** The A2UI-over-MCP carrier: the messages inside an MCP tool result
+ *  (`content[]` resources with an A2UI mime type, or
+ *  `structuredContent.a2ui`). */
+export declare function messagesFromMcpResult(result: unknown): Decoded;
+/** A client message as the MCP tools/call that carries it back. */
+export declare function mcpActionCall(message: ClientMessage, tool?: string): {
+    method: `tools/call`;
+    params: {
+        name: string;
+        arguments: {
+            message: ClientMessage;
+        };
+    };
+};

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

@@ -0,0 +1,11 @@
+export * from "./contract.js";
+export * from "./policy.js";
+export * from "./sources.js";
+export * from "./decoders.js";
+export * from "./package.js";
+export { HostRouter, normalizePath } from "./router.js";
+export type { HostRouterOptions, SurfaceInfo } from "./router.js";
+export { ExponentialHost, PackageError, SurfaceStore, resolveSurfaceTheme } from "./runtime.js";
+export type { Transport, TransportStatus, HostOptions, HostPolicy, HostFunction, FunctionCallInfo, FunctionOutcome, HostIssue } from "./runtime.js";
+export { MemoryTransport, JsonlStreamTransport, SseTransport, WebSocketTransport, McpTransport } from "./transports.js";
+export type { HttpTransportOptions, McpTransportOptions } from "./transports.js";

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

@@ -0,0 +1,58 @@
+import type { FlatComponent } from "../types.js";
+import type { ServerMessage } from "./contract.js";
+/** The core, the core lite, the A2UI basic catalog, then every registered
+ *  extension id in order, de-duplicated. */
+export declare function supportedCatalogIds(extensionIds?: readonly string[]): string[];
+/** A2UI's `a2uiClientCapabilities`. */
+export declare function clientCapabilities(extensionIds?: readonly string[]): {
+    "v0.9": {
+        supportedCatalogIds: string[];
+    };
+};
+export interface TemplateBinding {
+    path: string;
+    source: string;
+}
+export interface AppTemplate {
+    components: FlatComponent[];
+    data?: unknown;
+    bindings?: TemplateBinding[];
+}
+export interface AppPackage {
+    id: string;
+    name: string;
+    version: string;
+    catalogId: string;
+    templates: Record<string, AppTemplate>;
+    /** Function patterns the package's surfaces may call (allowlist). */
+    functions?: string[];
+    /** VAPP-107: the binding sources the package's surfaces may follow
+     *  (`exp:devices`, or a prefix `exp:*`); unset = any registered scheme.
+     *  Set, a template binding or a later `bindDataModel` outside it is
+     *  refused (`sourceAllowed`). */
+    sources?: string[];
+    /** A built-in theme id or a theme JSON. */
+    theme?: unknown;
+    icon?: {
+        glyph?: string;
+        color?: string;
+    };
+    description?: string;
+}
+export interface PackageIssue {
+    path: string;
+    message: string;
+}
+/** Every problem with a package, each with a JSON pointer into it. */
+export declare function validatePackage(pkg: unknown, catalogIds?: readonly string[]): PackageIssue[];
+/** VAPP-107: may a package whose `sources` list is `allowed` follow this
+ *  source URI? Unset = yes; else the URI's `scheme:name` (scheme
+ *  lower-cased, the query dropped) must match a listed source exactly or a
+ *  `prefix*` pattern. */
+export declare function sourceAllowed(allowed: readonly string[] | undefined, source: string): boolean;
+/** A template as the messages that create it: createSurface, the
+ *  components, the merged initial data, one bindDataModel per binding. */
+export declare function templateMessages(pkg: AppPackage, templateId: string, surfaceId: string, data?: unknown): ServerMessage[] | null;
+/** The template's data under the caller's (objects merge one level deep in
+ *  key order; anything else: the caller's wins). */
+export declare function mergeData(base: unknown, over: unknown): unknown;

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

@@ -0,0 +1,105 @@
+/** The catalog's built-in client functions: the basic 14 + round 1's 15
+ *  core ones (`functions.names`). */
+export declare const BUILTIN_FUNCTIONS: readonly string[];
+export type FunctionDecision = `allow` | `ask` | `deny` | `not_found`;
+export interface FunctionPolicy {
+    allow?: readonly string[];
+    ask?: readonly string[];
+    deny?: readonly string[];
+    /** For a registered name no list matches; default `allow`. */
+    default?: `allow` | `ask` | `deny`;
+}
+/** `harness.*` matches `harness.toast`; anything else is exact. */
+export declare function matchesPattern(pattern: string, name: string): boolean;
+/** The gate: built-ins always run; an unregistered name is `not_found`;
+ *  then deny wins, then allow, then ask, then the policy's default. */
+export declare function decideFunction(policy: FunctionPolicy | undefined, name: string, registered: boolean): FunctionDecision;
+/** Two policies stacked (a package's allowlist under the host's own): the
+ *  stricter decision wins. */
+export declare function combineDecisions(a: FunctionDecision, b: FunctionDecision): FunctionDecision;
+/** A declarative package's `functions` list as a policy: listed = allow,
+ *  anything else = deny. */
+export declare function packagePolicy(functions: readonly string[] | undefined): FunctionPolicy;
+export interface UrlPolicy {
+    /** The schemes allowed; default `DEFAULT_URL_SCHEMES` (https, http,
+     *  mailto, tel). `["https"]` = https only. */
+    schemes?: readonly string[];
+    /** http(s) hosts allowed: exact or `*.example.com`; unset = any. */
+    hosts?: readonly string[];
+    /** VAPP-107: private, loopback and link-local hosts (`isPrivateHost`)
+     *  are DENIED for http(s) unless listed here: exact, `*.suffix`, or `*`
+     *  for every private address. A `hosts` allowlist does not opt one in. */
+    allowPrivate?: readonly string[];
+    baseUrl?: string;
+}
+export interface UrlDecision {
+    allowed: boolean;
+    /** The absolute url when it parses. */
+    url?: string;
+    reason?: `invalid` | `scheme` | `host` | `private`;
+}
+/** VAPP-107: is a parsed, lower-cased hostname one the URL and media policy
+ *  deny by default (`catalog/host.json` urls.privateHosts)? `localhost`
+ *  and `*.localhost`, `*.local` (mDNS), the IPv4 blocks 0/8, 10/8, 127/8,
+ *  169.254/16, 172.16/12, 192.168/16, and IPv6 `::`, `::1`, fe80::/10,
+ *  fc00::/7 plus an IPv4-mapped address of a private IPv4. LITERALS only:
+ *  the policy never resolves names (a public name that resolves privately
+ *  is the host network's job). */
+export declare function isPrivateHost(hostname: string): boolean;
+/** The decision for a url: it must parse (relative against `baseUrl`), use
+ *  one of `schemes`, and for http(s) match `hosts` when set and not be a
+ *  private host unless `allowPrivate` covers it. */
+export declare function decideUrl(policy: UrlPolicy | undefined, url: string): UrlDecision;
+export interface MediaRule {
+    prefix: string;
+    headers: Record<string, string>;
+}
+export interface MediaOptions {
+    baseUrl?: string;
+    rules?: readonly MediaRule[];
+    /** The schemes a src may use; default `DEFAULT_MEDIA_SCHEMES` (https,
+     *  http, data). `file` only when listed. */
+    schemes?: readonly string[];
+    /** http(s) hosts media may load from: exact or `*.example.com`; unset = any. */
+    hosts?: readonly string[];
+    /** VAPP-107: the private hosts media may load from (`UrlPolicy.allowPrivate`). */
+    allowPrivate?: readonly string[];
+}
+export interface MediaRequest {
+    url: string;
+    headers: Record<string, string>;
+}
+/** The image / media loader's request: the absolute url plus the headers of
+ *  every rule whose prefix it starts with (later rules win per header).
+ *  Null when the url does not resolve or the media policy (schemes, hosts)
+ *  denies it: nothing loads. */
+export declare function mediaRequest(url: string, options?: MediaOptions): MediaRequest | null;
+/** The href a renderer may navigate to (Link, markdown links, FileUpload
+ *  file urls), or undefined when the URL policy denies it. */
+export declare function safeHref(policy: UrlPolicy | undefined, url: unknown): string | undefined;
+export declare function sortKeys<T>(record: Record<string, T>): Record<string, T>;
+/** Width × height from an image's header (PNG, JPEG, GIF, WebP, BMP) or an
+ *  SVG's root `width`/`height`/`viewBox` without decoding it: what a loader
+ *  checks against `MEDIA_LIMITS.maxPixels` BEFORE decoding (the Rust core's
+ *  `image_dimensions`). Null = not a header this reads (truncated bytes,
+ *  another format). VAPP-103 rfix: an SVG has a size (`svgDimensions`). */
+export declare function imageDimensions(bytes: Uint8Array): [number, number] | null;
+/** The size an SVG rasterizes at: its root's `width`/`height` (px, or
+ *  pt/pc/in/cm/mm/em/ex at 96 dpi and a 16 px em; `%` = unset); a missing
+ *  one follows the `viewBox` aspect, both missing = the `viewBox` size, no
+ *  `viewBox` = 100. Null = no `<svg` root tag (the Rust core's `svg_dimensions`). */
+export declare function svgDimensions(bytes: Uint8Array): [number, number] | null;
+/** The frames an image decodes into: a GIF's image descriptors, an APNG's
+ *  `acTL` count, an animated WebP's `ANMF` chunks; 1 otherwise (the Rust
+ *  core's `image_frames`). */
+export declare function imageFrames(bytes: Uint8Array): number;
+/** VAPP-103 rfix: the pixel cap on a whole image before it decodes (the
+ *  Rust core's `media_image_within_limits`): a raster (PNG, JPEG, GIF, WebP,
+ *  BMP) or SVG whose size cannot be read is refused, and width × height ×
+ *  `imageFrames` must fit `maxPixels`. Null = within the limits, else the
+ *  reason; bytes of no known image format pass (the decoder refuses them).
+ *  `limits` defaults to `MEDIA_LIMITS` (a host may pass its own). */
+export declare function mediaImageWithinLimits(bytes: Uint8Array, limits?: {
+    maxBytes: number;
+    maxPixels: number;
+}): string | null;

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

@@ -0,0 +1,34 @@
+import type { HostOp } from "./contract.js";
+import type { PackageIssue, AppPackage } from "./package.js";
+export interface HostRouterOptions {
+    /** Extension catalog ids the host registered (negotiation). */
+    extensionIds?: readonly string[];
+}
+export interface SurfaceInfo {
+    surfaceId: string;
+    catalogId: string;
+    /** The package whose template created it (its function policy). */
+    packageId?: string;
+}
+export declare class HostRouter {
+    private extensionIds;
+    private surfaces;
+    private packages;
+    constructor(options?: HostRouterOptions);
+    get supportedCatalogIds(): string[];
+    registerExtension(id: string): void;
+    /** Install a declarative package: its templates become `applyTemplate`
+     *  targets. Returns the validation issues (installed only when none). */
+    installPackage(pkg: AppPackage): PackageIssue[];
+    package(id: string): AppPackage | undefined;
+    surface(id: string): SurfaceInfo | undefined;
+    surfaceIds(): string[];
+    /** One server message → the ops to perform, in order. Never throws. */
+    route(message: unknown): HostOp[];
+    private findPackage;
+    private invalid;
+    private missing;
+}
+/** A2UI: an omitted path or `/` is the whole data model (`""` in JSON
+ *  pointer terms, which every surface's setPointer takes). */
+export declare function normalizePath(path: string | undefined): string;