@calliopelabs/ui 0.13.0 → 0.16.0

package/dist/agent/engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * An engine runs an AG-UI agent for the controller: it starts runs, executes
+ * the browser's tools and decides on follow-up runs. Two ship: the direct
+ * engine here, over any `@ag-ui/client` agent (an `HttpAgent` on a plain
+ * AG-UI endpoint), and the CopilotKit engine (`@calliopelabs/ui/agent/copilotkit`),
+ * which hands the same work to CopilotKit's core. The controller reads the
+ * agent's events either way, so the conversation looks the same.
+ */
+import type { AbstractAgent } from "@ag-ui/client";
+import type { Context, ResumeEntry } from "@ag-ui/core";
+import { type AgentTool } from "./tool.js";
+/** Runs a tool call for an engine, with validation and human-in-the-loop waiting. */
+export type ToolInvoker = (tool: AgentTool, args: unknown, call: {
+    toolCallId: string;
+    signal: AbortSignal;
+}) => Promise<unknown>;
+export interface EngineRunInput {
+    forwardedProps?: Record<string, unknown>;
+    /** Answers to the previous run's interrupts. */
+    resume?: ResumeEntry[];
+}
+export interface AgentEngine {
+    readonly agent: AbstractAgent;
+    /** Runs until the agent is done: frontend tool calls answered, follow-ups made. */
+    run(input: EngineRunInput): Promise<void>;
+    /** Stops the run in flight and any tool it is waiting on. */
+    stop(): void;
+    /** The tools the agent may call now; the controller calls this whenever they change. */
+    setTools(tools: readonly AgentTool[]): void;
+    /** The context (readables) the next run carries. */
+    setContext(context: readonly Context[]): void;
+    /** Lets go of everything the engine registered. */
+    dispose(): void;
+}
+/**
+ * The engine for a plain AG-UI agent. Each run sends the tools and context;
+ * when the agent calls a browser tool, the engine runs it, adds the result to
+ * the agent's messages and runs again (unless the tool says `followUp: false`).
+ * A run that ends on an interrupt stops there: the person's answer resumes it.
+ */
+export declare function createDirectEngine(agent: AbstractAgent, invoke: ToolInvoker): AgentEngine;

package/dist/agent/engine.js

@@ -0,0 +1,93 @@
+import { toolJsonSchema, toolResultText } from "./tool.js";
+/** Runs past this many follow-ups in one turn are a loop, not a conversation. */
+const MAX_FOLLOW_UPS = 8;
+/**
+ * The engine for a plain AG-UI agent. Each run sends the tools and context;
+ * when the agent calls a browser tool, the engine runs it, adds the result to
+ * the agent's messages and runs again (unless the tool says `followUp: false`).
+ * A run that ends on an interrupt stops there: the person's answer resumes it.
+ */
+export function createDirectEngine(agent, invoke) {
+    let tools = [];
+    let context = [];
+    let aborter = null;
+    const answered = (toolCallId) => agent.messages.some((m) => m.role === "tool" && m.toolCallId === toolCallId);
+    return {
+        agent,
+        async run({ forwardedProps, resume }) {
+            aborter?.abort();
+            const own = new AbortController();
+            aborter = own;
+            let params = { resume };
+            try {
+                for (let turn = 0; turn <= MAX_FOLLOW_UPS; turn++) {
+                    const offered = tools.filter((t) => t.available !== false);
+                    const { newMessages } = await agent.runAgent({
+                        ...params,
+                        tools: offered.map((t) => ({
+                            name: t.name,
+                            description: t.description ?? "",
+                            parameters: toolJsonSchema(t),
+                        })),
+                        context: [...context],
+                        ...(forwardedProps ? { forwardedProps } : {}),
+                    });
+                    if (own.signal.aborted || agent.pendingInterrupts.length > 0)
+                        return;
+                    const calls = newMessages.flatMap((m) => m.role === "assistant" ? (m.toolCalls ?? []) : []);
+                    let again = false;
+                    for (const call of calls) {
+                        const tool = offered.find((t) => t.name === call.function.name);
+                        if (!tool || answered(call.id))
+                            continue;
+                        let content;
+                        let error;
+                        try {
+                            const args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+                            content = toolResultText(await invoke(tool, args, { toolCallId: call.id, signal: own.signal }));
+                        }
+                        catch (e) {
+                            if (own.signal.aborted)
+                                return;
+                            error = e instanceof Error ? e.message : String(e);
+                            content = `Error: ${error}`;
+                        }
+                        if (own.signal.aborted)
+                            return;
+                        agent.addMessage({
+                            id: `${call.id}:result`,
+                            role: "tool",
+                            toolCallId: call.id,
+                            content,
+                            ...(error ? { error } : {}),
+                        });
+                        if (tool.followUp !== false)
+                            again = true;
+                    }
+                    if (!again)
+                        return;
+                    params = {};
+                }
+            }
+            finally {
+                if (aborter === own)
+                    aborter = null;
+            }
+        },
+        stop() {
+            aborter?.abort();
+            aborter = null;
+            if (agent.isRunning)
+                agent.abortRun();
+        },
+        setTools(next) {
+            tools = next;
+        },
+        setContext(next) {
+            context = next;
+        },
+        dispose() {
+            this.stop();
+        },
+    };
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@calliopelabs/ui/agent`: one embedded agent for every Calliope AI product,
+ * over the AG-UI protocol, drawn with the chat kit. Opt-in: it needs
+ * `@ag-ui/client`, which the package's main entry never loads. For a
+ * CopilotKit runtime, see `@calliopelabs/ui/agent/copilotkit`.
+ */
+export { AgentController, agentId, type AgentContextEntry, type AgentCustomItem, type AgentControllerOptions, type AgentSnapshot, type AgentSuggestion, type AgentThread, type SendOptions, } from "./controller.js";
+export { createDirectEngine, type AgentEngine, type EngineRunInput, type ToolInvoker, } from "./engine.js";
+export { defineTool, isStandardSchema, toolJsonSchema, toolResultText, toolStandardSchema, validateToolArgs, type AgentTool, type AgentToolContext, type AgentToolRenderProps, type JsonSchema, type StandardSchemaV1, } from "./tool.js";
+export { CalliopeAgentProvider, useAgentController, useAgentReadable, useAgentSuggestions, useAgentTool, useCalliopeAgent, type CalliopeAgentApi, type CalliopeAgentOptions, type CalliopeAgentProviderProps, } from "./AgentProvider.js";
+export { createFunctionAgent, createMockAgent, type AgentRunFunction, type FunctionAgentOptions, textEvents, toolCallEvents, type MockAgentOptions, type MockTurn, } from "./mock.js";
+export { AgentChat, NewConversationButton, type AgentChatProps } from "./AgentChat.js";
+export { AgentLauncher, type AgentLauncherProps } from "./AgentLauncher.js";
+export { CalliopeAgent, type CalliopeAgentMode, type CalliopeAgentProps } from "./CalliopeAgent.js";
+export { shortcutLabel, useMediaQuery, useOpenState, useShortcut } from "./surface.js";
+export { mergeRenderers, parseResult, type AgentRenderers, type CustomRendererProps, type InterruptRendererProps, type StateRendererProps, type ToolRendererProps, } from "./renderers.js";
+export { ArtifactReviewCard, InterruptCard, QuestionInterruptCard, RunProgressCard, workflowRenderers, type ArtifactReviewValue, type ArtifactValue, type QuestionInterruptMetadata, type RunProgressValue, } from "./WorkflowRenderers.js";

package/dist/agent/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@calliopelabs/ui/agent`: one embedded agent for every Calliope AI product,
+ * over the AG-UI protocol, drawn with the chat kit. Opt-in: it needs
+ * `@ag-ui/client`, which the package's main entry never loads. For a
+ * CopilotKit runtime, see `@calliopelabs/ui/agent/copilotkit`.
+ */
+export { AgentController, agentId, } from "./controller.js";
+export { createDirectEngine, } from "./engine.js";
+export { defineTool, isStandardSchema, toolJsonSchema, toolResultText, toolStandardSchema, validateToolArgs, } from "./tool.js";
+export { CalliopeAgentProvider, useAgentController, useAgentReadable, useAgentSuggestions, useAgentTool, useCalliopeAgent, } from "./AgentProvider.js";
+export { createFunctionAgent, createMockAgent, textEvents, toolCallEvents, } from "./mock.js";
+export { AgentChat, NewConversationButton } from "./AgentChat.js";
+export { AgentLauncher } from "./AgentLauncher.js";
+export { CalliopeAgent } from "./CalliopeAgent.js";
+export { shortcutLabel, useMediaQuery, useOpenState, useShortcut } from "./surface.js";
+export { mergeRenderers, parseResult, } from "./renderers.js";
+export { ArtifactReviewCard, InterruptCard, QuestionInterruptCard, RunProgressCard, workflowRenderers, } from "./WorkflowRenderers.js";

package/dist/agent/mock.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agents from functions: `createFunctionAgent` adapts any function that
+ * produces AG-UI events (a non-AG-UI backend, wrapped), and `createMockAgent`
+ * plays recorded turns for Storybook and tests. Both are a real
+ * `@ag-ui/client` `HttpAgent` whose fetch is answered in the page as a
+ * server-sent event stream, never over the network.
+ */
+import { HttpAgent } from "@ag-ui/client";
+import { type Message, type RunAgentInput } from "@ag-ui/core";
+import type { AgUiEvent } from "../chat/model.js";
+/** What the mock answers one run with: the events, without the run's start and finish. */
+export type MockTurn = readonly AgUiEvent[] | ((input: RunAgentInput, turn: number) => readonly AgUiEvent[]);
+export interface MockAgentOptions {
+    /**
+     * One entry per run, in order; the last repeats. A function sees the run's
+     * input (messages, tools, context, resume) and the run's index.
+     */
+    turns: readonly MockTurn[];
+    /** Pause between events, in ms; 0 for tests. Defaults to 30. */
+    delay?: number;
+    threadId?: string;
+    initialMessages?: Message[];
+    initialState?: unknown;
+    /** Every request's input, for a test to read. */
+    onRequest?: (input: RunAgentInput) => void;
+}
+/**
+ * The events of one run, as a function produces them: a list, a promise of
+ * one, or an async iterable that yields them as they come. The run's start
+ * and finish are added unless the function emits them.
+ */
+export type AgentRunFunction = (input: RunAgentInput, signal: AbortSignal) => Iterable<AgUiEvent> | AsyncIterable<AgUiEvent> | Promise<Iterable<AgUiEvent>>;
+export interface FunctionAgentOptions {
+    threadId?: string;
+    initialMessages?: Message[];
+    initialState?: unknown;
+    /** Pause before each event, in ms (a recording played back at reading speed). */
+    delay?: number;
+}
+/**
+ * An AG-UI agent from a function: the adapter for a backend that does not
+ * speak AG-UI yet (a request and response endpoint, a custom stream), and
+ * the base of `createMockAgent`. It is a real `HttpAgent` whose transport is
+ * the function, so the client's parser, verifier and message bookkeeping run
+ * as they do against a live endpoint, and `stop` aborts `signal`.
+ */
+export declare function createFunctionAgent(run: AgentRunFunction, { threadId, initialMessages, initialState, delay }?: FunctionAgentOptions): HttpAgent;
+/** An agent that answers from `turns`, streaming each event as SSE. */
+export declare function createMockAgent({ turns, delay, threadId, initialMessages, initialState, onRequest, }: MockAgentOptions): HttpAgent;
+/** An assistant's streamed reply, in `chunks`, as the events that make it. */
+export declare function textEvents(messageId: string, ...chunks: string[]): AgUiEvent[];
+/** A tool call with its arguments, optionally with a result (a backend tool). */
+export declare function toolCallEvents(toolCallId: string, name: string, args: unknown, options?: {
+    parentMessageId?: string;
+    result?: unknown;
+}): AgUiEvent[];

package/dist/agent/mock.js

@@ -0,0 +1,143 @@
+/**
+ * Agents from functions: `createFunctionAgent` adapts any function that
+ * produces AG-UI events (a non-AG-UI backend, wrapped), and `createMockAgent`
+ * plays recorded turns for Storybook and tests. Both are a real
+ * `@ag-ui/client` `HttpAgent` whose fetch is answered in the page as a
+ * server-sent event stream, never over the network.
+ */
+import { HttpAgent } from "@ag-ui/client";
+import { EventType } from "@ag-ui/core";
+const encoder = new TextEncoder();
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(new DOMException("Aborted", "AbortError"));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+    }, { once: true });
+});
+async function* eventsOf(output) {
+    if (Symbol.asyncIterator in output)
+        yield* output;
+    else
+        yield* output;
+}
+/**
+ * An AG-UI agent from a function: the adapter for a backend that does not
+ * speak AG-UI yet (a request and response endpoint, a custom stream), and
+ * the base of `createMockAgent`. It is a real `HttpAgent` whose transport is
+ * the function, so the client's parser, verifier and message bookkeeping run
+ * as they do against a live endpoint, and `stop` aborts `signal`.
+ */
+export function createFunctionAgent(run, { threadId, initialMessages, initialState, delay = 0 } = {}) {
+    const fetch = async (_url, init) => {
+        const input = JSON.parse(String(init.body));
+        const signal = init.signal ?? new AbortController().signal;
+        const body = new ReadableStream({
+            async start(controller) {
+                try {
+                    let ended = false;
+                    controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId })}\n\n`));
+                    const output = run(input, signal);
+                    const source = output instanceof Promise ? await output : output;
+                    for await (const event of eventsOf(source)) {
+                        if (delay > 0)
+                            await sleep(delay, signal);
+                        if (signal.aborted)
+                            throw new DOMException("Aborted", "AbortError");
+                        if (event.type === EventType.RUN_STARTED)
+                            continue;
+                        if (event.type === EventType.RUN_FINISHED || event.type === EventType.RUN_ERROR)
+                            ended = true;
+                        controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+                    }
+                    if (!ended) {
+                        const finished = {
+                            type: EventType.RUN_FINISHED,
+                            threadId: input.threadId,
+                            runId: input.runId,
+                        };
+                        controller.enqueue(encoder.encode(`data: ${JSON.stringify(finished)}\n\n`));
+                    }
+                    controller.close();
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        controller.error(error);
+                    else {
+                        const failed = {
+                            type: EventType.RUN_ERROR,
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                        controller.enqueue(encoder.encode(`data: ${JSON.stringify(failed)}\n\n`));
+                        controller.close();
+                    }
+                }
+            },
+        });
+        return new Response(body, { status: 200, headers: { "content-type": "text/event-stream" } });
+    };
+    return new HttpAgent({
+        url: "https://agent.invalid/agui",
+        fetch,
+        ...(threadId ? { threadId } : {}),
+        ...(initialMessages ? { initialMessages } : {}),
+        ...(initialState !== undefined ? { initialState: initialState } : {}),
+    });
+}
+/** An agent that answers from `turns`, streaming each event as SSE. */
+export function createMockAgent({ turns, delay = 30, threadId, initialMessages, initialState, onRequest, }) {
+    let turn = 0;
+    return createFunctionAgent(async function* (input) {
+        onRequest?.(input);
+        const index = turn++;
+        const script = turns[Math.min(index, turns.length - 1)] ?? [];
+        const events = typeof script === "function" ? script(input, index) : script;
+        // Yield once first, so even a delay of 0 streams instead of arriving in one piece.
+        for (const event of events) {
+            await Promise.resolve();
+            yield event;
+        }
+    }, {
+        delay,
+        ...(threadId ? { threadId } : {}),
+        ...(initialMessages ? { initialMessages } : {}),
+        ...(initialState !== undefined ? { initialState } : {}),
+    });
+}
+/** An assistant's streamed reply, in `chunks`, as the events that make it. */
+export function textEvents(messageId, ...chunks) {
+    return [
+        { type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" },
+        ...chunks.map((delta) => ({
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId,
+            delta,
+        })),
+        { type: EventType.TEXT_MESSAGE_END, messageId },
+    ];
+}
+/** A tool call with its arguments, optionally with a result (a backend tool). */
+export function toolCallEvents(toolCallId, name, args, options = {}) {
+    return [
+        {
+            type: EventType.TOOL_CALL_START,
+            toolCallId,
+            toolCallName: name,
+            ...(options.parentMessageId ? { parentMessageId: options.parentMessageId } : {}),
+        },
+        { type: EventType.TOOL_CALL_ARGS, toolCallId, delta: JSON.stringify(args) },
+        { type: EventType.TOOL_CALL_END, toolCallId },
+        ...(options.result === undefined
+            ? []
+            : [
+                {
+                    type: EventType.TOOL_CALL_RESULT,
+                    messageId: `${toolCallId}:result`,
+                    toolCallId,
+                    content: typeof options.result === "string" ? options.result : JSON.stringify(options.result),
+                },
+            ]),
+    ];
+}

package/dist/agent/renderers.d.ts

@@ -0,0 +1,49 @@
+import type * as React from "react";
+import { type AgUiInterrupt, type ChatToolCall } from "../chat/model.js";
+import type { CalliopeAgentApi } from "./AgentProvider.js";
+import type { AgentToolRenderProps } from "./tool.js";
+/** What a tool renderer draws from: the call, its arguments and result, and the agent. */
+export interface ToolRendererProps<Args = unknown> extends AgentToolRenderProps<Args> {
+    /** The result parsed as JSON, or as text when it is not JSON. */
+    result: unknown;
+    agent: CalliopeAgentApi;
+}
+/** What a custom-event renderer draws from: the latest value of its event, and the agent. */
+export interface CustomRendererProps<Value = unknown> {
+    name: string;
+    value: Value;
+    /** Every value the event has had under this key, oldest first. */
+    history: readonly Value[];
+    agent: CalliopeAgentApi;
+}
+/** What an interrupt renderer draws from: the open interrupt and how to answer it. */
+export interface InterruptRendererProps {
+    interrupt: AgUiInterrupt;
+    /** Answers it; the run resumes once every open interrupt has an answer. */
+    resolve: (payload?: unknown) => void;
+    cancel: () => void;
+    agent: CalliopeAgentApi;
+}
+export interface StateRendererProps<State = unknown> {
+    state: State;
+    setState: (state: State) => void;
+    agent: CalliopeAgentApi;
+}
+/**
+ * Generative UI: host components for what the agent emits. A tool call by
+ * name (the agent's backend tools as well as the browser's), an AG-UI
+ * `CUSTOM` event by name (drawn where it arrived; an event carrying an `id`
+ * in its value replaces its earlier values in place, so progress updates
+ * one card), an interrupt by reason, and the shared state.
+ */
+export interface AgentRenderers {
+    tools?: Readonly<Record<string, React.ComponentType<ToolRendererProps<any>>>>;
+    custom?: Readonly<Record<string, React.ComponentType<CustomRendererProps<any>>>>;
+    interrupts?: Readonly<Record<string, React.ComponentType<InterruptRendererProps>>>;
+    /** Draws the shared state above the conversation. */
+    state?: React.ComponentType<StateRendererProps<any>>;
+}
+/** Several registries as one; a later one wins a name. */
+export declare function mergeRenderers(...registries: (AgentRenderers | undefined)[]): AgentRenderers;
+/** A tool's result as a renderer reads it. */
+export declare function parseResult(call: ChatToolCall): unknown;

package/dist/agent/renderers.js

@@ -0,0 +1,27 @@
+import { parseToolCallArgs } from "../chat/model.js";
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/** Several registries as one; a later one wins a name. */
+export function mergeRenderers(...registries) {
+    const merged = {
+        tools: {},
+        custom: {},
+        interrupts: {},
+    };
+    for (const r of registries) {
+        if (!r)
+            continue;
+        merged.tools = { ...merged.tools, ...r.tools };
+        merged.custom = { ...merged.custom, ...r.custom };
+        merged.interrupts = { ...merged.interrupts, ...r.interrupts };
+        if (r.state)
+            merged.state = r.state;
+    }
+    return merged;
+}
+/** A tool's result as a renderer reads it. */
+export function parseResult(call) {
+    if (call.result === undefined)
+        return undefined;
+    const parsed = parseToolCallArgs(call.result);
+    return parsed === undefined ? call.result : parsed;
+}

package/dist/agent/surface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An open state that is controlled (`open`), remembered per person in this
+ * browser (`persistKey`), or held here. The server renders `defaultOpen`; the
+ * client applies the saved state after hydration, without a mismatch, and a
+ * change in one tab reaches the others.
+ */
+export declare function useOpenState({ open, defaultOpen, onOpenChange, persistKey, }: {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    persistKey?: string;
+}): readonly [boolean, (open: boolean) => void];
+/** A shortcut as given: "mod+/" (Cmd on a Mac, Ctrl elsewhere) or a single key ("]"). */
+export interface ParsedShortcut {
+    mod: boolean;
+    key: string;
+}
+export declare function parseShortcut(shortcut: string): ParsedShortcut;
+/** The shortcut as people read it on this machine ("⌘/", "Ctrl+/"). */
+export declare function shortcutLabel(shortcut: string): string;
+/** The shortcut in `aria-keyshortcuts` form. */
+export declare function shortcutAria(shortcut: string): string;
+/**
+ * Calls `onPress` on the shortcut, anywhere in the page. A modified shortcut
+ * works while typing (the assistant opens from the middle of a form); a bare
+ * key does not, and neither works while a modal dialog holds the keyboard.
+ */
+export declare function useShortcut(shortcut: string | false | undefined, onPress: () => void): void;
+/** Whether a media query matches; the server and the first render say `serverValue`. */
+export declare function useMediaQuery(query: string, serverValue?: boolean): boolean;

package/dist/agent/surface.js

@@ -0,0 +1,90 @@
+"use client";
+import * as React from "react";
+import { readLocal, subscribeLocal, writeLocal } from "../lib/local-store.js";
+/**
+ * An open state that is controlled (`open`), remembered per person in this
+ * browser (`persistKey`), or held here. The server renders `defaultOpen`; the
+ * client applies the saved state after hydration, without a mismatch, and a
+ * change in one tab reaches the others.
+ */
+export function useOpenState({ open, defaultOpen = false, onOpenChange, persistKey, }) {
+    const [own, setOwn] = React.useState(defaultOpen);
+    const saved = React.useSyncExternalStore(subscribeLocal, () => (persistKey ? readLocal(persistKey) : null), () => null);
+    const current = open ?? (persistKey && saved !== null ? saved === "1" : persistKey ? defaultOpen : own);
+    const set = React.useCallback((next) => {
+        if (open === undefined) {
+            if (persistKey)
+                writeLocal(persistKey, next ? "1" : "0");
+            else
+                setOwn(next);
+        }
+        onOpenChange?.(next);
+    }, [open, persistKey, onOpenChange]);
+    return [current, set];
+}
+export function parseShortcut(shortcut) {
+    const mod = shortcut.toLowerCase().startsWith("mod+");
+    return { mod, key: mod ? shortcut.slice(4) : shortcut };
+}
+const isMac = () => typeof navigator !== "undefined" && /mac|iphone|ipad/i.test(navigator.platform || "");
+/** The shortcut as people read it on this machine ("⌘/", "Ctrl+/"). */
+export function shortcutLabel(shortcut) {
+    const { mod, key } = parseShortcut(shortcut);
+    if (!mod)
+        return key;
+    return isMac() ? `⌘${key}` : `Ctrl+${key}`;
+}
+/** The shortcut in `aria-keyshortcuts` form. */
+export function shortcutAria(shortcut) {
+    const { mod, key } = parseShortcut(shortcut);
+    return mod ? `Meta+${key} Control+${key}` : key;
+}
+function typing(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName);
+}
+/**
+ * Calls `onPress` on the shortcut, anywhere in the page. A modified shortcut
+ * works while typing (the assistant opens from the middle of a form); a bare
+ * key does not, and neither works while a modal dialog holds the keyboard.
+ */
+export function useShortcut(shortcut, onPress) {
+    const latest = React.useRef(onPress);
+    React.useEffect(() => {
+        latest.current = onPress;
+    });
+    React.useEffect(() => {
+        if (!shortcut)
+            return;
+        const { mod, key } = parseShortcut(shortcut);
+        const onKey = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.altKey)
+                return;
+            if (event.key !== key)
+                return;
+            const modified = event.metaKey || event.ctrlKey;
+            if (mod !== modified)
+                return;
+            if (!mod && typing(event.target))
+                return;
+            const target = event.target instanceof HTMLElement ? event.target : null;
+            if (target?.closest("[aria-modal='true'], [role='alertdialog']"))
+                return;
+            event.preventDefault();
+            latest.current();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [shortcut]);
+}
+/** Whether a media query matches; the server and the first render say `serverValue`. */
+export function useMediaQuery(query, serverValue = true) {
+    return React.useSyncExternalStore((onChange) => {
+        if (typeof window.matchMedia !== "function")
+            return () => { };
+        const list = window.matchMedia(query);
+        list.addEventListener("change", onChange);
+        return () => list.removeEventListener("change", onChange);
+    }, () => typeof window.matchMedia === "function" ? window.matchMedia(query).matches : serverValue, () => serverValue);
+}