@chatlychat/world 0.0.0-stage → 0.1.0

package/dist/capabilities.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Host capabilities: what the visitor's world can DO, declared to the bot and
+ * dispatched to handlers the host registers.
+ *
+ * The world never walks, dresses or spawns anything itself — those are the
+ * host's. This surfaces the four standard intents as typed handlers and keeps
+ * the contract every capability carries:
+ *
+ *  - an `equivalent` is REQUIRED at registration, because a bot's offer must
+ *    mean something to a visitor whose world cannot do it. It is announced
+ *    whenever a handler is missing, declines or throws;
+ *  - the host is the gate: a handler may return `false` or throw to refuse, and
+ *    a refusal is reported as `failed` with `refused: true` (two refusals in ten
+ *    minutes stop the bot firing it — server-side);
+ *  - args are checked here against the declared shape before a handler sees
+ *    them, because a bot-fired invocation is data from outside.
+ */
+import type { ConversationLike } from './types.js';
+import type { CapabilityEquivalent, HostCapabilityDeclaration, HostSurface, HostSurfaceState } from '@chatlychat/core';
+/** The standard intents and their arguments. Names are verbs, never positions. */
+export interface WorldActionMap {
+    'world.walk_to': {
+        place: string;
+    };
+    'avatar.try_on': {
+        item: string;
+    };
+    'scene.highlight': {
+        ref: string;
+    };
+    'scene.spawn': {
+        ref: string;
+    };
+}
+export type StandardAction = keyof WorldActionMap;
+/** What a handler may answer. `false` or a throw is a refusal; `void`/`true` is done. */
+export type ActionOutcome = void | boolean | {
+    readonly ok: boolean;
+    readonly text?: string;
+};
+export interface ActionContext {
+    readonly equivalent: CapabilityEquivalent;
+    /** True when the bot fired it without a press. */
+    readonly unprompted: boolean;
+}
+export type ActionHandler<A extends Readonly<Record<string, unknown>>> = (args: A, ctx: ActionContext) => ActionOutcome | Promise<ActionOutcome>;
+export interface RegisterOptions {
+    /** What a person or screen reader gets instead of the world doing it. Required. */
+    readonly equivalent: CapabilityEquivalent;
+    /** Let the bot fire it without a press. Off by default. */
+    readonly unprompted?: boolean;
+    readonly label?: string;
+    readonly description?: string;
+    /** Required for a custom (non-standard) name; a small JSON-Schema subset. */
+    readonly args?: Readonly<Record<string, unknown>>;
+}
+export interface ActionReport {
+    readonly status: 'done' | 'failed';
+    readonly refused: boolean;
+    readonly text: string | null;
+}
+export declare class CapabilityRegistry {
+    private readonly announce;
+    private readonly entries;
+    constructor(announce?: (text: string) => void);
+    register<N extends StandardAction>(name: N, handler: ActionHandler<WorldActionMap[N]>, opts: RegisterOptions): () => void;
+    register(name: string, handler: ActionHandler<Readonly<Record<string, unknown>>>, opts: RegisterOptions): () => void;
+    declarations(): readonly HostCapabilityDeclaration[];
+    /** The surface to hand `core.setSurface`. */
+    surface(state?: HostSurfaceState, kind?: string): HostSurface;
+    has(name: string): boolean;
+    /** Run a handler, with every failure mode folded into a report. Never throws. */
+    invoke(name: string, args: Readonly<Record<string, unknown>>, unprompted: boolean): Promise<ActionReport>;
+    /** Route a bot-fired invocation to its handler and answer it into the thread. */
+    bind(conversation: ConversationLike): () => void;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.js

@@ -0,0 +1,118 @@
+const STANDARD = {
+    'world.walk_to': {
+        label: 'Take me there',
+        description: 'Walk the visitor to a named place.',
+        arg: 'place',
+    },
+    'avatar.try_on': {
+        label: 'Try it on',
+        description: "Put an item on the visitor's avatar.",
+        arg: 'item',
+    },
+    'scene.highlight': {
+        label: 'Show me',
+        description: 'Highlight a named object in the scene.',
+        arg: 'ref',
+    },
+    'scene.spawn': {
+        label: 'Bring it here',
+        description: 'Place a named object in front of the visitor.',
+        arg: 'ref',
+    },
+};
+const ARG_MAX = 40;
+const equivalentText = (e) => e.kind === 'text' ? e.text : (e.text ?? e.href);
+export class CapabilityRegistry {
+    announce;
+    entries = new Map();
+    constructor(announce = () => undefined) {
+        this.announce = announce;
+    }
+    register(name, handler, opts) {
+        const std = STANDARD[name];
+        const decl = {
+            name,
+            label: opts.label ?? std?.label ?? name,
+            ...((opts.description ?? std?.description)
+                ? { description: (opts.description ?? std?.description) }
+                : {}),
+            ...(opts.args !== undefined || std !== undefined
+                ? {
+                    args: opts.args ?? {
+                        type: 'object',
+                        properties: { [std?.arg]: { type: 'string', maxLength: ARG_MAX } },
+                        required: [std?.arg],
+                    },
+                }
+                : {}),
+            ...(opts.unprompted === true ? { unprompted: true } : {}),
+            equivalent: opts.equivalent,
+        };
+        this.entries.set(name, {
+            decl,
+            handler: handler,
+            argName: std?.arg ?? null,
+        });
+        return () => {
+            this.entries.delete(name);
+        };
+    }
+    declarations() {
+        return [...this.entries.values()].map((e) => e.decl);
+    }
+    /** The surface to hand `core.setSurface`. */
+    surface(state, kind = 'world') {
+        return { kind, capabilities: this.declarations(), ...(state === undefined ? {} : { state }) };
+    }
+    has(name) {
+        return this.entries.has(name);
+    }
+    /** Run a handler, with every failure mode folded into a report. Never throws. */
+    async invoke(name, args, unprompted) {
+        const e = this.entries.get(name);
+        if (e === undefined) {
+            return { status: 'failed', refused: true, text: null };
+        }
+        const fail = (refused) => {
+            this.announce(equivalentText(e.decl.equivalent));
+            return { status: 'failed', refused, text: equivalentText(e.decl.equivalent) };
+        };
+        if (e.argName !== null) {
+            const v = args[e.argName];
+            if (typeof v !== 'string' || v === '' || v.length > ARG_MAX) {
+                return fail(false);
+            }
+        }
+        try {
+            const out = await e.handler(args, { equivalent: e.decl.equivalent, unprompted });
+            const ok = out === undefined || out === true || (typeof out === 'object' && out.ok);
+            if (!ok) {
+                return fail(true);
+            }
+            return {
+                status: 'done',
+                refused: false,
+                text: typeof out === 'object' ? (out.text ?? null) : null,
+            };
+        }
+        catch {
+            return fail(true);
+        }
+    }
+    /** Route a bot-fired invocation to its handler and answer it into the thread. */
+    bind(conversation) {
+        return conversation.onCapability((inv) => {
+            void this.invoke(inv.capability, inv.args, true)
+                .then((r) => conversation.reportAction({
+                messageId: inv.messageId,
+                actionId: inv.invocationId,
+                status: r.status,
+                ...(r.text === null ? {} : { text: r.text }),
+                ...(r.refused ? { data: { refused: true } } : {}),
+            }))
+                // Reporting is best-effort: the visitor already saw the announcement.
+                .catch(() => undefined);
+        });
+    }
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/cards.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Picks: a `card_grid` rendered as objects in the scene.
+ *
+ * `buildGrid` lays the cards out (`layout.ts`), asks the card renderer — the
+ * default below or a host's override — for each one and parents them. The
+ * default card is a plate with title, subtitle and price label, a glTF model
+ * if the card has one, and the theme's pedestal, beam and selection ring.
+ */
+import { Group, type Object3D } from 'three';
+import { type GridPlacement, type Mount } from './layout.js';
+import { type ModelAnchor, type ModelLoader } from './model.js';
+import type { BlockOf, CardRenderProps, ConversationMessage, ResolvedWorldTheme } from '@chatlychat/core';
+export interface CardData {
+    readonly title: string;
+    readonly subtitle: string | null;
+    readonly price: {
+        readonly amount: number;
+        readonly currency: string;
+    } | null;
+    readonly model: {
+        readonly url: string;
+        readonly format?: string;
+        readonly scale?: number;
+        readonly anchor?: ModelAnchor;
+    } | null;
+}
+/** Read the fields a world draws off a card block, tolerantly: the block is wire data. */
+export declare function readCard(block: Readonly<Record<string, unknown>>): CardData;
+/** Minor units to a locale string. The fraction digits come from the currency, not from "100". */
+export declare function formatPrice(amount: number, currency: string, locale?: string): string;
+export interface CardDeps {
+    readonly loadModel: ModelLoader;
+    readonly onError: (e: unknown) => void;
+}
+export declare const cardKey: (message: ConversationMessage, block: Readonly<Record<string, unknown>>, index: number) => string;
+/** The default `renderCard`. */
+export declare function defaultCard(props: CardRenderProps, deps: CardDeps): Object3D;
+/** Whether a card node is drawn selected — the default's ring, readable by tests and hosts. */
+export declare function isHighlighted(node: Object3D): boolean;
+export interface GridBuild {
+    readonly group: Group;
+    readonly mount: Mount;
+    /** card key -> node, so one card can be redrawn when its selection changes. */
+    readonly nodes: Map<string, {
+        node: Object3D;
+        index: number;
+    }>;
+}
+export declare function buildGrid(placement: GridPlacement, count: number, theme: ResolvedWorldTheme, draw: (index: number) => Object3D, keyOf: (index: number) => string): GridBuild;
+export type { BlockOf };
+//# sourceMappingURL=cards.d.ts.map

package/dist/cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAEL,KAAK,EAKL,KAAK,QAAQ,EACd,MAAM,OAAO,CAAC;AAEf,OAAO,EAAe,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAY,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAK1E,OAAO,KAAK,EACV,OAAO,EACP,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAK1B,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;KAC/B,GAAG,IAAI,CAAC;CACV;AAED,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,QAAQ,CAsB3E;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAOrF;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC;AAED,eAAO,MAAM,OAAO,YACT,mBAAmB,SACrB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,SACjC,MAAM,KACZ,MAA0F,CAAC;AAE9F,gCAAgC;AAChC,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,CA2E5E;AAED,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAErD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,wBAAgB,SAAS,CACvB,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,QAAQ,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAC/B,SAAS,CAcX;AAED,YAAY,EAAE,OAAO,EAAE,CAAC"}

package/dist/cards.js

@@ -0,0 +1,136 @@
+/**
+ * Picks: a `card_grid` rendered as objects in the scene.
+ *
+ * `buildGrid` lays the cards out (`layout.ts`), asks the card renderer — the
+ * default below or a host's override — for each one and parents them. The
+ * default card is a plate with title, subtitle and price label, a glTF model
+ * if the card has one, and the theme's pedestal, beam and selection ring.
+ */
+import { CylinderGeometry, Group, Mesh, MeshBasicMaterial, RingGeometry, DoubleSide, } from 'three';
+import { layoutCards } from './layout.js';
+import { fitModel } from './model.js';
+import { createTextMesh } from './text.js';
+import { accentMaterial, panelBacking } from './theme-apply.js';
+import { WORLD_CONTRACT } from './types.js';
+const PLATE_W = 0.28;
+const PLATE_H = 0.2;
+/** Read the fields a world draws off a card block, tolerantly: the block is wire data. */
+export function readCard(block) {
+    const s = (k) => typeof block[k] === 'string' && block[k] !== '' ? block[k] : null;
+    const p = block['price'];
+    const m = block['model'];
+    return {
+        title: s('title') ?? '',
+        subtitle: s('subtitle'),
+        price: typeof p?.amount === 'number' && typeof p.currency === 'string'
+            ? { amount: p.amount, currency: p.currency }
+            : null,
+        model: typeof m?.['url'] === 'string'
+            ? {
+                url: m['url'],
+                ...(typeof m['format'] === 'string' ? { format: m['format'] } : {}),
+                ...(typeof m['scale'] === 'number' ? { scale: m['scale'] } : {}),
+                ...(typeof m['anchor'] === 'string' ? { anchor: m['anchor'] } : {}),
+            }
+            : null,
+    };
+}
+/** Minor units to a locale string. The fraction digits come from the currency, not from "100". */
+export function formatPrice(amount, currency, locale) {
+    try {
+        const f = new Intl.NumberFormat(locale, { style: 'currency', currency });
+        return f.format(amount / 10 ** (f.resolvedOptions().maximumFractionDigits ?? 2));
+    }
+    catch {
+        return `${String(amount / 100)} ${currency}`;
+    }
+}
+export const cardKey = (message, block, index) => `${message.id}:${typeof block['id'] === 'string' ? block['id'] : String(index)}`;
+/** The default `renderCard`. */
+export function defaultCard(props, deps) {
+    const { theme } = props;
+    const card = readCard(props.block);
+    const g = new Group();
+    g.name = WORLD_CONTRACT.objects.card;
+    g.userData['float'] = theme.cardPedestal === 'float';
+    if (theme.cardPedestal === 'plinth') {
+        const plinth = new Mesh(new CylinderGeometry(0.16, 0.18, 0.1, 24), accentMaterial(theme));
+        plinth.name = 'cl3-card-pedestal';
+        plinth.position.y = -0.1;
+        g.add(plinth);
+    }
+    else if (theme.cardPedestal === 'hanger') {
+        const rod = new Mesh(new CylinderGeometry(0.004, 0.004, 0.5, 6), accentMaterial(theme));
+        rod.name = 'cl3-card-pedestal';
+        rod.position.y = 0.35;
+        g.add(rod);
+    }
+    if (theme.cardBeam) {
+        const beam = new Mesh(new CylinderGeometry(0.12, 0.16, 1.2, 24, 1, true), accentMaterial(theme, 0.2));
+        beam.name = 'cl3-card-beam';
+        beam.position.y = 0.55;
+        g.add(beam);
+    }
+    const plate = panelBacking(theme, PLATE_W, PLATE_H);
+    const body = new Group();
+    if (plate !== null) {
+        body.add(plate);
+    }
+    const title = createTextMesh(card.title, theme, { maxWidthMetres: PLATE_W - 0.02, size: 0.8 });
+    title.position.set(0, card.subtitle === null ? 0.02 : 0.04, 0.002);
+    body.add(title);
+    if (card.subtitle !== null) {
+        const sub = createTextMesh(card.subtitle, theme, { maxWidthMetres: PLATE_W - 0.02, size: 0.6 });
+        sub.position.set(0, -0.03, 0.002);
+        body.add(sub);
+    }
+    if (theme.cardPriceLabel && card.price !== null) {
+        const price = createTextMesh(formatPrice(card.price.amount, card.price.currency), theme, {
+            maxWidthMetres: PLATE_W,
+            size: 0.8,
+            color: theme.accentColor,
+        });
+        price.name = 'cl3-card-price';
+        price.position.set(0, -PLATE_H / 2 - 0.03, 0.002);
+        body.add(price);
+    }
+    g.add(body);
+    if (card.model !== null && card.model.format !== 'usdz') {
+        const { url, scale, anchor } = card.model;
+        deps.loadModel(url).then((m) => {
+            const fitted = fitModel(m.scene, scale ?? 1, anchor ?? 'center');
+            fitted.name = 'cl3-card-model';
+            // The model stands above its label plate.
+            body.position.y = -0.2;
+            fitted.position.y = 0.1;
+            g.add(fitted);
+        }, deps.onError);
+    }
+    const ring = new Mesh(new RingGeometry(0.2, 0.23, 32), new MeshBasicMaterial({ color: theme.cardHighlightColor, side: DoubleSide }));
+    ring.name = 'cl3-card-highlight';
+    ring.rotation.x = -Math.PI / 2;
+    ring.position.y = -0.14;
+    ring.visible = props.selected;
+    g.add(ring);
+    return g;
+}
+/** Whether a card node is drawn selected — the default's ring, readable by tests and hosts. */
+export function isHighlighted(node) {
+    return node.getObjectByName('cl3-card-highlight')?.visible === true;
+}
+export function buildGrid(placement, count, theme, draw, keyOf) {
+    const group = new Group();
+    group.name = WORLD_CONTRACT.objects.grid;
+    group.userData['placement'] = placement;
+    const { poses, mount } = layoutCards(placement, count, theme.cardSpacingMetres);
+    const nodes = new Map();
+    poses.forEach((p, i) => {
+        const node = draw(i);
+        node.position.set(...p.position);
+        node.rotation.set(p.pitch, p.yaw, 0, 'YXZ');
+        group.add(node);
+        nodes.set(keyOf(i), { node, index: i });
+    });
+    return { group, mount, nodes };
+}
+//# sourceMappingURL=cards.js.map

package/dist/cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.js","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"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"}

package/dist/composer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The composer's state: a draft the HOST fills (a virtual keyboard, dictation,
+ * a DOM overlay, voice) and a submit the world sends. Typing in a headset is
+ * the host's problem; what is ours is that composing turns the agent's body to
+ * listen, so the draft going empty/non-empty is reported to the conversation.
+ */
+import type { ConversationLike } from './types.js';
+export interface Composer {
+    readonly draft: string;
+    readonly composing: boolean;
+    readonly busy: boolean;
+    setDraft(text: string): void;
+    /** Report composing without a draft (a custom composer with its own field). */
+    setComposing(composing: boolean): void;
+    submit(): Promise<void>;
+}
+export interface ComposerDeps {
+    readonly conversation: ConversationLike;
+    readonly onError: (e: unknown) => void;
+    readonly onSent: () => void;
+    /** The draft changed; `composingChanged` when it crossed empty/non-empty. */
+    readonly onChange: (composingChanged: boolean) => void;
+}
+export declare function createComposer(d: ComposerDeps): Composer;
+//# sourceMappingURL=composer.d.ts.map

package/dist/composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../src/composer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+EAA+E;IAC/E,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,CAAC,gBAAgB,EAAE,OAAO,KAAK,IAAI,CAAC;CACxD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,QAAQ,CAiDxD"}

package/dist/composer.js

@@ -0,0 +1,53 @@
+export function createComposer(d) {
+    let draft = '';
+    let composing = false;
+    let busy = false;
+    const flip = (next) => {
+        if (next === composing) {
+            return false;
+        }
+        composing = next;
+        d.conversation.setTyping(next);
+        return true;
+    };
+    const composer = {
+        get draft() {
+            return draft;
+        },
+        get composing() {
+            return composing;
+        },
+        get busy() {
+            return busy;
+        },
+        setDraft(text) {
+            draft = text;
+            d.onChange(flip(text !== ''));
+        },
+        setComposing(c) {
+            if (flip(c)) {
+                d.onChange(true);
+            }
+        },
+        async submit() {
+            const body = draft.trim();
+            if (body === '' || busy) {
+                return;
+            }
+            busy = true;
+            try {
+                await d.conversation.send(body);
+                composer.setDraft('');
+                d.onSent();
+            }
+            catch (e) {
+                d.onError(e);
+            }
+            finally {
+                busy = false;
+            }
+        },
+    };
+    return composer;
+}
+//# sourceMappingURL=composer.js.map

package/dist/composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.js","sourceRoot":"","sources":["../src/composer.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,cAAc,CAAC,CAAe;IAC5C,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,MAAM,IAAI,GAAG,CAAC,IAAa,EAAW,EAAE;QACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,SAAS,GAAG,IAAI,CAAC;QACjB,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,MAAM,QAAQ,GAAa;QACzB,IAAI,KAAK;YACP,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,SAAS;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,IAAI;YACN,OAAO,IAAI,CAAC;QACd,CAAC;QACD,QAAQ,CAAC,IAAI;YACX,KAAK,GAAG,IAAI,CAAC;YACb,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;QAChC,CAAC;QACD,YAAY,CAAC,CAAC;YACZ,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBACZ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QACD,KAAK,CAAC,MAAM;YACV,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;YAC1B,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,EAAE,CAAC;gBACxB,OAAO;YACT,CAAC;YACD,IAAI,GAAG,IAAI,CAAC;YACZ,IAAI,CAAC;gBACH,MAAM,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBACtB,CAAC,CAAC,MAAM,EAAE,CAAC;YACb,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACf,CAAC;oBAAS,CAAC;gBACT,IAAI,GAAG,KAAK,CAAC;YACf,CAAC;QACH,CAAC;KACF,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC"}