@yschimke/livery-a2ui 0.0.0-stage → 0.11.0

package/dist/livery.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Livery's web session: Kotlin's own pipeline (`livery-web`, compiled to Wasm), behind a typed
+ * API. Nothing here selects, trusts or binds: it passes JSON across and back.
+ */
+export interface LiveryConfig {
+    /** The catalog's base URL; `manifest.json` is fetched from beside it. */
+    catalog: string;
+    /** App-configured HTTPS POST endpoint for contract decisions (§8.3); never supplied by the agent. */
+    decisionEndpoint?: string;
+    decisionContext?: {
+        nowEpochMs?: number;
+        platform: string;
+        locale: string;
+        appVersion: number;
+        bucketingId: string;
+        segments?: string[];
+    };
+    /** Trusted Ed25519 keys, the public key as base64 of its raw 32 bytes. */
+    keys?: {
+        keyId: string;
+        publicKey: string;
+        contracts?: string[];
+    }[];
+    /** Accept an unsigned catalog: development only. */
+    unsigned?: boolean;
+    /** Persist catalog state and blobs in IndexedDB (default true); false uses session memory. */
+    persistentCache?: boolean;
+    /** Documents an agent sends with a message (`template.inline`): refused unless set. */
+    agentBytes?: {
+        contracts: string[];
+        maxBytes?: number;
+        allowedKinds?: string[];
+    };
+    /** Risky features a signed inline document may use (`shaders`, …). */
+    signedFeatures?: string[];
+    /** Hosts images are fetched from directly. */
+    imageHosts?: string[];
+    /** URL prefixes an `open-url` action may open. */
+    urlAllowlist?: string[];
+    /** Action kinds the page handles itself when the agent didn't wire them. */
+    appKinds?: string[];
+}
+export interface LiveryPropertySpec {
+    key: string;
+    kind: 'DynamicString' | 'DynamicNumber' | 'DynamicBoolean' | 'DynamicValue' | 'String' | 'Action' | 'Actions' | 'Any';
+    required: boolean;
+    /** For `Actions`: the contract's action names. */
+    properties?: string[];
+}
+export interface LiveryComponentSpec {
+    name: string;
+    contract: string;
+    description: string;
+    /** The component's JSON schema, as A2UI advertises it. */
+    schema: Record<string, unknown>;
+    properties: LiveryPropertySpec[];
+    /** Inputs the contract's `set` actions write back. */
+    setInputs: string[];
+}
+export interface LiverySpace {
+    widthDp?: number;
+    heightDp?: number;
+    density?: number;
+    colorScheme?: string;
+    /** Theme roles (`primary`, `surface`, `onSurface`, …) as `#RRGGBB` or `#AARRGGBB`. */
+    theme?: Record<string, string>;
+    /** What the render's events carry as `decisionId`: `a2ui:<surfaceId>/<componentId>` for an A2UI component. */
+    decisionId?: string;
+}
+export type Rendered = {
+    ok: true;
+    render: number;
+    /** The document to play; load it only when [documentKey] changes, otherwise set [values]. */
+    document: Uint8Array;
+    documentKey: string;
+    /** Impression identity; a new decision can reuse the same documentKey. */
+    presentationKey: string;
+    /** Its named values: strings, numbers (booleans as 1 or 0), colours as `#AARRGGBB`. */
+    values: Record<string, string | number>;
+    design: string;
+    sha256: string;
+    /** The template's own height in dp: what to draw it at when the page gives the component none. */
+    heightDp?: number;
+    pending?: boolean;
+    /** An authored target minimum, retained when sizing to the measured root. */
+    minHeightDp?: number;
+} | {
+    ok: false;
+    reason: string;
+    waiting?: boolean;
+    pending?: boolean;
+};
+export type Routed = {
+    route: 'agent';
+    action: Record<string, unknown>;
+    shadowed: string[];
+} | {
+    route: 'set';
+    input: string;
+    value: unknown;
+    agent?: {
+        action: Record<string, unknown>;
+        shadowed: string[];
+    };
+} | {
+    route: 'app';
+    kind: string;
+    action: string;
+    args: Record<string, string>;
+} | {
+    route: 'dropped';
+    reason: string;
+};
+/** The `livery-web` module's exports (`livery-livery-web.mjs`). */
+export interface LiveryWebModule {
+    liveryOpen(config: string): Promise<unknown>;
+    liveryClose(session: number): void;
+    liveryRefresh(session: number): Promise<unknown>;
+    liveryComponents(session: number): Promise<unknown>;
+    liveryCatalogSchema(session: number, catalogId: string): Promise<unknown>;
+    liveryRender(session: number, name: string, props: string, space: string): Promise<unknown>;
+    liveryShown(session: number, render: number): void;
+    liveryRelease(session: number, render: number): void;
+    liveryAction(session: number, render: number, name: string, valueType: string, value: string | null): Promise<unknown>;
+    liveryEvents(session: number): string;
+    liveryFetchPending(session: number): Promise<unknown>;
+    liveryFetchImages(session: number): Promise<unknown>;
+}
+/** Loads the Wasm module shipped in this package (`dist/livery-web/`). */
+export declare function loadLiveryWeb(): Promise<LiveryWebModule>;
+export declare class LiverySession {
+    private readonly lib;
+    readonly id: number;
+    private constructor();
+    /** Opens [config]'s catalog (fetching it once) with [lib], or the module this package ships. */
+    static open(config: LiveryConfig, lib?: LiveryWebModule): Promise<LiverySession>;
+    /** Close after removing the session's components. Cancels pending work and clears listeners. */
+    close(): void;
+    refresh(): Promise<string>;
+    /** The components to register: one per contract the catalog can play here now. */
+    components(): Promise<LiveryComponentSpec[]>;
+    /** The A2UI catalog JSON of those components, to prompt an agent with. */
+    catalogSchema(catalogId: string): Promise<Record<string, unknown>>;
+    render(name: string, props: Record<string, unknown>, space?: LiverySpace): Promise<Rendered>;
+    private pendingFetch;
+    /** Run after rendering an answer marked pending, then render again. */
+    fetchPending(): Promise<void>;
+    private fetching;
+    private readonly waiting;
+    /**
+     * Fetches the images renders were waiting for (`waiting: true`), off the render path, then calls
+     * every [whenImagesArrive] callback, whichever render asked: the session's misses are one queue,
+     * so one fetch can bring another component's image. Fetches run one after another. `arrived` is
+     * false when one of them could not be fetched: render again, and a render still waiting has
+     * failed.
+     */
+    fetchImages(): Promise<void>;
+    /** [callback] runs once, when the next fetch ends: render again then. */
+    whenImagesArrive(callback: (arrived: boolean) => void): void;
+    shown(render: number): void;
+    release(render: number): void;
+    action(render: number, name: string, valueType: string, value: unknown): Promise<Routed>;
+    /** Livery's events since the last call: impressions, actions, fallbacks, errors. */
+    events(): Record<string, unknown>[];
+}

package/dist/livery.js

@@ -0,0 +1,87 @@
+/** Loads the Wasm module shipped in this package (`dist/livery-web/`). */
+export async function loadLiveryWeb() {
+    // The path is computed so a bundler leaves it alone: the module fetches its .wasm beside itself.
+    const url = new URL('./livery-web/livery-livery-web.mjs', import.meta.url).href;
+    return (await import(/* @vite-ignore */ url));
+}
+export class LiverySession {
+    constructor(lib, id) {
+        this.lib = lib;
+        this.id = id;
+        this.pendingFetch = Promise.resolve();
+        this.fetching = Promise.resolve();
+        this.waiting = new Set();
+    }
+    /** Opens [config]'s catalog (fetching it once) with [lib], or the module this package ships. */
+    static async open(config, lib) {
+        const m = lib ?? (await loadLiveryWeb());
+        return new LiverySession(m, Number(await m.liveryOpen(JSON.stringify(config))));
+    }
+    /** Close after removing the session's components. Cancels pending work and clears listeners. */
+    close() { this.waiting.clear(); this.lib.liveryClose(this.id); }
+    async refresh() {
+        return String(await this.lib.liveryRefresh(this.id));
+    }
+    /** The components to register: one per contract the catalog can play here now. */
+    async components() {
+        return JSON.parse(String(await this.lib.liveryComponents(this.id)));
+    }
+    /** The A2UI catalog JSON of those components, to prompt an agent with. */
+    async catalogSchema(catalogId) {
+        return JSON.parse(String(await this.lib.liveryCatalogSchema(this.id, catalogId)));
+    }
+    async render(name, props, space = {}) {
+        const r = JSON.parse(String(await this.lib.liveryRender(this.id, name, JSON.stringify(props), JSON.stringify(space))));
+        return r.ok ? { ...r, document: base64ToBytes(r.document) } : r;
+    }
+    /** Run after rendering an answer marked pending, then render again. */
+    fetchPending() {
+        this.pendingFetch = this.pendingFetch.then(async () => { await this.lib.liveryFetchPending(this.id); }).catch(() => { });
+        return this.pendingFetch;
+    }
+    /**
+     * Fetches the images renders were waiting for (`waiting: true`), off the render path, then calls
+     * every [whenImagesArrive] callback, whichever render asked: the session's misses are one queue,
+     * so one fetch can bring another component's image. Fetches run one after another. `arrived` is
+     * false when one of them could not be fetched: render again, and a render still waiting has
+     * failed.
+     */
+    fetchImages() {
+        this.fetching = this.fetching.then(async () => {
+            let arrived = false;
+            try {
+                arrived = String(await this.lib.liveryFetchImages(this.id)) === 'true';
+            }
+            catch { /* as a miss */ }
+            const callbacks = [...this.waiting];
+            this.waiting.clear();
+            callbacks.forEach((c) => c(arrived));
+        }).catch(() => { });
+        return this.fetching;
+    }
+    /** [callback] runs once, when the next fetch ends: render again then. */
+    whenImagesArrive(callback) {
+        this.waiting.add(callback);
+    }
+    shown(render) {
+        this.lib.liveryShown(this.id, render);
+    }
+    release(render) {
+        this.lib.liveryRelease(this.id, render);
+    }
+    async action(render, name, valueType, value) {
+        const text = value === null || value === undefined ? null : String(value);
+        return JSON.parse(String(await this.lib.liveryAction(this.id, render, name, valueType, text)));
+    }
+    /** Livery's events since the last call: impressions, actions, fallbacks, errors. */
+    events() {
+        return JSON.parse(this.lib.liveryEvents(this.id));
+    }
+}
+function base64ToBytes(b64) {
+    const s = atob(b64);
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}

package/dist/player.d.ts

@@ -0,0 +1,2 @@
+export { RcCanvasPlayer } from '@yschimke/livery-web/player';
+export type { NamedAction, LiveryPlayer, LiveryPlayerFactory, HostValue } from '@yschimke/livery-web/player';

package/dist/player.js

@@ -0,0 +1,2 @@
+// The neutral player is bundled into the published A2UI package.
+export { RcCanvasPlayer } from '@yschimke/livery-web/player';

package/dist/react.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import { type LiveryCatalogOptions } from './api.js';
+import type { LiverySession } from './livery.js';
+export { LiverySession, loadLiveryWeb } from './livery.js';
+export declare function liveryReactCatalog(session: LiverySession, options: LiveryCatalogOptions): Promise<{
+    catalog: import("@a2ui/web_core").Catalog<any, any>;
+    components: {
+        name: string;
+        tagName: string;
+        schema: import("zod").ZodTypeAny;
+        spec: import("./livery.js").LiveryComponentSpec;
+        session: LiverySession;
+        options: LiveryCatalogOptions;
+        render: import("react").FC<{
+            context: import("@a2ui/web_core").ComponentContext;
+            buildChild: (id: string, basePath?: string) => ReactNode;
+            metadata?: import("@a2ui/web_core").A2uiMetadata;
+        }>;
+        view?: import("react").FC<import("@a2ui/react").NodeViewProps>;
+        allowedParents?: string[];
+        allowedChildren?: string[];
+        metadata?: import("@a2ui/web_core").A2uiMetadata;
+    }[];
+}>;

package/dist/react.js

@@ -0,0 +1,36 @@
+import { createElement, useLayoutEffect, useRef, useState } from 'react';
+import { createComponentImplementation } from '@a2ui/react/v0_9';
+import { basicCatalog } from '@a2ui/web_core/v0_9/basic_catalog';
+import { componentApi, preparePlayerOptions } from './api.js';
+import { hostStyle, LiveryController } from './controller.js';
+export { LiverySession, loadLiveryWeb } from './livery.js';
+export async function liveryReactCatalog(session, options) {
+    options = await preparePlayerOptions(options);
+    const components = (await session.components()).map((spec) => {
+        const api = componentApi(session, spec, options);
+        function View({ context, props }) {
+            const host = useRef(null);
+            const controller = useRef(null);
+            const [, update] = useState(0);
+            useLayoutEffect(() => {
+                const el = host.current;
+                el.style.cssText = hostStyle;
+                const c = new LiveryController(el, () => update((n) => n + 1), () => new Promise(requestAnimationFrame));
+                controller.current = c;
+                (el.shadowRoot ?? el.attachShadow({ mode: 'open' })).append(c.box);
+                c.connect();
+                c.update(api, context, props);
+                return () => { c.disconnect(); c.box.remove(); controller.current = null; };
+            }, []);
+            useLayoutEffect(() => { controller.current?.update(api, context, props); });
+            const reason = controller.current?.fallback;
+            // The player owns its shadow tree; React owns the optional fallback beside it.
+            if (controller.current)
+                controller.current.box.style.display = reason === undefined ? '' : 'none';
+            return createElement('div', null, createElement('div', { ref: host, 'data-livery-component': spec.name }), reason === undefined ? null : options.fallback?.(spec, reason));
+        }
+        return { ...createComponentImplementation(api, View), ...api };
+    });
+    const base = options.base ?? basicCatalog;
+    return { catalog: base.derive({ catalogId: options.catalogId, components: [...base.components.keys(), ...components] }), components };
+}

package/node_modules/@js-joda/core/CHANGELOG.md

@@ -0,0 +1,363 @@
+Changelog
+=========
+
+### next (upcoming)
+
+### 3.2.0
+
+* add typescript definitions for OffsetDateTime and OffsetTime #448 by jonfreedman
+ 
+### 3.1.0
+
+* Fix bitwise or #439 by @pithu
+* Tests for TS declaration run with ts-node #423 by InExtremaRes
+* dependabot Bump elliptic from 6.5.2 to 6.5.3
+* dependabot Bump lodash from 4.17.15 to 4.17.19
+* dependabot Bump npm-registry-fetch from 4.0.2 to 4.0.5
+
+### 3.0.0
+
+This is a major release because of these following minor/ breaking cleanups:
+
+* Renamed method getDisplayName to displayName for
+   * WeekFields 
+   * DayOfWeek
+   * Month
+   * IsoFields
+* Removed duplicate function YearMonth.with(number, number)
+   * YearMonth.with(year, month), use YearMonth.of() instead
+   * YearMonth.withYearMonth(year, month), use YearMonth.of() instead
+
+All updates:
+
+ * Implement OffsetTime and OffsetDateTim #416 by exoego
+ * TS types reorganized and documentation added #418 by InExtremaRes
+ * Fix isBrowserTest check #419 by pithu
+ * Duration#(minus|plus) should accept TemporalUnit, not just ChronoUnit #417 by exoego
+ * TS types refactor part 1 #415 by InExtremaRes
+ * Remove YearMonth#with that takes (number, number) #412 by InExtremaRes
+ * Fixes and cleanups to TemporalFields and TemporalUnits #408 by InExtremaRes
+ * Switch to travis-ci.com #409 by pithu
+ * Error base name changed to "JsJodaException" and exceptions exposed in TS #407 by InExtremaRes
+ * Some fixes to TS declarations #404 by InExtremaRes
+ * remove android saucelabs test setup #403 by pithu
+ * Fix TS declarations of some TemporalAdjuster implementations (like DayOfWeak) #402 by InExtremaRes
+ * Fixed types of DateTimeFormatterBuilder.prototype.toFormatter to allow zero arguments  #388 by InExtremaRes
+ * Add missing types for Clock.offset() #387 by InExtremaRes  
+ * Added missing nanoAdjustment to Duration.ofSeconds static method #383 by jseter
+ * changed bitwise or to logical or #379 by bowersj 
+ * Add Typescript for IsoChronology.INSTANCE #373 by cranberyxl 
+ * Remove `withTemporalAdjuster` and others non-public methods from TS declaration #363 by InExtremaRes
+
+### 2.0.0
+
+This is a major release because some 'internal' methods were hidden from the typescript definitions
+and were renamed in the javascript code. 
+Resolve those conflicts by using the 'public shorthand' methods, like instead of using `with*()` use `with(...)`. 
+
+ * Improve of the TS declarations #353 from InExtremaRes
+ * Add missing methods to `Temporal` interface #361 from thrucker
+ * LocalDateTime.of requires at least 3 arguments #356
+ 
+### 1.12.0
+
+ * Cleanup documentation and configuration
+ * Upgrade dependencies
+ * Add ISO formatters definitions #358 akonior/iso-formetters
+ * Improve TS declarations with no breaking change #357 InExtremaRes/ts-declarations
+ * Fixes to docu and LocalDateTime.of() according to the typescript changes #359
+ 
+### 1.11.0
+ 
+ * Added ts defs for new methods in DayOfWeek and Month #301
+ * add method params for #appendValue and #appendValueReduced #288 
+ * add type definition for ChronoUnit.NANOS #296
+ * Add ZoneRulesProvider TypeScript definition #317 
+ * Add type definition for Instant.atZone #313 
+
+### 1.10.1
+
+ * implement methods on DayOfWeek and Month #300
+ * Adding private constructors and abstract modifiers to TypeScript definitions #298
+
+### 1.9.3
+
+ * fix typescript definitions: add `ZoneId#id()` #265
+ * fix typescript definitions: Fix DateTimeFormatter.withLocale() #277
+ * Remove unreachable code #278
+ * add package-lock for dev dependencies
+
+### 1.9.2
+
+#### public API
+
+ * implement atZone in Instant
+ * Add DateTimeParseException to typings file
+
+### 1.9.1
+
+#### dependency updates
+
+ * revert babel to previous version
+
+### 1.9.0
+
+#### public API
+
+ * add OffsetClock and add withZone and equals to other Clock impls
+
+#### bugfixes
+
+ * fix error when parsing dates from string with e.g. WeekOfWeekbasedYear fields
+ * fix call to `substring` in generating error message when parsing  
+
+#### dependency updates
+
+### 1.8.2 
+
+#### public API
+
+ * add ESM module to pkg.module build with rollup
+
+#### dev setup
+
+ * Migrate from webpack to rollup
+
+#### etc
+
+ * Remove usage of module.exports
+ 
+#### dependency updates
+ 
+### 1.7.0 1.7.1 1.8.0 1.8.1
+
+ * issues with build artifacts, dont use it.
+ 
+### 1.6.3
+
+#### public API
+
+ * improve typescript definition (see PR #196)
+ 
+#### dependency updates
+
+### etc
+
+ * Remove usage of call on constructors
+
+### 1.6.2
+
+#### public API
+
+ * improve typescript definition (see PR #188)
+
+#### internal API
+
+ * add `DateTimeBuilder` to internal API
+
+#### dependency updates
+
+### 1.6.1
+
+#### dependency updates
+
+#### bugs
+
+ * fix issue #166, bug from upstream project, parse zoned date time during overlap
+
+### 1.6.0
+
+#### public API
+
+ * update API: export all public classes/interfaces
+ * add `IsoChronology#date(temporal)` function
+ * add export of "internal" APIs needed e.g. for plugins, these should *not* be used by users of the `js-joda` library.
+   Since we do not consider these a public APIs, they may change without warning!
+   These internal APIs are exported as the `_` object
+
+### 1.5.5
+
+#### bugs
+
+ * fix Period.ofDays() if called with none number string values
+ 
+#### public API
+
+ * improve typescript definition
+
+### 1.5.4
+
+#### public API
+
+ * fail if temporals ar created with float values 
+ * fix typescript definition and esdoc 
+
+#### dependency updates
+
+### 1.5.2
+
+#### public API
+
+ * fix LocalDate.now in typescript definition and esdoc 
+ * fix LocalTime static properties in typescript definition
+
+### 1.5.1
+
+#### public API
+
+ * Add `use` function to typescript definition
+ * Add `convert` function to typescript definition
+
+### 1.5.0
+
+#### public API
+
+* Add toJSON methods where missing and useful
+* Remove protected class DateTimeBuilder from esdoc and typescript definition
+
+#### lint
+
+* add linter rules `no-var`, `prefer-const`
+
+#### dependency updates
+
+### 1.4.0
+
+#### public API
+
+ * Remove private constructors, functions and classes from  typescript definition (see #134)
+
+### 1.3.1
+
+#### public API
+
+ * Add `DateTimeFormatter.withResolverStyle` function
+
+#### etc
+ 
+ * Fix DateTimeFormatterBuilder.constructor esdoc/ typescript definition
+ * Fix esdoc/ typescript definition for ZoneId
+ * Remove private functions, classses and constructors from esdoc
+ * unify the format pattern esdoc in `DateTimeFormatter.ofPattern` 
+   and `DateTimeFormatterBuilder.appendPattern`, and add `u` Symbol to documentation
+ 
+### 1.3.0
+
+#### public API
+
+ * export zone/ZoneOffsetTransition
+
+### 1.2.0
+
+#### iana tzdb
+
+ * Complete parsing of ZoneRegions
+
+#### etc
+
+ * Fix bower.json
+ * Fix LocalTime.parse esdoc/ typescript definition
+
+#### dependency updates
+
+### 1.1.17
+
+#### Bugfixes
+
+ * Improve LocalDateTime.toInstant error handling
+ * Improve validation of LocalDate parameter values when passed as Strings
+ 
+#### iana tzdb
+
+ * First quick approach for parsing ZoneRegions
+ 
+### 1.1.14
+
+#### Add more classes to public export
+
+ * add all error classes
+ * add zone/ZoneRules
+ 
+#### code cleanup
+
+ * fix lint issues
+ * fix ESDoc tags
+ * Replace var by let/ const declaration
+
+#### dependency updates
+
+### 1.1.13
+
+#### Add ZoneRulesProvider stub
+
+Add the ZoneRulesProvider. This should be the last step to enable js-joda for an external js-joda-timezone plugin.
+
+#### Provide a way to extend js-joda
+
+[Implement a use function](https://github.com/js-joda/js-joda/pull/100#issuecomment-252425196)
+
+### Bugfixes
+
+ * Fix SystemDefaultZoneRules transition (fix a bug in convert and LocalDate.startOfDay)
+
+### 1.1.12 
+
+#### Implement daylight saving transition functionality
+
+Complete / implement methods/ interfaces
+- LocalDate.atStartOfDayWithZone
+- ZonedDateTime.ofLocal
+- ZonedDateTime.ofStrict
+- ZonedDateTime.withEarlierOffsetAtOverlap
+- ZonedDateTime.withLaterOffsetAtOverlap
+- ZonedDateTime.until
+- ZoneRules
+- Pseudo zones for testing purpose
+
+Increased test coverage for zone related classes
+
+#### Test Coverage and more threetenbp Features
+
+increased Test Coverage by adding/extending more tests from threetenbp 
+but also adding own tests that increase the coverage. 
+
+This also led to missing features implemented, e.g. more Fields in `DateTimeBuilder` being handled
+
+#### Bugfixes
+
+fixes found by extended Tests in
+- `Duration`
+- `DateTimeBuilder`
+- `DateTimeFormatterBuilder`
+- `YearMonth`
+
+#### dependency updates
+
+### 1.1.11
+
+#### Typescript typings
+
+make typescript definitions to be module definitions (see PR #86)
+
+#### ESDoc Updates
+
+fixed some warnings in esdoc build regarding signature mismatches (see PR #87)
+
+#### Bugfixes
+
+#### dependency updates
+
+### 1.1.9
+
+#### Typescript typings
+
+added initial typescript typings (`.d.ts`) provided by [@spencerwi](https://github.com/spencerwi) and test based on the code from [CheatSheet](CheatSheet.md) to verify the typings 
+
+#### Bugfixes
+
+#### dependency updates
+ * several dev dependency updates
+  
+### 1.1.8
+
+last release without a CHANGELOG.md