@tangle-network/agent-app 0.45.53 → 0.45.55

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

@@ -0,0 +1,43 @@
+/**
+ * The React half of the motion primitives that ship in `src/theme/tokens.css`.
+ *
+ * The stylesheet owns every keyframe, duration and easing, and that is the
+ * whole point: a component that writes its own timing is invisible to the
+ * reduced-motion collapse at `:root`, so "it writes its own timing" and "it
+ * ignores reduced motion" are the same defect. The one thing CSS cannot supply
+ * is WHERE in a group a row sits, which is per-element data — hence these two
+ * helpers and nothing else.
+ */
+import { type CSSProperties } from 'react';
+/**
+ * Position in a staggered `.agent-arrive` group. `--stagger-index` is a custom
+ * property and `CSSProperties` has no index signature for one, so the cast is
+ * the only way to hand React a value tokens.css already defines (it declares
+ * the property with a `0` default and caps the delay at 8 steps internally, so
+ * a long list never opens with a multi-second cascade).
+ *
+ * Use it directly only where the group's order is FIXED once rendered — an
+ * ask's option rows, a turn's append-only tool segments. A list that can
+ * re-sort wants {@link useArrivalStyle}.
+ *
+ * `base` merges a caller's own style, because a row that carries layout of its
+ * own would otherwise have to spread the two itself at every call site, and the
+ * spread order matters: the index must win, or a stale `--stagger-index` on the
+ * base silently overrides the position being asked for.
+ */
+export declare function staggerStyle(index: number, base?: CSSProperties): CSSProperties;
+/**
+ * The same style, frozen at the row's first render.
+ *
+ * A settled `.agent-arrive` is finished, not inert: `animation-delay` is part
+ * of its timing, so handing an already-arrived row a LARGER delay pushes it
+ * back into the animation's before-phase and it plays again. Any list that
+ * re-sorts does exactly that — `mergeActivityPages` sorts newest-first, so one
+ * newer run landing on a refresh shifts every row's index by one and the whole
+ * panel would re-animate because nothing about it changed. Freezing the index
+ * at mount makes the arrival a property of ARRIVING rather than of the row's
+ * current position, which is the difference between choreography and flicker.
+ *
+ * Rules of hooks: a row that needs this is a component, not a `.map` body.
+ */
+export declare function useArrivalStyle(index: number): CSSProperties;

package/dist/web-react/provenance-model.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The pure half of the provenance affordance: what kind of claim a value is,
+ * what a reader should DO about it, and what has to be SAID when its origin
+ * cannot be shown.
+ *
+ * Zero React, zero DOM — a loader or a worker can decide a value's standing
+ * before it reaches a screen, and `./provenance`'s `ProvenanceValue` renders
+ * exactly what these functions decide.
+ *
+ * The distinction the module exists to hold: a person typing a number, a
+ * document carrying it, a formula producing it, and a model claiming it are
+ * four different kinds of evidence. Rendered as one grey caption they are
+ * indistinguishable, which is how an unverified model assertion reads to a
+ * reviewer as a transcribed fact.
+ *
+ * Every domain word is a caller parameter: no field names, no document kinds,
+ * and no confidence policy beyond a default the product overrides.
+ */
+/**
+ * How a value came to exist. Four kinds, never interchangeable:
+ *
+ * - `extracted` — read out of a document or message the product can open.
+ * - `entered` — a person typed or confirmed it.
+ * - `computed` — produced from other values, each carrying its own provenance.
+ * - `asserted` — the agent stated it, with nothing outside the model behind it.
+ */
+export type ProvenanceBasis = 'extracted' | 'entered' | 'computed' | 'asserted';
+/** Every basis, in the order a legend should list them. */
+export declare const PROVENANCE_BASES: readonly ProvenanceBasis[];
+/** The words one basis is rendered and announced with. */
+export interface ProvenanceBasisMeta {
+    /** Marker text next to the value — short, and never only a colour. */
+    label: string;
+    /** One plain sentence naming what kind of claim this is. */
+    meaning: string;
+    /** What a reader can hold the value against, or `null` when nothing outside
+     *  the model can. `null` is what makes an `asserted` value uncertifiable at
+     *  any confidence. */
+    checkableAgainst: string | null;
+}
+/** Words for one basis. */
+export declare function provenanceBasisMeta(basis: ProvenanceBasis): ProvenanceBasisMeta;
+/** Whether a source could be resolved. `ready` is the default for a source that
+ *  says nothing. */
+export type ProvenanceSourceStatus = 'ready' | 'loading' | 'unavailable';
+/** One thing a value came from. A `label` is mandatory because an unnamed
+ *  source is the same as no source. */
+export interface ProvenanceSource {
+    /** What the source IS, in the reader's words: "Form W-2 (Acme Corp)",
+     *  "Dana Whitfield", "Engagement letter". */
+    label: string;
+    /** The text in the source that carries the value. */
+    quote?: string;
+    /** Position inside the source — a page, a line, a span, a timestamp. The
+     *  caller's words; nothing here parses it. */
+    locator?: string;
+    /** Click-through target. Absent → the source is named but not openable. */
+    href?: string;
+    /** Defaults to `ready`. */
+    status?: ProvenanceSourceStatus;
+    /** Why an `unavailable` source cannot be opened, in one sentence. */
+    unavailableReason?: string;
+}
+/**
+ * What the reader should DO about a value — the only form confidence takes on
+ * screen. "89% confidence" names no next move; these three do.
+ *
+ * - `settled` — nothing to do.
+ * - `check` — open the source and confirm before relying on it.
+ * - `confirm` — a person has to confirm the value before it is used.
+ */
+export type ProvenanceStanding = 'settled' | 'check' | 'confirm';
+/** The words one standing is rendered and announced with. */
+export interface ProvenanceStandingMeta {
+    /** Short state label. */
+    label: string;
+    /** The next move, as a sentence a person can follow. */
+    action: string;
+}
+/** Words for one standing. */
+export declare function provenanceStandingMeta(standing: ProvenanceStanding): ProvenanceStandingMeta;
+/** The weaker of two standings — `confirm` beats `check` beats `settled`. */
+export declare function weakerProvenanceStanding(a: ProvenanceStanding, b: ProvenanceStanding): ProvenanceStanding;
+/**
+ * Where a product draws its confidence lines. These are a POLICY, not a truth:
+ * a number a model reports about itself means different things per surface, so
+ * the thresholds are a parameter and the number itself never reaches the screen.
+ */
+export interface ProvenanceConfidencePolicy {
+    /** At or above this, a value is `settled`. */
+    settledAtOrAbove: number;
+    /** At or above this (and below `settledAtOrAbove`), a value is `check`.
+     *  Below it, `confirm`. */
+    checkAtOrAbove: number;
+}
+/** The starting policy. Products with a different tolerance pass their own. */
+export declare const DEFAULT_PROVENANCE_CONFIDENCE_POLICY: ProvenanceConfidencePolicy;
+/** A value, where it came from, and — when it was computed — the provenanced
+ *  values it came from. The `inputs` field is what makes the shape compose:
+ *  a computed value's provenance IS its inputs. */
+export interface ProvenanceRecord {
+    /** The value as the reader should see it, already formatted. An empty string
+     *  is a missing value and renders as one, never as blank space. */
+    display: string;
+    /** What the value IS ("Wages", "Filing deadline"). Optional at the top level,
+     *  where the surface around it usually says; rendered for every composed
+     *  input, where nothing else names them. */
+    label?: string;
+    basis: ProvenanceBasis;
+    /** Where it came from. An `extracted` value without one is a gap, not a
+     *  detail. */
+    sources?: readonly ProvenanceSource[];
+    /** The provenanced values a `computed` value was produced from. */
+    inputs?: readonly ProvenanceRecord[];
+    /** How the inputs combine, in the caller's words ("wages + interest"). */
+    derivation?: string;
+    /** 0–1. Never rendered as a number — it selects a standing. */
+    confidence?: number;
+    /** Overrides the standing confidence and basis would produce — a reviewer
+     *  approved it, a gate failed. It can only make a value WEAKER: the
+     *  structural floors below still apply, so a product cannot mark a value
+     *  settled that has no origin on file. */
+    standing?: ProvenanceStanding;
+}
+/** The standing a bare confidence maps to under a policy. */
+export declare function standingFromConfidence(confidence: number, policy?: ProvenanceConfidencePolicy): ProvenanceStanding;
+/** Something missing that the reader has to be TOLD about, because the value
+ *  renders either way and a bare number reads as a fact. */
+export type ProvenanceGapKind = 'no-source' | 'no-inputs' | 'unavailable-source';
+/** One stated gap. `message` is rendered verbatim. */
+export interface ProvenanceGap {
+    kind: ProvenanceGapKind;
+    message: string;
+    /** The source that could not be resolved (`unavailable-source` only). */
+    source?: ProvenanceSource;
+}
+/** The sentence for a source that is not `ready`, or `null` when it is. One
+ *  source of this copy, so the row and the gap list never disagree. */
+export declare function describeProvenanceSourceStatus(source: ProvenanceSource): string | null;
+/**
+ * What this record cannot show, at its own level. Inputs are not walked: every
+ * composed input renders its own gaps next to its own value, where a reader can
+ * act on them.
+ */
+export declare function provenanceGaps(record: ProvenanceRecord): ProvenanceGap[];
+/** The sources still resolving — rendered as their own state, never as an
+ *  absence. A load in flight is not a missing source. */
+export declare function loadingProvenanceSources(record: ProvenanceRecord): ProvenanceSource[];
+/**
+ * This record's own standing, ignoring its inputs.
+ *
+ * The order is: start from the explicit standing, else from confidence, else
+ * from the basis — then apply every structural floor, taking the WEAKEST. The
+ * floors are what a caller cannot talk its way out of:
+ *
+ * - an `asserted` value never reaches `settled` (a model's own confidence
+ *   cannot certify the model's claim — there is nothing to check it against),
+ * - a `no-source` / `no-inputs` gap forces `confirm` (a value dressed as
+ *   evidence with no evidence behind it is worse than an open guess),
+ * - an unopenable source forces `check` (the value may be right; the reader
+ *   just cannot confirm it).
+ */
+export declare function resolveProvenanceStanding(record: ProvenanceRecord, policy?: ProvenanceConfidencePolicy): ProvenanceStanding;
+/**
+ * The standing a reader should see: this record's own, weakened by every value
+ * it was computed from, however deep.
+ *
+ * A total is only as trustworthy as the weakest number in it. Rendering the
+ * parent's own standing instead is how an exact sum of one document figure and
+ * one model guess presents as traced.
+ *
+ * Cycle-safe: a record reachable from itself is counted once.
+ */
+export declare function rollUpProvenanceStanding(record: ProvenanceRecord, policy?: ProvenanceConfidencePolicy, seen?: Set<ProvenanceRecord>): ProvenanceStanding;
+/**
+ * One plain sentence naming where the value came from — the panel's first line
+ * and part of what a screen reader announces. It states the absence when there
+ * is one, so no code path produces silence.
+ */
+export declare function describeProvenance(record: ProvenanceRecord): string;
+/**
+ * The move THIS value's reader can actually make.
+ *
+ * `provenanceStandingMeta().action` is the generic sentence for a standing;
+ * this is the one that accounts for what is on file. "Open the source and
+ * confirm it" is a dead instruction on a value that has no source — an action
+ * a reader cannot perform is the same defect as no action at all.
+ */
+export declare function provenanceNextMove(record: ProvenanceRecord, standing: ProvenanceStanding, policy?: ProvenanceConfidencePolicy): string;
+/**
+ * The accessible name of the disclosure control: the value, how it came to
+ * exist, and — unless there is nothing to do — the next move. This is the
+ * whole affordance for someone who never sees the colour.
+ */
+export declare function provenanceTriggerLabel(record: ProvenanceRecord, standing: ProvenanceStanding): string;

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

@@ -0,0 +1,82 @@
+/**
+ * `ProvenanceValue` — one value rendered so its origin is discoverable without
+ * navigating away, and openable when there is something to open.
+ *
+ * This is the affordance three verticals each rebuilt: tax renders a source
+ * quote under an expanded return line, legal renders authorities under a
+ * finding, the record grid renders a per-cell marker. Same product promise,
+ * three vocabularies, three sets of gaps.
+ *
+ * What the primitive holds that a hand-rolled caption does not:
+ *
+ * 1. The four bases render differently — a person's entry and a model's
+ *    assertion are never the same pixels. Each carries its own glyph AND its
+ *    own words, so the distinction survives greyscale and a screen reader.
+ * 2. It COMPOSES. A computed value's provenance is its inputs, and each input
+ *    is itself a `ProvenanceValue` with its own disclosure.
+ * 3. Confidence renders as the next move ("Check the source"), never as a
+ *    percentage a reader cannot act on.
+ * 4. The disclosure is a real button — keyboard reachable, `aria-expanded`,
+ *    Escape closes and returns focus, a click outside dismisses, and opening
+ *    one trail closes the one the reader left. Nothing here discloses on hover,
+ *    and no fact lives only in a `title` attribute.
+ * 5. A source that is loading, unopenable, or absent SAYS so. There is no path
+ *    through this component that renders a bare number.
+ *
+ * Layout: an inline-block block-level element, so put it in a table cell, a
+ * list item, or a card — not inside a `<p>`. Sandbox-ui-free, like the rest of
+ * `/web-react`; the model in `./provenance-model` is React-free.
+ */
+import { type ProvenanceBasis, type ProvenanceConfidencePolicy, type ProvenanceRecord, type ProvenanceSource } from './provenance-model';
+export * from './provenance-model';
+/** Properties for one provenanced value and its disclosure. */
+export interface ProvenanceValueProps {
+    /** The value and where it came from. */
+    record: ProvenanceRecord;
+    /**
+     * Open one source in the product's own way (a document pane at the right
+     * page, a drawer, a route). Takes precedence over `href` when both are
+     * present, because a product that routes wants its router — a source with
+     * neither is named but not openable, which is a legitimate state and is
+     * rendered as such.
+     */
+    onOpenSource?: (source: ProvenanceSource, record: ProvenanceRecord) => void;
+    /** Retry resolving an `unavailable` source. Absent → the failure is stated
+     *  without a retry control, never swallowed. */
+    onRetrySource?: (source: ProvenanceSource, record: ProvenanceRecord) => void;
+    /** Where this product draws its confidence lines. */
+    confidencePolicy?: ProvenanceConfidencePolicy;
+    /**
+     * How many levels of composed inputs stay expandable. Past it an input still
+     * renders its value, its basis and its origin sentence — it just stops
+     * carrying its own disclosure, so a deep tree cannot run away and a record
+     * that reaches itself cannot recurse forever. Default 2.
+     */
+    maxDepth?: number;
+    /** Open the disclosure on first render — for a review surface where the
+     *  trail is the point. Several of these coexist: only a reader opening a
+     *  trail closes another one. */
+    defaultOpen?: boolean;
+    /** What an empty `display` renders as. A blank cell is the defect this
+     *  component exists to remove. */
+    missingValueLabel?: string;
+    className?: string;
+}
+/**
+ * A value, its origin marker, and the disclosure that shows where it came
+ * from. The marker states the basis in words and, whenever there is something
+ * to do about the value, the next move — so the standing is legible at rest
+ * and does not depend on anyone opening the panel.
+ */
+export declare function ProvenanceValue({ record, onOpenSource, onRetrySource, confidencePolicy, maxDepth, defaultOpen, missingValueLabel, className, }: ProvenanceValueProps): import("react").JSX.Element;
+/** Properties for the basis legend. */
+export interface ProvenanceLegendProps {
+    /** Only the bases present on screen. Passing all four when only two appear
+     *  teaches distinctions the reader cannot use. */
+    bases: readonly ProvenanceBasis[];
+    className?: string;
+}
+/** The marker key for a surface that renders several bases at once — a review
+ *  pane, a grid, a return. Each row is the same glyph, tone and words the
+ *  markers use, plus what the basis MEANS. */
+export declare function ProvenanceLegend({ bases, className }: ProvenanceLegendProps): import("react").JSX.Element | null;

package/dist/web-react/provider-logo.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Provider brand marks — real logo path data (simple-icons / SVG Logos, both
+ * CC0) inlined so the picker shows actual provider identity instead of
+ * colored-initial monograms. Providers without a usable mark fall back to a
+ * tinted monogram chip. Aliases (z-ai/zai, moonshot/moonshotai, deepseek_ai)
+ * normalize to one entry.
+ */
+import type { ReactNode } from 'react';
+export interface ProviderLogoProps {
+    provider?: string;
+    size?: number;
+}
+/** Real brand mark when we have one; tinted monogram otherwise. */
+export declare function ProviderLogo({ provider, size }: ProviderLogoProps): ReactNode;

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

@@ -0,0 +1,257 @@
+/**
+ * The pure half of the editable record grid: the typed column vocabulary, the
+ * per-cell parse/validate rules, display + editor formatting, and the
+ * optimistic overlay a caller's rows are projected through.
+ *
+ * Zero React, zero DOM — a product can validate a row on a worker before it
+ * ever reaches storage, and the component in `./record-grid` renders exactly
+ * what these functions decide.
+ *
+ * Every domain word is a caller parameter: the module knows no column names,
+ * no currencies, no option sets. What it owns is the mechanism four verticals
+ * each re-derived — typed cells, an error a person can act on, and an
+ * optimistic edit that can be taken back.
+ */
+import type { ProvenanceBasis } from './provenance-model';
+/** The value one cell can hold. `null` is "no value on file". */
+export type RecordGridValue = string | number | boolean | null;
+/** Typed outcome for one cell. Callers MUST inspect `succeeded` before reading
+ *  `value`; nothing here throws. */
+export type RecordGridCellOutcome = {
+    succeeded: true;
+    value: RecordGridValue;
+} | {
+    succeeded: false;
+    error: string;
+};
+/** Typed outcome for a whole row of inputs (the add form). `cellErrors` is
+ *  keyed by column id so each control can render its own message. */
+export type RecordGridRowOutcome = {
+    succeeded: true;
+    value: Record<string, RecordGridValue>;
+} | {
+    succeeded: false;
+    error: string;
+    cellErrors: Readonly<Record<string, string>>;
+};
+/** Build a cell success outcome. */
+export declare function recordGridOk(value: RecordGridValue): RecordGridCellOutcome;
+/** Build a cell failure outcome carrying the message shown next to the cell. */
+export declare function recordGridFail(error: string): RecordGridCellOutcome;
+/**
+ * How a value came to sit in a cell. Rendered as the provenance tone.
+ *
+ * A type alias of `./provenance-model`'s `ProvenanceBasis`, not a lookalike:
+ * two vocabularies for the same concept — a grid cell's origin — shipped one
+ * day apart and would have drifted the moment either one added a value. The
+ * grid gains `asserted` for free (a cell an agent claimed with nothing behind
+ * it), where the caller previously had no way to say that.
+ */
+export type RecordGridSourceBasis = ProvenanceBasis;
+/**
+ * Where one cell's value came from. Optional on every row — a grid over data
+ * with no lineage renders identically without it.
+ */
+export interface RecordGridCellSource {
+    /** The text in the source that supports this value. */
+    quote?: string;
+    /** Human name of the source document, message, or system. */
+    label?: string;
+    /** Click-through to the source. */
+    href?: string;
+    /** Position inside the source: a page, a line, a span — the caller's words. */
+    locator?: string;
+    /** How the value got here. Absent renders as `asserted` — the weakest claim
+     *  in the union — because a caller that stated no basis has established
+     *  nothing about a document, and an omission must never read as one. */
+    basis?: RecordGridSourceBasis;
+}
+/** One option of a `select` column. */
+export interface RecordGridSelectOption {
+    value: string;
+    label: string;
+}
+/** A cell is only editable, rendered, and validated when the column it depends
+ *  on holds `equals`. This is how a nested sub-form (a vesting schedule behind
+ *  a "has vesting" toggle) stays a set of flat, individually-typed columns. */
+export interface RecordGridDependency {
+    column: string;
+    equals: RecordGridValue;
+}
+/** Fields every column kind carries. */
+export interface RecordGridColumnBase {
+    /** Key into a row's `values` bag. */
+    id: string;
+    /** Column heading, and the accessible name of every control in the column. */
+    header: string;
+    /** Short hint rendered under the control in the add form. */
+    hint?: string;
+    /** An empty cell is rejected. */
+    required?: boolean;
+    /** Cells are editable unless this is `false`. */
+    editable?: boolean;
+    /** Cell alignment. Numeric kinds default to `right`. */
+    align?: 'left' | 'right';
+    /** Groups this column under a labelled sub-form in the add form. */
+    group?: string;
+    /** Only applicable when another column holds a given value. */
+    dependsOn?: RecordGridDependency;
+    /** Extra rule, run after the kind's own checks pass. Return the message to
+     *  reject with, or `null` to accept. */
+    validate?: (value: RecordGridValue) => string | null;
+    /** Column summary rendered in the footer row. */
+    footerValue?: (rows: readonly RecordGridRow[]) => RecordGridValue;
+}
+/** Free text, optionally length- or pattern-constrained. */
+export interface RecordGridTextColumn extends RecordGridColumnBase {
+    kind: 'text';
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    /** Message when `pattern` rejects. Without it the pattern source is shown. */
+    patternMessage?: string;
+    /** Render a textarea instead of a single-line input. */
+    multiline?: boolean;
+}
+/** A plain number. */
+export interface RecordGridNumberColumn extends RecordGridColumnBase {
+    kind: 'number';
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    /** Passed through to the editor's `step`. */
+    step?: number;
+}
+/** A money amount. The currency is a caller parameter — this module bakes no
+ *  domain value, so a product with two currencies declares two columns. */
+export interface RecordGridCurrencyColumn extends RecordGridColumnBase {
+    kind: 'currency';
+    /** ISO 4217 code, e.g. `USD`. */
+    currency: string;
+    min?: number;
+    max?: number;
+    /** Fraction digits for display. Defaults to the currency's own. */
+    fractionDigits?: number;
+}
+/** A calendar date held as `YYYY-MM-DD`; no time, no zone. */
+export interface RecordGridDateColumn extends RecordGridColumnBase {
+    kind: 'date';
+    /** Earliest accepted date, `YYYY-MM-DD`. */
+    min?: string;
+    /** Latest accepted date, `YYYY-MM-DD`. */
+    max?: string;
+}
+/** One of a closed set of values. */
+export interface RecordGridSelectColumn extends RecordGridColumnBase {
+    kind: 'select';
+    options: readonly RecordGridSelectOption[];
+}
+/** A checkbox. */
+export interface RecordGridBooleanColumn extends RecordGridColumnBase {
+    kind: 'boolean';
+    /** Label for `true`. Defaults to `Yes`. */
+    trueLabel?: string;
+    /** Label for `false`. Defaults to `No`. */
+    falseLabel?: string;
+}
+/** Every column shape the grid renders. */
+export type RecordGridColumn = RecordGridTextColumn | RecordGridNumberColumn | RecordGridCurrencyColumn | RecordGridDateColumn | RecordGridSelectColumn | RecordGridBooleanColumn;
+/** One row: an id, a flat value bag keyed by column id, and optional per-cell
+ *  provenance. A record-backed product maps its fold output straight onto
+ *  this — one entry per cell, its quote and link in `sources`. */
+export interface RecordGridRow {
+    id: string;
+    values: Readonly<Record<string, RecordGridValue>>;
+    /** Per-cell provenance, keyed by column id. */
+    sources?: Readonly<Record<string, RecordGridCellSource>>;
+    /** No cell in this row may be edited or deleted. */
+    readOnly?: boolean;
+    /** Accessible name for the row's own controls. Falls back to the first text
+     *  or select column's value, then the row id. */
+    label?: string;
+}
+/** True when the column's dependency (if any) is satisfied by the row's other
+ *  values. An inapplicable cell is never required, never validated, and never
+ *  editable. */
+export declare function isRecordGridCellApplicable(column: RecordGridColumn, values: Readonly<Record<string, RecordGridValue>>): boolean;
+/** Value equality across the grid's value union, treating `undefined` as
+ *  `null` so an absent key and an explicit null never read as a change. */
+export declare function sameRecordGridValue(a: RecordGridValue | undefined, b: RecordGridValue | undefined): boolean;
+/**
+ * Turn what an editor control produced into a typed value. Syntax only —
+ * range, length, and membership are {@link validateRecordGridCell}'s job.
+ */
+export declare function parseRecordGridInput(column: RecordGridColumn, raw: string): RecordGridCellOutcome;
+/**
+ * Check one already-typed value against its column. Returns the value the grid
+ * should store (empty text normalizes to `null`) or the message a person can
+ * act on.
+ */
+export declare function validateRecordGridCell(column: RecordGridColumn, value: RecordGridValue): RecordGridCellOutcome;
+/** Parse editor text and validate it in one step — what a committing cell
+ *  editor calls. */
+export declare function readRecordGridCell(column: RecordGridColumn, raw: string): RecordGridCellOutcome;
+/**
+ * Validate a whole value bag against the columns. Inapplicable cells (an
+ * unsatisfied `dependsOn`) are forced to `null` rather than carried, so a
+ * sub-form the user turned off cannot smuggle stale values into a write.
+ */
+export declare function validateRecordGridRow(columns: readonly RecordGridColumn[], values: Readonly<Record<string, RecordGridValue>>): RecordGridRowOutcome;
+/** Display text for a cell. `null` renders as the empty string; the component
+ *  decides what a missing value looks like. */
+export declare function formatRecordGridValue(column: RecordGridColumn, value: RecordGridValue, locale?: string): string;
+/** The text an editor control starts with — the raw value, never the formatted
+ *  one, so committing an untouched cell is a no-op. */
+export declare function recordGridEditorText(column: RecordGridColumn, value: RecordGridValue): string;
+/** Accessible name for a row's own controls. */
+export declare function recordGridRowLabel(columns: readonly RecordGridColumn[], row: RecordGridRow): string;
+/** Sum a numeric column over the rows that hold a number. Rows with no value
+ *  are absent from the sum, not zero — a total over three of five filled cells
+ *  is the total of what is on file. */
+export declare function sumRecordGridColumn(rows: readonly RecordGridRow[], columnId: string): number;
+/**
+ * Edits the grid has applied locally but the caller's `rows` prop has not yet
+ * caught up with. Every field is what rollback removes: drop the entry and the
+ * caller's own data shows through again.
+ */
+export interface RecordGridOverlay {
+    /** rowId → columnId → optimistic value. */
+    updates: Readonly<Record<string, Readonly<Record<string, RecordGridValue>>>>;
+    /** Rows created locally, in insertion order. */
+    created: readonly RecordGridRow[];
+    /** Row ids removed locally. */
+    removed: readonly string[];
+}
+/** An overlay holding nothing. */
+export declare const EMPTY_RECORD_GRID_OVERLAY: RecordGridOverlay;
+/** The rows to render: caller rows minus local deletes, with local cell edits
+ *  applied, then locally-created rows. */
+export declare function projectRecordGridRows(rows: readonly RecordGridRow[], overlay: RecordGridOverlay): RecordGridRow[];
+/** Record one optimistic cell edit. */
+export declare function withRecordGridUpdate(overlay: RecordGridOverlay, rowId: string, columnId: string, value: RecordGridValue): RecordGridOverlay;
+/** Take back one optimistic cell edit — the rollback path. */
+export declare function withoutRecordGridUpdate(overlay: RecordGridOverlay, rowId: string, columnId: string): RecordGridOverlay;
+/** Adopt a row the writer returned as canonical: for a locally-created row it
+ *  replaces the draft; for an existing row it replaces the optimistic cells.
+ *  Either way the draft's pending cell edits go with it — the canonical row IS
+ *  the answer, and leaving an edit layered over it is how a grid keeps showing
+ *  a value the server normalized away. */
+export declare function withRecordGridServerRow(overlay: RecordGridOverlay, draftId: string, row: RecordGridRow): RecordGridOverlay;
+/** Record an optimistic create. */
+export declare function withRecordGridCreated(overlay: RecordGridOverlay, row: RecordGridRow): RecordGridOverlay;
+/** Take back an optimistic create — the rollback path. Cell edits made against
+ *  the draft go with it; the row they applied to no longer exists anywhere. */
+export declare function withoutRecordGridCreated(overlay: RecordGridOverlay, rowId: string): RecordGridOverlay;
+/** Record an optimistic delete. */
+export declare function withRecordGridRemoved(overlay: RecordGridOverlay, rowId: string): RecordGridOverlay;
+/** Take back an optimistic delete — the rollback path. */
+export declare function withoutRecordGridRemoved(overlay: RecordGridOverlay, rowId: string): RecordGridOverlay;
+/**
+ * Drop the overlay entries the caller's own rows have caught up with: a cell
+ * whose value now matches, a created row now present, a removed row now gone.
+ * Without this an overlay would mask every later refresh of the same cell.
+ *
+ * Returns the SAME overlay object when nothing settled, so a caller can prune
+ * on every render without looping.
+ */
+export declare function pruneRecordGridOverlay(rows: readonly RecordGridRow[], overlay: RecordGridOverlay): RecordGridOverlay;