@yschimke/livery-a2ui 0.0.0-stage → 0.12.0

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# @yschimke/livery-a2ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Livery contracts as [A2UI](https://a2ui.org) components on the web, for A2UI's Lit, React and Angular renderers. An agent places a component per contract and sends its data. The page then picks a
+reviewed, signed template for it, binds the data through the contract, and plays the template on a
+canvas in the page with the TypeScript Remote Compose player (the default), or Compose Multiplatform
+compiled to Wasm (`player: 'cmp'`). A data change sets named values on the
+playing document; it never reloads it. Actions in the template become A2UI events, or are written
+back to the data model.
+
+The player is vendored from the commit recorded in `../core/vendor/PROVENANCE.md`, with the fixes this package needs
+([yschimke/rc-players#829](https://github.com/yschimke/rc-players/pull/829)): without them, these
+templates lay out at `NaN` and their buttons don't fire.
+
+The work is done by Livery's own Kotlin client compiled to Wasm (`livery-web`), which this package
+ships in `dist/livery-web/`. That covers selection, trust, binding, instantiation and the action
+gate, so the web behaves like every other Livery client. See [docs/A2UI.md](../../docs/A2UI.md).
+
+## Use
+
+```ts
+import '@a2ui/lit/v0_9';
+import { MessageProcessor } from '@a2ui/web_core/v0_9';
+import { LiverySession, liveryCatalog } from '@yschimke/livery-a2ui';
+
+const session = await LiverySession.open({
+  catalog: 'https://example.com/catalog/',            // manifest.json is beside it
+  keys: [{ keyId: 'main', publicKey: '<base64 raw Ed25519 key>' }],
+  appKinds: ['navigate'],                             // kinds this page handles itself
+});
+const { catalog } = await liveryCatalog(session, {
+  catalogId: 'https://example.com/a2ui/catalog/v1',   // what the client advertises
+  onAppAction: (kind, action, args) => { /* navigate, … */ },
+  onProblem: (component, message) => { /* tell the agent */ },
+});
+const processor = new MessageProcessor([catalog], (action) => sendToAgent(action));
+```
+
+Then render surfaces with `<a2ui-surface>` as usual. `session.catalogSchema(catalogId)` returns
+the components' JSON schema to prompt an agent with. `livery build --a2ui` writes the same schema
+at publish time.
+
+### Player choice
+
+```ts
+const { catalog } = await liveryCatalog(session, {
+  catalogId: 'https://example.com/a2ui/catalog/v1',
+  player: 'cmp', // omit or use 'ts' for the default
+});
+```
+
+`'cmp'` prepares the optional `livery-web-compose` module, Skiko and bundled Roboto Flex / Noto
+Sans Symbols 2 fonts before returning the catalog. Rendering and value updates never fetch fonts.
+It mounts one Compose viewport in the component's DOM, with no iframe. Both players keep the
+same document loaded across data changes; changes to baked images or `long` values change its key.
+The theme, height rule, session, decision ID and action gate are shared.
+
+Each CMP viewport owns a Skia context. At most eight are reserved across the page; additional
+components use TS for their lifetime. Disconnecting releases the viewport and its reservation.
+This keeps long chats from exhausting browser WebGL contexts; it is not a performance guarantee.
+
+A custom `player: (box, onAction) => LiveryPlayer` implements `show`, `resize`, `forget`, `dispose`
+and `stats`. `show` resolves `false` when superseded or disposed; it resolves `true` after drawing.
+For the synchronous `liveryComponent` API, pass `player: await prepareCmpPlayer()` instead of the
+`'cmp'` shorthand. Runtime or font preparation failures reject `liveryCatalog`; a document the
+prepared CMP player cannot render follows the usual chosen-design/automatic fallback route.
+
+See [the comparison and measured costs](../../docs/A2UI-CMP.md). CMP uses the same Kotlin player
+as desktop, but no player is the specification or a promise of Android-identical pixels.
+
+### Serving
+
+The page serves this package's `dist/livery-web/` (fetched beside `dist/livery.js`, `.wasm` as
+`application/wasm`) and the catalog (its `manifest.json` and blobs). The player is in the bundle:
+`vendor/remote-compose-player.mjs` (vendor/PROVENANCE.md).
+
+The module's glue imports `@js-joda/core`, a dependency of this package. A bundler resolves it; a
+page without one uses an import map. For CMP, also serve `dist/livery-web-compose/` beside the
+package's JS modules, preserving its `fonts/` subdirectory. A TS-only page never requests it.
+`prepareCmpPlayer` and the catalog option compute asset URLs relative to their module; when
+bundling, copy both Wasm directories beside the resulting bundle. Serve `.wasm` as `application/wasm`.
+
+### Theme and size
+
+Each theme role (`primary`, `surface`, `onSurface`, …) comes from the first of these that is set:
+
+1. For `primary`, the agent's `createSurface` theme: `primaryColor`.
+2. `--livery-<role>`, for example `--livery-on-surface`.
+3. A2UI's `--a2ui-color-<role>`.
+4. Material 3's baseline colour.
+
+Templates therefore match the basic components around them. The width the element gets selects
+the design. The height is `--livery-a2ui-height` when the page sets it; otherwise it's the
+measured root content at that width, clamped to the target's `minHeightDp` when declared.
+Documents without a finite root measurement use their authored height as the fallback.
+The sample banner wraps to 112dp instead of its 160dp authored viewport.
+
+## Develop
+
+```sh
+build-brief ./gradlew :livery-web:webDist :livery-web-compose:webDist :livery-publish:installDist :livery-capture-cmp:sampleCatalogs   # the Wasm module, the CLI the test builds a catalog with, and the built sample catalogs
+npm ci && npm run check && npm run build
+npm test                                                    # headless Chromium (Playwright)
+```
+
+`npm test` serves the sample catalog to a page that runs A2UI's own engine with each of the Lit, React and Angular renderers, then
+checks rendering, interactions and offline behavior for both players:
+
+- both templates draw on a canvas in the page, with no iframe;
+- an action reaches the agent with only its declared arguments, and a `set` writes the data model;
+- a data change sets values on the playing document without reloading it, and redraws it;
+- Livery's events carry the A2UI decision id, `a2ui:<surfaceId>/<componentId>`;
+- a surface's `primaryColor` colours its templates over the page's CSS theme;
+- a component wraps measured content unless the page sets its height;
+- a second catalog's components keep their own session;
+- container resizing, disconnect/reconnect, queued shows and disposal during loading;
+- fifteen simultaneous components respect the eight-CMP-viewport bound.
+
+### npm releases
+
+`@yschimke/livery-a2ui` follows the repository version. Release-please updates its package and lockfile;
+merging the release PR builds and checks the npm tarball, then publishes it alongside Maven.
+The first publication is bootstrapped manually under the npm account owning `@yschimke`.
+Then configure npm trusted publishing for GitHub owner `yschimke`, repository `livery`,
+workflow `release.yml`, with no environment and direct publishing allowed. Subsequent releases
+use GitHub Actions OIDC; no `NPM_TOKEN` secret is required. The bundled
+`@yschimke/livery-web` dependency does not need a separate registry publication.
+See the [first-publish instructions](https://github.com/yschimke/livery/blob/main/web/a2ui/PUBLISHING.md). `npm run pack:check` checks the files and
+relative runtime imports in the actual tarball in CI. The TypeScript player remains vendored
+with its provenance until rc-players publishes a supported npm package.
+
+### React and Angular
+
+The same session and controller power all three web renderers. Use
+`liveryReactCatalog(session, options)` from `@yschimke/livery-a2ui/react` with React's `A2uiSurface`, or
+`liveryAngularCatalog(session, options)` from `@yschimke/livery-a2ui/angular` with Angular's
+`provideA2Ui({ catalogs: [catalog] })` and `SurfaceComponent`. Install the matching optional peers:
+React 18/19 with `@a2ui/react` 0.15; Angular 21 with `@a2ui/angular` 0.14 (which uses web_core 0.15).
+Angular applications also configure A2UI's `provideMarkdownRenderer()` for the basic components.
+The Angular entry ships partial compilation for the application's Angular linker.
+
+`options.base` extends the selected renderer's catalog. Actions, data-model paths, themes,
+decision ids, retry and height behavior are shared. `fallback` returns a Lit template for Lit,
+a React node for React, or a DOM node/string for Angular. `npm test` runs the same sample catalog
+and all interaction checks once per renderer; `CHROMIUM_PATH` can select a local Chromium binary.
+
+### Persistent browser cache
+
+Web sessions default to IndexedDB for blobs and small named documents. A session with playable cached templates reads
+its catalog immediately and refreshes in the background. A cached manifest without playable
+blobs first retries prefetch, so an interrupted download cannot register an empty component catalog.
+Template rendering does not
+wait for a network response. The existing repository still owns expiry, stale grace, install
+policy, blob eviction and image-cache metadata. Browser storage can be cleared or evicted by
+the browser; this is a cache, not durable application data.
+
+Set `persistentCache: false` in `LiverySession.open` for memory-only sessions (also useful in
+hosts that deny IndexedDB or Web Locks). Persistent caching requires a secure origin
+(HTTPS or localhost) and Web Locks; refreshes sharing a namespace are serialized across sessions and tabs. Cache namespaces include the catalog and trust configuration:
+switching from an unsigned development catalog to signed trust cannot reuse the old manifest.
+The browser suite reloads with all catalog requests blocked and checks that cached templates
+draw, that memory-only sessions cannot use this cache offline, and that a different trust configuration
+cannot inherit the cached unsigned catalog. Serving an application's shell offline remains the
+host application's responsibility.
+
+### Wasm distribution size
+
+`webDist` runs Kotlin's pinned Binaryen optimizer before packaging. On the 0.6.0 baseline this
+reduces raw Wasm from 4,749,595 to 1,454,082 bytes (69.4%). Ktor remains in the module to preserve
+its fetch and redirect contract. `docs/WASM-SIZE.md` records section and dependency measurements;
+`scripts/wasm-size.py` reproduces the breakdown for subsequent builds.
+
+`LIVERY_TEST_PLAYER=ts` or `cmp` selects one player; `LIVERY_RENDERER=lit`, `react` or `angular`
+selects a framework when running `node test/e2e.mjs` directly. `LIVERY_RENDER_OUT` saves screenshots
+and load measurements. `CHROMIUM_PATH` (or `PLAYWRIGHT_CHROMIUM_EXECUTABLE`) selects an installed
+Chromium. CMP retains authored height when it cannot expose a finite root measurement.
+
+Content height is read from the player's normal layout at the current viewport constraints.
+The size query does not run a second measure pass or alter expressions, animations or scroll
+state. Fill-height, weighted-height and scrolling layouts retain their authored-height fallback.
+
+When replacing a cached catalog, refresh keeps the previous manifest active until its required
+replacement templates and assets finish downloading. Failed downloads keep the playable cache;
+the accepted serial watermark is still persisted immediately so rollback protection survives a
+failure or interruption. Kotlin and Swift use the same activation order.
+
+CI uses Binaryen 130.0.0 from the npm lockfile with `-Plivery.wasmOpt=<path-to-wasm-opt>`.
+This keeps the same optimizer version and Kotlin arguments while avoiding the GitHub release
+asset endpoint, which repeatedly returned HTTP 504. Ordinary Gradle builds retain Kotlin's
+native Binaryen download unless an executable is supplied.
+
+The optional A2UI facade delegates shared document preparation and action routing to
+`livery-web-core`. Its canvas player comes from the neutral `@yschimke/livery-web/player`
+package, bundled into the published A2UI tarball. In a checkout, build `web/core`
+before installing/building this package; `npm ci` copies that local package.
+Standalone component previews are documented in [../core/README.md](../core/README.md).

package/dist/angular.d.ts

@@ -0,0 +1,32 @@
+import { type OnDestroy } from '@angular/core';
+import { AngularCatalog, CatalogComponent } from '@a2ui/angular/v0_9';
+import { type LiveryComponentApi, type LiveryCatalogOptions } from './api.js';
+import type { LiverySession } from './livery.js';
+import * as i0 from "@angular/core";
+export { LiverySession, loadLiveryWeb } from './livery.js';
+export declare class LiveryAngularComponent extends CatalogComponent<LiveryComponentApi> implements OnDestroy {
+    private readonly host;
+    private readonly service;
+    private api?;
+    private readonly fallbackBox;
+    private readonly controller;
+    constructor();
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LiveryAngularComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LiveryAngularComponent, "livery-angular-view", never, {}, {}, never, never, true, never>;
+}
+export declare function liveryAngularCatalog(session: LiverySession, options: LiveryCatalogOptions): Promise<{
+    catalog: AngularCatalog;
+    components: {
+        component: import("@angular/core").Type<import("@a2ui/angular").CatalogComponentInstance>;
+        name: string;
+        schema: import("zod").ZodTypeAny;
+        allowedParents?: string[];
+        allowedChildren?: string[];
+        metadata?: import("@a2ui/web_core").A2uiMetadata;
+        tagName: string;
+        spec: import("./livery.js").LiveryComponentSpec;
+        session: LiverySession;
+        options: LiveryCatalogOptions;
+    }[];
+}>;

package/dist/angular.js

@@ -0,0 +1,51 @@
+import { Component, ElementRef, effect, inject } from '@angular/core';
+import { A2uiRendererService, AngularCatalog, CatalogComponent, createComponentImplementation, BasicCatalog } from '@a2ui/angular/v0_9';
+import { ComponentContext } from '@a2ui/web_core/v0_9';
+import { componentApi, preparePlayerOptions } from './api.js';
+import { hostStyle, LiveryController } from './controller.js';
+import * as i0 from "@angular/core";
+export { LiverySession, loadLiveryWeb } from './livery.js';
+export class LiveryAngularComponent extends CatalogComponent {
+    constructor() {
+        super();
+        this.host = inject((ElementRef)).nativeElement;
+        this.service = inject(A2uiRendererService);
+        this.fallbackBox = document.createElement('div');
+        this.controller = new LiveryController(this.host, () => {
+            const reason = this.controller.fallback;
+            this.controller.box.style.display = reason === undefined ? '' : 'none';
+            const content = reason === undefined ? '' : this.api?.options.fallback?.(this.api.spec, reason) ?? '';
+            this.fallbackBox.replaceChildren(content instanceof Node ? content : String(content));
+        }, () => new Promise(requestAnimationFrame));
+        this.host.style.cssText = hostStyle;
+        this.host.attachShadow({ mode: 'open' }).append(this.controller.box, this.fallbackBox);
+        this.controller.connect();
+        effect(() => {
+            const surface = this.service.surfaceGroup.getSurface(this.surfaceId());
+            if (!surface)
+                return;
+            const context = new ComponentContext(surface, this.componentId(), this.dataContextPath());
+            this.api = context.componentModel.catalog.components.get(context.componentModel.type);
+            this.host.dataset.liveryComponent = this.api.name;
+            const props = Object.fromEntries(Object.entries(this.props()).map(([key, binding]) => [key, binding.value()]));
+            this.controller.update(this.api, context, props);
+        });
+    }
+    ngOnDestroy() { this.controller.disconnect(); }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: LiveryAngularComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.5", type: LiveryAngularComponent, isStandalone: true, selector: "livery-angular-view", usesInheritance: true, ngImport: i0, template: '', isInline: true }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: LiveryAngularComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'livery-angular-view', standalone: true, template: '' }]
+        }], ctorParameters: () => [] });
+export async function liveryAngularCatalog(session, options) {
+    options = await preparePlayerOptions(options);
+    const components = (await session.components()).map((spec) => {
+        const api = componentApi(session, spec, options);
+        return { ...api, ...createComponentImplementation(api, LiveryAngularComponent) };
+    });
+    const base = options.base ?? new BasicCatalog();
+    const catalog = new AngularCatalog(options.catalogId, '0.9', [...base.components.values(), ...components], [...base.functions.values()], base.themeSchema);
+    return { catalog, components };
+}

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+import type { LiveryPlayerFactory } from './player.js';
+import { type Catalog } from '@a2ui/web_core/v0_9';
+import { z } from 'zod';
+import type { LiveryComponentSpec, LiverySession } from './livery.js';
+export interface LiveryCatalogOptions {
+    /** In-page player; optional CMP is prepared before any framework registers its catalog. */
+    player?: 'ts' | 'cmp' | LiveryPlayerFactory;
+    /** The catalog id the client advertises: basic components plus one per Livery contract. */
+    catalogId: string;
+    /** The catalog to extend; A2UI's basic catalog by default. */
+    base?: Catalog<any, any>;
+    /** An action of a kind the page handles (`navigate`, `dismiss`, `app:…`) that the agent didn't wire. */
+    onAppAction?: (kind: string, action: string, args: Record<string, string>, component: string) => void;
+    /**
+     * Something the agent should hear about: data that doesn't bind, no playable template, a `set` on
+     * an input it didn't bind to a path. The page tells its agent (A2UI's `error` message).
+     */
+    onProblem?: (component: string, message: string) => void;
+    /** What draws when there is no template (the agent is told through [onProblem]); nothing by default. */
+    fallback?: (spec: LiveryComponentSpec, reason: string) => unknown;
+}
+/** One Livery component's A2UI API: its name, tag, element and props schema, and the session it draws with. */
+export interface LiveryComponentApi {
+    name: string;
+    tagName: string;
+    schema: z.ZodTypeAny;
+    spec: LiveryComponentSpec;
+    session: LiverySession;
+    options: LiveryCatalogOptions;
+}
+/** The props schema, from the same projection as Kotlin's (`livery-a2ui`): A2UI's own dynamic types. */
+export declare function schemaOf(spec: LiveryComponentSpec): z.ZodTypeAny;
+export declare function componentApi(session: LiverySession, spec: LiveryComponentSpec, options: LiveryCatalogOptions): LiveryComponentApi;
+export declare function kebab(s: string): string;
+export declare function preparePlayerOptions(options: LiveryCatalogOptions): Promise<LiveryCatalogOptions>;

package/dist/api.js

@@ -0,0 +1,35 @@
+import { prepareCmpPlayer } from './cmp-player.js';
+import { ActionSchema, DynamicBooleanSchema, DynamicNumberSchema, DynamicStringSchema, DynamicValueSchema } from '@a2ui/web_core/v0_9';
+import { z } from 'zod';
+/** The props schema, from the same projection as Kotlin's (`livery-a2ui`): A2UI's own dynamic types. */
+export function schemaOf(spec) {
+    const shape = {};
+    for (const p of spec.properties) {
+        const s = propertySchema(p);
+        shape[p.key] = p.required ? s : s.optional();
+    }
+    return z.object(shape).describe(spec.description);
+}
+function propertySchema(p) {
+    switch (p.kind) {
+        case 'DynamicString': return DynamicStringSchema;
+        case 'DynamicNumber': return DynamicNumberSchema;
+        case 'DynamicBoolean': return DynamicBooleanSchema;
+        case 'DynamicValue': return DynamicValueSchema;
+        case 'String': return z.string();
+        case 'Action': return ActionSchema;
+        case 'Actions': return z.object(Object.fromEntries((p.properties ?? []).map((a) => [a, ActionSchema.optional()]))).strict();
+        default: return z.any();
+    }
+}
+export function componentApi(session, spec, options) {
+    if (options.player === 'cmp')
+        throw new Error("Use an async catalog factory with player: 'cmp', or pass await prepareCmpPlayer() to liveryComponent");
+    return { name: spec.name, tagName: `livery-${kebab(spec.name)}`, schema: schemaOf(spec), session, spec, options };
+}
+export function kebab(s) {
+    return s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/[^A-Za-z0-9]+/g, '-').toLowerCase();
+}
+export async function preparePlayerOptions(options) {
+    return options.player === 'cmp' ? { ...options, player: await prepareCmpPlayer() } : options;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,18 @@
+import type { Catalog } from '@a2ui/web_core/v0_9';
+import type { LiveryComponentSpec, LiverySession } from './livery.js';
+import { type LiveryComponentApi as SharedComponentApi, type LiveryCatalogOptions } from './api.js';
+export type { LiveryCatalogOptions } from './api.js';
+/** Lit retains its custom-element constructor alongside the renderer-neutral API. */
+export interface LiveryComponentApi extends SharedComponentApi {
+    element: CustomElementConstructor;
+}
+export declare function liveryCatalog(session: LiverySession, options: LiveryCatalogOptions): Promise<{
+    catalog: Catalog<any, any>;
+    components: LiveryComponentApi[];
+}>;
+/**
+ * The A2UI component for one contract ([spec]). Its element is defined once per tag, and takes its
+ * session, spec and options from the catalog entry it was rendered from, never from the first
+ * catalog that defined the tag: two catalogs (or a session opened again) each draw with their own.
+ */
+export declare function liveryComponent(session: LiverySession, spec: LiveryComponentSpec, options: LiveryCatalogOptions): LiveryComponentApi;

package/dist/catalog.js

@@ -0,0 +1,55 @@
+import { A2uiLitElement, basicCatalog } from '@a2ui/lit/v0_9';
+import { css, html, nothing } from 'lit';
+import { componentApi, preparePlayerOptions } from './api.js';
+import { LiveryController } from './controller.js';
+export async function liveryCatalog(session, options) {
+    options = await preparePlayerOptions(options);
+    const base = options.base ?? basicCatalog;
+    const components = (await session.components()).map((spec) => liveryComponent(session, spec, options));
+    const catalog = base.derive({ catalogId: options.catalogId, components: [...base.components.keys(), ...components] });
+    return { catalog, components };
+}
+/**
+ * The A2UI component for one contract ([spec]). Its element is defined once per tag, and takes its
+ * session, spec and options from the catalog entry it was rendered from, never from the first
+ * catalog that defined the tag: two catalogs (or a session opened again) each draw with their own.
+ */
+export function liveryComponent(session, spec, options) {
+    const api = componentApi(session, spec, options);
+    const { tagName } = api;
+    let element = customElements.get(tagName);
+    if (!element) {
+        // One constructor per tag (the registry allows no other), all of them the same element.
+        element = class extends LiveryElement {
+        };
+        customElements.define(tagName, element);
+    }
+    return { ...api, element };
+}
+class LiveryElement extends A2uiLitElement {
+    constructor() {
+        super(...arguments);
+        this.liveryController = new LiveryController(this, () => this.requestUpdate(), () => this.updateComplete);
+    }
+    static { this.styles = css `:host { display:block; width:100%; height:var(--livery-a2ui-height,var(--livery-template-height,200px)); }`; }
+    get liveryApi() {
+        const model = this.context?.componentModel;
+        return model?.catalog?.components.get(model.type);
+    }
+    get liveryStats() { return this.liveryController.liveryStats; }
+    get liveryTheme() { return this.liveryController.liveryTheme; }
+    liveryHostAction(action) { return this.liveryController.liveryHostAction(action); }
+    connectedCallback() { super.connectedCallback(); this.liveryController.connect(); }
+    disconnectedCallback() { this.liveryController.disconnect(); super.disconnectedCallback(); }
+    updated(changed) {
+        super.updated(changed);
+        if (this.liveryApi)
+            this.dataset.liveryComponent = this.liveryApi.name;
+        if (this.context)
+            this.liveryController.update(this.liveryApi, this.context, this.controller.props ?? {});
+    }
+    render() {
+        const reason = this.liveryController.fallback;
+        return reason === undefined ? html `${this.liveryController.box}` : html `${this.liveryApi?.options.fallback?.(this.liveryApi.spec, reason) ?? nothing}`;
+    }
+}

package/dist/cmp-player.d.ts

@@ -0,0 +1,3 @@
+import type { LiveryPlayerFactory } from './player.js';
+/** Preload the optional Wasm/Skiko runtime and bundled font before rendering any components. */
+export declare function prepareCmpPlayer(): Promise<LiveryPlayerFactory>;

package/dist/cmp-player.js

@@ -0,0 +1,125 @@
+import { RcCanvasPlayer } from './player.js';
+let prepared;
+let activeViewports = 0;
+// Each viewport owns a Skia/WebGL context. Leave room for other canvas users on a chat page.
+const MAX_VIEWPORTS = 8;
+/** Preload the optional Wasm/Skiko runtime and bundled font before rendering any components. */
+export function prepareCmpPlayer() {
+    return prepared ??= prepare().catch((e) => { prepared = undefined; throw e; });
+}
+async function prepare() {
+    const base = new URL('./livery-web-compose/', import.meta.url);
+    const url = new URL('livery-livery-web-compose.mjs', base).href;
+    const font = async (name) => {
+        const r = await fetch(new URL(`fonts/${name}`, base));
+        if (!r.ok)
+            throw new Error(`CMP font ${name}: HTTP ${r.status}`);
+        return base64(new Uint8Array(await r.arrayBuffer()));
+    };
+    const [lib, roboto, symbols] = await Promise.all([
+        import(/* @vite-ignore */ url),
+        font('RobotoFlex.ttf'),
+        font('NotoSansSymbols2-Regular.ttf'),
+    ]);
+    // Importing Skiko starts its fetch but does not await it. Finish it during preparation, too.
+    const skikoUrl = new URL('skiko.mjs', base).href;
+    await (await import(/* @vite-ignore */ skikoUrl)).awaitSkiko;
+    // Compose's Locale parser rejects some OS tags (for example en-US@posix). Leave valid
+    // browser settings untouched; repair only the invalid entries before composition starts.
+    const languages = navigator.languages.map((tag) => tag.replaceAll('_', '-').split('@')[0]);
+    const usable = languages.filter((tag) => { try {
+        new Intl.Locale(tag);
+        return true;
+    }
+    catch {
+        return false;
+    } });
+    if (usable.join('\0') !== navigator.languages.join('\0')) {
+        const safe = usable.length ? usable : ['en-US'];
+        Object.defineProperty(navigator, 'languages', { configurable: true, get: () => safe });
+        Object.defineProperty(navigator, 'language', { configurable: true, get: () => safe[0] });
+    }
+    lib.liveryCmpPrepare(roboto, symbols);
+    return (box, onAction) => {
+        if (activeViewports >= MAX_VIEWPORTS)
+            return new RcCanvasPlayer(box, onAction);
+        activeViewports++;
+        return new CmpPlayer(lib, box, onAction, () => activeViewports--);
+    };
+}
+class CmpPlayer {
+    constructor(lib, box, onAction, release) {
+        this.lib = lib;
+        this.box = box;
+        this.onAction = onAction;
+        this.release = release;
+        this.latest = 0;
+        this.disposed = false;
+        this.size = '';
+        this.queue = Promise.resolve();
+        this.stats = { loads: 0, sets: 0 };
+    }
+    show(key, document, values, width, height, density) {
+        const mine = ++this.latest;
+        const run = this.queue.then(async () => {
+            if (this.disposed || mine !== this.latest)
+                return false;
+            this.resize(width, height, density);
+            // Mount only after the element's height rule has sized its container.
+            this.id ??= this.lib.liveryCmpMount(this.box, (name, type, value) => {
+                if (!this.disposed)
+                    this.onAction({ name, valueType: type, value: type === 'int' || type === 'float' ? Number(value) : value });
+            });
+            const frame = this.lib.liveryCmpShow(this.id, key, key === this.key ? '' : base64(document), JSON.stringify(values), density);
+            this.key = key;
+            const drawn = await frame;
+            if (this.disposed)
+                return false;
+            Object.assign(this.stats, JSON.parse(this.lib.liveryCmpStats(this.id)));
+            return drawn && mine === this.latest;
+        });
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    resize(width, height, density) {
+        if (this.disposed)
+            return;
+        if (width > 0 && height > 0) {
+            this.box.style.width = `${width}px`;
+            this.box.style.height = `${height}px`;
+            const size = `${width}/${height}/${density}`;
+            if (size !== this.size) {
+                this.size = size;
+                // Compose 1.12's viewport observes window resize, not its container's ResizeObserver.
+                window.dispatchEvent(new Event('resize'));
+            }
+        }
+        if (this.id !== undefined)
+            this.lib.liveryCmpResize(this.id, density);
+    }
+    forget() {
+        this.latest++;
+        this.key = undefined;
+        if (this.id !== undefined)
+            this.lib.liveryCmpForget(this.id);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.latest++;
+        try {
+            if (this.id !== undefined)
+                this.lib.liveryCmpDispose(this.id);
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+function base64(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i += 8192)
+        s += String.fromCharCode(...bytes.subarray(i, i + 8192));
+    return btoa(s);
+}

package/dist/controller.d.ts

@@ -0,0 +1,61 @@
+import type { ComponentContext } from '@a2ui/web_core/v0_9';
+import type { LiveryComponentApi } from './api.js';
+import { type NamedAction } from './player.js';
+export declare const hostStyle = "display:block;width:100%;height:var(--livery-a2ui-height,var(--livery-template-height,200px))";
+export declare class LiveryController {
+    readonly element: HTMLElement;
+    private readonly changed;
+    private readonly settled;
+    private livery?;
+    private context?;
+    private resolved;
+    private connected;
+    constructor(element: HTMLElement, changed: () => void, settled: () => Promise<unknown>);
+    connect(): void;
+    update(api: LiveryComponentApi | undefined, context: ComponentContext, resolved: Record<string, unknown>): void;
+    private invalidate;
+    disconnect(): void;
+    private player?;
+    /** The player's canvas lives here across framework renders. */
+    readonly box: HTMLDivElement;
+    private render_?;
+    private request;
+    fallback?: string;
+    private sequence;
+    /** The agent's design failed to play: render the automatic choice instead, until the props change. */
+    private automatic;
+    private lastTheme?;
+    private automaticFor?;
+    /** A fetch for this element's images failed: if it renders waiting again, it can't draw. */
+    private imagesFailed;
+    private shownPresentation?;
+    private resize?;
+    private widthDp;
+    /** Documents this element's player loaded and values it set: a data change sets values, never reloads. */
+    get liveryStats(): {
+        loads: number;
+        sets: number;
+    } | undefined;
+    /** The theme roles of the last render, as `#AARRGGBB`. @internal For tests. */
+    get liveryTheme(): Record<string, string> | undefined;
+    /** The props Livery renders from: inputs and lists as A2UI resolved them, the rest as the agent wrote them. */
+    private props;
+    /** Whether the page sets the component's height (`--livery-a2ui-height`), so selection can use it. */
+    private pageHeight;
+    /** `a2ui:<surfaceId>/<componentId>`: on every event of this component, so analytics can tell agent-placed templates from the app's own. */
+    private decisionId;
+    sync(): Promise<void>;
+    /**
+     * This render can't draw. The agent hears why. A chosen design falls back to the automatic
+     * choice, never to nothing; the agent's own document is never replaced (PROTOCOL.md §5.3), so
+     * it, and an automatic choice that can't draw either, show the page's fallback.
+     */
+    private cannotPlay;
+    /**
+     * A host named action, exactly as the player's callback delivers one. @internal For tests that
+     * send a document's action with values its buttons wouldn't (an undeclared argument).
+     */
+    liveryHostAction(a: NamedAction): Promise<void>;
+    private onAction;
+    private dispatch;
+}