@adia-ai/web-components 0.5.5 → 0.5.6

package/components/agent-feedback-bar/class.js

@@ -45,12 +45,17 @@
 
 import { UIElement } from '../../core/element.js';
 
-function makeButton({ icon, text = '' }) {
+function makeButton({ icon, text = '', title = '' }) {
   const btn = document.createElement('button-ui');
   btn.setAttribute('icon', icon);
   btn.setAttribute('variant', 'ghost');
   btn.setAttribute('size', 'sm');
   if (text) btn.setAttribute('text', text);
+  // §190a (v0.5.6): supply title= for icon-only buttons. button-ui's §184
+  // FEEDBACK-08 §8 a11y safety-net mirrors title → aria-label automatically
+  // when the button is icon-only. Closes the per-render console.warn class
+  // captured 2026-05-14 ("Icon-only button is missing an accessible name").
+  if (!text && title) btn.setAttribute('title', title);
   return btn;
 }
 
@@ -142,11 +147,12 @@ export class UIAgentFeedbackBar extends UIElement {
   #build() {
     this.innerHTML = '';
 
-    this.#upEl = makeButton({ icon: 'thumbs-up' });
-    this.#downEl = makeButton({ icon: 'thumbs-down' });
+    this.#upEl = makeButton({ icon: 'thumbs-up', title: 'Rate this response positively' });
+    this.#downEl = makeButton({ icon: 'thumbs-down', title: 'Rate this response negatively' });
     this.#saveEl = makeButton({
       icon: this.saveIcon || 'bookmark-simple',
       text: this.saveLabel || '',
+      title: this.saveLabel ? '' : 'Save this response',
     });
     if (!this.saveLabel) this.#saveEl.hidden = true;
 

package/components/segmented/segmented.d.ts

@@ -6,10 +6,10 @@
 
 import { UIFormElement } from '../../core/form.js';
 
-export interface SegmentedChangeEventDetail {
-  value: string;
+export interface SegmentedChangeEventDetail<V extends string = string> {
+  value: V;
 }
-export type SegmentedChangeEvent = CustomEvent<SegmentedChangeEventDetail>;
+export type SegmentedChangeEvent<V extends string = string> = CustomEvent<SegmentedChangeEventDetail<V>>;
 
 export class UISegmented extends UIFormElement {
   /** Selected segment's value. */

package/components/select/select.d.ts

@@ -16,10 +16,10 @@ export interface SelectOption {
   divider?: boolean;
 }
 
-export interface SelectChangeEventDetail {
-  value: string;
+export interface SelectChangeEventDetail<V extends string = string> {
+  value: V;
 }
-export type SelectChangeEvent = CustomEvent<SelectChangeEventDetail>;
+export type SelectChangeEvent<V extends string = string> = CustomEvent<SelectChangeEventDetail<V>>;
 
 export interface SelectActionEventDetail {
   action: string;

package/components/switch/switch.d.ts

@@ -6,13 +6,13 @@
 
 import { UIFormElement } from '../../core/form.js';
 
-export interface SwitchChangeEventDetail {
+export interface SwitchChangeEventDetail<V extends string = string> {
   /** Submitted value (defaults to `"on"` when checked). */
-  value: string;
+  value: V;
   /** Current checked state. */
   checked: boolean;
 }
-export type SwitchChangeEvent = CustomEvent<SwitchChangeEventDetail>;
+export type SwitchChangeEvent<V extends string = string> = CustomEvent<SwitchChangeEventDetail<V>>;
 
 export class UISwitch extends UIFormElement {
   /** Checked state — reflected, toggles on click. */

package/components/toast/toast.d.ts

@@ -12,6 +12,28 @@
 
 import { UIElement } from '../../core/element.js';
 
+/** Options accepted by `UIToast.show(opts)` — the imperative one-shot path. */
+export interface UIToastShowOptions {
+  /** Toast message text. */
+  text?: string;
+  /** Semantic variant. Legacy alias `"error"` is auto-mapped to `"danger"`. */
+  variant?: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral' | 'error';
+  /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. Default `4000`. */
+  duration?: number;
+  /** Screen position. Default `'bottom-right'`. */
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+}
+
+/** Returned by `UIToast.show()` — imperative handle for dismiss / update. */
+export interface UIToastFeedHandle {
+  /** Stable id assigned by `<feed-ui>`. `null` if the toast couldn't be posted. */
+  id: string | null;
+  /** Dismiss the toast programmatically. */
+  dismiss(): void;
+  /** Mutate the toast's content in-place (e.g. promote from "loading" to "done"). */
+  update(patch: Partial<UIToastShowOptions>): void;
+}
+
 export class UIToast extends UIElement {
   /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. */
   duration: number;
@@ -21,4 +43,17 @@ export class UIToast extends UIElement {
   text: string;
   /** Semantic variant — `default | info | success | warning | danger`. `primary` and `muted` are style hints; canonical "neutral but interesting" tone is `info`. */
   variant: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral';
+
+  /**
+   * Post a one-shot toast through the shared `<feed-ui>` host. Imperative
+   * alternative to declarative `<toast-ui>`. Returns a `UIToastFeedHandle`
+   * for programmatic dismiss / update.
+   *
+   * Legacy alias `variant: 'error'` is auto-mapped to `variant: 'danger'`.
+   *
+   * @example
+   *   const t = UIToast.show({ text: 'Saved!', variant: 'success' });
+   *   setTimeout(() => t.dismiss(), 1000);
+   */
+  static show(opts?: UIToastShowOptions): UIToastFeedHandle;
 }

package/core/anchor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Anchor positioning — positions a popover/panel relative to an anchor
+ * element. Uses native CSS Anchor Positioning when supported (Chrome
+ * 125+), falls back to a JS implementation (`getBoundingClientRect()` +
+ * `position: fixed`) otherwise.
+ *
+ * Works with the Popover API: the popover renders in the top layer via
+ * `showPopover()` on a `popover="manual"` or `popover="auto"` element,
+ * and the position is wired with either `anchor()` + `position-area` or
+ * manual coords.
+ *
+ * Runtime exports mirror `core/anchor.js`. `.d.ts` authored in v0.5.6
+ * §191 to close the §178 audit-script baseline missing-sibling gap.
+ *
+ * @see ./anchor.js (runtime SoT)
+ * @see ../USAGE.md (consumer guide)
+ */
+
+/**
+ * Placement vocabulary for {@link anchorPopover}. Mirrors a subset of
+ * the floating-ui / Popper conventions. `-start` aligns the popover's
+ * leading edge to the anchor's leading edge along the perpendicular
+ * axis; `-end` aligns the trailing edges; bare (no suffix) centers.
+ */
+export type Placement =
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
+
+/**
+ * Options for {@link anchorPopover}.
+ */
+export interface AnchorOptions {
+  /** Where to place the popover relative to its anchor. Default: `bottom-start`. */
+  placement?: Placement;
+  /** Pixel gap on the main (anchor-adjacent) axis. Default: 4. */
+  gap?: number;
+  /**
+   * When true, the popover's `width` is constrained to match the
+   * anchor's width — useful for combobox-style listboxes.
+   */
+  matchWidth?: boolean;
+}
+
+/**
+ * `true` when the current browser supports the CSS Anchor Positioning
+ * primitives the native path uses (`anchor-name`, `position-area`).
+ * `false` otherwise (browser falls back to the JS positioning path).
+ */
+export const supportsAnchorCSS: boolean;
+
+/**
+ * Position `popover` relative to `anchor`. Picks the native CSS Anchor
+ * Positioning path when available, otherwise the JS fallback. Returns a
+ * cleanup function — call it to detach listeners / restore inline
+ * styles.
+ */
+export function anchorPopover(
+  anchor: Element,
+  popover: HTMLElement,
+  options?: AnchorOptions,
+): () => void;

package/core/controller.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Controller pattern — host-attached state objects that reflect into
+ * the DOM + notify subscribers on change. `BaseController` is the
+ * minimal contract; `RouteController` is the canonical routing-state
+ * implementation used by `<router-ui>` (see `core/provider.js`).
+ *
+ * Runtime exports mirror `core/controller.js`. `.d.ts` authored in
+ * v0.5.6 §191 to close the §178 audit-script baseline missing-sibling
+ * gap.
+ *
+ * @see ./controller.js (runtime SoT)
+ * @see ./provider.js (`<router-ui>` consumer of `RouteController`)
+ */
+
+/**
+ * Static schema each {@link BaseController} subclass should declare so
+ * the dev-warn at `connect()` time can identify the controller in
+ * diagnostics. Optional but conventional.
+ */
+export interface ControllerSchema {
+  /** Stable lowercase controller identifier (e.g. `"route"`). */
+  name: string;
+  /** Map of public state field names → human-readable type label. */
+  state?: Record<string, string>;
+  /** List of canonical command names available on the controller. */
+  commands?: ReadonlyArray<string>;
+  /** Host attributes the controller writes via `reflect()`. */
+  attributes?: ReadonlyArray<string>;
+}
+
+/**
+ * Base class for host-attached controllers.
+ *
+ * Subclasses MUST implement `getState()` and SHOULD declare a static
+ * `schema`; the constructor warns when these are missing the first
+ * time the controller is connected.
+ */
+export class BaseController {
+  /** Optional schema (subclasses declare via `static schema = …`). */
+  static schema?: ControllerSchema;
+
+  /** The host element this controller is attached to, or `null`. */
+  readonly host: Element | null;
+
+  /**
+   * Wire the controller to a host element. Calls
+   * {@link onConnect} + {@link reflect} once.
+   */
+  connect(host: Element): void;
+
+  /**
+   * Detach from `host` (or the currently-connected host if omitted).
+   * Calls {@link onDisconnect}.
+   */
+  disconnect(host?: Element): void;
+
+  /**
+   * Subscribe to state-change notifications. Returns an unsubscribe
+   * function.
+   */
+  subscribe(fn: () => void): () => void;
+
+  /**
+   * Run subscriber callbacks + `reflect()` after a state mutation.
+   * Subclasses call this from their command implementations.
+   */
+  notify(): void;
+
+  /** Lifecycle hook — override to wire listeners at connect time. */
+  onConnect(host: Element): void;
+
+  /** Lifecycle hook — override to release listeners at disconnect time. */
+  onDisconnect(host: Element): void;
+
+  /**
+   * Override to write controller state into the host (attributes,
+   * data-* properties, etc.). Called on every {@link notify} + at
+   * `connect()`.
+   */
+  reflect(): void;
+
+  /**
+   * Return the controller's current public state. Subclasses MUST
+   * override. The default implementation throws.
+   */
+  getState(): unknown;
+}
+
+/**
+ * A single route declaration consumed by {@link RouteController}.
+ */
+export interface Route {
+  /**
+   * Path pattern. Static segments match literally; segments prefixed
+   * with `:` are captured into `params`. e.g. `/users/:id`.
+   */
+  path: string;
+  /** Optional content URL for `<router-ui>` to fetch + inject. */
+  content?: string;
+  /** Optional document title to set when the route matches. */
+  title?: string;
+  /** Optional section identifier (consumer-defined). */
+  section?: string;
+  /** Open-ended — route definitions can carry arbitrary metadata. */
+  [key: string]: unknown;
+}
+
+/**
+ * Public state shape returned by {@link RouteController.getState}.
+ */
+export interface RouteState {
+  /** Current pathname being matched. */
+  path: string;
+  /** Captured `:param` values from the matched route. */
+  params: Record<string, string>;
+  /** The matched route declaration, or `null` if no match. */
+  route: Route | null;
+  /** Previous pathname (before the most recent navigation). */
+  previous: string;
+}
+
+/**
+ * Imperative commands exposed by {@link RouteController}. Wire-up
+ * stable across both code-driven navigation + DOM-driven link clicks
+ * (the latter via `<router-ui>`'s click delegation).
+ */
+export interface RouteCommands {
+  /** Push a new pathname onto the history stack + re-match routes. */
+  navigate(path: string): void;
+  /** Replace the current history entry's pathname + re-match. */
+  replace(path: string): void;
+  /** Equivalent to `history.back()` when `historySync` is on. */
+  back(): void;
+  /** Equivalent to `history.forward()` when `historySync` is on. */
+  forward(): void;
+  /** Swap the routes table at runtime (re-matches the current path). */
+  setRoutes(routes: ReadonlyArray<Route>): void;
+}
+
+/**
+ * Constructor options for {@link RouteController}.
+ */
+export interface RouteControllerOptions {
+  /** Initial routes table. May be empty + updated later via `setRoutes`. */
+  routes?: ReadonlyArray<Route>;
+  /** Initial pathname (defaults to `location.pathname`). */
+  initial?: string;
+  /**
+   * When `true` (default), navigate/replace push to History API +
+   * `popstate` syncs state on browser back/forward.
+   */
+  historySync?: boolean;
+}
+
+/**
+ * Routing-state controller. Used by `<router-ui>` (see
+ * `core/provider.js`) as the canonical history-syncing route matcher.
+ * Can also be used standalone — `notify()` fires whenever the path
+ * changes; `getState()` returns the current match.
+ */
+export class RouteController extends BaseController {
+  static schema: ControllerSchema;
+
+  constructor(options?: RouteControllerOptions);
+
+  /** Public state — path, params, matched route, previous path. */
+  getState(): RouteState;
+
+  /** Imperative API; wire from command palette / link handlers. */
+  commands: RouteCommands;
+}

package/core/markdown.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal markdown → HTML renderer for LLM output. Handles fenced code
+ * blocks, inline code, bold, italic, links, lists, headings, and
+ * paragraphs. No external dependencies.
+ *
+ * Fenced code blocks with a language identifier emit `<code-ui
+ * language="…">…</code-ui>` so the syntax-highlight upgrade picks them
+ * up automatically (see SPEC-CODE-EDITOR-001). Unlabeled fences keep
+ * the bare `<pre><code>…</code></pre>` form.
+ *
+ * Runtime exports mirror `core/markdown.js`. `.d.ts` authored in v0.5.6
+ * §191 to close the §178 audit-script baseline missing-sibling gap.
+ *
+ * @see ./markdown.js (runtime SoT)
+ */
+
+/**
+ * Render a markdown source string to HTML.
+ *
+ * The output is a sanitized HTML string suitable for direct
+ * `element.innerHTML` assignment — text content is HTML-escaped before
+ * inline formatting is applied. Consumer is responsible for any
+ * additional context-specific sanitization (e.g. URL-scheme allowlisting
+ * for the link targets).
+ */
+export function renderMarkdown(src: string): string;

package/core/polyfills.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Optional polyfills — for consumers extending BELOW the library's
+ * stated baseline (Chromium 125+, Safari 17.4+, Firefox 129+).
+ *
+ * **Side-effect-only module.** Importing this file runs feature checks
+ * at module-evaluation time and dynamically loads polyfills only when
+ * the runtime lacks support:
+ *
+ * - Popover API (consumers extending to Firefox < 125 / Safari < 17)
+ * - CSS Anchor Positioning (consumers extending to Safari < 26 /
+ *   Firefox < 147)
+ *
+ * Browsers with native support skip the download. The polyfill
+ * packages (`@oddbird/popover-polyfill`, `@oddbird/css-anchor-positioning`)
+ * are optional — if not installed, the import silently fails.
+ *
+ * Consumers on the stated baseline should NOT import this module — the
+ * runtime checks resolve to no-op, but skipping the file avoids the
+ * conditional `import()` setup entirely.
+ *
+ * Runtime mirror: `core/polyfills.js`. `.d.ts` authored in v0.5.6 §191
+ * to close the §178 audit-script baseline missing-sibling gap.
+ *
+ * @see ./polyfills.js (runtime SoT)
+ */
+
+// Side-effect-only module — no exports. The empty `export {}` marks
+// the file as an ES module so TypeScript treats `import '...polyfills.js'`
+// as a valid module side-effect import without complaining about a
+// missing module shape.
+export {};

package/core/provider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `<router-ui>` provider — declarative + imperative client-side
+ * routing built on {@link RouteController} (re-declared here for
+ * historical reasons; the canonical export lives in `core/controller.js`).
+ *
+ * Two consumer paths:
+ *
+ *  1. **Declarative** — assign `router.routes = [...]` and the provider
+ *     instantiates its own controller, wires `popstate`, intercepts
+ *     same-origin link clicks, fetches each matched route's `content`
+ *     URL, and injects into the host element.
+ *
+ *  2. **Controller-driven** — construct a {@link RouteController}
+ *     yourself + assign to `router.controller`. Useful when multiple
+ *     UI surfaces need to share routing state.
+ *
+ * Side-effect: importing this module calls
+ * `customElements.define('router-ui', UIRouter)`.
+ *
+ * Runtime exports mirror `core/provider.js`. `.d.ts` authored in v0.5.6
+ * §191 to close the §178 audit-script baseline missing-sibling gap.
+ *
+ * @see ./provider.js (runtime SoT — also defines `customElements`)
+ * @see ./controller.d.ts (canonical `RouteController` typing)
+ */
+
+import { UIElement } from './element.js';
+import type { Route, RouteCommands, RouteState, ControllerSchema, RouteControllerOptions } from './controller.js';
+import { BaseController } from './controller.js';
+
+/**
+ * Routing-state controller. Re-declared from `core/controller.js` for
+ * historical compatibility — both files define the same class shape;
+ * consumers can import either. New code should prefer
+ * `import { RouteController } from '@adia-ai/web-components/core/controller'`
+ * for the canonical path.
+ */
+export class RouteController extends BaseController {
+  static schema: ControllerSchema;
+  constructor(options?: RouteControllerOptions);
+  getState(): RouteState;
+  commands: RouteCommands;
+}
+
+/**
+ * Optional async transform applied to fetched route content before
+ * injection. Useful for wrapping content in a layout shell.
+ */
+export type TemplateResolver = (html: string, route: Route) => string | Promise<string>;
+
+/**
+ * `<router-ui>` custom element. Side-effect-registered on module load.
+ */
+export class UIRouter extends UIElement {
+  /** Currently-bound controller (declarative-mode controller is auto-created). */
+  controller?: RouteController;
+
+  /** Optional template wrapper hook — see {@link TemplateResolver}. */
+  templateResolver?: TemplateResolver;
+
+  /**
+   * Declarative-mode setter — assigning routes auto-creates an
+   * internal {@link RouteController} on first assignment, or
+   * `setRoutes`-replaces the table on subsequent ones.
+   */
+  set routes(list: ReadonlyArray<Route>);
+
+  /** Shortcut for `controller.commands.navigate(path)`. */
+  navigate(path: string): void;
+
+  /** Shortcut for `controller.commands.replace(path)`. */
+  replace(path: string): void;
+}
+
+/**
+ * `router-ui` is registered as a side-effect of module load.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    'router-ui': UIRouter;
+  }
+}

package/core/streams-bridge.d.ts

@@ -0,0 +1,78 @@
+/**
+ * streams-bridge — proxy data-stream signals into A2UI surface data
+ * models (per OD-CHART-16 option b).
+ *
+ * The bridge duck-types the renderer (it needs `.process()`, nothing
+ * else), so it works with any A2UI-protocol consumer — the actual
+ * `A2UIRenderer` from `@adia-ai/a2ui-runtime`, a custom renderer, or
+ * a test stub.
+ *
+ * Contract:
+ *  - One-way only: stream → data model. A2UI writes back to its model
+ *    (e.g. via `update-data-model` wiring actions) do NOT propagate
+ *    into the stream signal.
+ *  - Tear down with the returned dispose function. Dispose detaches
+ *    the effect; it does NOT release the stream's refcount.
+ *  - `select` uses dot-separated path syntax (matches
+ *    `data-stream-path` on the trait). `path` uses slash-separated
+ *    syntax (matches A2UI bindings).
+ *
+ * Runtime exports mirror `core/streams-bridge.js`. `.d.ts` authored in
+ * v0.5.6 §191 to close the §178 audit-script baseline missing-sibling
+ * gap.
+ *
+ * @see ./streams-bridge.js (runtime SoT)
+ * @see ./data-stream.js (the stream registry the bridge reads from)
+ */
+
+/**
+ * Minimal renderer contract the bridge requires. The actual
+ * `A2UIRenderer` from `@adia-ai/a2ui-runtime` satisfies this surface,
+ * as does any custom renderer that handles
+ * `{ type: 'updateDataModel', ... }` actions.
+ */
+export interface BridgeRenderer {
+  process(action: {
+    type: 'updateDataModel';
+    surfaceId: string;
+    path: string;
+    value: unknown;
+  }): void;
+}
+
+/**
+ * Bridge options shared by {@link bridgeStream} and
+ * {@link bridgeStreamAsync}.
+ */
+export interface BridgeOptions {
+  /** Target surface ID inside the renderer's data model. */
+  surfaceId: string;
+  /** Stream registry ID (the same string passed to `acquireStream`). */
+  streamId: string;
+  /** Slash-separated A2UI data-model path inside the surface. */
+  path: string;
+  /** Optional dot-separated path to a sub-value within the stream's signal value. */
+  select?: string;
+}
+
+/**
+ * Bridge a registered stream into a renderer's surface data model.
+ *
+ * If the stream is not yet registered, logs a warning and returns a
+ * no-op dispose. Use {@link bridgeStreamAsync} when the stream might
+ * register after this call (e.g. DOM source connecting on the same
+ * tick as the bridge wiring).
+ *
+ * Returns a dispose function — call it to detach the effect.
+ */
+export function bridgeStream(renderer: BridgeRenderer, opts: BridgeOptions): () => void;
+
+/**
+ * Async variant — awaits the stream's registration before attaching
+ * the effect. Resolves once the bridge is wired (the resolved value
+ * is the dispose function).
+ */
+export function bridgeStreamAsync(
+  renderer: BridgeRenderer,
+  opts: BridgeOptions,
+): Promise<() => void>;

package/core/transport.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Transport — `fetch` wrapper with timeout, exponential-backoff
+ * retries, and a normalized {@link TransportError} for predictable
+ * downstream handling.
+ *
+ * Zero dependencies. Vanilla-JS-friendly — drop into CodePen,
+ * StackBlitz, or any vanilla project.
+ *
+ * Runtime exports mirror `core/transport.js`. `.d.ts` authored in
+ * v0.5.6 §191 to close the §178 audit-script baseline missing-sibling
+ * gap.
+ *
+ * @see ./transport.js (runtime SoT)
+ */
+
+/**
+ * Discriminator for {@link TransportError} kinds. Lets consumers
+ * branch on user-cancellation (`abort`) vs network errors (`network`)
+ * vs HTTP-level non-2xx (`http`) vs timeout exhaustion (`timeout`).
+ */
+export type TransportErrorKind = 'abort' | 'timeout' | 'network' | 'http';
+
+/**
+ * Options for {@link request} and {@link json}.
+ */
+export interface TransportOptions {
+  /** Standard `fetch` init forwarded as-is (method, headers, body, …). */
+  init?: RequestInit;
+  /** Per-request timeout in ms. Default: 30 000. Aborts the underlying fetch. */
+  timeout?: number;
+  /** Retry attempts on 5xx + network failures. Default: 0. */
+  retries?: number;
+  /** Base retry delay in ms; exponential backoff applies. Default: 1000. */
+  retryDelay?: number;
+  /** External `AbortSignal` — aborts the request + skips retries. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Resilient `fetch` with timeout + retries. Returns the raw `Response`
+ * — consumers handle status codes (the `request()` path does NOT throw
+ * on non-2xx responses; use {@link json} when 2xx-only is desired).
+ *
+ * Throws {@link TransportError} on:
+ *  - Caller-driven abort (`kind: 'abort'`)
+ *  - Timeout exhaustion (`kind: 'timeout'`)
+ *  - Network failure after retries exhausted (`kind: 'network'`)
+ */
+export function request(url: string, options?: TransportOptions): Promise<Response>;
+
+/**
+ * JSON-typed variant of {@link request}. On 2xx responses, returns the
+ * parsed JSON body. On non-2xx responses, throws {@link TransportError}
+ * with `kind: 'http'` + the status code + the body (parsed as JSON if
+ * possible, else raw text).
+ */
+export function json<T = unknown>(url: string, options?: TransportOptions): Promise<T>;
+
+/**
+ * Normalized error thrown by {@link request} and {@link json}. The
+ * `kind` discriminator lets consumers branch on user-cancellation vs
+ * timeout vs network vs HTTP-level failures.
+ *
+ * Inherits `message` + `cause` from `Error`.
+ */
+export class TransportError extends Error {
+  /** Error category — see {@link TransportErrorKind}. */
+  kind: TransportErrorKind;
+  /** HTTP status code on `kind: 'http'`; `undefined` otherwise. */
+  status?: number;
+  /** Response body on `kind: 'http'` (parsed JSON or raw text). */
+  body?: unknown;
+
+  constructor(
+    message: string,
+    options?: { kind?: TransportErrorKind; status?: number; body?: unknown; cause?: unknown },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",