@exponential_app/eui 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,107 @@
+import type { CatalogView, ExtensionDef, Formatter } from "@exponential_app/eui";
+export type DataModel = Record<string, unknown> | unknown[];
+export interface DataBinding {
+    path: string;
+}
+export interface FunctionCall {
+    call: string;
+    args?: Record<string, unknown>;
+    returnType?: string;
+}
+export declare function isBinding(value: unknown): value is DataBinding;
+export declare function isCall(value: unknown): value is FunctionCall;
+/** A pointer's tokens; `` and `/` are the whole model. */
+export declare function pointerTokens(pointer: string): string[];
+/** `path` made absolute against a template scope (`/items/3`). */
+export declare function absolutePath(path: string, scope?: string): string;
+/** The core's `readPointer`: real indices and OWN keys only, `-` = the
+ *  last element. */
+export declare const getPointer: (data: unknown, pointer: string) => unknown;
+/** A copy of `data` with the value at `pointer` replaced (or removed when
+ *  `value` is undefined): the core's `writePointer` (missing containers are
+ *  OBJECTS, an array index up to its length, `-` appends). A refused write
+ *  (pointer limits, a non-index token, an index past the end) leaves the
+ *  data as it is. */
+export declare function setPointer<T extends DataModel>(data: T, pointer: string, value: unknown): T;
+export interface ResolveContext {
+    data: unknown;
+    /** The template item's pointer, for relative paths. */
+    scope?: string;
+    functions?: Record<string, ClientFunction>;
+    /** `openUrl` and other side effects go to the host. */
+    openUrl?: (url: string) => void;
+    /** The surface locale (BCP 47) the format functions use; default en-US. */
+    locale?: string;
+    /** The surface's built-in string table: `$string.<id>` resolves through it. */
+    strings?: Readonly<Record<string, string>>;
+    /** Round 2: the surface's Formatter (locale + time zone); the format
+     *  functions, Table cells, charts and pickers format through it. */
+    formatter?: Formatter;
+    /** The clock `formatRelativeTime` reads without a `now` argument. */
+    now?: () => number;
+}
+/** The synthetic root a Table's LITERAL rows are mounted under in a slot
+ *  cell's read view: never written to the real data model (the table keeps
+ *  those edits), never reported to the host as a path. */
+export declare const LITERAL_ROWS_ROOT = "/$xuiRows";
+/** A bound path the host may see (`undefined` for a synthetic one). */
+export declare function hostPath(path: string | undefined): string | undefined;
+export type ClientFunction = (args: Record<string, unknown>, ctx: ResolveContext) => unknown;
+/** `intlFormatter` builds a new Intl instance per call (~18 µs for a
+ *  currency); a windowed Table re-formats every visible cell per scroll
+ *  step. This wrapper memoises the RESULTS of the pure members (number,
+ *  currency, percent, date, plural) per formatter, bounded; relativeTime
+ *  (it reads a clock) passes through. */
+export declare function memoFormatter(base: Formatter, max?: number): Formatter;
+/** The context's Formatter: the surface's (`ctx.formatter`), else an Intl
+ *  one in its locale and UTC (a bare `resolveValue` call in a test). */
+export declare function formatterOf(ctx: ResolveContext): Formatter;
+export declare const CLIENT_FUNCTIONS: Record<string, ClientFunction>;
+/** A prop value with its bindings and calls resolved for one render. Plain
+ *  objects recurse (a check's `condition`, a menu item's label). */
+export declare function resolveValue(value: unknown, ctx: ResolveContext): unknown;
+export declare function resolveProps(props: Record<string, unknown>, ctx: ResolveContext): Record<string, unknown>;
+/** The catalog (core + extensions) a node's props resolve along. */
+export declare function viewOf(extensions?: readonly ExtensionDef[]): CatalogView;
+/** A node's props resolved along its component's schema (an unknown
+ *  component's resolve at any depth); undefined results are dropped. */
+export declare function resolveNodeProps(component: string, props: Record<string, unknown>, ctx: ResolveContext, extensions?: readonly ExtensionDef[]): Record<string, unknown>;
+/** The pointer a bindable prop writes back to (two-way state), if bound. */
+export declare function boundPath(props: Record<string, unknown>, name: string, scope?: string): string | undefined;
+/** A node's `visible`: absent = shown, else its resolved truthiness. */
+export declare function resolveVisible(visible: unknown, ctx: ResolveContext): boolean;
+/** True when a value holds a binding or a call anywhere (a style value the
+ *  expander left dynamic). */
+export declare function hasDynamic(value: unknown): boolean;
+/** The React renderer's BIND pass as a pure function (round-1 contract §1;
+ *  `@exponential_app/eui` `bindTree` is the reference, fixtures/bind-time.json
+ *  locks both): a node whose `visible` resolves falsy is dropped with its
+ *  subtree, props / style values / recipe props resolve, `visible` goes,
+ *  actions and templates stay. `NodeView` binds node by node with the same
+ *  `resolveValue`; this is the whole-tree form for tests and hosts. */
+/** A node's `accessibility` resolved against the data (bindings, calls,
+ *  `$string`), undefined members dropped; null when nothing is left. */
+export declare function resolveAccessibility(accessibility: unknown, ctx: ResolveContext): Record<string, unknown> | null;
+/** The ARIA attributes of a RESOLVED `accessibility` (contract §6): `role`
+ *  (`text` = none of its own, `hidden` = aria-hidden), label/description,
+ *  `level`, `expanded`, `current` (page|step; false = absent), `selected`,
+ *  `pressed`, `checked`, `valueNow/Min/Max`, `hidden`; `autoFocus` →
+ *  `data-xui-autofocus` (an opening dialog focuses it). */
+export declare function ariaAttributes(a11y: Record<string, unknown> | null): Record<string, string>;
+export declare function bindTree<T extends {
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    children: T[];
+    style?: Record<string, unknown>;
+    visible?: unknown;
+    slots?: Record<string, T>;
+    recipe?: {
+        macro: string;
+        part: string;
+        props: Record<string, unknown>;
+    };
+    on?: unknown;
+    accessibility?: unknown;
+    template?: unknown;
+}>(node: T, ctx: ResolveContext, extensions?: readonly ExtensionDef[]): T | null;

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

@@ -0,0 +1,12 @@
+export declare const isoDate: (d: Date) => string;
+export declare const parseIsoDate: (s: string) => Date | null;
+export declare const addDays: (d: Date, n: number) => Date;
+/** `n` months on, the day clamped to the target month's last. */
+export declare const addMonths: (d: Date, n: number) => Date;
+export declare const sameDay: (a: Date | null, b: Date | null) => boolean;
+/** The 6×7 days of `view`'s month, starting on `first` (0 = Sunday). */
+export declare function monthGrid(view: Date, first: number): Date[];
+/** The roving tab stop of a month view: the focused day when it is in the
+ *  visible month and enabled, else the enabled in-month day nearest to it,
+ *  else none (a disabled day never holds the stop). */
+export declare function calendarStop(days: readonly Date[], view: Date, focus: Date, disabled: (d: Date) => boolean): Date | null;

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

@@ -0,0 +1,44 @@
+/** One registered field (a renderer's handle onto its control). */
+export interface FormField {
+    name: string;
+    domId: string;
+    value: () => unknown;
+    errors: () => string[];
+    focus: () => void;
+    element: () => Element | null;
+}
+export interface FormError {
+    name: string;
+    message: string;
+}
+export type FormCheck<F extends FormField = FormField> = {
+    ok: false;
+    errors: FormError[];
+    first: F | null;
+} | {
+    ok: true;
+    values: Record<string, unknown>;
+};
+/** A component's catalog default `validateOn`, or undefined. */
+export declare function validateOnDefault(component: string): string | undefined;
+/** Whether a field shows its failing messages now. */
+export declare function fieldErrorsVisible(state: {
+    validateOn: string;
+    submitted: boolean;
+    attempts: number;
+    dirty: boolean;
+    touched: boolean;
+}): boolean;
+/** Fields in document order (unmounted ones keep their place). */
+export declare function documentOrder<F extends FormField>(fields: Iterable<F>): F[];
+export declare class FormRegistry<F extends FormField = FormField> {
+    readonly fields: Set<F>;
+    /** Adds a field; the returned function removes it. */
+    register(field: F): () => void;
+    /** Every field's checks: the failures (document order) and the first
+     *  invalid field, or the values by name. */
+    check(): FormCheck<F>;
+    /** The summary entries whose field still fails with that message (they
+     *  clear as their fields become valid). */
+    stillFailing(summary: readonly FormError[]): FormError[];
+}

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

@@ -0,0 +1,126 @@
+import type { FunctionCallInfo, MediaOptions, MediaRequest, ThemeIssue, UiNode, UrlPolicy } from "@exponential_app/eui";
+import type { ClientFunction } from "./data.js";
+import type { QrScannerHost } from "./round5.js";
+/** A registry name → the renderer's icon component (a map or a lookup). */
+export type IconMap<Icon = unknown> = Record<string, Icon | undefined> | ((name: string) => Icon | undefined);
+/** A user action: a node's `on.<event>` with an `event` action, resolved. */
+export interface SurfaceActionEvent {
+    surfaceId: string;
+    /** The catalog event (`press`, `change`, `select`, `submit`…). */
+    event: string;
+    /** The action's `event.name`. */
+    name: string;
+    componentId: string;
+    context: Record<string, unknown>;
+    /** What the component adds (a Select's `value`, a Tabs' `value`…). */
+    payload?: Record<string, unknown>;
+    timestamp: string;
+}
+/** A host-owned input edit. `change` fires debounced while typing with a
+ *  monotonically increasing `revision`; `commit` on blur / Enter. The host's
+ *  echo (a data model write at `path`) is applied only while no newer
+ *  revision is outstanding and the field is not focused. */
+export interface SurfaceInputEvent {
+    surfaceId: string;
+    componentId: string;
+    /** The input's `name` prop. */
+    name: string;
+    /** The bound data model pointer, when `value` is a binding. */
+    path?: string;
+    value: unknown;
+    revision: number;
+    kind: `change` | `commit`;
+}
+/** A painter that failed: the surface, the component, why. */
+export interface PaintError {
+    surfaceId: string;
+    componentId: string;
+    message: string;
+}
+/** One option a host source supplies (the catalog's `option` shape). */
+export interface SourceOption {
+    label: string;
+    value: string;
+    icon?: string;
+    disabled?: boolean;
+}
+export interface HostPlugin<Icon = unknown, Markdown = unknown> {
+    /** The icon registry: the catalog's `Icon` names → components. */
+    icons?: IconMap<Icon>;
+    /** Server events. Returning a promise keeps the source control in its
+     *  optimistic pending state until it settles. */
+    onAction?: (event: SurfaceActionEvent) => void | Promise<void>;
+    /** Host-owned input edits. Returning a promise acknowledges the revision
+     *  when it settles; a sync host acknowledges at once. */
+    onInput?: (event: SurfaceInputEvent) => void | Promise<void>;
+    /** Opens an href the URL policy allowed (`openUrl`, `Link`); default
+     *  `window.open(url, "_blank")`. */
+    openUrl?: (url: string) => void;
+    /** The URL policy EVERY href passes (Link, markdown links, FileUpload
+     *  file urls, openUrl): `catalog/host.json` urls. Unset = the default
+     *  schemes; relative urls resolve against `baseUrl`, else `media.baseUrl`,
+     *  else the document's. A denied href paints as text. */
+    urls?: UrlPolicy;
+    /** The media policy every src passes when there is no `mediaRequest`
+     *  (schemes, hosts, private opt-ins, base, header rules):
+     *  `catalog/host.json` media. */
+    media?: MediaOptions;
+    /** Extra or overriding client functions, web renderers only (`{call,
+     *  args}` in a prop; an action naming one runs it). Any OTHER action
+     *  function name goes to onFunctionCall (the portable host functions). */
+    functions?: Record<string, ClientFunction>;
+    /** An action `functionCall` to a name outside the built-ins (the host
+     *  function registry + its policy gate, `ExponentialHost.callFunction`).
+     *  A promise keeps the source control pending until it settles. */
+    onFunctionCall?: (call: FunctionCallInfo) => unknown | Promise<unknown>;
+    /** The media loader's request for a source (absolute url + headers, e.g.
+     *  auth for /api/attachments); null = denied. A request WITH headers is
+     *  fetched (under the media limits) and shown as a blob url; without, its
+     *  url is used as is. Its url is re-checked against `media`'s schemes,
+     *  hosts and private opt-ins. */
+    mediaRequest?: (src: string) => MediaRequest | null;
+    /** Video/Audio (`catalog/host.json` media: the byte limits do not apply,
+     *  they stream): a url the browser's player loads WITHOUT headers for a
+     *  request that carries some (a signed or cookie-authed url), so the
+     *  player streams and seeks. Its result passes the media policy again.
+     *  Unset = the request is fetched whole into a blob url under the media
+     *  byte cap and timeout for the WHOLE download (VAPP-107), so a long
+     *  video needs this hook. */
+    mediaStreamUrl?: (request: MediaRequest) => string | Promise<string>;
+    /** A richer markdown renderer than the built-in one (a component taking
+     *  `{text, className}` in the renderer's framework). */
+    Markdown?: Markdown;
+    /** Rewrites a media src BEFORE the media policy (signed URLs). */
+    resolveUrl?: (src: string) => string;
+    /** `onPaintError` (`catalog/host.json` paint): a component's painter
+     *  failed; it paints an empty box. `hostPlugin(host)` forwards it to the
+     *  agent as an A2UI `RENDER_FAILED` error. */
+    onPaintError?: (error: PaintError) => void;
+    /** Called with the node for every Unknown placeholder painted. */
+    onUnknown?: (node: UiNode) => void;
+    /** Round 4 (VAPP-103): the `theme` prop was unusable (an unknown built-in
+     *  id, a theme file with issues). The surface never throws: it paints
+     *  with the default theme and reports why here. */
+    onThemeIssues?: (issues: ThemeIssue[]) => void;
+    /** Round 1, FileUpload: the picked/dropped files' BYTES (the `upload`
+     *  event carries only `{name, size, type}`). Return a promise to keep the
+     *  drop zone busy until it settles. */
+    onUpload?: (files: File[], target: {
+        nodeId: string;
+        name: string;
+    }) => void | Promise<void>;
+    /** Round 1, Select `source`: a host list id (`exp:statuses`) → its
+     *  options for a query (`""` when not searchable). */
+    optionSource?: (source: string, query: string) => SourceOption[] | Promise<SourceOption[]>;
+    /** VAPP-162, QrScanner: THE camera (host-owned, like FileUpload's bytes):
+     *  `start(feed, formats, onValue)` renders the live feed into `feed`,
+     *  decodes codes of `formats` and calls `onValue` per decoded string;
+     *  returns the stop. Unset (or `start` returning false) = no camera: the
+     *  scanner shows its placeholder and `Camera unavailable`. */
+    qrScanner?: QrScannerHost;
+}
+/** Any renderer's plugin (what the framework-free helpers take). */
+export type AnyHostPlugin = HostPlugin<unknown, unknown>;
+/** A registry lookup: the host's map (or function) first, then the
+ *  renderer's own fallbacks. */
+export declare function lookupIcon<Icon>(icons: IconMap<Icon> | undefined, name: string, fallbacks?: Readonly<Record<string, Icon>>): Icon | undefined;

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

@@ -0,0 +1,35 @@
+export { compileTheme, compiledTheme, globalsCss, themeScope, partClass, propAttribute, tokenVar, tokenVarName, cssValue, declarations, animationDeclarations, shimmerRule, rule, ruleSelectors, isMacroComponent, STATE_SELECTORS, LAYERS } from "./theme-css.js";
+export type { CompiledTheme } from "./theme-css.js";
+export { nodeSheet, compileNodeSheet, nodeSheetBatches, dynamicStyleEntries, queryToken, nodeClass, surfaceClass, walkNodes, cssEscape, resolvedMediaKey, styleDirection } from "./box-css.js";
+export type { NodeSheet, NodeSheetBatch, DynamicStyleEntry } from "./box-css.js";
+export { BASE_CSS } from "./base-css.js";
+export { getPointer, setPointer, pointerTokens, absolutePath, resolveValue, resolveProps, resolveNodeProps, resolveVisible, resolveAccessibility, ariaAttributes, bindTree, boundPath, hostPath, isBinding, isCall, hasDynamic, memoFormatter, formatterOf, viewOf, CLIENT_FUNCTIONS, LITERAL_ROWS_ROOT } from "./data.js";
+export type { DataModel, DataBinding, FunctionCall, ClientFunction, ResolveContext } from "./data.js";
+export { linkHref, mediaRequestOf, mediaUrlAllowed, openAllowed, ownPrivateHosts, urlPolicyOf } from "./urls.js";
+export { lookupIcon } from "./host-types.js";
+export { CUSTOM_ICON_NODES } from "./custom-icons.generated.js";
+export type { CustomIconNode } from "./custom-icons.generated.js";
+export type { HostPlugin, AnyHostPlugin, IconMap, PaintError, SourceOption, SurfaceActionEvent, SurfaceInputEvent } from "./host-types.js";
+export { str, num, bool, arr, objects, phrase, formatFileSize, acceptsFile, failingChecks, failingCheck, builtinIconName, joinIds } from "./coerce.js";
+export { sortRows } from "./table.js";
+export type { TableColumn, TableSort } from "./table.js";
+export { isoDate, parseIsoDate, addDays, addMonths, sameDay, monthGrid, calendarStop } from "./dates.js";
+export { DEBOUNCE_MS, HostOwnedController, parseLocaleNumber } from "./inputs.js";
+export type { HostOwnedControllerOptions, HostOwnedSend } from "./inputs.js";
+export { MEDIA_CACHE_IDLE_MAX, acquireMedia, releaseMedia, mediaCacheKey, mediaCacheStats, clearMediaCache, openMediaSource, streamEntry, fetchStream, fetchLimited } from "./media.js";
+export type { MediaKind, MediaCacheEntry, MediaSourcePlan } from "./media.js";
+export { MAX_LINK_NESTING, MAX_LINK_DEST, MAX_BLOCK_NESTING, LIST_ITEM, linkAt, wholeImage, parseInline, parseList, parseMarkdown } from "./markdown.js";
+export type { MarkdownInline, MarkdownBlock, MarkdownList, MarkdownListItem } from "./markdown.js";
+export { FormRegistry, documentOrder, fieldErrorsVisible, validateOnDefault } from "./form.js";
+export type { FormField, FormError, FormCheck } from "./form.js";
+export { scrollParent, listViewport } from "./list.js";
+export type { ListAxis } from "./list.js";
+export { layoutSize, visualScale, elementScale } from "./primitives/measure.js";
+export type { LayoutSize } from "./primitives/measure.js";
+export { nextEnabledIndex, typeaheadStep, TYPEAHEAD_RESET_MS } from "./listbox.js";
+export type { TypeaheadBuffer } from "./listbox.js";
+export { PLACED, placedPartId } from "./parts.js";
+export { share } from "./share.js";
+export { voiceWaveAnimates, voiceWaveClock, voiceWaveFitChild, voiceWaveName } from "./primitives/voice-wave.js";
+export { qrPaint, qrScanReporter, qrScanFormats, qrCornerPath, qrFeedColour, QR_CORNERS, QR_SCANNER, segmentedBadge, ButtonHold, HOLD_SLOP, withinSlop } from "./round5.js";
+export type { QrPaint, QrScannerHost, QrCorner, HoldEvent, HoldRect } from "./round5.js";

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

@@ -0,0 +1,55 @@
+export declare const DEBOUNCE_MS = 150;
+export type HostOwnedSend<T> = (value: T, revision: number, kind: `change` | `commit`) => void | Promise<void>;
+export interface HostOwnedControllerOptions<T> {
+    /** The value the host holds when the field mounts. */
+    initial: T;
+    /** Sends an edit; a returned promise acknowledges the revision on settle. */
+    send: HostOwnedSend<T>;
+    /** Optional local write-through (the bound data model path). */
+    writeLocal?: (value: T) => void;
+    debounceMs?: number;
+    /** Called after every change of `value`, `pending` or `focused`. */
+    onChange?: () => void;
+}
+export declare class HostOwnedController<T> {
+    /** The field's value (the last edit, or the last adopted host push). */
+    value: T;
+    /** The newest revision sent or scheduled. */
+    revision: number;
+    /** True while a revision the host has not acknowledged exists. */
+    pending: boolean;
+    focused: boolean;
+    private acked;
+    private timer;
+    private live;
+    private send;
+    private writeLocal?;
+    private debounceMs;
+    private readonly onChange?;
+    constructor(options: HostOwnedControllerOptions<T>);
+    /** The latest callbacks (a re-render may hand new closures). */
+    configure(options: Pick<HostOwnedControllerOptions<T>, `send` | `writeLocal` | `debounceMs`>): void;
+    /** A local edit: bump the revision, write through, debounce a `change`. */
+    edit(next: T): void;
+    /** Flush the debounce and send a `commit`. */
+    commit(): void;
+    focus(): void;
+    /** Blur commits. */
+    blur(): void;
+    /** The host's push: adopted only when idle and fully acknowledged.
+     *  Returns whether it was adopted. */
+    push(external: T): boolean;
+    /** (Re)attach after `dispose` (a remount). */
+    attach(): void;
+    /** Unmount: the pending debounce is dropped, acknowledgements no longer
+     *  notify. */
+    dispose(): void;
+    private clearTimer;
+    private notify;
+    private ack;
+    private dispatch;
+}
+/** A typed number in the surface locale (its group and decimal separators
+ *  AND its digits; ASCII digits are always accepted too) → the number, or
+ *  null. */
+export declare function parseLocaleNumber(text: string, locale: string): number | null;

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

@@ -0,0 +1,16 @@
+export type ListAxis = `vertical` | `horizontal`;
+/** The nearest ancestor that scrolls on `axis`: overflow auto/scroll AND a
+ *  box shorter than its content (a content-sized `overflow: auto` box is not
+ *  a viewport). Null = the document scrolls (the window). */
+export declare function scrollParent(el: HTMLElement | null, axis?: ListAxis): HTMLElement | null;
+/** Where the list's content starts relative to the viewport's start on the
+ *  axis (the scroll offset in list coordinates) and the viewport length.
+ *  `known` = the scroller already found (null = the window). NEW-82: both
+ *  in the LIST's layout px: rect deltas are visual px (CSS zoom,
+ *  transforms), so they divide by the list's scale; the scroller's
+ *  client box is in its own layout px, so it multiplies by the scroller's. */
+export declare function listViewport(el: HTMLElement, axis: ListAxis, rtl: boolean, known?: HTMLElement | null): {
+    scroll: number;
+    viewport: number;
+    scroller: HTMLElement | null;
+};

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

@@ -0,0 +1,14 @@
+/** The TYPE-AHEAD buffer resets after this pause (ms). */
+export declare const TYPEAHEAD_RESET_MS = 700;
+/** The next enabled index `delta` steps from `from` (wrapping), or -1. */
+export declare function nextEnabledIndex(count: number, from: number, delta: number, isDisabled?: (index: number) => boolean): number;
+export interface TypeaheadBuffer {
+    text: string;
+    at: number;
+}
+/** One printable key typed: the new buffer and the index it lands on (-1 =
+ *  no label starts with the buffer; the active option stays). */
+export declare function typeaheadStep(buffer: TypeaheadBuffer, key: string, now: number, active: number, count: number, isDisabled: (index: number) => boolean, labelOf: (index: number) => string): {
+    buffer: TypeaheadBuffer;
+    index: number;
+};

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

@@ -0,0 +1,96 @@
+/** Link labels nest at most this deep (×4): a link inside 32 enclosing link
+ *  labels is its text. */
+export declare const MAX_LINK_NESTING = 32;
+/** A link / image destination longer than this (UTF-16 units) is no link. */
+export declare const MAX_LINK_DEST = 8192;
+/** `[label](dest)` / `![alt](dest)` starting at `s[at]` (the `[`): the label
+ *  (brackets balanced), the destination (`<…>` or balanced parentheses, no
+ *  whitespace) and the end index. An optional `"title"` is skipped. */
+export declare function linkAt(s: string, at: number): {
+    label: string;
+    dest: string;
+    end: number;
+} | null;
+/** A paragraph that is exactly one `![alt](src)` → its alt + src (a BLOCK
+ *  image, as every renderer paints it; an image inside running text is its
+ *  alt text). */
+export declare function wholeImage(text: string): {
+    alt: string;
+    src: string;
+} | null;
+/** An inline run's tree: text, code, strong/em (nested), strike, a link
+ *  (raw `dest`, label nested). */
+export type MarkdownInline = string | {
+    type: `code`;
+    text: string;
+} | {
+    type: `strong`;
+    children: MarkdownInline[];
+} | {
+    type: `em`;
+    children: MarkdownInline[];
+} | {
+    type: `del`;
+    text: string;
+} | {
+    type: `link`;
+    dest: string;
+    children: MarkdownInline[];
+};
+export type MarkdownBlock = {
+    type: `paragraph`;
+    children: MarkdownInline[];
+}
+/** A paragraph that is exactly one image. */
+ | {
+    type: `image`;
+    alt: string;
+    src: string;
+} | {
+    type: `codeBlock`;
+    lang?: string;
+    text: string;
+} | {
+    type: `heading`;
+    level: number;
+    children: MarkdownInline[];
+} | {
+    type: `quote`;
+    children: MarkdownBlock[];
+} | {
+    type: `list`;
+    list: MarkdownList;
+} | {
+    type: `table`;
+    align: (`start` | `center` | `end` | undefined)[];
+    head: MarkdownInline[][];
+    rows: MarkdownInline[][][];
+} | {
+    type: `rule`;
+};
+/** One inline run, linear in its length: the link geometry is precomputed
+ *  (LinkScanner), the simple spans come off one global regex that never
+ *  rescans, and link labels recurse at most MAX_LINK_NESTING deep. */
+export declare function parseInline(text: string, depth?: number): MarkdownInline[];
+export declare const LIST_ITEM: RegExp;
+export interface MarkdownListItem {
+    /** The item's raw text (its inline markdown). */
+    text: string;
+    /** `text` parsed. */
+    content: MarkdownInline[];
+    /** A task item: done (`[x]`) or not (`[ ]`). */
+    task?: boolean;
+    children: MarkdownList[];
+}
+export interface MarkdownList {
+    indent: number;
+    ordered: boolean;
+    items: MarkdownListItem[];
+}
+/** Consecutive list item lines → a list tree: an item whose marker is
+ *  indented 2+ columns past its list's nests under the previous item. */
+export declare function parseList(lines: readonly string[]): MarkdownList;
+/** Block quotes and lists nest at most this deep (deeper = text). */
+export declare const MAX_BLOCK_NESTING = 32;
+/** Markdown text → its block tree. */
+export declare function parseMarkdown(text: string): MarkdownBlock[];

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

@@ -0,0 +1,63 @@
+import type { AnyHostPlugin as HostPlugin } from "./host-types.js";
+/** What a source feeds: an image (the limits hold) or a player stream. */
+export type MediaKind = `image` | `stream`;
+/** How many fetched media nobody shows stay cached (their blob urls live). */
+export declare const MEDIA_CACHE_IDLE_MAX = 64;
+export interface MediaCacheEntry {
+    promise: Promise<string>;
+    /** Set once the fetch resolved. */
+    url?: string;
+    /** Mounted consumers. */
+    refs: number;
+}
+export declare function mediaCacheKey(url: string, headers: Record<string, string>): string;
+export declare function acquireMedia(k: string, load: () => Promise<string>): MediaCacheEntry;
+export declare function releaseMedia(k: string, e: MediaCacheEntry): void;
+/** The cache's size (tests). */
+export declare function mediaCacheStats(): {
+    entries: number;
+    inUse: number;
+};
+/** Drop every idle entry and revoke its url (tests, a host that logs out). */
+export declare function clearMediaCache(): void;
+/** One source, planned: `direct` = the url to use as is (no headers, or
+ *  undefined when the policy denies it), `denied` = the policy refused a
+ *  non-empty src, `key` = the cache identity of a FETCHED source ('' when
+ *  direct), `open()` = start (or join) its load: the url promise and the
+ *  release a consumer calls when it unmounts. */
+export interface MediaSourcePlan {
+    fetched: boolean;
+    key: string;
+    direct: string | undefined;
+    denied: boolean;
+    open: () => {
+        promise: Promise<string>;
+        release: () => void;
+    };
+}
+export declare function openMediaSource(host: HostPlugin, src: string, kind?: MediaKind): MediaSourcePlan;
+/** A host stream url (never cached here, never revoked: the host owns
+ *  it), re-checked against the media policy. */
+export declare function streamEntry(host: HostPlugin, req: {
+    url: string;
+    headers: Record<string, string>;
+}): MediaCacheEntry;
+/** A Video/Audio fetch (no `mediaStreamUrl`): the whole body into a blob
+ *  under `maxBytes` (Content-Length up front, then as it streams) and
+ *  `timeoutMs` for the WHOLE download (VAPP-107); no pixel check. */
+export declare function fetchStream(url: string, headers: Record<string, string>, limits?: {
+    maxBytes: number;
+    timeoutMs: number;
+}, allowed?: (url: string) => boolean): Promise<Blob>;
+/** A fetch under `MEDIA_LIMITS`: the whole request within `timeoutMs`, the
+ *  body (Content-Length up front, then as it streams) within `maxBytes`, an
+ *  image's width × height × frames within `maxPixels` before any decode
+ *  (`mediaImageWithinLimits`: SVG sizes count, an unreadable raster is
+ *  refused; `image = false` skips that check: a stream's bytes are not
+ *  an image). A redirected response's final url must pass `allowed` (the
+ *  host's media policy) or the load fails before a byte is read. */
+export declare function fetchLimited(url: string, headers: Record<string, string>, limits?: {
+    maxBytes: number;
+    timeoutMs: number;
+    maxPixels: number;
+}, image?: boolean, allowed?: (url: string) => boolean): Promise<Blob>;

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

@@ -0,0 +1,4 @@
+export declare const PLACED: Readonly<Record<string, readonly string[]>>;
+/** The painted id of a SINGLE part (`<domId>.<part>`), or null when the
+ *  component does not place it. */
+export declare function placedPartId(component: string, part: string, domId: string): string | null;

package/dist/types/src/web/primitives/alert-dialog.d.ts

@@ -0,0 +1,10 @@
+export declare const ALERT_DIALOG_CLASSES: {
+    readonly overlay: "fixed inset-0 z-50 bg-black/50 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:duration-fast data-[state=closed]:ease-accelerate data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:duration-standard data-[state=open]:ease-decelerate";
+    readonly content: "fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border bg-background p-6 shadow-lg motion-dialog sm:max-w-lg";
+    readonly header: "flex flex-col gap-2 text-center sm:text-left";
+    readonly footer: "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end";
+    readonly title: "text-lg font-semibold";
+    readonly description: "text-sm text-muted-foreground";
+    readonly action: string;
+    readonly cancel: string;
+};

package/dist/types/src/web/primitives/alert.d.ts

@@ -0,0 +1,9 @@
+import { type VariantProps } from "class-variance-authority";
+export declare const alertVariants: (props?: ({
+    variant?: "default" | "destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type AlertVariantProps = VariantProps<typeof alertVariants>;
+export declare const ALERT_CLASSES: {
+    readonly title: "col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight";
+    readonly description: "col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed";
+};

package/dist/types/src/web/primitives/avatar-color.d.ts

@@ -0,0 +1,2 @@
+export declare const AVATAR_HUE_COUNT = 8;
+export declare function avatarHueIndex(userId: string | null | undefined): number;

package/dist/types/src/web/primitives/avatar.d.ts

@@ -0,0 +1,13 @@
+export declare const AVATAR_CLASSES: {
+    readonly root: "relative flex size-8 shrink-0 overflow-hidden rounded-full select-none";
+    readonly image: "aspect-square size-full";
+    readonly fallback: "flex size-full items-center justify-center rounded-full text-sm";
+    /** The fallback without a `userId`: the muted chrome. */
+    readonly fallbackMuted: "bg-muted text-muted-foreground";
+};
+export declare function avatarFallbackHue(userId: string | null | undefined): string | undefined;
+/** The inline colours of a hued fallback. */
+export declare function avatarFallbackColors(hue: string): {
+    backgroundColor: string;
+    color: string;
+};

package/dist/types/src/web/primitives/badge.d.ts

@@ -0,0 +1,10 @@
+export type BadgeTone = `muted` | `primary`;
+export declare const BADGE_CLASSES: {
+    readonly root: "pointer-events-none inline-flex h-4 min-w-4 shrink-0 items-center justify-center rounded-full px-1 text-[10px] leading-none font-semibold tabular-nums";
+    readonly tones: {
+        readonly primary: "bg-primary text-primary-foreground";
+        readonly muted: "bg-muted text-muted-foreground";
+    };
+};
+/** What the badge prints for `count` (zero and below render nothing). */
+export declare function badgeLabel(count: number, max?: number): string;

package/dist/types/src/web/primitives/breadcrumb.d.ts

@@ -0,0 +1,10 @@
+export declare const BREADCRUMB_CLASSES: {
+    readonly list: "flex list-none flex-wrap items-center gap-1.5 text-sm break-words text-muted-foreground sm:gap-2.5";
+    readonly item: "inline-flex items-center gap-1.5";
+    readonly link: "transition-colors hover:text-foreground";
+    readonly page: "font-normal text-foreground";
+    readonly separator: "[&>svg]:size-3.5";
+    readonly ellipsis: "flex size-9 items-center justify-center";
+    readonly ellipsisIcon: "size-4";
+    readonly srOnly: "sr-only";
+};