@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/web-react/record-grid.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `RecordGrid` — the editable record table four verticals each hand-rolled: a
+ * cap table, two relationship record pages, a content board, and an entities
+ * panel. Every copy re-derived the same mechanism and each one lost a
+ * different part of it.
+ *
+ * What this owns:
+ *
+ *  - **Typed columns with correctable errors.** A cell is text / number /
+ *    currency / date / select / boolean (`./record-grid-model`), so a rejected
+ *    edit explains itself next to the control instead of storing a coerced
+ *    value.
+ *  - **Optimistic write with a real rollback.** The edit lands instantly, the
+ *    caller's writer returns a typed outcome, and a failure puts the previous
+ *    value back AND says why. A grid that keeps a value the server refused is
+ *    the defect this replaces.
+ *  - **Provenance per cell.** An optional quote + link + basis, so a
+ *    record-backed grid shows where a value came from without the product
+ *    building a second surface for it.
+ *  - **Three distinct data states, on `web-react/async`'s own contract.**
+ *    `state: AsyncResourceState<Row[]>` and `empty: AsyncEmptySpec` are the
+ *    same types every other screen fetches through — loading, error-with-
+ *    retry and empty are different renders, a failed fetch never looks like
+ *    "no data yet", and the empty state carries the CALLER's next action.
+ *    The optimistic overlay is layered on top of whichever `ready`/`empty`
+ *    value the caller last supplied, so a row created while the caller's own
+ *    status is still `empty` renders immediately rather than waiting for a
+ *    refetch.
+ *  - **Keyboard-navigable, labelled controls.** Arrow keys move between cells,
+ *    Enter edits, Escape cancels, and no destructive control is an unlabelled
+ *    icon.
+ *
+ * Presentation is Tailwind against the shared design tokens, with no icon
+ * library and no sandbox-ui — the same contract as the rest of `/web-react`.
+ */
+import { type ReactNode } from 'react';
+import { type AsyncEmptySpec, type AsyncResourceState } from './async';
+import { type RecordGridColumn, type RecordGridRow, type RecordGridValue } from './record-grid-model';
+export * from './record-grid-model';
+/** One committed cell edit, handed to `onUpdate`. */
+export interface RecordGridCellChange {
+    /** The row as it was BEFORE the edit — what rollback restores. */
+    row: RecordGridRow;
+    columnId: string;
+    value: RecordGridValue;
+    /** The full value bag after the edit: what a whole-row write would send. */
+    values: Readonly<Record<string, RecordGridValue>>;
+}
+/** Outcome of an update or a delete. `value` optionally carries the server's
+ *  canonical row, which replaces the optimistic one. */
+export type RecordGridWriteOutcome = {
+    succeeded: true;
+    value?: RecordGridRow;
+} | {
+    succeeded: false;
+    error: string;
+};
+/** Outcome of a create. The row is REQUIRED on success: a create that does not
+ *  name the row it wrote leaves the grid unable to address it. */
+export type RecordGridCreateOutcome = {
+    succeeded: true;
+    value: RecordGridRow;
+} | {
+    succeeded: false;
+    error: string;
+};
+/** Properties for the editable, provenance-aware record grid. */
+export interface RecordGridProps {
+    /** Column definitions, in render order. */
+    columns: readonly RecordGridColumn[];
+    /** Fetch state over the caller's rows — `web-react/async`'s
+     *  `AsyncResourceState`, the same three-state contract every other screen
+     *  in the shell fetches through. `ready`/`empty`'s value is the base rows;
+     *  optimistic edits are layered over it and dropped as a later value
+     *  catches up. `error` always carries `retry` — there is no way to render a
+     *  failed fetch with no recovery action, by construction. */
+    state: AsyncResourceState<readonly RecordGridRow[]>;
+    /** Accessible name for the grid. Required — an unnamed grid is unusable with
+     *  a screen reader. */
+    caption: string;
+    /** What the empty state says, and what it offers next — `web-react/async`'s
+     *  `AsyncEmptySpec`, so an empty grid reads in the same words as an empty
+     *  list or panel elsewhere in the product. */
+    empty: AsyncEmptySpec;
+    /** Persist one created row. Absent → no add affordance. */
+    onCreate?: (values: Readonly<Record<string, RecordGridValue>>) => Promise<RecordGridCreateOutcome>;
+    /** Persist one cell edit. Absent → every cell renders read-only. */
+    onUpdate?: (change: RecordGridCellChange) => Promise<RecordGridWriteOutcome>;
+    /** Delete one row. Absent → no delete affordance. */
+    onDelete?: (row: RecordGridRow) => Promise<RecordGridWriteOutcome>;
+    /** Starting values for the add form. */
+    newRowDefaults?: Readonly<Record<string, RecordGridValue>>;
+    /** Label of the add control and of the add form. Defaults to `Add row`. */
+    addLabel?: string;
+    /** BCP-47 locale for number, currency, and date display. */
+    locale?: string;
+    /** Rendered above the grid — filters, counts, a product action row. */
+    toolbar?: ReactNode;
+    /** Skeleton rows in the loading state. Defaults to 3. */
+    loadingRowCount?: number;
+    className?: string;
+}
+/**
+ * The shared editable record table. A row is a flat value bag keyed by column
+ * id, so a record store's fold output maps straight on: one cell per entry,
+ * its quote and link in `sources`.
+ */
+export declare function RecordGrid({ columns, caption, state, empty, onCreate, onUpdate, onDelete, newRowDefaults, addLabel, locale, toolbar, loadingRowCount, className, }: RecordGridProps): import("react").JSX.Element;

package/dist/web-react/sandbox-terminal.d.ts

@@ -0,0 +1,90 @@
+/** Define the connection details and status for a sandbox terminal session */
+export interface SandboxTerminalConnection {
+    runtimeUrl: string | null;
+    sidecarUrl: string | null;
+    token: string | null;
+    expiresAt: string | null;
+    status: string;
+    error: string | null;
+    loading: boolean;
+    sandboxId?: string;
+    connectionId?: string;
+}
+/**
+ * Define the response structure for a sandbox terminal connection including URLs, token, status, and errors
+ *
+ * The browser-direct scoped-token route (`createSandboxTerminalConnectionRoute`,
+ * `src/sandbox/terminal-connection.ts`) returns `sidecarUrl`. The hook also
+ * exposes that URL through the historical `runtimeUrl` state field so existing
+ * terminal panels do not need transport-specific branching.
+ *
+ * `connectionId` is the id the route's minted token's `sid` is bound to
+ * (echoed back from the `connectionId` the hook sent) — pass it straight
+ * through as `TerminalView`'s `connectionId` prop, since any other value
+ * fails the WS upgrade on the current platform.
+ */
+export interface SandboxTerminalConnectionResponse {
+    runtimeUrl?: string;
+    sidecarUrl?: string;
+    token?: string;
+    expiresAt?: string;
+    status?: string;
+    error?: string;
+    sandboxId?: string;
+    connectionId?: string;
+}
+/**
+ * Define options for configuring a sandbox terminal connection including workspace ID and connection parameters
+ *
+ * `connectionId`, when set, is passed to
+ * `createSandboxTerminalConnectionRoute` as the `connectionId` query
+ * parameter — pass `tabTerminalConnectionId()` here so the route mints a
+ * token whose `sid` is bound to the same id `TerminalView` will dial. Give
+ * `TerminalView` the response's echoed `connectionId` (not this input
+ * value) alongside `sidecarUrl` as `apiUrl` and `token`, since a product's
+ * `resolveConnectionId` seam may rewrite it server-side.
+ */
+export interface UseSandboxTerminalConnectionOptions {
+    workspaceId: string;
+    connectionUrl?: string | ((workspaceId: string) => string);
+    connectionId?: string;
+    fetcher?: typeof fetch;
+    provisionPollIntervalMs?: number;
+    provisionPollTimeoutMs?: number;
+    tokenRefreshSkewMs?: number;
+}
+/** Resolve sandbox terminal connection status and provide a method to initiate the connection */
+export interface UseSandboxTerminalConnectionResult extends SandboxTerminalConnection {
+    connect: () => Promise<void>;
+}
+/**
+ * Manage and maintain a sandbox terminal connection with automatic polling and token refresh handling
+ *
+ * `connectionUrl` is backed by the browser-direct scoped-token route
+ * (`createSandboxTerminalConnectionRoute`,
+ * `src/sandbox/terminal-connection.ts`). The route returns `sidecarUrl`; the
+ * hook normalizes it into both URL fields for compatibility with existing
+ * terminal panels.
+ *
+ * Pass `tabTerminalConnectionId()` as `opts.connectionId` — the hook forwards
+ * it as the `connectionId` query parameter the browser-direct route requires
+ * to mint a token whose `sid` is bound to that exact id (the orchestrator's
+ * terminal WS gate fails closed on any other value). Give `TerminalView` the
+ * RESULT's echoed `connectionId` (not the input value — a product's
+ * `resolveConnectionId` seam may rewrite it), the resolved `sidecarUrl`/
+ * `runtimeUrl` as `apiUrl`, and `token` as its token prop.
+ */
+export declare function useSandboxTerminalConnection(opts: UseSandboxTerminalConnectionOptions): UseSandboxTerminalConnectionResult;
+/**
+ * Stable-per-tab, unique-per-client terminal connection id.
+ *
+ * Persists in `sessionStorage` so a reload in the same tab reuses the id (the
+ * sidecar restores the same PTY session via `TerminalView.connectionId`), while
+ * separate tabs/windows each get a distinct id. Pass the result as
+ * `TerminalView`'s `connectionId`. Without it (e.g. gtm-agent today) every tab
+ * shares one connection id and their reconnects evict each other.
+ *
+ * Falls back to an ephemeral id when `sessionStorage` is unavailable (SSR,
+ * privacy mode) — still unique per call, just not reload-stable.
+ */
+export declare function tabTerminalConnectionId(storageKey?: string): string;

package/dist/web-react/seat-paywall.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `SeatPaywall` — the shared "unlock this product" screen every agent app
+ * shows when a user has no active seat and has spent past the free tier.
+ *
+ * Copy contract (design §6.8): the included monthly AI usage is framed as a
+ * BENEFIT the buyer receives — never the ratio, never the word "margin", never
+ * "we debit 50%". Surface the allowance, hide the economics.
+ *
+ * Styling contract matches the rest of `web-react`: Tailwind classes over the
+ * shared design tokens (`bg-card`, `border-border`, `text-muted-foreground`,
+ * `bg-primary`, …); glyphs are inline SVGs; no icon or UI library.
+ */
+import type { ReactNode } from 'react';
+import type { ProductSeatOffer } from '../platform/billing';
+export interface SeatPaywallProps {
+    /** Human product name shown in the headline, e.g. "Creative". */
+    product: string;
+    /** Fired when the user clicks the unlock CTA — route them to checkout. When
+     *  it returns a promise the button shows a pending state and ignores repeat
+     *  clicks until it settles (no double-charge on a slow checkout open). */
+    onCheckout: () => void | Promise<void>;
+    /** Monthly seat price in whole dollars. Default 100. */
+    priceUsd?: number;
+    /** Included monthly AI usage in whole dollars. Default 50. */
+    includedUsageUsd?: number;
+    /** Platform catalog terms. When present, these override the legacy dollar
+     * props and show any introductory period without product-local price copy. */
+    offer?: ProductSeatOffer;
+    /** Optional one-line value prop under the headline. */
+    tagline?: string;
+    /** CTA label. Default "Continue to checkout". */
+    ctaLabel?: string;
+    /** Value-prop bullets. Default = product/usage-derived only; pass your own to
+     *  supply product-specific value props (the shell bakes no GTM copy). */
+    benefits?: ReactNode[];
+    /** Optional fine print under the CTA (e.g. "Cancel anytime."). Omitted by default. */
+    footnote?: ReactNode;
+}
+/**
+ * Centered card paywall. The price line reads
+ * "$100/mo · includes $50/mo of AI usage" so the included allowance anchors the
+ * value without ever exposing the ratio — and says it ONCE: the default
+ * benefits don't restate the usage line the subline already carries, and the
+ * CTA is the next step ("Continue to checkout"), not a third repeat of the
+ * eyebrow + headline's "Unlock {product}".
+ */
+export declare function SeatPaywall({ product, onCheckout, priceUsd, includedUsageUsd, offer, tagline, ctaLabel, benefits, footnote, }: SeatPaywallProps): ReactNode;

package/dist/web-react/session-history.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The rendered half of the session shell: the history view behind the rail's
+ * session list, and the rename/delete dialogs both surfaces drive.
+ *
+ * Storage is a seam, not a dependency. Every product keeps sessions somewhere
+ * different (gtm threads, tax sessions, legal matters), so this takes a
+ * `fetchPage` data port and injected mutations — the same shape
+ * `AgentActivityPanel` (`fetchActivity`) and `ReviewQueuePanel` (`fetchQueue`)
+ * already use, rather than a fifth pattern.
+ *
+ * sandbox-ui free on purpose: `/web-react` must not force the optional peer, so
+ * these render on the shared design tokens like the rest of the subpath. The
+ * pure logic (nav items, routing, cookies, merging) lives in `/session-shell`,
+ * which a server loader can import without pulling React.
+ */
+import { type ReactNode, type RefObject } from 'react';
+import { type SessionPage, type SessionRailAction, type SessionSort, type SessionSummary } from '../session-shell/index';
+export interface UseInfiniteScrollOptions {
+    /** Only fire `onLoadMore` while true (a next page exists, none in flight). */
+    enabled: boolean;
+    /** Scroll container the sentinel lives in. Defaults to the viewport. */
+    root?: RefObject<HTMLElement | null>;
+    /** Prefetch distance before the sentinel is actually reached. */
+    rootMargin?: string;
+}
+/**
+ * Fires `onLoadMore` when a sentinel element scrolls into view. Returns a ref
+ * callback for that sentinel (typically the last element in a list).
+ *
+ * The observer is re-created whenever `enabled` flips, so a short first page
+ * that leaves the sentinel on-screen keeps loading: when a load finishes and
+ * `enabled` returns to true, the fresh observer re-reads the current
+ * intersection state and fires again until the sentinel is pushed off-screen.
+ */
+export declare function useInfiniteScroll(onLoadMore: () => void, { enabled, root, rootMargin }: UseInfiniteScrollOptions): (node: HTMLElement | null) => void;
+export interface SessionPageQuery {
+    /** Trimmed search term; empty string means no filter. */
+    q: string;
+    sort: SessionSort;
+    /** `null` for the first page. */
+    cursor: string | null;
+    /** Aborted when the view changes or the component unmounts. */
+    signal: AbortSignal;
+}
+/** Data port — one page of sessions for the current view. */
+export type FetchSessionPage = (query: SessionPageQuery) => Promise<SessionPage>;
+export interface UseSessionHistoryOptions {
+    fetchPage: FetchSessionPage;
+    /** Trimmed search term driving the fetch. */
+    q: string;
+    sort: SessionSort;
+    /** SSR page 1 of the default view, so the first paint costs no request. */
+    initialPage: SessionPage;
+    /** The sort `initialPage` was rendered for. Default `'newest'`. */
+    defaultSort?: SessionSort;
+}
+export interface SessionHistoryState {
+    items: SessionSummary[];
+    hasMore: boolean;
+    isLoadingFirst: boolean;
+    isLoadingMore: boolean;
+    isError: boolean;
+    loadMore: () => void;
+    /** Re-run whichever load failed. */
+    retry: () => void;
+    /** Refetch page 1 — call after a client-side mutation (e.g. a delete). */
+    reload: () => void;
+}
+/**
+ * Infinite-scroll data source for the history view. Seeds from `initialPage`
+ * for the default view (no fetch) and otherwise fetches page 1 for the current
+ * search/sort; `loadMore` appends the next cursor page.
+ *
+ * Raw promises + `AbortController` rather than a router fetcher, so a filter
+ * change cancels in-flight requests, pages accumulate, and a late response from
+ * a superseded view is dropped by the monotonic `seq` guard.
+ */
+export declare function useSessionHistory({ fetchPage, q, sort, initialPage, defaultSort, }: UseSessionHistoryOptions): SessionHistoryState;
+export interface SessionActionsOptions {
+    /** Persist a new title. Reject to surface the error in the dialog. */
+    renameSession: (sessionId: string, title: string) => Promise<void>;
+    deleteSession: (sessionId: string) => Promise<void>;
+    /** Called after a successful rename/delete — revalidate the rail here. */
+    onChanged?: () => void;
+    /** Called after deleting the session the user is currently viewing, so the
+     *  product can navigate away from a route that no longer resolves. */
+    onDeletedCurrent?: () => void;
+    /** The open session, compared against the delete target. */
+    currentSessionId?: string | null;
+    /** Product toast/log seam. Errors also render inside the dialog. */
+    notify?: (level: 'success' | 'error', message: string) => void;
+    labels?: Partial<SessionActionLabels>;
+}
+export interface SessionActionLabels {
+    renameTitle: string;
+    renameField: string;
+    renameSubmit: string;
+    deleteTitle: string;
+    deleteBody: (title: string) => string;
+    deleteSubmit: string;
+    cancel: string;
+    renamed: string;
+    deleted: string;
+    renameFailed: string;
+    deleteFailed: string;
+}
+export interface SessionActions {
+    openRename: (session: SessionSummary) => void;
+    openDelete: (session: SessionSummary) => void;
+    /** Render once, anywhere that survives navigation (the layout). */
+    dialogs: ReactNode;
+    busy: boolean;
+}
+/**
+ * Rename + delete for one session, shared by the rail kebab and the history
+ * row menu so both drive the same dialogs and the same product mutations.
+ *
+ * Dialogs are owned here rather than returned as raw state: two surfaces
+ * needing the same confirm step is exactly how a product ends up with two
+ * subtly different delete confirmations.
+ */
+export declare function useSessionActions({ renameSession, deleteSession, onChanged, onDeletedCurrent, currentSessionId, notify, labels, }: SessionActionsOptions): SessionActions;
+export interface SessionHistoryPanelProps {
+    history: SessionHistoryState;
+    /** Whether the workspace has any sessions at all — decided by the SSR page,
+     *  independent of the active search, so filtering to zero shows "no matches"
+     *  rather than the first-run empty state. */
+    hasAnySessions: boolean;
+    query: string;
+    onQueryChange: (value: string) => void;
+    sort: SessionSort;
+    onSortChange: (value: SessionSort) => void;
+    /** Product route for one session row. */
+    hrefForSession: (sessionId: string) => string;
+    /** Rendered as the row link. Defaults to an `<a>`; pass a router Link to keep
+     *  client-side navigation. */
+    linkComponent?: LinkLikeComponent;
+    /** Ids currently mid-turn — renders the responding treatment. */
+    respondingSessionIds?: ReadonlySet<string>;
+    onRename?: (session: SessionSummary) => void;
+    onDelete?: (session: SessionSummary) => void;
+    /** Product-owned mutation for selected rows or a workspace-wide age range. */
+    onBulkAction?: (action: SessionBulkAction) => Promise<void>;
+    /** Menu wording, so this surface and the rail name the same act the same way
+     *  — a product whose delete is really an archive says so in both places. */
+    renameLabel?: string;
+    deleteLabel?: string;
+    /**
+     * Row actions this shell has no opinion about — pin, categorise, share.
+     * Same seam and same ordering as the rail's `SessionRowActions.extraActions`:
+     * evaluated per session, placed between rename and delete. This menu is
+     * text-only, so `icon` is ignored here and honoured on the rail.
+     */
+    extraActions?: (session: SessionSummary) => SessionRailAction[];
+    /** New-session destination for the header action. Omitted ⇒ no button. */
+    newSessionHref?: string;
+    title?: string;
+    untitledLabel?: string;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    /** Absolute → relative timestamp. Defaults to a compact built-in. */
+    formatTimestamp?: (isoDate: string | null) => string;
+    /** Max width of the reading column. `'full'` opts out for a product whose
+     *  surface really is a wide table. Default keeps title and timestamp inside
+     *  one scannable line rather than at opposite edges of a 1440px viewport. */
+    contentWidth?: 'reading' | 'full';
+    className?: string;
+}
+export type SessionBulkAction = {
+    kind: 'selected';
+    ids: string[];
+} | {
+    kind: 'older-than';
+    days: number;
+} | {
+    kind: 'newer-than';
+    days: number;
+};
+export interface LinkLikeProps {
+    to: string;
+    className?: string;
+    children?: ReactNode;
+}
+export type LinkLikeComponent = (props: LinkLikeProps) => ReactNode;
+/** Compact relative time. Overridable — a product with its own i18n passes
+ *  `formatTimestamp` rather than this being the only option. */
+export declare function formatSessionTimestamp(isoDate: string | null): string;
+/**
+ * The full session history: search, sort, cursor-paged rows with per-row
+ * actions, and the states in between (first-run empty, loading, no matches,
+ * error + retry).
+ *
+ * This is the surface the rail's capped list overflows into — the reason the
+ * rail can stay short without hiding the user's work.
+ */
+export declare function SessionHistoryPanel({ history, hasAnySessions, query, onQueryChange, sort, onSortChange, hrefForSession, linkComponent: Link, respondingSessionIds, onRename, onDelete, onBulkAction, renameLabel, deleteLabel, extraActions, newSessionHref, title, untitledLabel, emptyTitle, emptyDescription, formatTimestamp, contentWidth, className, }: SessionHistoryPanelProps): import("react").JSX.Element;

package/dist/web-react/smooth-text.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Smooth text reveal — turns chunky network deltas into a continuous
+ * typewriter paint. Streamed turns arrive in 100-500ms slabs (model burst,
+ * flush windows, replay polls); revealing characters at an adaptive rate
+ * makes the same bytes read as top-tier streaming. The rate scales with the
+ * backlog so the reveal never falls behind the stream — it crawls when caught
+ * up and sprints when a burst lands (e.g. a reasoning summary arriving all at
+ * once still *types out* instead of popping in).
+ */
+/** Define configuration options for controlling smooth text reveal animation rates */
+export interface SmoothRevealOptions {
+    /** Baseline reveal rate when nearly caught up. Default 90 chars/s. */
+    baseCharsPerSecond?: number;
+    /** Extra chars/s per backlog character — the catch-up pressure. Default 5. */
+    catchUpPerChar?: number;
+    /** Hard ceiling so giant bursts still animate. Default 2400 chars/s. */
+    maxCharsPerSecond?: number;
+}
+/** Pure reveal step: how many characters should be visible after `dtMs`.
+ *  Exposed for tests; the hook is a thin rAF wrapper around it. */
+export declare function nextRevealCount(shown: number, targetLength: number, dtMs: number, opts?: SmoothRevealOptions): number;
+/**
+ * Animate `target` text into view. While `enabled`, the returned string grows
+ * smoothly toward `target` (which may itself keep growing); when `enabled` is
+ * false the full text returns immediately (history, completed turns). A
+ * target that is not an extension of the revealed prefix (new message) resets
+ * the reveal.
+ */
+export declare function useSmoothText(target: string, enabled: boolean, opts?: SmoothRevealOptions): string;

package/dist/web-react/sparkline.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `Sparkline` — the series behind a number, as inline SVG.
+ *
+ * `/spend`, `/missions` and the eval lanes all produce a number for today, and
+ * every product renders it as text. Text cannot separate "$41, up from $38"
+ * from "$41, up from $4" — the same sentence, two different situations — so the
+ * reader opens a second surface to find out which one they are in. The series
+ * next to the number answers it in one glance.
+ *
+ * No chart dependency: this subpath is react + `@tangle-network/ui` only, and a
+ * polyline is not worth a bundle. What a chart library would give us here is
+ * axes, ticks and a tooltip, none of which belong on a 96×24 glyph.
+ *
+ * The three shapes a hand-rolled sparkline gets wrong, each handled here rather
+ * than left to the caller:
+ *
+ *  - **no readings** renders an explicit empty label, never a line. A line
+ *    along the baseline is a claim — "this metric sat at zero" — and a series
+ *    nobody has measured yet did not sit anywhere.
+ *  - **one reading** renders a point. A line needs two coordinates; drawing one
+ *    from a single reading invents the segment before it.
+ *  - **equal readings** render flat at MID height. The obvious normalisation
+ *    divides by `max - min`, which is `0` for a perfectly stable metric, and
+ *    the resulting `NaN` lands in the `points` attribute — SVG drops the whole
+ *    polyline, so the metric that never moved is the one that disappears.
+ *  - **a missing reading renders as a GAP, and the accessible name says so.**
+ *    A `null` from a hole in a series and a `NaN` from a producer's unguarded
+ *    division are not smaller series — they are readings nobody has. Deleting
+ *    them closed the line straight across the hole and announced a count that
+ *    was short by the number deleted: measured on `[1, NaN, 3]`, one continuous
+ *    two-point line labelled "2 readings, rising from 1 to 3", with nothing
+ *    anywhere saying a reading was unreadable. The card's figure slot already
+ *    refuses to let a non-measurement look measured; the series one line below
+ *    it holds the same rule. The x axis is the SAMPLE index, so the hole keeps
+ *    its width, the line breaks at it, and the label carries "N not available".
+ *
+ * Accessibility: `role="img"` with an `aria-label` naming the metric, its range
+ * and its direction. A sparkline with no accessible name is decoration a screen
+ * reader cannot report, which would leave the shape — the entire reason the
+ * component exists — visible to exactly one kind of reader.
+ *
+ * Deliberately not animated. `docs/product-surfaces.md` Pattern 4 lists chart
+ * draw-on under what this package does not animate: the shape IS the answer,
+ * and easing it in taxes every read of a surface people sit in for hours. The
+ * card around it arrives (`.agent-arrive`); the line does not draw itself.
+ */
+import type { ReactElement } from 'react';
+/** Where a series ended relative to where it started. */
+export type SparklineDirection = 'rising' | 'falling' | 'flat';
+export interface SparklinePoint {
+    readonly x: number;
+    readonly y: number;
+}
+export interface SparklineGeometry {
+    /** The finite readings, in order — what was actually plotted. */
+    readonly readings: readonly number[];
+    /** Every plotted point, in order. Positions are on the SAMPLE axis, so a
+     *  missing reading leaves its width behind rather than closing up. */
+    readonly points: readonly SparklinePoint[];
+    /** The points split into runs of CONSECUTIVE samples. One run is one stroke:
+     *  a line drawn across a missing reading states a movement nobody measured. */
+    readonly segments: readonly (readonly SparklinePoint[])[];
+    /** Samples that carried no usable reading — a `null`, a `NaN`, an infinity.
+     *  Counted rather than discarded, because the accessible name has to state
+     *  them: a shorter series announced as a complete one is the silent loss. */
+    readonly gaps: number;
+    readonly min: number;
+    readonly max: number;
+    readonly first: number;
+    readonly last: number;
+    readonly direction: SparklineDirection;
+}
+export interface SparklineGeometryOptions {
+    width?: number;
+    height?: number;
+    /** Keeps the stroke and the end dot inside the viewBox instead of clipping
+     *  them at the extremes, where the interesting readings always are. */
+    inset?: number;
+}
+export declare const DEFAULT_SPARKLINE_WIDTH = 96;
+export declare const DEFAULT_SPARKLINE_HEIGHT = 24;
+/** Only a name, never a metric: it exists so the accessible label is never
+ *  empty. Every caller in this package passes the metric's own title. */
+export declare const DEFAULT_SPARKLINE_LABEL = "Trend";
+export declare const DEFAULT_SPARKLINE_EMPTY_LABEL = "No history yet";
+/** Nothing was measurable, which is not the same as nothing was measured yet —
+ *  and "No history yet" over a series that arrived full of `NaN` reads as the
+ *  metric being new when the producer is broken. */
+export declare const DEFAULT_SPARKLINE_UNAVAILABLE_LABEL = "No readings available";
+/** The package's default number rendering, pinned to `en-US` so a card and its
+ *  series read the same on every host — a series formatted by the server's
+ *  locale and a value formatted by the browser's is a defect nobody sees until
+ *  the decimal separators disagree. */
+export declare function formatSparklineValue(value: number): string;
+/**
+ * The readings that can be plotted.
+ *
+ * A `null` from a gap in a series, or a `NaN` from a division a producer did
+ * not guard, is not plotted rather than coerced to `0`: plotting a missing
+ * reading at the baseline draws a cliff that never happened.
+ *
+ * This returns the readings ALONE, so it cannot tell a caller how many are
+ * missing. That is what {@link SparklineGeometry.gaps} is for, and what the
+ * accessible name reports — dropping a sample and then announcing the shorter
+ * count as the whole series is the defect, not the filter.
+ */
+export declare function sparklineReadings(values: readonly number[]): number[];
+/**
+ * Plots the series into the viewBox.
+ *
+ * Pure and exported so the cases that produce a broken chart — nothing, one
+ * reading, a flat series, negatives — are unit-testable without a DOM.
+ */
+export declare function sparklineGeometry(values: readonly number[], { width, height, inset }?: SparklineGeometryOptions): SparklineGeometry;
+/** `"2,14 48,3 94,21"` — the `points` attribute of the polyline. */
+export declare function sparklinePointsAttribute(points: readonly SparklinePoint[]): string;
+export interface SparklineLabelOptions {
+    label?: string;
+    format?: (value: number) => string;
+}
+/**
+ * The accessible name: metric, how many readings, how many are missing, the
+ * range, and the direction.
+ *
+ * All of it is load-bearing. The range without the direction describes a shape
+ * that could have been walked in either order; the direction without the range
+ * says "rising" about a metric that moved by a rounding error; and the count
+ * without the gaps is the number of readings that SURVIVED announced as the
+ * number that were taken — the shape a reader cannot see is exactly the one
+ * this sentence exists to carry.
+ */
+export declare function sparklineLabel(values: readonly number[], { label, format }?: SparklineLabelOptions): string;
+export interface SparklineProps {
+    values: readonly number[];
+    /** Names the metric in the accessible label. */
+    label?: string;
+    /** Renders a reading in that label; defaults to the package number format. */
+    format?: (value: number) => string;
+    width?: number;
+    height?: number;
+    /** Shown instead of a line when the metric has no history yet. */
+    emptyLabel?: string;
+    /** Shown instead of a line when every sample arrived unreadable — a different
+     *  state from "no history yet", and one the reader has to be able to tell
+     *  apart, because one is a new metric and the other is a broken producer. */
+    unavailableLabel?: string;
+    className?: string;
+}
+/** The series glyph. Strokes in `currentColor`, so tone is the caller's. */
+export declare function Sparkline({ values, label, format, width, height, emptyLabel, unavailableLabel, className, }: SparklineProps): ReactElement;