sg-widgets-core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,2726 @@
+import { $ as STOCK_SPRITE_PATH, $t as isOperator, A as hierarchyEntity, At as emptyFilter, B as intersectStatuses, Bt as DataType, C as SummaryType, Ct as FilterNode, D as UploadFile, Dt as WireCondition, E as ThreadRow, Et as TextSearchFilter, F as StatusIcon, Ft as referencedPaths, G as statusLabel, Gt as TIME_UNITS, H as relativeLuminance, Ht as OPERATORS, I as StatusOption, It as toApi3Hash, J as NATIVE_STATUSES, Jt as ValueShape, K as statusPaint, Kt as TimeUnit, L as StatusPaint, Lt as toFilterArray, M as normalizeHierarchyNode, Mt as group, N as Rgb, Nt as isBlankCondition, O as UploadResult, Ot as WireGroup, P as StatusGlyph, Pt as isEmptyFilter, Q as STOCK_ICON_KEYS, Qt as isNumericType, R as StatusRecord, Rt as walk, S as SummaryGrouping, St as FilterGroup, T as ThreadAuthor, Tt as Scalar, U as rgbToCss, Ut as OPERATORS_BY_TYPE, V as parseBgColor, Vt as NEGATING_OPERATORS, W as statusGlyph, Wt as Operator, X as STOCK_ICON_CELLS, Xt as isFilterable, Y as NativeStatus, Yt as isDataType, Z as STOCK_ICON_DATA_URLS, Zt as isLinkType, _ as SgClient, _t as statusFieldNameFor, a as EventLogOptions, at as stockIconSource, b as SummaryField, bt as EntityRef, c as HierarchyNode, ct as FieldSchema, d as RawHierarchyNode, dt as RawProperty, en as isTemporalType, et as SpriteCell, f as RestClient, ft as displayNameOf, g as SgApiError, gt as statusFieldFor, h as SearchResult, ht as normalizeFields, i as EventLogEntry, it as spriteStyle, j as normalizeEventLogEntry, jt as fromWire, k as eventLogFilters, kt as condition, l as HierarchyPath, lt as RawFieldSchema, m as SearchOptions, mt as normalizeField, n as EntityRow, nn as supportsOperator, nt as isNativeStatus, o as EventLogResult, ot as DISPLAY_NAME_FIELDS, p as RestClientOptions, pt as fieldSchemaOverride, q as usableStatuses, qt as VALUE_SHAPE, r as EntityTypeInfo, rt as nativeStatus, s as FollowingOptions, st as FIELD_SCHEMA_OVERRIDES, t as EVENT_LOG_FIELDS, tn as operatorsFor, tt as StockIconSource, u as HierarchyRef, ut as RawFieldsResponse, v as SummarizeOptions, vt as undeclaredField, w as TextSearchRow, wt as LogicalOperator, x as SummaryGroup, xt as FilterCondition, y as SummarizeResult, yt as ConditionValue, z as foregroundFor, zt as DATA_TYPES } from "./client-BhHppzTV.mjs";
+//#region src/field-icons.d.ts
+/** The catch-all glyph, used for a data type this build does not know. */
+export declare const DEFAULT_FIELD_ICON = "file-text";
+/** The lucide icon name for a field's data type. */
+export declare function iconNameFor(dataType: string): string;
+/** Every icon name this module can return, for a UI package's name-to-component map. */
+export declare const FIELD_ICON_NAMES: readonly string[];
+//#endregion
+//#region src/filter-ux.d.ts
+/** One label per raw operator, for a type that has no wording of its own. */
+export declare const OPERATOR_LABELS: Readonly<Record<Operator, string>>;
+/** The label a data type puts on an operator. */
+export declare function operatorLabel(operator: Operator, dataType?: string): string;
+/** Singular and plural wording for a relative-date unit. */
+export declare const TIME_UNIT_LABELS: Readonly<Record<TimeUnit, [string, string]>>;
+export declare function timeUnitLabel(unit: TimeUnit, count?: number): string;
+/** How a row edits the value of a preset. */
+export type PresetInput = 'none' | 'scalar' | 'list' | 'range' | 'relative' | 'string';
+/**
+ * One entry of the operator menu.
+ *
+ * `operator` and, for a pinned preset, `value` are what serialisation sends;
+ * everything else is wording. A preset whose `id` equals its `operator` is the
+ * plain operator with no UX layer on it.
+ */
+export interface OperatorPreset {
+  id: string;
+  label: string;
+  operator: Operator;
+  input: PresetInput;
+  /** The value the preset pins. Present only when `input` is `none`. */
+  value?: ConditionValue;
+}
+/** A named run of the operator menu. */
+export interface OperatorGroup {
+  label: string;
+  presets: OperatorPreset[];
+}
+/**
+ * The value "is empty" sends on a type, or `undefined` when the type has no
+ * empty test at all.
+ *
+ * `null` is the spelling on every filterable type but two: uuid takes `""` and
+ * 400s on null, and a checkbox is two-state, never null, and 400s on both
+ * (field_types/uuid, field_types/checkbox).
+ */
+export declare function emptyValueFor(dataType: string): '' | null | undefined;
+export declare function supportsEmpty(dataType: string): boolean;
+/**
+ * The operators a field takes: its data type's vocabulary, narrowed by the
+ * field's own `operators` where the API evaluates fewer of them.
+ */
+export declare function fieldOperators(field?: Pick<FieldSchema, 'dataType' | 'operators'> | null): readonly Operator[];
+/**
+ * The operator menu for a data type, grouped. Every entry names the raw operator
+ * it serialises to; an unfilterable type gets an empty menu. `operators` narrows
+ * the menu to what the field's own site answers.
+ */
+export declare function operatorMenu(dataType: string, operators?: readonly Operator[]): OperatorGroup[];
+/**
+ * Every menu entry for a data type, in menu order. Calendar operators are
+ * replaced by their named offsets and never offered raw: an integer offset with
+ * no wording around it is not a control anyone can read.
+ */
+export declare function presetsFor(dataType: string, only?: readonly Operator[]): OperatorPreset[];
+export declare function presetById(dataType: string, id: string, operators?: readonly Operator[]): OperatorPreset | undefined;
+/** The menu entry a condition currently sits on. */
+export declare function presetIdOf(condition: FilterCondition, dataType: string): string;
+/**
+ * Move a condition onto another menu entry. The value survives when the two
+ * entries edit the same shape and is reset to the type's default otherwise, so
+ * switching "is" to "is any of" keeps what was typed only where it fits.
+ */
+export declare function applyPreset(condition: FilterCondition, preset: OperatorPreset, dataType: string): FilterCondition;
+/** True when the condition sits on a preset that pins its value, so no editor is drawn. */
+export declare function isPinned(condition: FilterCondition, dataType: string): boolean;
+/**
+ * The value a row starts on. Blank wherever a person has to supply the value, so
+ * a half-built row serialises to nothing; filled where the type has only one
+ * sensible starting point (a checkbox is two-state and never null, and a
+ * relative window with no length is not a window).
+ */
+export declare function defaultValueFor(dataType: string, operator: Operator): ConditionValue;
+/** A blank condition on a field, ready for its value. */
+export declare function defaultCondition(path: string, dataType: string, operators?: readonly Operator[]): FilterCondition;
+/** A condition read as three segments: what is compared, how, and against what. */
+export interface ConditionParts {
+  field: string;
+  operator: string;
+  /** Empty when the operator pins its own value, as `is empty` and the calendar presets do. */
+  value: string;
+}
+/**
+ * The three segments of a condition's summary. A pill draws them apart and a
+ * sentence joins them; both read the same words.
+ */
+export declare function conditionParts(condition: FilterCondition, field?: FieldSchema | null): ConditionParts;
+/** A condition's values, as much of them as a pill has room to name. */
+export interface ConditionValues {
+  /** The values the pill names, in order. */
+  shown: string[];
+  /** Values past `shown`, which the pill reads as `+n`. */
+  overflow: number;
+  /** Every value, comma-joined, for the `title` a truncated pill carries. */
+  title: string;
+  /** The shown values as one line, for a pill that spells its values rather than drawing them. */
+  text: string;
+  /** The scalar behind each shown value, for a pill that draws its values rather than spelling them. */
+  values: Scalar[];
+}
+/**
+ * A condition's values as a pill reads them: the first `max`, at least one, a count of
+ * the rest, and the whole list for the title. A condition on any other shape than a
+ * list has one value and no overflow, so a pill draws it whole.
+ */
+export declare function conditionValues(condition: FilterCondition, field?: FieldSchema | null, max?: number): ConditionValues;
+/**
+ * One line naming what a condition matches, such as
+ * `Status is any of Approved, Final`. Without a schema the field's dotted path
+ * stands in for its label and codes stand in for their display values.
+ */
+export declare function describeCondition(condition: FilterCondition, field?: FieldSchema | null): string;
+export type ConditionIssueCode = 'no-field' | 'unknown-field' | 'unfilterable' | 'unknown-operator' | 'wrong-shape' | 'blank-value';
+export interface ConditionIssue {
+  code: ConditionIssueCode;
+  message: string;
+}
+/**
+ * Everything wrong with one row, in the order a person would fix it. An empty
+ * array means the row serialises to a filter the API accepts.
+ *
+ * `field` is the schema of the path's last segment. Pass `null` when the path
+ * resolved to nothing and omit it when no schema is loaded, which suppresses
+ * every check that needs one.
+ */
+export declare function validateCondition(condition: FilterCondition, field?: FieldSchema | null): ConditionIssue[];
+/** The value editor a data type needs, once the operator has chosen the shape. */
+export type ValueEditorKind = 'none' | 'text' | 'number' | 'date' | 'date_time' | 'checkbox' | 'options' | 'entity' | 'color' | 'url';
+/**
+ * Which editor a row draws. The operator picks the arity (one value, a list, a
+ * range, a relative window) and the data type picks the editor inside it.
+ *
+ * A `url` field takes no filter at all, so no field list offers one; the kind is
+ * here for a tree that carries a path the schema no longer filters on
+ * (field_types/url).
+ */
+export declare function valueEditorFor(dataType: string, operator: Operator): ValueEditorKind;
+/** Whether a value editor holds one value or many. */
+/** The arity a row draws: none for a pinned preset, else the operator's own. */
+export declare function conditionArity(condition: FilterCondition, dataType: string): 'none' | 'one' | 'many' | 'two' | 'relative';
+export declare function valueArity(operator: Operator): 'none' | 'one' | 'many' | 'two' | 'relative';
+/**
+ * The values a list-shaped condition holds, as a row edits them. `in` and `not_in`
+ * take a JSON array, so anything else on the condition reads as no values yet.
+ */
+export declare function conditionList(value: ConditionValue): Scalar[];
+/** The list with one value replaced. An index outside it leaves the list alone. */
+export declare function withListValue(value: ConditionValue, index: number, next: Scalar): Scalar[];
+/** The list with one value dropped. */
+export declare function withoutListValue(value: ConditionValue, index: number): Scalar[];
+/**
+ * The list with one more entry on the end, blank. A blank entry serialises to
+ * nothing: a row whose value is still unfilled is dropped rather than sent.
+ */
+export declare function withAddedListValue(value: ConditionValue): Scalar[];
+/** A relative-date window, as a filter row edits it. */
+export interface RelativeDate {
+  count: number;
+  unit: TimeUnit;
+  direction: 'last' | 'next';
+  /** Negated windows also match rows where the field is unset (017_filter_operators). */
+  negated?: boolean;
+}
+export declare function relativeOperator(relative: Pick<RelativeDate, 'direction' | 'negated'>): Operator;
+export declare function relativeValue(relative: Pick<RelativeDate, 'count' | 'unit'>): [number, TimeUnit];
+/** Read a condition back as a relative window, or `null` when it is not one. */
+export declare function relativeFrom(operator: Operator, value: ConditionValue): RelativeDate | null;
+/** The count and the unit a relative row shows, with the default window for an unfilled one. */
+export declare function relativeWindow(value: ConditionValue): {
+  count: number | null;
+  unit: TimeUnit;
+};
+/** The window with one half replaced. A missing count goes as 1, the smallest the API takes. */
+export declare function withRelativeWindow(value: ConditionValue, next: Partial<{
+  count: number | null;
+  unit: TimeUnit;
+}>): [number, TimeUnit];
+/**
+ * The time units as a field, so a relative row picks its unit with the same list
+ * control a `list` field uses. Mandatory: a window always has a unit.
+ */
+export declare function timeUnitField(displayName?: string): Pick<FieldSchema, 'displayName' | 'mandatory' | 'validValues' | 'displayValues'>;
+/**
+ * Where a node sits in the tree: the index it holds in each group from the root
+ * down. `[]` is the root itself.
+ */
+export type NodePath = readonly number[];
+export declare function nodeAt(root: FilterNode, path: NodePath): FilterNode | undefined;
+/** A copy of the tree with the node at `path` replaced. The root cannot be replaced this way. */
+export declare function replaceAt(root: FilterGroup, path: NodePath, node: FilterNode): FilterGroup;
+/** A copy of the tree with the node at `path` gone. */
+export declare function removeAt(root: FilterGroup, path: NodePath): FilterGroup;
+/** A copy of the tree with `node` appended to the group at `path`. */
+export declare function appendAt(root: FilterGroup, path: NodePath, node: FilterNode): FilterGroup;
+/** A copy of the tree with the node at `path` moved `delta` places among its siblings. */
+export declare function moveAt(root: FilterGroup, path: NodePath, delta: number): FilterGroup;
+/** Conditions in the tree, nested groups included. */
+export declare function countConditions(node: FilterNode): number;
+/** Conditions that would survive serialisation. */
+export declare function countActiveConditions(node: FilterNode): number;
+/** The first condition on a field path, with where it sits. */
+export declare function findCondition(root: FilterNode, path: string, at?: NodePath): {
+  at: NodePath;
+  condition: FilterCondition;
+} | undefined;
+/**
+ * A copy of the tree with every condition on one of `paths` gone. A group the
+ * pruning emptied goes with it, so the `or` of `is` conditions a facet writes
+ * leaves nothing behind.
+ */
+export declare function withoutPaths(root: FilterGroup, paths: readonly string[]): FilterGroup;
+/**
+ * How a facet spells a set of ticked values on a field.
+ *
+ * A field the API evaluates `in` on takes one condition holding the list. A field
+ * it does not takes one condition per value: `is` joined by `or`, `is_not` joined
+ * by `and`, which is the same set of rows.
+ */
+export interface FacetShape {
+  /** The operator a ticked set writes. */
+  any: Operator;
+  /** The operator a negated set writes. */
+  none: Operator;
+  /** True where a set of several values is one condition per value. */
+  spread: boolean;
+}
+export declare function facetShape(field?: Pick<FieldSchema, 'dataType' | 'operators'> | null): FacetShape;
+/** The node a facet contributes, read back as one checklist. */
+export interface FacetCondition {
+  /** Where the node sits in the tree. */
+  at: NodePath;
+  /** The condition, or the group of one-value conditions, the facet wrote. */
+  node: FilterNode;
+  /**
+   * The condition a pill reads. A group of one-value conditions stands in as one
+   * list-shaped condition, so a pill draws every facet the same way. Never serialised.
+   */
+  summary: FilterCondition;
+  /** The operator the checklist writes, `in` or `is` and their negations. */
+  operator: Operator;
+  /** The values ticked. Empty where the node is not a checklist. */
+  values: Scalar[];
+  /** True where the node is a checklist this facet can edit, false where the editor wrote it. */
+  checklist: boolean;
+}
+/**
+ * The node a facet contributes on `path`, wherever it sits: the condition it
+ * wrote, or the group of one-value conditions it wrote on a field the API
+ * evaluates no `in` on.
+ */
+export declare function findFacet(root: FilterNode, path: string, field?: Pick<FieldSchema, 'dataType' | 'operators'> | null, at?: NodePath): FacetCondition | undefined;
+/**
+ * Set the condition a facet contributes: replaced where one exists, appended to
+ * the root where none does, removed when nothing is ticked. `operator` is the
+ * list operator the facet holds, spelled out as one `is` per value on a field the
+ * API evaluates no `in` on.
+ */
+export declare function setFacet(root: FilterGroup, path: string, values: readonly Scalar[], operator?: Operator, field?: Pick<FieldSchema, 'dataType' | 'operators'> | null): FilterGroup;
+/** A facet's condition moved onto another of its menu entries. */
+export declare function setFacetPreset(root: FilterGroup, path: string, preset: OperatorPreset, dataType: string, field?: Pick<FieldSchema, 'dataType' | 'operators'> | null): FilterGroup;
+/** One value a facet offers, with how many rows hold it. */
+export interface FacetValue {
+  /** Stable identity for the UI. An entity is `Type:id`; everything else is its own string. */
+  key: string;
+  label: string;
+  /** The value an `in` condition sends. */
+  value: Scalar;
+  count: number;
+}
+/** What one facet lists, and where its counts came from. */
+export interface FacetList {
+  values: FacetValue[];
+  /**
+   * The rows the counts were tallied from, where they came from a page of rows rather
+   * than the site's groups. Absent where every count is the site's own.
+   */
+  sampled?: number;
+}
+/** The groups of a `_summarize` call grouped on `field` under `filters`. */
+export type FacetCounts = (field: string, filters: WireGroup | null) => Promise<SummaryGroup[]>;
+/** What a facet reads: the site's groups, and one page of rows for a field it cannot group. */
+export interface FacetReads {
+  counts?: FacetCounts | undefined;
+  /** One page of rows carrying `fields`, under `filters`. */
+  sample: (fields: readonly string[], filters: WireGroup | null) => Promise<readonly EntityRow[]>;
+  /**
+   * Fields the site refused to group, as `Type.field`, held by the caller across reads
+   * so the site is asked once per field. Filled here.
+   */
+  refused?: Set<string>;
+}
+/**
+ * The values a facet offers, tallied from a page of rows.
+ *
+ * The site vocabulary of a `list` or `status_list` field comes from the schema so
+ * a value nobody holds still appears at zero; every other type can only be
+ * discovered from the rows that were read, so its list is as complete as the page
+ * size allowed.
+ */
+export declare function facetValues(rows: readonly EntityRow[], field: FieldSchema): FacetValue[];
+/**
+ * The values a facet offers, from the groups of a `_summarize` call grouped on its
+ * field. A group is keyed on `group_value`, which on an entity field is the reference
+ * itself, so two people sharing a display name stay two rows, and `group_name` is the
+ * label. The `''` group, the rows with nothing in the field, is left out: the empty
+ * tests belong to the dialog (020_summarize). A multi_entity group's value is the
+ * row's set of links as an array of references, and it counts towards each of them;
+ * the corpus has not measured that grouping.
+ */
+export declare function facetValuesFromGroups(groups: readonly SummaryGroup[], field: FieldSchema): FacetValue[];
+/** The `counts` reader over a client: one `_summarize` call grouped on the field. */
+export declare function facetCounts(client: Pick<SgClient, 'summarize'>, entityType: string): FacetCounts;
+/**
+ * The filter each facet counts against: the base filter and the whole tree, less the
+ * facet's own conditions, so a facet keeps every value it could switch to while the
+ * others show what remains. Keyed by facet name; a facet nobody ticked shares the
+ * whole tree with its neighbours.
+ */
+export declare function facetScopes(value: FilterGroup, base: FilterGroup | null, facets: readonly string[]): Record<string, WireGroup | null>;
+/**
+ * True where the site refused to group the field: a 4xx. The measured refusal is
+ * 400 `Grouping is not allowed for field <Type>.<field>.` (field_types/image,
+ * field_types/summary); the status decides, never the wording.
+ */
+export declare function isGroupingRefusal(error: unknown): boolean;
+/**
+ * What every facet lists, each counted under its own scope.
+ *
+ * With `counts`, a field's values come from the site's groups, and a field the site
+ * refuses to group is tallied from one page of rows instead, with the schema's
+ * vocabulary at zero and `sampled` saying how many rows; the refusal is kept in
+ * `refused` so the next read tallies that field without asking. Without `counts`
+ * every field is tallied that way. Facets sharing a scope share one page. Any other
+ * failure fails the read.
+ */
+export declare function facetLists(fields: readonly FieldSchema[], scopes: Record<string, WireGroup | null>, reads: FacetReads): Promise<Record<string, FacetList>>;
+/**
+ * The menu a facet pill's operator segment offers: the operators that take the
+ * checklist's list of values, and the empty tests, which take none. A field the
+ * API evaluates no `in` on still offers both list entries, since the facet spells
+ * a list out as one condition per value.
+ */
+export declare function facetPresets(dataType: string, field?: Pick<FieldSchema, 'dataType' | 'operators'> | null): OperatorPreset[];
+export declare function isSortable(dataType: string): boolean;
+/** Fields a sort picker may offer, sorted by display name. */
+export declare function sortableFields(fields: Record<string, FieldSchema>, options?: {
+  hidePaths?: readonly string[];
+}): FieldSchema[];
+export interface SortKey {
+  /** Field name or dotted path. */
+  field: string;
+  direction: 'asc' | 'desc';
+}
+/**
+ * The `sort` string `_search` takes: field names comma-joined, each descending
+ * one prefixed with `-`. A leading `+` and a trailing ` desc` are both 400s, and
+ * id ascending is the implicit tiebreak (026_result_order).
+ */
+export declare function toSortString(keys: readonly SortKey[]): string;
+export declare function fromSortString(sort: string | null | undefined): SortKey[];
+/** A path pattern hides the exact path and everything under it. */
+export declare function isHiddenPath(path: string, hidePaths: readonly string[] | undefined): boolean;
+/** Fields a filter row may choose, sorted by display name. */
+export declare function filterableFields(fields: Record<string, FieldSchema>, options?: {
+  hidePaths?: readonly string[];
+  dataTypes?: readonly DataType[];
+}): FieldSchema[];
+//#endregion
+//#region src/render.d.ts
+/**
+ * The renderings a value can need. Deliberately small: several data types share a
+ * rendering, and the exact number formatting is chosen from the `dataType` itself.
+ */
+export type RenderKind = 'text' | 'number' | 'date' | 'datetime' | 'entity' | 'multi_entity' | 'status' | 'image' | 'checkbox' | 'url' | 'color' | 'list' | 'empty';
+/** The rendering a data type needs. Unknown types fall back to text. */
+export declare function renderKindFor(dataType: string): RenderKind;
+export interface FieldTextOptions {
+  /** The site's `hours_per_day`; a duration then renders in days (field_types/duration). */
+  hoursPerDay?: number;
+  locale?: string;
+  /** IANA zone a `date_time` is shown in. Defaults to the runtime's, which is what "local" means to a viewer. */
+  timeZone?: string;
+  /** Frames a second, for a timecode. Given, a timecode gains its frame digits (field_types/timecode). */
+  frameRate?: number;
+  /** Decimals kept on a float or a currency. */
+  decimals?: number;
+  currencySymbol?: string;
+  /** The status field's `display_values`, the only source of a status label (field_types/status_list). */
+  displayValues?: Record<string, string>;
+  /** Between the names of a multi_entity value. */
+  separator?: string;
+}
+/**
+ * Any value as one line of text.
+ *
+ * The renderings a widget usually draws with a component of its own -- a status
+ * badge, a thumbnail, a chip -- come back as their plain label, so a compact
+ * surface can show them as text and a caller can copy or export them.
+ */
+export declare function fieldText(value: unknown, dataType: string, options?: FieldTextOptions): string;
+/**
+ * True when there is nothing to show. `0`, `false` and `"0"` are values, not
+ * emptiness: a `number` holding 0 is `is_not None` on the server too
+ * (field_types/number, percent, duration).
+ */
+export declare function isEmptyValue(value: unknown): boolean;
+export interface DurationFormatOptions {
+  /**
+   * The site's `hours_per_day` from `GET /preferences`. Given, the duration is
+   * rendered in days, which is what a site with `duration_units: "days"` expects.
+   * The field schema names no unit; only the site does (field_types/duration).
+   */
+  hoursPerDay?: number;
+}
+/** A stored duration is a whole number of minutes (field_types/duration). */
+export declare function formatDuration(minutes: number | null | undefined, options?: DurationFormatOptions): string;
+/**
+ * A percent is a bare integer on a 0-100 scale, and nothing is clamped: -1 and
+ * 1000 both store at 200, so render what is there (field_types/percent).
+ */
+export declare function formatPercent(value: number | string | null | undefined): string;
+export interface TimecodeFormatOptions {
+  /**
+   * Frames a second, for the `HH:MM:SS:FF` form. No schema property and no
+   * preference names the rate, so it comes from the app; solving it out of a
+   * `_summarize` grouping gives 23.976 on the probed site
+   * (field_types/timecode).
+   */
+  frameRate?: number;
+}
+/**
+ * A timecode is milliseconds in a signed 32-bit integer. Nothing wraps at 24
+ * hours and negatives are stored, so hours are not clamped either
+ * (field_types/timecode). Without a frame rate the frame digits are left off;
+ * with one they are the sub-second remainder rounded to the nearest frame, which
+ * is how the server renders it.
+ */
+export declare function formatTimecode(ms: number | null | undefined, options?: TimecodeFormatOptions): string;
+export interface FloatFormatOptions {
+  /** Decimals to keep at most; trailing zeros are dropped. The store itself rounds to 6 (field_types/float). */
+  maxDecimals?: number;
+  /** Exactly this many decimals, zeros kept. Wins over `maxDecimals`. */
+  decimals?: number;
+}
+/**
+ * A float reads back as a JSON *string* rounded to 6 decimals ("25.0"), never a
+ * JSON number, so it is formatted from the string to avoid a needless round trip
+ * through binary (field_types/float).
+ */
+/**
+ * A currency amount with its symbol. There is no corpus card for `currency`; the
+ * read shape is treated as a decimal number and the symbol is the caller's.
+ */
+export declare function formatCurrency(value: number | string | null | undefined, options?: {
+  symbol?: string;
+  decimals?: number;
+  locale?: string;
+}): string;
+export declare function formatFloat(value: number | string | null | undefined, options?: FloatFormatOptions): string;
+export interface DateFormatOptions {
+  locale?: string | string[];
+  /** IANA zone. Defaults to the runtime's, which is what "local" means to a viewer. */
+  timeZone?: string;
+}
+/**
+ * A `date` is exactly "YYYY-MM-DD": no time, no zone (field_types/date). It is
+ * therefore formatted in UTC whatever the viewer's zone, because shifting a
+ * zoneless day into a local zone moves it to the wrong day.
+ */
+export declare function formatDate(value: string | null | undefined, options?: DateFormatOptions): string;
+/**
+ * A `date_time` is always UTC "YYYY-MM-DDTHH:MM:SSZ" at second resolution
+ * (field_types/date_time). It is shown in the viewer's zone; keep the raw string
+ * as a `title` so the stored instant stays readable.
+ */
+export declare function formatDateTime(value: string | null | undefined, options?: DateFormatOptions): string;
+/** The `upload`/`web` and `local` shapes of a `url` field (field_types/url). */
+export interface UrlValue {
+  url?: string | null;
+  name?: string | null;
+  content_type?: string | null;
+  link_type?: 'upload' | 'web' | 'local' | string;
+  local_path_mac?: string | null;
+  local_path_linux?: string | null;
+  local_path_windows?: string | null;
+  relative_path?: string | null;
+  type?: string;
+  id?: number;
+}
+/**
+ * The last path segment of a URL or path, percent-decoded, with the query
+ * dropped. A presigned attachment URL carries the signature in the query and the
+ * content hash in the path, so the query is never part of a file name
+ * (field_types/url, field_types/image).
+ */
+export declare function fileNameFromUrl(url: string | null | undefined): string;
+export type LocalPlatform = 'mac' | 'linux' | 'windows';
+/** The platform the current browser reports, for choosing which local path to open. */
+export declare function currentPlatform(): LocalPlatform;
+/** `file:` URL for a local path: a Windows drive path gains a third slash, and every segment is encoded. */
+export declare function fileHref(path: string): string;
+export interface UrlLinkInfo {
+  /** Where to open, or null when nothing can be opened. A local link opens through `file:`. */
+  href: string | null;
+  label: string;
+  /** Present on a `local` link: the path per platform, and the one for the current platform. */
+  local?: {
+    mac: string | null;
+    linux: string | null;
+    windows: string | null;
+    path: string | null;
+  };
+}
+/**
+ * A displayable link out of a `url` value. Three shapes exist and no fourth:
+ * `upload`/`web` (has `url` and `name`), `local` (paths, no `url`), and a bare
+ * string (field_types/url). A local link resolves to a `file:` href for the
+ * current platform; browsers refuse to follow one from an http page, so an app
+ * that opens paths another way rewrites it with its own scheme.
+ */
+export declare function urlLink(value: unknown, platform?: LocalPlatform): UrlLinkInfo | null;
+/** The prefix Flow PT serves while a thumbnail is still transcoding (field_types/image). */
+export declare const THUMBNAIL_PENDING_PATH = "/images/status/transient/";
+/**
+ * An `image` value is the only state marker there is: test the transient prefix,
+ * never truthiness (field_types/image).
+ */
+export declare function imageState(value: string | null | undefined): 'none' | 'pending' | 'ready';
+/**
+ * `Task.color` holds this token instead of a colour, meaning "use the colour of
+ * my Pipeline Step". Resolve it with a dotted `step.Step.color` read in the same
+ * call and keep a client default (field_types/color).
+ */
+export declare const COLOR_SENTINEL = "pipeline_step";
+/**
+ * Initials for an avatar fallback, from a person's display name. Takes the first
+ * letter of the first and last word, so "Ada Lovelace" is AL and "Anna van der
+ * Meer" is AM. A single word gives one letter; a `login` such as `j.doe` is
+ * split on its punctuation too.
+ */
+/**
+ * A stable index in `[0, count)` for a name, so the same person always gets the same
+ * tint. FNV-1a over the code points; the name alone, so a login and a display name
+ * of one person may differ.
+ */
+export declare function nameColorIndex(name: string | null | undefined, count?: number): number;
+/** Eight hues far enough apart to tell neighbours apart, skipping the muddy yellows. */
+export declare const NAME_HUES: readonly [15, 45, 95, 150, 195, 240, 285, 330];
+/** A stable hue for a name, for tinting initials independently of the theme. */
+export declare function nameHue(name: string | null | undefined): number;
+export declare function initialsOf(name: string | null | undefined, max?: number): string;
+//#endregion
+//#region src/state.d.ts
+/**
+ * The empty, loading and error states of `docs/design-rules.md` rule 5.
+ *
+ * Every data widget takes the same three labels and draws the same block. The
+ * defaults are here so the two registries cannot drift and a studio that wants
+ * its own wording sets one prop per widget. A translation seam belongs at this
+ * boundary; until a non-English studio asks for one, these are the strings.
+ */
+/** What a data widget is showing: one of the three state blocks, or its rows. */
+export type WidgetState = 'error' | 'loading' | 'empty' | 'rows';
+/** What a data widget calls its empty, loading and error states. */
+export interface StateLabels {
+  /** Shown when the read or the query returned nothing. */
+  emptyLabel?: string;
+  /** The accessible name of the skeletons a read stands behind. */
+  loadingLabel?: string;
+  /** Shown in place of what the failed read said. */
+  errorLabel?: string;
+}
+/** A query matched nothing. */
+export declare const NO_MATCH_LABEL = "No match";
+/** A read returned nothing. */
+export declare const NO_ROWS_LABEL = "No rows";
+/** A list of what the caller has picked holds nothing. */
+export declare const NOTHING_CHOSEN_LABEL = "Nothing chosen";
+/** A read is in flight. */
+export declare const LOADING_LABEL = "Loading…";
+/** A read failed and said nothing a reader can use. */
+export declare const ERROR_LABEL = "Something went wrong";
+/**
+ * The line a state block shows.
+ *
+ * An error falls back to what the read said and then to a fixed line, so a
+ * failure is never a blank block; a caller's `errorLabel` replaces both.
+ */
+export declare function stateLine(state: WidgetState, labels: StateLabels, message?: string | null): string;
+/**
+ * What a failed read said, as a line. An `Error` gives its message; anything else
+ * a promise rejected with is rendered as itself, so a thrown string still reads.
+ */
+export declare function errorText(error: unknown): string;
+//#endregion
+//#region src/search.d.ts
+/** The words the API matches on: whitespace-separated, empties dropped. */
+export declare function searchWords(text: string): string[];
+/** One stretch of a label, either inside a matched word or outside every one. */
+export interface MatchRun {
+  text: string;
+  match: boolean;
+}
+/**
+ * Split a label into alternating plain and matched runs, one run per stretch.
+ * Matching is case-insensitive and every word is highlighted wherever it occurs,
+ * because that is what the server matched on. Overlapping words merge into one
+ * run, so a run never nests and the runs always rebuild the label exactly.
+ *
+ * The result is text, never markup: a widget draws each run as an element and
+ * never sets HTML from a row. It is the one splitting in this package, and
+ * `highlightRuns` is the name the pickers were written against.
+ */
+export declare function matchRuns(label: string, query: string): MatchRun[];
+/**
+ * True when every word of the query appears in the text, the server's own rule.
+ * It is also the rule a list filters its own rows with, over the row's label and
+ * code joined into one text.
+ */
+export declare function matchesEveryWord(text: string, query: string): boolean;
+/** One search result, with what a row needs to draw itself. */
+export interface SearchHit {
+  /** The row, `name` filled from the search answer. */
+  ref: EntityRef;
+  /** Status code, never a label. */
+  status: string | null;
+  /** The row `_text_search` also matched the words against, when the row links to one. */
+  link: {
+    type: string;
+    name: string;
+  } | null;
+  /** `image`, when the type has one. Presigned and short-lived (field_types/image). */
+  image: string | null;
+  /** The row's project, `name` being its `cached_display_name`. Null on a site-wide type. */
+  project: EntityRef | null;
+  /**
+   * Attributes and relationships of the second read, in one map, so a row anatomy
+   * reads any field a caller asked for. A relationship is unwrapped to its `data`.
+   */
+  values: Record<string, unknown>;
+}
+/** A hit with only what `_text_search` itself answers. */
+export declare function toSearchHit(row: TextSearchRow): SearchHit;
+/**
+ * Fill in what `_text_search` does not answer: one `search` per type over the ids
+ * just returned. An unknown field name is dropped at 200, so asking every type for
+ * `image`, `project` and whatever a row anatomy names is safe even where the type
+ * carries none of it (probe 003).
+ */
+export declare function hydrate(client: SgClient, rows: TextSearchRow[], options?: {
+  /** Fields on top of the identity ones, for a caller's own sub-label or secondary. */
+  fields?: readonly string[] | undefined;
+  /** Field holding the label. The display-name chain answers it when absent. */
+  labelField?: string | undefined;
+}): Promise<SearchHit[]>;
+/** Enough of `SchemaService` to answer whether a type carries a field. */
+export interface FieldLookup {
+  field(entityType: string, name: string): Promise<{
+    name: string;
+  } | undefined>;
+}
+/**
+ * Add a project condition to every searched type that has a `project` field.
+ * A type without one 400s on the path rather than returning nothing: Project has
+ * no `project` field at all (entity_types/Project) and neither does Step
+ * (entity_types/Step), so the schema decides which types can be scoped.
+ */
+export declare function scopeToProject(schema: FieldLookup, entityTypes: Record<string, WireCondition[] | null | undefined>, projectId: number): Promise<Record<string, WireCondition[]>>;
+/**
+ * The pause a search widget leaves before it asks. Long enough that a typist does
+ * not fire a request a letter, short enough to feel live.
+ */
+export declare const SEARCH_DEBOUNCE_MS = 250;
+/** The page `_text_search` answers at its cap, which is also its default (probe 053). */
+export declare const SEARCH_PAGE_SIZE = 25;
+/**
+ * The rows a hierarchy search asks for. Each hit costs one path lookup on top of the
+ * search itself, so it asks for fewer than the endpoint allows.
+ */
+export declare const HIERARCHY_LEAF_LIMIT = 10;
+/**
+ * True when a further page may be there. A read carries no total and `links.next` is
+ * emitted forever, so a full page is the only sign of another one (006_pagination).
+ */
+export declare function hasMorePage(count: number, size: number): boolean;
+/** The project a tree root path names, or null on the site root. */
+export declare function projectOfPath(path: string): number | null;
+/**
+ * What a search does with the query it now holds: empty the list, ask at once, or
+ * ask once the pause has elapsed.
+ *
+ * A widget that browses rather than matching reads on an empty query too, which is
+ * what `readsEmpty` says; nothing is debounced there, because no one is typing.
+ */
+export type QueryPlan = 'clear' | 'now' | 'debounce';
+export declare function queryPlan(query: string, readsEmpty: boolean): QueryPlan;
+export interface SearchViewState {
+  /** What the failed read said, or null. */
+  error: string | null;
+  loading: boolean;
+  /** Rows on show. */
+  count: number;
+  /** An empty list is the empty line only once something has been asked for. */
+  asked: boolean;
+}
+/**
+ * What a search list draws. The skeletons stand for a first page only: a page on the
+ * way under rows already on screen leaves those rows where they are.
+ */
+export declare function searchView(state: SearchViewState): WidgetState;
+/**
+ * The ticket an answer has to still hold to be written.
+ *
+ * A search cancels by taking the next ticket: whatever is in flight then holds a
+ * stale one and is dropped rather than landing over the query that replaced it.
+ */
+export interface RequestGate {
+  /** Take the next ticket. Every earlier one is stale from here on. */
+  next: () => number;
+  /** Drop whatever is in flight without starting anything. */
+  cancel: () => void;
+  /** True while `ticket` is the one that may write. */
+  holds: (ticket: number) => boolean;
+}
+export declare function requestGate(): RequestGate;
+/**
+ * How long a press stays answerable for what it set off. A press that replaces the
+ * rows under it does so while the event it started is still unfolding, and each
+ * framework flushes that on its own schedule, so the mark outlives the press by a
+ * little and no longer.
+ */
+export declare const PRESS_WINDOW_MS = 400;
+/**
+ * The press a replacement is the consequence of.
+ *
+ * A press inside a list that replaces the rows under it leaves the caret on a row
+ * that is gone. `mark` is the press; `takes` answers true once, to whatever the
+ * press led to inside the window.
+ */
+export interface PressGate {
+  /** A press landed inside the list. */
+  mark: () => void;
+  /** True when a press is still answerable, and spends it. */
+  takes: () => boolean;
+}
+export declare function pressGate(windowMs?: number): PressGate;
+/** The types to search, as the map `_text_search` takes: bare names carry no filter. */
+export declare function searchTypeMap(types: string[] | Record<string, WireCondition[] | null>): Record<string, WireCondition[] | null>;
+/**
+ * A list of what was picked before, newest first: the new entry leads, the one it
+ * repeats is dropped, and the list is cut to `limit`.
+ */
+export declare function prependRecent<T>(recents: readonly T[], picked: T, limit: number, keyOf: (item: T) => string): T[];
+/**
+ * The rows a tree path runs through, root first.
+ *
+ * A path is read left to right. A capitalised segment names the type the level
+ * below is drawn from; `<Type>/<id>` and `<field>/<Type>/<id>` are a row of that
+ * type, and a bare `id/<n>` is a row of the type the last folder named. The path
+ * runs through field names such as `sg_sequence`, because the tree follows the
+ * site's own navigation configuration rather than a fixed hierarchy
+ * (post_hierarchy_search).
+ */
+export declare function pathRefs(path: string | string[]): EntityRef[];
+/** The breadcrumb a hierarchy row shows: the path rendered for a person, then the row. */
+export declare function breadcrumb(path: HierarchyPath): string[];
+//#endregion
+//#region src/query.d.ts
+export interface QueryCacheOptions {
+  /**
+   * How long a resolved value stays fresh, in milliseconds. Default 30000.
+   * `Infinity` keeps values until `invalidate()`; `0` disables caching and
+   * leaves only the in-flight deduping.
+   */
+  ttlMs?: number;
+}
+export interface QueryCache extends SgClient {
+  /**
+   * Forget cached values. With no argument, all of them. With a prefix, every
+   * key that starts with it; a key is `<method>:<json args>`, so `'fields'`
+   * drops every schema read and `'fields:["Shot"'` drops only Shot's.
+   */
+  invalidate(prefix?: string): void;
+}
+export declare function createQueryCache(client: SgClient, options?: QueryCacheOptions): QueryCache;
+//#endregion
+//#region src/edit.d.ts
+/** A parsed value, or the reason the input was refused. */
+export type ParseResult<T> = {
+  value: T;
+} | {
+  error: string;
+};
+export declare function isParseError<T>(result: ParseResult<T>): result is {
+  error: string;
+};
+/**
+ * The column behind `number`, `percent`, `duration` and `timecode` is a signed
+ * 32-bit integer; one past either end is a 400 (field_types/number, percent,
+ * timecode).
+ */
+export declare const INT32_MIN = -2147483648;
+export declare const INT32_MAX = 2147483647;
+/** Decimals a `float` keeps. Rounding happens on write, at 200 and without warning (field_types/float). */
+export declare const FLOAT_PRECISION = 6;
+/**
+ * Free text. Both ends are stripped on write and an empty string is stored as
+ * null, so there is no "set but blank" state to preserve (field_types/text).
+ */
+export declare function parseTextInput(raw: string): ParseResult<string | null>;
+export interface IntegerParseOptions {
+  min?: number;
+  max?: number;
+}
+/**
+ * A whole number for `number`, `percent` and `timecode`. A decimal is refused
+ * rather than rounded, matching the API: `number` and `percent` 400 on a Float
+ * and `timecode` takes `[Integer, NilClass]` alone (field_types/number, percent,
+ * timecode). Empty input clears the field.
+ */
+export declare function parseInteger(raw: string, options?: IntegerParseOptions): ParseResult<number | null>;
+export interface FloatParseOptions {
+  /** Decimals to keep. Defaults to the six the store itself keeps (field_types/float). */
+  precision?: number;
+}
+/**
+ * A decimal for `float`. The store rounds to six decimals on write, so the parse
+ * rounds too and the value a caller emits is the value that comes back
+ * (field_types/float). Empty input clears the field.
+ */
+export declare function parseFloatInput(raw: string, options?: FloatParseOptions): ParseResult<number | null>;
+/**
+ * The wire form of a float. An Integer is refused on write and inside a filter,
+ * so a whole value has to carry a decimal point; JSON has no way to write one, so
+ * the value goes as the numeric string the API also accepts (field_types/float).
+ */
+export declare function toApiFloat(value: number | null): string | null;
+export interface DurationParseOptions {
+  /** The site's `hours_per_day` from `GET /preferences`. Without it the `d` unit is refused. */
+  hoursPerDay?: number;
+}
+/**
+ * A duration, in whole minutes.
+ *
+ * The stored integer is minutes and no schema names the unit, so the accepted
+ * spellings are the client's own: a bare number is minutes, `1h 30m` and `1.5h`
+ * are hours, and `1:30` is hours and minutes. `2d` needs `hours_per_day`, which
+ * only the site's preferences hold, and is refused without it. The API itself
+ * takes only something that parses as a number, so `"1h 30m"` never leaves this
+ * function (field_types/duration).
+ */
+export declare function parseDurationInput(raw: string, options?: DurationParseOptions): ParseResult<number | null>;
+export interface TimecodeParseOptions {
+  /** Frames a second, without which the frame digits of a typed timecode are refused. */
+  frameRate?: number;
+}
+/**
+ * A timecode, in milliseconds.
+ *
+ * The stored integer is milliseconds: `1000` renders as one whole second in the
+ * server's own `_summarize` grouping. The field rejects every timecode string,
+ * including the drop-frame spelling, so the conversion is the client's
+ * (field_types/timecode). Empty input clears the field.
+ */
+export declare function parseTimecodeInput(raw: string, options?: TimecodeParseOptions): ParseResult<number | null>;
+/** The bounds and the amount one step moves, for one numeric data type. */
+export interface NumberSteps {
+  step: number;
+  min?: number;
+  max?: number;
+}
+export interface NumberStepsOptions {
+  /** Frames per second. A timecode steps one frame when it is known, one second when it is not. */
+  frameRate?: number;
+}
+/**
+ * The step and the bounds a numeric data type takes when the caller names none.
+ *
+ * A percent runs 0 to 100 because that is the scale it is read on; the column
+ * itself clamps nothing, so a caller with out-of-scale data widens the bounds
+ * (field_types/percent). A duration steps a quarter of an hour, a timecode one
+ * frame, and a float a tenth.
+ */
+export declare function numberSteps(dataType: string, options?: NumberStepsOptions): NumberSteps;
+export interface StepOptions {
+  step: number;
+  /** Steps taken at once: ten with Shift, a hundred with Page Up and Page Down. */
+  multiplier?: number;
+  min?: number;
+  max?: number;
+}
+/**
+ * Where a step lands: rounded to the decimals the step and the starting value
+ * carry, then clamped. The rounding is what keeps a tenth-sized step off
+ * `0.30000000000000004`.
+ */
+export declare function settleStep(from: number | null, to: number, options: StepOptions): number;
+/** The value one step away. An empty field lands on zero first, then steps. */
+export declare function stepNumber(from: number | null, direction: 1 | -1, options: StepOptions): number;
+export interface NumberInputFormat {
+  locale?: string;
+  /** Exactly this many decimals, zeros kept. */
+  decimals?: number;
+}
+/** A number written the way the locale writes it, for putting a stored value back in an input. */
+export declare function formatNumberInput(value: number, options?: NumberInputFormat): string;
+/**
+ * The digits behind a locale-formatted number: spacing and group marks dropped,
+ * the decimal mark turned into a point, so the parsers above read back what the
+ * formatter wrote. A comma is a group mark in every locale that does not spell
+ * its decimal with one.
+ */
+export declare function unformatNumberInput(raw: string, locale?: string): string;
+/**
+ * What the six numeric data types need beyond the type's own name: the site
+ * preferences a duration and a timecode read in, the decimals a float keeps, the
+ * bounds an integer is held to, and the locale a plain number is written in.
+ */
+export interface NumberShape {
+  /** The site's `hours_per_day` from `GET /preferences`, for the `d` unit (field_types/duration). */
+  hoursPerDay?: number;
+  /** Frames per second, for the `HH:MM:SS:FF` form and the one-frame step (field_types/timecode). */
+  frameRate?: number;
+  /** Decimals kept on a float. The store itself keeps six (field_types/float). */
+  precision?: number;
+  min?: number;
+  max?: number;
+  /** Locale the value is written in. Defaults to the runtime's. */
+  locale?: string;
+}
+/** The stored value as the string an input shows. Each type round-trips through its own parse. */
+export declare function numberDraft(value: unknown, dataType: string, shape?: NumberShape): string;
+/** What the numeric parses read: the locale's group and decimal marks are undone first. */
+export declare function numberDigits(raw: string, dataType: string, shape?: NumberShape): string;
+/** One numeric input, through the parse its data type calls for. */
+export declare function parseNumberInput(raw: string, dataType: string, shape?: NumberShape): ParseResult<number | null>;
+/**
+ * The wire value. A `float` goes as a decimal string because an Integer is
+ * refused on write and JSON cannot spell `2.0`; every other type is a bare
+ * number (field_types/float, number, percent, duration, timecode).
+ */
+export declare function numberWire(parsed: number | null, dataType: string): number | string | null;
+/** The stored value as the number the steppers and the spinbutton role work on. */
+export declare function storedNumber(value: number | string | null | undefined): number | null;
+/**
+ * A calendar date as `YYYY-MM-DD`, with no time and no zone. The API validates
+ * the date rather than only parsing it, and refuses every timestamp
+ * (field_types/date). Empty input clears the field.
+ */
+export declare function toApiDate(raw: string): ParseResult<string | null>;
+/** A calendar day, as the three numbers a calendar widget is built from. */
+export interface IsoDayParts {
+  year: number;
+  month: number;
+  day: number;
+}
+/**
+ * `YYYY-MM-DD` as its three numbers, or null when the string is not one. The shape
+ * a calendar takes differs per framework, so only the split is shared.
+ */
+export declare function isoDayParts(value: string | null | undefined): IsoDayParts | null;
+/** The three numbers back as `YYYY-MM-DD`, zero-padded. */
+export declare function isoDay(parts: IsoDayParts): string;
+export interface DateTimeOptions {
+  /** IANA zone the typed wall-clock time is read in. Defaults to the runtime's. */
+  timeZone?: string;
+}
+/**
+ * A local wall-clock date and time as the UTC `YYYY-MM-DDTHH:MM:SSZ` the field
+ * stores. A written offset is normalised away and a zoneless string is taken as
+ * UTC, so the conversion has to happen here or the instant is wrong
+ * (field_types/date_time). Both parts empty clears the field; a date with no time
+ * is midnight local.
+ */
+export declare function toApiDateTime(date: string, time: string, options?: DateTimeOptions): ParseResult<string | null>;
+export interface LocalDateTime {
+  /** `YYYY-MM-DD` in the given zone. */
+  date: string;
+  /** `HH:MM` in the given zone. */
+  time: string;
+  /** `HH:MM:SS` in the given zone, for a value whose seconds matter. */
+  timeWithSeconds: string;
+}
+/**
+ * The stored UTC instant as local wall-clock parts, for putting back in a date
+ * and a time input. The store is second-resolution UTC with a literal `Z`
+ * (field_types/date_time).
+ */
+export declare function fromApiDateTime(value: string | null | undefined, options?: DateTimeOptions): LocalDateTime | null;
+/** The zone a wall-clock input is read in, named for the line under a date-time field. */
+export declare function timeZoneName(timeZone?: string): string;
+/**
+ * A value is legal only if it is in `valid_values`, byte for byte: a write is
+ * case-sensitive and a trailing space is a 400, while a filter on the same string
+ * matches (field_types/list).
+ */
+export declare function isValidListValue(validValues: readonly string[] | undefined, value: string): boolean;
+/** The web-link write shape: an object holding `url`, optionally `name` (field_types/url). */
+export interface UrlWriteValue {
+  url: string;
+  name?: string;
+}
+/**
+ * A web link for a `url` field. The only accepted input is an object holding
+ * `url`: a bare string 400s, `{}` 400s, and the url itself is validated, a raw
+ * space being the one character measured to fail. With no `name` the field reads
+ * back the whole url as its name (field_types/url).
+ */
+export declare function parseUrlInput(url: string, name?: string): ParseResult<UrlWriteValue | null>;
+/**
+ * A colour as the decimal `r,g,b` the field stores, with no spaces and no `#`.
+ * Hex is rejected on write, so it is converted here; spaces inside the triple are
+ * rejected too, so they are stripped (field_types/color). The pipeline-step token
+ * passes through.
+ */
+export declare function parseColorInput(raw: string): ParseResult<string | null>;
+/** A stored `r,g,b` as `#rrggbb`, for a colour input. Null for the sentinel and for anything else. */
+export declare function colorToHex(value: string | null | undefined): string | null;
+/** The editor a data type needs. `none` means the type has no editor here. */
+export type EditorKind = 'text' | 'number' | 'checkbox' | 'date' | 'date_time' | 'list' | 'url' | 'color' | 'status_list' | 'entity' | 'multi_entity' | 'none';
+/**
+ * The editor for a data type. The read-only types and the ones REST cannot write
+ * have no editor at all (field_types/calculated, summary, pivot_column).
+ */
+export declare function editorKindFor(dataType: string): EditorKind;
+/**
+ * True when the editor for a data type reads the API, so the caller has to hand it
+ * a context. A status picker reads the schema and the Status table; an entity
+ * picker searches.
+ */
+export declare function editorNeedsContext(dataType: string): boolean;
+/** True when a data type can be edited by one of these widgets. */
+export declare function isEditableType(dataType: string): boolean;
+/** Where a cell's editor opens: in the cell, or in a popover anchored to it. */
+export type EditorPlacement = 'inline' | 'popover';
+/**
+ * Where the editor for a data type opens when the caller names no placement.
+ * Every editor takes the room a popover has; a checkbox is one press and stays in
+ * the cell.
+ */
+export declare function editorPlacementFor(dataType: string): EditorPlacement;
+//#endregion
+//#region src/schema-service.d.ts
+export interface SchemaServiceOptions {
+  /** How long a schema read stays fresh. Ignored when a `QueryCache` is passed in. Default one hour. */
+  ttlMs?: number;
+}
+/** One step of a resolved dotted path. */
+export interface PathSegment {
+  /** Type this segment was read on. */
+  entityType: string;
+  /** Programmatic field name. */
+  name: string;
+  displayName: string;
+  dataType: string;
+  /** For a link that the path continues through: the type the next segment reads on. */
+  through?: string;
+  field: FieldSchema;
+}
+export interface SchemaService {
+  /** Enabled types with their display names. */
+  entityTypes(): Promise<EntityTypeInfo[]>;
+  /** Every field of a type, at site scope. */
+  fields(entityType: string): Promise<Record<string, FieldSchema>>;
+  field(entityType: string, name: string): Promise<FieldSchema | undefined>;
+  /** Codes the project hides on a list or status field. */
+  hiddenValues(entityType: string, field: string, projectId: number): Promise<string[]>;
+  /**
+   * Statuses a picker may offer. Without `projectId` the site vocabulary, which hides nothing.
+   * `field` names a list or status field other than the type's own status field.
+   */
+  statusOptions(entityType: string, projectId?: number, field?: string): Promise<StatusOption[]>;
+  /** Statuses usable in every one of the projects. */
+  statusOptionsForProjects(entityType: string, projectIds: number[], field?: string): Promise<StatusOption[]>;
+  /** The type's status field, or its conventional name when the type has none. */
+  statusField(entityType: string): Promise<FieldSchema | string>;
+  /** Walk `entity.Shot.code` into its segments. Throws naming the whole path when a segment does not resolve. */
+  resolvePath(rootType: string, dottedPath: string): Promise<PathSegment[]>;
+  invalidate(): void;
+}
+export declare function createSchemaService(client: SgClient | QueryCache, options?: SchemaServiceOptions): SchemaService;
+//#endregion
+//#region src/collection.d.ts
+/** One sort key. Serialised as `path` or `-path` (026_result_order). */
+export interface SortSpec {
+  path: string;
+  descending: boolean;
+}
+/** A filter as the caller holds it: the editor's tree, the wire group, or nothing. */
+export type SourceFilters = FilterNode | WireGroup | null;
+export type SourceStatus = 'idle' | 'loading' | 'loadingMore' | 'ready' | 'error';
+/** `pages` shows one page at a time; `infinite` appends page after page. */
+export type SourceMode = 'pages' | 'infinite';
+export interface EntitySourceOptions {
+  client: SgClient;
+  entityType: string;
+  /** Paths to read, plain or dotted. `id` is always read. */
+  fields: string[];
+  filters?: SourceFilters;
+  sort?: SortSpec[];
+  /** Rows per request. Default 50. */
+  pageSize?: number;
+  /** Default `infinite`. */
+  mode?: SourceMode;
+  /** The page `pages` mode opens on. Default 1. */
+  page?: number;
+}
+/** Everything a view renders. A new object on every change, so identity is the signal. */
+export interface EntitySourceState {
+  rows: EntityRow[];
+  status: SourceStatus;
+  error: Error | null;
+  /** True when another page exists. */
+  hasMore: boolean;
+  /** The total the last `count()` answered. Null until one is asked for, and null when the site did not answer it. */
+  total: number | null;
+  filters: WireGroup | null;
+  sort: SortSpec[];
+  mode: SourceMode;
+  /** 1-based page number of the rows on screen. 1 in infinite mode. */
+  page: number;
+  pageSize: number;
+}
+export interface EntitySource {
+  readonly entityType: string;
+  readonly fields: readonly string[];
+  readonly rows: EntityRow[];
+  readonly status: SourceStatus;
+  readonly error: Error | null;
+  readonly hasMore: boolean;
+  readonly filters: WireGroup | null;
+  readonly sort: SortSpec[];
+  readonly mode: SourceMode;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly total: number | null;
+  /** Read the first page, discarding anything already loaded, and count the set in `pages` mode. */
+  load(): Promise<void>;
+  /**
+   * Append the next page. A no-op in `pages` mode, while another read is in flight,
+   * or when there is no more. Calling it again is what retries a page that failed.
+   */
+  loadMore(): Promise<void>;
+  /** Read every page already shown again, keeping the row count. */
+  refresh(): Promise<void>;
+  setFilters(filters: SourceFilters): Promise<void>;
+  setSort(sort: SortSpec[]): Promise<void>;
+  /** Show one page of the set. `pages` mode only. */
+  setPage(page: number): Promise<void>;
+  /** Walk the set a page at a time, or append page after page. Opens at the first page. */
+  setMode(mode: SourceMode): Promise<void>;
+  /** Change the rows per page and open at the first one. */
+  setPageSize(size: number): Promise<void>;
+  /** Total rows the filter matches, through `_summarize` (020_summarize). Null when the site did not answer the key. */
+  count(): Promise<number | null>;
+  /** Write the named fields of one row and put the re-read row back in place. */
+  updateRow(ref: EntityRef, patch: Record<string, unknown>): Promise<EntityRow>;
+  /**
+   * Read these rows again with the source's own projection and swap them in place.
+   * A row the site no longer answers (retired, or moved out of reach) leaves the list.
+   * The filter is not applied, as on `updateRow`: a row that moved out of the filter
+   * still comes back so the view can show what changed. Ids not on screen are ignored.
+   * Neither status nor order changes, so nothing dims and nothing jumps.
+   */
+  rereadRows(ids: readonly number[]): Promise<void>;
+  /** The current state object, stable between changes. */
+  snapshot(): EntitySourceState;
+  subscribe(listener: () => void): () => void;
+}
+/** `Type:id`, the key a list keys rows on. */
+export declare function rowKey(row: EntityRow | EntityRef): string;
+/**
+ * The value at a path on a row. A dotted path comes back flat under its literal
+ * key in `attributes`; a plain entity field comes back under `relationships`
+ * (003_query, endpoints/post_entity_type_search).
+ */
+export declare function cellValue(row: EntityRow, path: string): unknown;
+/** Sort keys as the API's `sort` body value: comma separated, `-` per key (026_result_order). */
+export declare function serializeSort(sort: readonly SortSpec[]): string | undefined;
+/** A filter in the one shape a read carries, whichever spelling the caller holds. */
+export declare function toWireGroup(filters: SourceFilters): WireGroup | null;
+export declare function createEntitySource(options: EntitySourceOptions): EntitySource;
+/** The numbers a collection's footer draws, in either mode. */
+export interface PageRange {
+  mode: SourceMode;
+  page: number;
+  pageSize: number;
+  /** 1-based index of the first row on screen. 0 when there are none. */
+  from: number;
+  /** 1-based index of the last row on screen. 0 when there are none. */
+  to: number;
+  total: number | null;
+  /** Pages the total implies. Null when nothing counted the set. */
+  pageCount: number | null;
+  hasPrevious: boolean;
+  hasNext: boolean;
+  /** `1 to 25 of 320`, and `1 to 25` when nothing counted the set. */
+  rangeLabel: string;
+  /** `25 loaded`, and `25 of 320 loaded` once the set is counted. */
+  loadedLabel: string;
+}
+/**
+ * The footer's numbers for one state.
+ *
+ * A read answers no total of its own, so a range reads "of N" only once
+ * `_summarize` has counted the set. In `pages` mode a next page exists because
+ * that count says so, or because the page that came back was full; in
+ * `infinite` mode the source has already walked the set, so its own answer
+ * stands (006_pagination, 020_summarize).
+ */
+export declare function describePaging(state: EntitySourceState): PageRange;
+/** A column as a caller writes it: a path, and anything the schema should not decide. */
+export interface ColumnSpec {
+  /** Plain or dotted path, e.g. `entity.Shot.code`. */
+  path: string;
+  header?: string;
+  dataType?: string;
+  /** Starting width in pixels. */
+  width?: number;
+  editable?: boolean;
+  align?: 'left' | 'right';
+  field?: FieldSchema | null;
+  /** Override the sortability the data type implies. */
+  sortable?: boolean;
+  /** Override where this column's editor opens. */
+  editorPlacement?: EditorPlacement;
+}
+/** A column with every question answered, which is what a collection widget takes. */
+export interface CollectionColumn {
+  path: string;
+  header: string;
+  dataType: string;
+  width?: number;
+  /** True when a cell may open an editor. A projection is never writable. */
+  editable: boolean;
+  align: 'left' | 'right';
+  /** False for a type the server sorts as a silent no-op or a 400 (026_result_order). */
+  sortable: boolean;
+  /** The schema of the field the path lands on, for a status label out of `display_values`. */
+  field: FieldSchema | null;
+  /** Where this column's editor opens. Absent leaves it to the data type. */
+  editorPlacement?: EditorPlacement;
+}
+/**
+ * Fill in headers, data types and editability from the schema.
+ *
+ * The header of a dotted path is the display name of the field it lands on. A
+ * projection is never writable: a write names one field of one row
+ * (put_entity_type_id), so only a plain path can open an editor.
+ */
+export declare function resolveColumns(schema: SchemaService, entityType: string, columns: ReadonlyArray<string | ColumnSpec>): Promise<CollectionColumn[]>;
+/**
+ * A column from a bare path, for a row-anatomy prop that takes either.
+ *
+ * Nothing but the path is known, so the value renders as text and the column is
+ * neither sortable nor editable. A caller that wants the field's own type passes
+ * the resolved column from `resolveColumns` instead.
+ */
+export declare function toColumn(spec: string | CollectionColumn): CollectionColumn;
+/**
+ * Contiguous runs of rows sharing a value at `path`.
+ *
+ * Grouping a paged read is only honest over an order the server produced, so a
+ * caller sorts on the same path and this walks the runs. A group whose rows
+ * continue on the next page grows when that page arrives.
+ */
+export interface RowGroup {
+  /** The raw value the run shares. */
+  value: unknown;
+  rows: EntityRow[];
+}
+/**
+ * The value a row groups under, derived rather than read from a column.
+ *
+ * For a group a column cannot name: a multi-entity field no site sorts on, or a
+ * value that comes from one field on one type and another on another. The order
+ * the runs are walked in is the caller's, so a caller passing this sorts the
+ * source itself.
+ */
+export type GroupKeyFn = (row: EntityRow) => unknown;
+/** What the rows are grouped on: a path they are sorted by, or a key derived from each row. */
+export type GroupBy = string | GroupKeyFn;
+export declare function groupRows(rows: readonly EntityRow[], by: GroupBy): RowGroup[];
+/**
+ * The text a group key reads as when there is no column to render it by.
+ *
+ * A row reads as its display name, anything else as its own text, and a key that
+ * is nothing at all as the empty string.
+ */
+export declare function groupKeyText(value: unknown): string;
+//#endregion
+//#region src/status-service.d.ts
+export interface StatusService {
+  /** Every Status on the site. Fetched once. */
+  all(): Promise<StatusRecord[]>;
+  /** The table indexed by code. The first row wins when a code repeats. */
+  byCode(): Promise<ReadonlyMap<string, StatusRecord>>;
+  /** One status, or `undefined` for a code with no Status behind it, such as a plain `list` value. */
+  record(code: string): Promise<StatusRecord | undefined>;
+  invalidate(): void;
+}
+export declare function createStatusService(client: SgClient | QueryCache): StatusService;
+//#endregion
+//#region src/row.d.ts
+/**
+ * A field named by a row-anatomy prop: a bare path, or a column already resolved
+ * from the schema so the value renders by its data type. One type everywhere.
+ */
+export type FieldSpec = string | CollectionColumn;
+/** The path a field spec names. Empty when nothing is named. */
+export declare function pathOf(spec: FieldSpec | null | undefined): string;
+/** The six props of rule 9, as a widget holds them. */
+export interface RowAnatomy {
+  /** `false`, or the field name holding the image URL. */
+  thumbnail?: string | false | undefined;
+  /** The field shown as the main label. The display-name chain answers it when absent. */
+  labelField?: string | undefined;
+  /** The muted line under the label. */
+  subLabelField?: FieldSpec | null | undefined;
+  /** The right-aligned column, rendered by data type. */
+  secondaryField?: FieldSpec | null | undefined;
+  /** Show programmatic names beside display names. */
+  showCode?: boolean | undefined;
+  /** Extra fields to request, so a caller's own sub-label or secondary can read them. */
+  fields?: string[] | undefined;
+}
+/** The field a row's thumbnail is read from, or null when there is none. */
+export declare function thumbnailField(anatomy: RowAnatomy): string | null;
+/**
+ * Every field a row anatomy has to read, `base` first and duplicates dropped.
+ *
+ * An unknown field name is a silent 200 with the key absent (003_query), so asking
+ * for a path a type does not carry costs nothing.
+ */
+export declare function rowFields(anatomy: RowAnatomy, base?: readonly string[]): string[];
+/** The picture a row shows, or null when the field is off or holds no URL. */
+export declare function rowThumbnail(values: Record<string, unknown>, anatomy: RowAnatomy): string | null;
+/** The site's Status rows by code, as a widget holds them (probe 010). */
+export type StatusTable = Readonly<Record<string, StatusRecord>>;
+/** What the sub-label reads its value by. Both parts are optional: without them the value stands as written. */
+export interface SubLabelSource {
+  /** The data type of the field the sub-label names. */
+  dataType?: string | undefined;
+  /** The status table, so a status code reads the name the site gives it. */
+  statuses?: StatusTable | null | undefined;
+}
+/**
+ * The muted line under the label, as text. Empty when nothing names it or the value is blank.
+ *
+ * The value reads by its data type, as the secondary column does: a status is stored as a
+ * bare code and the name a reader knows it by lives on the site's Status row, keyed by code
+ * and site-wide (probe 010, field_types/status_list); an entity keeps its name, a list of
+ * them joins their names, and a date stays the string the API sent (field_types/date). A
+ * caller with no schema hands in no type and gets the value as written.
+ */
+export declare function rowSubLabel(values: Record<string, unknown>, anatomy: RowAnatomy, source?: SubLabelSource): string;
+/**
+ * The data type the sub-label reads by: the resolved column's own, the schema's when
+ * one was read, and nothing otherwise, which leaves the value as written.
+ */
+export declare function subLabelType(anatomy: RowAnatomy, fieldType?: string | undefined): string;
+/** The schemas a row's sub-label and secondary draw with, and the status table when either needs one. */
+export interface RowFieldPlan {
+  subLabel: FieldSchema | null;
+  secondary: FieldSchema | null;
+  /** `Status` rows by code, read once and only when a status is on show (probe 010). */
+  statuses: StatusTable | null;
+}
+/**
+ * The two fields a row resolves, in one pass and with one status read.
+ *
+ * A resolved column already carries its type, so only a bare path costs a schema
+ * read, and that read is the service's cached one.
+ */
+export declare function resolveRowFields(schema: SchemaService, statusTable: StatusService, type: string, anatomy: RowAnatomy): Promise<RowFieldPlan>;
+/** The programmatic name beside the label, when it says something the label does not. */
+export declare function rowCode(values: Record<string, unknown>, label: string, showCode?: boolean): string;
+/**
+ * The raw value the secondary column draws. `id` is on the row itself rather than
+ * among the attributes a read returns, so it is answered from the reference.
+ */
+export declare function rowSecondary(row: {
+  id: number;
+  values: Record<string, unknown>;
+}, anatomy: RowAnatomy): unknown;
+/**
+ * The data type the secondary renders as: the resolved column's own, the schema's
+ * when one was read, and `number` for `id`, which is a code rather than a name.
+ */
+export declare function secondaryType(anatomy: RowAnatomy, fieldType?: string | undefined): string;
+//#endregion
+//#region src/picker.d.ts
+/** One searched row, flattened for display. */
+export interface PickerRow {
+  type: string;
+  id: number;
+  /** The label, from `labelField` or the display-name chain, never empty. */
+  name: string;
+  /**
+   * Attributes and relationships in one map. A dotted path is a literal key with
+   * dots in it, not a nested object (003_query), and a relationship is unwrapped
+   * to its `data` so a caller reads `{type, id, name}` rather than an envelope.
+   */
+  values: Record<string, unknown>;
+}
+/**
+ * The key a picker holds a row under, everywhere. A numeric id alone collides:
+ * a Shot and an Asset on one site share ids freely, and a picker may search both.
+ */
+export declare function entityKey(ref: {
+  type: string;
+  id: number;
+}): string;
+/** `Type 123`, the label a row falls back to when nothing names it. */
+export declare function placeholderName(ref: {
+  type: string;
+  id: number;
+}): string;
+/** True when a reference carries no usable name and needs a read to become a row. */
+export declare function isBareRef(ref: EntityRef): boolean;
+export declare function toRef(row: PickerRow): EntityRef;
+/** Flatten a `_search` row. `labelField` wins over the display-name chain when set. */
+export declare function flattenRow(row: EntityRow, labelField?: string): PickerRow;
+/** One field a query is matched against, and how. */
+export interface SearchField {
+  path: string;
+  /** Default `contains`. `starts_with` keeps a shared tail, such as an email domain, out of the match. */
+  operator?: 'contains' | 'starts_with' | 'ends_with' | 'is';
+}
+/** A field name, or a field name with the operator it is matched with. */
+export type SearchFieldSpec = string | SearchField;
+/**
+ * The filter a typed query becomes: every word must match, each anywhere in the
+ * field, and a word may sit in any one of `fields`. So "pub an" finds
+ * "Published Anna" and a login search finds a person by either half of a name.
+ *
+ * An empty query, or no fields, gives an empty group, which matches every row:
+ * `"conditions": []` is 200 and unscoped (030_complex_filters). `contains` and
+ * `starts_with` both work on text fields and through dotted paths, so a field may
+ * be `entity.Shot.code` (017_filter_operators).
+ */
+export declare function nameSearchFilter(query: string, fields: readonly SearchFieldSpec[]): FilterGroup;
+/**
+ * The extra fields a person search matches, for the query as typed.
+ *
+ * The email is always searched, because it is what a person is known by on a site,
+ * but only on its local part until the query holds an `@`: every address shares one
+ * domain, so `contains` on "le" matches `example.studio` and with it the whole site.
+ * A login never holds whitespace, so it is dropped once the query does. The
+ * display-name chain is searched either way.
+ */
+export declare function userSearchFields(query: string): SearchFieldSpec[];
+/** Accept either the editor tree or the wire shape wherever a caller supplies a filter. */
+export declare function asFilterGroup(filter: FilterGroup | WireGroup | null | undefined): FilterGroup | null;
+/**
+ * Drop every condition whose root field the type does not have, and every group
+ * left empty by that. A picker across several types shares one pre-filter, and a
+ * filter naming a field the type lacks is a 400 rather than a silent no-op
+ * (017_filter_operators), so the condition is dropped on the types it cannot
+ * apply to. Dropping widens a result set; it never narrows one wrongly.
+ */
+export declare function pruneFilterToFields(node: FilterNode, fieldNames: ReadonlySet<string>): FilterNode | null;
+/** One `and` of the parts that are not empty. Blank parts are dropped, not sent. */
+export declare function mergeFilters(...parts: Array<FilterNode | null | undefined>): FilterGroup;
+/** What a caller narrows a person search with. */
+export interface UserPickerOptions {
+  /** Search script accounts alongside people. */
+  includeApiUsers?: boolean;
+  /** Offer people whose status is `dis`. */
+  includeInactive?: boolean;
+}
+/** Login and email are searched and shown, so they have to be read (entity_types/HumanUser). */
+export declare const USER_PICKER_FIELDS: string[];
+/** People and script accounts, in that order. */
+export declare function userPickerTypes(includeApiUsers: boolean): string[];
+/**
+ * The active condition, unless inactive people are wanted. `sg_status_list` on
+ * HumanUser is two codes, `act` and `dis`, and `act` is the default
+ * (entity_types/HumanUser). ApiUser has no status field, so a picker drops the
+ * condition on that type rather than sending a filter that would 400.
+ */
+export declare function userPickerFilters(includeInactive: boolean, extra: FilterGroup | WireGroup | null | undefined): FilterGroup;
+/** `API user` for a script account, the email for a person, nothing without one. */
+export declare function userPickerSubLabel(row: PickerRow): string;
+/** The caller's own search fields, on top of the ones a person is searched by. */
+export declare function userPickerSearchFields(extra: SearchFieldSpec[] | ((query: string) => SearchFieldSpec[])): (query: string) => SearchFieldSpec[];
+/** What a caller narrows a project search with. */
+export interface ProjectPickerOptions {
+  /** Offer projects whose `archived` checkbox is set. */
+  includeArchived?: boolean;
+}
+/** Project's status field is `sg_status`, a plain list, not `sg_status_list`. */
+export declare const PROJECT_PICKER_FIELDS: string[];
+/**
+ * Archived projects are hidden unless asked for. `sg_status` is not a liveness
+ * filter and is null on most projects; `archived`, `is_template` and `is_demo`
+ * are the discriminators (018_project_listing).
+ */
+export declare function projectPickerFilters(includeArchived: boolean, extra: FilterGroup | WireGroup | null | undefined): FilterGroup;
+/**
+ * Clause 8 of the picker contract: the clear control follows `clearable`, and a
+ * mandatory field never offers one. A field whose schema the widget has not read is
+ * not mandatory as far as it knows, so the caller's answer stands.
+ */
+export declare function clearableForField(clearable: boolean | undefined, field: {
+  mandatory?: boolean;
+} | null | undefined): boolean;
+/**
+ * Search results first, then any selected row not among them. Keyboard picking
+ * lands on fresh matches, and a selected row never leaves the list, so it stays
+ * deselectable with an empty query.
+ */
+export declare function withSelectedPinned(rows: readonly PickerRow[], selected: readonly EntityRef[], known: ReadonlyMap<string, PickerRow>): PickerRow[];
+/** What a multi picker's control shows for the selection. */
+export type PickerSummary = 'chips' | 'ellipsis' | 'count';
+/** Chips `ellipsis` draws before the rest becomes `+n`, when nothing has measured the row. */
+export declare const ELLIPSIS_CHIPS = 3;
+/** How many chips a row shows, and how many it hides behind `+n`. */
+export interface ChipFit {
+  visible: number;
+  hidden: number;
+}
+/** A measured chip row: each chip's width, the room it has, and the room held back. */
+export interface ChipRow {
+  /** Chip widths in order, each carrying the gap that follows it. */
+  widths: readonly number[];
+  /** The room the chips may occupy. */
+  available: number;
+  /** Room held back for the `+n` pill, spent only when something is hidden. */
+  reserve: number;
+}
+/**
+ * How many whole chips fit `available`, taken greedily from the first.
+ *
+ * A chip is never cut: one that does not fit whole is hidden, and so is every chip
+ * after it. `reserve` is the room the `+n` pill needs, so it is subtracted only
+ * once the row overflows and the pill is drawn. Each width carries its own trailing
+ * gap, so `k` chips cost the sum of the first `k` widths whatever follows them.
+ */
+export declare function fitChips(widths: readonly number[], available: number, reserve: number): ChipFit;
+export interface SelectionSummary<T> {
+  /** The items drawn as chips, in order. Empty under `count`. */
+  shown: T[];
+  /** Items past `shown`. Drawn as `+n` beside the chips. */
+  overflow: number;
+  /** Every label, comma-joined, for the control's `title`. */
+  title: string;
+  /** `3 selected`, which is the whole control under `count`. */
+  countLabel: string;
+  /** True while the chips must stay on one line rather than wrap. */
+  oneLine: boolean;
+}
+/**
+ * What a multi picker draws for its selection.
+ *
+ * `chips` draws every chip and wraps. `ellipsis`, the default, keeps one line: as
+ * many whole chips as the measured row fits, then `+n`, with the whole list in the
+ * title. `count` draws neither and reads `3 selected`. `max` bounds the chips in
+ * either chip mode; `0` means every chip. An `ellipsis` row nothing has measured yet
+ * falls back to three chips.
+ */
+export declare function summariseSelection<T>(items: readonly T[], labelOf: (item: T) => string, options?: {
+  summary?: PickerSummary | undefined;
+  max?: number | undefined;
+  /** The measured row. `ellipsis` fits whole chips to it; the other modes ignore it. */
+  fit?: ChipRow | undefined;
+}): SelectionSummary<T>;
+export interface EntitySearchOptions {
+  /** A cached client. Every read goes through it, so repeated queries cost one request. */
+  client: SgClient;
+  /** Shared schema service. One is built over the client when absent. */
+  schema?: SchemaService;
+  entityTypes: string[];
+  /** Field holding the row label. Defaults to the display-name chain. */
+  labelField?: string | undefined;
+  /**
+   * Extra fields the query is matched against, on top of the display-name chain.
+   * A function is called with the query, so a field is searched only when the query
+   * suits it, and a field may name the operator it is matched with.
+   */
+  searchFields?: SearchFieldSpec[] | ((query: string) => SearchFieldSpec[]) | undefined;
+  /** Field shown right-aligned, rendered by its data type. Nothing is shown without it. */
+  secondaryField?: FieldSpec | null | undefined;
+  /** Field shown under the label. Defaults to the entity type when several are searched. */
+  subLabelField?: FieldSpec | null | undefined;
+  /** Field holding the thumbnail URL. `false` hides thumbnails. */
+  thumbnail?: string | false | undefined;
+  /** Extra fields to request, so a caller's own sub-label or secondary can be read. */
+  fields?: string[] | undefined;
+  /** Caller pre-filter, merged into every request with `and`. */
+  filters?: FilterGroup | WireGroup | null | undefined;
+  /** Sugar for a project condition. Skipped on a type that has no project link. */
+  projectId?: number | undefined;
+  /** Rows to keep out of the results. Pushed into the server filter, per type. */
+  exclude?: EntityRef[] | undefined;
+  minQueryLength?: number | undefined;
+  pageSize?: number | undefined;
+  debounceMs?: number | undefined;
+  onError?: ((error: Error) => void) | undefined;
+}
+export interface EntitySearchState {
+  /** The query the current rows answer. Highlighting reads this, not the input. */
+  query: string;
+  loading: boolean;
+  error: Error | null;
+  rows: PickerRow[];
+  /** True when another page exists. From a full page, never from `links.next` (006_pagination). */
+  hasMore: boolean;
+  /** True while the query is shorter than the minimum, so the rows answer no query. */
+  tooShort: boolean;
+}
+export interface EntitySearch {
+  readonly state: EntitySearchState;
+  /** Rows seen or hydrated so far, by `Type:id`. */
+  readonly known: ReadonlyMap<string, PickerRow>;
+  subscribe(listener: (state: EntitySearchState) => void): () => void;
+  /** Set the typed query. Debounced; a run already in flight is abandoned. */
+  setQuery(query: string): void;
+  /** Append the next page of the current query. */
+  loadMore(): void;
+  /** Read the rows behind bare references, one batched request per type. */
+  hydrate(refs: readonly EntityRef[]): void;
+  /** Remember a row so a selection can be shown before it is searched again. */
+  remember(rows: readonly PickerRow[]): void;
+  /** Apply changed props. Resets the results when the request would change. */
+  update(options: Partial<EntitySearchOptions>): void;
+  dispose(): void;
+}
+export declare function createEntitySearch(options: EntitySearchOptions): EntitySearch;
+//#endregion
+//#region src/picker-keys.d.ts
+/**
+ * The keyboard model every picker shares.
+ *
+ * A picker is a token field: chips, a caret and a list. The chips take the caret one at
+ * a time, and Backspace, the arrows and Escape mean the same thing in all of them, so
+ * the rules live here and the two frameworks cannot drift.
+ */
+/** What a keydown asks the control to do. */
+export type PickerKeyIntent =
+/** The key is not the control's business. */
+{
+  kind: 'nothing';
+} |
+/** Close the popup, clear the query and give the caret back to the input. */
+{
+  kind: 'dismiss';
+} |
+/** Put the caret on the chip at `index`, or back in the input when `null`. */
+{
+  kind: 'focus';
+  index: number | null;
+} |
+/** Remove the chip at `index`, then take `then`: a chip, or the input when `null`. */
+{
+  kind: 'remove';
+  index: number;
+  then: number | null;
+} |
+/** Give the caret back to the input and write `key` into the query. */
+{
+  kind: 'type';
+  key: string;
+} |
+/** Give the caret back to the input and show the list. */
+{
+  kind: 'open';
+} |
+/** Keep the list's highlighted row in view. */
+{
+  kind: 'follow';
+};
+export interface PickerKeyState {
+  /** The popup is showing. */
+  open: boolean;
+  /** Text in the search box. */
+  query: string;
+  /** Chips in the control. A single picker counts its value as one. */
+  count: number;
+  /** Index of the chip holding the caret, or `null` while the input holds it. */
+  focused: number | null;
+  /** The control takes edits. A disabled or readonly one takes none. */
+  editable: boolean;
+  /** Several keys may be chosen at once. */
+  multiple: boolean;
+}
+/**
+ * What a keydown means to a picker.
+ *
+ * From the input, Backspace and `ArrowLeft` in an empty query reach the chips of a multi
+ * picker rather than the text, and a single picker clears its one value in a press. From
+ * a chip, the arrows walk the row, Backspace and Delete take the chip and leave the caret
+ * on its neighbour, `ArrowDown` shows the list, and anything a person would type gives
+ * the caret back to the input. Escape is the control's business only while the popup
+ * shows; a closed picker leaves the key to whatever encloses it.
+ */
+export declare function pickerKeyIntent(key: string, state: PickerKeyState): PickerKeyIntent;
+/** What a keydown asks a search box to do. */
+export type SearchKeyIntent =
+/** The key is not the search box's business. */
+{
+  kind: 'nothing';
+} |
+/** Clear the query and the rows it answered, and keep the caret where it is. */
+{
+  kind: 'clear';
+};
+export interface SearchKeyState {
+  /** Text in the search box. */
+  query: string;
+}
+/**
+ * What a keydown means to a search box. Escape is the search box's business only while
+ * the query has text; an empty one leaves the key to the shell, as a closed picker does.
+ */
+export declare function searchKeyIntent(key: string, state: SearchKeyState): SearchKeyIntent;
+/**
+ * Put the caret on one chip of a row.
+ *
+ * Every chip is taken out of the tab order, so the row is walked with the arrows and Tab
+ * still leaves the control. A chip the measured row hides takes no caret, and the input
+ * keeps it; the model still counts the chip as the one a Backspace removes.
+ */
+export declare function focusChip(row: Element | null | undefined, index: number | null): boolean;
+/**
+ * Keep the list's highlighted row in view.
+ *
+ * `nearest` moves the scroller by the least it can and leaves the page under a
+ * fixed popup where it is. Both primitives mark the row with `data-highlighted`.
+ */
+export declare function scrollHighlightedIntoView(list: Element | null | undefined): boolean;
+/**
+ * Keep the highlighted row in view for as long as the list is drawn.
+ *
+ * The primitive moves the highlight itself, and a load-more page appends rows under it,
+ * so the list follows the mark rather than the key that moved it. Returns the teardown.
+ */
+export declare function watchHighlight(list: Element | null | undefined): () => void;
+//#endregion
+//#region src/proxy-client.d.ts
+export interface ProxyClientOptions {
+  /** Where the endpoints live, e.g. `/sg` or `https://app.example.com/api/sg`. */
+  basePath: string;
+  fetch?: typeof fetch;
+  /** Extra request headers. Called per request, so a caller can rotate a CSRF or auth header. */
+  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+export declare class ProxyClient implements SgClient {
+  private readonly options;
+  private readonly base;
+  private readonly fetchFn;
+  constructor(options: ProxyClientOptions);
+  private post;
+  entityTypes(): Promise<EntityTypeInfo[]>;
+  fields(entityType: string, projectId?: number): Promise<Record<string, FieldSchema>>;
+  fieldWithProject(entityType: string, field: string, projectId: number): Promise<FieldSchema>;
+  search(entityType: string, options: SearchOptions): Promise<SearchResult>;
+  textSearch(text: string, entityTypes: Record<string, TextSearchFilter>, page?: {
+    size?: number;
+    number?: number;
+  }): Promise<TextSearchRow[]>;
+  statuses(): Promise<StatusRecord[]>;
+  create(entityType: string, body: Record<string, unknown>): Promise<EntityRow>;
+  /** The bytes cross the protocol base64-encoded; the handler runs the three calls. */
+  upload(entityType: string, id: number, file: UploadFile): Promise<UploadResult>;
+  update(entityType: string, id: number, patch: Record<string, unknown>): Promise<EntityRow>;
+  hierarchySearch(rootPath: string, entity: EntityRef): Promise<HierarchyPath[]>;
+  hierarchyExpand(path: string): Promise<HierarchyNode>;
+  summarize(entityType: string, options?: SummarizeOptions): Promise<SummarizeResult>;
+  threadContents(noteId: number, entityFields?: Record<string, string[]>): Promise<ThreadRow[]>;
+  eventLog(options?: EventLogOptions): Promise<EventLogResult>;
+  following(userId: number, options?: FollowingOptions): Promise<EntityRef[]>;
+}
+//#endregion
+//#region src/proxy-handler.d.ts
+/** The methods the protocol carries, one POST each. */
+export declare const PROXY_METHODS: readonly ['entityTypes', 'fields', 'fieldWithProject', 'search', 'textSearch', 'statuses', 'create', 'update', 'upload', 'hierarchyExpand', 'hierarchySearch', 'summarize', 'threadContents', 'eventLog', 'following'];
+export type ProxyMethod = (typeof PROXY_METHODS)[number];
+/** An error as it crosses the wire. `ProxyClient` rebuilds an `SgApiError` from it. */
+export interface ProxyError {
+  status: number;
+  message: string;
+  body: unknown;
+}
+export type ProxyBody = {
+  data: unknown;
+} | {
+  error: ProxyError;
+};
+export interface ProxyResult {
+  /** HTTP status the wrapper writes. */
+  status: number;
+  body: ProxyBody;
+}
+export type ProxyHandler = (method: string, body: unknown) => Promise<ProxyResult>;
+export declare function isProxyMethod(value: string): value is ProxyMethod;
+/**
+ * Bytes as base64. The protocol is one JSON object per call, so an upload's bytes
+ * cross it encoded and are decoded here.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(value: string): Uint8Array;
+/** Wraps a client so a host app can expose it over its own HTTP endpoints. */
+export declare function createProxyHandler(client: SgClient): ProxyHandler;
+//#endregion
+//#region src/session-auth.d.ts
+export interface SessionTokenAuthOptions {
+  /** Site root, e.g. `https://studio.shotgrid.autodesk.com`. */
+  siteUrl: string;
+  /** The launcher's `sessionToken`. A credential for the person who approved: store it where a key would be stored. */
+  sessionToken: string;
+  fetch?: typeof fetch;
+}
+/**
+ * A `token()` for `RestClientOptions`. It mints a bearer, holds it until shortly
+ * before it expires, refreshes with the refresh token, and re-mints from the
+ * session token when the refresh is refused.
+ */
+export declare function createSessionTokenAuth(options: SessionTokenAuthOptions): () => Promise<string>;
+/** Why the launcher stopped. */
+export type AppSessionFailure = 'not_found' | 'timeout';
+export declare class AppSessionError extends Error {
+  readonly reason: AppSessionFailure;
+  constructor(reason: AppSessionFailure, message: string);
+}
+export interface RequestAppSessionOptions {
+  siteUrl: string;
+  /** The name shown to the person approving. */
+  appName: string;
+  /** Any string identifying this machine. The poll does not check it. */
+  machineId: string;
+  fetch?: typeof fetch;
+}
+export interface AppSessionRequest {
+  id: string;
+  /** The approval page. Show it to the person; opening a browser is the caller's business. */
+  url: string;
+}
+/** Step one: ask the site for an approval page. Takes no token and no cookie. */
+export declare function requestAppSession(options: RequestAppSessionOptions): Promise<AppSessionRequest>;
+export interface PollAppSessionOptions {
+  siteUrl: string;
+  /** `sessionRequestId` from `requestAppSession`. */
+  id: string;
+  fetch?: typeof fetch;
+  /** Gap between polls. Default 2000. */
+  intervalMs?: number;
+  /** Give up after this long. Default 300000, the life of a pending request. */
+  timeoutMs?: number;
+}
+export interface AppSession {
+  sessionToken: string;
+  /** On an Autodesk Identity site this is the person's email address. Treat it as identifying. */
+  userLogin: string;
+}
+/**
+ * Step two: poll until the person approves. The token is handed out once, so poll
+ * from one place and keep the response that holds it. A 404 is forgotten, denied
+ * or a mistyped id alike, so the only answer is to request a new session.
+ */
+export declare function pollAppSession(options: PollAppSessionOptions): Promise<AppSession>;
+//#endregion
+//#region src/context.d.ts
+/**
+ * What the site decides about display. None of it is on a field: the unit behind
+ * a duration is `hours_per_day` from `GET /preferences` (field_types/duration),
+ * and nothing at all names the frame rate behind a timecode
+ * (field_types/timecode), so the app supplies that one.
+ */
+export interface SitePreferences {
+  /** The site's `hours_per_day`; a duration then renders in days. */
+  hoursPerDay?: number;
+  locale?: string;
+  /** IANA zone a `date_time` is shown in. Defaults to the runtime's. */
+  timeZone?: string;
+  /** Frames a second, for a timecode. Given, a timecode gains its frame digits. */
+  frameRate?: number;
+}
+export interface SgContextOptions extends SitePreferences {
+  client: SgClient;
+  /** How long a row read stays fresh. Schema and statuses keep their own hour-long cache. Default 30000. */
+  ttlMs?: number;
+  /** The web app this data comes from, so widgets can link a row to its page. */
+  siteUrl?: string;
+}
+export interface SgContext {
+  /** The cached client. Widgets read rows through this, not through the one passed in. */
+  client: QueryCache;
+  schema: SchemaService;
+  statuses: StatusService;
+  /** The web app this data comes from, without its trailing slash. Empty when the app named none. */
+  siteUrl: string;
+  /** What the site decides about display. Empty when the app named nothing. */
+  preferences: SitePreferences;
+  /** Drop everything cached. Call it after a write. */
+  invalidate(): void;
+}
+export declare function createSgContext(options: SgContextOptions): SgContext;
+/**
+ * The context for a bare client, built once. A widget given a client and no
+ * context calls this, and every widget on the page handed that client shares its
+ * caches. The options are read on the first call for a client; a later call
+ * returns what that one built.
+ */
+export declare function contextFromClient(client: SgClient, options?: Omit<SgContextOptions, 'client'>): SgContext;
+/** The site preferences a formatter takes, ready to spread into `fieldText`. */
+export declare function preferencesOf(context?: {
+  preferences?: SitePreferences;
+} | null): FieldTextOptions;
+//#endregion
+//#region src/presentation.d.ts
+/** Trailing slashes off, so a site url composes with an absolute path. */
+export declare function normalizeSiteUrl(siteUrl: string | null | undefined): string;
+/**
+ * The web app's page for one row.
+ *
+ * `Project.landing_page_url` is the only detail address the API hands out, and it
+ * is the site-relative path `/detail/Project/<id>` with the site url left to the
+ * caller (entity_types/Project). Every other type takes the same shape by a
+ * convention the API does not document: on the test site `/detail/<Type>/<id>`
+ * answers 302 to `/user/login` carrying itself as `return_path`, so the route
+ * resolves before authentication decides.
+ *
+ * Answers null when there is no site to link into or no row to link to.
+ */
+export declare function entityDetailUrl(siteUrl: string | null | undefined, ref: EntityRef | null | undefined): string | null;
+/** The character between the hops of a path label. */
+export declare const PATH_SEPARATOR = " › ";
+export interface PathLabelOptions {
+  /**
+   * Name the type a hop travels through when the hop's field links several types.
+   * Default true.
+   */
+  typeWhenAmbiguous?: boolean;
+  /** Display names by schema type name, from `entityTypes()`. */
+  typeLabels?: Record<string, string>;
+  separator?: string;
+}
+/**
+ * The label of a resolved path.
+ *
+ * A hop names its field, and the type only when the field's `valid_types` holds
+ * more than one: `sg_task.Task.sg_status_list` reads `Task › Status`, while
+ * `note_links.Shot.sg_sequence` reads `Link › Shot › Sequence` because the same
+ * field could have gone to an Asset. A projection resolves a dotted path against
+ * that `valid_types` list (probe 059), so the ambiguity the label spells out is
+ * the one the read itself has to settle.
+ */
+export declare function pathLabel(segments: readonly PathSegment[], options?: PathLabelOptions): string;
+//#endregion
+//#region src/pickers.d.ts
+export interface EntityTypeRestrictions {
+  /** Codes a caller offers. Empty or absent means every type. */
+  allow?: string[];
+  /** Codes a caller withholds, applied after `allow`. */
+  deny?: string[];
+}
+/**
+ * The types a picker may offer, allow first and deny second.
+ *
+ * Applied to the derived list rather than to the read, so a caller narrowing the
+ * set sees the list change with no second call. `/schema` is 12KB and holds every
+ * enabled type, custom slots included (probe 002).
+ */
+export declare function filterEntityTypes(types: readonly EntityTypeInfo[], restrictions?: EntityTypeRestrictions): EntityTypeInfo[];
+/** What an entity-type picker draws: the rows on offer and the label a code takes. */
+export interface EntityTypeOptions {
+  /** Types on offer, `allow` first and `deny` second. */
+  types: EntityTypeInfo[];
+  /** Those the query matches, on display name or code. */
+  shown: EntityTypeInfo[];
+  /** A code's display name, or the code itself where the site offers no such type. */
+  labelOf: (code: string) => string;
+}
+/**
+ * The options both entity-type pickers derive from one schema read.
+ *
+ * The vocabulary is one read of 12KB (probe 002), so the query narrows the derived
+ * list in the browser rather than asking for it again. `loaded` is `null` while the
+ * read is in flight, which offers nothing and labels a code as itself.
+ */
+export declare function entityTypeOptions(loaded: readonly EntityTypeInfo[] | null, options?: EntityTypeRestrictions & {
+  query?: string;
+}): EntityTypeOptions;
+/** One traversal step: the link field followed, and the type it landed on. */
+export interface FieldHop {
+  /** Field code on the type the hop leaves. */
+  name: string;
+  displayName: string;
+  /** Type the hop lands on. */
+  through: string;
+}
+/** `entity.Shot.code`: every hop names the type it travels through (field_types/entity). */
+export declare function fieldPathOf(hops: readonly FieldHop[], name: string): string;
+/** The type each hop landed on, root first. A type already here is not descended into again. */
+export declare function pathTypes(rootType: string, hops: readonly FieldHop[]): string[];
+/** The type a picker is reading fields from after these hops. */
+export declare function currentType(rootType: string, hops: readonly FieldHop[]): string;
+/** A resolved path as a person reads it. */
+export declare function friendlyFieldPath(segments: readonly PathSegment[], separator?: string): string;
+/** A column a data source computes, offered alongside the real fields. */
+export interface ExtraField {
+  /** The value emitted when it is chosen. */
+  name: string;
+  displayName?: string;
+}
+export interface FieldPickerRestrictions {
+  /** Allow descending through entity fields. Off by default. */
+  deepLinks?: boolean;
+  /** How many hops a path may take. Default 2. */
+  maxDepth?: number;
+  /** Data types a field must have to be selected. Traversal ignores this. */
+  dataTypes?: string | string[];
+  /** A field is selectable only if it declares link targets and one of them is here. Traversal ignores this. */
+  validTypes?: string[];
+  /** Full dotted paths to drop, so a root field and the same name behind a hop are separate. */
+  exclude?: string[];
+  /** Dotted prefixes to drop, along with everything beneath them. */
+  hidePaths?: string[];
+  /** Drop types the API refuses in a filter (017_filter_operators). */
+  filterableOnly?: boolean;
+  /** Synthetic entries offered at the root only. They bypass `dataTypes` and `validTypes`. */
+  extraFields?: ExtraField[];
+  /** Caller's own visibility test, receiving the schema and the candidate's full path. */
+  filter?: (field: FieldSchema, path: string) => boolean;
+}
+export interface FieldOption {
+  /** Full dotted path from the root type. This is the emitted value. */
+  path: string;
+  /** Field code on the type it lives on. */
+  name: string;
+  displayName: string;
+  dataType: string;
+  /** The row may be chosen as the value. */
+  selectable: boolean;
+  /** The row descends. */
+  traversable: boolean;
+  /** Types a traversable row may descend into, minus the ones already on the path. */
+  targets: string[];
+  /** A synthetic entry rather than a schema field. */
+  computed: boolean;
+}
+export interface FieldOptionsInput extends FieldPickerRestrictions {
+  rootType: string;
+  /** Hops already taken. Empty at the root. */
+  hops?: readonly FieldHop[];
+}
+/**
+ * The types a field may be descended into from here.
+ *
+ * Only a single `entity` field: a dotted path through a `multi_entity` field reads
+ * back nothing, 200 with the key absent from `attributes` (probe 016). A type
+ * already on the path is dropped, so `project.Project.users.HumanUser.projects`
+ * cannot loop.
+ */
+export declare function traversalTargets(field: Pick<FieldSchema, 'dataType' | 'validTypes'>, input: {
+  rootType: string;
+  hops?: readonly FieldHop[];
+  deepLinks?: boolean;
+  maxDepth?: number;
+}): string[];
+/**
+ * The rows a field picker shows for one type at one depth.
+ *
+ * `dataTypes` and `validTypes` bind what may be *selected*; a link field stays on
+ * the list so a restricted picker can still reach a nested field of the wanted
+ * type. Every other restriction hides the row outright and is measured against
+ * the full dotted path, so excluding a root field leaves the same name behind a
+ * hop alone. Computed entries come first, then the schema fields by display name.
+ */
+export declare function deriveFieldOptions(fields: Record<string, FieldSchema>, input: FieldOptionsInput): FieldOption[];
+/** Rows matching the search box. */
+export declare function searchFieldOptions(options: readonly FieldOption[], query: string): FieldOption[];
+/** The list with `path` appended, or dropped when it is already there. */
+export declare function toggleFieldPath(paths: readonly string[], path: string): string[];
+/** The list with the entry at `from` moved to `to`. An index off either end leaves the order alone. */
+export declare function moveFieldPath(paths: readonly string[], from: number, to: number): string[];
+/** The sub-label of a row whose path the schema does not hold. */
+export declare const UNRESOLVED_PATH_LABEL = "not in the schema";
+/** One row of a fixed list of paths: what a caller offered, read through the schema. */
+export interface FieldPathOption {
+  /** The path as the caller wrote it. This is the emitted value. */
+  path: string;
+  /** The resolved path, display names joined, or the raw path where the schema has no such path. */
+  label: string;
+  /** Code of the leaf field, empty where the path does not resolve. */
+  name: string;
+  /** Data type of the leaf field, empty where the path does not resolve. */
+  dataType: string;
+  /** The muted line under the label: the leaf's data type, or that the schema has no such path. */
+  subLabel: string;
+  /** The schema resolved the path. */
+  resolved: boolean;
+}
+/**
+ * A caller's fixed list of paths as flat rows, in the order given.
+ *
+ * Each path is resolved through every type it travels and labelled as the picker
+ * labels a chosen value. A path the schema does not hold keeps its place and is
+ * marked, so a list of columns never comes back shorter than it went in.
+ */
+export declare function resolveFieldPathOptions(schema: Pick<SchemaService, 'resolvePath'>, rootType: string, paths: readonly string[], options?: PathLabelOptions): Promise<FieldPathOption[]>;
+/** Rows matching the search box, read on what the row shows and on the path behind it. */
+export declare function searchFieldPathOptions(options: readonly FieldPathOption[], query: string): FieldPathOption[];
+//#endregion
+//#region src/sortable.d.ts
+/**
+ * Ordered lists that reorder by pointer and by keyboard.
+ *
+ * The model answers what a move does to an order and what a screen reader should
+ * be told about it. The controller binds one list element: it turns pointer
+ * events into a drag, moves the rows out of the way with a transform, runs the
+ * keyboard drag mode, and calls back with the new order. A framework binding
+ * wires the two together and renders the live region; it decides nothing here.
+ */
+export type SortableDirection = 'up' | 'down';
+export type SortableOrientation = 'vertical' | 'horizontal';
+/** The edges of an item, as `getBoundingClientRect` gives them. */
+export interface SortableRect {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+export interface SortablePoint {
+  x: number;
+  y: number;
+}
+/** The attribute carrying an item's id. It is what the controller walks the list by. */
+export declare const SORTABLE_ID_ATTRIBUTE = "data-sortable-id";
+/** The attribute marking the element a drag starts from. */
+export declare const SORTABLE_HANDLE_ATTRIBUTE = "data-sortable-handle";
+/** The live-region copy, one line per gesture step. Indexes are counted from zero. */
+export declare const sortableAnnouncements: {
+  pickup: (label: string, index: number, count: number) => string;
+  move: (label: string, index: number, count: number) => string;
+  drop: (label: string) => string;
+  cancel: () => string;
+};
+export interface SortableModelOptions {
+  /** The name announced for an id. The id itself by default. */
+  label?: (id: string) => string;
+}
+export interface SortableModel {
+  readonly ids: readonly string[];
+  indexOf(id: string): number;
+  labelOf(id: string): string;
+  /** The order with the entry at `from` moved to `to`. An index off either end leaves it alone. */
+  moveTo(from: number, to: number): string[];
+  /** The order with `id` moved one place towards the start or the end. */
+  keyboardMove(id: string, direction: SortableDirection): string[];
+  pickedUp(id: string): string;
+  movedTo(id: string, index: number): string;
+  dropped(id: string): string;
+  cancelled(): string;
+}
+/** A frozen view of one order: every move answers with a new array. */
+export declare function createSortable(ids: readonly string[], options?: SortableModelOptions): SortableModel;
+/**
+ * The index an item dragged from `from` lands on.
+ *
+ * `rects` are the items in list order, measured before the drag; `point` is the
+ * dragged item's own midpoint, moved by the pointer. A neighbour's place is
+ * claimed once its midpoint is crossed, so the far edge of a tall row does not
+ * take a place the item is only overlapping.
+ */
+export declare function sortableDropIndex(rects: readonly SortableRect[], from: number, point: SortablePoint, orientation?: SortableOrientation): number;
+/** How far one item sits from the next, so the rows a drag passes shift by a whole row. */
+export declare function sortableStride(rects: readonly SortableRect[], from: number, orientation?: SortableOrientation): number;
+export interface SortableScrollOptions {
+  /** How near an edge the pointer has to be before the container scrolls. */
+  threshold?: number;
+  /** Pixels per frame at the edge itself. */
+  speed?: number;
+  orientation?: SortableOrientation;
+}
+/**
+ * Pixels to scroll the container this frame, negative towards the start.
+ *
+ * Zero until the pointer is inside `threshold` of an edge, then proportional to
+ * how far past it, up to `speed` at the edge and beyond.
+ */
+export declare function sortableScrollStep(bounds: SortableRect, point: SortablePoint, options?: SortableScrollOptions): number;
+/**
+ * Where every item of the list sits, by id, relative to the container.
+ *
+ * A measurement is compared with one taken later. Between the two the page may have
+ * scrolled, or the container itself may have moved: a list inside a popover is
+ * measured at the viewport's corner before the popover is placed. Container
+ * coordinates read neither as a move of every row.
+ */
+export declare function measureSortable(container: HTMLElement): Map<string, SortableRect>;
+export interface SortableFlipOptions {
+  duration?: number;
+}
+/**
+ * Move every item from where it was to where it is now, transform only.
+ *
+ * Called after the order has changed and the list has been redrawn. Returns the
+ * fresh measurement to hold for the next change. Under reduced motion the items
+ * are left where they are.
+ */
+export declare function playSortableFlip(container: HTMLElement, previous: Map<string, SortableRect> | null, options?: SortableFlipOptions): Map<string, SortableRect>;
+export interface SortableControllerOptions {
+  /** The element holding the items. */
+  container: HTMLElement;
+  /** The ids in their current order. Read at the start of every gesture and on every move. */
+  order: () => readonly string[];
+  /** The new order and the id that moved. */
+  onOrderChange: (order: string[], id: string) => void;
+  /** The name announced for an id. */
+  label?: (id: string) => string;
+  /** One line for the live region. */
+  onAnnounce?: (message: string) => void;
+  /** The id under a live gesture, or null when it ends. */
+  onDraggingChange?: (id: string | null) => void;
+  /** How far the pointer travels before a drag starts. */
+  activationDistance?: number;
+  /** How long the rows a drag passes take to shift. */
+  duration?: number;
+  orientation?: SortableOrientation;
+  /** A true blocks every gesture. */
+  disabled?: () => boolean;
+}
+export interface SortableController {
+  /** The id under a live gesture, pointer or keyboard. */
+  readonly active: string | null;
+  /**
+   * Set when a pointer drop has just committed a new order. The rows are already
+   * where the drag left them, so a binding clears this and re-measures instead of
+   * animating the change a second time.
+   */
+  settled: boolean;
+  destroy(): void;
+}
+/**
+ * Pointer and keyboard reordering over one list element.
+ *
+ * A drag starts on an element carrying the handle attribute, once the pointer has
+ * travelled `activationDistance`; the dragged row follows the pointer and the rows
+ * it passes shift by one row with a transform, so the gap left behind is the drop
+ * slot. Escape cancels. Space or Enter on a handle enters keyboard drag mode,
+ * where the arrow keys move the row a place at a time, Space, Enter or losing
+ * focus drops it, and Escape puts it back.
+ */
+export declare function createSortableController(options: SortableControllerOptions): SortableController;
+//#endregion
+//#region src/collection-state.d.ts
+/** How a collection keys a row. Without one, `Type:id`. */
+export type RowIdFn = (row: EntityRow) => string;
+/** True for a row the keyboard skips and the selection refuses. */
+export type RowDisabledFn = (row: EntityRow) => boolean;
+/** A row's id: the caller's, or `Type:id`. */
+export declare function rowIdOf(row: EntityRow, getRowId?: RowIdFn | null): string;
+/** True when the caller says the row is disabled. */
+export declare function rowIsDisabled(row: EntityRow, isRowDisabled?: RowDisabledFn | null): boolean;
+/**
+ * Where a cursor lands moving `step` from `from`, skipping disabled entries.
+ *
+ * The walk stops at the ends rather than wrapping, and answers `from` when every
+ * entry that way is disabled, so a key press on the last enabled row does nothing.
+ */
+export declare function nextEnabledIndex(count: number, from: number, step: number, disabled: (index: number) => boolean): number;
+/** The first enabled entry at or after `from`, walking `step`. -1 when there is none. */
+export declare function firstEnabledIndex(count: number, from: number, step: number, disabled: (index: number) => boolean): number;
+/** The ids the rows of `refs` are keyed under. A ref no loaded row stands for is dropped. */
+export declare function idsForRefs(rows: readonly EntityRow[], refs: readonly EntityRef[], getRowId?: RowIdFn | null): string[];
+/** The rows the ids stand for, in row order. */
+export declare function refsForIds(rows: readonly EntityRow[], ids: readonly string[], getRowId?: RowIdFn | null): EntityRef[];
+/** `ids` with `id` added or removed. `on` forces the direction. */
+export declare function toggleId(ids: readonly string[], id: string, on?: boolean): string[];
+/** True when two id lists hold the same ids, whatever their order. */
+export declare function sameIds(a: readonly string[], b: readonly string[]): boolean;
+/** True when two selections name the same rows, whatever their order. */
+export declare function sameRefs(a: readonly EntityRef[], b: readonly EntityRef[]): boolean;
+/** True when two sort lists name the same keys in the same order. */
+export declare function sameSort(a: readonly SortSpec[], b: readonly SortSpec[]): boolean;
+/**
+ * True when two filters reach the server as the same group.
+ *
+ * The editor's tree and the wire hash are two spellings of one filter, so a `filters`
+ * prop holding the tree and a source holding the hash agree, and neither overwrites
+ * the other.
+ */
+export declare function sameFilters(a: SourceFilters, b: SourceFilters): boolean;
+/** A sort picker's keys as a source's sort. */
+export declare function toSortSpecs(keys: readonly SortKey[]): SortSpec[];
+/** A source's sort as a sort picker's keys. */
+export declare function toSortKeys(sort: readonly SortSpec[]): SortKey[];
+/** A selection with `ref` added or removed. */
+export declare function toggleRef(selection: readonly EntityRef[], ref: EntityRef): EntityRef[];
+/** What a header checkbox reads: every selectable row, or some of them. */
+export interface SelectionState {
+  all: boolean;
+  some: boolean;
+}
+/**
+ * The tri-state of a select-all control over the rows that are loaded.
+ *
+ * A disabled row refuses its own box, so it is left out of both readings and a page
+ * of nothing but disabled rows is neither all nor some.
+ */
+export declare function selectionState(rows: readonly EntityRow[], selection: readonly EntityRef[], isRowDisabled?: RowDisabledFn | null): SelectionState;
+/** Every selectable loaded row, as a selection. */
+export declare function selectableRefs(rows: readonly EntityRow[], isRowDisabled?: RowDisabledFn | null): EntityRef[];
+/**
+ * Which groups are shut.
+ *
+ * A mode with exceptions rather than a set of keys, because the keys a list holds
+ * are only the ones loaded so far: Collapse all written as a list says nothing
+ * about the groups the next page brings, and they arrive open under a header that
+ * said everything was shut. `all` is what a group does unless `except` names it.
+ */
+export interface CollapseState {
+  /** True when every group is shut but the ones `except` names. */
+  all: boolean;
+  /** The keys that go the other way from `all`. */
+  except: string[];
+}
+/** Every group shut, including the ones not loaded yet. */
+export declare function collapseAll(): CollapseState;
+/** Every group open. */
+export declare function expandAll(): CollapseState;
+/**
+ * A caller's value as a state. A bare key list is the open mode with those keys
+ * shut, and a mode written without `except` has none.
+ */
+export declare function asCollapseState(value: readonly string[] | Pick<CollapseState, 'all'> | CollapseState | null | undefined): CollapseState;
+/** True when the group under `key` is shut. */
+export declare function isCollapsed(state: CollapseState, key: string): boolean;
+/** `state` with the group under `key` shut or open. `on` forces the direction. */
+export declare function toggleCollapsed(state: CollapseState, key: string, on?: boolean): CollapseState;
+/** The keys of `keys` that are shut, in the order given. */
+export declare function collapsedKeys(state: CollapseState, keys: readonly string[]): string[];
+/**
+ * The state a set of shut keys reads as, under the mode already in force.
+ *
+ * For a widget whose own machinery answers which headers are shut rather than which
+ * key was pressed. The mode is kept, so the groups the next page brings still follow
+ * it, and an exception for a key no longer drawn is dropped.
+ */
+export declare function collapseStateFrom(state: CollapseState, shut: readonly string[], keys: readonly string[]): CollapseState;
+/** True when two collapse states shut the same groups. */
+export declare function sameCollapse(a: CollapseState, b: CollapseState): boolean;
+//#endregion
+//#region src/entity-card.d.ts
+export interface EntityCardOptions {
+  /** Dotted field paths for the grid, in order. */
+  fields?: readonly string[];
+  /** The `image` field to read the thumbnail from. Default `image`. */
+  imagePath?: string;
+}
+/** One field of the grid, resolved. */
+export interface EntityCardColumn {
+  path: string;
+  /** `pathLabel` of the resolved path; the raw path when the path does not resolve. */
+  label: string;
+  dataType: string;
+  /** The leaf field's schema, for a status label out of `display_values` (probe 009). */
+  field: FieldSchema | null;
+  value: unknown;
+}
+export interface EntityCardModel {
+  entity: EntityRef;
+  /** The row the model was built from, for a caller's own label or sub-label. */
+  row: EntityRow;
+  name: string;
+  /** The type's display name, from the site's enabled types. */
+  typeLabel: string;
+  thumbnail: string | null;
+  /** The type's status field and the row's code, when the type has one. */
+  status: {
+    code: string;
+    field: FieldSchema;
+  } | null;
+  /** The caller's paths, less the one naming the type's own status field. */
+  columns: EntityCardColumn[];
+}
+/**
+ * The fields one card read asks for: the identity chain the type actually has,
+ * its thumbnail, its status field and the caller's paths.
+ *
+ * The chain is intersected with the type's schema because a name absent from a
+ * type is not an empty column but a 400 on the read: Task has neither `code` nor
+ * `name` (entity_types/Task).
+ */
+export declare function entityCardFields(context: SgContext, entityType: string, options?: EntityCardOptions): Promise<string[]>;
+/** The card model for a row already read. Resolves the labels and types of the paths. */
+export declare function describeEntityCard(context: SgContext, row: EntityRow, options?: EntityCardOptions): Promise<EntityCardModel>;
+/**
+ * The column one metadata slot of a tile draws, or null when there is nothing to draw.
+ *
+ * The slot takes the same spec as every other row-anatomy prop: a bare path, resolved
+ * against the card's own columns so the value renders by its data type, or a column the
+ * caller already resolved, which is taken at its word and costs no lookup. A slot naming
+ * the row's own status field draws it: the grid leaves that field to the header, and a
+ * caller who puts it on the metadata line has asked for it there. A status reads the name
+ * the site gives the code, off the field's `display_values`, which covers the whole
+ * vocabulary (recipes/010, field_types/status_list).
+ */
+export declare function entityCardSlot(card: EntityCardModel, spec: FieldSpec | null | undefined): EntityCardColumn | null;
+/** The card model for a reference: one search for the row, then its description. */
+export declare function loadEntityCard(context: SgContext, entity: EntityRef, options?: EntityCardOptions): Promise<EntityCardModel>;
+//#endregion
+//#region src/tree.d.ts
+/** One node of a level, as a loader hands it over. */
+export interface TreeSourceNode {
+  /** The key everything else is held under, and what the loader is called with. */
+  path: string;
+  label: string;
+  ref: HierarchyRef;
+  /** False when opening this node would return nothing. */
+  hasChildren: boolean;
+  /** Fields of the row the node stands for, flattened. */
+  values?: Record<string, unknown>;
+}
+/** One level: the node that was opened, and the level below it. */
+export interface TreeLevel {
+  node: TreeSourceNode;
+  children: TreeSourceNode[];
+}
+/** Reads one level. A node already read is never read again. */
+export type TreeLoader = (path: string) => Promise<TreeLevel>;
+/** A node in the tree, with where it sits. */
+export interface TreeNode {
+  path: string;
+  label: string;
+  ref: HierarchyRef;
+  /** The row the node stands for, or null where it stands for a type or nothing. */
+  entity: EntityRef | null;
+  hasChildren: boolean;
+  parentPath: string | null;
+  /** Depth below the root, which is 0. */
+  level: number;
+  /** Fields of the row the node stands for, flattened. Empty until a loader fills it. */
+  values: Record<string, unknown>;
+}
+export type TreeCheckState = 'checked' | 'mixed' | 'unchecked';
+export type TreeSelectionMode = 'none' | 'single' | 'multiple';
+export type TreeStatus = 'idle' | 'loading' | 'ready' | 'error';
+/** One line of the visible list, with everything a row draws itself from. */
+export interface TreeRow {
+  node: TreeNode;
+  expanded: boolean;
+  /** True while this node's level is being read. */
+  loading: boolean;
+  checked: TreeCheckState;
+  selected: boolean;
+  /** True on the one node that owns the tab stop. */
+  focused: boolean;
+  /** True when the caller disabled the node: the cursor skips it and it never selects. */
+  disabled: boolean;
+  /** True when the search placed this row, or its label holds every word. */
+  match: boolean;
+}
+/** Everything a view renders. A new object on every change, so identity is the signal. */
+export interface TreeState {
+  rows: TreeRow[];
+  status: TreeStatus;
+  error: Error | null;
+  /** Path of the focus cursor, or null before the root is read. */
+  cursor: string | null;
+  /** The text the tree is searching for. */
+  search: string;
+  /** True while a search is in flight. */
+  searching: boolean;
+  /** Paths of the rows the search marked, in visible order. */
+  matches: string[];
+  /** Paths whose box is fully checked, branches included. */
+  checked: string[];
+  selected: string[];
+  /** Paths that are open, in visible order. */
+  expanded: string[];
+}
+/** A keyboard event, reduced to what the model reads. */
+export interface TreeKey {
+  key: string;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+}
+export interface TreeSelectOptions {
+  /** Add to the selection instead of replacing it. Ignored unless selection is `multiple`. */
+  additive?: boolean;
+}
+export interface TreeOptions {
+  loader: TreeLoader;
+  /** Where the tree starts, `/Project/<id>` against the hierarchy loader. */
+  rootPath: string;
+  selection?: TreeSelectionMode;
+  /** Places rows by text. Without one, a search marks the labels already loaded. */
+  searcher?: TreeSearcher;
+  /** Types a search covers. Default: the types the levels already read stand for. */
+  searchTypes?: readonly string[];
+  /** How many levels `expandAll` opens under a node. Default 3. */
+  expandDepth?: number;
+  /** True for a node the cursor skips and selection refuses. */
+  disabled?: (node: TreeNode) => boolean;
+  /** How long a type-ahead buffer survives, in milliseconds. Default 800. */
+  typeAheadMs?: number;
+  /** The clock type-ahead measures on. */
+  now?: () => number;
+}
+/** One row a search found, and where the tree puts it. */
+export interface TreeSearchHit {
+  ref: EntityRef;
+  label: string;
+  /** One path per level, root first; the last entry is the row itself. */
+  incrementalPath: string[];
+}
+/** Matches words and answers where each hit sits. */
+export type TreeSearcher = (text: string, entityTypes: readonly string[]) => Promise<TreeSearchHit[]>;
+export interface TreeEngine {
+  readonly rootPath: string;
+  snapshot(): TreeState;
+  subscribe(listener: () => void): () => void;
+  /** A node already loaded, by path. */
+  node(path: string): TreeNode | undefined;
+  /** The paths of a node's level, once it has been read. */
+  childPaths(path: string): string[];
+  checkStateOf(path: string): TreeCheckState;
+  /** Read the root and open it. */
+  load(): Promise<void>;
+  expand(path: string): Promise<void>;
+  collapse(path: string): void;
+  toggle(path: string): Promise<void>;
+  /** Open every level down to a path, or to the deepest entry of an incremental path. */
+  expandToPath(refs: string | readonly string[]): Promise<void>;
+  /** Open every level under a node, breadth first, down to `depth`. */
+  expandAll(path: string, depth?: number): Promise<void>;
+  /** Move the focus cursor. A path outside the visible list is ignored. */
+  focus(path: string): void;
+  /** Open exactly these paths, reading whatever level is not loaded, and shut the rest. */
+  setExpanded(paths: readonly string[]): Promise<void>;
+  /** Select exactly these paths. A path outside the tree is dropped. */
+  setSelected(paths: readonly string[]): void;
+  setChecked(path: string, on: boolean): void;
+  toggleChecked(path: string): void;
+  /** The rows the checked nodes stand for, in visible order. */
+  checkedRefs(): EntityRef[];
+  select(path: string, options?: TreeSelectOptions): void;
+  clearSelection(): void;
+  /**
+   * Place every row the words match, open the tree onto them and mark them. An
+   * empty text drops the marks and restores the expansion the search opened onto.
+   */
+  search(text: string): Promise<void>;
+  /** True when the tree handled the key, which is when the caller stops it. */
+  keyDown(event: TreeKey): boolean;
+}
+export declare function createTree(options: TreeOptions): TreeEngine;
+export interface HierarchyLoaderOptions {
+  /** Field paths read for the rows the nodes of a level stand for. */
+  fields?: readonly string[];
+}
+/**
+ * `hierarchyExpand` as a tree loader.
+ *
+ * With `fields`, the rows a level's nodes stand for are read once per type over
+ * the ids just returned, so a sub-label or a status comes back with the level
+ * rather than one read per row. A name a type does not have is dropped at 200, so
+ * one list of names serves every type (probe 003).
+ */
+export declare function hierarchyLoader(client: SgClient, options?: HierarchyLoaderOptions): TreeLoader;
+export interface HierarchySearcherOptions {
+  /** Answers whether a type carries `project`, so the words are scoped to it. */
+  schema?: FieldLookup;
+  /** Rows the text search asks for. Each one costs a path lookup. Default 10. */
+  limit?: number;
+}
+/**
+ * `_text_search` and `hierarchy/_search` chained, as a tree searcher.
+ *
+ * The hierarchy endpoint takes an entity and answers where it sits rather than
+ * matching words, so the words go to `_text_search` first and each hit is then
+ * asked for its path (post_hierarchy_search). A root path naming a project scopes
+ * the words to it, on every type that carries a `project` field.
+ */
+export declare function hierarchySearcher(client: SgClient, rootPath: string, options?: HierarchySearcherOptions): TreeSearcher;
+/** The schemas a tree row needs, one entry per type the tree has shown. */
+export interface TreeFieldPlan {
+  /** The type's own status field, when it has a real one. */
+  status: Record<string, FieldSchema | null>;
+  /** The secondary column's field, per type. */
+  secondary: Record<string, FieldSchema | null>;
+  /** The sub-label field's, per type, so the line reads by its data type. */
+  subLabel: Record<string, FieldSchema | null>;
+  /** `Status` rows by code, read once and only when a status is on show (probe 010). */
+  statuses: Record<string, StatusRecord> | null;
+}
+/** The row-anatomy fields a tree resolves per type, as bare paths. */
+export interface TreeFieldNames {
+  secondary?: string | undefined;
+  subLabel?: string | undefined;
+}
+/**
+ * The status field, the secondary field and the sub-label field of every type a tree shows.
+ *
+ * A type's status field is whichever field is a `status_list`. Project's
+ * `sg_status` is a plain `list` with no Status row behind its values, so it
+ * carries no badge (entity_types/Project, probe 009).
+ */
+export declare function resolveTreeFields(schema: SchemaService, statusTable: StatusService, types: readonly string[], names?: TreeFieldNames): Promise<TreeFieldPlan>;
+/** The field names a level is read under so a row can show a status: the two the API uses. */
+export declare const TREE_STATUS_FIELDS: readonly ['sg_status_list', 'sg_status'];
+//#endregion
+//#region src/paging.d.ts
+/** How a collection walks a set: a page number, a load-more row, or the scroller. */
+export type PagingMode = 'pages' | 'more' | 'scroll';
+/** Rows before the last at which a scroller asks for the next page. */
+export declare const SCROLL_THRESHOLD = 5;
+/** The source mode a paging mode needs: `pages` shows one page, the other two append. */
+export declare function sourceModeFor(paging: PagingMode): SourceMode;
+/**
+ * True when every row the filter matches is loaded.
+ *
+ * A set that has never been read has not reached its end, however empty it is.
+ */
+export declare function reachedEnd(state: EntitySourceState): boolean;
+/** True when the next page may be asked for now. */
+export declare function canLoadNext(state: EntitySourceState, paging: PagingMode): boolean;
+/** True when a read failed with rows already on screen: the error belongs under them, with a retry. */
+export declare function hasFailedPage(state: EntitySourceState): boolean;
+export interface LoadNextOptions {
+  paging: PagingMode;
+  /** Index of the last row the viewport reaches. -1 when none is. */
+  lastVisible: number;
+  /** Rows before the last at which the next page is asked for. Default `SCROLL_THRESHOLD`. */
+  threshold?: number;
+}
+/**
+ * True when the scroller has reached far enough down for the next page.
+ *
+ * A failed page is not retried here, only on the retry the error line carries:
+ * a scroller that retried on its own would ask again on every pixel.
+ */
+export declare function shouldLoadNext(state: EntitySourceState, options: LoadNextOptions): boolean;
+/**
+ * True when a cursor stepping to `index` runs past the loaded rows and should ask
+ * for the next page instead of moving. The cursor stays where it is until the rows
+ * arrive.
+ */
+export declare function loadsOnArrowDown(state: EntitySourceState, paging: PagingMode, index: number): boolean;
+/** A contiguous run of rows sharing a value, under the key a collapsed group is named by. */
+export interface KeyedRowGroup extends RowGroup {
+  key: string;
+}
+/**
+ * Contiguous runs with a stable key.
+ *
+ * The key is the run's position and its value, so a page whose first rows carry
+ * the value the last run carries grows that run rather than opening a second one,
+ * and a group shut before the page arrived is still shut after it.
+ */
+export declare function groupRowsKeyed(rows: readonly EntityRow[], by: GroupBy): KeyedRowGroup[];
+/**
+ * What a collection draws in place of its rows.
+ *
+ * A read that failed with rows already loaded is not this block: those rows stay and
+ * the error goes under them, which is what `hasFailedPage` answers.
+ */
+export declare function collectionView(state: EntitySourceState, lines: number): WidgetState;
+/** What sits under the last loaded row, if anything. */
+export type CollectionBottom = 'error' | 'loading' | 'more' | 'sentinel' | null;
+/**
+ * The block under the rows: the failed page with its retry, the skeleton of a page on
+ * the way, the load-more row, or the sentinel a scroller watches. One at a time.
+ */
+export declare function collectionBottom(state: EntitySourceState, paging: PagingMode): CollectionBottom;
+//#endregion
+//#region src/list-chrome.d.ts
+/** A read is on its way and the list is standing by. */
+export declare const SEARCHING_LABEL = "Searching…";
+/** What the live row says about a list that answered. */
+export declare function countLine(count: number): string;
+/** What the live row is told about the list under it. */
+export interface ListStatusState {
+  /** A read is in flight. */
+  loading: boolean;
+  /** Rows on show. */
+  count: number;
+  /** What the failed read said, or null. */
+  error?: string | null;
+  /** Nothing is announced until something has been asked for. */
+  asked?: boolean;
+}
+/**
+ * The one line a list's live region carries.
+ *
+ * A failure wins, then a read in flight, then what the read answered. Nothing is
+ * announced before anything has been asked for, so an idle list stays silent.
+ */
+export declare function listStatus(state: ListStatusState, labels?: StateLabels): string;
+/** How far a scroller has more content past each of its edges, in pixels. */
+export interface OverflowEdges {
+  start: number;
+  end: number;
+}
+/** The room above and below what a scroller shows. */
+export declare function overflowEdges(scrollTop: number, scrollHeight: number, clientHeight: number): OverflowEdges;
+/** The variables the fade reads. The names are Base UI's, so one class string serves both registries. */
+export declare const OVERFLOW_START_VAR = "--scroll-area-overflow-y-start";
+export declare const OVERFLOW_END_VAR = "--scroll-area-overflow-y-end";
+/** Write a scroller's overflow onto itself, so the fade on each edge follows what is past it. */
+export declare function markOverflow(list: HTMLElement | null | undefined): boolean;
+/**
+ * Keep a scroller's overflow variables current while it is on screen.
+ *
+ * The measurement follows a scroll, a resize of the scroller and a change to what it
+ * holds, which is every way the room past an edge can move. Returns the teardown.
+ */
+export declare function watchOverflow(list: HTMLElement | null | undefined): () => void;
+//#endregion
+export { ConditionValue, DATA_TYPES, DISPLAY_NAME_FIELDS, DataType, EVENT_LOG_FIELDS, EntityRef, EntityRow, EntityTypeInfo, EventLogEntry, EventLogOptions, EventLogResult, FIELD_SCHEMA_OVERRIDES, FieldSchema, FilterCondition, FilterGroup, FilterNode, FollowingOptions, HierarchyNode, HierarchyPath, HierarchyRef, LogicalOperator, NATIVE_STATUSES, NEGATING_OPERATORS, NativeStatus, OPERATORS, OPERATORS_BY_TYPE, Operator, RawFieldSchema, RawFieldsResponse, RawHierarchyNode, RawProperty, RestClient, RestClientOptions, Rgb, STOCK_ICON_CELLS, STOCK_ICON_DATA_URLS, STOCK_ICON_KEYS, STOCK_SPRITE_PATH, Scalar, SearchOptions, SearchResult, SgApiError, SgClient, SpriteCell, StatusGlyph, StatusIcon, StatusOption, StatusPaint, StatusRecord, StockIconSource, SummarizeOptions, SummarizeResult, SummaryField, SummaryGroup, SummaryGrouping, SummaryType, TIME_UNITS, TextSearchFilter, TextSearchRow, ThreadAuthor, ThreadRow, TimeUnit, UploadFile, UploadResult, VALUE_SHAPE, ValueShape, WireCondition, WireGroup, condition, displayNameOf, emptyFilter, eventLogFilters, fieldSchemaOverride, foregroundFor, fromWire, group, hierarchyEntity, intersectStatuses, isBlankCondition, isDataType, isEmptyFilter, isFilterable, isLinkType, isNativeStatus, isNumericType, isOperator, isTemporalType, nativeStatus, normalizeEventLogEntry, normalizeField, normalizeFields, normalizeHierarchyNode, operatorsFor, parseBgColor, referencedPaths, relativeLuminance, rgbToCss, spriteStyle, statusFieldFor, statusFieldNameFor, statusGlyph, statusLabel, statusPaint, stockIconSource, supportsOperator, toApi3Hash, toFilterArray, undeclaredField, usableStatuses, walk };