@mihe-dev/js 0.0.0-stage → 0.1.0

package/dist/commands.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Executing the commands the runtime sends.
+ *
+ * Every command names a registered target — a route the runtime resolved from
+ * its screen catalogue, or a component key the app declared. Nothing here
+ * takes a CSS selector or a coordinate, so there is no path by which the model
+ * drives the UI directly (spec §5.2).
+ *
+ * Every branch returns a result, including failures, because the runtime is
+ * blocking a turn on the ack and the model needs to learn the truth. Reporting
+ * "the element was not on screen" is far better than reporting nothing.
+ */
+import type { AssistantCommand } from "@mihe-dev/protocol";
+import type { HighlightEngine } from "./highlight.js";
+import type { AssistantStore, QueryParamDeclaration } from "./store.js";
+/** When a frontend action is warned about as slow. */
+export declare const ACTION_SLOW_MS = 5000;
+/**
+ * How long the runtime waits for a command's answer (`COMMAND_ACK_TIMEOUT`
+ * in the runtime's session.rs). Past it, the assistant is told the command
+ * failed.
+ */
+export declare const RUNTIME_ACK_WAIT_MS = 10000;
+export interface CommandResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface CommandContext {
+    store: AssistantStore;
+    highlighter: HighlightEngine;
+    /**
+     * How the host app changes route. Supplied by the customer, because only
+     * they know whether that is Next.js's router, React Router, or something
+     * else. Defaults to a full page load, which works everywhere and is
+     * noticeably worse — the docs should push people to wire this up.
+     */
+    navigate: (route: string) => void;
+    /**
+     * Resolves once the screen at `route` has published its context to the
+     * runtime, or `false` if it has not done so within the timeout.
+     *
+     * Navigating is the one command whose effects are not finished when the
+     * function returns: the router swaps the tree, React mounts the destination,
+     * its hooks register, and only then does the new context travel. The runtime
+     * re-reads the screen after every tool call to decide what the next step may
+     * do, so acking before that lands would tell it the user is still on the
+     * screen they just left — and the action they navigated *for* would be
+     * filtered out as off-screen.
+     *
+     * Optional so a hand-built context still works; the provider always supplies
+     * it.
+     */
+    screenPublished?: (route: string, options?: {
+        fresh?: boolean;
+    }) => Promise<boolean>;
+    /**
+     * Resolves once a published screen shows `controlKey` set to `value`, or
+     * `false` if none does within the timeout. A switch is acked only then, for
+     * `screenPublished`'s reason: the runtime's next step reads the screen.
+     */
+    viewPublished?: (controlKey: string, value: string) => Promise<boolean>;
+    /** Opens a registered modal, when the host app has modals to open. */
+    /** Return `false` when the key is not one this app can open. */
+    openModal?: (modalKey: string) => void | boolean;
+}
+/** Why a set of search parameters is not what the table declared, or null. */
+export declare function checkQueryParams(declared: QueryParamDeclaration[], params: Record<string, string>): string | null;
+export declare function executeCommand(command: AssistantCommand, ctx: CommandContext): Promise<CommandResult>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../js/src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAY,MAAM,SAAS,CAAC;AAE/E,sDAAsD;AACtD,eAAO,MAAM,cAAc,OAAQ,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,eAAe,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrF;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,sEAAsE;IACtE,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;CAClD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,qBAAqB,EAAE,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,GAAG,IAAI,CAgBf;AAqBD,wBAAsB,cAAc,CAClC,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC,CAgPxB"}

package/dist/commands.js

@@ -0,0 +1,295 @@
+/**
+ * Executing the commands the runtime sends.
+ *
+ * Every command names a registered target — a route the runtime resolved from
+ * its screen catalogue, or a component key the app declared. Nothing here
+ * takes a CSS selector or a coordinate, so there is no path by which the model
+ * drives the UI directly (spec §5.2).
+ *
+ * Every branch returns a result, including failures, because the runtime is
+ * blocking a turn on the ack and the model needs to learn the truth. Reporting
+ * "the element was not on screen" is far better than reporting nothing.
+ */
+import { findComponent } from "./highlight.js";
+/** When a frontend action is warned about as slow. */
+export const ACTION_SLOW_MS = 5_000;
+/**
+ * How long the runtime waits for a command's answer (`COMMAND_ACK_TIMEOUT`
+ * in the runtime's session.rs). Past it, the assistant is told the command
+ * failed.
+ */
+export const RUNTIME_ACK_WAIT_MS = 10_000;
+/** Why a set of search parameters is not what the table declared, or null. */
+export function checkQueryParams(declared, params) {
+    for (const [key, value] of Object.entries(params)) {
+        const param = declared.find((p) => p.key === key);
+        if (!param)
+            return `"${key}" is not something this table can be searched by.`;
+        if (typeof value !== "string")
+            return `The value for "${key}" must be a string.`;
+        if (param.kind === "enum" && !param.values.includes(value)) {
+            return `"${value}" is not one of "${key}"'s values.`;
+        }
+        if (param.kind === "date" && !isIsoDate(value)) {
+            return `"${value}" is not a date in YYYY-MM-DD form.`;
+        }
+        if (param.kind === "text" && (value.length > MAX_QUERY_TEXT || /[\u0000-\u001f\u007f]/.test(value))) {
+            return `The search for "${key}" is too long or contains control characters.`;
+        }
+    }
+    return null;
+}
+/** Matches the runtime's cap, `QUERY_TEXT_MAX_CHARS`. */
+const MAX_QUERY_TEXT = 100;
+function isIsoDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+function currentPath() {
+    return typeof window === "undefined" ? null : window.location.pathname;
+}
+function currentUrl() {
+    return typeof window === "undefined"
+        ? null
+        : window.location.pathname + window.location.search;
+}
+export async function executeCommand(command, ctx) {
+    switch (command.type) {
+        case "navigate": {
+            const { route } = command.data;
+            // A query means the page's state is about to change — usually the same
+            // page with new filters. The screen already published is then the
+            // *old* view, and acking on it would have the model read the chart it
+            // was asked to replace. So wait for a fresh publish, unless the URL is
+            // already exactly this, in which case nothing will change and nothing
+            // will be published.
+            const fresh = route.includes("?") && currentUrl() !== route;
+            ctx.navigate(route);
+            const arrived = (await ctx.screenPublished?.(route, { fresh })) ?? true;
+            return arrived
+                ? { ok: true, result: { route } }
+                : {
+                    ok: true,
+                    result: {
+                        route,
+                        note: "Navigation started, but the destination has not reported its context yet. Anything scoped to that screen may not be available for another moment.",
+                    },
+                };
+        }
+        case "highlight": {
+            const { componentKey, message } = command.data;
+            return ctx.highlighter.highlight(componentKey, message ?? undefined)
+                ? { ok: true }
+                : { ok: false, error: notOnPage(componentKey) };
+        }
+        case "focus": {
+            const { componentKey, message } = command.data;
+            return ctx.highlighter.focus(componentKey, message ?? undefined)
+                ? { ok: true }
+                : { ok: false, error: notOnPage(componentKey) };
+        }
+        case "scroll_to": {
+            const { componentKey } = command.data;
+            return ctx.highlighter.scrollTo(componentKey)
+                ? { ok: true }
+                : { ok: false, error: notOnPage(componentKey) };
+        }
+        case "open_modal": {
+            const { modalKey } = command.data;
+            if (!ctx.openModal) {
+                return {
+                    ok: false,
+                    error: "This app has not wired up modal opening, so that modal cannot be opened.",
+                };
+            }
+            // An explicit `false` means the host app knows about modals but not this
+            // one — usually because the dialog belongs to a screen the user has
+            // left. Reported as a failure rather than swallowed: the model's
+            // standing rule is never to claim something happened without a tool
+            // result saying so, and "ok" to an unopened form is exactly that claim.
+            // `undefined` stays a success, so an implementation returning nothing
+            // behaves as it always did.
+            if (ctx.openModal(modalKey) === false) {
+                return {
+                    ok: false,
+                    error: `There is no \`${modalKey}\` dialog on this screen. It may belong to a different one.`,
+                };
+            }
+            return { ok: true };
+        }
+        case "run_frontend_action": {
+            const { actionName, input } = command.data;
+            const action = ctx.store.getAction(actionName);
+            if (!action) {
+                // The runtime believes this action is registered but no handler
+                // mounted — usually a component that owns it is not on this screen.
+                return {
+                    ok: false,
+                    error: `No handler is currently mounted for "${actionName}".`,
+                };
+            }
+            // A handler that waits on the user (a confirmation dialog, a password,
+            // a file picker) outlives the runtime's wait, and the assistant then
+            // reports as failed an action the user goes on to finish. Nothing else
+            // tells the developer, so the console does.
+            const started = Date.now();
+            const slow = setTimeout(() => {
+                console.warn(`[mihe] The "${actionName}" handler has run for ${ACTION_SLOW_MS / 1000}s. ` +
+                    `The runtime waits ${RUNTIME_ACK_WAIT_MS / 1000}s, then tells the assistant it failed. ` +
+                    "If it is waiting for the user, open the UI they need and return at once (say what you opened); " +
+                    "they finish it there.");
+            }, ACTION_SLOW_MS);
+            const late = () => {
+                if (Date.now() - started > RUNTIME_ACK_WAIT_MS) {
+                    console.warn(`[mihe] The "${actionName}" handler finished after the runtime stopped waiting, ` +
+                        "so the assistant was told it failed whatever the outcome. Return before the user acts; see the warning above.");
+                }
+            };
+            try {
+                const result = await action.handler((input ?? {}));
+                late();
+                return { ok: true, result: result ?? { done: true } };
+            }
+            catch (cause) {
+                late();
+                // The host app's handler threw. Its message is the most useful thing
+                // to hand back, so the assistant can tell the user what went wrong.
+                return { ok: false, error: describeError(cause) };
+            }
+            finally {
+                clearTimeout(slow);
+            }
+        }
+        case "set_view": {
+            const { controlKey, value } = command.data;
+            const control = ctx.store.getControl(controlKey);
+            if (!control) {
+                return { ok: false, error: `"${controlKey}" is not on the page right now.` };
+            }
+            // Checked here as well as in the runtime, so the app's `onChange` is
+            // only ever handed a value it declared, whatever sent the command.
+            if (!control.options.some((option) => option.value === value)) {
+                return { ok: false, error: `"${value}" is not one of "${controlKey}"'s options.` };
+            }
+            try {
+                await control.onChange(value);
+            }
+            catch (cause) {
+                return { ok: false, error: describeError(cause) };
+            }
+            const shown = (await ctx.viewPublished?.(controlKey, value)) ?? true;
+            return shown
+                ? { ok: true, result: { showing: value } }
+                : {
+                    ok: false,
+                    error: `The app was asked to show "${value}", but "${controlKey}" still reports another tab.`,
+                };
+        }
+        case "read_table": {
+            const { tableKey, offset, limit } = command.data;
+            const table = ctx.store.getTable(tableKey);
+            if (!table) {
+                return { ok: false, error: `"${tableKey}" is not on the page right now.` };
+            }
+            try {
+                const rows = table.read(offset, limit);
+                return {
+                    ok: true,
+                    result: {
+                        rows,
+                        offset,
+                        loaded: table.loadedRows,
+                        ...(table.total === undefined ? {} : { total: table.total }),
+                    },
+                };
+            }
+            catch (cause) {
+                return { ok: false, error: describeError(cause) };
+            }
+        }
+        case "query_table": {
+            const { tableKey, params, limit, show } = command.data;
+            const table = ctx.store.getTable(tableKey);
+            if (!table) {
+                return { ok: false, error: `"${tableKey}" is not on the page right now.` };
+            }
+            if (!table.query) {
+                return { ok: false, error: `"${tableKey}" cannot be searched.` };
+            }
+            // Checked here as well as in the runtime, so the app's `run` is only
+            // ever handed parameters it declared, whatever sent the command.
+            const invalid = checkQueryParams(table.query.params, params);
+            if (invalid)
+                return { ok: false, error: invalid };
+            let found;
+            try {
+                found = await table.query.run(params);
+            }
+            catch (cause) {
+                return { ok: false, error: describeError(cause) };
+            }
+            let shown = false;
+            if (show && table.query.show) {
+                try {
+                    await table.query.show(params);
+                    // Acked once the page has published again, for `navigate`'s
+                    // reason: the model's next step reads the screen.
+                    shown = (await ctx.screenPublished?.(currentPath() ?? "", { fresh: true })) ?? true;
+                }
+                catch (cause) {
+                    return { ok: false, error: describeError(cause) };
+                }
+            }
+            return {
+                ok: true,
+                result: {
+                    rows: found.rows.slice(0, limit),
+                    ...(found.total === undefined ? {} : { total: found.total }),
+                    shown,
+                },
+            };
+        }
+        case "read_chart": {
+            const { chartKey, series, limit } = command.data;
+            const chart = ctx.store.getChart(chartKey);
+            if (!chart) {
+                return { ok: false, error: `"${chartKey}" is not on the page right now.` };
+            }
+            try {
+                return { ok: true, result: { series: chart.read(series ?? undefined, limit) } };
+            }
+            catch (cause) {
+                return { ok: false, error: describeError(cause) };
+            }
+        }
+        case "clear_highlight": {
+            ctx.highlighter.clear();
+            return { ok: true };
+        }
+        default: {
+            // An unknown command type means the runtime is ahead of this SDK.
+            // Reporting it beats silently doing nothing.
+            const unknown = command;
+            return {
+                ok: false,
+                error: `This app's SDK does not understand the "${unknown.type}" command. It may need updating.`,
+            };
+        }
+    }
+}
+function notOnPage(componentKey) {
+    const registeredElsewhere = Boolean(findComponent(componentKey));
+    return registeredElsewhere
+        ? `"${componentKey}" is on the page but not visible.`
+        : `"${componentKey}" is not on the page right now.`;
+}
+function describeError(cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    if (typeof cause === "string")
+        return cause;
+    return "The action failed.";
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

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

package/dist/debug.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The developer's view of what each screen costs (amendment 67).
+ *
+ * With `debug` on the provider, the runtime reports what one answer on the
+ * current screen re-sends to the model, and this turns that report into a
+ * console line someone can act on: which part is large, and which tools make
+ * it so. Estimates, about four characters a token. The dashboard's usage
+ * page has the real bill.
+ */
+import type { ContextSize, ScreenId } from "@mihe-dev/protocol";
+export interface ContextReport {
+    screenId?: ScreenId;
+    chat: ContextSize;
+    voice?: ContextSize;
+}
+export declare function formatContextReport(report: ContextReport): string;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../js/src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEhE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAKD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAajE"}

package/dist/debug.js

@@ -0,0 +1,29 @@
+/**
+ * The developer's view of what each screen costs (amendment 67).
+ *
+ * With `debug` on the provider, the runtime reports what one answer on the
+ * current screen re-sends to the model, and this turns that report into a
+ * console line someone can act on: which part is large, and which tools make
+ * it so. Estimates, about four characters a token. The dashboard's usage
+ * page has the real bill.
+ */
+/** How many of the largest tools to name. The rest are counted. */
+const LARGEST = 5;
+export function formatContextReport(report) {
+    const where = report.screenId ? `\`${report.screenId}\`` : "an unregistered page";
+    const lines = [`[mihe] Each answer on ${where} re-sends about:`];
+    lines.push(`  typed: ${describe(report.chat)}`);
+    if (report.voice)
+        lines.push(`  voice: ${describe(report.voice)}`);
+    const largest = (report.voice ?? report.chat).tools.slice(0, LARGEST);
+    if (largest.length > 0) {
+        lines.push(`  largest tools: ${largest.map((tool) => `${tool.name} ${tool.tokens}`).join(", ")}`);
+    }
+    return lines.join("\n");
+}
+function describe(size) {
+    const total = size.instructionTokens + size.toolTokens + size.screenTokens;
+    return (`${total.toLocaleString("en")} tokens — instructions ${size.instructionTokens}, ` +
+        `${size.tools.length} tools ${size.toolTokens}, this screen ${size.screenTokens}`);
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../../js/src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,mEAAmE;AACnE,MAAM,OAAO,GAAG,CAAC,CAAC;AAElB,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC;IAClF,MAAM,KAAK,GAAG,CAAC,yBAAyB,KAAK,kBAAkB,CAAC,CAAC;IACjE,KAAK,CAAC,IAAI,CAAC,YAAY,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,YAAY,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAEnE,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACtE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CACR,oBAAoB,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,QAAQ,CAAC,IAAiB;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC;IAC3E,OAAO,CACL,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,0BAA0B,IAAI,CAAC,iBAAiB,IAAI;QACjF,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,UAAU,IAAI,CAAC,UAAU,iBAAiB,IAAI,CAAC,YAAY,EAAE,CAClF,CAAC;AACJ,CAAC"}

package/dist/declarations.d.ts

@@ -0,0 +1,160 @@
+/**
+ * What an app declares about tabs, tables and charts, and how each becomes
+ * what the store holds (amendment 67, doc 08).
+ *
+ * Shared by the JavaScript API (`mihe.registerTable(…)`) and the React hooks
+ * (`useAssistantTable(…)`), so the two can't send the model different things
+ * for the same table. Each builder takes `latest`, a function returning the
+ * declaration as it is now: rows, closures and data are read at the moment of
+ * a read rather than captured at registration, so a table that re-renders
+ * every second doesn't re-register every second.
+ */
+import type { ChartDeclaration, TableDeclaration, ViewControlDeclaration } from "./store.js";
+/** A set of tabs the assistant can see and switch. */
+export interface AssistantTabs {
+    /** Unique on the screen, e.g. `reports.tabs`. The model refers to it by this. */
+    id: string;
+    /** What the tabs choose between, for the model: "Report", "Period". */
+    label: string;
+    tabs: {
+        value: string;
+        label: string;
+    }[];
+    /** The tab showing now. */
+    value: string | undefined;
+    /** Switch to `value`. Called with one of `tabs`' values and nothing else. */
+    onChange: (value: string) => void | Promise<void>;
+}
+/** A column a table exposes. Undeclared fields are never sent. */
+export interface AssistantTableColumn<Row> {
+    key: string;
+    /** What the model calls it, and the key each row's cell is read under. */
+    label: string;
+    /** The cell's value. Defaults to `row[key]`. */
+    value?: (row: Row) => unknown;
+}
+/** A table the assistant can read. */
+export interface AssistantTable<Row> {
+    /** Unique on the screen, e.g. `orders.table`. */
+    id: string;
+    label: string;
+    columns: AssistantTableColumn<Row>[];
+    /** The rows loaded now — the page on screen, for a paged table. */
+    rows: Row[];
+    rowId: (row: Row) => string;
+    /**
+     * The action input a row's id fills, such as `orderId`. The runtime tells
+     * the model which actions accept it, from your registry and the user's
+     * permissions. Leave it out for rows nothing acts on.
+     */
+    rowIdName?: string;
+    /**
+     * The screen a row opens, and the route params that open it:
+     * `{ screenId: "orders.detail", params: (order) => ({ id: order.id }) }`.
+     * Each row the model reads then carries exactly those params, so it never
+     * has to guess which of a record's ids the link wants.
+     */
+    opens?: {
+        screenId: string;
+        params: (row: Row) => Record<string, string>;
+    };
+    /** Rows in the whole list, when `rows` is one page of it. */
+    total?: number;
+    /**
+     * Search past the loaded rows, with your own API and the user's own
+     * session (amendment 67, step 3). The model fills in `params`; only the
+     * keys you declare, and for an enum only its values, ever reach `run`.
+     *
+     * ```ts
+     * query: {
+     *   params: {
+     *     search: { kind: "text", description: "order number or customer name" },
+     *     status: { kind: "enum", values: ["pending", "paid"] },
+     *     from: { kind: "date" },
+     *   },
+     *   run: async (p) => {
+     *     const res = await fetchOrders({ search: p.search, status: p.status, dateFrom: p.from });
+     *     return { rows: res.data, total: res.meta.total };
+     *   },
+     *   // Optional. Make the page show this search — set its filters and
+     *   // search box. Without it, results are read but not shown.
+     *   show: (p) => { setSearch(p.search ?? ""); setStatus(p.status ?? "all"); },
+     * }
+     * ```
+     *
+     * It only reads. A search is in `navigate`'s class: it changes what is
+     * shown, never what is stored.
+     */
+    query?: AssistantTableQuery<Row>;
+}
+/** A search parameter: what the model may fill in. */
+export type AssistantQueryParam = {
+    kind: "text";
+    description?: string;
+} | {
+    kind: "enum";
+    values: readonly string[];
+    description?: string;
+} | {
+    kind: "date";
+    description?: string;
+};
+/** How a table is searched beyond the rows it has loaded. */
+export interface AssistantTableQuery<Row> {
+    params: Record<string, AssistantQueryParam>;
+    run: (params: Record<string, string>) => Promise<{
+        rows: Row[];
+        total?: number;
+    }>;
+    show?: (params: Record<string, string>) => void | Promise<void>;
+}
+/** A chart the assistant can explain. */
+export interface AssistantChart<Datum> {
+    /** Unique on the screen, e.g. `stock.trend`. */
+    id: string;
+    title: string;
+    /** The rows the chart is drawn from: the same array your chart library gets. */
+    data: Datum[];
+    x: {
+        key: keyof Datum & string;
+        /** What the axis is: "Month", "Product". */
+        label: string;
+        /**
+         * `ordered` for time and anything else with a sequence, `category` for a
+         * set of things. Rises and falls are worked out only for the first.
+         * Defaults to `ordered`.
+         */
+        kind?: "ordered" | "category";
+        /** How an x value reads, such as "Mar 26" for "2026-03-01". */
+        format?: (value: unknown) => string;
+    };
+    series: {
+        key: keyof Datum & string;
+        name: string;
+        unit?: string;
+    }[];
+}
+export declare function toCell(value: unknown): string | number | boolean | null;
+/** The tabs as the store holds them. `onChange` is read at call time. */
+export declare function tabsDeclaration(latest: () => AssistantTabs): ViewControlDeclaration;
+/**
+ * What identifies a tab set's declaration, without its closure: when this
+ * changes, the store needs the new declaration.
+ */
+export declare function tabsSignature(tabs: AssistantTabs): string;
+/**
+ * What identifies a table's declaration, without its rows or closures: when
+ * this changes, the store needs the new declaration. The rows' count is in
+ * it, because the screen context reports how many are loaded.
+ */
+export declare function tableSignature<Row>(table: AssistantTable<Row>): string;
+/** The table as the store holds it. Rows and closures are read at call time. */
+export declare function tableDeclaration<Row>(latest: () => AssistantTable<Row>): TableDeclaration;
+/**
+ * The chart as the store holds it: each series summarised here, in the
+ * browser, and the points read at call time when an exact value is wanted.
+ */
+export declare function chartDeclaration<Datum>(latest: () => AssistantChart<Datum>): ChartDeclaration;
+/** What identifies a chart's declaration: its summaries, not its closures. */
+export declare function chartSignature<Datum>(chart: AssistantChart<Datum>): string;
+//# sourceMappingURL=declarations.d.ts.map

package/dist/declarations.d.ts.map

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