@perspective-dev/viewer 5.0.0 → 5.2.0

package/dist/wasm/perspective-viewer.d.ts

@@ -1,6 +1,90 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * A table hosted by a `VirtualServerHandler`, as returned by
+ * `getHostedTables()`. A plain `string` is shorthand for `{ name }`.
+ */
+export interface VirtualHostedTable {
+    name: string;
+    index?: string;
+    limit?: number;
+}
+
+/**
+ * Handler interface that you implement to provide custom data sources.
+ *
+ * All methods will be called by the `VirtualServer` when handling protocol
+ * messages from Perspective clients. Methods can return values directly or
+ * return Promises for asynchronous operations (e.g., database queries).
+ * Optional methods fall back to defaults documented per-method.
+ */
+export interface VirtualServerHandler {
+    getHostedTables():
+    | (string | VirtualHostedTable)[]
+    | Promise<(string | VirtualHostedTable)[]>;
+    tableSchema(
+    tableId: string,
+    ): Record<string, ColumnType> | Promise<Record<string, ColumnType>>;
+    tableSize(tableId: string): number | Promise<number>;
+    tableMakeView(
+    tableId: string,
+    viewId: string,
+    config: ViewConfigUpdate,
+    ): void | Promise<void>;
+    viewDelete(viewId: string): void | Promise<void>;
+    viewGetData(
+    viewId: string,
+    config: ViewConfig,
+    schema: Record<string, ColumnType>,
+    viewport: ViewWindow,
+    dataSlice: VirtualDataSlice,
+    ): void | Promise<void>;
+
+    /** Defaults to `tableSchema(viewId)`. */
+    viewSchema?(
+    viewId: string,
+    config: ViewConfig,
+    ): Record<string, ColumnType> | Promise<Record<string, ColumnType>>;
+
+    /** Defaults to `tableSize(viewId)`. */
+    viewSize?(viewId: string): number | Promise<number>;
+
+    /** Defaults to the length of `tableSchema(tableId)`. */
+    tableColumnsSize?(tableId: string): number | Promise<number>;
+
+    /** Defaults to the length of `viewSchema(viewId, config)`. */
+    viewColumnSize?(
+    viewId: string,
+    config: ViewConfig,
+    ): number | Promise<number>;
+
+    /** Required when `getFeatures()` reports `expressions: true`. */
+    tableValidateExpression?(
+    tableId: string,
+    expression: string,
+    ): ColumnType | Promise<ColumnType>;
+
+    viewGetMinMax?(
+    viewId: string,
+    columnName: string,
+    config: ViewConfig,
+    ): { min: Scalar; max: Scalar } | Promise<{ min: Scalar; max: Scalar }>;
+
+    /** Defaults to no optional features. */
+    getFeatures?(): Features | Promise<Features>;
+
+    /** Defaults to port `0`. */
+    tableMakePort?(): number | Promise<number>;
+
+    makeTable?(
+    tableId: string,
+    data: string | Uint8Array,
+    ): void | Promise<void>;
+}
+
+
+
 import type {
     ColumnType,
     TableInitOptions,
@@ -11,28 +95,42 @@ import type {
     JoinOptions,
     UpdateOptions,
     DeleteOptions,
+    ViewConfig,
     ViewConfigUpdate,
     SystemInfo,
+    Scalar,
+    Features,
 } from "@perspective-dev/client";
 
 export type * from "../../src/ts/ts-rs/ViewerConfig.d.ts";
 export type * from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
+export type * from "../../src/ts/ts-rs/ViewerConfigInitial.d.ts";
 export type * from "../../src/ts/ts-rs/PluginStaticConfig.d.ts";
 export type * from "../../src/ts/ts-rs/WorkspaceConfig.d.ts";
 export type * from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
 export type * from "../../src/ts/ts-rs/ExportMethod.d.ts";
 export type * from "../../src/ts/ts-rs/PanelOptions.d.ts";
+export type * from "../../src/ts/ts-rs/RestoreOptions.d.ts";
 export type * from "../../src/ts/ts-rs/ClientOptions.d.ts";
 export type * from "../../src/ts/ts-rs/ExportOptions.d.ts";
 export type * from "../../src/ts/ts-rs/GetTableOptions.d.ts";
 export type * from "../../src/ts/ts-rs/GetClientOptions.d.ts";
+export type * from "../../src/ts/ts-rs/CustomNumberFormatConfig.d.ts";
+export type * from "../../src/ts/ts-rs/NumberFormatStyle.d.ts";
+export type * from "../../src/ts/ts-rs/Notation.d.ts";
+export type * from "../../src/ts/ts-rs/DatetimeFormatType.d.ts";
+export type * from "../../src/ts/ts-rs/StringColorMode.d.ts";
+export type * from "../../src/ts/ts-rs/DatetimeColorMode.d.ts";
+export type * from "../../src/ts/ts-rs/FormatMode.d.ts";
 import type {GetTableOptions} from "../../src/ts/ts-rs/GetTableOptions.d.ts";
 import type {PanelOptions} from "../../src/ts/ts-rs/PanelOptions.d.ts";
+import type {RestoreOptions} from "../../src/ts/ts-rs/RestoreOptions.d.ts";
 import type {ExportOptions} from "../../src/ts/ts-rs/ExportOptions.d.ts";
 import type {GetClientOptions} from "../../src/ts/ts-rs/GetClientOptions.d.ts";
 import type {ClientOptions} from "../../src/ts/ts-rs/ClientOptions.d.ts";
 import type {ViewerConfig} from "../../src/ts/ts-rs/ViewerConfig.d.ts";
 import type {ViewerConfigUpdate} from "../../src/ts/ts-rs/ViewerConfigUpdate.d.ts";
+import type {ViewerConfigInitial} from "../../src/ts/ts-rs/ViewerConfigInitial.d.ts";
 import type {WorkspaceConfig} from "../../src/ts/ts-rs/WorkspaceConfig.d.ts";
 import type {WorkspaceConfigUpdate} from "../../src/ts/ts-rs/WorkspaceConfigUpdate.d.ts";
 
@@ -442,14 +540,98 @@ export class PerspectiveViewerElement {
     __get_model(): PerspectiveViewerElement;
     /**
      * Add a new, independent panel to this viewer's layout, rendering the
-     * supplied [`ViewerConfigUpdate`] into it. The panel uses the default
-     * [`perspective_client::Client`] (the first passed to [`Self::load`]) to
-     * resolve its `table`. Returns the generated panel id.
+     * supplied [`ViewerConfigInitial`] into it. Unlike [`Self::restore`]'s
+     * update-shaped argument, a new panel has no prior state, so `table`
+     * is REQUIRED — a table-less call rejects before the layout is
+     * touched. The panel uses the default [`perspective_client::Client`]
+     * (the first passed to [`Self::load`]) to resolve its `table`. Returns
+     * the generated panel id.
+     *
+     * The element-level `settings` field does not exist on the argument
+     * type (it is shared across the element, not per-panel).
+     */
+    addPanel(config: ViewerConfigInitial): Promise<any>;
+    /**
+     * Configure the embedded LLM agent (see `prompt()`), replacing any prior
+     * configuration and conversation.
+     *
+     * The agent core is provider-agnostic: one OpenAI-chat-completions
+     * protocol over primitive connection fields. Exactly one of
+     * `config.url` or `config.engine` is required; the `providers` presets
+     * exported by this package are plain spreadable collections of these
+     * fields (`{...providers.anthropic, apiKey}`).
+     *
+     * - `config.url` - a full chat-completions endpoint URL (any
+     *   OpenAI-compatible service: Anthropic/Gemini compatibility endpoints,
+     *   LM Studio, Ollama, OpenRouter, a proxy...).
+     * - `config.engine` - an in-page engine object with an OpenAI-compatible
+     *   `chat.completions.create(request)` method (e.g. WebLLM's `MLCEngine`);
+     *   mutually exclusive with `url`.
+     * - `config.headers` - extra request headers, sent verbatim.
+     * - `config.apiKey` - sugar for the `Authorization: Bearer` header.
+     * - `config.model` - model id sent with each request; local servers and
+     *   engines generally answer with whatever model is loaded.
+     * - `config.name` - cosmetic label for the chat badge (presets set this).
+     * - `config.systemPrompt` - extra system-prompt context appended to the
+     *   agent's built-in instructions.
+     * - `config.maxTurns` - max model turns (tool-call rounds + the final
+     *   answer) per `prompt()` call. Defaults to 16.
+     * - `config.docs` - the agent metadata bundle, which supplies the
+     *   `search_docs` corpus and the rich tool parameter schemas: the packaged
+     *   `dist/docs/perspective-docs.json` asset as a parsed object (`import
+     *   docs from "…json" with { type: "json" }`), a `fetch()` `Response`, an
+     *   `ArrayBuffer`, a JSON string, or a `Promise` of any of those — and/or
+     *   an inline array of `{title?, text}` entries for host data definitions.
+     *   Omitted, `search_docs` searches an empty corpus and the parameter
+     *   schemas degrade to permissive objects.
+     * - `config.systemRole` - where the preamble (plus `systemPrompt`) is
+     *   placed: `"system"` (default) or `"user"`. Some engines refuse a system
+     *   message alongside `tools` because they substitute their own — WebLLM's
+     *   Hermes function calling throws `CustomSystemPromptError` on ANY system
+     *   message — and those need `"user"`, which folds the same text into the
+     *   opening user turn.
+     * - `config.entitlements` - access grants limiting which tools the agent
+     *   is offered (and may call): any of `"read_view"`, `"configure_view"`,
+     *   `"manage_layout"`, `"read_docs"`, `"read_data"`. Omitted, all but
+     *   `"read_data"` are granted; `["read_view", "read_docs"]` yields a
+     *   read-only agent.
+     *
+     * # JavaScript Examples
      *
-     * Element-level config fields (`settings`, `theme`) in the argument are
-     * ignored — those are shared across the element, not per-panel.
+     * ```javascript
+     * import { providers } from "@perspective-dev/viewer";
+     *
+     * viewer.agentConfig({
+     *     ...providers.anthropic,
+     *     apiKey: "sk-ant-...",
+     *     docs: fetch(
+     *         "node_modules/@perspective-dev/viewer/dist/docs/perspective-docs.json",
+     *     ),
+     * });
+     * ```
+     */
+    agentConfig(config: any): void;
+    /**
+     * Run one conversational turn of the embedded LLM agent (configured via
+     * `agentConfig()`), resolving with the agent's final text response after
+     * any tool calls have been applied to this element. Turns share a
+     * conversation history (and the chat sidebar's transcript) until
+     * `agentReset()`; a call made while a turn is already running rejects.
+     * Tool activity is emitted as `perspective-agent-tool` CustomEvents on
+     * this element.
+     *
+     * # JavaScript Examples
+     *
+     * ```javascript
+     * await viewer.agentPrompt("Show me sales by region as a bar chart");
+     * ```
+     */
+    agentPrompt(prompt: string): Promise<any>;
+    /**
+     * Clear the agent's conversation (history and chat transcript), keeping
+     * its configuration. Cancels any in-flight turn.
      */
-    addPanel(update: ViewerConfigUpdate): Promise<any>;
+    agentReset(): Promise<any>;
     connectedCallback(): void;
     /**
      * Copy this viewer's `View` or `Table` data as CSV to the system
@@ -848,9 +1030,12 @@ export class PerspectiveViewerElement {
      * optional `{panel}` selector.
      *
      * If `panel` names no existing panel, a NEW panel is created with that id
-     * and the config restored into it (an upsert), equivalent to
-     * [`Self::addPanel`] but with a caller-chosen id. As with a created panel,
+     * and the config restored into it (an upsert). As with a created panel,
      * the element-level `settings`/`theme` fields are ignored in that case.
+     * Unlike [`Self::addPanel`], the argument is a PATCH, so a `table` is
+     * optional: creating without one yields a DEFERRED panel that the next
+     * [`Self::load`] binds. Such a panel renders but cannot be serialized —
+     * [`Self::save`] rejects with "Panel has no `table`" until it is bound.
      *
      * On an empty element with a pending [`Self::load`] whose payload is not
      * yet classified, the active-target form (no `panel`) instead claims and
@@ -869,7 +1054,15 @@ export class PerspectiveViewerElement {
      *
      * - `update` - The config to restore to, as returned by [`Self::save`] in
      *   either "json", "string" or "arraybuffer" format.
-     * - `name` - The panel to target, or `None` for the active panel.
+     * - `options.panel` - The panel to target, or the active panel when
+     *   omitted.
+     * - `options.suppress_errors` - when `true`, a failed restore only rejects
+     *   the returned `Promise`; the error is NOT committed to the viewer's
+     *   visible error state and the session remains usable. The view config is
+     *   rolled back to its pre-call value, so a rejected patch cannot re-merge
+     *   into a later restore. Element-level state the call already applied
+     *   (theme, title, a plugin swap) is NOT undone — restore a known-good
+     *   config to recover those exactly.
      *
      * # JavaScript Examples
      *
@@ -887,7 +1080,7 @@ export class PerspectiveViewerElement {
      * await viewer.restore({group_by: ["State"]});
      * ```
      */
-    restore(update: ViewerConfigUpdate, options?: PanelOptions | null): Promise<void>;
+    restore(update: ViewerConfigUpdate, options?: RestoreOptions | null): Promise<void>;
     /**
      * Restore the ENTIRE element from a whole-element
      * [`WorkspaceConfigUpdate`] (`{version, active?, layout, panels, ...}`) —
@@ -1516,7 +1709,7 @@ export class VirtualServer {
     free(): void;
     [Symbol.dispose](): void;
     handleRequest(bytes: Uint8Array): Promise<any>;
-    constructor(handler: object);
+    constructor(handler: VirtualServerHandler);
 }
 
 export function get_wasm_module(): WebAssembly.Module;
@@ -1568,6 +1761,9 @@ export interface InitOutput {
     readonly perspectivedebugpluginelement_update: (a: number, b: number) => number;
     readonly perspectiveviewerelement___get_model: (a: number) => number;
     readonly perspectiveviewerelement_addPanel: (a: number, b: number) => number;
+    readonly perspectiveviewerelement_agentConfig: (a: number, b: number, c: number) => void;
+    readonly perspectiveviewerelement_agentPrompt: (a: number, b: number, c: number) => number;
+    readonly perspectiveviewerelement_agentReset: (a: number) => number;
     readonly perspectiveviewerelement_connectedCallback: (a: number, b: number) => void;
     readonly perspectiveviewerelement_copy: (a: number, b: number) => number;
     readonly perspectiveviewerelement_delete: (a: number) => number;
@@ -1704,21 +1900,21 @@ export interface InitOutput {
     readonly virtualdataslice_setStringCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly virtualserver_handleRequest: (a: number, b: number, c: number) => number;
     readonly virtualserver_new: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_15590: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_3497: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_18482: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_19140: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_19169: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_26445: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_6144: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_6145: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_6146: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_6142: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_18602: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_19145: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_19186: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_16279: (a: number, b: number) => number;
-    readonly __wasm_bindgen_func_elem_19144: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_17003: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_17713: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_18571: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_3989: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_23208: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_31328: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_17122: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_17718: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_6981: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_6982: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_6983: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_6979: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_23225: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_19569: (a: number, b: number) => number;
+    readonly __wasm_bindgen_func_elem_17717: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;