@xenosystem/blocks 0.4.1 → 0.5.0

package/dist/data/index.d.ts

@@ -0,0 +1,3255 @@
+import { PanelModule, PanelManifest, LogSink } from '@xenosystem/panel-sdk';
+import * as _xenosystem_data_core from '@xenosystem/data-core';
+import { XenoColumn, XenoQuery, XenoResultSet, XenoValue, XenoRow, XenoAggFn, XenoValueFormat, XenoFilterGroup, XenoColumnRole, XenoSchemaCatalog, XenoFilter, XenoSourceSchema } from '@xenosystem/data-core';
+import { ReactNode } from 'react';
+import { C as ConnectorExecuteInput, a as ConnectorExecuteOutput, b as ConnectorsPanelState, S as SubstrateFacilities, c as ConnectorsViewState, d as XenoConnection, e as XenoCredentialFormSpec, f as XenoCredentialResult, g as XenoConnectionStatus, P as PushdownSplit, h as XenoConnectorQueryRequest, i as XenoRestPaging, j as XenoConnectorFetch, k as XenoResolverErrorCode, l as XenoConnectorFileReader, X as XenoSqlEngine, m as ConnectorTransport, n as XenoCredentialField } from '../transport-B1cdciP8.js';
+export { B as BrowserFetchOptions, o as ConnectorTransportError, p as SECRET_HEADER_NAMES, q as XenoConnectionConfig, r as XenoConnectionHealth, s as XenoConnectionKind, t as XenoConnectionState, u as XenoConnectorCapabilities, v as XenoCredentialSubmission, w as XenoFetchRequest, x as XenoFetchResponse, y as XenoFileReadRequest, z as XenoFileReadResponse, A as XenoRefreshPolicy, D as XenoSqlTable, E as browserFetch, F as classifyBrowserFetchFailure, G as defaultCapabilitiesFor, H as errorResult, I as evaluateSupport, J as facilitiesOf, K as normalizePaging, L as secretHeaderNames } from '../transport-B1cdciP8.js';
+
+/**
+ * Column layout — width, order, visibility and freezing.
+ *
+ * Layout is **panel state, not query state**: it persists through `serialize()` and never travels in
+ * a `XenoQuery`. Widths are keyed by `XenoColumn.id`, so a source that renames a column keeps its
+ * width and a source that returns two columns with the same display name keeps them apart (§6.2).
+ *
+ * All of it is pure so the geometry is unit-tested without a DOM — the same discipline that let the
+ * Transport panel's time math be tested without a clock.
+ *
+ * @module
+ */
+
+/** Per-column layout overrides, keyed by column id. */
+interface ColumnLayout {
+    /** Explicit widths in px. */
+    widths: Record<string, number>;
+    /** Explicit left-to-right order; ids absent from the result are ignored. */
+    order: string[];
+    /** Ids the user hid. */
+    hidden: string[];
+    /** How many leading columns are frozen (pinned) — counted in RENDER order. */
+    frozenCount: number;
+}
+/** An empty layout — every column visible, in source order, at the default width. */
+declare const EMPTY_LAYOUT: ColumnLayout;
+/** Default column width in px when neither the source nor the user set one. */
+declare const DEFAULT_COLUMN_WIDTH = 140;
+/** Minimum width a column can be dragged to — below this a header is unreadable and unclickable. */
+declare const MIN_COLUMN_WIDTH = 40;
+/** A column resolved for rendering: the source column plus its resolved geometry. */
+interface ResolvedColumn {
+    /** The source column. */
+    column: XenoColumn;
+    /** Resolved width in px. */
+    width: number;
+    /** Distance from the left edge of the full column strip, in px. */
+    offset: number;
+    /** Frozen (pinned) — rendered in the sticky leading region. */
+    frozen: boolean;
+    /** Index in render order. */
+    index: number;
+}
+/**
+ * Resolve the render-order column list with widths and offsets.
+ *
+ * Ordering rule: ids named in `layout.order` come first in that order, then any remaining source
+ * columns in **source order**. A source that adds a column therefore appends it rather than
+ * silently dropping it — the failure mode of a layout that stores a closed list.
+ *
+ * @param columns - The result's columns.
+ * @param layout - Persisted layout state.
+ * @returns Visible columns, resolved.
+ *
+ * @example
+ * ```ts
+ * const resolved = resolveColumns(result.columns, layout)
+ * const totalWidth = resolved.at(-1)!.offset + resolved.at(-1)!.width
+ * ```
+ */
+declare function resolveColumns(columns: readonly XenoColumn[], layout?: ColumnLayout): ResolvedColumn[];
+/** Total width of the resolved column strip, in px. */
+declare function totalWidth(resolved: readonly ResolvedColumn[]): number;
+/** Width of the frozen (sticky) leading region, in px. */
+declare function frozenWidth(resolved: readonly ResolvedColumn[]): number;
+/**
+ * Set a column's width, clamped to the minimum.
+ *
+ * @param layout - Current layout.
+ * @param columnId - Column to resize.
+ * @param width - Requested width in px.
+ * @returns A new layout (the input is not mutated).
+ */
+declare function setColumnWidth(layout: ColumnLayout, columnId: string, width: number): ColumnLayout;
+/**
+ * Move a column to a new index in render order.
+ *
+ * The order list is rewritten from the CURRENT resolved order, not patched, so a reorder is
+ * meaningful even the first time (when `layout.order` is still empty).
+ *
+ * @param layout - Current layout.
+ * @param columns - The result's columns (for the current order).
+ * @param columnId - Column to move.
+ * @param toIndex - Destination index among visible columns.
+ * @returns A new layout.
+ */
+declare function moveColumn(layout: ColumnLayout, columns: readonly XenoColumn[], columnId: string, toIndex: number): ColumnLayout;
+/**
+ * Toggle a column's visibility.
+ *
+ * @param layout - Current layout.
+ * @param columnId - Column to toggle.
+ * @param visible - Desired visibility; omitted flips.
+ * @returns A new layout.
+ */
+declare function setColumnVisible(layout: ColumnLayout, columnId: string, visible?: boolean): ColumnLayout;
+/**
+ * Set how many leading columns are frozen.
+ *
+ * @param layout - Current layout.
+ * @param count - Number of columns to pin; clamped to `>= 0`.
+ * @returns A new layout.
+ */
+declare function setFrozenCount(layout: ColumnLayout, count: number): ColumnLayout;
+/** Normalize an unknown (deserialized) layout, dropping anything malformed. */
+declare function normalizeLayout(raw: unknown): ColumnLayout;
+
+/**
+ * Panel-local types for `xeno.core.table`.
+ *
+ * The data contract itself lives in `@xenosystem/data-core` — this file holds only what the PANEL owns:
+ * view mode, selection, the cell-edit intent, and the serialized shape.
+ *
+ * @module
+ */
+
+/**
+ * How the row set is laid out.
+ *
+ * v1 ships `grid` and `pivot`. `board` and `gallery` are reserved in the union — they are the same
+ * rows and the same cell editor with a different layout function, and reserving the values now means
+ * adding them later is not a config migration. See the README for why they are not in v1.
+ */
+type TableViewMode = 'grid' | 'pivot' | 'board' | 'gallery';
+/** Every view mode the panel currently implements. */
+declare const IMPLEMENTED_VIEW_MODES: readonly TableViewMode[];
+/** An edit the user performed on a cell. Emitted as an INTENT — the host writes. */
+interface XenoCellEdit {
+    /** Row to edit. */
+    rowId: string;
+    /** Column to edit. */
+    columnId: string;
+    /** The new value. */
+    value: XenoValue;
+    /** The value before the edit, so a host can build an undo entry without re-reading. */
+    previousValue: XenoValue;
+    /**
+     * Gesture correlation id. Every preview and the final commit of one edit share it, so a host
+     * coalesces them into **one** undo entry.
+     */
+    gestureId: string;
+}
+/** A row activation (double-click / Enter) — the event that drives BACK-view execution. */
+interface XenoRowActivate {
+    /** The activated row. */
+    rowId: string;
+    /** The column the activation happened in, when it was a cell. */
+    columnId?: string;
+}
+/** The panel's serialized state. `.xapp` stores this; it never stores a result. */
+interface TablePanelState {
+    /** The query — **this persists**. */
+    query: XenoQuery;
+    /** View mode. */
+    viewMode: TableViewMode;
+    /** Column widths / order / hidden / frozen. */
+    layout: ColumnLayout;
+    /** Ids of collapsed groups, serialized from their structured keys. */
+    collapsedGroups: string[];
+    /** Selected row ids. */
+    selection: string[];
+}
+/** What the panel exposes to its view layer. */
+interface TableViewState {
+    /** The newest result, or `null` before the first one lands. */
+    result: XenoResultSet | null;
+    /** The query the panel intends. Chrome renders from `result.query` when one exists. */
+    query: XenoQuery;
+    /** Current view mode. */
+    viewMode: TableViewMode;
+    /** Column layout. */
+    layout: ColumnLayout;
+    /** Serialized keys of collapsed groups. */
+    collapsedGroups: string[];
+    /** Selected row ids. */
+    selection: string[];
+    /** The focused cell, when the grid has a cursor. */
+    cursor: {
+        rowIndex: number;
+        columnIndex: number;
+    } | null;
+    /** The cell currently being edited. */
+    editing: {
+        rowId: string;
+        columnId: string;
+        draft: string;
+    } | null;
+    /** A request is outstanding. */
+    pending: boolean;
+}
+
+/** The host seam the controller emits through. */
+interface TableHostBridge {
+    /** Emit on a declared output port. */
+    emit(portId: string, value: unknown): void;
+    /** Generate a correlation id. Injectable so tests are deterministic. */
+    makeId?: () => string;
+}
+/** Construction options. */
+interface TableControllerOptions {
+    /** The host bridge. */
+    host: TableHostBridge;
+    /** Initial state (from `deserialize`). */
+    initial?: Partial<TablePanelState>;
+    /** Rows per page. Default 100. */
+    pageSize?: number;
+    /** Emit `editPreview` while typing. Default `false` — cell editing is commit-on-blur by nature. */
+    livePreview?: boolean;
+}
+/** Default page size. */
+declare const DEFAULT_PAGE_SIZE = 100;
+/** Structural equality for queries — the diff-before-emit gate. */
+declare function queriesEqual(a: XenoQuery | undefined, b: XenoQuery | undefined): boolean;
+/** The Table panel controller. */
+declare class TableController {
+    private readonly host;
+    private readonly makeId;
+    private readonly pageSize;
+    private readonly livePreview;
+    private readonly listeners;
+    private result;
+    private query;
+    private viewMode;
+    private layout;
+    private collapsedGroups;
+    private selection;
+    private cursor;
+    private editing;
+    /** The newest emitted request id. Anything else that arrives is stale and dropped. */
+    private outstandingId;
+    /** The last query actually emitted, for diff-before-emit. */
+    private lastEmitted;
+    /** Cached view snapshot, so `useSyncExternalStore` sees a stable reference between changes. */
+    private snapshot;
+    constructor(options: TableControllerOptions);
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe: (listener: () => void) => (() => void);
+    /** The current view snapshot (stable reference until something changes). */
+    getState: () => TableViewState;
+    private notify;
+    /**
+     * Deliver a result.
+     *
+     * @param payload - `{requestId, result}` — the id must be echoed from the request.
+     * @returns `true` if the result was accepted, `false` if it was dropped as stale.
+     */
+    deliverResult(payload: {
+        requestId?: string;
+        result: XenoResultSet;
+    } | XenoResultSet): boolean;
+    /**
+     * Apply an incremental update from a live source.
+     *
+     * @param delta - The delta.
+     * @returns `true` if applied, `false` if there is nothing to apply it to.
+     */
+    deliverDelta(delta: _xenosystem_data_core.XenoResultDelta): boolean;
+    /** Selection may reference rows the newest page no longer contains — drop those. */
+    private pruneSelection;
+    /**
+     * Emit a query request, unless the query is structurally unchanged.
+     *
+     * @param reason - Why the query changed (telemetry + host debounce hints).
+     * @param force - Emit even if unchanged (an explicit refresh).
+     * @returns The emitted request id, or `null` if the emission was suppressed.
+     */
+    requestQuery(reason: _xenosystem_data_core.XenoQueryRequest['reason'], force?: boolean): string | null;
+    /** Replace the query wholesale (from a wired `fields` panel) and request it. */
+    setQuery(query: XenoQuery): void;
+    /**
+     * Cycle a column's sort: none → asc → desc → none.
+     *
+     * @param columnId - The column.
+     * @param additive - Keep existing terms and append/update this one (Shift-click).
+     */
+    toggleSort(columnId: string, additive?: boolean): void;
+    /** Replace the filter tree. */
+    setFilters(filters: XenoQuery['filters']): void;
+    /** Replace the grouping levels. */
+    setGroupBy(groupBy: XenoQuery['groupBy']): void;
+    /** Replace the pivot spec. Switching it on also switches the view mode. */
+    setPivot(pivot: XenoQuery['pivot']): void;
+    /** Go to a page by index (0-based). */
+    goToPage(index: number): void;
+    /** Step one page forward/backward, clamped to what the result says exists. */
+    stepPage(direction: 1 | -1): void;
+    /** Change the page size, returning to the first page. */
+    setPageSize(limit: number): void;
+    /** Re-run the current query unchanged. */
+    refresh(): void;
+    private firstPage;
+    /**
+     * The query the CHROME should render from.
+     *
+     * `result.query` when there is one and the result is settled; the local intent only while a
+     * request is in flight. This is invariant 2, in one method.
+     */
+    effectiveQuery(): XenoQuery;
+    /** Switch view mode. Unimplemented modes are refused rather than rendering blank. */
+    setViewMode(mode: TableViewMode): boolean;
+    /** Resolved columns for the current result + layout. */
+    resolvedColumns(): ResolvedColumn[];
+    /** Set a column width. */
+    resizeColumn(columnId: string, width: number): void;
+    /** Move a column in render order. */
+    reorderColumn(columnId: string, toIndex: number): void;
+    /** Show/hide a column. */
+    toggleColumn(columnId: string, visible?: boolean): void;
+    /** Freeze the leading `count` columns. */
+    freezeColumns(count: number): void;
+    /** Collapse/expand a group by its serialized key. */
+    toggleGroup(serializedKey: string): void;
+    /** Select rows. `additive` toggles membership instead of replacing. */
+    select(rowIds: readonly string[], additive?: boolean): void;
+    /** Move the cell cursor, clamped to the grid. */
+    moveCursor(delta: {
+        rows?: number;
+        columns?: number;
+    }): void;
+    /** Put the cursor at an explicit address. */
+    setCursor(address: {
+        rowIndex: number;
+        columnIndex: number;
+    } | null): void;
+    /** Emit a row activation (double-click / Enter) — the BACK-view execution trigger. */
+    activateRow(rowId: string, columnId?: string): void;
+    /**
+     * Begin editing a cell.
+     *
+     * @param rowId - Row.
+     * @param columnId - Column.
+     * @returns `true` if editing started; `false` when the column is not editable or the row is gone.
+     */
+    beginEdit(rowId: string, columnId: string): boolean;
+    /** Update the in-flight draft. Emits `editPreview` only when `livePreview` is on. */
+    updateDraft(text: string): void;
+    /**
+     * Commit the edit.
+     *
+     * Rejects invalid input by REVERTING rather than committing a coerced value — the whole point of
+     * inheriting the Inspector's parse-as-a-result contract. Also suppresses a no-op commit, so
+     * tabbing through a column does not write an undo entry per cell.
+     *
+     * @returns `true` if an `edit` intent was emitted.
+     */
+    commitEdit(): boolean;
+    /** Abandon the edit. Escape reverts; nothing is emitted. */
+    cancelEdit(): void;
+    private buildEdit;
+    /** Parse a draft according to the column's declared type. */
+    private parseDraft;
+    private rowById;
+    private columnById;
+    /** Format a cell for display — the column's format, honoured. */
+    displayValue(row: XenoRow, column: XenoColumn): string;
+    /**
+     * Serialize the panel's state.
+     *
+     * **The query persists; the result never does.** A result is transient and can be megabytes; an
+     * `.xapp` that embeds one is both stale and enormous the moment it is opened.
+     */
+    serialize(): TablePanelState;
+    /** Restore serialized state. Does NOT emit — the caller decides when to ask for data. */
+    deserialize(state: Partial<TablePanelState>): void;
+    /** Drop listeners and in-flight state. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — what a host registers and mounts.
+ *
+ * Everything the panel does flows through the injected {@link PanelHost}: inputs arrive on
+ * `onInput`, commands on `onCommand`, and every output leaves through `host.emit`. There is no
+ * other door.
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the host's resolved config. */
+interface TableRenderContext {
+    controller: TableController;
+    /**
+     * The host's config, already defaulted from the manifest.
+     *
+     * Passed in because a renderer that cannot see config makes every manifest-declared display
+     * option unreachable — the panel would document `rowHeight` and `zebra` and then ignore them.
+     */
+    config: {
+        rowHeight: number;
+        showFooter: boolean;
+        zebra: boolean;
+        showRowNumbers: boolean;
+    };
+}
+/** Options for {@link createTablePanel}. */
+interface CreateTablePanelOptions {
+    /**
+     * Override the renderer.
+     *
+     * **Rarely needed.** The module wires {@link TablePanelView} itself, which is what keeps `react`
+     * and `react-dom` resolving to ONE copy: if the host calls `createRoot` against a view imported
+     * from the package, a `file:`/workspace link gives the host's `react-dom` and the package's
+     * `react` two different copies and every hook throws *"Invalid hook call"*. Vitest hides this
+     * (its React plugin dedupes implicitly); a real app does not.
+     *
+     * Supply this only for a non-React host or a test double.
+     */
+    render?: (root: HTMLElement, context: TableRenderContext) => () => void;
+}
+/**
+ * Build the Table panel module.
+ *
+ * @param options - Optional renderer.
+ * @returns The module.
+ */
+declare function createTablePanel(options?: CreateTablePanelOptions): PanelModule;
+/**
+ * The default Table panel module — view already wired.
+ *
+ * **Register THIS**, not `createTablePanel()` plus a hand-rolled renderer. Every other canonical
+ * panel exports the same shape, and the reason is not symmetry: it is that mounting the view inside
+ * the package is what guarantees a single React copy.
+ */
+declare const tablePanel: PanelModule;
+
+/**
+ * The `xeno.core.table` manifest.
+ *
+ * Ports follow the union spec §5 sketch: `result` + `query` in, `queryRequest` + `edit` +
+ * `selection` + `rowActivate` out. Every structured port carries a **shape tag**, so the builder
+ * cannot wire a Layers `op` into `result` (SDK 1.1's `PanelPort.schema`).
+ *
+ * **Capabilities: `storage.local` ONLY.** Zero network, zero fs, zero gpu — query execution stays
+ * host-side, so the panel is fully sandboxable under `iframe-quickjs`, web-exportable, and
+ * marketplace-shippable. That property is the whole point of the request/response seam.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const TABLE_PANEL_ID = "xeno.core.table";
+/** The `xeno.core.table` manifest. */
+declare const tableManifest: PanelManifest;
+
+/**
+ * Grid viewport math — the windowing that keeps a wide, tall table cheap.
+ *
+ * Rendering discipline taken from sheets' `Grid.tsx` as a **reference only** — its viewport
+ * derivation, its `ResizeObserver`-driven measurement, and its 2×`requestAnimationFrame` defer.
+ * None of its cell/formula/A1 semantics come along: this grid renders a `XenoResultSet`, which has
+ * ids and types, not a spreadsheet address space.
+ *
+ * Rows use the fixed-height virtualizer (`virtualize.ts`). Columns need their own pass because they
+ * are variable width, so the window is found by binary search over the resolved offsets — O(log n)
+ * per scroll instead of the O(n) scan a naive loop does on every frame of a horizontal drag.
+ *
+ * @module
+ */
+
+/** The visible column window. */
+interface ColumnWindow {
+    /** First rendered column index (inclusive). */
+    startIndex: number;
+    /** Last rendered column index (exclusive). */
+    endIndex: number;
+    /** Left spacer width in px — the offset of `startIndex`. */
+    offsetLeft: number;
+}
+/**
+ * Index of the last column whose offset is `<= x`, by binary search.
+ *
+ * @param columns - Resolved columns, ascending by offset.
+ * @param x - Horizontal position in px.
+ * @returns The index, or `0` when the strip is empty.
+ */
+declare function columnIndexAt(columns: readonly ResolvedColumn[], x: number): number;
+/**
+ * Compute the visible column window.
+ *
+ * Frozen columns are ALWAYS rendered — they are sticky, so scrolling them out of the window would
+ * make them disappear from a region that is still on screen. They are excluded from the spacer, and
+ * the window starts after them.
+ *
+ * @param columns - Resolved columns.
+ * @param scrollLeft - Horizontal scroll offset in px.
+ * @param viewportWidth - Visible width in px.
+ * @param overscan - Extra columns to render on each side. Default 1.
+ * @returns The window.
+ */
+declare function computeColumnWindow(columns: readonly ResolvedColumn[], scrollLeft: number, viewportWidth: number, overscan?: number): ColumnWindow;
+/**
+ * The scroll position that brings a column fully into view, or `null` if it already is.
+ *
+ * Returning `null` for the no-op case is deliberate: a caller that always assigns `scrollLeft`
+ * cancels a user's in-flight momentum scroll on every keystroke.
+ *
+ * @param columns - Resolved columns.
+ * @param index - Target column index.
+ * @param scrollLeft - Current scroll offset.
+ * @param viewportWidth - Visible width.
+ * @returns The new `scrollLeft`, or `null`.
+ */
+declare function scrollLeftToReveal(columns: readonly ResolvedColumn[], index: number, scrollLeft: number, viewportWidth: number): number | null;
+/**
+ * The scroll position that brings a row fully into view, or `null` if it already is.
+ *
+ * @param index - Row index.
+ * @param rowHeight - Fixed row height.
+ * @param scrollTop - Current vertical scroll offset.
+ * @param viewportHeight - Visible height.
+ * @returns The new `scrollTop`, or `null`.
+ */
+declare function scrollTopToReveal(index: number, rowHeight: number, scrollTop: number, viewportHeight: number): number | null;
+/** A cell address within the rendered page. */
+interface CellAddress {
+    /** Row index within the page. */
+    rowIndex: number;
+    /** Column index in render order. */
+    columnIndex: number;
+}
+/**
+ * Move a cell cursor, clamped to the grid.
+ *
+ * Clamping rather than wrapping: an arrow key at the last row should stop, not jump to the first —
+ * wrapping in a grid loses the user's place and is not what any spreadsheet does.
+ *
+ * @param from - Current address.
+ * @param delta - Movement in rows/columns.
+ * @param bounds - Grid extent.
+ * @returns The new address.
+ */
+declare function moveCell(from: CellAddress, delta: {
+    rows?: number;
+    columns?: number;
+}, bounds: {
+    rowCount: number;
+    columnCount: number;
+}): CellAddress;
+
+/**
+ * Fixed-height row virtualization — Canvas's architecture (union spec §1.2).
+ *
+ * Canvas added this after a documented ~200 ms-at-5k-layers wall; Pixel has none, which is why the
+ * parity gate includes a perf floor Pixel itself does not meet today (spec §6). Fixed `rowHeight`
+ * keeps the index math O(1) — no measurement, no prefix sums (variable height is v1.1).
+ *
+ * @module
+ */
+/** The slice of rows to render, plus the spacer geometry that preserves scroll extent. */
+interface VirtualWindow {
+    /** First row index to render (inclusive), overscan included. */
+    startIndex: number;
+    /** Last row index to render (exclusive), overscan included. */
+    endIndex: number;
+    /** Top spacer height in px — `startIndex * rowHeight`. */
+    offsetTop: number;
+    /** Total scrollable height in px — `rowCount * rowHeight`. */
+    totalHeight: number;
+}
+/** Inputs for {@link computeWindow}. */
+interface WindowInput {
+    rowCount: number;
+    rowHeight: number;
+    scrollTop: number;
+    viewportHeight: number;
+    /** Extra rows rendered above and below the viewport. Canvas ships 8. */
+    overscan?: number;
+}
+/**
+ * Compute the visible row window.
+ *
+ * Clamped and NaN-safe: a zero/unknown viewport (before the first `ResizeObserver` tick) yields an
+ * empty-but-valid window rather than rendering the whole list.
+ *
+ * @param input - Row count, fixed row height, scroll offset, viewport height, overscan.
+ * @returns The {@link VirtualWindow} to render.
+ */
+declare function computeWindow(input: WindowInput): VirtualWindow;
+
+/**
+ * Numeric cell parsing — **inherited wholesale from `@xenosystem/panel-inspector`'s `numeric.ts`**, not
+ * re-invented.
+ *
+ * The union spec (§6.3) names `parseFloat(e.target.value) || 0` in notes' number-cell editor as a
+ * live instance of checklist #91 (`x || default` where `0` is meaningful) *in the richest data
+ * surface in the ecosystem*: an empty box, a typo, or a half-typed `-` all commit a silent `0` over
+ * whatever the cell held. The spec's remedy is explicit — the cell editor **inherits the Inspector's
+ * numeric-field synthesis, not a re-implementation** — because a second implementation is a second
+ * chance to reintroduce the bug.
+ *
+ * Copied rather than imported: panels are standalone (zero cross-panel dependencies), the same rule
+ * under which `throttle` and `virtualize` are copied. The Inspector's file is the SOURCE OF TRUTH —
+ * a fix there must be mirrored here, and both are covered by the same assertions.
+ *
+ * Only the parse/clamp/precision half is carried over; the Inspector's slider, log-scale and scrub
+ * math have no cell-editor analogue.
+ *
+ * @module
+ */
+/** Parse outcome. Invalid input is a first-class case, never a silent `0`. */
+type ParseResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: 'empty' | 'nan';
+};
+/** Constraints a numeric cell can carry (read off the column's format). */
+interface NumericConstraints {
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    /** Reject a fractional result — an `integer` column cannot hold `1.5`. */
+    integer?: boolean;
+}
+/**
+ * Parse user text into a number.
+ *
+ * Accepts leading/trailing whitespace, a leading `+`/`-`, decimals, exponents, and a trailing unit
+ * suffix (`12px`, `45°`, `50 %`) so a suffix the panel itself rendered round-trips. Everything else
+ * is REJECTED — including empty input, a bare `-`, and `NaN`/`Infinity`.
+ *
+ * @param text - Raw input.
+ * @returns `{ok:true, value}` or `{ok:false, reason}` — never a coerced number.
+ */
+declare function parseNumeric(text: string): ParseResult;
+/** Clamp to `[min, max]` when declared. */
+declare function clamp(value: number, { min, max }: NumericConstraints): number;
+/** Round to the declared precision (decimal places). No precision ⇒ unchanged. */
+declare function applyPrecision(value: number, precision?: number): number;
+/**
+ * Clamp + round in one step — the canonical "make this value legal" helper.
+ *
+ * @param value - The parsed number.
+ * @param c - Constraints.
+ * @returns A value that satisfies every declared constraint.
+ */
+declare function normalizeNumeric(value: number, c: NumericConstraints): number;
+/**
+ * Read the numeric constraints a column implies.
+ *
+ * @param column - The column.
+ * @returns Constraints for {@link normalizeNumeric}.
+ */
+declare function constraintsOfColumn(column: {
+    type: string;
+    format?: {
+        precision?: number;
+    };
+}): NumericConstraints;
+
+/**
+ * The Table panel's React view — grid + pivot.
+ *
+ * **First real consumer of `@xenosystem/workbench/primitives`.** Everything that is chrome (toolbar,
+ * status strip, empty/loading/error states, badges, icon buttons, segmented control) comes from the
+ * primitives; only the grid body itself — which is the panel's actual job — is local.
+ *
+ * The view is deliberately thin: all state lives in {@link TableController}, bound through
+ * `useSyncExternalStore`. Rendering is the only thing that happens here.
+ *
+ * @module
+ */
+
+/** Props for {@link TablePanelView}. */
+interface TablePanelViewProps {
+    /** The controller. */
+    controller: TableController;
+    /** Fixed row height in px (config `rowHeight`). */
+    rowHeight?: number;
+    /** Render the grand-totals footer. */
+    showFooter?: boolean;
+    /** Shade alternate rows. */
+    zebra?: boolean;
+    /**
+     * Render a leading ordinal gutter.
+     *
+     * U5: the manifest declared this from day one and the view never rendered it — declared config
+     * with no implementation. The numbers are 1-based over the CURRENT PAGE plus the query offset,
+     * so row 1 of page 2 reads as its absolute position rather than restarting.
+     */
+    showRowNumbers?: boolean;
+}
+/** The Table panel view. */
+declare function TablePanelView({ controller, showRowNumbers, rowHeight, showFooter, zebra, }: TablePanelViewProps): ReactNode;
+
+/**
+ * The `xeno.core.chart` contract.
+ *
+ * ## 🔴 Landmine §6.11, stated as a type
+ *
+ * sheets' chart is bound to a **viewport selection**, its type lives in component `useState` (lost
+ * on unmount), and its `ChartConfig` is written but never read. All three are the same mistake:
+ * chart state that is not part of the panel's serialized model.
+ *
+ * Here, data always arrives as a **`XenoResultSet`** — never a viewport range — and the encoding is
+ * the panel's persisted state, round-tripped through `serialize()`. A chart that forgets what it was
+ * showing is a chart nobody trusts.
+ *
+ * @module
+ */
+
+/** Chart types v1 renders. */
+type XenoChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'scatter' | 'pie' | 'doughnut';
+/** Every chart type, in menu order. */
+declare const ALL_CHART_TYPES: readonly XenoChartType[];
+/**
+ * How columns map to visual channels.
+ *
+ * **This is the panel's persisted state**, not component state — see the module note.
+ */
+interface XenoChartEncoding {
+    /** The mark. */
+    type: XenoChartType;
+    /** Category / time axis. */
+    x?: string;
+    /** Measure(s). More than one produces multiple series. */
+    y?: string[];
+    /** Column that splits `y` into one series per distinct value. */
+    series?: string;
+    /** Column driving mark colour. */
+    color?: string;
+    /** Column driving mark size (scatter). */
+    size?: string;
+    /** Aggregate applied to `y` when the query groups. */
+    aggregate?: XenoAggFn;
+    /** Stack series rather than grouping them. */
+    stacked?: boolean;
+    /** Line smoothing, `0`–`1`. */
+    smoothing?: number;
+}
+/**
+ * The monochrome series palette — SIX steps of `--xeno-chart-series-<n>`, and the fill ramp that pairs
+ * with it, `--xeno-chart-fill-<n>`. The VALUES live one rung down (`@xenosystem/elements/tokens`
+ * `chart`, emitted by elements-react's theme); a block may carry no colour literal. Until 2026-09-18
+ * these were twelve white-alpha strings lifted from sheets' `ChartModel`.
+ *
+ * A `var()` cannot reach a `<canvas>`, so a RENDERER resolves them against the element it draws in —
+ * `resolveChartColors(element)` — right before handing the config to Chart.js. The model stays pure
+ * and testable: it assigns var strings, never computed colours.
+ */
+declare const CHART_PALETTE_STEPS = 6;
+declare const MONO_PALETTE: readonly string[];
+/** The fill palette that pairs with it. */
+declare const MONO_FILL_PALETTE: readonly string[];
+/** The fill for a category with no value (a null slice). */
+declare const CHART_EMPTY_FILL = "var(--xeno-border-subtle)";
+/**
+ * A function that turns `var(--name)` strings into the computed value in scope at `element`. Anything
+ * that is not a `var()` passes through; a var the theme does not define resolves to `''` and Chart.js
+ * uses its own default for it — visible, never a wrong colour.
+ */
+declare function resolveChartColors(element: {
+    ownerDocument?: {
+        defaultView?: {
+            getComputedStyle(el: unknown): {
+                getPropertyValue(name: string): string;
+            };
+        } | null;
+    } | null;
+} | null | undefined): (css: string) => string;
+/** One plotted series. */
+interface XenoChartSeries {
+    /** Stable id — the `series` value, or the `y` column id when there is no split. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Points, aligned to {@link XenoChartData.labels} by index. `null` is a genuine gap. */
+    data: (number | null)[];
+    /** Stroke colour. */
+    color: string;
+    /** Fill colour, for area and bar marks. */
+    fill: string;
+}
+/** The renderer-agnostic plot model. */
+interface XenoChartData {
+    /** Category labels, one per point index. */
+    labels: string[];
+    /** The series. */
+    series: XenoChartSeries[];
+    /** The encoding that produced it. */
+    encoding: XenoChartEncoding;
+    /**
+     * Set when the source has more points than `maxPoints`.
+     *
+     * The panel then requests an AGGREGATED query rather than downsampling: **silent downsampling is a
+     * lie about the data**, and a user cannot tell a thinned line from a real one.
+     */
+    tooDense?: {
+        points: number;
+        limit: number;
+    };
+}
+/** A cross-filter highlight arriving from a sibling panel. */
+type XenoChartHighlight = {
+    rowIds: string[];
+} | {
+    columnId: string;
+    values: XenoValue[];
+} | null;
+/** What the panel emits when a mark is clicked. */
+interface XenoChartDrillDown {
+    columnId: string;
+    value: XenoValue;
+    /** The series the mark belonged to, when there is one. */
+    seriesId?: string;
+}
+/** An export request. The HOST renders and writes — the panel never touches a filesystem. */
+interface XenoChartExportRequest {
+    requestId: string;
+    format: 'png' | 'svg';
+    width: number;
+    height: number;
+}
+/** The panel's serialized state. **The encoding persists** — that is the §6.11 fix. */
+interface ChartPanelState {
+    encoding: XenoChartEncoding;
+}
+/** What the controller exposes to its view. */
+interface ChartViewState {
+    /** The plot model, or `null` before a usable result + encoding exist. */
+    data: XenoChartData | null;
+    /** The current encoding. */
+    encoding: XenoChartEncoding;
+    /** Columns available to encode. */
+    columns: XenoColumn[];
+    /** Chart types this host allows. */
+    allowedTypes: readonly XenoChartType[];
+    /** Highlighted row ids, from a sibling's cross-filter. */
+    highlightedRowIds: string[];
+    /** No result, or a result with no rows. */
+    empty: boolean;
+    /** The result was `partial`. */
+    partial: boolean;
+    /** A typed error from the result. */
+    errorMessage: string | null;
+    /** Set when the encoding cannot be plotted, with the reason. */
+    encodingProblem: string | null;
+}
+/** Marks that plot a single series against a category axis. */
+declare function isCategorical(type: XenoChartType): boolean;
+/** Marks that draw a filled region. */
+declare function isFilled(type: XenoChartType): boolean;
+/**
+ * Whether an encoding can be plotted, and if not, why.
+ *
+ * Returns a SENTENCE rather than a boolean: a chart that renders blank because the encoding is
+ * incomplete is indistinguishable from one that is broken.
+ */
+declare function validateEncoding(encoding: XenoChartEncoding, columns: readonly XenoColumn[]): string | null;
+/** The default encoding for a result — the first time column vs the first measure. */
+declare function defaultEncoding(columns: readonly XenoColumn[], type?: XenoChartType): XenoChartEncoding;
+
+/**
+ * The Chart controller.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface ChartHostBridge {
+    emit(portId: string, value: unknown): void;
+    makeId?: () => string;
+}
+/** Construction options. */
+interface ChartControllerOptions {
+    host: ChartHostBridge;
+    initial?: Partial<ChartPanelState>;
+    /** Chart types this host permits. */
+    allowedTypes?: readonly XenoChartType[];
+    defaultType?: XenoChartType;
+    maxSeries?: number;
+    maxPoints?: number;
+}
+/** The Chart panel controller. */
+declare class ChartController {
+    private readonly host;
+    private readonly makeId;
+    private readonly allowedTypes;
+    private readonly buildOptions;
+    private readonly listeners;
+    private result;
+    private encoding;
+    private highlight;
+    private snapshot;
+    /** Set once `tooDense` has been reported, so the request is not re-emitted every render. */
+    private densityReported;
+    constructor(options: ChartControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => ChartViewState;
+    private notify;
+    /**
+     * Receive a result.
+     *
+     * **Data always arrives as a result set** — never a viewport range. That is landmine §6.11: a
+     * chart bound to a selection cannot be saved, cannot be shared, and shows nothing the moment the
+     * selection moves.
+     */
+    setResult(result: XenoResultSet): void;
+    /** Receive an externally authored encoding (from a wired `fields` panel). */
+    setEncoding(encoding: XenoChartEncoding, emit?: boolean): void;
+    /** Patch one channel. */
+    patchEncoding(patch: Partial<XenoChartEncoding>): void;
+    /** Change the mark. Refuses a type this host disallows. */
+    setType(type: XenoChartType): boolean;
+    /** Receive a cross-filter highlight from a sibling panel. */
+    setHighlight(highlight: XenoChartHighlight): void;
+    /** The plot model, or `null` when there is nothing plottable. */
+    buildData(): XenoChartData | null;
+    /** Row ids the current highlight resolves to. */
+    private resolveHighlight;
+    /**
+     * Ask for an aggregated query when the result is too dense to plot honestly.
+     *
+     * **Never a silent downsample.** A thinned line is indistinguishable from a real one, so the panel
+     * asks the resolver to aggregate instead — and asks once per encoding/result, not every render.
+     */
+    private reportDensity;
+    /** A mark was clicked: emit the selection and a drill-down. */
+    activateMark(label: string, seriesId?: string): boolean;
+    /** A brush selected several categories. */
+    brush(labels: readonly string[]): boolean;
+    /**
+     * Ask the HOST to render an image.
+     *
+     * The panel never touches a filesystem — it declares `storage.local` and nothing else, which is
+     * only true because export is a request rather than a write.
+     */
+    requestExport(format: 'png' | 'svg', width?: number, height?: number): string;
+    /**
+     * Serialize.
+     *
+     * **The encoding persists.** sheets keeps its chart type in component `useState` and loses it on
+     * unmount, and writes a `ChartConfig` nothing ever reads — the same bug twice.
+     */
+    serialize(): ChartPanelState;
+    /** Restore. Does not emit. */
+    deserialize(state: Partial<ChartPanelState>): void;
+    /** Columns available to encode. */
+    columns(): XenoColumn[];
+    /** Drop listeners. */
+    dispose(): void;
+}
+
+/**
+ * The renderer SEAM.
+ *
+ * v1 renders with Chart.js — proven in sheets' 195-LOC `ChartView` — but the panel never imports it
+ * directly. A renderer receives the derived {@link XenoChartData} and a host element, and returns a
+ * disposer. That is the whole contract.
+ *
+ * The seam exists because spectra's future Canvas2D/WebGPU engine must be a **swap, not a rewrite**:
+ * everything expensive (deriving series, resolving labels, palette assignment, density detection)
+ * lives in `model.ts` and is renderer-agnostic. A second renderer implements ~40 lines.
+ *
+ * @module
+ */
+
+/** What a renderer is handed. */
+interface ChartRenderInput {
+    /** The element to draw into. */
+    element: HTMLElement;
+    /** The derived, renderer-agnostic model. */
+    data: XenoChartData;
+    /** Presentation toggles. */
+    options: ChartRenderOptions;
+    /** Row ids currently highlighted by a sibling's cross-filter. */
+    highlightedRowIds?: readonly string[];
+    /** Called when a mark is activated. */
+    onMarkActivate?: (label: string, seriesId?: string) => void;
+}
+/** Presentation toggles a renderer honours. */
+interface ChartRenderOptions {
+    showLegend: boolean;
+    showGrid: boolean;
+    showTooltip: boolean;
+    stacked: boolean;
+    /** Line smoothing `0`–`1`. */
+    smoothing: number;
+}
+/** A renderer: draw, and hand back a disposer. */
+type ChartRenderer = (input: ChartRenderInput) => () => void;
+/**
+ * Install the renderer.
+ *
+ * @param next - The renderer, or `null` to uninstall.
+ *
+ * @example
+ * ```ts
+ * import { Chart } from 'chart.js/auto'
+ * setChartRenderer(createChartJsRenderer(Chart))
+ * ```
+ */
+declare function setChartRenderer(next: ChartRenderer | null): void;
+/** The installed renderer. */
+declare function getChartRenderer(): ChartRenderer | null;
+/**
+ * Chart.js dataset shape — derived from the model so a host can wire Chart.js in a few lines
+ * without the panel importing it.
+ *
+ * Exported rather than inlined so the mapping is testable without a DOM or a chart library.
+ *
+ * @param data - The derived model.
+ * @param options - Presentation toggles.
+ * @returns A Chart.js-compatible `{type, data, options}` config.
+ */
+declare function toChartJsConfig(data: XenoChartData, options: ChartRenderOptions): Record<string, unknown>;
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface ChartRenderContext {
+    controller: ChartController;
+    config: {
+        options: ChartRenderOptions;
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createChartPanel}. */
+interface CreateChartPanelOptions {
+    /** Override the view. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: ChartRenderContext) => () => void;
+}
+/**
+ * Build the Chart panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createChartPanel(options?: CreateChartPanelOptions): PanelModule;
+/** The default Chart panel module — view already wired. Register THIS. */
+declare const chartPanel: PanelModule;
+
+/**
+ * The `xeno.core.chart` manifest.
+ *
+ * Capabilities: `storage.local` only — export is a REQUEST to the host, never a write, which is what
+ * keeps the capability list at one entry.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const CHART_PANEL_ID = "xeno.core.chart";
+/** The `xeno.core.chart` manifest. */
+declare const chartManifest: PanelManifest;
+
+/**
+ * The plot model — `XenoResultSet` + `XenoChartEncoding` → `XenoChartData`.
+ *
+ * Pure, renderer-agnostic, and the whole reason the renderer is a **seam**: Chart.js consumes this,
+ * and spectra's future Canvas2D/WebGPU engine consumes the same thing. Swapping the renderer must
+ * never mean re-deriving the data.
+ *
+ * @module
+ */
+
+/** Options for {@link buildChartData}. */
+interface BuildChartOptions {
+    /** Series ceiling. Beyond this the tail is dropped rather than rendering an unreadable legend. */
+    maxSeries?: number;
+    /**
+     * Point ceiling. Above it the data is flagged `tooDense` and the panel requests an AGGREGATED
+     * query — **never a silent downsample**, which is a lie about the data.
+     */
+    maxPoints?: number;
+}
+/**
+ * Build the plot model.
+ *
+ * Two paths. A result carrying `groups` whose aggregates match the encoded measures is plotted from
+ * the GROUPS; everything else is plotted from the rows. See {@link buildFromGroups} for why the row
+ * path is a wrong answer for an aggregated query.
+ *
+ * @param result - The result set. Rows are THE PAGE — the model never invents rows the page lacks.
+ * @param encoding - How columns map to channels.
+ * @param options - Series and point ceilings.
+ * @returns The renderer-agnostic model.
+ *
+ * @example
+ * ```ts
+ * const data = buildChartData(result, { type: 'line', x: 'day', y: ['revenue'], series: 'region' })
+ * ```
+ */
+declare function buildChartData(result: XenoResultSet, encoding: XenoChartEncoding, options?: BuildChartOptions): XenoChartData;
+/**
+ * The row ids a mark corresponds to — what `selection` and `drillDown` are built from.
+ *
+ * @param result - The result the model was built from.
+ * @param encoding - The encoding.
+ * @param label - The category label that was clicked.
+ * @param seriesId - The series, when the mark belongs to one.
+ * @returns Matching row ids, in row order.
+ */
+declare function rowsForMark(result: XenoResultSet, encoding: XenoChartEncoding, label: string, seriesId?: string): string[];
+
+/**
+ * The Chart panel view.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure `@xenosystem/workbench/primitives.css` is
+ * present. The plot area delegates to the installed renderer (see `renderer.ts`) — this view owns
+ * the chrome and the states, not the marks.
+ *
+ * **There is no shelf UI here.** The encoding editor is `xeno.core.fields` with chart shelves,
+ * wired as a sibling panel; building a second shelf UI is exactly what sequencing chart after fields
+ * was meant to avoid.
+ *
+ * @module
+ */
+
+/** Props for {@link ChartPanelView}. */
+interface ChartPanelViewProps {
+    controller: ChartController;
+    options?: Partial<ChartRenderOptions>;
+    emptyHint?: string;
+}
+/** The Chart panel view. */
+declare function ChartPanelView({ controller, options, emptyHint }: ChartPanelViewProps): ReactNode;
+
+/**
+ * The `xeno.core.metrics` contract — KPI tiles over a `XenoResultSet`.
+ *
+ * The cheapest panel in the family: the tile primitives already landed in
+ * `@xenosystem/workbench/primitives` (lifted from `xeno-post`'s kit), and the percentile math already
+ * landed in `@xenosystem/data-core`. This package is the model that binds them.
+ *
+ * @module
+ */
+
+/**
+ * Which direction of change is GOOD.
+ *
+ * Load-bearing: **a rising error rate is not good news.** A delta arrow that is green whenever the
+ * number went up is worse than no arrow, because it reads as reassurance.
+ */
+type DeltaDirection = 'higherIsBetter' | 'lowerIsBetter' | 'neutral';
+/** One KPI tile. */
+interface XenoMetricSpec {
+    /** Stable id — the key in thresholds, alerts and `metricActivate`. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Column to aggregate. Ignored by `count`. */
+    columnId: string;
+    /** The aggregate. Percentiles are R-7 / `PERCENTILE.INC`, as `@xenosystem/data-core` documents. */
+    fn: XenoAggFn;
+    /** Presentation. */
+    format?: XenoValueFormat;
+    /** Column supplying the sparkline series, when one is wanted. */
+    sparklineColumnId?: string;
+    /** Lucide icon name for the tile. */
+    icon?: string;
+    /** Which direction is good. Default `neutral` — no colour rather than a wrong colour. */
+    deltaDirection?: DeltaDirection;
+    /** Longer explanation, shown as a tooltip. */
+    description?: string;
+}
+/** A warn/critical threshold for one metric. */
+interface XenoMetricThreshold {
+    metricId: string;
+    /** Crossing this raises `level: 'warn'`. */
+    warn?: number;
+    /** Crossing this raises `level: 'critical'`. */
+    critical?: number;
+    /**
+     * Which side of the number is bad. Defaults from the metric's `deltaDirection`:
+     * `lowerIsBetter` ⇒ `above`, `higherIsBetter` ⇒ `below`.
+     */
+    breach?: 'above' | 'below';
+}
+/** Threshold severity, mirroring the profiler's bottleneck model. */
+type XenoAlertLevel = 'ok' | 'warn' | 'critical';
+/** What the panel emits when a threshold is crossed. */
+interface XenoMetricAlert {
+    metricId: string;
+    level: XenoAlertLevel;
+    value: number;
+    threshold: number;
+}
+/** A tile, computed. */
+interface XenoMetricValue {
+    spec: XenoMetricSpec;
+    /** The aggregate, or `null` when the sample supports no answer. */
+    value: XenoValue;
+    /** Formatted for display. */
+    display: string;
+    /** The comparison-period value, when a comparison result was supplied. */
+    previous?: XenoValue;
+    /** Signed fractional change vs the previous period (`0.12` = +12%). */
+    delta?: number;
+    /**
+     * Whether the change is GOOD, BAD or neither — derived from `deltaDirection`, never from the sign.
+     */
+    deltaTone: 'good' | 'bad' | 'neutral';
+    /** Threshold state. */
+    level: XenoAlertLevel;
+    /** The sparkline series, oldest first. */
+    spark?: number[];
+    /**
+     * `true` when the underlying result is `status: 'partial'`.
+     *
+     * A partial result means "these rows are real, the measures are still landing". Rendering it as
+     * zero is a lie the user cannot detect; the tile shows the hint instead.
+     */
+    partial?: boolean;
+}
+/** A named time range offered in the toolbar. */
+interface XenoMetricRange {
+    /** Stable id. */
+    id: string;
+    /** Display label (`'7d'`). */
+    label: string;
+    /** How far back. */
+    unit: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    /** How many units. Positive; the panel emits it as a negative relative filter. */
+    n: number;
+}
+/**
+ * The default ranges.
+ *
+ * **Config, not constants.** One product hardcoded 7/30/90 as tabs precisely because the filter
+ * vocabulary had no `relative` primitive; now that it does, these are data.
+ */
+declare const DEFAULT_RANGES: readonly XenoMetricRange[];
+/** The panel's serialized state. */
+interface MetricsPanelState {
+    /** The active range id. */
+    rangeId?: string;
+    /** Per-metric threshold overrides the user set. */
+    thresholds?: XenoMetricThreshold[];
+}
+/** What the controller exposes to its view. */
+interface MetricsViewState {
+    /** Computed tiles, in config order. */
+    metrics: XenoMetricValue[];
+    /** The active range. */
+    rangeId: string | null;
+    /** Ranges to offer. */
+    ranges: readonly XenoMetricRange[];
+    /** No result yet. */
+    empty: boolean;
+    /** The result is `partial`. */
+    partial: boolean;
+    /** The result carried an error. */
+    errorMessage: string | null;
+}
+/** Resolve which direction is bad for a threshold. */
+declare function breachSideOf(threshold: XenoMetricThreshold, spec: XenoMetricSpec | undefined): 'above' | 'below';
+/**
+ * The tone a delta should render with.
+ *
+ * Derived from `deltaDirection`, **never from the sign**. `neutral` metrics get no tone at all,
+ * because a colour that means nothing still reads as a judgement.
+ */
+declare function deltaToneOf(delta: number | undefined, direction?: DeltaDirection): XenoMetricValue['deltaTone'];
+
+/**
+ * The Metrics controller — result in, tiles out.
+ *
+ * Every number comes from `@xenosystem/data-core`'s `applyAggregate`, so a percentile here is the same
+ * percentile a table's footer shows (R-7 / `PERCENTILE.INC`). Definitions differ by a whole element
+ * on small samples, and a dashboard whose KPI disagrees with its own table is worse than one with no
+ * KPI at all.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface MetricsHostBridge {
+    emit(portId: string, value: unknown): void;
+    makeId?: () => string;
+}
+/** Construction options. */
+interface MetricsControllerOptions {
+    host: MetricsHostBridge;
+    /** The tiles to render. */
+    metrics?: XenoMetricSpec[];
+    /** Ranges to offer. Default 7/30/90 days. */
+    ranges?: readonly XenoMetricRange[];
+    /** Which time column a range filter applies to. */
+    rangeColumnId?: string;
+    /** IANA zone for the range filter. Default `'UTC'`. */
+    timeZone?: string;
+    /** Restored state. */
+    initial?: Partial<MetricsPanelState>;
+}
+/** The Metrics panel controller. */
+declare class MetricsController {
+    private readonly host;
+    private readonly listeners;
+    private readonly ranges;
+    private readonly rangeColumnId?;
+    private readonly timeZone;
+    private specs;
+    private result;
+    private comparison;
+    private thresholds;
+    private rangeId;
+    /** Last emitted level per metric, so an alert fires on TRANSITION and not on every render. */
+    private readonly lastLevels;
+    private snapshot;
+    constructor(options: MetricsControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => MetricsViewState;
+    private notify;
+    /** Receive the current-period result. */
+    setResult(result: XenoResultSet): void;
+    /** Receive the prior-period result, which is what makes a delta possible. */
+    setComparison(result: XenoResultSet | null): void;
+    /** Receive thresholds. */
+    setThresholds(thresholds: XenoMetricThreshold[]): void;
+    /** Replace the tile set. */
+    setMetrics(specs: XenoMetricSpec[]): void;
+    /** Compute every tile. */
+    compute(): XenoMetricValue[];
+    private aggregate;
+    private sparkFor;
+    /** The threshold state of one metric. */
+    levelFor(spec: XenoMetricSpec, value: XenoValue): XenoAlertLevel;
+    /**
+     * Emit an alert for every metric whose level CHANGED.
+     *
+     * On transition, not on every render: a dashboard that re-emits `critical` sixty times a second
+     * is a dashboard whose alerts get muted.
+     */
+    private emitAlerts;
+    /**
+     * Select a time range, emitting a `queryRequest` carrying a RELATIVE filter.
+     *
+     * Relative, not two absolute timestamps: a saved dashboard must still mean "the last 7 days"
+     * tomorrow.
+     */
+    setRange(rangeId: string): boolean;
+    /** A tile was clicked — the drill-down trigger. */
+    activate(metricId: string): boolean;
+    /** Serialize. Range and thresholds — never a result. */
+    serialize(): MetricsPanelState;
+    /** Restore. Does not emit. */
+    deserialize(state: Partial<MetricsPanelState>): void;
+    /** Drop listeners. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface MetricsRenderContext {
+    controller: MetricsController;
+    config: {
+        layout: 'grid' | 'row' | 'list';
+        columns: number;
+        sparkline: boolean;
+        showDelta: boolean;
+        emptyHint?: string;
+        partialHint: string;
+    };
+}
+/** Options for {@link createMetricsPanel}. */
+interface CreateMetricsPanelOptions {
+    /** Override the renderer. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: MetricsRenderContext) => () => void;
+}
+/**
+ * Build the Metrics panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createMetricsPanel(options?: CreateMetricsPanelOptions): PanelModule;
+/** The default Metrics panel module — view already wired. Register THIS. */
+declare const metricsPanel: PanelModule;
+
+/**
+ * The `xeno.core.metrics` manifest.
+ *
+ * The cheapest panel in the family and a LEAF — it consumes a result and emits events, so nothing
+ * downstream waits on it. Capabilities: `storage.local` only.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const METRICS_PANEL_ID = "xeno.core.metrics";
+/** The `xeno.core.metrics` manifest. */
+declare const metricsManifest: PanelManifest;
+
+/**
+ * The Metrics panel view — tiles, deltas, sparklines, threshold tone.
+ *
+ * Composes `@xenosystem/workbench/primitives` (`StatTile`, `Badge`, `SegmentedControl`, `Sparkline`); the
+ * host must ensure `@xenosystem/workbench/primitives.css` is present. Nothing here is a local re-cut —
+ * the sparkline moved into the primitives so there is exactly one.
+ *
+ * @module
+ */
+
+/** Props for {@link MetricsPanelView}. */
+interface MetricsPanelViewProps {
+    controller: MetricsController;
+    layout?: 'grid' | 'row' | 'list';
+    columns?: number;
+    sparkline?: boolean;
+    showDelta?: boolean;
+    emptyHint?: string;
+    partialHint?: string;
+}
+/** The Metrics panel view. */
+declare function MetricsPanelView({ controller, layout, columns, sparkline, showDelta, emptyHint, partialHint, }: MetricsPanelViewProps): ReactNode;
+
+/**
+ * The `xeno.core.fields` contract — the query AUTHOR.
+ *
+ * This is the panel that retires three surfaces at once: sheets' mock pivot shelves (three dashed
+ * "Drag fields here" rectangles whose `computePivot` is never called), notes' inline filter builder,
+ * and architect's *nonexistent* schedule field editor.
+ *
+ * ## The design bet: shelves are CONFIG
+ *
+ * One panel serves three consumers because a "shelf" is nothing but a named, typed bucket of column
+ * references. Pivot wants `rows|columns|values|filters`; chart wants `x|y|series|color|size`; table
+ * wants `columns|filters|sorts`. Those differ in *labels, arity and accepted roles* — not in
+ * behaviour. Encoding them as config is what stops this becoming three panels that drift.
+ *
+ * @module
+ */
+
+/** What a shelf accepts and how many. */
+interface XenoShelfSpec {
+    /** Stable id — also the key in {@link FieldsPanelState.shelves}. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /**
+     * Which roles may land here. A `measure` shelf refuses a dimension, so a user cannot build a
+     * query the source will reject.
+     */
+    accepts: XenoColumnRole[];
+    /** Maximum entries. `1` makes it a single-slot shelf (chart's `x`); omit for unlimited. */
+    max?: number;
+    /** Entries carry an aggregate function (a `values` shelf). */
+    aggregated?: boolean;
+    /** Time-bucket granularity is offered for `time` columns dropped here. */
+    bucketed?: boolean;
+    /** Help text. */
+    hint?: string;
+}
+/** The three shelf layouts v1 ships, as data. */
+declare const SHELF_PRESETS: Readonly<Record<'pivot' | 'chart' | 'table', XenoShelfSpec[]>>;
+/** One column placed on a shelf. */
+interface XenoShelfEntry {
+    /** The column. */
+    columnId: string;
+    /** Aggregate function, on an `aggregated` shelf. */
+    fn?: XenoAggFn;
+    /** Roll-up function for grand totals. Defaults to `fn` — never to sum. */
+    totalFn?: XenoAggFn;
+    /** Time bucket, on a `bucketed` shelf with a temporal column. */
+    granularity?: 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    /** Sort direction, on a `sorts` shelf. */
+    direction?: 'asc' | 'desc';
+    /** Display label override. */
+    label?: string;
+    /**
+     * `true` when the panel placed this entry by role inference rather than the user.
+     *
+     * Auto-assignment is a **suggestion, not a decision**: a suggested entry renders differently and
+     * is cleared wholesale the moment the user touches the shelf, so the panel never silently decides
+     * what a query means.
+     */
+    suggested?: boolean;
+}
+/** Live per-column statistics derived from a result — cardinality and nulls. */
+interface XenoFieldStat {
+    columnId: string;
+    /** Distinct values seen on the page. */
+    distinct: number;
+    /** Empty cells on the page. */
+    nulls: number;
+    /** Rows the statistic was computed over. */
+    sampled: number;
+}
+/** The panel's serialized state. */
+interface FieldsPanelState {
+    /** Entries per shelf id. */
+    shelves: Record<string, XenoShelfEntry[]>;
+    /** The filter tree. */
+    filters?: XenoFilterGroup;
+    /** Which preset the shelves came from. */
+    preset: 'pivot' | 'chart' | 'table' | 'custom';
+}
+/** What the controller exposes to its view. */
+interface FieldsViewState {
+    /** The catalog's columns for the active source, or `[]` before one lands. */
+    columns: XenoColumn[];
+    /** The shelf specs in play. */
+    shelves: XenoShelfSpec[];
+    /** Entries per shelf. */
+    entries: Record<string, XenoShelfEntry[]>;
+    /** The filter tree. */
+    filters: XenoFilterGroup;
+    /** Live stats, keyed by column id. */
+    stats: Record<string, XenoFieldStat>;
+    /** Aggregate functions the SOURCE can actually do. Empty ⇒ everything is local. */
+    allowedAggregates: XenoAggFn[];
+    /** Filter operators the source understands. */
+    allowedFilterOps: string[];
+    /**
+     * Set when the catalog was inferred from a sample.
+     *
+     * `fields` must WARN that a column may be absent later — a shape derived from the first N rows is
+     * a guess, and building a query on a guessed column is how a dashboard breaks next Tuesday.
+     */
+    sampleWarning: string | null;
+    /** A query is pending an explicit Apply (only when `autoApply` is off). */
+    dirty: boolean;
+    /** The column the user is hovering/focused, mirrored on `fieldFocus`. */
+    focusedColumnId: string | null;
+}
+/** A calculated-field request. The HOST validates and compiles it — never the panel. */
+interface XenoCalculatedFieldRequest {
+    requestId: string;
+    /** Proposed column id. */
+    columnId: string;
+    label: string;
+    /** The expression, verbatim. Host-parsed; the panel never evaluates it. */
+    expression: string;
+    /** The user's declared result type, for the host to check against. */
+    type?: XenoColumn['type'];
+}
+/** Every aggregate the family knows, in menu order. */
+declare const ALL_AGGREGATES: readonly XenoAggFn[];
+/**
+ * The default aggregate for a column.
+ *
+ * A measure sums, a dimension counts. Anything else counts, because counting is the one aggregate
+ * that is meaningful for every type.
+ */
+declare function defaultAggregateFor(column: XenoColumn | undefined): XenoAggFn;
+/**
+ * Which aggregates may be offered for a column, gated by what the SOURCE can push down.
+ *
+ * **Never offer a pushdown the source cannot do.** A menu that lists `p95` against a REST endpoint
+ * produces a query the resolver must silently run locally over one page — which is a different,
+ * wrong number.
+ *
+ * @param column - The column.
+ * @param sourceAggregates - `capabilities.aggregates`, or empty when the source declares none.
+ * @returns The offerable list.
+ */
+declare function offerableAggregates(column: XenoColumn | undefined, sourceAggregates?: readonly string[]): XenoAggFn[];
+/** The shelf a column belongs on by role — a SUGGESTION, never a silent decision. */
+declare function suggestedShelfFor(column: XenoColumn, shelves: readonly XenoShelfSpec[]): XenoShelfSpec | undefined;
+/** An empty filter group. An empty group PASSES — a half-authored filter must not blank the table. */
+declare function emptyFilterGroup(): XenoFilterGroup;
+/** Operators offerable for a column type, intersected with what the source understands. */
+declare function offerableFilterOps(column: XenoColumn | undefined, sourceOps?: readonly string[]): string[];
+/** Read the columns of the active source out of a catalog. */
+declare function columnsOf(catalog: XenoSchemaCatalog | null, sourceId?: string): XenoColumn[];
+/** Narrow a filter-tree member to a leaf. */
+declare function isLeafFilter(f: XenoFilter | XenoFilterGroup): f is XenoFilter;
+
+/**
+ * The Fields controller — shelves in, `XenoQuery` out.
+ *
+ * Emitting a query is **the panel's whole reason to exist**, so the interesting decisions are all
+ * about when *not* to emit: never on a structurally unchanged query, never mid-edit when `autoApply`
+ * is off, and never a query the source cannot run.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface FieldsHostBridge {
+    emit(portId: string, value: unknown): void;
+    makeId?: () => string;
+}
+/** Construction options. */
+interface FieldsControllerOptions {
+    host: FieldsHostBridge;
+    initial?: Partial<FieldsPanelState>;
+    /** Which shelf layout to serve. Default `'table'`. */
+    preset?: 'pivot' | 'chart' | 'table';
+    /** Custom shelves, overriding the preset. */
+    shelves?: XenoShelfSpec[];
+    /** Emit on every edit. Default `true`; when `false` the user presses Apply. */
+    autoApply?: boolean;
+    /** Rows per page in the emitted query. */
+    pageSize?: number;
+}
+/** The Fields panel controller. */
+declare class FieldsController {
+    private readonly host;
+    private readonly makeId;
+    private readonly autoApply;
+    private readonly pageSize;
+    private readonly listeners;
+    private shelves;
+    private preset;
+    private entries;
+    private filters;
+    private catalog;
+    private sourceId;
+    private stats;
+    private focusedColumnId;
+    private dirty;
+    private lastEmitted;
+    private snapshot;
+    constructor(options: FieldsControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => FieldsViewState;
+    private notify;
+    /** Receive a schema catalog. */
+    setCatalog(catalog: XenoSchemaCatalog, sourceId?: string): void;
+    /**
+     * Receive a result — the source of LIVE per-column statistics.
+     *
+     * Cardinality and null counts come from the page, not from the schema, which is why they update on
+     * every result rather than every catalog.
+     */
+    setResult(result: XenoResultSet): void;
+    /** Adopt an externally authored query, so a user can edit what a table already shows. */
+    setQuery(query: XenoQuery): void;
+    /** The shelf spec with this id. */
+    shelf(id: string): XenoShelfSpec | undefined;
+    /**
+     * Place a column on a shelf.
+     *
+     * Refuses when the shelf does not accept the column's role or is full — a shelf that silently
+     * accepts anything is a shelf that builds queries the source rejects.
+     *
+     * @returns `true` when the column was placed.
+     */
+    addToShelf(shelfId: string, columnId: string, at?: number): boolean;
+    /** Remove a column from a shelf. */
+    removeFromShelf(shelfId: string, columnId: string): boolean;
+    /** Move an entry within a shelf. */
+    reorderShelf(shelfId: string, columnId: string, toIndex: number): boolean;
+    /**
+     * Change an entry's aggregate.
+     *
+     * Refuses a function the source cannot run — offering `p95` against a source with no percentile
+     * support produces a silently different number.
+     */
+    setAggregate(shelfId: string, columnId: string, fn: XenoAggFn): boolean;
+    /** Change an entry's time bucket. */
+    setGranularity(shelfId: string, columnId: string, granularity: XenoShelfEntry['granularity']): void;
+    /** Flip a sort direction. */
+    toggleDirection(shelfId: string, columnId: string): void;
+    /**
+     * Fill empty shelves from column roles — a SUGGESTION the user can override.
+     *
+     * Every entry it creates is marked `suggested`, renders differently, and disappears the moment the
+     * user touches that shelf. Auto-assignment that silently decides what a query means is how a
+     * dashboard shows a number nobody chose.
+     *
+     * @returns How many entries were suggested.
+     */
+    autoAssign(): number;
+    private clearSuggestions;
+    /** Replace the whole filter tree. */
+    setFilters(filters: XenoFilterGroup): void;
+    /**
+     * Add a leaf filter to a group, addressed by its path from the root.
+     *
+     * @param path - Indices into nested `filters` arrays; `[]` is the root group.
+     * @param filter - The condition.
+     */
+    addFilter(path: readonly number[], filter: XenoFilter): boolean;
+    /** Add a nested group (an and/or branch). */
+    addFilterGroup(path: readonly number[], combinator?: 'and' | 'or'): boolean;
+    /** Update a leaf in place. */
+    updateFilter(path: readonly number[], index: number, patch: Partial<XenoFilter>): boolean;
+    /** Remove a member (leaf or group). */
+    removeFilter(path: readonly number[], index: number): boolean;
+    /** Flip a group between AND and OR. */
+    setCombinator(path: readonly number[], combinator: 'and' | 'or'): boolean;
+    private groupAt;
+    /**
+     * Report the focused column, so a table can highlight the matching one.
+     *
+     * A direct lift of the Inspector's `fieldFocus` — the same idea, the same port shape, so a host
+     * that already wired one gets the other for free.
+     */
+    focusColumn(columnId: string | null): void;
+    /** Ask the host to validate and compile a calculated field. The panel never evaluates one. */
+    requestCalculatedField(label: string, expression: string, type?: XenoColumn['type']): string;
+    /**
+     * The query the current shelves describe.
+     *
+     * Pivot shelves produce a `pivot` block; everything else produces `groupBy` + `aggregates`, which
+     * is what makes one panel serve a cross-tab and a flat table without a second code path.
+     */
+    buildQuery(): XenoQuery;
+    /** Emit the query, unless it is structurally unchanged. */
+    apply(force?: boolean): XenoQuery | null;
+    private afterEdit;
+    private columnById;
+    /** Serialize. Shelves and filters — never a catalog, never a result. */
+    serialize(): FieldsPanelState;
+    /** Restore. Does not emit. */
+    deserialize(state: Partial<FieldsPanelState>): void;
+    /** Drop listeners. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface FieldsRenderContext {
+    controller: FieldsController;
+    config: {
+        showStats: boolean;
+        manualApply: boolean;
+    };
+}
+/** Options for {@link createFieldsPanel}. */
+interface CreateFieldsPanelOptions {
+    /** Override the renderer. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: FieldsRenderContext) => () => void;
+}
+/**
+ * Build the Fields panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createFieldsPanel(options?: CreateFieldsPanelOptions): PanelModule;
+/** The default Fields panel module — view already wired. Register THIS. */
+declare const fieldsPanel: PanelModule;
+
+/**
+ * The `xeno.core.fields` manifest.
+ *
+ * Capabilities: `storage.local` only. The panel authors a query; the connectors panel runs it.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const FIELDS_PANEL_ID = "xeno.core.fields";
+/** The `xeno.core.fields` manifest. */
+declare const fieldsManifest: PanelManifest;
+
+/**
+ * The Fields panel view — column list, shelves, filter builder.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure
+ * `@xenosystem/workbench/primitives.css` is present.
+ *
+ * @module
+ */
+
+/** Props for {@link FieldsPanelView}. */
+interface FieldsPanelViewProps {
+    controller: FieldsController;
+    /** Render live cardinality/null counts. */
+    showStats?: boolean;
+    /** Show an explicit Apply (config `autoApply: false`). */
+    manualApply?: boolean;
+}
+/** The Fields panel view. */
+declare function FieldsPanelView({ controller, showStats, manualApply, }: FieldsPanelViewProps): ReactNode;
+
+/**
+ * The Connectors controller — the data family's **resolver**.
+ *
+ * Owns connections, the credential lifecycle, pushdown negotiation, the single-flight cache, refresh
+ * timers, and the typed error surface. Every log line leaves through the SDK's redacting sink, so a
+ * credential cannot reach a log even by accident.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface ConnectorsHostBridge {
+    emit(portId: string, value: unknown): void;
+    makeId?: () => string;
+    /** Structured logging. Wrapped in a redacting sink before use — never called directly. */
+    log?: LogSink;
+    /** Executes the pushed half of a query. Supplied by the host; the panel never opens a socket. */
+    execute?: (input: ConnectorExecuteInput) => Promise<ConnectorExecuteOutput>;
+    /** Wall clock, injectable for tests. */
+    now?: () => number;
+    /** Timer seam, injectable for tests. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** Construction options. */
+interface ConnectorsControllerOptions {
+    host: ConnectorsHostBridge;
+    initial?: Partial<ConnectorsPanelState>;
+    /** What the substrate can do. Drives honest degradation. */
+    facilities?: SubstrateFacilities;
+    defaultPageSize?: number;
+    maxRows?: number;
+    cacheTtlMs?: number;
+    /** Whether a panel-authored `raw` query is permitted. Default `false`. */
+    allowRawQueries?: boolean;
+}
+/** The Connectors panel controller / resolver. */
+declare class ConnectorsController {
+    private readonly host;
+    private readonly makeId;
+    private readonly log;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly facilities;
+    private readonly defaultPageSize;
+    private readonly maxRows;
+    private readonly cacheTtlMs;
+    private readonly allowRawQueries;
+    private readonly listeners;
+    private connections;
+    private statuses;
+    private lastQueries;
+    private selectedId;
+    private form;
+    /** Newest outstanding request per `(connectionId, requestorPanelId)`. */
+    private readonly outstanding;
+    /** In-flight executions, keyed by cache key — the single-flight map. */
+    private readonly inFlight;
+    private readonly cache;
+    /** One timer per connection. */
+    private readonly timers;
+    /** Connections whose refresh is currently running — the re-entrancy guard. */
+    private readonly refreshing;
+    /** Last good result per connection, so a failed refresh can keep serving. */
+    private readonly lastGood;
+    /**
+     * Introspected schema per connection — the catalog this panel PUBLISHES.
+     *
+     * Not persisted: a schema is host knowledge, re-pushed on load. A cached one written into `.xapp`
+     * would outlive the table it describes.
+     */
+    private readonly schemas;
+    /** Monotonic catalog revision, so `fields` re-reads without polling. */
+    private catalogRev;
+    /** Connections currently being read as a SQL source — the recursion guard for `sourceRows`. */
+    private readonly resolvingSources;
+    private hidden;
+    private snapshot;
+    constructor(options: ConnectorsControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => ConnectorsViewState;
+    private notify;
+    private stateOf;
+    /**
+     * Add or replace a connection.
+     *
+     * Health is **always rebuilt**, never taken from the input — a persisted "healthy" is a lie, and a
+     * caller passing one must not be able to install it.
+     */
+    addConnection(connection: XenoConnection, emit?: boolean): void;
+    /** Remove a connection, clearing its timer, cache and in-flight work. */
+    removeConnection(id: string): boolean;
+    /**
+     * Receive an introspected schema from the host and **publish the catalog**.
+     *
+     * **Why this exists.** The `catalog` output port was declared, `introspect` documented "re-read
+     * the schema and emit a catalog", and nothing in the package ever emitted on it — `introspect`
+     * only emitted `sourceChanged` and deferred to "a host flow". But **a host cannot emit on a
+     * panel's output port**, so `connectors.catalog → fields.catalog` — step one of `fields`' own
+     * INTEGRATION.md — had no producer and `fields` was unusable in a builder.
+     *
+     * The division of labour that fixes it, unchanged from the rest of the family: **the host does
+     * the IO, the panel owns the aggregation.** The host answers an `introspect` ask by pushing one
+     * `XenoSourceSchema` in here; the panel merges it across connections, bumps `rev`, and emits the
+     * catalog itself.
+     *
+     * @param schema - One source's schema, or a whole catalog to install at once.
+     * @returns Whether a catalog was emitted.
+     */
+    setSchema(schema: XenoSourceSchema | XenoSchemaCatalog): boolean;
+    /** The catalog as it currently stands. */
+    catalog(): XenoSchemaCatalog;
+    /** Publish it. */
+    private emitCatalog;
+    /** The connection with this id. */
+    connection(id: string): XenoConnection | undefined;
+    /** Select a connection in the UI. */
+    select(id: string | null): void;
+    /** The host asks for a credential. The panel renders the descriptor; it knows no platform names. */
+    requireCredential(spec: XenoCredentialFormSpec): void;
+    /**
+     * Submit a credential form.
+     *
+     * The values leave immediately and are **cleared from local state right here** — not in a
+     * `.then()`, not on unmount. `submit_credential` is declared `agentVisible: false`, so an agent can
+     * neither read this form nor replay it.
+     */
+    submitCredential(values: Record<string, string | number | boolean>): boolean;
+    /** Abandon the form. Values are dropped; nothing is emitted. */
+    cancelCredential(): void;
+    /**
+     * The host's answer to a credential flow.
+     *
+     * **Never carries the values back.** A new `credentialRefRev` invalidates every cached result for
+     * that connection, so a re-auth cannot serve data fetched with the old identity.
+     */
+    credentialChanged(result: XenoCredentialResult): void;
+    /** A host-pushed health change. */
+    healthChanged(connectionId: string, status: XenoConnectionStatus): void;
+    /**
+     * Split a query into what the source can run and what must run locally.
+     *
+     * The split is echoed in `result.stats` so a user can see *why* a filter was slow — a resolver that
+     * silently runs everything locally looks identical to one that pushes everything down, right up
+     * until the row count matters.
+     *
+     * @param query - The full query.
+     * @param connection - The target connection.
+     * @returns The split, with op names for telemetry.
+     */
+    splitQuery(query: XenoQuery, connection: XenoConnection): PushdownSplit;
+    /** The effective row cap: the smallest of query, source ceiling and host budget. */
+    clampLimit(query: XenoQuery, connection: XenoConnection): number;
+    /** Cache key: connection + credential revision + the pushed query. */
+    private cacheKey;
+    /** Drop every cached result for a connection. */
+    invalidateCache(connectionId: string): void;
+    /**
+     * Resolve a query.
+     *
+     * The whole of §5 lives here: per-`(connection, requestor)` correlation, the pushdown split,
+     * single-flight, the clamped-limit echo, honest `page.total`, and keeping the last good result
+     * when a refresh fails.
+     *
+     * @param request - The incoming query.
+     * @returns The result set (also emitted on `result`).
+     */
+    resolve(request: XenoConnectorQueryRequest): Promise<XenoResultSet>;
+    /**
+     * The number of rows the source must return for this query to be answerable.
+     *
+     * **Not the same as the page size**, and conflating them is a real bug: when a source cannot push
+     * `limit` down, the page is cut *locally*, so trimming the fetch to one page's worth leaves
+     * nothing for the local cut to find and **every page after the first comes back empty**. A source
+     * that pages for itself is asked for exactly one page; a source that cannot is asked for
+     * everything up to the end of the requested window, capped by the row ceiling.
+     *
+     * @param split - The pushdown split.
+     * @param limit - The clamped page size.
+     * @returns The row budget, and whether the source paged for us.
+     */
+    private rowBudget;
+    /** Run the pushed half through the host, then the local half through the pipeline. */
+    private execute;
+    /**
+     * Another connection's rows, as plain objects — the in-sandbox SQL bridge's source of data.
+     *
+     * Reuses the ordinary resolution path, so a DuckDB query over a REST source gets that source's
+     * cache, its credential and its error handling rather than a second, subtly different resolver.
+     *
+     * @param connectionId - The source to read.
+     * @returns Its rows, or `null` when it is unknown or failed.
+     */
+    sourceRows(connectionId: string): Promise<{
+        rows: Record<string, unknown>[];
+        name?: string;
+    } | null>;
+    /**
+     * Publish a **sampled** schema derived from a result, so `catalog` has a producer for every kind.
+     *
+     * Without this, `catalog` only ever emits for a host that answers `introspect` — which is exactly
+     * one kind of host. A REST or CSV source has no DDL to read, but it does have a page of rows, and
+     * §7 already names that path `derivedFrom: 'sample'` and requires `fields` to warn that a column
+     * may be absent later.
+     *
+     * A host-supplied schema always wins: this never overwrites one that was genuinely introspected.
+     * The revision is bumped **only when the derived shape actually changes**, so a 30-second refresh
+     * does not force `fields` to re-read on every tick.
+     *
+     * @param connection - The source that answered.
+     * @param result - Its result set.
+     * @returns Whether a new catalog was published.
+     */
+    private noteSampledSchema;
+    /** Apply the local half of the query and stamp the echoed query + split telemetry. */
+    private finish;
+    private echoQuery;
+    /** Emit a result, unless the request has been superseded. */
+    private deliver;
+    /** Install the refresh timer for a connection, replacing any existing one. */
+    scheduleRefresh(connection: XenoConnection): void;
+    /** Clear a connection's timer. */
+    clearRefresh(id: string): void;
+    /** Suspend or resume every timer — a hidden panel must not poll. */
+    setHidden(hidden: boolean): void;
+    /** Re-run a connection's last query, bypassing the cache. */
+    refresh(connectionId: string): Promise<XenoResultSet | null>;
+    /**
+     * Refresh every connection, reporting **per connection**.
+     *
+     * A partial failure must never collapse to one error: with five sources and one expired token, a
+     * single rejected promise tells the user nothing about the four that worked.
+     *
+     * @returns One outcome per connection, in order.
+     */
+    refreshAll(): Promise<{
+        connectionId: string;
+        ok: boolean;
+        code?: string;
+    }[]>;
+    /**
+     * Serialize.
+     *
+     * Connections with their `credentialRef` and the last query. **Never a result, never `health`,
+     * never a secret — and NO MASKED VALUES AT ALL.**
+     *
+     * A mask is not a security boundary, and a mask that survives a round-trip is data loss: one
+     * shipped connector writes `password: '***'` on save and reads it back verbatim on load, so
+     * opening and saving a document *replaces the real credential with three asterisks*. The only way
+     * to make that unrepresentable is to never serialize a value field in the first place.
+     */
+    serialize(): ConnectorsPanelState;
+    /** Restore. Health is rebuilt as `unknown` — never read from the document. */
+    deserialize(state: Partial<ConnectorsPanelState>): void;
+    /** Drop timers, listeners and in-flight state. */
+    dispose(): void;
+}
+
+/**
+ * The `sql.*` executors — and the honest refusal that replaces a stub.
+ *
+ * **A sandboxed panel cannot open a TCP socket.** Not "does not yet"; cannot. QuickJS has no socket
+ * API, a browser has no raw TCP at all, and no amount of work in this package changes either. The
+ * capability matrix therefore marks `sql.postgres`, `sql.mysql`, `sql.sqlite` and file-mode
+ * `sql.duckdb` as **`unsupported`** in those substrates, with one instruction attached to that
+ * decision: *"Disabled card + reason. **Never a stub.**"*
+ *
+ * So this module has exactly two behaviours:
+ *
+ * 1. A **host resolver was supplied** — delegate to it. The host owns the driver, the connection
+ *    pool and the credential; the panel contributes the compiled statement and the paging truth.
+ * 2. **No host resolver** — return `HOST_RESOLVER_REQUIRED` with a sentence naming what the user
+ *    can actually do about it. Not an empty grid, not a spinner, not a "coming soon".
+ *
+ * The second case is the whole point. A stub that returns `[]` renders as a working connection with
+ * no data, and the user's next hour goes into debugging their WHERE clause.
+ *
+ * @module
+ */
+
+/** A host-side SQL resolver: the desktop main process, an IPC bridge, a server. */
+type HostSqlResolver = (input: ConnectorExecuteInput) => Promise<ConnectorExecuteOutput>;
+/** Options for {@link executeSql}. */
+interface ExecuteSqlOptions {
+    /** The host's resolver. Absent means this substrate genuinely cannot reach a database. */
+    hostResolver?: HostSqlResolver;
+}
+/**
+ * Run a SQL query against a server or file database.
+ *
+ * @param input - Connection, the pushed query, and the clamped row budget.
+ * @param options - The host resolver, when this substrate has one.
+ * @returns Rows, or the typed refusal.
+ *
+ * @example
+ * ```ts
+ * // In a browser with no host: a visible, explained, disabled state.
+ * await executeSql(input, {})
+ * // → { rows: [], error: { code: 'HOST_RESOLVER_REQUIRED', message: 'Reading PostgreSQL … ' } }
+ * ```
+ */
+declare function executeSql(input: ConnectorExecuteInput, options: ExecuteSqlOptions): Promise<ConnectorExecuteOutput>;
+/**
+ * The sentence shown on a disabled source card.
+ *
+ * Says the constraint, then the two real options. The spec's own remedy — *"convert to an inline
+ * snapshot"* — is included because it is the one that works today without leaving the app.
+ *
+ * @param kind - The connection kind.
+ * @returns An authored, user-facing sentence.
+ */
+declare function unsupportedMessage(kind: string): string;
+/**
+ * Compile the statement a host resolver would otherwise write itself.
+ *
+ * Offered, never imposed: a host with its own query builder ignores this and reads
+ * `input.query` directly. A host without one gets correct identifier quoting, literal escaping and
+ * `NULLS LAST` ordering for free, which is three classes of bug it does not have to rediscover.
+ *
+ * @param input - The executor input.
+ * @param table - The table or view to read.
+ * @param columns - Known columns, so unknown ids are refused rather than emitted.
+ * @returns The statement or an authored refusal.
+ *
+ * @example
+ * ```ts
+ * const compiled = compileForHost(input, 'orders')
+ * if ('sql' in compiled) rows = await pg.query(compiled.sql)
+ * ```
+ */
+declare function compileForHost(input: ConnectorExecuteInput, table: string, columns?: string[]): {
+    sql: string;
+} | {
+    error: string;
+};
+/**
+ * The default entity (table/view) for a connection, when its config names one.
+ *
+ * @param input - The executor input.
+ * @returns The entity name, or `null`.
+ */
+declare function entityOf(input: ConnectorExecuteInput): string | null;
+
+/**
+ * The REST executor.
+ *
+ * Owns the protocol so no host has to: URL assembly, the four paging styles, JSONPath extraction,
+ * HTTP-status→typed-error mapping, and the over-fetch that makes `hasMore` honest. The only thing it
+ * does not own is the socket — that is {@link XenoConnectorFetch}, supplied by the host.
+ *
+ * @module
+ */
+
+/** Options for {@link executeRest}. */
+interface ExecuteRestOptions {
+    fetch: XenoConnectorFetch;
+    timeoutMs?: number;
+}
+/**
+ * Run a REST query.
+ *
+ * @param input - Connection, the pushed query, and the already-clamped row limit.
+ * @param options - The host's fetch and a deadline.
+ * @returns Rows plus paging truth, or a typed error. **Never throws for a source-side failure.**
+ *
+ * @example
+ * ```ts
+ * const out = await executeRest(
+ *   { connection, query: {}, limit: 51 },
+ *   { fetch: browserFetch() },
+ * )
+ * ```
+ */
+declare function executeRest(input: ConnectorExecuteInput, options: ExecuteRestOptions): Promise<ConnectorExecuteOutput>;
+/**
+ * Assemble a request URL from the base, static params and the paging style.
+ *
+ * @param base - The configured URL, which may already carry a query string.
+ * @param spec - Static params plus the paging position.
+ * @returns The absolute URL to request.
+ *
+ * @example
+ * ```ts
+ * buildRestUrl('https://api.test/v1/rows?team=1', {
+ *   paging: { style: 'offset', limitParam: 'limit', offsetParam: 'offset' },
+ *   limit: 50,
+ *   offset: 100,
+ * })
+ * // → 'https://api.test/v1/rows?team=1&limit=50&offset=100'
+ * ```
+ */
+declare function buildRestUrl(base: string, spec: {
+    params?: Record<string, string>;
+    paging: XenoRestPaging;
+    limit: number;
+    offset: number;
+    cursor?: string;
+}): string;
+/**
+ * Work out how to reach the next page, per style.
+ *
+ * @param paging - The declared style.
+ * @param body - The parsed response body.
+ * @param response - The raw response, for header-based styles.
+ * @param pageLength - Rows in the page just read.
+ * @returns The next cursor or URL, or `exhausted`.
+ */
+declare function nextPageToken(paging: XenoRestPaging, body: unknown, response: {
+    headers: Record<string, string>;
+    url?: string;
+}, pageLength: number): {
+    cursor?: string;
+    url?: string;
+    exhausted?: boolean;
+};
+/**
+ * Parse an RFC 8288 `Link` header.
+ *
+ * @param header - The raw header value.
+ * @returns URLs by `rel`.
+ *
+ * @example
+ * ```ts
+ * parseLinkHeader('<https://api/x?page=2>; rel="next", <https://api/x?page=9>; rel="last"')
+ * // → { next: 'https://api/x?page=2', last: 'https://api/x?page=9' }
+ * ```
+ */
+declare function parseLinkHeader(header: string): Record<string, string>;
+
+/**
+ * Turning failures into the typed vocabulary of §5 — **authored, never echoed**.
+ *
+ * Two rules from the spec are enforced here rather than remembered:
+ *
+ * 1. *"Never surface a 500."* A server's error body is written for the server's operator; it
+ *    routinely contains stack frames, internal hostnames and occasionally a connection string. The
+ *    status **number** is diagnostic and is kept; the body and the reason phrase are not.
+ * 2. *"Never echo env-var names."* A misconfigured platform must say what the user can fix, not
+ *    which variable the operator forgot — one surveyed implementation renders
+ *    `PLATFORM_NOT_CONFIGURED` complete with the variable names, which tells an end user nothing and
+ *    tells an attacker something.
+ *
+ * @module
+ */
+
+/** A typed executor failure. */
+interface ExecuteError {
+    code: XenoResolverErrorCode;
+    message: string;
+    retryable?: boolean;
+}
+/**
+ * Map an HTTP status onto the typed vocabulary.
+ *
+ * @param status - The HTTP status code.
+ * @param statusText - The reason phrase. **Deliberately unused in the message** — see the module doc.
+ * @returns A typed error with an authored, user-facing sentence.
+ *
+ * @example
+ * ```ts
+ * classifyHttpStatus(401) // → { code: 'AUTH_EXPIRED', message: 'The credential … ', retryable: false }
+ * classifyHttpStatus(503) // → { code: 'NETWORK', …, retryable: true }
+ * ```
+ */
+declare function classifyHttpStatus(status: number, statusText?: string): ExecuteError;
+/**
+ * Parse a JSON body, reporting a `PARSE` failure rather than throwing.
+ *
+ * The offending text is **not** included: an HTML error page or a login redirect is the usual cause,
+ * and pasting a kilobyte of markup into a panel error is neither readable nor safe. The first
+ * meaningful characters are enough to recognise "that's HTML, not JSON".
+ *
+ * @param body - The raw response text.
+ * @returns The parsed value, or a typed error.
+ *
+ * @example
+ * ```ts
+ * parseJsonBody('<!doctype html>…')
+ * // → { error: { code: 'PARSE', message: 'The source returned HTML, not JSON. …' } }
+ * ```
+ */
+declare function parseJsonBody(body: string): {
+    value: unknown;
+} | {
+    error: ExecuteError;
+};
+/**
+ * Convert anything thrown during execution into a typed error.
+ *
+ * A {@link ConnectorTransportError} already knows its code — that is the whole point of the
+ * transport carrying one, and it is what keeps `CORS_BLOCKED` from collapsing into `NETWORK`
+ * (§6 L9). Everything else is genuinely unknown and says so.
+ *
+ * @param error - The thrown value.
+ * @returns A typed error.
+ */
+declare function toExecuteError(error: unknown): ExecuteError;
+
+/**
+ * The GraphQL executor.
+ *
+ * **This file exists because of §6 L13, a live bug in shipped code.** One surveyed connector
+ * declares `graphql` as a supported kind and then branches only on `rest`, so every other kind falls
+ * through to the SQL path and a plain HTTP source dies with *"Database queries require main process
+ * IPC"* — a message about the wrong subsystem entirely. The discriminated config union makes the
+ * missing branch a compile error; this module is that branch.
+ *
+ * @module
+ */
+
+/** Options for {@link executeGraphql}. */
+interface ExecuteGraphqlOptions {
+    fetch: XenoConnectorFetch;
+    timeoutMs?: number;
+}
+/**
+ * Run a GraphQL query.
+ *
+ * @param input - Connection, the pushed query, and the clamped row limit.
+ * @param options - The host's fetch and a deadline.
+ * @returns Rows plus paging truth, or a typed error.
+ */
+declare function executeGraphql(input: ConnectorExecuteInput, options: ExecuteGraphqlOptions): Promise<ConnectorExecuteOutput>;
+/**
+ * Read the first error out of a GraphQL `errors` array.
+ *
+ * An `UNAUTHENTICATED`/`FORBIDDEN` extension code is mapped onto the auth vocabulary so the
+ * connection flips to `expired` and offers **Reconnect**, exactly as an HTTP 401 would. Without
+ * that mapping a GraphQL auth failure is indistinguishable from a typo in the document.
+ *
+ * @param errors - The `errors` member of a GraphQL envelope.
+ * @returns A typed error, or `null` when there are none.
+ */
+declare function firstGraphqlError(errors: unknown): ExecuteError | null;
+
+/**
+ * The file executors — `file.csv` and `file.json`.
+ *
+ * **The panel never enumerates paths and never learns one.** `fileRef` is an opaque handle the host
+ * minted from its own picker, exactly the discipline `xeno-shell` uses for host-folder mounts, where
+ * raw paths deliberately never cross the bridge. The panel asks "read this handle"; the host decides
+ * whether that handle is still valid, still consented, and still inside a granted mount.
+ *
+ * @module
+ */
+
+/** Options for the file executors. */
+interface ExecuteFileOptions {
+    readFile: XenoConnectorFileReader;
+    /** Byte ceiling for one read. Default 32 MiB. */
+    maxBytes?: number;
+}
+/**
+ * Read a delimited file into rows.
+ *
+ * @param input - Connection and the clamped row budget.
+ * @param options - The host's file reader and a byte ceiling.
+ * @returns Rows, or a typed error.
+ *
+ * @example
+ * ```ts
+ * await executeCsvFile({ connection, query: {}, limit: 500 }, { readFile })
+ * ```
+ */
+declare function executeCsvFile(input: ConnectorExecuteInput, options: ExecuteFileOptions): Promise<ConnectorExecuteOutput>;
+/**
+ * Read a JSON or NDJSON file into rows.
+ *
+ * @param input - Connection and the clamped row budget.
+ * @param options - The host's file reader and a byte ceiling.
+ * @returns Rows, or a typed error.
+ */
+declare function executeJsonFile(input: ConnectorExecuteInput, options: ExecuteFileOptions): Promise<ConnectorExecuteOutput>;
+
+/**
+ * The in-sandbox SQL bridge — **the honest bridge** of the capability matrix.
+ *
+ * Every other route to real SQL needs something a sandboxed panel cannot have: a TCP socket, a file
+ * handle, a host process. This one needs nothing. DuckDB-WASM runs *inside* the sandbox over buffers
+ * that were **already fetched** by connections that had their own permission to fetch them — so a
+ * user gets joins, `GROUP BY`, window functions and correct `NULL` semantics over their REST and CSV
+ * sources with **zero additional capabilities**, and it survives a web export.
+ *
+ * That is why the capability matrix lists this row as `requires: []` while every other `sql.*` row
+ * requires a host resolver. The data crossed the boundary once, under an existing grant; SQL over it
+ * afterwards is arithmetic.
+ *
+ * ## The engine is not a dependency
+ *
+ * `@duckdb/duckdb-wasm` is megabytes of wasm plus a worker. Rule 8 — no heavyweight runtime
+ * dependency — is not negotiable for a package that twenty other panels sit beside, and the lucide
+ * incident already proved what a static import costs every consumer who never uses the feature. So
+ * the engine arrives through the three-method {@link XenoSqlEngine} seam, resolved from the host,
+ * exactly as xterm does in `panel-terminal`. A reference adapter ships on the `./duckdb` subpath.
+ *
+ * **Absent engine ⇒ a visible `unsupported` state**, never a stub.
+ *
+ * @module
+ */
+
+/** Options for {@link executeDuckDb}. */
+interface ExecuteDuckDbOptions {
+    /** The engine. Absent means "no in-sandbox SQL here", which is a state, not a failure. */
+    engine?: XenoSqlEngine;
+    /**
+     * Fetch the rows of another connection, by id.
+     *
+     * Supplied by the controller, which already knows how to resolve a connection — including its
+     * cache, its credential and its own error handling. Re-implementing that here would give the SQL
+     * path a second, subtly different resolver.
+     */
+    resolveSource?: (connectionId: string) => Promise<{
+        rows: Record<string, unknown>[];
+        name?: string;
+    } | null>;
+    /** Whether a panel-authored `raw` statement may be executed. Mirrors the controller's config. */
+    allowRawQueries?: boolean;
+}
+/**
+ * Run SQL over already-fetched results.
+ *
+ * @param input - Connection, the pushed query, and the clamped row budget.
+ * @param options - The engine seam, the source resolver, and the raw-query gate.
+ * @returns Rows, or a typed error.
+ *
+ * @example
+ * ```ts
+ * // A duckdb source joining two REST connections:
+ * // config = { kind: 'sql.duckdb', mode: 'wasm', sourceConnectionIds: ['orders', 'customers'] }
+ * await executeDuckDb(input, { engine, resolveSource })
+ * ```
+ */
+declare function executeDuckDb(input: ConnectorExecuteInput, options: ExecuteDuckDbOptions): Promise<ConnectorExecuteOutput>;
+/**
+ * Turn a connection name or id into a safe, unique SQL table name.
+ *
+ * Registered table names are not merely quoted — in most engines they also name a registered buffer,
+ * where quoting protects nothing. So the name is *sanitized to an identifier*, not escaped: anything
+ * outside `[A-Za-z0-9_]` becomes `_`, a leading digit gains a prefix, and collisions get a numeric
+ * suffix so two sources called "Data" stay distinct.
+ *
+ * @param raw - The connection's display name or id.
+ * @param taken - Names already assigned, as a map of sourceId → name.
+ * @returns A safe, unused table name.
+ *
+ * @example
+ * ```ts
+ * uniqueTableName('Sales (EU)', new Map()) // → 'Sales__EU_'
+ * uniqueTableName('2024', new Map())       // → 't_2024'
+ * ```
+ */
+declare function uniqueTableName(raw: string, taken: Map<string, string>): string;
+
+/**
+ * A dependency-free RFC 4180 CSV reader.
+ *
+ * Rule 8 forbids a runtime dependency, so PapaParse is not an option — but "split on commas" is not
+ * a CSV parser either, and the difference shows up on the first export anyone actually has: a
+ * quoted field containing a comma, a newline inside a quoted address, a doubled `""` escape, or a
+ * UTF-8 BOM that turns the first column's name into `id` and makes every lookup by that name
+ * silently miss.
+ *
+ * This is a proper character-scanning parser. It is ~90 lines because CSV genuinely is that, and
+ * every one of the cases above has a test.
+ *
+ * @module
+ */
+/** Options for {@link parseCsv}. */
+interface ParseCsvOptions {
+    /** Field separator. Omit to sniff — see {@link sniffDelimiter}. */
+    delimiter?: string;
+    /** Quote character. Default `"`. */
+    quote?: string;
+    /** First (non-skipped) row is a header. Default `true`. */
+    hasHeader?: boolean;
+    /** Rows to drop before the header — banner lines above the table are common in exports. */
+    skipRows?: number;
+}
+/** The parsed table. */
+interface ParsedCsv {
+    /** Column names, either from the header row or synthesized as `column_1`, `column_2`, … */
+    columns: string[];
+    /** Records keyed by column name, values still as text. */
+    rows: Record<string, string>[];
+}
+/**
+ * Guess the field separator from the first meaningful line.
+ *
+ * Counts candidates **outside quotes only**, so a comma inside `"Smith, John"` does not vote for
+ * comma in a semicolon-separated European export — which is the case that makes naive sniffers pick
+ * the wrong character and produce a one-column table.
+ *
+ * @param text - The file's text.
+ * @returns The most likely delimiter. Falls back to `,`.
+ *
+ * @example
+ * ```ts
+ * sniffDelimiter('a;b;c\n"x, y";2;3') // → ';'
+ * ```
+ */
+declare function sniffDelimiter(text: string): string;
+/**
+ * Parse CSV text into records.
+ *
+ * @param text - The file contents.
+ * @param options - Delimiter, quote, header and skip settings.
+ * @returns Columns and records.
+ *
+ * @example
+ * ```ts
+ * parseCsv('id,name\n1,"Smith, John"\n')
+ * // → { columns: ['id','name'], rows: [{ id: '1', name: 'Smith, John' }] }
+ * ```
+ */
+declare function parseCsv(text: string, options?: ParseCsvOptions): ParsedCsv;
+/**
+ * Convert text cells into JSON-ish values.
+ *
+ * CSV has no types, so a reader must infer them — but **only where inference is safe**. A value is
+ * numeric only if it round-trips exactly through `String(Number(v))`, which is what keeps a zip code
+ * `01234`, a phone number `+15551234`, and a 20-digit account id from being silently mangled into
+ * `1234`, `15551234`, and a float that lost its last four digits.
+ *
+ * @param rows - Text records from {@link parseCsv}.
+ * @returns Records with numbers, booleans and nulls where they are unambiguous.
+ *
+ * @example
+ * ```ts
+ * coerceCsvValues([{ n: '42', zip: '01234', ok: 'true', gap: '' }])
+ * // → [{ n: 42, zip: '01234', ok: true, gap: null }]
+ * ```
+ */
+declare function coerceCsvValues(rows: Record<string, string>[]): Record<string, unknown>[];
+
+/**
+ * JSONPath extraction — finding the row array inside a response envelope.
+ *
+ * Almost no API returns a bare array. It returns `{data: {items: [...], next: "..."}}`, and the
+ * whole difference between a working REST source and a one-row table containing the word `[object
+ * Object]` is knowing where to look. `rootPath` is that knowledge.
+ *
+ * ## A deliberate subset, and why
+ *
+ * This implements the *dotted-path* subset of JSONPath — `$.data.items`, `data.items`,
+ * `results[0].rows`, `a["odd key"].b` — plus the `[*]` wildcard, and nothing else. No filter
+ * expressions, no recursive descent, no script evaluation.
+ *
+ * That is not laziness. A full JSONPath engine is a third-party runtime dependency (rule 8 forbids
+ * it) *and* the expression-evaluating half of the grammar is an injection surface pointed at the
+ * response of a network call. The subset covers every shape the survey found in real connector
+ * configs, and the parts left out are the parts that could bite.
+ *
+ * @module
+ */
+/** One step in a parsed path. */
+type Step = {
+    kind: 'key';
+    key: string;
+} | {
+    kind: 'index';
+    index: number;
+} | {
+    kind: 'wildcard';
+};
+/**
+ * Parse a dotted/bracketed path into steps.
+ *
+ * @param path - e.g. `$.data.items[0]`, `data["odd key"]`, `rows[*].cells`.
+ * @returns The steps, or `null` if the expression uses syntax this subset does not implement.
+ *
+ * @example
+ * ```ts
+ * parseJsonPath('$.data.items[0]')
+ * // → [{kind:'key',key:'data'},{kind:'key',key:'items'},{kind:'index',index:0}]
+ * ```
+ */
+declare function parseJsonPath(path: string): Step[] | null;
+/**
+ * Read a value out of parsed JSON at `path`.
+ *
+ * @param input - The parsed response body.
+ * @param path - A dotted/bracketed path. Empty or `'$'` returns `input` unchanged.
+ * @returns The value at the path, or `undefined` if any step is missing.
+ *
+ * @example
+ * ```ts
+ * extractJsonPath({ data: { items: [1, 2] } }, 'data.items') // → [1, 2]
+ * extractJsonPath({ pages: [{ rows: [1] }, { rows: [2] }] }, 'pages[*].rows') // → [[1],[2]]
+ * ```
+ */
+declare function extractJsonPath(input: unknown, path: string | undefined): unknown;
+/**
+ * Extract the row array from a response, with a documented fallback.
+ *
+ * When no `rootPath` is configured, an envelope is still the common case, so this looks for the
+ * conventional wrappers (`data`, `items`, `results`, `records`, `rows`, `value`) before giving up.
+ * **The fallback only fires when the top level is not already an array** — a source that returned
+ * exactly what we wanted is never second-guessed.
+ *
+ * @param body - The parsed response body.
+ * @param rootPath - The configured path, if any.
+ * @returns The rows, and how they were found.
+ *
+ * @example
+ * ```ts
+ * extractRows({ items: [{ id: 1 }] }, undefined) // → { rows: [{id:1}], via: 'convention' }
+ * ```
+ */
+declare function extractRows(body: unknown, rootPath: string | undefined): {
+    rows: unknown;
+    via: 'path' | 'convention' | 'root';
+    missing?: boolean;
+};
+
+/**
+ * Compiling a `XenoQuery` into SQL.
+ *
+ * Used by the in-sandbox DuckDB bridge, and offered to any host resolver that would otherwise write
+ * this itself. It is the highest-risk file in the package, so the rules are absolute:
+ *
+ * - **Every identifier is quoted and escaped.** A column called `"; DROP TABLE x; --` becomes the
+ *   literal identifier `"""; DROP TABLE x; --"`, which is a column that does not exist — an error,
+ *   never an execution.
+ * - **Every literal is escaped or refused.** Strings double their quotes; numbers must be finite;
+ *   anything else becomes a parameterless `NULL`. There is no path by which a value reaches the
+ *   statement uninspected.
+ * - **`raw` is never assembled here.** A panel-authored raw string is the family's injection
+ *   surface and is gated on `allowRawQueries` in the controller, upstream of this file.
+ *
+ * The output targets DuckDB, whose dialect is PostgreSQL-compatible for everything used here.
+ *
+ * @module
+ */
+
+/**
+ * Quote a SQL identifier.
+ *
+ * @param name - A table or column name from user data.
+ * @returns The safely quoted identifier.
+ *
+ * @example
+ * ```ts
+ * quoteIdent('order')          // → '"order"'
+ * quoteIdent('a"; DROP b; --') // → '"a""; DROP b; --"'   (one identifier, not a statement)
+ * ```
+ */
+declare function quoteIdent(name: string): string;
+/**
+ * Render a value as a SQL literal.
+ *
+ * @param value - Any value from a filter or parameter.
+ * @returns A literal safe to concatenate.
+ *
+ * @example
+ * ```ts
+ * quoteLiteral("O'Brien") // → "'O''Brien'"
+ * quoteLiteral(NaN)       // → 'NULL'   (a non-finite number is not a number)
+ * ```
+ */
+declare function quoteLiteral(value: XenoValue | undefined): string;
+/** Is this a valid, safe table name to register with the engine? */
+declare function isSafeTableName(name: string): boolean;
+/** Options for {@link buildSelect}. */
+interface BuildSelectOptions {
+    /** Table to read from. Must satisfy {@link isSafeTableName}. */
+    table: string;
+    /** The query to compile. */
+    query: XenoQuery;
+    /** Row ceiling. */
+    limit: number;
+    /** Row offset. */
+    offset?: number;
+    /** Columns known to exist. When supplied, unknown column ids are refused rather than emitted. */
+    columns?: string[];
+}
+/** A compiled statement, or the reason it could not be compiled. */
+type BuildSelectResult = {
+    sql: string;
+} | {
+    error: string;
+};
+/**
+ * Compile a query into a `SELECT`.
+ *
+ * @param options - Table, query, paging and the known column list.
+ * @returns The statement, or an authored refusal.
+ *
+ * @example
+ * ```ts
+ * buildSelect({
+ *   table: 'orders',
+ *   query: { aggregates: [{ id: 'total', columnId: 'amount', fn: 'sum' }], groupBy: [{ columnId: 'region' }] },
+ *   limit: 100,
+ * })
+ * // → { sql: 'SELECT "region", sum("amount") AS "total" FROM "orders" GROUP BY "region" LIMIT 100' }
+ * ```
+ */
+declare function buildSelect(options: BuildSelectOptions): BuildSelectResult;
+/** Render a filter group into a WHERE fragment. */
+declare function renderFilterGroup(group: XenoFilterGroup, unknown?: (id: string) => boolean): {
+    sql: string;
+} | {
+    error: string;
+};
+/**
+ * Escape `%`, `_` and `\` so user text is matched literally inside a LIKE pattern.
+ *
+ * @param text - Raw user input.
+ * @returns The escaped text, for use with `ESCAPE '\'`.
+ *
+ * @example
+ * ```ts
+ * escapeLikePattern('50%') // → '50\\%'  — searches for the character %, not "anything"
+ * ```
+ */
+declare function escapeLikePattern(text: string): string;
+
+/**
+ * The executor dispatcher — one function per connection kind, chosen by the discriminator.
+ *
+ * The `switch` below is exhaustive over `XenoConnectionConfig['kind']`, which is the entire reason
+ * the config is a discriminated union rather than a flat bag. §6 L13 is a live bug produced by the
+ * alternative: one surveyed connector branches on `rest` and lets *every other kind* fall through to
+ * the SQL path, so a declared-but-unhandled `graphql` source dies with *"Database queries require
+ * main process IPC"* — a message about a subsystem it never touched. Here a missing branch does not
+ * compile.
+ *
+ * @module
+ */
+
+/** Options for {@link createConnectorExecutor}. */
+interface CreateConnectorExecutorOptions {
+    /** The host's transport seams. Every field optional; absence is a state, not a bug. */
+    transport?: ConnectorTransport;
+    /**
+     * A host-side resolver for `sql.*` and the first-party `xeno.*` kinds.
+     *
+     * Also consulted as a **fallback** for any kind whose transport is missing, so a desktop host can
+     * supply one resolver and get every kind rather than wiring three seams.
+     */
+    hostResolver?: HostSqlResolver;
+    /** Whether a panel-authored `raw` statement may execute. Default `false`. */
+    allowRawQueries?: boolean;
+    /** Fetch another connection's rows, for the in-sandbox SQL bridge. Supplied by the controller. */
+    resolveSource?: (connectionId: string) => Promise<{
+        rows: Record<string, unknown>[];
+        name?: string;
+    } | null>;
+}
+/**
+ * Build the executor the controller calls for every non-`inline` source.
+ *
+ * `inline` never reaches here: it is resolved in the controller with no round-trip at all, which is
+ * what makes the first `table` drag in the builder a live grid rather than a dead one.
+ *
+ * @param options - Transports, an optional host resolver, and the raw-query gate.
+ * @returns An executor.
+ *
+ * @example
+ * ```ts
+ * const execute = createConnectorExecutor({
+ *   transport: { fetch: browserFetch(), readFile: hostReadFile },
+ *   hostResolver: ipcSqlResolver,
+ * })
+ * ```
+ */
+declare function createConnectorExecutor(options?: CreateConnectorExecutorOptions): (input: ConnectorExecuteInput) => Promise<ConnectorExecuteOutput>;
+
+/**
+ * The `PanelModule` — what a host registers and mounts.
+ *
+ * Ships a wired default (`connectorsPanel`) with the view mounted INSIDE the package, so `react` and
+ * `react-dom` resolve to one copy. A host that calls `createRoot` against a view imported from a
+ * `file:`-linked package gets two React copies and every hook throws *"Invalid hook call"*.
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface ConnectorsRenderContext {
+    controller: ConnectorsController;
+    config: {
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createConnectorsPanel}. */
+interface CreateConnectorsPanelOptions {
+    /**
+     * A complete host-side executor, replacing the built-in one entirely.
+     *
+     * Use this when the host has its own resolver for **every** kind. To keep the built-in protocol
+     * handling and only add what the substrate allows, pass {@link transport} instead — that is the
+     * ordinary case.
+     */
+    execute?: ConnectorsHostBridge['execute'];
+    /**
+     * The host's transport seams: `fetch`, `readFile`, and an in-sandbox SQL engine.
+     *
+     * The panel owns the protocol — paging, extraction, parsing, error classification — and the host
+     * owns the act. Every field is optional and **absence is meaningful**: no `fetch` means this
+     * substrate has no network, which renders as a visible `unsupported` card rather than a source
+     * that fails later.
+     */
+    transport?: ConnectorTransport;
+    /**
+     * A host-side resolver for `sql.*` and the first-party `xeno.*` kinds, which no sandboxed panel
+     * can serve. Also the fallback for any kind whose transport is absent.
+     */
+    hostResolver?: HostSqlResolver;
+    /**
+     * What the substrate can do.
+     *
+     * **Derived from the transports when omitted**, which is the honest default: the controller's own
+     * fallback assumes everything is available, and a source that reports healthy and then fails at
+     * query time is precisely the "stub that fails later" the capability matrix forbids.
+     */
+    facilities?: SubstrateFacilities;
+    /** Override the renderer. Rarely needed — see the module doc. */
+    render?: (root: HTMLElement, context: ConnectorsRenderContext) => () => void;
+}
+/**
+ * Build the Connectors panel module.
+ *
+ * @param options - Executor, substrate facilities, optional renderer.
+ * @returns The module.
+ */
+declare function createConnectorsPanel(options?: CreateConnectorsPanelOptions): PanelModule;
+/** The default Connectors panel module — view already wired. Register THIS. */
+declare const connectorsPanel: PanelModule;
+
+/**
+ * The `xeno.core.connectors` manifest.
+ *
+ * **The only panel in the data family holding a capability.** `table`, `chart`, `metrics`,
+ * `calendar` and `fields` declare `storage.local` and nothing else *because this one declares
+ * `net.fetch` and `fs.read`* — the seam concentrates every dangerous power in one auditable place.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const CONNECTORS_PANEL_ID = "xeno.core.connectors";
+/**
+ * Commands an agent must never be able to invoke.
+ *
+ * `submit_credential` is the whole list: an agent that can call it can read the form it answers and
+ * replay a credential. The SDK has no `agentVisible` field yet, so the panel enforces it — the
+ * command is absent from the manifest entirely and reachable only through the view.
+ */
+declare const AGENT_HIDDEN_COMMANDS: readonly string[];
+/** The `xeno.core.connectors` manifest. */
+declare const connectorsManifest: PanelManifest;
+
+/**
+ * The credential form — the panel's half, and only the panel's half.
+ *
+ * The lock from §3 holds with one precision that is worth stating exactly, because it is the
+ * difference between a rule people follow and a rule people quietly break: **the panel never
+ * receives a *stored* secret, and holds an *entered* one only in transient component state that is
+ * cleared at the moment of submission.** A user has to be able to type a password; they must never
+ * be able to read one back.
+ *
+ * A counter-example is on the record. `xeno-hub`'s environment-secrets section reveals stored
+ * secrets behind an eye-toggle. If this panel ever ships in Hub, **that affordance does not come
+ * with it** — there is no code path here that can render a stored value, because no stored value
+ * ever arrives.
+ *
+ * @module
+ */
+
+/** Values entered into a form, before submission. */
+type CredentialDraft = Record<string, string | number | boolean>;
+/**
+ * Should this field be shown, given the current draft?
+ *
+ * `showWhen` is what lets one descriptor serve "API key *or* username+password" without the panel
+ * knowing which platform it is rendering — the property that keeps a vendor registry out of this
+ * package entirely.
+ *
+ * @param field - The field to test.
+ * @param draft - Values entered so far.
+ * @returns Whether to render it.
+ *
+ * @example
+ * ```ts
+ * isFieldVisible(
+ *   { key: 'pw', label: 'Password', type: 'password', showWhen: { key: 'mode', equals: ['basic'] } },
+ *   { mode: 'basic' },
+ * ) // → true
+ * ```
+ */
+declare function isFieldVisible(field: XenoCredentialField, draft: CredentialDraft): boolean;
+/**
+ * The fields a form is currently showing.
+ *
+ * @param spec - The host's form descriptor.
+ * @param draft - Values entered so far.
+ * @returns Visible fields, in declared order.
+ */
+declare function visibleFields(spec: XenoCredentialFormSpec, draft: CredentialDraft): XenoCredentialField[];
+/** A per-field validation result, keyed by field key. */
+type CredentialErrors = Record<string, string>;
+/**
+ * Validate a draft against its descriptor.
+ *
+ * **Only visible fields are required.** A required field hidden by its own `showWhen` would
+ * otherwise block submission with an error pointing at a control that is not on screen — which
+ * looks, to the user, exactly like a broken form.
+ *
+ * @param spec - The form descriptor.
+ * @param draft - Values entered so far.
+ * @returns Messages by field key. Empty means valid.
+ *
+ * @example
+ * ```ts
+ * validateCredentialDraft({ …, fields: [{ key: 'token', label: 'Token', type: 'password', required: true }] }, {})
+ * // → { token: 'Token is required.' }
+ * ```
+ */
+declare function validateCredentialDraft(spec: XenoCredentialFormSpec, draft: CredentialDraft): CredentialErrors;
+/**
+ * Drop values belonging to hidden fields.
+ *
+ * A user who fills in a password, switches the mode selector to "API key", and submits would
+ * otherwise send the password too — a secret they believe they abandoned, travelling to a host that
+ * will store it. Submitting only what is on screen is what makes "I changed my mind" mean it.
+ *
+ * @param spec - The form descriptor.
+ * @param draft - Everything entered.
+ * @returns Only the visible fields' values.
+ */
+declare function pruneHiddenValues(spec: XenoCredentialFormSpec, draft: CredentialDraft): CredentialDraft;
+/**
+ * Is this descriptor usable?
+ *
+ * §6 L2: a form-mode credential with no fields must be **rejected at registration, not at click** —
+ * a card that offers "Connect", opens an empty modal, and can never be completed is a dead end the
+ * user cannot diagnose. A host validating its own descriptors at registration time turns that into
+ * a developer-visible error instead.
+ *
+ * @param spec - The descriptor.
+ * @returns A reason it is unusable, or `null`.
+ *
+ * @example
+ * ```ts
+ * credentialSpecProblem({ requestId: '1', connectionId: 'c', title: 'X', mode: 'form' })
+ * // → 'A form credential needs at least one field.'
+ * ```
+ */
+declare function credentialSpecProblem(spec: XenoCredentialFormSpec): string | null;
+
+/**
+ * The OAuth halves — loopback hardening, state, PKCE, and token refresh.
+ *
+ * ## Whose code is this?
+ *
+ * The panel's half of an OAuth flow is small and boring: render the redirect-URI hint verbatim, show
+ * a button, wait for `credentialChanged`. The *host's* half is where every landmine in §6 lives —
+ * and in `xeno-apps` the connectors panel **is** the host-side resolver, so this package is where
+ * that logic belongs.
+ *
+ * Everything here is pure and injectable: no timers of its own, no global clock, no network. A host
+ * that already owns a vault composes these functions into it; a host that does not gets a correct
+ * implementation instead of the fourth independent one. Each landmine below was solved exactly once
+ * somewhere in the ecosystem and nowhere twice — which is the definition of knowledge that should
+ * live in one package.
+ *
+ * @module
+ */
+/**
+ * The loopback redirect URI, **derived from the port actually bound**.
+ *
+ * §6 L3 is a mismatch that costs an afternoon every time: one implementation falls back to
+ * `localhost:3000` when three environment variables are unset — silently registering a URI the
+ * server never listens on — while another derives it correctly from the loopback port. Deriving is
+ * right, but the fix that actually stops the bug is **rendering the exact string to the user**, so
+ * the value they paste into the provider's console and the value the token exchange sends are the
+ * same characters.
+ *
+ * `127.0.0.1` is deliberate, not stylistic: RFC 8252 §7.3 requires the literal IP rather than
+ * `localhost`, because `localhost` can resolve to an address another process is listening on.
+ *
+ * @param port - The port the loopback server actually bound.
+ * @param path - The callback path. Default `/callback`.
+ * @returns The exact URI to register with the provider.
+ *
+ * @example
+ * ```ts
+ * redirectUriFor(8730) // → 'http://127.0.0.1:8730/callback'
+ * ```
+ */
+declare function redirectUriFor(port: number, path?: string): string;
+/** A request arriving at the loopback callback server. */
+interface LoopbackRequest {
+    /** The request target, e.g. `/callback?code=…&state=…`. */
+    url: string;
+    /** Request headers, any casing. */
+    headers: Record<string, string | string[] | undefined>;
+    method?: string;
+}
+/** The verdict on a loopback request. */
+type LoopbackVerdict = {
+    ok: true;
+    code: string;
+    state: string;
+} | {
+    ok: false;
+    status: 404 | 400 | 403;
+    reason: string;
+};
+/**
+ * Validate a request hitting the one-shot loopback server.
+ *
+ * The engineering log's note on this is blunt: *"binding 127.0.0.1 is NOT enough."* A page on any
+ * website can point a `<form>` or an `<img>` at `http://127.0.0.1:8730/callback?...`, and DNS
+ * rebinding lets an attacker's domain resolve to 127.0.0.1 so the browser sends the request with
+ * **their** hostname in the `Host` header. Binding the interface stops remote packets; it does not
+ * stop the user's own browser being aimed at the port.
+ *
+ * The surveyed implementation is good on three counts — one-shot, no reflected parameters, 404s
+ * non-callback paths — and **does not validate `Host`**. This adds it: the header must be a literal
+ * loopback address with the expected port, so a rebound hostname is refused before the `code` is
+ * ever read.
+ *
+ * @param request - The incoming request.
+ * @param expected - The port and path the server bound.
+ * @returns The extracted `code`/`state`, or a refusal with a status.
+ *
+ * @example
+ * ```ts
+ * validateLoopbackRequest(
+ *   { url: '/callback?code=a&state=b', headers: { host: 'evil.com:8730' } },
+ *   { port: 8730 },
+ * )
+ * // → { ok: false, status: 403, reason: 'unexpected Host header' }
+ * ```
+ */
+declare function validateLoopbackRequest(request: LoopbackRequest, expected: {
+    port: number;
+    path?: string;
+}): LoopbackVerdict;
+/**
+ * Is this `Host` header a literal loopback address on the expected port?
+ *
+ * Only the literal forms pass. **`localhost` is rejected on purpose**: it is a name, and a name is
+ * exactly what DNS rebinding controls.
+ */
+declare function isLoopbackHost(host: string, port: number): boolean;
+/** One outstanding authorization attempt. */
+interface OAuthStateRecord {
+    state: string;
+    connectionId: string;
+    /** PKCE verifier, held until the token exchange. */
+    verifier?: string;
+    /** Absolute epoch ms. */
+    expiresAt: number;
+    /** Anything the host needs on the way back. **Never a secret.** */
+    meta?: Record<string, string>;
+}
+/** Options for {@link createOAuthStateStore}. */
+interface OAuthStateStoreOptions {
+    now?: () => number;
+    /** Time-to-live. Default 10 minutes, per the spec. */
+    ttlMs?: number;
+    /** Random state generator, injectable for tests. Must produce ≥192 bits of entropy. */
+    randomState?: () => string;
+}
+/** An atomic, single-use OAuth state store. */
+interface OAuthStateStore {
+    /** Mint a state for a connection. */
+    issue(connectionId: string, options?: {
+        verifier?: string;
+        meta?: Record<string, string>;
+    }): OAuthStateRecord;
+    /**
+     * **Atomically** take the record for a state. A second call with the same state returns `null`.
+     *
+     * There is deliberately no `peek`.
+     */
+    consume(state: string): OAuthStateRecord | null;
+    /** Drop expired records. Returns how many went. */
+    sweep(): number;
+    /** Outstanding count, for tests and diagnostics. */
+    size(): number;
+}
+/**
+ * A CSRF state store whose only read is a **consume**.
+ *
+ * §6 L11: one surveyed implementation *peeks* at the state to look up the connection and then
+ * consumes it in a second call. Two concurrent callbacks both pass the peek, and the window between
+ * the two calls is exactly the race a CSRF state exists to close. The invariant is *one atomic
+ * consume, checked at the point of use* — so this store **has no peek to misuse**. Anything the
+ * caller wanted from a peek is returned by the consume itself.
+ *
+ * @param options - Clock, TTL and randomness, all injectable.
+ * @returns The store.
+ *
+ * @example
+ * ```ts
+ * const store = createOAuthStateStore()
+ * const { state } = store.issue('conn-1', { verifier })
+ * store.consume(state) // → the record
+ * store.consume(state) // → null. Always.
+ * ```
+ */
+declare function createOAuthStateStore(options?: OAuthStateStoreOptions): OAuthStateStore;
+/**
+ * Base64url-encode bytes, without padding.
+ *
+ * Encoded by hand rather than through `btoa` or `Buffer`: this package targets the browser *and*
+ * QuickJS *and* Node, `btoa` is absent in some of those, `Buffer` in others, and a panel that
+ * assumes either one has quietly taken a runtime dependency on its substrate. Twelve lines removes
+ * the question.
+ *
+ * @param bytes - Raw bytes.
+ * @returns Unpadded base64url text, as RFC 7636 requires for a PKCE verifier.
+ *
+ * @example
+ * ```ts
+ * base64Url(new Uint8Array([255, 254, 253])) // → '__79'
+ * ```
+ */
+declare function base64Url(bytes: Uint8Array): string;
+/** A PKCE verifier/challenge pair. */
+interface PkcePair {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+/**
+ * Generate a PKCE pair.
+ *
+ * **S256 only.** `plain` is still in RFC 7636 and is worthless: the "challenge" is the verifier, so
+ * anything that can read the authorization request can complete the exchange. Offering it as an
+ * option would only ever be a way to pick the broken one.
+ *
+ * @param digest - SHA-256 implementation. Defaults to WebCrypto; injectable for tests.
+ * @returns The pair.
+ *
+ * @example
+ * ```ts
+ * const { verifier, challenge } = await createPkcePair()
+ * ```
+ */
+declare function createPkcePair(digest?: (input: Uint8Array) => Promise<Uint8Array>): Promise<PkcePair>;
+/** A stored OAuth credential. **Never rendered, never serialized into a document.** */
+interface StoredOAuthToken {
+    accessToken: string;
+    refreshToken?: string;
+    /** Absolute epoch ms. Never a duration — see {@link mergeRefreshResponse}. */
+    expiresAt?: number;
+    tokenType?: string;
+    scope?: string;
+}
+/** A token endpoint's response. */
+interface TokenEndpointResponse {
+    access_token?: string;
+    refresh_token?: string;
+    /** Seconds from *now*, as OAuth defines it. */
+    expires_in?: number;
+    token_type?: string;
+    scope?: string;
+}
+/** Clock skew allowance, ms. */
+declare const EXPIRY_SKEW_MS = 60000;
+/**
+ * Merge a refresh response over the stored credential.
+ *
+ * **§6 L4, both halves:**
+ *
+ * 1. *Expiry is absolute epoch ms, with a 60 s skew.* A stored `expires_in` is a duration measured
+ *    from a moment nobody wrote down; after a restart it is unusable, and after a suspend it is a
+ *    lie. It is converted here, once, at the only point where "now" is known to be the right now.
+ * 2. 🔴 *A response omitting `refresh_token` must **preserve** the prior one.* Most providers rotate
+ *    the refresh token on every use, but a large minority — and every provider using a
+ *    non-expiring refresh token — return only a new access token. Overwriting with `undefined`
+ *    destroys the only credential that can ever get another access token, and the failure does not
+ *    appear until the *next* refresh, long after the code that caused it.
+ *
+ * @param prior - What is stored today, if anything.
+ * @param response - The token endpoint's answer.
+ * @param now - Current epoch ms.
+ * @returns The credential to store.
+ *
+ * @example
+ * ```ts
+ * mergeRefreshResponse({ accessToken: 'a', refreshToken: 'KEEP' }, { access_token: 'b' }, 0)
+ * // → { accessToken: 'b', refreshToken: 'KEEP' }
+ * ```
+ */
+declare function mergeRefreshResponse(prior: StoredOAuthToken | undefined, response: TokenEndpointResponse, now: number): StoredOAuthToken;
+/**
+ * Does this credential need refreshing?
+ *
+ * @param token - The stored credential.
+ * @param now - Current epoch ms.
+ * @param skewMs - Safety margin. Default {@link EXPIRY_SKEW_MS}.
+ * @returns Whether to refresh before using it.
+ *
+ * @example
+ * ```ts
+ * needsRefresh({ accessToken: 'a', expiresAt: 100_000 }, 40_000) // → true (inside the 60s skew)
+ * ```
+ */
+declare function needsRefresh(token: StoredOAuthToken | undefined, now: number, skewMs?: number): boolean;
+/** Coordinates refreshes so N consumers produce one exchange. */
+interface RefreshCoordinator<T> {
+    /**
+     * Refresh `key`, or join the refresh already running for it.
+     *
+     * @param key - Credential reference.
+     * @param run - Performs the exchange. Called at most once per concurrent burst.
+     */
+    refresh(key: string, run: () => Promise<T>): Promise<T>;
+    /** How many exchanges are in flight. */
+    inFlight(): number;
+    /** Refresh many keys, reporting **per key** — §6 L6. */
+    refreshAll(keys: string[], run: (key: string) => Promise<T>): Promise<{
+        key: string;
+        ok: boolean;
+        value?: T;
+        error?: string;
+    }[]>;
+}
+/**
+ * Dedupe concurrent refreshes of the same credential.
+ *
+ * §6 L5a: five panels sharing one connection all notice the expiry in the same tick and all start a
+ * refresh. With a rotating refresh token that is not merely wasteful — the first exchange
+ * invalidates the token the other four are holding, so four of them fail and, depending on the
+ * provider, the whole family is revoked for reuse. One exchange, four joiners.
+ *
+ * @returns The coordinator.
+ *
+ * @example
+ * ```ts
+ * const coordinator = createRefreshCoordinator<Token>()
+ * await Promise.all([a, b, c].map(() => coordinator.refresh('$cred:1', exchange)))
+ * // `exchange` ran exactly once.
+ * ```
+ */
+declare function createRefreshCoordinator<T>(): RefreshCoordinator<T>;
+
+/**
+ * The Connectors panel view — connection list, health, and the credential form.
+ *
+ * Composes `@xenosystem/workbench/primitives`. **The host must import
+ * `@xenosystem/workbench/primitives.css`** (or let the workbench inject it) or this renders unstyled with
+ * no error.
+ *
+ * Two things this view deliberately does NOT have:
+ *
+ * - **No secret reveal.** `xeno-hub`'s `EnvironmentSecretsSection` exposes stored secrets behind an
+ *   eye-toggle; that affordance does not come with this panel. The panel never receives a stored
+ *   secret, so there is nothing to reveal.
+ * - **No masked value round-trip.** A form field is uncontrolled-by-design local state that is
+ *   cleared at submit; nothing here reads a value back from a saved document.
+ *
+ * @module
+ */
+
+/** Props for {@link ConnectorsPanelView}. */
+interface ConnectorsPanelViewProps {
+    controller: ConnectorsController;
+    /** Hint shown when no source is configured. */
+    emptyHint?: string;
+}
+/** The Connectors panel view. */
+declare function ConnectorsPanelView({ controller, emptyHint, }: ConnectorsPanelViewProps): ReactNode;
+
+export { AGENT_HIDDEN_COMMANDS, ALL_AGGREGATES, ALL_CHART_TYPES, type BuildChartOptions, type BuildSelectOptions, type BuildSelectResult, CHART_EMPTY_FILL, CHART_PALETTE_STEPS, CHART_PANEL_ID, CONNECTORS_PANEL_ID, type CellAddress, ChartController, type ChartControllerOptions, type ChartHostBridge, type ChartPanelState, ChartPanelView, type ChartPanelViewProps, type ChartRenderContext, type ChartRenderInput, type ChartRenderOptions, type ChartRenderer, type ChartViewState, type ColumnLayout, type ColumnWindow, ConnectorExecuteInput, ConnectorExecuteOutput, ConnectorTransport, ConnectorsController, type ConnectorsControllerOptions, type ConnectorsHostBridge, ConnectorsPanelState, ConnectorsPanelView, type ConnectorsPanelViewProps, type ConnectorsRenderContext, ConnectorsViewState, type CreateChartPanelOptions, type CreateConnectorExecutorOptions, type CreateConnectorsPanelOptions, type CreateFieldsPanelOptions, type CreateMetricsPanelOptions, type CreateTablePanelOptions, type CredentialDraft, type CredentialErrors, DEFAULT_COLUMN_WIDTH, DEFAULT_PAGE_SIZE, DEFAULT_RANGES, type DeltaDirection, EMPTY_LAYOUT, EXPIRY_SKEW_MS, type ExecuteError, FIELDS_PANEL_ID, FieldsController, type FieldsControllerOptions, type FieldsHostBridge, type FieldsPanelState, FieldsPanelView, type FieldsPanelViewProps, type FieldsRenderContext, type FieldsViewState, type HostSqlResolver, IMPLEMENTED_VIEW_MODES, type LoopbackRequest, type LoopbackVerdict, METRICS_PANEL_ID, MIN_COLUMN_WIDTH, MONO_FILL_PALETTE, MONO_PALETTE, MetricsController, type MetricsControllerOptions, type MetricsHostBridge, type MetricsPanelState, MetricsPanelView, type MetricsPanelViewProps, type MetricsRenderContext, type MetricsViewState, type NumericConstraints, type OAuthStateRecord, type OAuthStateStore, type OAuthStateStoreOptions, type ParseCsvOptions, type ParseResult, type ParsedCsv, type PkcePair, PushdownSplit, type RefreshCoordinator, type ResolvedColumn, SHELF_PRESETS, type StoredOAuthToken, SubstrateFacilities, TABLE_PANEL_ID, TableController, type TableControllerOptions, type TableHostBridge, type TablePanelState, TablePanelView, type TablePanelViewProps, type TableRenderContext, type TableViewMode, type TableViewState, type TokenEndpointResponse, type VirtualWindow, type XenoAlertLevel, type XenoCalculatedFieldRequest, type XenoCellEdit, type XenoChartData, type XenoChartDrillDown, type XenoChartEncoding, type XenoChartExportRequest, type XenoChartHighlight, type XenoChartSeries, type XenoChartType, XenoConnection, XenoConnectionStatus, XenoConnectorFetch, XenoConnectorFileReader, XenoConnectorQueryRequest, XenoCredentialField, XenoCredentialFormSpec, XenoCredentialResult, type XenoFieldStat, type XenoMetricAlert, type XenoMetricRange, type XenoMetricSpec, type XenoMetricThreshold, type XenoMetricValue, XenoResolverErrorCode, XenoRestPaging, type XenoRowActivate, type XenoShelfEntry, type XenoShelfSpec, XenoSqlEngine, applyPrecision, base64Url, breachSideOf, buildChartData, buildRestUrl, buildSelect, chartManifest, chartPanel, clamp, classifyHttpStatus, coerceCsvValues, columnIndexAt, columnsOf, compileForHost, computeColumnWindow, computeWindow, connectorsManifest, connectorsPanel, constraintsOfColumn, createChartPanel, createConnectorExecutor, createConnectorsPanel, createFieldsPanel, createMetricsPanel, createOAuthStateStore, createPkcePair, createRefreshCoordinator, createTablePanel, credentialSpecProblem, defaultAggregateFor, defaultEncoding, deltaToneOf, emptyFilterGroup, entityOf, escapeLikePattern, executeCsvFile, executeDuckDb, executeGraphql, executeJsonFile, executeRest, executeSql, extractJsonPath, extractRows, fieldsManifest, fieldsPanel, firstGraphqlError, frozenWidth, getChartRenderer, isCategorical, isFieldVisible, isFilled, isLeafFilter, isLoopbackHost, isSafeTableName, mergeRefreshResponse, metricsManifest, metricsPanel, moveCell, moveColumn, needsRefresh, nextPageToken, normalizeLayout, normalizeNumeric, offerableAggregates, offerableFilterOps, parseCsv, parseJsonBody, parseJsonPath, parseLinkHeader, parseNumeric, pruneHiddenValues, queriesEqual, quoteIdent, quoteLiteral, redirectUriFor, renderFilterGroup, resolveChartColors, resolveColumns, rowsForMark, scrollLeftToReveal, scrollTopToReveal, setChartRenderer, setColumnVisible, setColumnWidth, setFrozenCount, sniffDelimiter, suggestedShelfFor, tableManifest, tablePanel, toChartJsConfig, toExecuteError, totalWidth, uniqueTableName, unsupportedMessage, validateCredentialDraft, validateEncoding, validateLoopbackRequest, visibleFields };