@mihe-dev/js 0.0.0-stage → 0.2.0

package/dist/mihe.js

@@ -0,0 +1,758 @@
+/**
+ * `Mihe` — the assistant without a framework (doc 08).
+ *
+ * The wiring between the store, the client and whatever UI draws it. It owns
+ * three responsibilities and nothing else:
+ *
+ * 1. Publish the screen context whenever the app's declaration changes.
+ * 2. Execute commands the runtime sends, and ack every one of them.
+ * 3. Hold the conversation the UI renders.
+ *
+ * State is an immutable snapshot, replaced on every change, so React's
+ * `useSyncExternalStore` reads it with no adapter: the React provider is a
+ * thin wrapper over this class, and the two cannot disagree about what a
+ * proposal or a voice event does.
+ */
+import { AssistantClient, } from "./client.js";
+import { appView, DESCRIBE_TIMEOUT_MS, hintedView } from "./card-view.js";
+import { executeCommand } from "./commands.js";
+import { formatContextReport } from "./debug.js";
+import { chartDeclaration, chartSignature, tableDeclaration, tableSignature, tabsDeclaration, tabsSignature, } from "./declarations.js";
+import { COMPONENT_ATTRIBUTE, HighlightEngine } from "./highlight.js";
+import { AssistantStore, } from "./store.js";
+import { VoiceSession, voiceUrl } from "./voice.js";
+/** How long to coalesce screen changes before publishing. */
+const SCREEN_DEBOUNCE_MS = 60;
+/**
+ * How long a navigate ack waits for the destination to publish. Comfortably
+ * under the runtime's 10s command timeout, and long enough for a route that
+ * loads data before registering itself.
+ */
+const SCREEN_ARRIVAL_TIMEOUT_MS = 2500;
+export const SDK_VERSION = "0.2.0";
+/**
+ * DOM id of the assistant panel, so a custom trigger can point
+ * `aria-controls` at it.
+ */
+export const ASSISTANT_PANEL_ID = "mihe-panel";
+/**
+ * How the approaching ceiling is put to the user.
+ *
+ * Phrased here rather than by the runtime because it is a countdown, and the
+ * runtime sends a number. Rounded to five seconds: the figure is approximate
+ * by the time it has crossed a socket and been rendered, and a notice reading
+ * "27 seconds left" claims a precision nobody has.
+ */
+function endingSoonNotice(secondsRemaining) {
+    const rounded = Math.max(5, Math.round(secondsRemaining / 5) * 5);
+    return `About ${rounded} seconds left of voice. The conversation carries on in text.`;
+}
+function messageId(prefix) {
+    return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/** Create the assistant and connect it. */
+export function createMihe(options) {
+    const mihe = new Mihe(options);
+    mihe.connect();
+    return mihe;
+}
+export class Mihe {
+    /** The app's declaration of itself. */
+    store = new AssistantStore();
+    highlighter = new HighlightEngine();
+    options;
+    state;
+    listeners = new Set();
+    client = null;
+    voiceSession = null;
+    /**
+     * Set while the user is waiting on a permit they asked for.
+     *
+     * A token arriving with this false is one the runtime issued for a probe at
+     * connect time, and starting a session on it would turn the microphone on
+     * without anyone having asked.
+     */
+    voiceRequested = false;
+    /** The mode asked for, read when the permit comes back. */
+    requestedHandsFree = false;
+    /** Whether the session being requested should open the panel. */
+    requestedOpenPanel = true;
+    levelListeners = new Set();
+    /** The route of the last screen context actually sent to the runtime. */
+    publishedRoute = null;
+    /** The last screen context actually sent, for acks that check a view. */
+    publishedScreen = null;
+    /** Whether that screen had finished loading its data when it was sent. */
+    publishedSettled = false;
+    /** Navigate and set_view acks waiting for the screen to report in. */
+    screenWaiters = new Set();
+    publishTimer = null;
+    unsubscribeStore = null;
+    tabs = new Map();
+    tables = new Map();
+    charts = new Map();
+    actions = new Map();
+    lastScreen = null;
+    constructor(options) {
+        this.options = { ...options };
+        this.state = {
+            connection: "idle",
+            messages: [],
+            proposals: [],
+            cardViews: {},
+            busy: false,
+            lastError: null,
+            isOpen: false,
+            assistantName: null,
+            launcherIconUrl: null,
+            widgetSettings: null,
+            voice: {
+                available: false,
+                state: "idle",
+                handsFree: false,
+                caption: "",
+                notice: null,
+                start: this.startVoiceRequest,
+                stop: this.stopVoice,
+                press: (options) => this.voiceSession?.beginUtterance(options),
+                release: () => this.voiceSession?.endUtterance(),
+                confirm: () => this.voiceSession?.confirmUtterance(),
+                discard: () => this.voiceSession?.discardUtterance(),
+                onLevel: (listener) => {
+                    this.levelListeners.add(listener);
+                    return () => {
+                        this.levelListeners.delete(listener);
+                    };
+                },
+            },
+        };
+    }
+    // ---- state -------------------------------------------------------------
+    /** The current state. The same object until something changes. */
+    getState = () => this.state;
+    /** Called after every change of state. Returns the unsubscribe. */
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    /** Voice controls and state; the same as `getState().voice`. */
+    get voice() {
+        return this.state.voice;
+    }
+    setState(patch) {
+        this.state = { ...this.state, ...patch };
+        // Copied, so a listener that unsubscribes while being called is safe.
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    setVoice(patch) {
+        this.setState({ voice: { ...this.state.voice, ...patch } });
+    }
+    setMessages(update) {
+        this.setState({ messages: update(this.state.messages) });
+    }
+    // ---- lifecycle ---------------------------------------------------------
+    /**
+     * Replace options. Callbacks take effect at once; a new `url`, `publicKey`
+     * or `debug` reconnects, since each belongs to the session.
+     */
+    update(options) {
+        const previous = this.options;
+        this.options = { ...previous, ...options };
+        const identityChanged = this.options.url !== previous.url ||
+            this.options.publicKey !== previous.publicKey ||
+            Boolean(this.options.debug) !== Boolean(previous.debug);
+        if (identityChanged && this.client) {
+            this.disconnect();
+            this.connect();
+        }
+    }
+    /** Open the session. Called by `createMihe`; does nothing if connected. */
+    connect() {
+        if (this.client)
+            return;
+        const client = new AssistantClient({
+            url: this.options.url,
+            publicKey: this.options.publicKey,
+            getUserToken: () => this.options.getUserToken(),
+            sdkVersion: SDK_VERSION,
+            onEvent: this.handleEvent,
+            debug: this.options.debug ?? false,
+        });
+        this.client = client;
+        // Debounced, because a screen with twenty components fires twenty
+        // registrations as it mounts and they should travel as one snapshot.
+        this.unsubscribeStore = this.store.subscribe(() => {
+            if (this.publishTimer !== null)
+                clearTimeout(this.publishTimer);
+            this.publishTimer = setTimeout(this.publish, SCREEN_DEBOUNCE_MS);
+        });
+        this.publish();
+        void client.connect();
+    }
+    /**
+     * Close the session, the voice session and any highlight. The
+     * conversation and the declarations stay, for a later `connect()`.
+     */
+    disconnect() {
+        if (this.publishTimer !== null)
+            clearTimeout(this.publishTimer);
+        this.publishTimer = null;
+        this.unsubscribeStore?.();
+        this.unsubscribeStore = null;
+        this.client?.close();
+        this.client = null;
+        void this.voiceSession?.stop();
+        this.voiceSession = null;
+        this.highlighter.clear();
+    }
+    /** Disconnect and drop every listener. The instance is done after this. */
+    destroy() {
+        this.disconnect();
+        this.listeners.clear();
+        this.levelListeners.clear();
+    }
+    // ---- conversation ------------------------------------------------------
+    send = (text) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        // Opening on send is what makes a "Help me add a product" button work as
+        // one call: the reply has to be visible somewhere. Harmless for host apps
+        // rendering their own always-visible panel.
+        const id = messageId("msg");
+        this.setState({
+            isOpen: true,
+            messages: [...this.state.messages, { id, role: "user", text: trimmed }],
+            lastError: null,
+        });
+        this.client?.sendMessage(trimmed, id);
+    };
+    /**
+     * Work out what a card says (amendment 99). The app's description when it
+     * gives one in time, else the registry's hints. Until then the card is
+     * pending, so nobody confirms a card whose words are about to change.
+     */
+    describe(proposal) {
+        const set = (view) => {
+            // A card already answered or withdrawn doesn't come back.
+            if (view !== "pending" && !this.state.proposals.some((p) => p.proposalId === proposal.proposalId))
+                return;
+            this.setState({ cardViews: { ...this.state.cardViews, [proposal.proposalId]: view } });
+        };
+        const describe = this.options.describeProposal;
+        if (!describe) {
+            set(hintedView(proposal));
+            return;
+        }
+        set("pending");
+        let settled = false;
+        const finish = (d) => {
+            if (settled)
+                return;
+            settled = true;
+            set(d && Array.isArray(d.lines) ? appView(d) : hintedView(proposal));
+        };
+        const timer = setTimeout(() => finish(null), DESCRIBE_TIMEOUT_MS);
+        Promise.resolve()
+            .then(() => describe(proposal))
+            .then((d) => { clearTimeout(timer); finish(d); })
+            .catch((cause) => {
+            clearTimeout(timer);
+            console.warn("[mihe] describeProposal failed; the card uses the registry's hints.", cause);
+            finish(null);
+        });
+    }
+    respondToProposal = (proposalId, confirmed) => {
+        this.client?.confirmAction(proposalId, confirmed);
+        if (!confirmed) {
+            this.setState({
+                proposals: this.state.proposals.filter((p) => p.proposalId !== proposalId),
+            });
+        }
+    };
+    open = () => {
+        if (!this.state.isOpen)
+            this.setState({ isOpen: true });
+    };
+    close = () => {
+        if (this.state.isOpen)
+            this.setState({ isOpen: false });
+    };
+    toggle = () => {
+        this.setState({ isOpen: !this.state.isOpen });
+    };
+    /**
+     * A one-tap "ask this", for suggestion chips and help links:
+     * `chip.onclick = mihe.prompt("How do I add a product?")`.
+     */
+    prompt(text) {
+        return () => this.send(text);
+    }
+    // ---- declarations ------------------------------------------------------
+    /**
+     * Declare the screen the user is on. Call it again when what the screen
+     * shows changes; call the returned function when the user leaves it.
+     *
+     * `visibleData` is what makes answers concrete — "you have 7 low-stock
+     * products" rather than "check your stock levels" — so include the summary
+     * values already on screen, and only those.
+     */
+    setScreen(screen) {
+        const serialized = JSON.stringify(screen);
+        // A render function that declares on every render would otherwise send
+        // the same screen over the socket each time.
+        if (serialized !== this.lastScreen || this.store.getScreenContext()?.screenId !== screen.screenId) {
+            this.lastScreen = serialized;
+            this.store.setScreen(JSON.parse(serialized));
+        }
+        return () => {
+            this.store.clearScreen(screen.screenId);
+            if (this.store.getScreenContext() === null)
+                this.lastScreen = null;
+        };
+    }
+    /**
+     * Declare a component the assistant can talk about or point at. Marks
+     * `element` so it can be found; pass `null` for one that is described but
+     * cannot be highlighted.
+     */
+    registerComponent(element, componentKey, meta) {
+        element?.setAttribute(COMPONENT_ATTRIBUTE, componentKey);
+        this.store.registerComponent(componentKey, { ...meta });
+        return () => {
+            this.store.unregisterComponent(componentKey);
+            if (element?.getAttribute(COMPONENT_ATTRIBUTE) === componentKey) {
+                element.removeAttribute(COMPONENT_ATTRIBUTE);
+            }
+        };
+    }
+    /**
+     * Supply the code for an action the assistant may run in the browser.
+     *
+     * The action itself — its risk tier, permissions, and whether it needs
+     * confirmation — is configured in the dashboard, not here. Whatever the
+     * handler returns becomes the tool result the model sees, so return
+     * something descriptive. Throwing reports the failure honestly.
+     */
+    registerAction(name, handler) {
+        const existing = this.actions.get(name);
+        if (existing && this.store.getAction(name) === existing.declaration) {
+            existing.latest = handler;
+            return () => this.undoAction(name, existing);
+        }
+        const entry = {
+            latest: handler,
+            signature: name,
+            declaration: { name, handler: (input) => entry.latest(input) },
+        };
+        this.actions.set(name, entry);
+        this.store.registerAction(entry.declaration);
+        return () => this.undoAction(name, entry);
+    }
+    undoAction(name, entry) {
+        if (this.actions.get(name) !== entry)
+            return;
+        this.actions.delete(name);
+        if (this.store.getAction(name) === entry.declaration)
+            this.store.unregisterAction(name);
+    }
+    /**
+     * Let the assistant see which tab is open and switch to another. Pass the
+     * tab that is really showing as `value`, and call this again when it
+     * changes: a switch is not reported done until `value` matches.
+     */
+    registerTabs(tabs) {
+        return this.declare(this.tabs, tabs.id, tabs, tabsSignature(tabs), (latest) => tabsDeclaration(latest), (id) => this.store.getControl(id), (id, declaration) => this.store.registerControl(id, declaration), (id) => this.store.unregisterControl(id));
+    }
+    /**
+     * Let the assistant read a table. The rows are not sent with the screen;
+     * the model reads them when a question needs them, and only the declared
+     * columns ever leave the browser (amendment 67). Call it again when the
+     * rows change.
+     */
+    registerTable(table) {
+        return this.declare(this.tables, table.id, table, tableSignature(table), (latest) => tableDeclaration(latest), (id) => this.store.getTable(id), (id, declaration) => this.store.registerTable(id, declaration), (id) => this.store.unregisterTable(id));
+    }
+    /**
+     * Let the assistant explain a chart. Each series is summarised here, in
+     * the browser; the points are read when an exact value is wanted. Call it
+     * again when the data changes.
+     */
+    registerChart(chart) {
+        return this.declare(this.charts, chart.id, chart, chartSignature(chart), (latest) => chartDeclaration(latest), (id) => this.store.getChart(id), (id, declaration) => this.store.registerChart(id, declaration), (id) => this.store.unregisterChart(id));
+    }
+    /**
+     * Add figures to the screen's `visibleData` under `key`: the stat cards
+     * inside a tab, a summary panel. Dropped when the screen changes.
+     */
+    setValues(key, values) {
+        this.store.setValues(key, JSON.parse(JSON.stringify(values)));
+        return () => this.store.clearValues(key);
+    }
+    /**
+     * One declaration kind's register-update-undo, shared so tabs, tables and
+     * charts behave the same. The store's entry is re-registered only when the
+     * signature changes, or when the store no longer holds it because the
+     * screen changed underneath.
+     */
+    declare(entries, id, value, signature, build, current, register, unregister) {
+        let entry = entries.get(id);
+        if (entry && current(id) === entry.declaration) {
+            entry.latest = value;
+            if (entry.signature !== signature) {
+                const target = entry;
+                entry.signature = signature;
+                entry.declaration = build(() => target.latest);
+                register(id, entry.declaration);
+            }
+        }
+        else {
+            const fresh = { latest: value, signature };
+            fresh.declaration = build(() => fresh.latest);
+            entries.set(id, fresh);
+            register(id, fresh.declaration);
+            entry = fresh;
+        }
+        const mine = entry;
+        return () => {
+            if (entries.get(id) !== mine)
+                return;
+            entries.delete(id);
+            if (current(id) === mine.declaration)
+                unregister(id);
+        };
+    }
+    /**
+     * Make an element open and close the assistant, keyboard and screen
+     * reader included: a `div` with only a click handler is invisible to both,
+     * and that is the most common way a custom trigger ships broken.
+     */
+    bindTrigger(element) {
+        const native = element instanceof HTMLButtonElement;
+        const added = ["aria-expanded", "aria-controls", "aria-haspopup"];
+        if (!native) {
+            element.setAttribute("role", "button");
+            added.push("role");
+            if (!element.hasAttribute("tabindex")) {
+                element.setAttribute("tabindex", "0");
+                added.push("tabindex");
+            }
+        }
+        element.setAttribute("aria-controls", ASSISTANT_PANEL_ID);
+        element.setAttribute("aria-haspopup", "dialog");
+        const sync = () => element.setAttribute("aria-expanded", String(this.state.isOpen));
+        const onClick = () => this.toggle();
+        // Space and Enter are what a native button responds to; a button
+        // already turns them into a click.
+        const onKeyDown = (event) => {
+            if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                this.toggle();
+            }
+        };
+        sync();
+        const unsubscribe = this.subscribe(sync);
+        element.addEventListener("click", onClick);
+        if (!native)
+            element.addEventListener("keydown", onKeyDown);
+        return () => {
+            unsubscribe();
+            element.removeEventListener("click", onClick);
+            element.removeEventListener("keydown", onKeyDown);
+            for (const attribute of added)
+                element.removeAttribute(attribute);
+        };
+    }
+    // ---- the runtime's events ---------------------------------------------
+    handleEvent = (event) => {
+        switch (event.type) {
+            case "state":
+                this.setState({ connection: event.state });
+                // Re-sent on every change of connection, so a reconnected session
+                // learns the screen without waiting for the user to move.
+                if (this.publishTimer !== null)
+                    clearTimeout(this.publishTimer);
+                this.publishTimer = null;
+                this.publish();
+                break;
+            case "turn_start":
+                this.setState({
+                    busy: true,
+                    messages: [
+                        ...this.state.messages,
+                        { id: event.turnId, role: "assistant", text: "", streaming: true },
+                    ],
+                });
+                break;
+            case "delta":
+                this.setMessages((current) => current.map((message) => message.id === event.turnId
+                    ? { ...message, text: message.text + event.text }
+                    : message));
+                break;
+            case "complete":
+                this.setState({
+                    busy: false,
+                    messages: this.state.messages.map((message) => message.id === event.turnId
+                        ? {
+                            ...message,
+                            text: event.message,
+                            streaming: false,
+                            sources: event.sources.length ? event.sources : undefined,
+                        }
+                        : message),
+                });
+                break;
+            case "command": {
+                const ctx = {
+                    store: this.store,
+                    highlighter: this.highlighter,
+                    navigate: this.options.navigate ??
+                        ((route) => {
+                            window.location.assign(route);
+                        }),
+                    screenPublished: this.awaitScreenPublished,
+                    viewPublished: this.awaitViewPublished,
+                    openModal: this.options.openModal,
+                };
+                const client = this.client;
+                // Always acks, including on a thrown handler, because the runtime is
+                // blocking a turn until it hears back.
+                void executeCommand(event.command, ctx)
+                    .then((result) => client?.ackCommand(event.commandId, result.ok, result.result, result.error))
+                    .catch((cause) => client?.ackCommand(event.commandId, false, undefined, cause instanceof Error ? cause.message : "The command failed."));
+                break;
+            }
+            case "proposal":
+                this.setState({ proposals: [...this.state.proposals, event.proposal] });
+                this.describe(event.proposal);
+                break;
+            case "action_status": {
+                if (event.status === "executing")
+                    break;
+                // Retire the card and say what became of it. Without this the card
+                // simply vanishes on approval and the assistant stays silent — which
+                // reads as nothing having happened, for an action that may have just
+                // notified a customer. The model does learn the outcome, but not
+                // until its next turn, so it cannot be what tells the user.
+                const settled = this.state.proposals.find((p) => p.proposalId === event.proposalId);
+                if (settled) {
+                    // Keyed by the proposal, so a status arriving twice — a reconnect
+                    // replaying it, a double tap — settles to one line rather than two.
+                    const statusId = `status_${event.proposalId}`;
+                    if (event.status !== "rejected" && !this.state.messages.some((m) => m.id === statusId)) {
+                        // The label comes from the registry, like everything else on the
+                        // card, so this line cannot be steered by model output.
+                        const outcome = event.status === "executed"
+                            ? `${settled.label} — done.`
+                            : `${settled.label} — ${event.error ?? "that did not work."}`;
+                        this.setMessages((messages) => [
+                            ...messages,
+                            { id: statusId, role: "assistant", text: outcome },
+                        ]);
+                    }
+                    // Host apps cache — an action that changed data server-side leaves
+                    // the page showing what was true a moment ago.
+                    this.options.onActionComplete?.({
+                        actionName: settled.actionName,
+                        status: event.status,
+                        result: event.result,
+                    });
+                }
+                this.setState({
+                    proposals: this.state.proposals.filter((p) => p.proposalId !== event.proposalId),
+                    ...(event.error ? { lastError: event.error } : {}),
+                });
+                break;
+            }
+            case "voice_available":
+                this.setVoice({ available: event.available });
+                break;
+            case "assistant_name":
+                this.setState({ assistantName: event.name });
+                break;
+            case "launcher_icon":
+                this.setState({ launcherIconUrl: event.url });
+                break;
+            case "widget_settings":
+                this.setState({ widgetSettings: event.settings });
+                break;
+            case "context_report":
+                console.info(formatContextReport(event.report));
+                break;
+            case "voice_token":
+                // Only ever the answer to a session the user actually asked for. It
+                // used to double as an availability probe, which meant minting a
+                // single-use credential to answer a yes/no question.
+                if (!this.voiceRequested)
+                    break;
+                this.voiceRequested = false;
+                void this.startVoice(event.token);
+                break;
+            case "error":
+                // Voice refusals are not chat errors and must not be shown as one:
+                // the chat socket is fine, and the honest reading is "voice is not
+                // available here", which is a button that should disappear.
+                if (event.code.startsWith("voice_")) {
+                    this.voiceRequested = false;
+                    this.setState({ busy: false, voice: { ...this.state.voice, available: false } });
+                    break;
+                }
+                this.setState({ busy: false, lastError: event.message });
+                break;
+        }
+    };
+    // ---- screen publishing -------------------------------------------------
+    publish = () => {
+        this.publishTimer = null;
+        const screen = this.store.getScreenContext();
+        // A null screen is published, not skipped. The user has navigated to a
+        // page the host app never declared, and the runtime has to be told —
+        // otherwise it answers with the last screen it heard about. Nothing is
+        // sent before the first screen ever registers, since there is no move to
+        // report yet.
+        if (!screen && this.publishedRoute === null)
+            return;
+        this.client?.updateScreen(screen);
+        this.publishedRoute = screen?.route ?? null;
+        this.publishedScreen = screen;
+        // Published either way, so the runtime knows where the user is and scopes
+        // actions to it. But a navigation is not acked against a screen whose
+        // data is still loading: the model's next step would read its empty
+        // counts as the answer.
+        this.publishedSettled = !this.store.isScreenLoading();
+        if (!screen || !this.publishedSettled)
+            return;
+        // Copied, because a waiter that matches removes itself from the set.
+        for (const waiter of [...this.screenWaiters])
+            waiter(screen);
+    };
+    /**
+     * A navigate command cannot be acked until the destination has published
+     * its context, or the runtime's next step would still be reasoning about
+     * the screen the user just left. See `CommandContext.screenPublished`.
+     */
+    awaitScreenPublished = (route, options) => new Promise((resolve) => {
+        // Pages publish their path, never the query, so arrival is matched on
+        // the path.
+        const path = route.split("?")[0];
+        if (!options?.fresh && this.publishedRoute === path && this.publishedSettled) {
+            return resolve(true);
+        }
+        const done = (arrived) => {
+            this.screenWaiters.delete(waiter);
+            clearTimeout(timer);
+            resolve(arrived);
+        };
+        const waiter = (published) => {
+            if (published.route === path)
+                done(true);
+        };
+        // Bounded, so a route the app never publishes stalls one turn rather
+        // than hanging until the runtime's own ack timeout fires.
+        const timer = setTimeout(() => done(false), SCREEN_ARRIVAL_TIMEOUT_MS);
+        this.screenWaiters.add(waiter);
+    });
+    /**
+     * A set_view ack waits the same way, for the tab the app was asked to show
+     * to be the one the published screen reports. An app whose `onChange` did
+     * nothing is reported as a failure rather than a switch that did not
+     * happen.
+     */
+    awaitViewPublished = (controlKey, value) => new Promise((resolve) => {
+        const showing = (screen) => screen?.controls.some((control) => control.controlKey === controlKey && control.value === value) ?? false;
+        if (this.publishedSettled && showing(this.publishedScreen))
+            return resolve(true);
+        const done = (shown) => {
+            this.screenWaiters.delete(waiter);
+            clearTimeout(timer);
+            resolve(shown);
+        };
+        const waiter = (published) => {
+            if (showing(published))
+                done(true);
+        };
+        const timer = setTimeout(() => done(false), SCREEN_ARRIVAL_TIMEOUT_MS);
+        this.screenWaiters.add(waiter);
+    });
+    // ---- voice -------------------------------------------------------------
+    startVoiceRequest = (options) => {
+        // A new session is not the place to still be reading why the last one
+        // stopped.
+        this.setVoice({ notice: null });
+        // A fresh permit every time: they are single use and expire in a minute.
+        this.requestedHandsFree = Boolean(options?.handsFree);
+        this.requestedOpenPanel = options?.openPanel ?? true;
+        this.voiceRequested = true;
+        this.client?.requestVoiceToken();
+    };
+    stopVoice = () => {
+        this.voiceRequested = false;
+        void this.voiceSession?.stop();
+        this.voiceSession = null;
+        // A countdown for a session the user has already closed is worse than no
+        // notice: it is a wrong one.
+        this.setVoice({ handsFree: false, notice: null });
+    };
+    async startVoice(token) {
+        const wanted = this.requestedHandsFree;
+        this.setVoice({ handsFree: wanted });
+        const session = new VoiceSession({
+            url: voiceUrl(this.options.url, token, wanted),
+            handsFree: wanted,
+            onEvent: this.handleVoiceEvent,
+            onLevel: (source, level) => {
+                for (const listener of this.levelListeners)
+                    listener(source, level);
+            },
+        });
+        this.voiceSession = session;
+        // Opening the panel so what is said has somewhere to appear, for the
+        // same reason `send` does, unless the caller shows voice itself.
+        if (this.requestedOpenPanel)
+            this.open();
+        await session.start();
+    }
+    handleVoiceEvent = (event) => {
+        switch (event.type) {
+            case "state":
+                this.setVoice({
+                    state: event.state,
+                    ...(event.state === "idle" || event.state === "error" ? { caption: "" } : {}),
+                });
+                break;
+            case "transcript":
+                // The caption is for words still being spoken. Once a line is final
+                // it joins the transcript, so the caption is cleared rather than
+                // showing the same sentence twice.
+                if (event.final) {
+                    this.setState({
+                        voice: { ...this.state.voice, caption: "" },
+                        messages: [
+                            ...this.state.messages,
+                            { id: messageId("voice"), role: event.role, text: event.text },
+                        ],
+                    });
+                }
+                else {
+                    this.setVoice({ caption: event.text });
+                }
+                break;
+            case "ending_soon":
+                this.setVoice({ notice: endingSoonNotice(event.secondsRemaining) });
+                break;
+            case "ended":
+                // The runtime's own words, which say the conversation survives. The
+                // session tore itself down, so nothing else will clear the mode; left
+                // set, the next push-to-talk session would open as hands-free.
+                this.setVoice({ caption: "", notice: event.message, handsFree: false });
+                break;
+            case "error":
+                this.setState({ lastError: event.message });
+                break;
+        }
+    };
+}
+//# sourceMappingURL=mihe.js.map