@parlor/client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cychien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @parlor/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser side of a Parlor app: the action client, and React hooks that read and write through actions and refresh when anyone, including an agent, changes the data.
+
+```sh
+pnpm add @parlor/client @tanstack/react-query @tanstack/react-router react react-dom
+```
+
+```tsx
+import { createActionClient } from "@parlor/client";
+import { useActionQuery } from "@parlor/client/react";
+
+export const client = createActionClient();
+
+export function Health() {
+  const status = useActionQuery("health" as never, {} as never);
+  return <p>{status.isSuccess ? "up" : "..."}</p>;
+}
+```
+
+`@parlor/client/router` gives TanStack Router loaders the same cache, so a page can load its data before it renders and links can preload it. Its `mount` starts the app, hydrating a page the server rendered.
+
+In an app, register the actions once in `src/parlor.d.ts` so names and inputs are typed. Docs: https://cychien.github.io/parlor/guides/pages-and-hooks/

package/dist/action-client.d.ts

@@ -0,0 +1,42 @@
+import { ActionError, type ActionInput, type ActionMap, type ActionOutput, type Tag } from "@parlor/core";
+export declare function generateClientId(): string;
+export type HeadersProvider = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+export interface ActionClientOptions {
+    readonly baseUrl?: string | undefined;
+    readonly basePath?: string | undefined;
+    readonly fetch?: typeof fetch | undefined;
+    readonly headers?: HeadersProvider | undefined;
+    readonly clientId?: string | undefined;
+}
+export interface CallOptions {
+    readonly signal?: AbortSignal | undefined;
+}
+export interface ActionEnvelope<T> {
+    readonly data: T;
+    readonly tags: readonly Tag[];
+    /** The sync cursor a read's data reflects, when the server tracks it. */
+    readonly cursor?: string | undefined;
+}
+export interface ActionClient<T extends ActionMap> {
+    readonly clientId: string;
+    readonly basePath: string;
+    call<K extends keyof T & string>(name: K, input: ActionInput<T[K]>, options?: CallOptions): Promise<ActionOutput<T[K]>>;
+    invoke<K extends keyof T & string>(name: K, input: ActionInput<T[K]>, options?: CallOptions): Promise<ActionEnvelope<ActionOutput<T[K]>>>;
+    request(path: string, init?: RequestInit): Promise<Response>;
+}
+export declare function toActionError(response: Response, options?: {
+    readonly missingIsNotFound?: boolean;
+}): Promise<ActionError>;
+export declare function invokeAt<T extends ActionMap, K extends keyof T & string>(request: ActionClient<ActionMap>["request"], path: string, input: ActionInput<T[K]>, options?: CallOptions & {
+    readonly missingIsNotFound?: boolean;
+}): Promise<ActionEnvelope<ActionOutput<T[K]>>>;
+export declare function resolveServerOrigin(): string;
+/**
+ * The one name of this app's backend on every surface: the page's own origin when it is
+ * served over http(s) and is not a shell's webview origin, else the shell's `server.url`.
+ * `parlor dev` running several targets names the web target's origin for all of them.
+ * Statements are signed for it and the host is paired with it.
+ */
+export declare function appOrigin(serverUrl?: string, injected?: string): string;
+export declare function createActionClient<T extends ActionMap>(options?: ActionClientOptions): ActionClient<T>;
+//# sourceMappingURL=action-client.d.ts.map

package/dist/action-client.d.ts.map

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

package/dist/action-client.js

@@ -0,0 +1,92 @@
+import { ActionError, SHELL_ORIGINS, } from "@parlor/core";
+const DEFAULT_BASE_PATH = "/_parlor";
+const SOURCE_HEADER = "x-parlor-source";
+const CLIENT_HEADER = "x-parlor-client";
+function injectedServerUrl() {
+    const env = import.meta.env;
+    return env?.PARLOR_SERVER_URL ?? "";
+}
+export function generateClientId() {
+    return globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2);
+}
+async function resolveHeaders(provider, clientId, extra) {
+    const headers = new Headers(typeof provider === "function" ? await provider() : provider);
+    new Headers(extra).forEach((value, key) => headers.set(key, value));
+    headers.set(SOURCE_HEADER, "ui");
+    headers.set(CLIENT_HEADER, clientId);
+    return headers;
+}
+export async function toActionError(response, options = {}) {
+    const body = await response.json().catch(() => undefined);
+    if (ActionError.isBody(body))
+        return ActionError.fromBody(body);
+    const code = options.missingIsNotFound && response.status === 404 ? "not_found" : "internal";
+    return new ActionError(code, `Action request failed with HTTP ${response.status}`);
+}
+export async function invokeAt(request, path, input, options = {}) {
+    const response = await request(path, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input ?? {}),
+        signal: options.signal ?? null,
+    });
+    if (!response.ok) {
+        throw await toActionError(response, options.missingIsNotFound ? { missingIsNotFound: true } : {});
+    }
+    const body = (await response.json());
+    return {
+        data: body.data,
+        tags: body.tags ?? [],
+        ...(typeof body.cursor === "string" ? { cursor: body.cursor } : {}),
+    };
+}
+export function resolveServerOrigin() {
+    return injectedServerUrl() || globalThis.location?.origin || "";
+}
+function injectedAppOrigin() {
+    const env = import.meta.env;
+    return env?.PARLOR_APP_ORIGIN ?? "";
+}
+/**
+ * The one name of this app's backend on every surface: the page's own origin when it is
+ * served over http(s) and is not a shell's webview origin, else the shell's `server.url`.
+ * `parlor dev` running several targets names the web target's origin for all of them.
+ * Statements are signed for it and the host is paired with it.
+ */
+export function appOrigin(serverUrl = resolveServerOrigin(), injected = injectedAppOrigin()) {
+    if (injected)
+        return new URL(injected).origin;
+    const page = globalThis.location?.origin ?? "";
+    if (/^https?:\/\//.test(page) && !SHELL_ORIGINS.includes(page))
+        return page;
+    try {
+        return new URL(serverUrl).origin;
+    }
+    catch {
+        return serverUrl;
+    }
+}
+export function createActionClient(options = {}) {
+    const { baseUrl = injectedServerUrl(), basePath = DEFAULT_BASE_PATH, headers, } = options;
+    // Drawn on first use: workerd allows no random values while a module loads.
+    let clientId = options.clientId;
+    const ownId = () => (clientId ??= generateClientId());
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const request = async (path, init = {}) => fetchImpl(`${baseUrl}${path}`, {
+        ...init,
+        headers: await resolveHeaders(headers, ownId(), init.headers),
+    });
+    const invoke = async (name, input, callOptions = {}) => {
+        return invokeAt(request, `${basePath}/actions/${name}`, input, callOptions);
+    };
+    return {
+        get clientId() {
+            return ownId();
+        },
+        basePath,
+        request,
+        invoke,
+        call: async (name, input, callOptions) => (await invoke(name, input, callOptions)).data,
+    };
+}
+//# sourceMappingURL=action-client.js.map

package/dist/action-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-client.js","sourceRoot":"","sources":["../src/action-client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EAIX,aAAa,GAEd,MAAM,cAAc,CAAC;AAEtB,MAAM,iBAAiB,GAAG,UAAU,CAAC;AACrC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AACxC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAExC,SAAS,iBAAiB;IACxB,MAAM,GAAG,GAAI,OAAO,IAAiD,CAAC,GAAG,CAAC;IAC1E,OAAO,GAAG,EAAE,iBAAiB,IAAI,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAuCD,KAAK,UAAU,cAAc,CAC3B,QAAqC,EACrC,QAAgB,EAChB,KAAmB;IAEnB,MAAM,OAAO,GAAG,IAAI,OAAO,CACzB,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAC7D,CAAC;IACF,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAkB,EAClB,OAAO,GAA6C,EAAE;IAEtD,MAAM,IAAI,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnE,IAAI,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,IAAI,GACR,OAAO,CAAC,iBAAiB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC;IAClF,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,mCAAmC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAA2C,EAC3C,IAAY,EACZ,KAAwB,EACxB,OAAO,GAA2D,EAAE;IAEpE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE;QACnC,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;KAC/B,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,MAAM,aAAa,CACvB,QAAQ,EACR,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAC7D,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAIlC,CAAC;IACF,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,GAAG,CAAC,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,iBAAiB,EAAE,IAAI,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,iBAAiB;IACxB,MAAM,GAAG,GAAI,OAAO,IAAiD,CAAC,GAAG,CAAC;IAC1E,OAAO,GAAG,EAAE,iBAAiB,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,SAAS,GAAW,mBAAmB,EAAE,EACzC,QAAQ,GAAW,iBAAiB,EAAE;IAEtC,IAAI,QAAQ;QAAE,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IAC/C,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5E,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,OAAO,GAAwB,EAAE;IAEjC,MAAM,EACJ,OAAO,GAAG,iBAAiB,EAAE,EAC7B,QAAQ,GAAG,iBAAiB,EAC5B,OAAO,GACR,GAAG,OAAO,CAAC;IACZ,4EAA4E;IAC5E,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAChC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,CAAC,QAAQ,KAAK,gBAAgB,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAEpD,MAAM,OAAO,GAAG,KAAK,EAAE,IAAY,EAAE,IAAI,GAAgB,EAAE,EAAE,EAAE,CAC7D,SAAS,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE;QAC7B,GAAG,IAAI;QACP,OAAO,EAAE,MAAM,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC;KAC9D,CAAC,CAAC;IAEL,MAAM,MAAM,GAAG,KAAK,EAClB,IAAO,EACP,KAAwB,EACxB,WAAW,GAAgB,EAAE,EACgB,EAAE;QAC/C,OAAO,QAAQ,CAAO,OAAO,EAAE,GAAG,QAAQ,YAAY,IAAI,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IACpF,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,QAAQ;YACV,OAAO,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,QAAQ;QACR,OAAO;QACP,MAAM;QACN,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CACvC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI;KAChD,CAAC;AACJ,CAAC","sourcesContent":["import {\n  ActionError,\n  type ActionInput,\n  type ActionMap,\n  type ActionOutput,\n  SHELL_ORIGINS,\n  type Tag,\n} from \"@parlor/core\";\n\nconst DEFAULT_BASE_PATH = \"/_parlor\";\nconst SOURCE_HEADER = \"x-parlor-source\";\nconst CLIENT_HEADER = \"x-parlor-client\";\n\nfunction injectedServerUrl(): string {\n  const env = (import.meta as { env?: { PARLOR_SERVER_URL?: string } }).env;\n  return env?.PARLOR_SERVER_URL ?? \"\";\n}\n\nexport function generateClientId(): string {\n  return globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2);\n}\n\nexport type HeadersProvider = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);\n\nexport interface ActionClientOptions {\n  readonly baseUrl?: string | undefined;\n  readonly basePath?: string | undefined;\n  readonly fetch?: typeof fetch | undefined;\n  readonly headers?: HeadersProvider | undefined;\n  readonly clientId?: string | undefined;\n}\n\nexport interface CallOptions {\n  readonly signal?: AbortSignal | undefined;\n}\n\nexport interface ActionEnvelope<T> {\n  readonly data: T;\n  readonly tags: readonly Tag[];\n  /** The sync cursor a read's data reflects, when the server tracks it. */\n  readonly cursor?: string | undefined;\n}\n\nexport interface ActionClient<T extends ActionMap> {\n  readonly clientId: string;\n  readonly basePath: string;\n  call<K extends keyof T & string>(\n    name: K,\n    input: ActionInput<T[K]>,\n    options?: CallOptions,\n  ): Promise<ActionOutput<T[K]>>;\n  invoke<K extends keyof T & string>(\n    name: K,\n    input: ActionInput<T[K]>,\n    options?: CallOptions,\n  ): Promise<ActionEnvelope<ActionOutput<T[K]>>>;\n  request(path: string, init?: RequestInit): Promise<Response>;\n}\n\nasync function resolveHeaders(\n  provider: HeadersProvider | undefined,\n  clientId: string,\n  extra?: HeadersInit,\n): Promise<Headers> {\n  const headers = new Headers(\n    typeof provider === \"function\" ? await provider() : provider,\n  );\n  new Headers(extra).forEach((value, key) => headers.set(key, value));\n  headers.set(SOURCE_HEADER, \"ui\");\n  headers.set(CLIENT_HEADER, clientId);\n  return headers;\n}\n\nexport async function toActionError(\n  response: Response,\n  options: { readonly missingIsNotFound?: boolean } = {},\n): Promise<ActionError> {\n  const body: unknown = await response.json().catch(() => undefined);\n  if (ActionError.isBody(body)) return ActionError.fromBody(body);\n  const code =\n    options.missingIsNotFound && response.status === 404 ? \"not_found\" : \"internal\";\n  return new ActionError(code, `Action request failed with HTTP ${response.status}`);\n}\n\nexport async function invokeAt<T extends ActionMap, K extends keyof T & string>(\n  request: ActionClient<ActionMap>[\"request\"],\n  path: string,\n  input: ActionInput<T[K]>,\n  options: CallOptions & { readonly missingIsNotFound?: boolean } = {},\n): Promise<ActionEnvelope<ActionOutput<T[K]>>> {\n  const response = await request(path, {\n    method: \"POST\",\n    headers: { \"content-type\": \"application/json\" },\n    body: JSON.stringify(input ?? {}),\n    signal: options.signal ?? null,\n  });\n  if (!response.ok) {\n    throw await toActionError(\n      response,\n      options.missingIsNotFound ? { missingIsNotFound: true } : {},\n    );\n  }\n  const body = (await response.json()) as {\n    data: ActionOutput<T[K]>;\n    tags?: Tag[];\n    cursor?: string;\n  };\n  return {\n    data: body.data,\n    tags: body.tags ?? [],\n    ...(typeof body.cursor === \"string\" ? { cursor: body.cursor } : {}),\n  };\n}\n\nexport function resolveServerOrigin(): string {\n  return injectedServerUrl() || globalThis.location?.origin || \"\";\n}\n\nfunction injectedAppOrigin(): string {\n  const env = (import.meta as { env?: { PARLOR_APP_ORIGIN?: string } }).env;\n  return env?.PARLOR_APP_ORIGIN ?? \"\";\n}\n\n/**\n * The one name of this app's backend on every surface: the page's own origin when it is\n * served over http(s) and is not a shell's webview origin, else the shell's `server.url`.\n * `parlor dev` running several targets names the web target's origin for all of them.\n * Statements are signed for it and the host is paired with it.\n */\nexport function appOrigin(\n  serverUrl: string = resolveServerOrigin(),\n  injected: string = injectedAppOrigin(),\n): string {\n  if (injected) return new URL(injected).origin;\n  const page = globalThis.location?.origin ?? \"\";\n  if (/^https?:\\/\\//.test(page) && !SHELL_ORIGINS.includes(page)) return page;\n  try {\n    return new URL(serverUrl).origin;\n  } catch {\n    return serverUrl;\n  }\n}\n\nexport function createActionClient<T extends ActionMap>(\n  options: ActionClientOptions = {},\n): ActionClient<T> {\n  const {\n    baseUrl = injectedServerUrl(),\n    basePath = DEFAULT_BASE_PATH,\n    headers,\n  } = options;\n  // Drawn on first use: workerd allows no random values while a module loads.\n  let clientId = options.clientId;\n  const ownId = () => (clientId ??= generateClientId());\n  const fetchImpl = options.fetch ?? globalThis.fetch;\n\n  const request = async (path: string, init: RequestInit = {}) =>\n    fetchImpl(`${baseUrl}${path}`, {\n      ...init,\n      headers: await resolveHeaders(headers, ownId(), init.headers),\n    });\n\n  const invoke = async <K extends keyof T & string>(\n    name: K,\n    input: ActionInput<T[K]>,\n    callOptions: CallOptions = {},\n  ): Promise<ActionEnvelope<ActionOutput<T[K]>>> => {\n    return invokeAt<T, K>(request, `${basePath}/actions/${name}`, input, callOptions);\n  };\n\n  return {\n    get clientId() {\n      return ownId();\n    },\n    basePath,\n    request,\n    invoke,\n    call: async (name, input, callOptions) =>\n      (await invoke(name, input, callOptions)).data,\n  };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type ActionClient, appOrigin, type ActionClientOptions, type ActionEnvelope, type CallOptions, createActionClient, generateClientId, type HeadersProvider, } from "./action-client.js";
+export { type AgentViewBinding, type AgentViewDefinition, type AnyAgentView, defineAgentView, type WritableField, } from "@parlor/agent-ui";
+export { ACTION_QUERY_PREFIX, actionQueryKey } from "./query-keys.js";
+export { createPluginClient, type PluginClient } from "./plugin-client.js";
+export type { AccountDevice, DeviceLinker, DeviceSource, FrameworkAuth, HostAuthorizer, PendingLink, SessionDevice, SessionSnapshot, SessionSource, SessionUser, } from "./session.js";
+export { LinkOnComputer } from "./session.js";
+export type { Register, RegisteredActions } from "./register.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,SAAS,EACT,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC3E,YAAY,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { appOrigin, createActionClient, generateClientId, } from "./action-client.js";
+export { defineAgentView, } from "@parlor/agent-ui";
+export { ACTION_QUERY_PREFIX, actionQueryKey } from "./query-keys.js";
+export { createPluginClient } from "./plugin-client.js";
+export { LinkOnComputer } from "./session.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,SAAS,EAIT,kBAAkB,EAClB,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,eAAe,GAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAqB,MAAM,oBAAoB,CAAC;AAa3E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC","sourcesContent":["export {\n  type ActionClient,\n  appOrigin,\n  type ActionClientOptions,\n  type ActionEnvelope,\n  type CallOptions,\n  createActionClient,\n  generateClientId,\n  type HeadersProvider,\n} from \"./action-client.js\";\nexport {\n  type AgentViewBinding,\n  type AgentViewDefinition,\n  type AnyAgentView,\n  defineAgentView,\n  type WritableField,\n} from \"@parlor/agent-ui\";\nexport { ACTION_QUERY_PREFIX, actionQueryKey } from \"./query-keys.js\";\nexport { createPluginClient, type PluginClient } from \"./plugin-client.js\";\nexport type {\n  AccountDevice,\n  DeviceLinker,\n  DeviceSource,\n  FrameworkAuth,\n  HostAuthorizer,\n  PendingLink,\n  SessionDevice,\n  SessionSnapshot,\n  SessionSource,\n  SessionUser,\n} from \"./session.js\";\nexport { LinkOnComputer } from \"./session.js\";\nexport type { Register, RegisteredActions } from \"./register.js\";\n"]}

package/dist/plugin-client.d.ts

@@ -0,0 +1,11 @@
+import type { ActionMap } from "@parlor/core";
+import { type ActionClient } from "./action-client.js";
+/** A plugin's actions at `/_parlor/<plugin>/actions/<name>`, typed by its registry. */
+export type PluginClient<T extends ActionMap> = Pick<ActionClient<T>, "call" | "invoke">;
+/**
+ * Reuses the app client's base URL, headers provider (the session) and client id, so a
+ * plugin's actions travel exactly like the app's. A server without the plugin answers
+ * `not_found`.
+ */
+export declare function createPluginClient<T extends ActionMap>(client: Pick<ActionClient<ActionMap>, "basePath" | "clientId" | "request">, plugin: string): PluginClient<T>;
+//# sourceMappingURL=plugin-client.d.ts.map

package/dist/plugin-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-client.d.ts","sourceRoot":"","sources":["../src/plugin-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,KAAK,YAAY,EAAY,MAAM,oBAAoB,CAAC;AAEjE,uFAAuF;AACvF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAEzF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,SAAS,EACpD,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC,EAC1E,MAAM,EAAE,MAAM,GACb,YAAY,CAAC,CAAC,CAAC,CAYjB"}

package/dist/plugin-client.js

@@ -0,0 +1,14 @@
+import { invokeAt } from "./action-client.js";
+/**
+ * Reuses the app client's base URL, headers provider (the session) and client id, so a
+ * plugin's actions travel exactly like the app's. A server without the plugin answers
+ * `not_found`.
+ */
+export function createPluginClient(client, plugin) {
+    const invoke = (name, input, options) => invokeAt(client.request, `${client.basePath}/${plugin}/actions/${name}`, input, { ...options, missingIsNotFound: true });
+    return {
+        invoke,
+        call: async (name, input, options) => (await invoke(name, input, options)).data,
+    };
+}
+//# sourceMappingURL=plugin-client.js.map

package/dist/plugin-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-client.js","sourceRoot":"","sources":["../src/plugin-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAKjE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA0E,EAC1E,MAAc;IAEd,MAAM,MAAM,GAA8B,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CACjE,QAAQ,CACN,MAAM,CAAC,OAAO,EACd,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,YAAY,IAAI,EAAE,EAC9C,KAAK,EACL,EAAE,GAAG,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,CACxC,CAAC;IACJ,OAAO;QACL,MAAM;QACN,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI;KAChF,CAAC;AACJ,CAAC","sourcesContent":["import type { ActionMap } from \"@parlor/core\";\n\nimport { type ActionClient, invokeAt } from \"./action-client.js\";\n\n/** A plugin's actions at `/_parlor/<plugin>/actions/<name>`, typed by its registry. */\nexport type PluginClient<T extends ActionMap> = Pick<ActionClient<T>, \"call\" | \"invoke\">;\n\n/**\n * Reuses the app client's base URL, headers provider (the session) and client id, so a\n * plugin's actions travel exactly like the app's. A server without the plugin answers\n * `not_found`.\n */\nexport function createPluginClient<T extends ActionMap>(\n  client: Pick<ActionClient<ActionMap>, \"basePath\" | \"clientId\" | \"request\">,\n  plugin: string,\n): PluginClient<T> {\n  const invoke: PluginClient<T>[\"invoke\"] = (name, input, options) =>\n    invokeAt<T, typeof name>(\n      client.request,\n      `${client.basePath}/${plugin}/actions/${name}`,\n      input,\n      { ...options, missingIsNotFound: true },\n    );\n  return {\n    invoke,\n    call: async (name, input, options) => (await invoke(name, input, options)).data,\n  };\n}\n"]}

package/dist/query-keys.d.ts

@@ -0,0 +1,3 @@
+export declare const ACTION_QUERY_PREFIX: readonly ["_parlor", "action"];
+export declare function actionQueryKey(name: string, input: unknown): readonly ["_parlor", "action", string, {}];
+//# sourceMappingURL=query-keys.d.ts.map

package/dist/query-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-keys.d.ts","sourceRoot":"","sources":["../src/query-keys.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,YAAI,SAAS,EAAE,QAAQ,CAAU,CAAC;AAElE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,8CAE1D"}

package/dist/query-keys.js

@@ -0,0 +1,5 @@
+export const ACTION_QUERY_PREFIX = ["_parlor", "action"];
+export function actionQueryKey(name, input) {
+    return [...ACTION_QUERY_PREFIX, name, input ?? {}];
+}
+//# sourceMappingURL=query-keys.js.map

package/dist/query-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-keys.js","sourceRoot":"","sources":["../src/query-keys.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAC;AAElE,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAc;IACzD,OAAO,CAAC,GAAG,mBAAmB,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAU,CAAC;AAC9D,CAAC","sourcesContent":["export const ACTION_QUERY_PREFIX = [\"_parlor\", \"action\"] as const;\n\nexport function actionQueryKey(name: string, input: unknown) {\n  return [...ACTION_QUERY_PREFIX, name, input ?? {}] as const;\n}\n"]}

package/dist/react/action-query.d.ts

@@ -0,0 +1,26 @@
+import type { ActionError, ActionInput, ActionOutput } from "@parlor/core";
+import { type QueryClient } from "@tanstack/react-query";
+import type { ActionClient } from "../action-client.js";
+import type { RegisteredActions } from "../register.js";
+type Actions = RegisteredActions;
+type Name = keyof Actions & string;
+/** What reading an action outside a component needs; a router made by `createParlorRouter` passes it to every loader. */
+export interface ActionQueryContext {
+    readonly client: ActionClient<RegisteredActions>;
+    readonly queryClient: QueryClient;
+}
+/**
+ * The query `useActionQuery(name, input)` runs, for `queryClient.prefetchQuery`, `useQueries`
+ * and the like. It reads the same cache entry and records the same read tags, so sync keeps it fresh.
+ */
+export declare function actionQueryOptions<K extends Name>({ client, queryClient }: ActionQueryContext, name: K, input: ActionInput<Actions[K]>): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, ActionError, unknown, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly unknown[], never>;
+} & import("@tanstack/react-query").QueryKeyWithDataTag<readonly unknown[], unknown, ActionError>;
+/**
+ * The action's cached data, fetched first when there is none or when a write it reads has
+ * invalidated it since. A route `loader` awaits it so the page renders with its data, and
+ * `useActionSuspenseQuery` with the same name and input reads it and keeps it fresh.
+ */
+export declare function ensureActionQueryData<K extends Name>(context: ActionQueryContext, name: K, input: ActionInput<Actions[K]>): Promise<ActionOutput<Actions[K]>>;
+export {};
+//# sourceMappingURL=action-query.d.ts.map

package/dist/react/action-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-query.d.ts","sourceRoot":"","sources":["../../src/react/action-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAW,KAAK,WAAW,EAAgB,MAAM,uBAAuB,CAAC;AAEhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAIxD,KAAK,OAAO,GAAG,iBAAiB,CAAC;AACjC,KAAK,IAAI,GAAG,MAAM,OAAO,GAAG,MAAM,CAAC;AAEnC,yHAAyH;AACzH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,IAAI,EAC/C,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,kBAAkB,EAC3C,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;;kGAc/B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,IAAI,EAClD,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAKnC"}

package/dist/react/action-query.js

@@ -0,0 +1,33 @@
+import { hashKey, queryOptions } from "@tanstack/react-query";
+import { actionQueryKey } from "../query-keys.js";
+import { actionRetry } from "./retry.js";
+import { readTagsOf } from "./sync.js";
+/** Sync refetches what a write makes out of date, so action data stays fresh until then. */
+const freshUntilInvalidated = ({ state, }) => (state.data === undefined || state.isInvalidated ? 0 : "static");
+/**
+ * The query `useActionQuery(name, input)` runs, for `queryClient.prefetchQuery`, `useQueries`
+ * and the like. It reads the same cache entry and records the same read tags, so sync keeps it fresh.
+ */
+export function actionQueryOptions({ client, queryClient }, name, input) {
+    const queryKey = actionQueryKey(name, input);
+    return queryOptions({
+        queryKey,
+        queryFn: ({ signal, client: cache }) => readTagsOf(cache).read(hashKey(queryKey), () => client.invoke(name, input, { signal })),
+        retry: actionRetry(queryClient.getDefaultOptions().queries?.retry),
+        ...(queryClient.getDefaultOptions().queries?.staleTime === undefined
+            ? { staleTime: freshUntilInvalidated }
+            : {}),
+    });
+}
+/**
+ * The action's cached data, fetched first when there is none or when a write it reads has
+ * invalidated it since. A route `loader` awaits it so the page renders with its data, and
+ * `useActionSuspenseQuery` with the same name and input reads it and keeps it fresh.
+ */
+export function ensureActionQueryData(context, name, input) {
+    return context.queryClient.query({
+        ...actionQueryOptions(context, name, input),
+        staleTime: freshUntilInvalidated,
+    });
+}
+//# sourceMappingURL=action-query.js.map

package/dist/react/action-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-query.js","sourceRoot":"","sources":["../../src/react/action-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAoB,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGhF,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAWvC,4FAA4F;AAC5F,MAAM,qBAAqB,GAAG,CAAC,EAC7B,KAAK,GAGN,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,EAAE,MAAM,EAAE,WAAW,EAAsB,EAC3C,IAAO,EACP,KAA8B;IAE9B,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7C,OAAO,YAAY,CAAkE;QACnF,QAAQ;QACR,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CACrC,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAC7C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,CACvC;QACH,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,iBAAiB,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC;QAClE,GAAG,CAAC,WAAW,CAAC,iBAAiB,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS;YAClE,CAAC,CAAC,EAAE,SAAS,EAAE,qBAAqB,EAAE;YACtC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAA2B,EAC3B,IAAO,EACP,KAA8B;IAE9B,OAAO,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;QAC/B,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC;QAC3C,SAAS,EAAE,qBAAqB;KACjC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ActionError, ActionInput, ActionOutput } from \"@parlor/core\";\nimport { hashKey, type QueryClient, queryOptions } from \"@tanstack/react-query\";\n\nimport type { ActionClient } from \"../action-client.js\";\nimport { actionQueryKey } from \"../query-keys.js\";\nimport type { RegisteredActions } from \"../register.js\";\nimport { actionRetry } from \"./retry.js\";\nimport { readTagsOf } from \"./sync.js\";\n\ntype Actions = RegisteredActions;\ntype Name = keyof Actions & string;\n\n/** What reading an action outside a component needs; a router made by `createParlorRouter` passes it to every loader. */\nexport interface ActionQueryContext {\n  readonly client: ActionClient<RegisteredActions>;\n  readonly queryClient: QueryClient;\n}\n\n/** Sync refetches what a write makes out of date, so action data stays fresh until then. */\nconst freshUntilInvalidated = ({\n  state,\n}: {\n  readonly state: { readonly data: unknown; readonly isInvalidated: boolean };\n}) => (state.data === undefined || state.isInvalidated ? 0 : \"static\");\n\n/**\n * The query `useActionQuery(name, input)` runs, for `queryClient.prefetchQuery`, `useQueries`\n * and the like. It reads the same cache entry and records the same read tags, so sync keeps it fresh.\n */\nexport function actionQueryOptions<K extends Name>(\n  { client, queryClient }: ActionQueryContext,\n  name: K,\n  input: ActionInput<Actions[K]>,\n) {\n  const queryKey = actionQueryKey(name, input);\n  return queryOptions<ActionOutput<Actions[K]>, ActionError, ActionOutput<Actions[K]>>({\n    queryKey,\n    queryFn: ({ signal, client: cache }) =>\n      readTagsOf(cache).read(hashKey(queryKey), () =>\n        client.invoke(name, input, { signal }),\n      ),\n    retry: actionRetry(queryClient.getDefaultOptions().queries?.retry),\n    ...(queryClient.getDefaultOptions().queries?.staleTime === undefined\n      ? { staleTime: freshUntilInvalidated }\n      : {}),\n  });\n}\n\n/**\n * The action's cached data, fetched first when there is none or when a write it reads has\n * invalidated it since. A route `loader` awaits it so the page renders with its data, and\n * `useActionSuspenseQuery` with the same name and input reads it and keeps it fresh.\n */\nexport function ensureActionQueryData<K extends Name>(\n  context: ActionQueryContext,\n  name: K,\n  input: ActionInput<Actions[K]>,\n): Promise<ActionOutput<Actions[K]>> {\n  return context.queryClient.query({\n    ...actionQueryOptions(context, name, input),\n    staleTime: freshUntilInvalidated,\n  });\n}\n"]}

package/dist/react/agent-ui/activity-state.d.ts

@@ -0,0 +1,20 @@
+import type { AgentOrigin, UiErrorCode } from "@parlor/agent-ui";
+import type { AgentActivity, AgentActivityKind } from "@parlor/agent-ui/client";
+export type AgentActivityState = {
+    readonly status: "idle";
+} | {
+    readonly status: "busy";
+    readonly op: AgentActivityKind;
+    readonly origin: AgentOrigin;
+} | {
+    readonly status: "done";
+    readonly op: AgentActivityKind;
+    readonly origin: AgentOrigin;
+} | {
+    readonly status: "refused";
+    readonly op: AgentActivityKind;
+    readonly origin: AgentOrigin;
+    readonly code: UiErrorCode;
+};
+export declare function deriveActivityState({ busy, last }: AgentActivity, faded: AgentActivity["last"]): AgentActivityState;
+//# sourceMappingURL=activity-state.d.ts.map

package/dist/react/agent-ui/activity-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-state.d.ts","sourceRoot":"","sources":["../../../src/react/agent-ui/activity-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEhF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B,CAAC;AAEN,wBAAgB,mBAAmB,CACjC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,aAAa,EAC7B,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAC3B,kBAAkB,CASpB"}

package/dist/react/agent-ui/activity-state.js

@@ -0,0 +1,14 @@
+export function deriveActivityState({ busy, last }, faded) {
+    if (!last)
+        return { status: "idle" };
+    const { op, origin, outcome } = last;
+    if (busy)
+        return { status: "busy", op, origin };
+    if (last === faded)
+        return { status: "idle" };
+    if (outcome?.status === "refused") {
+        return { status: "refused", op, origin, code: outcome.code };
+    }
+    return { status: "done", op, origin };
+}
+//# sourceMappingURL=activity-state.js.map

package/dist/react/agent-ui/activity-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-state.js","sourceRoot":"","sources":["../../../src/react/agent-ui/activity-state.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,mBAAmB,CACjC,EAAE,IAAI,EAAE,IAAI,EAAiB,EAC7B,KAA4B;IAE5B,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACrC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACrC,IAAI,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IAChD,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC9C,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import type { AgentOrigin, UiErrorCode } from \"@parlor/agent-ui\";\nimport type { AgentActivity, AgentActivityKind } from \"@parlor/agent-ui/client\";\n\nexport type AgentActivityState =\n  | { readonly status: \"idle\" }\n  | {\n      readonly status: \"busy\";\n      readonly op: AgentActivityKind;\n      readonly origin: AgentOrigin;\n    }\n  | {\n      readonly status: \"done\";\n      readonly op: AgentActivityKind;\n      readonly origin: AgentOrigin;\n    }\n  | {\n      readonly status: \"refused\";\n      readonly op: AgentActivityKind;\n      readonly origin: AgentOrigin;\n      readonly code: UiErrorCode;\n    };\n\nexport function deriveActivityState(\n  { busy, last }: AgentActivity,\n  faded: AgentActivity[\"last\"],\n): AgentActivityState {\n  if (!last) return { status: \"idle\" };\n  const { op, origin, outcome } = last;\n  if (busy) return { status: \"busy\", op, origin };\n  if (last === faded) return { status: \"idle\" };\n  if (outcome?.status === \"refused\") {\n    return { status: \"refused\", op, origin, code: outcome.code };\n  }\n  return { status: \"done\", op, origin };\n}\n"]}

package/dist/react/agent-ui/chat-activity.d.ts

@@ -0,0 +1,13 @@
+import { type ComponentProps, type ReactNode } from "react";
+import { type AgentActivityState } from "./activity-state.js";
+export interface ChatActivityProps extends Omit<ComponentProps<"span">, "children"> {
+    /** Milliseconds a finished event stays `done` or `refused` before it reads `idle`. */
+    readonly linger?: number;
+    readonly children: (state: AgentActivityState) => ReactNode;
+}
+/**
+ * A polite live region that says what an agent is doing on this screen. The app writes the
+ * words; style it through `[data-state]` and `[data-op]`.
+ */
+export declare function Activity({ linger, children, ...props }: ChatActivityProps): import("react").JSX.Element;
+//# sourceMappingURL=chat-activity.d.ts.map

package/dist/react/agent-ui/chat-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-activity.d.ts","sourceRoot":"","sources":["../../../src/react/agent-ui/chat-activity.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAEjF,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,qBAAqB,CAAC;AAiBnF,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IACjF,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,SAAS,CAAC;CAC7D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EACvB,MAA0B,EAC1B,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,iBAAiB,+BAanB"}

package/dist/react/agent-ui/chat-activity.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { deriveActivityState } from "./activity-state.js";
+import { useAgentActivity } from "./use-agent-activity.js";
+const DEFAULT_LINGER_MS = 2000;
+function useActivityState(lingerMs) {
+    const activity = useAgentActivity();
+    const [faded, setFaded] = useState();
+    const { busy, last } = activity;
+    useEffect(() => {
+        if (busy || !last)
+            return;
+        const timer = setTimeout(() => setFaded(last), lingerMs);
+        return () => clearTimeout(timer);
+    }, [busy, last, lingerMs]);
+    return deriveActivityState(activity, faded);
+}
+/**
+ * A polite live region that says what an agent is doing on this screen. The app writes the
+ * words; style it through `[data-state]` and `[data-op]`.
+ */
+export function Activity({ linger = DEFAULT_LINGER_MS, children, ...props }) {
+    const state = useActivityState(linger);
+    return (_jsx("span", { role: "status", "aria-live": "polite", ...props, "data-state": state.status, "data-op": state.status === "idle" ? undefined : state.op, children: children(state) }));
+}
+//# sourceMappingURL=chat-activity.js.map

package/dist/react/agent-ui/chat-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-activity.js","sourceRoot":"","sources":["../../../src/react/agent-ui/chat-activity.tsx"],"names":[],"mappings":";AACA,OAAO,EAAuC,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjF,OAAO,EAA2B,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,SAAS,gBAAgB,CAAC,QAAgB;IACxC,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,EAAyB,CAAC;IAC5D,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC;IAChC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QAC1B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;QACzD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3B,OAAO,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC9C,CAAC;AAQD;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,EACvB,MAAM,GAAG,iBAAiB,EAC1B,QAAQ,EACR,GAAG,KAAK,EACU;IAClB,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO,CACL,eACE,IAAI,EAAC,QAAQ,eACH,QAAQ,KACd,KAAK,gBACG,KAAK,CAAC,MAAM,aACf,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,YAEtD,QAAQ,CAAC,KAAK,CAAC,GACX,CACR,CAAC;AACJ,CAAC","sourcesContent":["import type { AgentActivity } from \"@parlor/agent-ui/client\";\nimport { type ComponentProps, type ReactNode, useEffect, useState } from \"react\";\n\nimport { type AgentActivityState, deriveActivityState } from \"./activity-state.js\";\nimport { useAgentActivity } from \"./use-agent-activity.js\";\n\nconst DEFAULT_LINGER_MS = 2000;\n\nfunction useActivityState(lingerMs: number): AgentActivityState {\n  const activity = useAgentActivity();\n  const [faded, setFaded] = useState<AgentActivity[\"last\"]>();\n  const { busy, last } = activity;\n  useEffect(() => {\n    if (busy || !last) return;\n    const timer = setTimeout(() => setFaded(last), lingerMs);\n    return () => clearTimeout(timer);\n  }, [busy, last, lingerMs]);\n  return deriveActivityState(activity, faded);\n}\n\nexport interface ChatActivityProps extends Omit<ComponentProps<\"span\">, \"children\"> {\n  /** Milliseconds a finished event stays `done` or `refused` before it reads `idle`. */\n  readonly linger?: number;\n  readonly children: (state: AgentActivityState) => ReactNode;\n}\n\n/**\n * A polite live region that says what an agent is doing on this screen. The app writes the\n * words; style it through `[data-state]` and `[data-op]`.\n */\nexport function Activity({\n  linger = DEFAULT_LINGER_MS,\n  children,\n  ...props\n}: ChatActivityProps) {\n  const state = useActivityState(linger);\n  return (\n    <span\n      role=\"status\"\n      aria-live=\"polite\"\n      {...props}\n      data-state={state.status}\n      data-op={state.status === \"idle\" ? undefined : state.op}\n    >\n      {children(state)}\n    </span>\n  );\n}\n"]}

package/dist/react/agent-ui/chat-confirm.d.ts

@@ -0,0 +1,28 @@
+import type { AgentConfirmation } from "@parlor/agent-ui/client";
+import { type ComponentProps, type ReactNode } from "react";
+export interface ChatConfirmationsProps extends Omit<ComponentProps<"div">, "children"> {
+    /** Shown while no agent request waits. */
+    readonly empty?: ReactNode;
+    readonly children: (confirmation: AgentConfirmation) => ReactNode;
+}
+/**
+ * Lists the agent requests waiting for this user, newest last. Rendering it is what tells
+ * the server this client can show a confirmation, so keep it mounted wherever the user can
+ * answer. `data-pending` carries the count while any wait. When the card holding focus goes
+ * away, focus moves to the next card, or to the list when none is left, so it never falls
+ * out of an enclosing dialog.
+ */
+export declare function Confirmations({ empty, children, ref, ...props }: ChatConfirmationsProps): import("react").JSX.Element;
+export interface ChatConfirmProps extends ComponentProps<"div"> {
+    readonly confirmation: AgentConfirmation;
+}
+/**
+ * One request as a labelled group. Escape inside it declines, and stops there so an
+ * enclosing dialog stays open. It never takes focus by itself, but it can hold it
+ * (`tabIndex` -1) so `Chat.Confirmations` can keep focus in the list.
+ */
+export declare function Confirm({ confirmation, onKeyDown, ref, ...props }: ChatConfirmProps): import("react").JSX.Element;
+export declare function ConfirmLabel(props: Omit<ComponentProps<"p">, "id">): import("react").JSX.Element;
+export declare function Approve({ onClick, ...props }: ComponentProps<"button">): import("react").JSX.Element;
+export declare function Decline({ onClick, ...props }: ComponentProps<"button">): import("react").JSX.Element;
+//# sourceMappingURL=chat-confirm.d.ts.map

package/dist/react/agent-ui/chat-confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-confirm.d.ts","sourceRoot":"","sources":["../../../src/react/agent-ui/chat-confirm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EACL,KAAK,cAAc,EAInB,KAAK,SAAS,EAQf,MAAM,OAAO,CAAC;AAkCf,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACrF,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,iBAAiB,KAAK,SAAS,CAAC;CACnE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,sBAAsB,+BAoExB;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC7D,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,+BA6CnF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,+BAGlE;AAED,wBAAgB,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,+BAYtE;AAED,wBAAgB,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,+BAYtE"}