@perspective-dev/viewer 5.1.0 → 5.3.0

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

@@ -104,22 +104,35 @@ import type {
 
 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/SaveWorkspaceOptions.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 {SaveWorkspaceOptions} from "../../src/ts/ts-rs/SaveWorkspaceOptions.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";
 
@@ -400,7 +413,7 @@ export class GenericSQLVirtualServerModel {
      * Returns the SQL query to create a view from a table with the given
      * configuration.
      */
-    tableMakeView(table_id: string, view_id: string, config: any): string;
+    tableMakeView(table_id: string, view_id: string, config: any, schema: any): string;
     /**
      * Returns the SQL query to describe a table's schema.
      */
@@ -529,14 +542,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.
      *
-     * Element-level config fields (`settings`, `theme`) in the argument are
-     * ignored — those are shared across the element, not per-panel.
+     * # JavaScript Examples
+     *
+     * ```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
@@ -741,6 +838,7 @@ export class PerspectiveViewerElement {
      * ```
      */
     getTable(options?: GetTableOptions | null): Promise<any>;
+    getThemes(): Promise<any>;
     /**
      * Get the underlying [`View`] for this viewer.
      *
@@ -862,9 +960,10 @@ export class PerspectiveViewerElement {
      * Reset a panel's `ViewerConfig` to its data-relative default.
      *
      * Without a `panel`, this is ELEMENT-LEVEL: EVERY panel is reset and the
-     * cross-filter overlay cleared (symmetric with whole-element
-     * [`Self::save`] / [`Self::restore`]). With `{panel}`, only that panel is
-     * reset — the other panels and the overlay are left untouched.
+     * cross-filter overlay cleared (symmetric with
+     * [`Self::saveWorkspace`] / [`Self::restoreWorkspace`]). With `{panel}`,
+     * only that panel is reset — the other panels and the overlay are left
+     * untouched.
      *
      * # Arguments
      *
@@ -935,15 +1034,18 @@ 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,
-     * the element-level `settings`/`theme` fields are ignored in that case.
+     * and the config restored into it (an upsert). Creation REQUIRES a
+     * `table` — the same rule [`Self::addPanel`] enforces in its argument
+     * type — and a would-create call without one REJECTS before any state
+     * (including `settings`) is applied: with no panel to target and no
+     * `table`, the patch has no data arrival path. In particular, on an
+     * element with zero panels every `restore` must carry a `table`.
      *
      * On an empty element with a pending [`Self::load`] whose payload is not
      * yet classified, the active-target form (no `panel`) instead claims and
      * restores into that load's reserved first panel — see [`Self::load`].
      *
-     * This restores a SINGLE panel; a whole-element config (with a `panels`
+     * This restores a SINGLE panel; a workspace config (with a `panels`
      * map) must be applied via [`Self::restoreWorkspace`] — its `panels` /
      * `layout` keys are ignored here.
      *
@@ -956,7 +1058,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
      *
@@ -974,10 +1084,10 @@ 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, ...}`) —
+     * Restore the ENTIRE element from a [`WorkspaceConfigUpdate`]
+     * (`{version, active?, layout, panels, ...}`) —
      * the multi-panel counterpart of [`Self::restore`]. Every existing panel
      * is replaced by the `panels` entries, and the layout tree + master/detail
      * cross-filter state re-applied. Unlike [`Self::restore`], this never
@@ -1041,11 +1151,12 @@ export class PerspectiveViewerElement {
      */
     save(options?: PanelOptions | null): Promise<ViewerConfig>;
     /**
-     * Save the ENTIRE element to a whole-element [`WorkspaceConfig`]
-     * (`{version, active?, layout, panels, ...}`) — the multi-panel
-     * counterpart of [`Self::save`]. Unlike [`Self::save`] (which emits a
-     * single `ViewerConfig` for one panel), this ALWAYS emits the
-     * whole-element format, restorable via [`Self::restoreWorkspace`].
+     * Save the ENTIRE element to a [`WorkspaceConfig`]
+     * (`{version, active?, layout, panels, palette?, ...}`) — the
+     * multi-panel counterpart of [`Self::save`]. Unlike [`Self::save`]
+     * (which emits a single `ViewerConfig` for one panel), this ALWAYS
+     * emits the workspace format, restorable via
+     * [`Self::restoreWorkspace`].
      *
      * # JavaScript Examples
      *
@@ -1054,7 +1165,7 @@ export class PerspectiveViewerElement {
      * await viewer.restoreWorkspace(token);
      * ```
      */
-    saveWorkspace(): Promise<WorkspaceConfig>;
+    saveWorkspace(options?: SaveWorkspaceOptions | null): Promise<WorkspaceConfig>;
     /**
      * Make the panel with id `name` the active panel, re-targeting the
      * settings panel and status-bar toolbar (and the root's
@@ -1655,6 +1766,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;
@@ -1671,6 +1785,7 @@ export interface InitOutput {
     readonly perspectiveviewerelement_getRenderStats: (a: number, b: number, c: number) => void;
     readonly perspectiveviewerelement_getSelection: (a: number, b: number, c: number) => void;
     readonly perspectiveviewerelement_getTable: (a: number, b: number) => number;
+    readonly perspectiveviewerelement_getThemes: (a: number) => number;
     readonly perspectiveviewerelement_getView: (a: number, b: number) => number;
     readonly perspectiveviewerelement_getViewConfig: (a: number, b: number) => number;
     readonly perspectiveviewerelement_load: (a: number, b: number, c: number) => void;
@@ -1684,7 +1799,7 @@ export interface InitOutput {
     readonly perspectiveviewerelement_restoreWorkspace: (a: number, b: number) => number;
     readonly perspectiveviewerelement_restyleElement: (a: number) => number;
     readonly perspectiveviewerelement_save: (a: number, b: number) => number;
-    readonly perspectiveviewerelement_saveWorkspace: (a: number) => number;
+    readonly perspectiveviewerelement_saveWorkspace: (a: number, b: number) => number;
     readonly perspectiveviewerelement_setActivePanel: (a: number, b: number, c: number) => number;
     readonly perspectiveviewerelement_setAutoPause: (a: number, b: number) => number;
     readonly perspectiveviewerelement_setAutoSize: (a: number, b: number) => void;
@@ -1724,7 +1839,7 @@ export interface InitOutput {
     readonly client_terminate: (a: number, b: number) => void;
     readonly genericsqlvirtualservermodel_getHostedTables: (a: number, b: number) => void;
     readonly genericsqlvirtualservermodel_new: (a: number, b: number) => void;
-    readonly genericsqlvirtualservermodel_tableMakeView: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly genericsqlvirtualservermodel_tableMakeView: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
     readonly genericsqlvirtualservermodel_tableSchema: (a: number, b: number, c: number, d: number) => void;
     readonly genericsqlvirtualservermodel_tableSize: (a: number, b: number, c: number, d: number) => void;
     readonly genericsqlvirtualservermodel_tableValidateExpression: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
@@ -1791,21 +1906,22 @@ 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_3667: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_16364: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_19409: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_20067: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_20096: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_27549: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_6430: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_6431: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_6432: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_6428: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_19529: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_20072: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_20113: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_17084: (a: number, b: number) => number;
-    readonly __wasm_bindgen_func_elem_20071: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_17916: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_18625: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_19491: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_4310: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_24164: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_32290: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_18035: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_18630: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7520: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7521: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7522: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7518: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_24181: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_20501: (a: number, b: number) => number;
+    readonly __wasm_bindgen_func_elem_18629: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_20502: (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;