@sigrun/tui 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-24
+### Added
+- Extension surfaces and live surface updates.
+- Typed block rendering: content, braille charts, collections, forms,
+  page shells, images, navigation, and all three keymaps.
+
+## [0.1.0] - 2026-10-21
+### Added
+- First published release of the TUI (workspace package of
+  [@sigrun/sigrun](https://github.com/sigrun-ai/sigrun)): fullscreen
+  alt-screen UI with mouse support, per-keymap standard/vim/emacs
+  keymaps, themes from the shared tokens, turn-grouped transcript,
+  composer, help overlay, and OSC 52 clipboard.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+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,10 @@
-# Temporary Holding Version
+# @sigrun/tui
 
-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 sigrun terminal client — a pi-tui based TUI over the sigrun §5 API,
+spawned by the sigrun CLI (`sigrun run`), or standalone against a server
+URL (`sigrun-tui`). Optional companion of
+[@sigrun/sigrun](https://github.com/sigrun-ai/sigrun) (install separately:
+`npm i -g @sigrun/tui`).
+
+Part of the sigrun workspace; published from the repository root as
+`@sigrun/tui`.

package/dist/actions.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The TUI action layer (Task C3, UI refresh): a channel-neutral union of
+ * everything the keymaps, pickers, mouse regions, and slash commands can
+ * ask the shell to do. {@link TuiApp} implements {@link ActionHost} and
+ * owns the focus state the focus/move/open actions drive.
+ *
+ * Focus targets: `composer` (the pi-tui Editor), `list` (the sidebar's
+ * conversation tree), `transcript` (the pane's focusable turns). The
+ * keymap decides WHICH action a key means per focus; the app decides
+ * what the action DOES per focus.
+ */
+/** The three focusable regions. `surface` (Task 4, UI-blocks U2) is a
+ *  block surface pane (lanes/calendar/collection) — the blocks.* keys
+ *  route ONLY while it has focus. While a surface is focused the
+ *  transcript/list nav keys (y/f/e//?) are inert (the keymaps pass
+ *  them); Task 6's surface host decides any surface-side meaning for
+ *  them. */
+export type Focus = "composer" | "list" | "transcript" | "surface";
+/** Every dispatchable intent. */
+export type Action = {
+    readonly type: "focus";
+    readonly target: Focus;
+} | {
+    readonly type: "focus-cycle";
+    readonly direction: 1 | -1;
+} | {
+    readonly type: "move";
+    readonly delta: number;
+} | {
+    readonly type: "page";
+    readonly direction: 1 | -1;
+    readonly half: boolean;
+} | {
+    readonly type: "edge";
+    readonly to: "top" | "bottom";
+} | {
+    readonly type: "prompt-jump";
+    readonly delta: 1 | -1;
+} | {
+    readonly type: "toggle-fold";
+} | {
+    readonly type: "open";
+} | {
+    readonly type: "copy";
+} | {
+    readonly type: "fork-here";
+} | {
+    readonly type: "edit-here";
+} | {
+    readonly type: "edit-in-vim";
+} | {
+    readonly type: "picker";
+    readonly kind: "conversation" | "model" | "command";
+} | {
+    readonly type: "new-conversation";
+} | {
+    readonly type: "cycle-thinking";
+} | {
+    readonly type: "search";
+    readonly direction: "forward" | "backward";
+} | {
+    readonly type: "search-next";
+    readonly reverse: boolean;
+} | {
+    readonly type: "answer-interaction";
+} | {
+    readonly type: "cancel-run";
+} | {
+    readonly type: "redraw";
+} | {
+    readonly type: "quit";
+} | {
+    readonly type: "help";
+} | {
+    readonly type: "command-line";
+} | {
+    readonly type: "run-command";
+    readonly line: string;
+}
+/** Pick up the item under the cursor (m / M-m). */
+ | {
+    readonly type: "blocks.pickUp";
+}
+/** Drop the picked-up item at its placement (Enter). */
+ | {
+    readonly type: "blocks.drop";
+}
+/** Cancel the pick-up (Esc). */
+ | {
+    readonly type: "blocks.cancelMove";
+}
+/** Toggle the selection of the item under the cursor (Space). */
+ | {
+    readonly type: "blocks.select";
+}
+/** Open the action menu (`.` — bulk actions, "Move to…"). */
+ | {
+    readonly type: "blocks.actionMenu";
+}
+/** Toggle the checkable field of the item under the cursor (x). */
+ | {
+    readonly type: "blocks.check";
+}
+/** Previous calendar range ([). */
+ | {
+    readonly type: "blocks.rangePrev";
+}
+/** Next calendar range (]). */
+ | {
+    readonly type: "blocks.rangeNext";
+}
+/** Return the calendar range to today (t). */
+ | {
+    readonly type: "blocks.today";
+};
+/** The dispatch surface {@link TuiApp} implements. */
+export interface ActionHost {
+    dispatch(action: Action): Promise<void>;
+}

package/dist/actions.js

@@ -0,0 +1,12 @@
+/**
+ * The TUI action layer (Task C3, UI refresh): a channel-neutral union of
+ * everything the keymaps, pickers, mouse regions, and slash commands can
+ * ask the shell to do. {@link TuiApp} implements {@link ActionHost} and
+ * owns the focus state the focus/move/open actions drive.
+ *
+ * Focus targets: `composer` (the pi-tui Editor), `list` (the sidebar's
+ * conversation tree), `transcript` (the pane's focusable turns). The
+ * keymap decides WHICH action a key means per focus; the app decides
+ * what the action DOES per focus.
+ */
+export {};

package/dist/api.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The TUI's typed §5 HTTP client (Task 4).
+ *
+ * Wire shapes are the channel contract — imported from the
+ * `@sigrun/shared` package (`views`, plus `SessionMeta`/`SlashCommand`
+ * siblings), the single source of truth shared with the server and the
+ * webui (build-and-webui Task 1: the tui is a pure client of the wire,
+ * never a relative importer of server source).
+ *
+ * Identity seam (Task 2): the configured `user` rides EVERY request as the
+ * `X-Sigrun-User` header; absent/empty user omits it entirely — the
+ * server's naive mode. The bearer token (Task 7) rides every request as
+ * `authorization: Bearer <token>` when configured.
+ *
+ * Fail-loud: a non-2xx rejects with a {@link SigrunApiError} carrying the
+ * status and the server's parsed error body (`{error: ...}`), never a
+ * silent `undefined` the UI could misrender as empty state.
+ */
+import type { CommandRunResponse, CommandsResponse } from "@sigrun/shared/commands";
+import type { JobsResponse, JobRunResponse } from "@sigrun/shared/views";
+import type { JobRevisionWire, JobRunWire } from "@sigrun/shared/jobs";
+import type { SessionMeta, SessionMetaPatch } from "@sigrun/shared/session-meta";
+import type { AbortResponse, AmbientList, CompactResponse, ConfigureResponse, ConversationCreateResponse, ConversationForkResponse, ConversationList, ConversationViewWire, InteractionAnswered, InteractionList, ModelsResponse, SettingsResponse, SubmissionResponse } from "@sigrun/shared/views";
+export type { AbortResponse, AmbientList, AmbientWire, CompactResponse, ConfigureResponse, ConversationCreateResponse, ConversationForkResponse, ConversationList, ConversationSummary, ConversationViewWire, InteractionAnswered, InteractionList, InteractionWire, ModelEntry, ModelsResponse, SettingsResponse, SubmissionResponse, } from "@sigrun/shared/views";
+export type { CommandRunResponse, CommandsResponse, SlashCommand } from "@sigrun/shared/commands";
+export type { JobSpec, JobSchedule, JobAction, JobWire, JobRunWire, JobRevisionWire, } from "@sigrun/shared/jobs";
+export type { JobsResponse, JobRunResponse } from "@sigrun/shared/views";
+export type { ExtensionsResponse, ExtensionInfo, ExtensionSurfaceInfo } from "@sigrun/shared/views";
+export type { SessionMeta, SessionMetaPatch } from "@sigrun/shared/session-meta";
+/** One answer to a pending interaction (the ONE generic route's body). */
+export interface InteractionAnswerInput {
+    readonly ids?: readonly string[];
+    readonly values?: Readonly<Record<string, string | number | boolean>>;
+    readonly text?: string;
+}
+/** `GET /v1/jobs/:id/runs`: the job's runs, newest first. */
+export interface JobRunsResponse {
+    readonly runs: readonly JobRunWire[];
+}
+/** `GET /v1/jobs/:id/revisions`: the job's revisions, newest first. */
+export interface JobRevisionsResponse {
+    readonly revisions: readonly JobRevisionWire[];
+}
+/** The `whenBusy` admission modes the server accepts (spec §7 item 3). */
+export type WhenBusyMode = "steer" | "followUp" | "reject";
+/** A non-2xx response: status + the server's parsed error body. */
+export declare class SigrunApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(method: string, path: string, status: number, body: unknown);
+}
+/** The fetch surface the client needs (the real thing or a test stub). */
+export type FetchLike = (input: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface SigrunClientOptions {
+    /**
+     * The server's origin (e.g. `http://127.0.0.1:PORT`) — the TUI is a
+     * remote client, so unlike the webui there is no same-origin default.
+     */
+    readonly baseUrl: string;
+    /**
+     * The `X-Sigrun-User` identity (Task 2). Absent/empty/whitespace → the
+     * header is omitted entirely (the server's naive mode).
+     */
+    readonly user?: string;
+    /**
+     * A bearer token (Task 7): rides EVERY request as
+     * `authorization: Bearer <token>`. Absent/empty/whitespace → omitted.
+     * The launcher threads `SIGRUN_TOKEN` here — the env beats tui.json.
+     */
+    readonly token?: string;
+    /** Injected for tests; defaults to the ambient `fetch`. */
+    readonly fetch?: FetchLike;
+}
+/** The typed §5 client. See {@link SigrunClientOptions} for the seams. */
+import type { ExtensionsResponse } from "@sigrun/shared/views";
+export declare class SigrunClient {
+    #private;
+    constructor(options: SigrunClientOptions);
+    /** `GET /v1/conversations` — all durable conversations (Task 3). */
+    listConversations(): Promise<ConversationList>;
+    /** `GET /v1/conversations/:id` — the full wire view (one frame). */
+    getConversation(id: number): Promise<ConversationViewWire>;
+    /** `POST /v1/conversations` — the new id plus its first view frame. */
+    createConversation(): Promise<ConversationCreateResponse>;
+    /** `POST /v1/conversations/:id/fork` (absent `at` = the newest entry). */
+    forkConversation(id: number, at?: number): Promise<ConversationForkResponse>;
+    /**
+     * `POST /v1/conversations/:id/submissions` — plain text input; 202 at
+     * ADMISSION (§7.1) with the record as it stands. The TUI is
+     * fire-and-forget: the reply arrives as view revisions on the stream,
+     * not from this response.
+     */
+    submit(id: number, text: string, whenBusy?: WhenBusyMode): Promise<SubmissionResponse>;
+    /** `POST /v1/conversations/:id/abort`. */
+    abort(id: number): Promise<AbortResponse>;
+    /**
+     * `POST /v1/conversations/:id/compact` — admits a manual compaction;
+     * the summary entry arrives later as a view revision on the stream.
+     */
+    compact(id: number, instructions?: string): Promise<CompactResponse>;
+    /** `GET /v1/conversations/:id/meta`. */
+    getMeta(id: number): Promise<SessionMeta>;
+    /** `PATCH /v1/conversations/:id/meta` — merges; resolves to the new meta. */
+    patchMeta(id: number, patch: SessionMetaPatch): Promise<SessionMeta>;
+    /** `GET /v1/conversations/:id/interactions` — pending interactions. */
+    listInteractions(id: number): Promise<InteractionList>;
+    /** `POST .../interactions/:callId/answer` — the ONE generic answer route. */
+    answerInteraction(id: number, callId: string, answer: InteractionAnswerInput): Promise<InteractionAnswered>;
+    /** `GET /v1/conversations/:id/ambient`. */
+    getAmbient(id: number): Promise<AmbientList>;
+    /** `GET /v1/commands` — the slash-command catalog (a boot constant). */
+    getCommands(): Promise<CommandsResponse>;
+    /** `GET /v1/extensions` — the loaded-extension inventory (U3 Task 5:
+     *  the sidebar's Views group + panels read the declared surfaces). */
+    listExtensions(): Promise<ExtensionsResponse>;
+    /**
+     * `POST /v1/conversations/:id/commands/:name` — invoke an extension
+     * slash command (W5 Task 3): the server runs the winning declaration
+     * and resolves with its optional `{notice}`.
+     */
+    runCommand(id: number, name: string, args?: string): Promise<CommandRunResponse>;
+    /** `GET /v1/settings` — the effective settings (absent file = `{}`). */
+    getSettings(): Promise<SettingsResponse>;
+    /** `GET /v1/models` — the chat-model catalog (the model picker's items). */
+    listModels(): Promise<ModelsResponse>;
+    /**
+     * `POST /v1/conversations/:id/configure` — change the model and/or
+     * thinking level (T9c-i). At least one field is required (the server
+     * rejects an empty change as `invalid_body`).
+     */
+    configure(id: number, body: {
+        readonly model?: string;
+        readonly thinking?: string;
+    }): Promise<ConfigureResponse>;
+    /** `GET /v1/jobs` — the caller-visible jobs (`/jobs`, W4 Task 5). */
+    listJobs(): Promise<JobsResponse>;
+    /** `POST /v1/jobs/:id/run` — fire a job now (write access). */
+    runJob(id: string): Promise<JobRunResponse>;
+    /** `GET /v1/jobs/:id/runs` — the job's runs, newest first. */
+    listJobRuns(id: string, limit?: number): Promise<JobRunsResponse>;
+    /** `GET /v1/jobs/:id/revisions` — the job's revisions, newest first. */
+    listJobRevisions(id: string): Promise<JobRevisionsResponse>;
+}

package/dist/api.js

@@ -0,0 +1,189 @@
+/**
+ * The TUI's typed §5 HTTP client (Task 4).
+ *
+ * Wire shapes are the channel contract — imported from the
+ * `@sigrun/shared` package (`views`, plus `SessionMeta`/`SlashCommand`
+ * siblings), the single source of truth shared with the server and the
+ * webui (build-and-webui Task 1: the tui is a pure client of the wire,
+ * never a relative importer of server source).
+ *
+ * Identity seam (Task 2): the configured `user` rides EVERY request as the
+ * `X-Sigrun-User` header; absent/empty user omits it entirely — the
+ * server's naive mode. The bearer token (Task 7) rides every request as
+ * `authorization: Bearer <token>` when configured.
+ *
+ * Fail-loud: a non-2xx rejects with a {@link SigrunApiError} carrying the
+ * status and the server's parsed error body (`{error: ...}`), never a
+ * silent `undefined` the UI could misrender as empty state.
+ */
+/** A non-2xx response: status + the server's parsed error body. */
+export class SigrunApiError extends Error {
+    status;
+    body;
+    constructor(method, path, status, body) {
+        super(`sigrun api: ${method} ${path} failed with status ${status}`);
+        this.name = "SigrunApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class SigrunClient {
+    #baseUrl;
+    #fetch;
+    #headers;
+    constructor(options) {
+        // A trailing slash would double every route's leading one
+        // (`--server http://host/` → `//v1/...`) — normalize once.
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#fetch =
+            options.fetch ??
+                ((input, init) => globalThis.fetch(input, init));
+        const user = options.user?.trim();
+        const token = options.token?.trim();
+        this.#headers = {
+            accept: "application/json",
+            ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
+            ...(token === undefined || token === ""
+                ? {}
+                : { authorization: `Bearer ${token}` }),
+        };
+    }
+    async #get(path) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method: "GET",
+            headers: this.#headers,
+        });
+        if (!response.ok) {
+            throw new SigrunApiError("GET", path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    }
+    async #send(method, path, body) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method,
+            headers: { ...this.#headers, "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new SigrunApiError(method, path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    }
+    /** `GET /v1/conversations` — all durable conversations (Task 3). */
+    listConversations() {
+        return this.#get("/v1/conversations");
+    }
+    /** `GET /v1/conversations/:id` — the full wire view (one frame). */
+    getConversation(id) {
+        return this.#get(`/v1/conversations/${id}`);
+    }
+    /** `POST /v1/conversations` — the new id plus its first view frame. */
+    createConversation() {
+        return this.#send("POST", "/v1/conversations", {});
+    }
+    /** `POST /v1/conversations/:id/fork` (absent `at` = the newest entry). */
+    forkConversation(id, at) {
+        return this.#send("POST", `/v1/conversations/${id}/fork`, {
+            ...(at === undefined ? {} : { at }),
+        });
+    }
+    /**
+     * `POST /v1/conversations/:id/submissions` — plain text input; 202 at
+     * ADMISSION (§7.1) with the record as it stands. The TUI is
+     * fire-and-forget: the reply arrives as view revisions on the stream,
+     * not from this response.
+     */
+    submit(id, text, whenBusy) {
+        return this.#send("POST", `/v1/conversations/${id}/submissions`, {
+            input: [{ type: "text", text }],
+            ...(whenBusy === undefined ? {} : { whenBusy }),
+        });
+    }
+    /** `POST /v1/conversations/:id/abort`. */
+    abort(id) {
+        return this.#send("POST", `/v1/conversations/${id}/abort`, {});
+    }
+    /**
+     * `POST /v1/conversations/:id/compact` — admits a manual compaction;
+     * the summary entry arrives later as a view revision on the stream.
+     */
+    compact(id, instructions) {
+        return this.#send("POST", `/v1/conversations/${id}/compact`, {
+            ...(instructions === undefined || instructions === ""
+                ? {}
+                : { instructions }),
+        });
+    }
+    /** `GET /v1/conversations/:id/meta`. */
+    getMeta(id) {
+        return this.#get(`/v1/conversations/${id}/meta`);
+    }
+    /** `PATCH /v1/conversations/:id/meta` — merges; resolves to the new meta. */
+    patchMeta(id, patch) {
+        return this.#send("PATCH", `/v1/conversations/${id}/meta`, patch);
+    }
+    /** `GET /v1/conversations/:id/interactions` — pending interactions. */
+    listInteractions(id) {
+        return this.#get(`/v1/conversations/${id}/interactions`);
+    }
+    /** `POST .../interactions/:callId/answer` — the ONE generic answer route. */
+    answerInteraction(id, callId, answer) {
+        return this.#send("POST", `/v1/conversations/${id}/interactions/${encodeURIComponent(callId)}/answer`, answer);
+    }
+    /** `GET /v1/conversations/:id/ambient`. */
+    getAmbient(id) {
+        return this.#get(`/v1/conversations/${id}/ambient`);
+    }
+    /** `GET /v1/commands` — the slash-command catalog (a boot constant). */
+    getCommands() {
+        return this.#get("/v1/commands");
+    }
+    /** `GET /v1/extensions` — the loaded-extension inventory (U3 Task 5:
+     *  the sidebar's Views group + panels read the declared surfaces). */
+    listExtensions() {
+        return this.#get("/v1/extensions");
+    }
+    /**
+     * `POST /v1/conversations/:id/commands/:name` — invoke an extension
+     * slash command (W5 Task 3): the server runs the winning declaration
+     * and resolves with its optional `{notice}`.
+     */
+    runCommand(id, name, args) {
+        return this.#send("POST", `/v1/conversations/${id}/commands/${encodeURIComponent(name)}`, {
+            args: args ?? "",
+        });
+    }
+    /** `GET /v1/settings` — the effective settings (absent file = `{}`). */
+    getSettings() {
+        return this.#get("/v1/settings");
+    }
+    /** `GET /v1/models` — the chat-model catalog (the model picker's items). */
+    listModels() {
+        return this.#get("/v1/models");
+    }
+    /**
+     * `POST /v1/conversations/:id/configure` — change the model and/or
+     * thinking level (T9c-i). At least one field is required (the server
+     * rejects an empty change as `invalid_body`).
+     */
+    configure(id, body) {
+        return this.#send("POST", `/v1/conversations/${id}/configure`, body);
+    }
+    /** `GET /v1/jobs` — the caller-visible jobs (`/jobs`, W4 Task 5). */
+    listJobs() {
+        return this.#get("/v1/jobs");
+    }
+    /** `POST /v1/jobs/:id/run` — fire a job now (write access). */
+    runJob(id) {
+        return this.#send("POST", `/v1/jobs/${encodeURIComponent(id)}/run`, {});
+    }
+    /** `GET /v1/jobs/:id/runs` — the job's runs, newest first. */
+    listJobRuns(id, limit) {
+        return this.#get(`/v1/jobs/${encodeURIComponent(id)}/runs` +
+            (limit === undefined ? "" : `?limit=${limit}`));
+    }
+    /** `GET /v1/jobs/:id/revisions` — the job's revisions, newest first. */
+    listJobRevisions(id) {
+        return this.#get(`/v1/jobs/${encodeURIComponent(id)}/revisions`);
+    }
+}

package/dist/blocks/braille.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The Braille dot canvas and the display ramps (UI-blocks spec §5.4):
+ * the pieces `chart` and the narrow-fallback sparkline draw with.
+ *
+ * - {@link BrailleCanvas} is a `cells×rows` cell grid of 2×4 dot
+ *   subpixels (Unicode Braille Patterns, U+2800 base). Each cell also
+ *   records the index of the series that plotted into it LAST, which
+ *   is how multi-colour charts colour a shared cell.
+ * - {@link sparkline} renders a value series onto the eighth-block
+ *   ramp `▁▂▃▄▅▆▇█` (or the ASCII ramp `_.,-+=*#` on a no-Unicode
+ *   terminal), downsampling with the shared `lttb` when the series is
+ *   longer than the cell budget.
+ */
+/** A Braille dot canvas: `cells` columns × `rows` rows of 2×4 dots. */
+export declare class BrailleCanvas {
+    #private;
+    constructor(cells: number, rows: number);
+    /** Plot one dot; out-of-range coordinates are ignored. */
+    plot(x: number, y: number, series?: number): void;
+    /** A straight dot-space line from (x0, y0) to (x1, y1): the steps
+     * are the CHEBYSHEV distance (diagonal-adjacent dots step one
+     * dot-space cell at a time). */
+    line(x0: number, y0: number, x1: number, y1: number, series?: number): void;
+    /** Fill the dot rectangle (x0..x1, y0..y1) inclusive. */
+    fill(x0: number, y0: number, x1: number, y1: number, series?: number): void;
+    /** The dot bits set in one cell. */
+    cellBits(cellX: number, cellY: number): number;
+    /** The series index that plotted into this cell last (−1: none). */
+    cellOwner(cellX: number, cellY: number): number;
+    /** Clear one cell row (a threshold rule paints over it). */
+    blankRow(cellY: number): void;
+    /** The canvas as one Braille string per cell row. */
+    rows(): string[];
+}
+/**
+ * A one-cell-per-sample sparkline of `values`, at most `maxCells`
+ * cells (longer series downsample with `lttb`, keeping both ends).
+ * `unicode: false` selects the ASCII ramp. Empty input renders empty;
+ * a flat series renders mid-height cells.
+ */
+export declare function sparkline(values: readonly number[], maxCells: number, unicode: boolean): string;