@ai-matrx/records-ui 0.115.70 → 0.115.71

package/dist/helpers.d.cts

@@ -0,0 +1,1258 @@
+import { Uuid, RecordsActor, RecordsDataSource, PermissionLevel, RecordScopeContext, Field, RowAction, RecordDocument, AggregateFilter, Table, RecordRead, RowAgentTarget, ReadRow, HistoryActor, FieldHistoryEntry, HiddenFieldNotice, DeclarableFieldKind, NewerFieldKind, FieldKind, ParityFieldType, TableDecorations } from '@ai-matrx/records';
+import { ReactNode, KeyboardEvent } from 'react';
+import { ReversibleAnnouncement } from '@ai-matrx/kit/reversible';
+import { Uuid as Uuid$1 } from '@ai-matrx/records/react';
+export { DEFAULT_FIELDS, DeclareResult, NewFieldSpec, NewTableSpec, addFields, declareTable, fieldDeclarationFor, tokenFor } from '@ai-matrx/records/core';
+import { TableStyle } from '@ai-matrx/design-system/data-table';
+
+declare function personActor(userId: Uuid | null | undefined): RecordsActor;
+declare function recordsDataSource(client: object, fallbackSchema?: string): RecordsDataSource;
+
+/** The host app's saved zone (IANA). `null` / junk clears it: the device zone applies. */
+declare function setPersonTimeZone(next: string | null | undefined): void;
+declare function getPersonTimeZone(): string | null;
+/** Calls `listener` whenever the zone changes; returns the unsubscribe. */
+declare function subscribePersonTimeZone(listener: () => void): () => void;
+/**
+ * `at` as a Date whose LOCAL fields (getFullYear, getHours, ...) read the wall clock in the person's zone.
+ * For day / hour math only: never compare it with a stored instant.
+ */
+declare function personWallNow(at?: Date): Date;
+
+/** The six things a person does to a record or a table, as the screens offer them. */
+type Capability = "read" | "comment" | "write" | "organise" | "remove" | "share" | "structure";
+interface WhatYouMayDo {
+    /** The word the store answered, or null when it answered nothing. */
+    level: PermissionLevel | null;
+    /**
+     * Whether the store has ANSWERED yet. `false` is a third state and not a
+     * refusal: a screen that drew "you may not" while the answer was in flight
+     * would blink every control off on every reload, which is its own lie.
+     */
+    known: boolean;
+    read: boolean;
+    comment: boolean;
+    write: boolean;
+    /** Duplicate, merge, restore, make a layout the default: the doors that ask `editor`, above content. */
+    organise: boolean;
+    remove: boolean;
+    share: boolean;
+    structure: boolean;
+    /** Why this person may not do that, in one sentence naming the way in. */
+    why: (what: Capability) => string;
+}
+
+/**
+ * What a person may do to one table. The four words and the ladder are the
+ * store's (`rights.ts`), not ours.
+ *
+ * `admin`, `comment` and `write` are kept with the names they have always had,
+ * because every screen in this package and in the host apps reads them; they
+ * are now the store's ANSWER rather than a host's guess.
+ */
+interface TableRights extends WhatYouMayDo {
+    /** SCR-2: holders of `admin` on the table see the "+" and the settings panel. */
+    admin: boolean;
+    /**
+     * Why this answer, in one sentence. Kept for callers that show a single
+     * reason; `why(what)` is the per-control sentence and is what the screens use.
+     */
+    reason: string;
+}
+/**
+ * Kept so a host that imported it still compiles. It is no longer any screen's
+ * default: the store answers this question now, and a package that said "I
+ * assume nothing" while holding the answer would be hiding controls from the
+ * people who hold them.
+ */
+declare const NO_RIGHTS: TableRights;
+/**
+ * THE ONE WAY TO BUILD A `TableRights` BY HAND — for a host with its own
+ * authority, and for a suite that wants to mount one seat's screen. It takes
+ * the LEVEL, never six booleans, so nobody can hand a screen a combination the
+ * ladder cannot produce (write without read, share without edit).
+ */
+declare function tableRightsAt(level: PermissionLevel | null): TableRights;
+
+/** What the settings panel can see right now, in the words the agent reads. */
+interface TableSettingsSnapshot {
+    table_id: Uuid;
+    /** True when the description or an open row action holds edits not saved yet. */
+    has_unsaved_changes: boolean;
+    table_details_draft: {
+        table_name: string;
+        description: string;
+        row_label: string | null;
+    };
+    saved_row_actions?: Array<Record<string, unknown>>;
+    editing_row_action?: Record<string, unknown>;
+    editing_row_action_problems?: string[];
+}
+/** What the host's surface reads and calls. Every call reads the panel as it is at that moment. */
+interface TableSettingsAgent {
+    read: () => TableSettingsSnapshot;
+    /** Replace the open row action (or open a new one) with a whole action. */
+    stageRowAction: (input: unknown) => Promise<void>;
+    /** Write one Calculate step's formula in the open update action. */
+    stageStepFormula: (input: unknown) => Promise<void>;
+    /** Stage the description in "About this table". */
+    stageTableDetails: (input: unknown) => Promise<void>;
+}
+
+/** What a door answers when it mints or changes a link. The token is the only time it is seen. */
+interface CalendarFeedMade {
+    id: string;
+    token: string;
+    expires_at: string | null;
+}
+/** One line of the person's list. Never a token — `token_prefix` is its first characters. */
+interface CalendarFeedRow {
+    id: string;
+    title: string;
+    organization_id: string;
+    table_id: string;
+    view_id: string | null;
+    token_prefix: string;
+    time_zone: string;
+    created_at: string;
+    expires_at: string | null;
+    last_read_at: string | null;
+    read_count: number;
+    expired: boolean;
+}
+interface CalendarFeedPort {
+    create(args: {
+        organizationId: string;
+        tableId: string;
+        viewId: string;
+        title: string;
+        timeZone: string;
+    }): Promise<CalendarFeedMade>;
+    rotate(id: string): Promise<CalendarFeedMade>;
+    revoke(id: string): Promise<void>;
+    list(): Promise<CalendarFeedRow[]>;
+    /** The https address a calendar app reads for this token (the host's route). */
+    urlFor(token: string): string;
+}
+
+/** One named piece of grounding, shaped the way the platform's context slice takes them. */
+interface RecordChatEntry {
+    key: string;
+    value: unknown;
+    label: string;
+    /** `text` for a scalar, `json` for a structure. The host maps this to its own vocabulary. */
+    type: "text" | "json";
+    /**
+     * DYN: a merge field resolves to a TRIPLE, not a string. The prompt gets the
+     * rendered value; the RUN gets this, and it is the only thing a "where did
+     * that come from" question can be answered from — so a host can turn a cited
+     * answer into a link to the record AND to the version it was read at.
+     */
+    cite?: {
+        record_id: Uuid$1;
+        field_id: Uuid$1;
+        value_version: number;
+        written_at: string | null;
+    };
+}
+/** A Field the agent was NOT given, named rather than silently dropped. */
+interface RecordChatWithheld {
+    key: string;
+    label: string;
+    /** The store's own reason. */
+    reason: string;
+    /**
+     * WHICH ABSENCE THIS IS. `masked` — the store kept it from THIS READER.
+     * `policy` — the organization keeps it out of conversations, and the same
+     * person can read it on the record two inches away. A screen that collapsed
+     * the two would tell somebody the wrong thing about their own access.
+     */
+    because?: "masked" | "policy";
+    /** The whole sentence, already written. A screen prints it; it composes nothing. */
+    says?: string;
+}
+/** Everything the host's chat surface needs, and nothing about how it should look. */
+interface RecordChatContext {
+    /**
+     * A unique key per mounted conversation. Two record panels open at once must
+     * not fight over focus, so this is derived from the record and never a
+     * constant.
+     */
+    surfaceKey: string;
+    tableId: Uuid$1;
+    recordId: Uuid$1;
+    tableName: string;
+    /** The record's own title, for the panel's one-row header and the chip. */
+    title: string;
+    /** What the scope chip says: `About: Fairhaven Steelworks`. */
+    chip: string;
+    /** The grounding, already read through the read door. */
+    entries: RecordChatEntry[];
+    /** What this reader is NOT being given, with the store's reason for each. */
+    withheld: RecordChatWithheld[];
+    /** Questions derived from THIS record's shape. Never a fixed list. */
+    suggested: string[];
+    /** One sentence naming what is not in the conversation. Printed verbatim. */
+    says: string;
+    /** The whole door answer, for a host that wants the history or the relations. */
+    scope: RecordScopeContext;
+}
+
+/** What the host is asked to have the SERVER's `records` tool do. */
+interface EnrichAsk {
+    tableId: Uuid$1;
+    fieldId: Uuid$1;
+    fieldKey: string;
+    /** How many records this run covers. */
+    rows: number;
+    /** True: ask the model and report what it WOULD write, writing nothing. */
+    previewOnly: boolean;
+}
+interface EnrichOutcome {
+    ok: boolean;
+    /** What happened, in a sentence — the server's own words when it has some. */
+    message: string;
+    /** For a preview: what would go in each cell. */
+    wouldWrite?: Array<{
+        record_id: string;
+        value?: unknown;
+        absent?: string;
+        says?: string;
+    }>;
+    /** What the run cost, in cents; shown only as points at the host's rate. */
+    costCents?: number;
+    /** How many values it wrote (0 for a preview). */
+    rowsWritten?: number;
+}
+
+/** One record as the grid shows it: its id, its name (the row label) and its masked document. */
+interface GridContextRecord {
+    id: Uuid;
+    title: string;
+    document: RecordDocument;
+}
+interface GridContextSnapshot {
+    tableId: Uuid;
+    tableName: string;
+    /** The table's own description (`metadata.description`), when it has one. */
+    tableDescription: string | null;
+    /** The Field key that names each record (`title_field`), or null. */
+    titleField: string | null;
+    /** The columns in the order the grid draws them (hidden columns left out). */
+    fields: Field[];
+    /** The table's row actions as the store lists them (update and agent). */
+    rowActions: RowAction[];
+    /** May this person change records here at all. */
+    canWrite: boolean;
+    /** The cell the cursor is on: its record, its Field key and the value drawn in it. */
+    currentCell: {
+        rowId: Uuid;
+        key: string;
+        value: unknown;
+    } | null;
+    /** The record the cursor is on (or whose editor is open). */
+    currentRow: GridContextRecord | null;
+    /** A block of more than one cell: Excel/Sheets TSV with a header line of Field keys. */
+    selectedRange: {
+        tsv: string;
+        cellCount: number;
+        rowIds: Uuid[];
+        keys: string[];
+    } | null;
+    /** The rows ticked with the row boxes. */
+    selectedRows: GridContextRecord[];
+    /** The page of records on screen, in screen order. */
+    visibleRows: GridContextRecord[];
+    /** How many records match the search and filters, when the store said. */
+    total: number | null;
+    search: string;
+}
+
+/**
+ * The authored-text slots `renderText` is asked to draw. `cell`: a long-text cell of the merged
+ * grid and the whole-text dialog's preview — the host may return block content there (the grid
+ * clips it to the row); the form slots take phrasing content only.
+ */
+type RenderTextSlot = "form-intro" | "form-help" | "form-thank-you" | "cell";
+
+/** One reference a chip names (`renderReference`). `record` is a relation's value, read side only. */
+/** What a record page hands the host's rich editor (`editRichText`). */
+interface RichTextEditProps {
+    /** The stored Markdown. A later value is the store's echo or a colleague's change. */
+    value: string;
+    /** Every change the person makes, as the whole Markdown text. Saving is the package's. */
+    onChange: (text: string) => void;
+    readOnly: boolean;
+    placeholder: string;
+}
+/**
+ * What a multi-line text box hands the host's own text box (`textBox`): the words and a setter, and
+ * what the box is for. The host draws its platform text box around them, with that box's "…" menu.
+ */
+interface TextBoxProps {
+    value: string;
+    /** Every change, as the whole text. Saving stays the package's. */
+    onChange: (next: string) => void;
+    /** The column's name: the box's accessible name and what its menu calls the text. */
+    label: string;
+    rows: number;
+    /** Where the box sits: an open grid cell, the whole-text editor, or a record form. */
+    where: "cell" | "whole-text" | "form";
+    id?: string | undefined;
+    autoFocus?: boolean | undefined;
+    readOnly?: boolean | undefined;
+    disabled?: boolean | undefined;
+    onKeyDown?: ((event: KeyboardEvent<HTMLTextAreaElement>) => void) | undefined;
+}
+interface ReferenceChipRef {
+    token: string;
+    id: Uuid;
+    label: string | null;
+    /** For `token: "record"`, the Table the relation points into. */
+    tableId?: Uuid | undefined;
+    /**
+     * The record it names sits in Archived items. An archive keeps every reference to what it
+     * archived (chair ruling B3-21), so the chip still names it and draws the archived state.
+     */
+    archived?: boolean | undefined;
+    /** The record's (or its table's) icon — an emoji or short glyph — when the host knows one. */
+    icon?: string | null | undefined;
+}
+/** One line typed into the table's Ask box, with the view the person was looking at ("" = none). */
+interface TableAskRequest {
+    tableId: Uuid;
+    question: string;
+    viewId: string;
+}
+/** What the platform's `table.ask` agent answers: an answer, or edits it proposes for the person to apply. */
+interface TableAskAgentAnswer {
+    mode: "answer" | "proposed_edits";
+    /** Markdown. */
+    answer: string;
+    cited_record_ids: string[];
+    proposed_changes: Array<{
+        record_id: string;
+        field_key: string;
+        from: unknown;
+        to: unknown;
+        reason: string;
+    }>;
+    could_not: string[];
+}
+type TableAskOutcome = {
+    ok: true;
+    answer: TableAskAgentAnswer;
+    /** What the run cost, in whole points at the viewer's rate. Absent or null = not measured; nothing is drawn (never dollars). */
+    costPoints?: number | null | undefined;
+}
+/** A refusal says the real reason (`message`) and, when the host knows one, what to do (`hint`); no hint, none is invented. */
+ | {
+    ok: false;
+    message: string;
+    hint?: string | undefined;
+};
+/** What `RecordsUiHost.writeSyncedCell` answers. */
+type SyncedCellOutcome = {
+    ok: true;
+    status: "written";
+    version?: number | null;
+} | {
+    ok: true;
+    status: "conflict";
+    sheetValue: string | null;
+} | {
+    ok: false;
+    message: string;
+};
+interface RecordsUiHost {
+    /**
+     * OPTIONAL. THE TABLE'S ASK BOX, ANSWERED BY AN AGENT. Bound, the box sends the typed line here and
+     * draws the answer, the records it cites and any edits it proposes (each applied by the person,
+     * against the record's version). Unbound, the box answers with the Question runner as before.
+     */
+    askTable?: ((ask: TableAskRequest) => Promise<TableAskOutcome>) | undefined;
+    /**
+     * OPTIONAL. WRITE-THROUGH FOR A SYNCED CELL (lane SYNC-AIRTABLE, CFL-058). A column the store keeps
+     * from a source (`field.source === "synced"`) is written only by that source: bound, an edit of such
+     * a cell is sent here (the host's server writes the connected Google Sheet first, then lands it) and
+     * answers `written` (with the record's new version) or `conflict` (the sheet changed since the last
+     * sync — the cell keeps both and the person picks; Retry sends `force`). A refusal is `{ ok: false }`
+     * in the host's own words. Unbound, the store refuses the edit as before.
+     */
+    writeSyncedCell?: ((cell: {
+        tableId: Uuid;
+        recordId: Uuid;
+        fieldKey: string;
+        value: unknown;
+        force: boolean;
+    }) => Promise<SyncedCellOutcome>) | undefined;
+    /**
+     * Draws an icon kept as a NAME ("Briefcase" — how the store keeps an icon a person picked from the
+     * icon list). A relation cell in an embedded table wears its record's icon; an emoji is drawn as
+     * text and a name only through this port. Unbound (or `null` back), the page glyph stands in.
+     */
+    renderIcon?: ((name: string) => ReactNode) | undefined;
+    /**
+     * TEMPORARY (one-grid merge, steps 5-8). Which table grid draws: `classic` — the default Grid
+     * as it shipped in 0.86; `merged` — the same grid with the older /data grid's control layer on
+     * it (the column header menu, the right-click Cell / Row / Column / Table sections, column
+     * settings, column order and hidden columns kept on the view). Left out: `classic`. Removed at
+     * merge step 9, when `merged` is the only grid.
+     */
+    grid?: "classic" | "merged";
+    /**
+     * OPTIONAL. CLEAN A PASTED PIECE OF HTML INTO PLAIN TEXT (merge tranche 6m, inventory A7).
+     *
+     * A cell pasted from a web page or an email carries its tags, entities and inline styles. The
+     * platform has ONE cleaner (the host's content-cleanup), so this is a port rather than a second
+     * one here. The merged grid offers "Clean HTML" in a text cell's right-click Cell section and in
+     * the whole-text editor; the cleaned text is written through the grid's own one-cell write (one
+     * undo step). Unbound, the item is ABSENT, never dead.
+     */
+    cleanText?: (text: string) => string;
+    /**
+     * OPTIONAL. THE PRIVATE CALENDAR LINK (CAL-FEED-UI): the host's create / rotate / revoke / list doors
+     * and the address its feed route answers at. Bound, a view with a date field offers "Subscribe in
+     * your calendar…" in the table's menu. Unbound, the entry is ABSENT, never dead.
+     */
+    calendarFeed?: CalendarFeedPort;
+    /**
+     * OPTIONAL. WHERE THE PERSON IS IN THE GRID, told as it changes (merge tranche 6l, inventory H1).
+     *
+     * An agent in the host's side chat is asked about "this cell", "these rows", "the table". Only
+     * the grid knows the table, its columns, the cell the cursor is on, the selected block, the
+     * ticked rows, the rows on screen and the search. The merged grid calls this after any of them
+     * changes (identical snapshots are not repeated); the host builds its agent scope from it. The
+     * snapshot carries the store's own `Field` records and the masked documents exactly as drawn.
+     * Unbound, nothing is built.
+     */
+    onGridContext?: (snapshot: GridContextSnapshot) => void;
+    /**
+     * OPTIONAL. THE PLATFORM'S ONE ICON PICKER (merge tranche 6j, inventory G2). A row action's
+     * button may carry an icon from the canonical icon set; that set and its picker are the host's
+     * (this package carries no icon library). Unbound, the row-action editor draws no icon control
+     * and keeps whatever icon an action already carries.
+     */
+    iconPicker?: (props: {
+        value: string;
+        label: string;
+        onChange: (name: string) => void;
+    }) => ReactNode;
+    /**
+     * OPTIONAL. HELP WRITING A FORMULA (Sheet retirement). The formula box hands the host what it
+     * holds — the text, the table's other columns and the store's reading of what is wrong — and the
+     * host draws its own help control beside the box (matrx-frontend runs its formula-writing job).
+     * Whatever formula the help arrives at goes back through `onFormula` into the box, unsaved, for
+     * the person to keep or change. Unbound, nothing is drawn.
+     */
+    formulaHelp?: (ask: FormulaHelpAsk) => ReactNode;
+    /**
+     * OPTIONAL. THE PLATFORM'S TEXT BOX FOR LONG TEXT (Sheet retirement). The Sheet edited a text cell
+     * in the platform's one text box, whose "…" menu offers Clean up, Help with this…, Copy, Save to
+     * notes and Share. Bound, the long-text cell editor, the whole-text editor and a record form's
+     * long-text field draw the host's box with these props (one "…", no other chrome). Unbound, the
+     * package's plain box.
+     */
+    textBox?: (props: TextBoxProps) => ReactNode;
+    /**
+     * OPTIONAL. AN AGENT OVER A TABLE'S SETTINGS (Sheet retirement). While the settings panel is open
+     * it wraps itself in what this returns, handing the host a `TableSettingsAgent`: what the panel
+     * can see (the description as edited, the row actions and the one being edited, what stops it
+     * saving) and three staging calls (a whole row action, one step's formula, the description).
+     * Staging never saves; the person presses Save. Unbound, the panel draws bare.
+     */
+    settingsAgent?: (args: {
+        tableId: Uuid;
+        agent: TableSettingsAgent;
+        children: ReactNode;
+    }) => ReactNode;
+    /** Answer the rights question for one table. Synchronous: a screen renders now. */
+    rights?: (table: Table) => TableRights;
+    /** Where a record's own page lives, when the host has one. A peek is used when it does not. */
+    hrefForRecord?: (args: {
+        table: Table;
+        recordId: Uuid;
+    }) => string | undefined;
+    /**
+     * OPTIONAL. WHERE A FILE OPENS. A value too big for one cell is kept as a file and the cell
+     * holds its first words (`@ai-matrx/records/core` `wholeValueOf`); this is the host's page for
+     * that file. Unbound, the cell shows the words and says the whole text is kept as a file this
+     * screen cannot open — never a dead link.
+     */
+    hrefForFile?: (args: {
+        fileId: Uuid;
+    }) => string | undefined;
+    /**
+     * OPTIONAL. READ A FILE'S WHOLE TEXT, so an export writes a big value's whole content rather
+     * than its first words. Unbound, the exported cell carries the words and one sentence naming
+     * the file (`wholeValueNotRead`) — never the words passed off as the value.
+     */
+    readFileText?: (args: {
+        fileId: Uuid;
+    }) => Promise<string>;
+    /**
+     * OPTIONAL. A FILE DRAWN AS A PICTURE — the gallery card's cover when the view's picture column
+     * is a File column (lane DATA-V2-VIEWS-1). The host owns how a file becomes pixels (its media
+     * lane, its auth), so this is a port: it returns the element that fills the cover box. Unbound,
+     * the cover says in words that this screen cannot draw files, never a broken image.
+     */
+    fileImage?: (args: {
+        fileId: Uuid;
+        alt: string;
+    }) => ReactNode;
+    /**
+     * OPTIONAL. HOW AUTHORED TEXT READS. A form's intro, a question's help and the thank-you body
+     * are written by a person and may carry markdown and math (`**bold**`, `\\(x^2\\)`, links).
+     * This package does not parse markdown — the host owns its renderer — so this is a port: the
+     * host returns phrasing content (valid inside a `<p>`). `where` names the slot. Unbound, the
+     * text shows exactly as written.
+     */
+    renderText?: (text: string, where: RenderTextSlot) => ReactNode;
+    /**
+     * OPTIONAL. ONE REFERENCE, DRAWN AS A CHIP THAT OPENS WHAT IT NAMES (lane REFERENCE-CARRY).
+     *
+     * Every reference this package shows — a relation to a record (`token: "record"`, with the
+     * Table it points into), an entity reference to a platform thing (`note`, `agent`, `workflow`…)
+     * — is drawn through this port, so a person can always reach the thing (the host owns routes,
+     * peeks and new tabs). `label` is the store's words, or null when they were withheld from this
+     * reader. Unbound, the chip names the thing and opens nothing.
+     */
+    renderReference?: (ref: ReferenceChipRef) => ReactNode;
+    /**
+     * OPTIONAL. A VALUE THAT NAMES ITS OWN SHAPE, DRAWN THROUGH THE HOST'S KIND SYSTEM (lane
+     * REFERENCE-CARRY). A cell holding `__kind` JSON — or a Matrx directive stored before the Kind
+     * Directives merge (```matrx {"matrx_version":1,…}```) — is handed over whole (`kindValues.ts`);
+     * the host decodes it with its one decoder and returns a compact rendering for `where` (a cell,
+     * a panel row) that opens the real view. Unbound, the cell names the kind and shows the raw text
+     * on hover — never the fence at eye level.
+     */
+    renderKind?: (args: {
+        value: Record<string, unknown>;
+        kind: string;
+        where: "cell" | "panel";
+        title: string;
+    }) => ReactNode;
+    /** The host's own link element, so routing stays the host's business. */
+    Link?: (props: {
+        href: string;
+        children: ReactNode;
+        className?: string;
+    }) => ReactNode;
+    /** Toasts. Absent means the screen shows the sentence inline instead — never silence. */
+    notify?: {
+        /** `action`: one button on the toast (an Undo). A host without actions draws the sentence alone. */
+        success: (message: string, action?: {
+            label: string;
+            run: () => void;
+        }) => void;
+        error: (message: string) => void;
+        /**
+         * OPTIONAL. THE REVERSIBLE ACTION (`@ai-matrx/kit/reversible`): something this package did
+         * that can be undone — a table archived — handed to the host's one announcer, which acts it
+         * out at the person's level (taught the first time, a long Undo toast the next few, an ordinary
+         * one after) and answers ⌘Z. The package says WHAT happened and HOW to undo it; where the
+         * thing went (`foundAt`) is the host's routes. Unbound, the package falls back to `success`
+         * with an Undo button.
+         */
+        reversible?: (announcement: ReversibleAnnouncement) => void;
+    };
+    /** Density for every table this package renders. */
+    density?: "condensed" | "normal" | "spacious";
+    /**
+     * OPTIONAL. WHETHER A WITHHELD CONTROL SAYS WHAT LEVEL IT TAKES ("You are Viewer here, and it takes
+     * Editor to … Ask somebody who is Admin on it to move you up."). Default `true`. A host whose
+     * person has no level to be moved up to — a template preview, a public look at a table — sets
+     * `false`: the control stays absent exactly as before, without the sentence. It changes words
+     * only, never what is offered.
+     */
+    sayLevelNeeded?: boolean;
+    /**
+     * OPTIONAL. Where a file a person attached actually goes. A File is a record
+     * in the kernel File Table (REC-31), but the BYTES are the host's file
+     * service, not this package's business — so this is a port.
+     *
+     * Unbound, an attachment question does NOT draw a file chooser that quietly
+     * loses the file: it says, in one sentence, that no file store is bound and
+     * names this port. Absent or honest, never dead.
+     */
+    upload?: (file: File) => Promise<{
+        ok: true;
+        fileId: Uuid;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * OPTIONAL. THE HOST'S OWN FILE WINDOW (one-grid merge, inventory: the older grid's
+     * AttachmentInput). An attachment cell adds files the person already holds through the host's
+     * file picker — Airtable's "Attach" over your own files — rather than a second browser this
+     * package would invent. `multiple`: the column holds several files; `accept`: the native
+     * `accept` list, when the column restricts types. Resolves the host's file ids (the store turns
+     * each into its kernel File record at the write door), or `null` when the person cancelled.
+     *
+     * Unbound, the editor offers `upload` alone; with neither bound it says no file store is bound
+     * (`NO_UPLOAD_REASON`) — never a dead button.
+     */
+    pickFiles?: (ask: {
+        multiple: boolean;
+        accept?: string;
+    }) => Promise<Uuid[] | null>;
+    /**
+     * Where this app serves its PUBLIC pages from, when that is not the origin
+     * the screen is running on. A form's link is built here, so an owner copying
+     * it from an admin host, a preview deployment or a desktop shell gets the
+     * address a stranger can actually open — never `http://localhost:3000/f/…`
+     * pasted into an email. Unbound, the browser's own origin is used.
+     */
+    publicOrigin?: string;
+    /**
+     * OPTIONAL. The organization's saved views as `platform.saved_view` holds
+     * them — which is what a subscription points at (DOOR-18). The record store
+     * has NO door onto that table, because it is the platform's and not the
+     * store's, so this is a port rather than a read this package invents.
+     *
+     * Unbound, `NotifyRuleEditor` shows the subscriptions that exist and says, in
+     * one sentence, that it cannot offer a view to subscribe to. It never renders
+     * an empty picker that looks like "you have no views".
+     */
+    savedViews?: () => Promise<Array<{
+        id: Uuid;
+        name: string;
+    }>>;
+    /**
+     * OPTIONAL. WHO IS IN THIS ORGANIZATION (FLD-11 `member`).
+     *
+     * A person field must offer PEOPLE. Who the people are is the platform's
+     * answer — organization membership lives in `iam`, not in the record store —
+     * and the store has no door onto it, so this is a port rather than a read
+     * this package invents. `PersonPicker` resolves whoever is picked to their
+     * record in the kernel Person Table, which is what the Field actually stores.
+     *
+     * Unbound, a person question is ABSENT with `NO_MEMBERS_REASON`. It never
+     * falls back to listing the kernel Person Table's contents: that Table also
+     * holds the Homes this package writes, and offering "Comments Home" as a
+     * person is exactly what this port exists to stop.
+     */
+    members?: () => Promise<OrganizationMember[]>;
+    /**
+     * OPTIONAL. THE HOST'S OWN CHAT SURFACE (SCR-26).
+     *
+     * This package ships no chat UI, on purpose: AI Matrx has exactly one, it
+     * lives in matrx-frontend (`AgentConversationColumn`), and it reads that app's
+     * Redux store — so a second one here would drift within a month and a package
+     * that imported the first would stop being a package. `RecordChat` therefore
+     * builds the CONTEXT (the record, through the read door, with the masked
+     * fields named) and hands it to this port.
+     *
+     * Unbound, the panel is ABSENT with that reason, never a composer that goes
+     * nowhere.
+     */
+    chat?: (context: RecordChatContext) => ReactNode;
+    /**
+     * OPTIONAL. MORE SECTIONS ON AN OPEN RECORD — drawn in the record rail after its history,
+     * one host-owned block about THIS record (e.g. "What ran on this record": the Workflow runs
+     * stamped with it). Unbound, nothing is drawn.
+     */
+    recordSections?: (target: {
+        tableId: Uuid;
+        recordId: Uuid;
+    }) => ReactNode;
+    /**
+     * OPTIONAL. THE PLATFORM'S ONE RICH EDITOR, for a record page's body (lane TABLE-EXPERIENCE,
+     * v7 item 1: a record is a page). The host draws its own editor — matrx-frontend's notes editor —
+     * reporting every change through `onChange`; this package owns the saving. Unbound, the body is
+     * drawn read-only and is edited through the record's form.
+     */
+    editRichText?: (props: RichTextEditProps) => ReactNode;
+    /**
+     * OPTIONAL. THE HOST DRAWS A RECORD PAGE'S WHOLE BODY (the "Spaces" page layer's block editor).
+     * When bound and it returns non-null, the record page draws that in place of the package's own
+     * body (the formatted-text column editor and its "Write on this page" offer); the host owns
+     * saving. Returning `null` (or leaving it unbound) draws today's body unchanged.
+     */
+    renderRecordBody?: (args: {
+        tableId: string;
+        recordId: string;
+        record: RecordRead;
+        readOnly: boolean;
+        /** Today's body as an element — return it (or null) where the host has no body of its own. */
+        fallback: ReactNode;
+    }) => ReactNode | null;
+    /**
+     * OPTIONAL. "LINK A RECORD…" — the HOST opens its one record picker pointed at this record and
+     * writes the link through its own reference door; this package draws only the menu entry (a
+     * card's ⋯ and right-click, the grid row's right-click). Unbound, the entry says it is not
+     * available here.
+     */
+    linkRecord?: (target: {
+        tableId: Uuid;
+        recordId: Uuid;
+        name: string;
+    }) => void;
+    /**
+     * OPTIONAL. "TALK TO THIS RECORD" — the HOST opens its own one chat surface
+     * (AGT-N-9, PRODUCTS row 11).
+     *
+     * `chat` is the port that RENDERS a chat inside a panel this package draws.
+     * This one is the other direction: a menu entry in the grid, the cell menu or
+     * the record header says "the person wants to talk about this record", and the
+     * host opens the chat where the host puts chats — full height, the platform's
+     * own pattern — and binds the conversation to the record through
+     * `conversationScopeBind`. Drawing a chat next to a grid row from inside this
+     * package would be the parallel layer the canvas ruling forbids.
+     *
+     * ABSENT, NEVER DEAD: where neither this nor `chat` is bound, the entries do
+     * not render at all.
+     */
+    talkToRecord?: (target: {
+        tableId: Uuid;
+        recordId: Uuid;
+        title: string;
+    }) => void;
+    /**
+     * OPTIONAL. A TABLE'S AGENT BUTTON, PRESSED (TABLE-PARITY M3, lane DEFAULT-GRID-PARITY).
+     *
+     * A row action of kind `agent` ("Ask Dr. Whitfield") hands the row to an agent with the
+     * action's own `prompt`. Only the host can start that conversation — this package ships no
+     * chat — so the grid hands the row, the action's name and its prompt here, and the host
+     * opens its one chat surface bound to the record with that prompt as the opening ask. It is
+     * a separate port from `talkToRecord` because that one carries no prompt: a host that bound
+     * only `talkToRecord` would open an empty chat and silently drop what the button was for.
+     *
+     * ABSENT, NEVER DEAD: unbound, agent buttons are not drawn.
+     *
+     * NO SECOND READ (lane GRID-TAILS, 2026-09-24). The grid already holds the table, its
+     * columns, the row as this reader may see it and this reader's level on the row, so it hands
+     * them over: a host needs no `tableList`, `fields`, `recordRead` or `myLevels` to start the
+     * job, and the agent is handed exactly what the person was looking at.
+     */
+    runAgentAction?: (target: RowAgentTarget) => void;
+    /**
+     * OPTIONAL. THE AI COLUMN'S RUNNER (SCR-27, custom-data PLAN §4 M2).
+     *
+     * An AI fill must be written with actor `agent` on behalf of the person, and
+     * only the server can honestly say that — a browser stamping itself `agent`
+     * is a browser claiming to be one. So `EnrichPanel` asks here, and the host
+     * calls the server's one enrichment runner (`POST /v1/tables/{table}/ai-columns/{field}/run`,
+     * model = the `table.column_fill` mandate), which lands each value through
+     * `custom.enrich_land` as `agent` on the person's behalf.
+     *
+     * Unbound, no Fill control is drawn at all and the reason names this port.
+     */
+    enrich?: (ask: EnrichAsk) => Promise<EnrichOutcome>;
+    /**
+     * OPTIONAL. POINTS PER DOLLAR — the platform's rate. Every cost these screens show is
+     * points at this rate (`costInPoints`); unbound, no cost is shown, never the vendor's money.
+     */
+    pointsRate?: number | null;
+    /**
+     * OPTIONAL. WHERE AN OFFLINE CAPTURE WAITS (SCR-30).
+     *
+     * `CaptureSheet` mints the id for a capture BEFORE it tries to send it, so a
+     * phone with no signal has already decided what the write will be called.
+     * Where that queue physically lives is the host's business — IndexedDB in a
+     * browser, a file in a desktop app — so it is a port. Unbound, the sheet
+     * keeps its queue in memory for the life of the page AND SAYS SO, because a
+     * queue that silently died with the tab is the failure this exists to avoid.
+     */
+    captureQueue?: CaptureQueuePort;
+    /**
+     * OPTIONAL. THE HOST'S OWN SHARE DIALOG (SCR-N-5).
+     *
+     * This package ships no share dialog, ON PURPOSE, and for the same reason it
+     * ships no chat: AI Matrx has exactly ONE sharing surface — matrx-frontend's
+     * `features/sharing` ShareModal, with its people picker, its level picker, its
+     * grant list and its "who can see this, and why" panel — and a second one here
+     * would be a parallel sharing UI within a month. Sharing is the access model's
+     * front door, and two front doors is how a platform ends up with two answers
+     * to "who can see this".
+     *
+     * So `ShareControl` draws the BUTTON (which belongs on the record and table
+     * screens, beside everything else a person does to a thing) and hands the
+     * subject to this port, which returns the host's own dialog.
+     *
+     * Unbound, the button is ABSENT and `NO_SHARE_REASON` says which port to bind.
+     * Never a Share button that opens nothing.
+     */
+    share?: (subject: ShareSubject) => ReactNode;
+    /**
+     * OPTIONAL. WHO CAN SEE AND EDIT ONE COLUMN (access-setup PLAN §12, Store Tables). The column header's
+     * "Who can see and edit…" item hands the column to this port, which returns the host's People involved
+     * panel (it says who loses sight before anything is saved; table admins change it, never an agent).
+     * Unbound, the item is ABSENT. The grid owns open/closed; the host owns the panel.
+     */
+    columnAccess?: (subject: ColumnAccessSubject) => ReactNode;
+    /**
+     * OPTIONAL. THE ARCHIVED-ORGANIZATION DOOR (lane ARCHIVED-ORG-RESTORE). When the store refuses because the
+     * organization is archived, `RefusalNotice` says so and asks this port two things: `state` - may THIS person
+     * restore it (an owner or a super admin) - and `restore`, which calls the platform's one restore door. Left
+     * unbound, the notice still says the organization is archived and who can restore it, and offers no button.
+     */
+    archivedOrganization?: {
+        state: (organizationId: Uuid) => Promise<{
+            mayRestore: boolean;
+            name?: string | null;
+        } | null>;
+        restore: (organizationId: Uuid) => Promise<void>;
+        /** Runs after a restore so the screen reloads; unbound, the page reloads. */
+        afterRestore?: () => void;
+    };
+    /**
+     * APPLETS ON A PAGE (v7 APPS-ON-DATA item 3). The host's applet system: which applets this person
+     * may place (`list`), and the applet itself drawn in place (`render`). Unbound, a page offers no
+     * Applet block and an applet block already on the page says it opens inside the app.
+     */
+    applets?: {
+        list: () => Promise<ReadonlyArray<{
+            id: string;
+            name: string;
+        }>>;
+        render: (appId: string) => ReactNode;
+    };
+    /**
+     * OPTIONAL. OPEN THE RECORDS BEHIND A NUMBER (SCR-16).
+     *
+     * Every number on a dashboard is a count of real records, and the whole
+     * product row is that a person can get from the number to them: click the
+     * "Awaiting parts" column and the grid opens on the twenty-eight jobs it
+     * counted, with the block's own filter still on. That is one navigation, and
+     * WHERE the grid lives is the host's routing — so it is a port, like
+     * `hrefForRecord`, rather than a route string this package invents.
+     *
+     * Unbound, the marks are NOT clickable and the canvas says so in one
+     * sentence naming this port. A chart whose bars looked pressable and did
+     * nothing is the dead control this package does not ship.
+     */
+    openRecords?: (ask: OpenRecordsAsk) => void;
+    /**
+     * OPTIONAL. WHERE A PAGE OPENS (v6 lane 11, wave D). A Page is a dashboard record whose
+     * `presentation.kind` is `"page"` (`pages.ts`); the host owns its route, so this hands back the
+     * address of an existing page, or of the screen that makes a new one on a Table. Unbound, the
+     * Dashboards area lists no pages and offers no "New page" — absent, never dead.
+     */
+    pageHref?: (target: {
+        pageId: Uuid;
+    } | {
+        newOnTable: Uuid;
+    }) => string;
+    /**
+     * OPTIONAL. ASK THE AGENT TO CHANGE THIS DASHBOARD (SCR-16).
+     *
+     * "break it down by owner" is how a dashboard is actually built — the agent
+     * calls `dashboard_propose` on the server's `records` tool with this
+     * dashboard's id and re-states it. Only the server can do that honestly (a
+     * browser stamping itself `agent` is a browser claiming to be one), which is
+     * the same reason `enrich` is a port, so this is one too.
+     *
+     * Unbound, the box is drawn DISABLED with one sentence naming this port —
+     * never a composer that goes nowhere and never silence.
+     */
+    onReask?: (question: string, context: ReaskContext) => Promise<void>;
+    /**
+     * OPTIONAL. ASK AN AGENT FOR A WHOLE FORM, BOOKING PAGE, PORTAL OR DIGEST.
+     *
+     * This is the FASTER of the two ways every builder offers (`BuildOrAsk`), and
+     * it is a port for the same reason `onReask` is: the server's `records` tool
+     * is what calls `form_propose`, `booking_propose`, `portal_propose` and
+     * `subscription_propose`, and a browser stamping itself `agent` would be a
+     * browser claiming to be one.
+     *
+     * `suggestion` is the sentence this package would put in the person's mouth —
+     * a host normally opens its composer with it already typed, so the person
+     * edits rather than starts.
+     *
+     * Unbound, the "Ask an agent" button is ABSENT — not greyed — and every
+     * builder's empty state says so in one sentence naming this port, with the
+     * hand-built way still right there. The product walk of 2026-09-21 found the
+     * opposite arrangement (the agent named and no builder at all), which left a
+     * person who did not know what to say with nothing to press.
+     */
+    onAskForOne?: (ask: AgentBuildAsk) => void;
+}
+/** What the formula box hands the host's help (`formulaHelp`). */
+interface FormulaHelpAsk {
+    tableId: Uuid;
+    /** The formula as it stands in the box (may be empty). */
+    text: string;
+    /** The table's other columns, the ones the formula may read as {Name}. */
+    columns: readonly Field[];
+    /** The store's reading of what is wrong with the text, when it does not parse. */
+    mistake: string | null;
+    /** The functions the store works out, as a person types them. */
+    functions: readonly string[];
+    /** Put a formula into the box (unsaved). */
+    onFormula: (text: string) => void;
+    /**
+     * What the formula is for, in a person's words, when it is not a formula column: a row action's
+     * Work out step says which column it sets. Absent, it is a formula column.
+     */
+    purpose?: string | undefined;
+}
+/** What a person is asking an agent to make, and where they were standing. */
+interface AgentBuildAsk {
+    /**
+     * `column`: a layout needs a column the table lacks (`ViewNeeds`, lane DATA-V2-VIEWS-1) — the
+     * agent adds it through the store's field door, held for approval like every agent schema change.
+     */
+    kind: "form" | "booking" | "portal" | "digest" | "column";
+    tableId: Uuid;
+    /** The sentence this package would say. A host opens its composer with it. */
+    suggestion: string;
+}
+/**
+ * WHAT A CLICK ON A NUMBER ASKS FOR. The filter is already merged: the block's
+ * own filter (which `custom.dashboard_run` echoes back with the canvas bar
+ * folded under it) with the clicked group's key and value over the top. A host
+ * that dropped a key would open the grid on more records than the number
+ * counted, which is the one way this control can lie.
+ */
+interface OpenRecordsAsk {
+    tableId: Uuid;
+    filter: Record<string, AggregateFilter>;
+    /** What the person clicked, in words: "Jobs by stage this month · Awaiting parts". */
+    label: string;
+}
+/** Which dashboard a re-ask is about, so the agent re-states it rather than making a second one. */
+interface ReaskContext {
+    tableId: Uuid;
+    /** Null while the canvas has no dashboard yet — the answer is the first one. */
+    dashboardId: Uuid | null;
+    dashboardName: string | null;
+}
+/**
+ * What a host's share dialog is being opened ON. A Table is a record in this
+ * store (a `custom.record` row whose table is the Table kernel), so ONE subject
+ * shape covers both screens and `kind` is what the sentences say, not what the
+ * store looks up.
+ */
+interface ShareSubject {
+    kind: "record" | "table";
+    /** The store is keyed (organization_id, id); this package never guesses one. */
+    organizationId: Uuid;
+    subjectId: Uuid;
+    /** What to call it on screen. Never empty — the id's first eight characters at worst. */
+    name: string;
+    /** Close the dialog. The control owns the open/closed state, the host owns the dialog. */
+    onClose: () => void;
+}
+/** One column, handed to the host's "Who can see and edit" panel. */
+interface ColumnAccessSubject {
+    tableId: Uuid;
+    fieldId: Uuid;
+    /** The column's name as the grid shows it. */
+    name: string;
+    /** Close the panel. */
+    onClose: () => void;
+    /** Called after the panel saved a change, so the grid re-reads the Table's columns. */
+    onChanged: () => void;
+}
+/** One member of the organization, in the words a person reads. */
+interface OrganizationMember {
+    /** The platform's user id. This is what a Person record carries as `user_id`. */
+    userId: string;
+    /** Their display name, when the platform has one. */
+    name?: string | null;
+    email?: string | null;
+    avatarUrl?: string | null;
+}
+/** The durable half of offline capture: read the queue, write it, that is all. */
+interface CaptureQueuePort {
+    load: () => Promise<PendingCapture[]>;
+    save: (pending: PendingCapture[]) => Promise<void>;
+}
+/** One capture waiting to be written, with the id the CLIENT minted for it. */
+interface PendingCapture {
+    /**
+     * The client key. Minted offline, before the first attempt, and never
+     * re-minted on retry — that is exactly what lets the store's replay ledger
+     * tell a retry from a second capture.
+     */
+    clientKey: string;
+    tableId: Uuid;
+    payload: Record<string, unknown>;
+    capturedAt: string;
+    device: string;
+    /** How many times sending has been tried, and what the store last said. */
+    attempts: number;
+    lastRefusal?: string | null;
+}
+
+/** The name of one Field, as a header, a form label or a peek's term. */
+declare function fieldName(field: Field): string;
+/** The name of one Table, as a card, a heading or a breadcrumb. */
+declare function tableName(table: Table): string;
+/**
+ * The name of one RECORD, for a chip, a card, a relation cell or a peek title.
+ *
+ * `titleKey` is the Table's own `title_field` when the caller knows the Table —
+ * that is the store's answer to "what makes this record a chip" (REC-2) — and
+ * the conventional keys are tried after it. A record with nothing readable is
+ * NOT shown as a truncated uuid: it says it has no name yet, because "8f2c1b0a"
+ * tells a person nothing and looks like a bug.
+ */
+declare function recordName(document: RecordDocument | undefined, titleKey?: string | null, fallback?: string): string;
+/**
+ * Is this string the store's id for something, rather than words a person wrote?
+ *
+ * The same question `custom._card_words` asks on the database, with the same regex, so the
+ * screen and the store agree about what is a name (TAILS-2, 2026-09-21).
+ */
+declare function looksLikeId(value: unknown): boolean;
+/** The same question for a row the read door returned. */
+declare function rowName(row: ReadRow | undefined, titleKey?: string | null, fallback?: string): string;
+/** A Table as far as naming is concerned — its own declared title column (REC-2). */
+type TitledTable = Pick<Table, "title_field"> | null | undefined;
+/**
+ * THE NAME OF A RECORD WHOSE TABLE YOU ALREADY HOLD.
+ *
+ * `table` is the Table the record belongs to; its `title_field` is the store's answer to
+ * "what makes this record a chip" (REC-2) and is tried first, then the conventional keys,
+ * then the fallback. A Table that has not loaded yet is `null` and the conventional keys
+ * still answer — a name arriving a tick late is better than a screen that shows nothing.
+ */
+declare function recordNameIn(table: TitledTable, document: RecordDocument | undefined, fallback?: string): string;
+/** The same, for a row the read door returned. */
+declare function rowNameIn(table: TitledTable, row: ReadRow | undefined, fallback?: string): string;
+/**
+ * WHAT A RELATION CHIP SAYS WHEN THE RECORD IT POINTS AT IS NOT YOURS.
+ *
+ * A relation joins two records in two tables, and holding one end says nothing
+ * about the other: a Job shared with you may point at a Client nobody shared.
+ * The chip then has three possible answers and only one of them is honest —
+ * the target's TITLE is a leak, a bare id is a bug with a hex number in it, and
+ * a permanent "Loading…" is a lie that never resolves.
+ *
+ * This is the SAME sentence `platform.relation_withheld_label()` answers on the
+ * database, word for word, so a person reads one wording whether the screen or
+ * the store worked it out. Changing it changes both (RELATION-DECLARE,
+ * 2026-09-20).
+ */
+declare const WITHHELD_RECORD_LABEL = "A record you have not been given access to";
+/**
+ * WHEN THE STORE COULD NOT BE ASKED (a 503, a dropped connection) the name is UNREAD, not
+ * withheld: saying "not given access" for a failed read lies about the data (W1.1 verifier,
+ * 2026-10-02). This is what a reference reads until a later read answers.
+ */
+declare const UNREAD_RECORD_LABEL = "Couldn't load this name";
+/**
+ * ONE RECORD'S NOUN, IN A SENTENCE ("Book a 30-minute visit") — lane HANDOVER, 2026-09-28.
+ *
+ * Cedar Ridge Physical Therapy's booking page was titled "Book a 30-minute Visits appointment":
+ * the table's NAME (a plural, a heading) was put where one record's noun goes. The noun is the
+ * table's own singular ("Visit"), else its name, else the fallback; a Title-case word is written
+ * the way a sentence writes it ("visit"), an acronym is kept ("MRI scan").
+ */
+declare function singularNoun(table: {
+    name?: string | null;
+    label_singular?: string | null;
+} | null | undefined, fallback?: string): string;
+/**
+ * THE FIELD A CARD IS TITLED BY — kanban, calendar, gallery and pipeline alike.
+ *
+ * Order: the Table's `title_field` → a conventional name key (`title`, `name`, …) → the first
+ * text column in declared `sort` order → the first other column that can title (never a
+ * checkbox, never the group column, never a system stamp). `undefined` when nothing can, and
+ * the card falls back to `rowName`, which says "Untitled" rather than "false".
+ */
+declare function cardTitleField(fields: readonly Field[], titleKey: string | null | undefined, exclude?: readonly (string | null | undefined)[]): Field | undefined;
+
+/** What the roster can tell us about a user id. `null` when it cannot. */
+type ResolveName = (userId: Uuid) => string | null;
+/** The honest stand-in when nobody and nothing can put a name to the author. */
+declare const SOMEBODY = "somebody in this organization";
+/** The platform's own word for itself. Never "null", never "system_user". */
+declare const THE_SYSTEM = "the system";
+/**
+ * WHO, in the words a person reads. One place, so the grid cell, the record
+ * timeline and the column history cannot drift into three different answers.
+ */
+declare function actorWords(actor: HistoryActor, resolve?: ResolveName | undefined): string;
+/** How long ago, in the words a person uses out loud. */
+declare function whenWords(at: string, now?: Date): string;
+declare function lastChangeSentence(fieldLabel: string, entry: FieldHistoryEntry | null, resolve?: ResolveName | undefined): string;
+/**
+ * The SHORT form the badge wears once it knows: a name a person recognises at a
+ * glance, in the width of a cell corner. Never a uuid, never an email's domain.
+ */
+declare function actorBadge(actor: HistoryActor, resolve?: ResolveName | undefined): string;
+
+/** The word a withheld cell shows in place of a value. Never "—", which means empty. */
+declare const WITHHELD_WORD = "Withheld";
+type Hidden = Readonly<Record<string, HiddenFieldNotice | undefined>> | null | undefined;
+/** The store's notice for this column of this row, when the store withheld it. */
+declare function withheldNoticeOf(hidden: Hidden, key: string): HiddenFieldNotice | null;
+/**
+ * THE SENTENCE, in the store's own words: the notice's `says` when the store wrote one (a
+ * worked-out column names what it reads), else the notice's reason, the level it needs and the
+ * other way in.
+ */
+declare function withheldSentence(field: Pick<Field, "key" | "label" | "name">, notice: HiddenFieldNotice): string;
+
+/**
+ * What a person picks in the panel — AND IT IS THE STORE'S OWN LIST, not a union
+ * assembled here.
+ *
+ * 🚨 THE CLASS FIX (FIX-10B-F6, VERIFIER-10). This used to read
+ * `ParityFieldType | PlainFieldType | RelationFieldType` — the parity floor plus two words
+ * this file knew about — and that union was the whole defect. `custom.doc_sign` accepts
+ * exactly one field, a text column whose format is `signature`, and it is granted to
+ * `authenticated`; the Documents screen told a person in so many words to go and declare
+ * one; and no list any screen could read named it, so the control did not exist and the
+ * e-sign half of Documents was unreachable from the product. A kind the store takes and no
+ * screen offers is invisible, and nothing failed — which is the only reason it survived.
+ *
+ * `custom.field_kinds()` is now the ONE registry and `DECLARABLE_FIELD_KINDS` is generated
+ * from it, so the next kind the store learns arrives here as a TYPE ERROR in
+ * `FIELD_TYPE_CHOICES`'s coverage and as a red `kindsWithNoChoice()` below — never as a
+ * silence.
+ */
+type PickableFieldType = DeclarableFieldKind | SystemFieldKind | "entity_reference" | NewerFieldKind | LookFieldKind;
+/**
+ * A KIND THAT IS A PLAIN COLUMN WEARING A LOOK (grids review 3, lane H item 5). The store keeps a
+ * column's "Shows as" on the Field (`display_format`, `custom.display_format_ids()` has `rating` and
+ * `time`), so a Rating is a whole number shown as stars and a Time is a time of day kept as its
+ * 24-hour text — declared through the ordinary door (`{ plain, display_format }`) the same way the
+ * "Shows as" picker makes one. Offered whenever the store does not yet publish the kind as its own
+ * word (`custom.field_kinds()`): a Rating the store publishes goes as `{ type: "rating", max }`.
+ */
+type LookFieldKind = "time";
+/**
+ * THE STORE'S OWN STAMPS AS COLUMNS (GRID-PRIMITIVES G5; TABLE-PARITY H2 H3, lane
+ * DEFAULT-GRID-PARITY). `custom.field_declare` takes these three WORDS and makes each a formula
+ * Field whose expression is the system node (`fx.autonumber`, `fx.created_time`,
+ * `fx.modified_time`, `config.system` naming which), so nobody types into them and every reader
+ * that serves a worked-out value serves them. `custom.field_kinds()` does not publish them,
+ * because each is a formula, not a behaviour of its own. So they are named here, sent as their
+ * word through the `{ type }` arm, and a new autonumber column numbers the records already in
+ * the table through `custom.autonumber_backfill`.
+ */
+type SystemFieldKind = "autonumber" | "created_time" | "modified_time";
+
+declare const PARITY_LABEL: Record<ParityFieldType, string>;
+/** The "made of" sentence the store itself publishes, for the field editor's help text. */
+declare const PARITY_MADE_OF: Record<string, string>;
+/**
+ * Plain text and plain number are behaviours with no parity type of their own.
+ *
+ * 🚨 THIS IS NOW AN ALIAS, AND THAT IS THE POINT (TAILS-3, 2026-09-21). The
+ * classifier moved into `@ai-matrx/records` as `FieldKind` so that the editor a
+ * person types into and the COERCION applied to what they typed are decided by
+ * one body. They were decided by two, and the public booking page paid for it:
+ * "Vehicle Year takes a number, and it was given a string" on every table with
+ * a number field.
+ */
+type EditorKind = FieldKind;
+/**
+ * Which editor one Field wants. Reads the Field's own declaration only — the
+ * behaviour, the modifiers, the format, the relation target and the config —
+ * because those are what the store stores, and a screen that guessed from a
+ * value would draw a different editor for an empty record.
+ *
+ * It is `fieldKindFor` with this package's kernel ids bound. Nothing here
+ * decides anything the core does not.
+ */
+declare function editorKindFor(field: Field): EditorKind;
+/**
+ * WHICH KIND A PERSON PICKED, read back off the Field the store keeps — the ONE reader every
+ * "what does this column hold" answer goes through (the Settings column list, the column panel).
+ *
+ * `editorKindFor` answers which EDITOR to draw, and for two families that is not the kind a
+ * person picked: a Signature is a text Field whose format is `signature` (it draws a line of
+ * text), and the store's stamps — Record number, Created time, Last changed time — are formula
+ * Fields whose `config.system` names the stamp. Read through the editor classifier alone, the
+ * Settings list called a Signature "Text" and a Record number "Worked out from other columns"
+ * (lane 10 W1-A, guard `every-pickable-kind-reads-back-as-itself.test.tsx`).
+ *
+ * `undefined` when the Field is none of the kinds the menu offers.
+ */
+declare function pickableTypeOf(field: Field): PickableFieldType | undefined;
+/**
+ * The type word a person sees in a header or a settings row — and it is the
+ * SAME word the field panel offers, read from `FIELD_TYPE_CHOICES`, so a column
+ * added as "Money" is never described anywhere else as "Currency".
+ */
+declare function fieldTypeLabel(field: Field): string;
+
+/** The facts a picker needs about one table, whichever list it came from. */
+interface PickerTable {
+    id: string;
+    name: string;
+    platform_owned?: boolean | null | undefined;
+    /** The Table document's own key for the same fact (`tableList()` spreads the document onto the Table). */
+    kept_by_the_app?: boolean | null | undefined;
+    /** `custom.table_facts`: which feature keeps it (`choices` for a value set). */
+    kept_for?: string | null | undefined;
+    /** `custom.data_home_tables`: the store's one word for what it is (`list` for a value set). */
+    kind?: string | null | undefined;
+    /** The table a value set belongs to (`custom.table_facts.used_in_table_id`). */
+    used_in_table_id?: string | null | undefined;
+    /** A checklist's steps, a booking page's slots, a workflow's states. */
+    work_kind?: unknown;
+    slug?: string | null | undefined;
+    /** When the table was made — what tells two lists apart once their column is gone. */
+    created_at?: string | null | undefined;
+}
+/** A value set: the List a choice column keeps its choices in. */
+declare function isValueSet(table: PickerTable): boolean;
+/** Anything the app keeps for itself rather than a table a person keeps. */
+declare function isKeptTable(table: PickerTable): boolean;
+interface TablePickerEntry<T extends PickerTable> {
+    table: T;
+    id: string;
+    /** Unique among the entries returned. */
+    label: string;
+    /** A value set (shown only with "Show lists", or because it is the chosen one). */
+    isList: boolean;
+}
+interface TablePickerEntries<T extends PickerTable> {
+    entries: TablePickerEntry<T>[];
+    /** How many value sets "Show lists" would add — 0 means the control is not worth drawing. */
+    listCount: number;
+}
+/**
+ * THE ONE RULE. Tables first (by name), then — with `showLists` — the value sets, each named
+ * "<column> — <owning table>". Any names still equal get " (2)", " (3)" so no two entries match.
+ */
+declare function tablePickerEntries<T extends PickerTable>(tables: readonly T[], options?: {
+    showLists?: boolean;
+    keep?: string | null | undefined;
+}): TablePickerEntries<T>;
+
+/**
+ * G1's TABLE-LEVEL COLORS (`custom.table_decorations` / `client.tableDecorations`),
+ * TRANSLATED INTO A `TableStyle` — the same document a saved view's own `presentation.style`
+ * is, so one resolver (`resolveTableStyle`, below) can treat "the table's colors" and "this
+ * view's colors" as two layers of the SAME thing instead of two unrelated systems.
+ *
+ * THE TRANSLATION IS NECESSARY AND IT IS THE ONLY ONE. G1 addresses a Field by its ID
+ * (REC-17 — a column renamed keeps its color), because it is the STORE's own door; a
+ * `TableStyle` addresses a Field by its KEY, because it reads straight off `row.document`,
+ * which is keyed by Field key. A rule or a color-by whose Field has been deleted (its id no
+ * longer resolves to a key) is dropped rather than crashing the whole style — a defect in
+ * one rule costs that rule, never the read.
+ */
+declare function styleFromDecorations(decorations: TableDecorations | null | undefined, fields: readonly Field[]): TableStyle;
+/**
+ * THE ONE PRESENTATION RESOLVER every colored surface in this package reads —
+ * `Grid`, and (via `Card`) the kanban board, the calendar and the gallery.
+ *
+ * THE CLASS THIS CLOSES (lane UI-QUICK-1, TABLE-PARITY review, 2026-09-24). Threading
+ * `view.presentation.style` into `Card` closed the instance the CALENDAR-GALLERY bench
+ * found — a VIEW that had its own color-by looked right everywhere — but it left the
+ * class open: a table whose colors are the ORGANIZATION's decorations (G1's
+ * `custom.table_decorations` — "color rows by Account Type", "MAXED and NEAR rules" on
+ * Arman's own Coding Accounts table) and whose views never set a `presentation.style` of
+ * their own drew NOTHING, on the grid exactly as much as on every other layout, because
+ * nothing in this package had ever read G1's door at all.
+ *
+ * TWO LAYERS, ONE DOCUMENT. The table's decorations are the base coat — what every view
+ * of this table shows until a view says otherwise. A view's OWN `presentation.style` is
+ * an override, piece by piece: a view that only ever set manual row highlights still
+ * inherits the table's color-by and rules for everything it never touched, and a view
+ * that fully redecorated (its own `colorBy` AND its own `rules`) is not haunted by a
+ * table rule it meant to replace. Per-piece, never all-or-nothing, because a view is a
+ * LOOK on top of the table, not a wholesale substitute for it.
+ */
+declare function resolveTableStyle(decorations: TableDecorations | null | undefined, fields: readonly Field[], viewStyle: TableStyle | undefined): TableStyle;
+
+export { type AgentBuildAsk, type EditorKind, NO_RIGHTS, type OpenRecordsAsk, PARITY_LABEL, PARITY_MADE_OF, type PickerTable, type RecordsUiHost, type ResolveName, SOMEBODY, THE_SYSTEM, type TablePickerEntries, type TablePickerEntry, type TableRights, UNREAD_RECORD_LABEL, WITHHELD_RECORD_LABEL, WITHHELD_WORD, actorBadge, actorWords, cardTitleField, editorKindFor, fieldName, fieldTypeLabel, getPersonTimeZone, isKeptTable, isValueSet, lastChangeSentence, looksLikeId, personActor, personWallNow, pickableTypeOf, recordName, recordNameIn, recordsDataSource, resolveTableStyle, rowName, rowNameIn, setPersonTimeZone, singularNoun, styleFromDecorations, subscribePersonTimeZone, tableName, tablePickerEntries, tableRightsAt, whenWords, withheldNoticeOf, withheldSentence };