@declarion/react 0.60.0 → 0.63.0

package/dist-lib/useResponsiveMode-DIR1bZfo.d.ts

@@ -0,0 +1,1786 @@
+import { t as IconDef } from "./icon-registry-CUT4eF63.js";
+import { ReactNode } from "react";
+//#region src/types/ordmap.d.ts
+/**
+ * OrderedMap preserves the insertion order of a string-keyed map while
+ * keeping O(1) lookup. It mirrors the Go `ordmap.OrderedMap[T]` container
+ * on the server side. Use it for schema sub-maps (entity fields, handler
+ * params, resolved_params) where YAML/JSON declaration order is part of
+ * the UI contract.
+ *
+ * JS objects already preserve insertion order for string keys (ES2015+),
+ * but the Go side emits JSON that is parsed into a plain object by
+ * default — this class wraps the hydrated object so call sites get a
+ * consistent API (`get`, `has`, iteration as `[name, value]` tuples) and
+ * the type system enforces read-only access.
+ */
+declare class OrderedMap<T extends {
+  name?: string;
+}> implements Iterable<[string, T]> {
+  #private;
+  constructor(items: readonly T[]);
+  /** Build from a `{ name: body }` object written in code: the key supplies
+   * `name`, insertion order is the JS property order, and bodies are
+   * type-checked. The wire equivalent, whose bodies cannot be, is `fromWire`. */
+  static fromObject<T extends {
+    name?: string;
+  }>(raw: Readonly<Record<string, Omit<T, "name">>> | null | undefined): OrderedMap<T>;
+  /** Build from a `{ name: body }` object decoded from JSON. Bodies are
+   * `unknown` and the cast to T is a claim about the server's envelope, not a
+   * check; anything written in code goes through `fromObject`, which checks. */
+  static fromWire<T extends {
+    name?: string;
+  }>(raw: Readonly<Record<string, unknown>> | null | undefined): OrderedMap<T>;
+  get length(): number;
+  has(name: string): boolean;
+  get(name: string): T | undefined;
+  /** Read-only items in declaration order. */
+  items(): readonly T[];
+  /** Names in declaration order. */
+  names(): readonly string[];
+  [Symbol.iterator](): IterableIterator<[string, T]>;
+}
+//#endregion
+//#region src/types/files.d.ts
+type FileFieldMode = "single" | "array" | "named_map" | "rich_text_inline";
+interface FileFieldDisplay {
+  widget: string;
+  placeholder?: LocalizedString;
+  initials?: boolean;
+  crop_on_upload?: boolean;
+  aspect_ratio?: string;
+  focal_point?: boolean;
+  is_listable?: boolean;
+  listable_thumbnail?: string;
+  reorderable?: boolean;
+  bulk_upload?: boolean;
+  bulk_download?: boolean;
+  lazy_load?: boolean;
+}
+interface FileNamedSlotDef {
+  name: LocalizedString;
+  accepts?: string[];
+  max_size_bytes?: number;
+  aspect_ratio?: string;
+  storage_backend?: string;
+}
+interface FileFieldDef {
+  /** The field's code, populated by the hydrator from the enclosing map key -
+   *  not a label a person reads. `OrderedMap.fromObject` takes bodies as
+   *  `Omit<_, "name">`, so a body cannot state it. */
+  name: string;
+  mode: FileFieldMode;
+  accepts?: string[];
+  max_size_bytes?: number;
+  max_count?: number;
+  max_total_size_bytes?: number;
+  required?: boolean;
+  slots?: Record<string, FileNamedSlotDef>;
+  display?: FileFieldDisplay;
+}
+interface HydratedFile {
+  id: string;
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+  sha256?: string;
+  width?: number;
+  height?: number;
+  page_count?: number;
+  uploaded_at?: string;
+  uploaded_by?: string;
+  url?: string;
+  presigned_url?: string;
+  derivations?: Record<string, string>;
+  metadata?: Record<string, unknown>;
+  position?: number;
+  slot?: string;
+  version?: {
+    number?: number;
+    is_current?: boolean;
+    supersedes_file_id?: string;
+  };
+}
+type NamedFileFieldValue = Record<string, HydratedFile | null>;
+type FileFieldValue = HydratedFile | HydratedFile[] | NamedFileFieldValue | null;
+interface UploadProgress {
+  loaded: number;
+  total: number;
+  pct: number;
+}
+interface UploadedFile {
+  id: string;
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+  sha256: string;
+  dedup?: boolean;
+  width?: number;
+  height?: number;
+  url?: string;
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+//#region src/lib/filters.d.ts
+/** A single node in the recursive filter tree. */
+interface FilterNode {
+  /** Field condition */
+  field?: string;
+  op?: FilterOp;
+  value?: unknown;
+  /** OR group: child nodes are OR-ed. */
+  or?: FilterNode[];
+  /** Explicit AND group (rarely needed, top-level is implicit AND) */
+  and?: FilterNode[];
+}
+/** All supported filter operator codes. */
+type FilterOp = "eq" | "not_eq" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in" | "between" | "contains" | "starts_with" | "is_empty" | "is_not_empty" | "today" | "this_week" | "this_month" | "last_7_days" | "last_30_days" | "last_hour" | "last_24_hours";
+/**
+ * Resolution status of one filter value, produced by the filter-value label
+ * resolver (`useFilterValueLabels`). `special` / `resolved` carry a `label`
+ * and are terminal-synchronous (no flicker); `loading` is a ref fetch in
+ * flight (render a skeleton, never the raw uuid); `unresolved` is a ref that
+ * could not be labeled (deleted / no access); `plain` is a literal/number/date
+ * (rendered raw, as before).
+ */
+type FilterValueStatus = "special" | "resolved" | "loading" | "unresolved" | "plain";
+/** Resolver result for one `(field, value)`: a label when known, the raw
+ *  coerced value always (the terminal fallback). */
+interface FilterValueLabel {
+  status: FilterValueStatus;
+  label?: string;
+  raw: string;
+}
+/** Maps one stored filter `(field, value)` to its human label. The single
+ *  source of chip + drawer value labels; see `useFilterValueLabels`. */
+type FilterValueResolver = (field: string, value: unknown) => FilterValueLabel;
+/** Operators that don't take a value. */
+declare const NO_VALUE_OPS: Set<FilterOp>;
+/** Human-friendly display names for operators. */
+declare const OP_LABELS: Record<FilterOp, string>;
+type FilterURLErrorCode = "filter.url_not_json" | "filter.url_not_tree";
+interface FilterURLState {
+  filters: FilterNode[];
+  error: string | null;
+  errorCode: FilterURLErrorCode | null;
+}
+/** Parse filters from URL search params (JSON `filters` param). */
+declare function parseFilterURLState(searchParams: URLSearchParams): FilterURLState;
+/** Parse the final tree and reject malformed URL state instead of treating it as no filter. */
+declare function parseFiltersFromURL(searchParams: URLSearchParams): FilterNode[];
+/**
+ * Write filters to URL search params.
+ *
+ * The parameter is present only while the tree differs from `defaults` - what
+ * this list resolves to with no `filters` in the URL, which is the active
+ * view's tree on a list screen and nothing anywhere else. So an empty tree is
+ * an OVERRIDE where a view supplies conditions (`filters=[]`, no conditions)
+ * and an absence where nothing does.
+ */
+declare function setFiltersInURL(filters: FilterNode[], searchParams: URLSearchParams, defaults?: FilterNode[]): void;
+/** Check if the filter tree has any OR groups. */
+declare function hasOrGroups(nodes: FilterNode[]): boolean;
+/** Count active field conditions in the filter tree. */
+declare function countActiveFilters(nodes: FilterNode[]): number;
+//#endregion
+//#region src/lib/language.d.ts
+declare const MANDATORY_LANGUAGE = "en";
+declare function pickLocalized(ls: LocalizedString | null | undefined, language: string, deploymentLanguage: string): string | undefined;
+type TextVars = Record<string, string | number>;
+interface TextFn {
+  (code: string, fallback: string, vars?: TextVars): string;
+  (value: LocalizedString | null | undefined): string;
+  readonly language: string;
+  readonly deploymentLanguage: string;
+}
+declare function makeTextFn(messages: Record<string, LocalizedString> | undefined, language: string, deploymentLanguage: string): TextFn;
+declare function pluralText(t: TextFn, code: string, count: number, english: {
+  one: string;
+  other: string;
+}, more?: TextVars): string;
+declare function textWithNodes(text: string, nodes: Record<string, ReactNode>): ReactNode[];
+//#endregion
+//#region src/types/schema.d.ts
+type LocalizedString = Record<string, string>;
+/**
+ * Where a `url` cell fetches an unknown host's site icon from.
+ *
+ * This is an outbound-request policy, not a visual style:
+ *   google — one request per rendered hostname to www.google.com.
+ *   direct — /favicon.ico from the site's own origin.
+ *   none   — no request at all; render the globe placeholder.
+ *
+ * Declared per column by `field.display.favicon_source`, and nowhere else -
+ * there is no parameter. Absent = `google`, today's rendered default. The
+ * server accepts exactly these three values.
+ */
+type FaviconSource = "google" | "direct" | "none";
+/**
+ * Per-entity empty-state copy declared in the manifest under
+ * `display.empty_state`. Title and Body are localized; LearnMoreURL is a
+ * plain string. The SDK falls back to a generic "No <plural> yet" derived
+ * from `display.name_plural` when this is absent. Read-only entities never
+ * render the legacy "Create your first..." copy regardless of EmptyStateDef.
+ */
+interface EmptyStateDef {
+  title?: LocalizedString;
+  body?: LocalizedString;
+  learn_more_url?: string;
+}
+declare function fieldDisplayName(t: TextFn, field: EntityField, fieldName: string, entities?: Record<string, Entity>): string;
+interface RefDisplay {
+  field: string;
+}
+interface RefConfig {
+  entity: string;
+  field?: string;
+  display?: RefDisplay;
+  fields?: string[];
+  /** Narrows the option set offered by this ref's entity-select dropdown (edit
+   *  combobox or action-param picker) to rows matching these conditions - e.g.
+   *  only `is_active = true`. Read-side only (not a write/security boundary).
+   *  The shared filter tree, so a declared narrowing takes the same shapes a
+   *  list query's `filters` takes. */
+  options_filter?: FilterNode[];
+}
+/** One declared filter-only option ({code, label}). `code` is stored into the
+ *  filter when chosen (a literal or a `$user.*` token resolved server-side);
+ *  `label` is the localized display string. Mirrors engine.FilterSpecialValue. */
+interface FilterSpecialValue {
+  code: string;
+  label: LocalizedString;
+}
+/** Per-screen override of a field's filter_special_values, keyed in
+ *  Screen.filter_special_values by the filter field code. */
+interface ScreenFilterSpecialValues {
+  mode?: "append" | "replace" | "clear";
+  values?: FilterSpecialValue[];
+}
+interface UnitConfig {
+  storage: string;
+  display?: string;
+}
+interface EntityField {
+  file_ref?: {
+    storage_backend: string;
+  };
+  /**
+   * Populated by the schema hydrator from the enclosing map key. Tests and
+   * fixtures may omit it; production code always receives it set.
+   */
+  name?: string;
+  type: string;
+  /**
+   * Computed and stamped by the server: whether a CROSS-store read can order by
+   * this field. Meaningful only where the entity's list_pagination is "cursor".
+   * Asked rather than re-derived here - a second copy of the backend's type
+   * allowlist drifts the day either side moves, and the symptom is an operator
+   * clicking a column header and getting a raw backend error in place of the
+   * table.
+   */
+  cross_store_sortable?: boolean;
+  required?: boolean;
+  primary?: boolean;
+  auto?: boolean;
+  readonly?: boolean;
+  source?: string;
+  timezone?: string;
+  precision?: number;
+  scale?: number;
+  unit?: UnitConfig;
+  default?: unknown;
+  display?: {
+    name: LocalizedString;
+    description?: LocalizedString;
+    width?: number;
+    widget?: string;
+    is_listable?: boolean;
+    is_filterable?: boolean;
+    list_preview?: {
+      max_chars: number;
+    };
+    ref_display_field?: string;
+    span?: number | "full";
+    bool_labels?: {
+      true: LocalizedString;
+      false: LocalizedString;
+    };
+    value_map?: Record<string, {
+      label?: LocalizedString;
+      color?: string;
+    }>;
+    currency?: string;
+    currency_field?: string;
+    currency_display?: "symbol" | "narrow_symbol" | "code" | "name";
+    favicon_source?: FaviconSource;
+  };
+  values?: Array<{
+    code: string;
+    name: LocalizedString;
+    description?: LocalizedString;
+    color?: string;
+  }>;
+  enum?: string;
+  files?: FileFieldDef;
+  ref?: RefConfig;
+  /** Filter-only declared options (e.g. "Myself" -> $user.id) surfaced in this
+   *  field's filter control. Inert everywhere else. A screen MAY override these
+   *  per-screen via Screen.filter_special_values. */
+  filter_special_values?: FilterSpecialValue[];
+  structure?: string;
+  array?: boolean;
+  copyable?: boolean;
+  /**
+   * Names the data_classifications tier gating reads + writes on this field. Read-side: stripped from the
+   * row when the caller lacks `classification:<tier>:read`. Write-side:
+   * 422 FIELDS_FORBIDDEN when the caller writes the key without
+   * `classification:<tier>:write`. Frontend reads the tier's localized
+   * display name from the top-level `classifications:` map and
+   * cross-references `schema.entities.<code>.field_access.<field>` for
+   * the per-caller decision.
+   */
+  classification?: string;
+}
+/**
+ * Per-caller classification decision for one classified field on one
+ * entity. Populated by the schema endpoint
+ * from the caller's grants + authority tier; the frontend reads this
+ * to render the locked-widget badge ("🔒 Compensation"), disable write
+ * inputs, and surface the operator-facing `required_permission` hint
+ * to the user (e.g. "Ask your admin to grant you
+ * classification:compensation:read").
+ */
+interface FieldAccessInfo {
+  read: "granted" | "denied";
+  write: "granted" | "denied";
+  classification: string;
+  /** Only set when read OR write is denied — the exact grant string an
+   *  administrator needs to add to a role to unlock this field. */
+  required_permission?: string;
+}
+interface StructureDef {
+  name: LocalizedString;
+  description?: LocalizedString;
+  fields: OrderedMap<EntityField>;
+}
+type ChildDisplayMode = "table" | "timeline" | "list" | "cards";
+interface TimelineConfig {
+  type_field?: string;
+  time_field?: string;
+  summary_field?: string;
+  content_field?: string;
+  author_field?: string;
+  direction_field?: string;
+  intent_field?: string;
+  scroll?: boolean;
+  auto_scroll?: "none" | "bottom" | "top";
+}
+interface CardsConfig {
+  columns_count?: number;
+  header_field?: string;
+  badge_field?: string;
+}
+interface ChildQuickAdd {
+  fields: string[];
+  defaults?: Record<string, unknown>;
+  placeholder?: LocalizedString;
+}
+interface ChildDisplay {
+  name: LocalizedString;
+  description?: LocalizedString;
+  icon?: string;
+  mode?: ChildDisplayMode;
+  columns?: string[];
+  sort?: string;
+  limit?: number;
+  timeline?: TimelineConfig;
+  cards?: CardsConfig;
+  editable?: boolean;
+  searchable?: boolean;
+  filters?: string[];
+  position_field?: string;
+  /**
+   * Row interaction for `mode: table`.
+   * - `navigate`: identity cell (first column) is a link to the child's
+   *   detail; other cells read-only. Default for associated entities
+   *   (child has its own detail screen).
+   * - `inline_edit`: click a cell to edit it; typing auto-saves after a
+   *   500ms debounce. One active cell at a time.
+   * - `row_edit`: a per-row Edit button puts the whole row into edit mode
+   *   (all editable cells become inputs); an explicit Confirm/Cancel pair
+   *   commits or discards. Nothing persists until Confirm - same flow as
+   *   the "Add row" draft.
+   * - `readonly`: pure display.
+   */
+  interaction?: "navigate" | "inline_edit" | "row_edit" | "readonly";
+}
+interface ChildRelation {
+  entity: string;
+  foreign_key: string | string[];
+  display?: ChildDisplay;
+  quick_add?: ChildQuickAdd;
+}
+interface StatusDef {
+  code: string;
+  name: LocalizedString;
+  description?: LocalizedString;
+  color?: string;
+  is_final?: boolean;
+}
+interface StatusGroupDef {
+  name: LocalizedString;
+  description?: LocalizedString;
+  is_main?: boolean;
+  initial: string;
+  statuses: StatusDef[];
+  transitions?: Record<string, string[]>;
+  display_mode?: "pill" | "stepper";
+}
+interface PropertyDef {
+  name: LocalizedString;
+  description?: LocalizedString;
+  type: string;
+  display?: EntityField["display"];
+  values?: EntityField["values"];
+  enum?: string;
+  ref?: RefConfig;
+  structure?: string;
+  readonly?: boolean;
+}
+interface EnumDef {
+  name: LocalizedString;
+  description?: LocalizedString;
+  values: Array<{
+    code: string;
+    name: LocalizedString;
+    description?: LocalizedString;
+    color?: string;
+  }>;
+}
+interface ParameterDef {
+  name: LocalizedString;
+  description?: LocalizedString;
+  type: string;
+  structure?: string;
+  default?: unknown;
+  is_public?: boolean;
+  category?: string;
+  /** Override scopes accepted on writes. Subset of: env, tenant, role, user, object. Empty = all. */
+  scopes?: string[];
+  /** Members of a closed type - `enum`, or an enum-backed `string_array`. Resolved
+   *  at load whether declared inline or by naming a shared enum, so this is the set
+   *  the platform enforces. Same shape a field's members have. */
+  values?: EntityField["values"];
+  /** The shared enum this parameter names, when it names one. `values` is what to render. */
+  enum?: string;
+}
+interface AssociationDisplay {
+  name?: LocalizedString;
+  description?: LocalizedString;
+  icon?: string;
+}
+interface AssociationDef {
+  target: string;
+  display?: AssociationDisplay;
+  source: string;
+  code: string;
+}
+interface EntityMutations {
+  create?: boolean;
+  update?: boolean;
+  delete?: boolean;
+  restore?: boolean;
+}
+interface EntityVariant {
+  name?: string;
+  when?: FilterNode[];
+  actions?: string[];
+}
+/** A set of CRUD op flags, each present or absent. The YAML-decoded shape of
+ *  an entity's `public` opt-out block (deny-by-default authorization). A flag being true means that op is open to ALL authenticated
+ *  callers with no grant required. Mirrors engine.OpSet. On the /api/schema
+ *  wire it always serializes as this object (never a bare bool, even though
+ *  YAML accepts `public: true`). */
+interface OpSet {
+  read?: boolean;
+  write?: boolean;
+  delete?: boolean;
+}
+interface CardSpec {
+  title_field?: string;
+  subtitle_field?: string;
+  badge_fields?: string[];
+  fields?: string[];
+  meta_fields?: string[];
+  hide_empty_fields?: boolean;
+  max_body_fields?: number;
+}
+interface Entity {
+  table: string;
+  read_sources?: string[];
+  primary_key?: string[];
+  virtual?: boolean;
+  readonly?: boolean;
+  mutations?: EntityMutations;
+  default_timezone?: string;
+  display: {
+    name: LocalizedString;
+    name_plural: LocalizedString;
+    description?: LocalizedString;
+    icon: string;
+    display_field?: string;
+    display_template?: string;
+    empty_state?: EmptyStateDef;
+  };
+  card?: CardSpec;
+  fields: OrderedMap<EntityField>;
+  filter_operators: Record<string, string[]>;
+  soft_delete?: string;
+  tenant_key?: string;
+  children?: ChildRelation[];
+  status_groups?: Record<string, StatusGroupDef>;
+  /** Computed by the server: this entity's rows are evidence-covered (an
+   *  `evidence:` block, or an audit table the core audit source covers). Drives
+   *  the evidence panel / `?expand=evidence` the same way `status_groups` drives
+   *  the statuses surface. Absent for uncovered entities. */
+  evidence_covered?: boolean;
+  properties?: Record<string, PropertyDef>;
+  search_fields?: string[];
+  actions?: Record<string, Action>;
+  variants?: OrderedMap<EntityVariant>;
+  /**
+   * Platform-default action codes the engine must NOT inject for this entity
+   * (`__new`, `__edit`, `__create`, ...). Declared in the entity's YAML.
+   *
+   * A disabled `__new` closes the CREATE ROUTE too, not only the toolbar
+   * button: `<list>/new` is the detail route with the literal id `new`, so
+   * without this the form the removed button pointed at still rendered for
+   * anyone who typed the address or kept a bookmark.
+   */
+  disable_defaults?: string[];
+  handlers?: Record<string, HandlerDef>;
+  associations?: Record<string, AssociationDef>;
+  files?: OrderedMap<FileFieldDef>;
+  detail_screen?: string;
+  /** Standard CSV export gate. Absent block (or absent `enabled`) means export is enabled. Only an
+   *  explicit `enabled: false` opts out, mirroring the Go ExportEnabled()
+   *  helper. Same shape ships on Screen for per-screen overrides. */
+  export?: ExportConfig;
+  /** At most one row visible per caller. Loader requires either a
+   *  caller-bound `prefilter` or `access: self` to back this. Frontend
+   *  routes a singleton entity's detail screen at the screen's declared
+   *  `route:` without a `:id` segment, and skips list-route registration. */
+  singleton?: boolean;
+  /** Carrier scope its `$params` writes land under (e.g. my_tenant -> "tenant",
+   *  profile -> "user"). Absent = writes land under the entity's own code. Used
+   *  by ParamsBlock to compute the attachable parameter set. */
+  params_scope?: string;
+  /** Server-enforced WHERE applied unconditionally on every read/write.
+   *  Values may be literal scalars
+   *  OR `$caller.*` expressions (`$caller.user_id`, `$caller.tenant_id`)
+   *  resolved at request time. Security boundary, not a UX hint. */
+  prefilter?: Record<string, unknown>;
+  /** Hard entity-wide access tier gate (checked BEFORE the deny-by-default
+   *  read/write decision). `"self"` restricts every read/write to rows where
+   *  the field marked `owner: true` matches the caller's user id (chokepoint +
+   *  with_check). `"tenant_admin"` admits any administrative standing in the
+   *  active tenant (superadmin / tenant_owner / any role grant). `"superadmin"`
+   *  admits only the platform-wide god flag. Empty = no tier floor (standard
+   *  RBAC). The legacy `"platform_admin"` alias was removed. */
+  access?: "self" | "tenant_admin" | "superadmin";
+  /** Deny-by-default authorization. Absent = every op
+   *  requires its `entity:<code>:<op>` grant. `public.<op>: true` opts that op
+   *  out of the grant requirement, opening it to all authenticated callers
+   *  (NOT anonymous). The Entity.Access floor is checked first and is never
+   *  waived by `public`. Mirrors engine.Entity.Public (*OpSet). The wire form
+   *  is always the object shape (never a bare bool). Replaces the removed
+   *  boolean `permissions`. */
+  public?: OpSet;
+  /**
+   * Optional structural tree for placing and grouping actions across all
+   * placement slots. Absent = runtime composes a flat list from all actions
+   * matching each slot's visibility[], sorted by position ascending.
+   * Server delivers RBAC-pruned nodes in tagged-union wire format.
+   */
+  action_layout?: ActionLayoutNode[];
+  /**
+   * Per-caller classification access
+   * decision keyed by field name. Only present for entities that
+   * declare at least one classified field; absent on non-classification
+   * entities so the wire stays byte-equivalent for non-classification
+   * deployments. Frontend reads this map to render the locked-widget
+   * badge, disable write inputs, and surface the required_permission
+   * hint to the user.
+   */
+  field_access?: Record<string, FieldAccessInfo>;
+  /**
+   * Per-entity realtime opt-in. When true the entity is in the CDC
+   * publication, its list views auto-update from the SSE stream, and the
+   * toolbar shows a green "Live" indicator. Absent or false (default OFF)
+   * means the entity is not live: no indicator, and the always-present
+   * manual refresh control is the only freshness mechanism. Server emits
+   * this with `omitempty`, so `false` arrives as absent.
+   */
+  realtime?: boolean;
+  /**
+   * Per-entity row-count strategy for list views. "exact" (default, also
+   * the meaning of absent) shows an exact total; "estimated" shows an
+   * O(1) query-planner estimate, rendered coarse (~3.6M) for high-volume
+   * tables. Independent of `realtime`. The SDK keys list-view count
+   * precision on the response `meta.count_mode`, not this field, so a
+   * forced exact count still renders precisely.
+   */
+  count?: "exact" | "estimated";
+  /**
+   * Computed (server-side, never author-set) pagination mode the generated
+   * admin list MUST use: "offset" (numbered pages) or "cursor" (keyset /
+   * infinite scroll). "cursor" iff the entity declares `persistence.archive`
+   * AND the deployment has ClickHouse wired at boot - a cross-store hot+cold
+   * read cannot offset-paginate. Absent means "offset" (every plain Postgres /
+   * ClickHouse-only / ClickHouse-disabled-archive entity). The SDK branches the
+   * list UI on this.
+   */
+  list_pagination?: "offset" | "cursor";
+  /**
+   * Static, per-caller document-generation capability computed from the
+   * SYSTEM document template registry at schema projection (registry-only,
+   * no DB read, no ETag impact - system templates are boot-static and are
+   * covered by the schema fingerprint). Absent (or both flags falsy) means
+   * no system template applies for this caller/tenant/entity - the
+   * frontend's Generate affordance renders nothing UNLESS a tenant-uploaded
+   * template is found via the lazy `document.templates.available` runtime
+   * probe (tenant templates are runtime data and are never baked into the
+   * schema). `generate_one` gates the detail-scope toolbar; `generate_many`
+   * gates the list-scope toolbar.
+   */
+  documents?: {
+    generate_one?: boolean;
+    generate_many?: boolean;
+  };
+}
+interface ExportConfig {
+  enabled?: boolean;
+}
+declare function getPrimaryKeyFields(entity: Entity): string[];
+type PkValues = Record<string, string>;
+declare function extractPkValues(entity: Entity, record: Record<string, unknown>): PkValues;
+declare function pkValuePartsToId(values: string[]): string;
+declare function pkValuesToId(pkValues: PkValues): string;
+declare function pkValuesToDetailId(entity: Entity, pkValues: PkValues): string;
+declare function pkValuesFromId(id: string, expectedCount: number): string[] | null;
+declare function resolveDetailRoute(list: Pick<Screen, "detail_screen"> | undefined, entity: Pick<Entity, "detail_screen"> | undefined, allScreens: Record<string, {
+  route?: string;
+}> | undefined): string | null;
+declare function buildDetailHrefFromId(list: Pick<Screen, "detail_screen">, id: string, entity: Pick<Entity, "detail_screen"> | undefined, allScreens: Record<string, {
+  route?: string;
+}> | undefined): string | null;
+declare function buildEntityDetailHref(list: Pick<Screen, "detail_screen">, entity: Entity | undefined, allScreens: Record<string, {
+  route?: string;
+}> | undefined, pkValues: PkValues): string | null;
+declare function buildRowDetailHref(list: Pick<Screen, "detail_screen">, entity: Entity | undefined, allScreens: Record<string, {
+  route?: string;
+}> | undefined, row: Record<string, unknown>): string | null;
+type SizeValue = string;
+interface SectionBadgeConfig {
+  text: LocalizedString;
+  tone?: "indigo" | "emerald" | "amber" | "rose" | "sky" | "violet" | "slate" | "teal";
+  dot?: boolean;
+}
+interface SectionNode {
+  name: LocalizedString;
+  items: LayoutNode[];
+  collapsed?: boolean;
+  columns?: number;
+  icon?: string;
+  badge?: SectionBadgeConfig;
+  emphasis?: "primary" | "secondary";
+  hide_empty_fields?: boolean;
+}
+interface RowConfig {
+  items: LayoutNode[];
+  gap?: number;
+  resizable?: boolean;
+  stack_below?: number | "never";
+  width?: SizeValue;
+  height?: SizeValue;
+}
+interface ColumnConfig {
+  items: LayoutNode[];
+  gap?: number;
+  width?: SizeValue;
+  height?: SizeValue;
+}
+interface TabsConfig {
+  items: LayoutNode[];
+}
+interface WidgetNode {
+  type: string;
+  inputs?: Record<string, string>;
+  options?: Record<string, unknown>;
+}
+interface LayoutField {
+  code: string;
+  actions?: Action[];
+  structure?: string;
+  detail_screen?: string;
+}
+interface LayoutNode {
+  row?: RowConfig;
+  column?: ColumnConfig;
+  tabs?: TabsConfig;
+  section?: SectionNode;
+  children?: string;
+  associated?: string;
+  foreign_key?: string;
+  properties?: true | string[];
+  statuses?: true | string[];
+  fields?: LayoutField[];
+  widget?: WidgetNode;
+  width?: SizeValue;
+  height?: SizeValue;
+  min_width?: string;
+  max_width?: string;
+  label?: LocalizedString;
+  icon?: string;
+  mode?: ChildDisplayMode;
+  columns?: string[];
+  sort?: string;
+  limit?: number;
+  quick_add?: ChildQuickAdd;
+  timeline?: TimelineConfig;
+  cards?: CardsConfig;
+  editable?: boolean;
+  searchable?: boolean;
+  filters?: string[];
+  position_field?: string;
+  interaction?: "navigate" | "inline_edit" | "row_edit" | "readonly";
+}
+interface AuditLineDef {
+  label: LocalizedString;
+  at?: string;
+  by?: string;
+}
+interface AuditConfig {
+  enabled?: boolean;
+  lines?: AuditLineDef[];
+}
+/** Resolved per-screen visibility decision (deny-by-default authorization).
+ *  Computed by the engine at load - authors write
+ *  `public` / `required_permission`, never this. `public` and
+ *  `required_permission` are mutually exclusive; `source` is the audit
+ *  provenance (authored:public | authored | authored->public |
+ *  derived:public-entity | derived:entity | derived:screen). Mirrors
+ *  engine.ScreenVisibility. */
+interface ScreenVisibility {
+  public: boolean;
+  required_permission: string;
+  source: string;
+}
+type ViewportKey = "phone" | "tablet" | "desktop";
+type ListPresentation = "table" | "cards";
+type RecordListPresentation = "split" | "drilldown" | "stacked";
+type DetailTabsPresentation = "sections" | "scroll";
+type DetailSidebarPresentation = "inline" | "hidden";
+type RelatedRecordsPresentation = "cards" | "table";
+interface ResponsiveDetailLayout {
+  header_card?: boolean;
+  tabs?: DetailTabsPresentation;
+  sidebar?: DetailSidebarPresentation;
+  related_records?: RelatedRecordsPresentation;
+}
+interface ResponsiveListBranch {
+  presentation?: ListPresentation;
+}
+interface ResponsiveDetailBranch {
+  header_card?: boolean;
+  tabs?: DetailTabsPresentation;
+}
+interface ScreenResponsiveViewport {
+  presentation?: ListPresentation | RecordListPresentation;
+  layout?: ResponsiveDetailLayout;
+  list?: ResponsiveListBranch;
+  detail?: ResponsiveDetailBranch;
+}
+type ScreenResponsive = Partial<Record<ViewportKey, ScreenResponsiveViewport>>;
+interface ScreenVariant {
+  name?: string;
+  when?: FilterNode[];
+  items?: LayoutNode[];
+  sidebar?: LayoutNode[];
+  sidebar_width?: string;
+  highlights?: string[];
+  audit?: AuditConfig;
+  actions?: string[];
+  row_actions?: string[];
+  action_layout?: ActionLayoutNode[];
+  card?: CardSpec;
+  quick_peek?: QuickPeekConfig;
+}
+interface Screen {
+  type: "list" | "detail" | "custom" | "record_list";
+  entity?: string;
+  route: string;
+  component?: string;
+  /** Deny-by-default authorization. CUSTOM (entity-less) screens only: true
+   *  makes the screen visible to all authenticated callers (data inside still
+   *  gates per entity). A load error on an entity-bound screen. Mirrors
+   *  engine.Screen.Public (*bool). */
+  public?: boolean;
+  /** Overrides the derived visibility rule for this screen (any grant string,
+   *  typically `screen:<code>` to retarget or to tighten an entity-bound
+   *  screen below its entity read). REPLACES the derived rule, not ANDs it. */
+  required_permission?: string;
+  /** Resolved visibility (engine-computed at load; never authored). */
+  visibility?: ScreenVisibility;
+  display?: {
+    name: LocalizedString;
+    /** Localized explanation of the screen, surfaced via the list-header info
+     *  affordance (falls back to the entity description). Optional. */
+    description?: LocalizedString;
+    icon: string;
+  };
+  columns?: string[];
+  default_columns?: string[];
+  card?: CardSpec;
+  responsive?: ScreenResponsive;
+  filters?: string[];
+  default_filters?: string[];
+  search_fields?: string[];
+  sort_default?: string;
+  actions?: string[];
+  row_actions?: string[];
+  variants?: OrderedMap<ScreenVariant>;
+  items?: LayoutNode[];
+  sidebar?: LayoutNode[];
+  sidebar_width?: string;
+  highlights?: string[];
+  audit?: AuditConfig;
+  self?: boolean;
+  list_width?: string;
+  list_resizable?: boolean;
+  detail_screen?: string;
+  fixed_filters?: Record<string, unknown>;
+  /** Per-screen override of field-level filter_special_values, keyed by filter
+   *  field code. Append/replace/clear the entity field's declared values for
+   *  just this screen. Mirrors engine.Screen.FilterSpecialValues. */
+  filter_special_values?: Record<string, ScreenFilterSpecialValues>;
+  /** Per-field operator lists, keyed by filter field code, published by the
+   *  server from the ONE vocabulary the query builder enforces
+   *  (engine.OperatorsByFieldType, plus the $status / $property sets). The
+   *  filter drawer renders exactly these; it keeps no table of its own,
+   *  because a client-side guess had already diverged - array, multilang,
+   *  json and bytes fields were offered two operators the builder rejects
+   *  and denied `contains`, the one that works. */
+  filter_operators?: Record<string, string[]>;
+  views?: ViewDefinition[];
+  /** Code of the view this list OPENS on. A starting point, never a bound: the
+   *  switcher still offers every other view and the unfiltered "All", and a
+   *  viewer's own default view wins over it. */
+  default_view?: string;
+  /** Action slot promotion for list screens (rule-of-2). UI honors first 2.
+   *  The detail-header `primary_record_actions` was removed; use action_layout. */
+  primary_actions?: string[];
+  primary_bulk_actions?: string[];
+  /** "open" (default) navigates to detail; "peek" opens QuickPeek drawer. */
+  on_row_click?: "open" | "peek";
+  quick_peek?: QuickPeekConfig;
+  inline_edit?: InlineEditConfig;
+  column_overrides?: Record<string, ColumnSpec>;
+  activity_rail?: ActivityRailConfig;
+  /** Per-screen override for the CSV export gate. Same shape as Entity.export.
+   *  Either gate being false hides the toolbar Export menu and makes the
+   *  POST endpoint return 403 EXPORT_DISABLED. */
+  export?: ExportConfig;
+  /**
+   * Optional per-screen structural tree for placing and grouping actions.
+   * When set, fully replaces entity.action_layout for this screen.
+   * Absent = inherit entity.action_layout (then default-flat if also absent).
+   * Server delivers RBAC-pruned nodes in tagged-union wire format.
+   */
+  action_layout?: ActionLayoutNode[];
+}
+interface QuickPeekConfig {
+  enabled?: boolean;
+  width?: number;
+  /**
+   * Explicit list of field codes to show. Highest precedence. When absent,
+   * `sections` is consulted; when that's also absent the platform falls back
+   * to all simple scalar fields on the entity (capped at 8).
+   */
+  fields?: string[];
+  /** Section names from the detail-layout. Their `fields:` get flattened. */
+  sections?: string[];
+  inline_editable?: boolean;
+  primary_action?: string;
+}
+interface InlineEditConfig {
+  enabled?: boolean;
+  /** dblclick | enter | always */
+  trigger?: string;
+}
+interface ColumnSpec {
+  inline_edit?: boolean;
+  width?: string;
+}
+interface ActivityRailConfig {
+  children: string;
+  /** left | right (default right) */
+  position?: string;
+  width?: number;
+}
+/** System view (preset) defined in screen YAML. Read-only. */
+interface ViewDefinition {
+  code: string;
+  name: LocalizedString;
+  description?: LocalizedString;
+  icon?: string;
+  filters?: FilterNode[];
+  columns?: string[];
+  sort?: string;
+}
+interface NavNode {
+  screen?: string;
+  name?: LocalizedString;
+  icon?: string;
+  items?: NavNode[];
+  area?: string;
+  badge?: string;
+  children?: NavNode[];
+}
+interface AreaDef {
+  code: string;
+  name?: LocalizedString;
+  icon?: string;
+  position?: number;
+  home_screen?: string;
+  required_permission?: string;
+}
+interface AccentDef {
+  color?: string;
+  color_2?: string;
+  soft?: string;
+  ring?: string;
+  on_dark?: string;
+  on_light?: string;
+}
+interface HandlerParamDisplay {
+  name?: LocalizedString;
+  description?: LocalizedString;
+  widget?: string;
+}
+interface HandlerParam {
+  /** Populated by the schema hydrator from the enclosing map key. */
+  name?: string;
+  type?: string;
+  required?: boolean;
+  default?: unknown;
+  hidden?: boolean;
+  enum?: string;
+  values?: Array<{
+    code: string;
+    name: LocalizedString;
+    description?: LocalizedString;
+    color?: string;
+  }>;
+  /** `type: structure` (or structure-shaped json) param target: the top-level
+   *  structure code whose fields the dialog renders as a nested form. */
+  structure?: string;
+  /** `type: ref` param target. Scalar entity-code string (shorthand) OR a
+   *  structured RefConfig (non-id lookup / display). Normalize via
+   *  normalizeRefConfig before use. */
+  ref?: string | RefConfig;
+  display?: HandlerParamDisplay;
+  /**
+   * Narrows the param's option set. Values may be literals or templates
+   * using the ui_steps interpolation vocabulary (e.g. "${params.other}").
+   * Semantics are type-specific: for type="status", a "status_group" key
+   * selects the group whose statuses are offered.
+   */
+  filter?: Record<string, string>;
+}
+interface ActionCondition {
+  status?: string[];
+  field?: string;
+  op?: string;
+  value?: unknown;
+}
+interface UISetFieldStep {
+  target: string;
+  value: unknown;
+}
+interface UIShowToastStep {
+  kind?: "success" | "error" | "info";
+  message: string;
+}
+interface UIStep {
+  copy_to_clipboard?: string;
+  set_field?: UISetFieldStep;
+  focus_field?: string;
+  show_toast?: UIShowToastStep;
+}
+/**
+ * Leaf node in an action_layout tree. References a single action by code.
+ * Wire format: {"kind": "action", "code": "<code>"}
+ */
+interface ActionLayoutLeaf {
+  kind: "action";
+  code: string;
+}
+/**
+ * Branch node in an action_layout tree. Groups child nodes under a labelled dropdown.
+ * Wire format: {"kind": "group", "name": {...}, "icon": "...", "items": [...]}
+ * Items is always non-empty (enforced by loader).
+ */
+interface ActionLayoutGroup {
+  kind: "group";
+  name?: LocalizedString;
+  icon?: string;
+  items: ActionLayoutNode[];
+}
+/**
+ * Discriminated union of all action_layout tree nodes.
+ * Narrow via `node.kind === "action"` (leaf) or `node.kind === "group"` (branch).
+ */
+type ActionLayoutNode = ActionLayoutLeaf | ActionLayoutGroup;
+/**
+ * Single row-state condition for visible_if / enabled_if / conditions.
+ * Operators: eq | ne | in | not_in | gt | lt | ge | le.
+ */
+interface ActionConditionEntry {
+  field?: string;
+  op?: string;
+  value?: unknown;
+  status?: string[];
+}
+/**
+ * Array of row-state conditions with AND semantics. YAML accepts both single
+ * object and array form (see Go ActionConditionList unmarshal); wire format
+ * from server is always array (server normalizes during schema response).
+ */
+type ActionConditionList = ActionConditionEntry[];
+interface Action {
+  /**
+   * Server-side handler code. One of four dispatch fields.
+   * Reason: the new wire format encodes dispatch mode by which field is set
+   * (handler | association | widget | href), so an explicit `type` enum is
+   * redundant and was removed. Exactly one of the four should be set per action.
+   */
+  handler?: string;
+  /**
+   * Association code for nav-only actions that navigate to a related list.
+   * Reason: same dispatch-by-field-presence rule.
+   */
+  association?: string;
+  /**
+   * SDK widget registry name. The SDK has no widget registry yet: an action
+   * carrying `widget` logs a warning and falls back to `onRun`.
+   * Reason: lets actions render bespoke UI (e.g. inline picker) instead of
+   * server-handled forms, without inventing a new entity per widget.
+   */
+  widget?: string;
+  /**
+   * Client-side navigation URL template (supports `${id}` and other row tokens).
+   * Reason: replaces the implicit "edit"/"create" type enum - any href-driven
+   * action (open a custom screen, deep-link a report) uses this field; the
+   * server never dispatches it.
+   */
+  href?: string;
+  /**
+   * Widget-specific opaque metadata. Schema/Action loader passes through
+   * untouched; the widget consumes its own keys.
+   * Reason: keeps the Action shape stable as new widgets ship without
+   * growing the typed surface for each one.
+   */
+  config?: Record<string, unknown>;
+  entity?: string;
+  display: {
+    name: LocalizedString;
+    icon: string;
+    /**
+     * Promotes the action to a header button (vs. dropdown item).
+     * Reason: explicit per-action UX control replaces the old position<=10
+     * heuristic, lets schema authors mark their headline action even when
+     * other actions sort earlier.
+     */
+    primary?: boolean;
+    /**
+     * Render as icon-only button (no label text).
+     * Reason: lets a dense toolbar host high-frequency actions without
+     * cluttering the bar with labels; tooltip still shows display.name.
+     */
+    icon_only?: boolean;
+    /**
+     * Button size hint. Default "md".
+     * Reason: secondary toolbars (associated blocks, inline editors) need
+     * smaller buttons than primary header bars - the schema author picks.
+     */
+    size?: "sm" | "md" | "lg";
+    /**
+     * Keyboard shortcut hint (e.g. "Cmd+S"), carried on the wire. The SDK
+     * neither renders it nor binds the key yet.
+     */
+    shortcut?: string;
+    /**
+     * Localized explanation of what the action does. Surfaces as the control
+     * tooltip (precedence: disabled-reason > description > name) and the
+     * ActionDialog subtitle. Optional; absent renders exactly as before.
+     * Supersedes the removed `help` field.
+     */
+    description?: LocalizedString;
+  };
+  visibility?: string[];
+  confirmation?: LocalizedString;
+  conditions?: ActionCondition[];
+  /**
+   * Ordering within a placement slot and overflow priority. Lower = earlier
+   * in bar AND last to overflow. Default 0; ties broken by action code.
+   * Convention: step by 10 so a later action fits between two.
+   */
+  position?: number;
+  /**
+   * Hide the action when condition does not hold against current row.
+   * Distinct from RBAC hide and from `enabled_if` disable. AND semantics
+   * across array elements.
+   */
+  visible_if?: ActionConditionList;
+  /**
+   * Disable the action (greyed out + tooltip) when condition does not hold.
+   * For bulk-mode multi-row selection, disabled if ANY selected row fails.
+   */
+  enabled_if?: ActionConditionList;
+  /**
+   * Localized tooltip shown when action is disabled by `enabled_if`.
+   * Required when `enabled_if` is set; the schema loader enforces it.
+   */
+  enabled_if_reason?: LocalizedString;
+  /** Forces confirm + danger styling. */
+  destructive?: boolean;
+  /** UI shows a toast instead of a blocking result modal; adds a navigation link if progress_screen is set. */
+  long_running?: boolean;
+  /** Screen code to navigate to after a long_running action starts (resolved via schema.screens). */
+  progress_screen?: string;
+  resolved_params?: OrderedMap<HandlerParam>;
+  /**
+   * Default values of params marked hidden+default by the action. The UI
+   * seeds formData with these so filter templates resolve references to
+   * prefilled siblings (e.g. "${params.status_group}") and so the
+   * submission payload includes them. Not rendered in the modal.
+   */
+  resolved_hidden_defaults?: Record<string, unknown>;
+  ui_steps?: UIStep[];
+  /**
+   * Server-derived: the action needs at least one selected row to be
+   * meaningful (the list toolbar greys it while nothing is selected). Derived
+   * from the handler's id-arity contract (cannot run without object IDs),
+   * association mode, or an href `${id}` row-link. ABSENT means the server did
+   * not derive it (older server, or widget/ui_steps modes) - consumers MUST
+   * fall back to the list_floatbar slot proxy, NOT treat absent as false. See
+   * actionRequiresSelection in lib/actions.ts.
+   */
+  requires_selection?: boolean;
+}
+interface LanguageDef {
+  code: string;
+  name: LocalizedString;
+}
+interface HandlerDef {
+  code: string;
+  type: string;
+  entity?: string;
+  display?: {
+    name?: LocalizedString;
+    description?: LocalizedString;
+    icon?: string;
+  };
+  params?: OrderedMap<HandlerParam>;
+}
+interface Schema {
+  languages: LanguageDef[];
+  language: string;
+  deployment_language: string;
+  structures: Record<string, StructureDef>;
+  entities: Record<string, Entity>;
+  screens: Record<string, Screen>;
+  navigation: NavNode[];
+  actions: Record<string, Action>;
+  handlers?: Record<string, HandlerDef>;
+  enums: Record<string, EnumDef>;
+  parameters: Record<string, ParameterDef>;
+  messages?: Record<string, LocalizedString>;
+  /**
+   * Declared error types, code -> title per language. For rendering a STORED
+   * code - on an agent turn, a job row, an audit row - in the reader's
+   * language. An error answering a request carries its own title in the
+   * response and needs none of this.
+   *
+   * Errors are NEVER declared under `messages`: a failure has a type, and a
+   * type has a title.
+   */
+  errors?: Record<string, LocalizedString>;
+  areas?: AreaDef[];
+  accents?: Record<string, AccentDef>;
+  /**
+   * data_classifications catalog keyed by
+   * tier code — display name + description + audit_on_read flag + icon
+   * + sod_protected flag. Absent when the consumer declares no tiers
+   * (preserves byte-equivalent wire shape for non-classification
+   * deployments). Frontend resolves the localized tier name from this
+   * map when rendering locked-widget badges.
+   */
+  classifications?: Record<string, ClassificationTierDef>;
+  /**
+   * Consumer-declared icon glyphs, keyed by the name referenced at `icon:`
+   * call sites. Carries ONLY declared/overridden entries (the built-in ~119
+   * travel as bare names, never here); absent when no module declares an
+   * `icons:` block. The Admin loads this into the runtime icon registry
+   * (setIconRegistry) so custom glyphs render across the chrome.
+   */
+  icons?: Record<string, IconDef>;
+}
+/**
+ * One entry in the top-level classifications map.
+ * Mirrors engine.DataClassification.
+ */
+interface ClassificationTierDef {
+  name: LocalizedString;
+  description?: LocalizedString;
+  audit_on_read?: boolean;
+  icon?: string;
+  /**
+   * When true, the tier triggers stricter SoD controls: a platform owner's
+   * reveal emits a distinct audit code, role self-assignment is refused, and
+   * transitive role inheritance is hard-errored at load.
+   */
+  sod_protected?: boolean;
+}
+//#endregion
+//#region src/types/api.d.ts
+interface ListMeta {
+  /**
+   * Total matching rows. Present only when the request asked for a count
+   * (`count=with` / `count=only` / `count=exact`). Absent (undefined) on a
+   * window-only response (`count` omitted) - the page of rows arrives
+   * without ever blocking on the count. Treat `count_mode === undefined` as
+   * "no count yet" and ignore `total` then.
+   */
+  total?: number;
+  page: number;
+  per_page: number;
+  /** Present only when a count was computed (see `total`). */
+  total_pages?: number;
+  has_more?: boolean;
+  /**
+   * How `total` was produced: "exact" (an exact COUNT(*)) or "estimated"
+   * (an O(1) query-planner estimate). Absent when no count was computed.
+   * The SDK keys display precision on this, NOT on the entity schema, so a
+   * forced exact count renders precisely even on a `count: estimated`
+   * entity.
+   */
+  count_mode?: "exact" | "estimated";
+}
+interface ListResponse<T = Record<string, unknown>> {
+  data: T[];
+  meta: ListMeta;
+  $refs?: Refs;
+}
+interface DataResponse<T = Record<string, unknown>> {
+  data: T;
+  $refs?: Refs;
+}
+/**
+ * A failure, in RFC 9457 Problem Details form - the one shape every Declarion
+ * carrier sends. `type` is the identifier to branch on; its last path segment is
+ * identical in every deployment. `title` is the sentence to SHOW: the server
+ * already rendered it in this caller's language, and the browser holds no
+ * catalogue to render one itself. A type's declared members are TOP-LEVEL, which
+ * is why this is an index signature and not a fixed shape.
+ */
+interface ApiErrorBody {
+  type: string;
+  status?: number;
+  title: string;
+  /** This occurrence. A DIAGNOSTIC, not the headline - and absent for a failure nothing recognised. */
+  detail?: string;
+  instance?: string;
+  retryable: boolean;
+  [member: string]: unknown;
+}
+declare class ApiError extends Error {
+  status: number;
+  /** The identifier to compare - the type's last path segment, e.g. `entity.not_found`. */
+  code: string;
+  /** The full `type`, e.g. `/errors/entity.not_found`. */
+  type: string;
+  /** Whether the same call can succeed later. From the DECLARATION, never computed from a status. */
+  retryable: boolean;
+  /** The diagnostic for this occurrence. Never the headline a user reads. */
+  detail?: string;
+  /** Bulk operation item index (present on validation errors for array requests). */
+  index?: number;
+  /** The untouched body, so a caller can re-detect a shape this class does not model. */
+  raw?: unknown;
+  constructor(status: number, body: Partial<ApiErrorBody>, raw?: unknown);
+  /**
+   * A declared member of this error's type. ONE accessor, so the six known
+   * consumers (`constraint`, `row_version`, `did_you_mean`, `valid_parameters`,
+   * `threshold`, `width`) do not each invent an access pattern.
+   */
+  ext<T = unknown>(member: string): T | undefined;
+}
+/**
+ * Stable error codes for cursor-based list pagination. The server returns
+ * these on ValidationError{Field:"after"} when an `after` token cannot be
+ * resumed under current request conditions:
+ *
+ * - CURSOR_SEMANTICS_MISMATCH: the cursor was minted under different sort
+ *   semantics (multi-column ordering, NULL placement). Server bumped its
+ *   cursor format version since the cursor was issued.
+ * - CURSOR_LANGUAGE_CHANGED: the cursor was minted in one language and the
+ *   request now reads in another. Issued so multilang sort cannot silently
+ *   re-order mid-pagination.
+ *
+ * UX contract for both: clear the `after` token and refetch page 1 under
+ * the current conditions. EntityClient.list does this transparently;
+ * direct apiFetch callers can recognise these codes to drive their own
+ * retry logic.
+ */
+declare const CURSOR_SEMANTICS_MISMATCH = "cursor.semantics_mismatch";
+declare const CURSOR_LANGUAGE_CHANGED = "cursor.language_changed";
+/** True if the error is a recoverable cursor-stale signal that warrants
+ *  refetching page 1 instead of surfacing to the user. */
+declare function isCursorStaleError(err: unknown): boolean;
+type TenantEnv = "production" | "staging" | "dev" | (string & {});
+interface Tenant {
+  id: string;
+  code: string;
+  name: string;
+  role: string;
+  env?: TenantEnv;
+  /**
+   * Whether the caller has a `tenant_users` row for this tenant. Always
+   * true for non-superadmins. For superadmins, `auth.list_tenants` also
+   * returns non-membership tenants reachable via cross-tenant authority;
+   * the switcher splits them into a separate "All tenants" section.
+   */
+  is_member?: boolean;
+}
+interface AuthUser {
+  id: string;
+  email: string;
+  display_name: string;
+  is_active: boolean;
+  roles: string[];
+  permissions?: string[];
+  tenant?: Tenant;
+  /** Populated only when the request is acting under an impersonation session. */
+  impersonation?: ImpersonationInfo;
+  created_at: string;
+  updated_at: string;
+}
+/**
+ * ImpersonationInfo is the read-side projection of the active session
+ * surfaced by auth.me. Drives the banner, topbar chip, viewport frame,
+ * and the "Exit impersonation" menu item.
+ */
+interface ImpersonationInfo {
+  session_id: string;
+  real_user_id: string;
+  real_user_email?: string;
+  target_user_id: string;
+  target_user_email?: string;
+  reason: string;
+  started_at: string;
+  expires_at: string;
+}
+interface LoginResponse {
+  expires_at: string;
+  user: AuthUser;
+  tenant?: Tenant;
+}
+interface CheckSetupResponse {
+  needs_setup: boolean;
+}
+interface StatusInfo {
+  group_code: string;
+  status_code: string;
+  status_name: LocalizedString;
+  color?: string;
+  set_by?: string;
+  set_at: string;
+  note?: string;
+}
+interface PropertyValue {
+  property_code: string;
+  name: LocalizedString;
+  type: string;
+  value: unknown;
+}
+interface PublicParam {
+  code: string;
+  name: LocalizedString;
+  type: string;
+  structure?: string;
+  category: string;
+  description?: LocalizedString;
+  value: unknown;
+}
+/** Per-app legal/support URL set rendered in the auth-shell footer. */
+interface PublicLegalLinks {
+  security_url?: string;
+  privacy_url?: string;
+  terms_url?: string;
+  docs_url?: string;
+}
+interface BrandingIdentity {
+  app_name?: string;
+  app_logo?: string;
+  app_initial?: string;
+  ai_name?: string;
+  wordmark?: string;
+  version_label?: string;
+  status_url?: string;
+  auth_tagline?: LocalizedString;
+  auth_subtagline?: LocalizedString;
+  auth_badges?: LocalizedString[];
+  legal_entity?: string;
+  workspace_domain?: string;
+  legal_links?: PublicLegalLinks;
+}
+/**
+ * Deploy-time identity exposed pre-login by /api/params/public so the
+ * auth shell can render real region/build values (no mockup placeholders).
+ * Each field is empty when unconfigured/unset; consumers hide the pill
+ * when the entire block is missing or empty.
+ */
+interface PublicMeta {
+  version?: string;
+  revision?: string;
+  build_time?: string;
+  region?: string;
+}
+/** Envelope returned by GET /api/params/public. */
+interface PublicParamsResponse {
+  parameters: PublicParam[];
+  accents?: Record<string, AccentDef>;
+  meta?: PublicMeta;
+}
+/**
+ * Wire envelope for GET /api/params/{code}.
+ *
+ * The server always responds with HTTP 200. `found:false` means the
+ * platform has no value for the code (undeclared, restricted-category,
+ * or no value at any resolution layer); the caller substitutes its own
+ * default. `found:true` means `value` is authoritative - even if it is
+ * null/zero (an explicit nil value is a real value, not absence).
+ *
+ * The default never crosses the wire; servers don't track caller
+ * defaults, so two callers with different defaults always see consistent
+ * server state.
+ */
+interface ParamLookup {
+  code: string;
+  found: boolean;
+  value?: unknown;
+  source?: "object" | "user" | "role" | "tenant" | "env" | "yaml";
+  type?: string;
+}
+interface ListParams {
+  page?: number;
+  per_page?: number;
+  sort?: string;
+  search?: string;
+  /** JSON filter nodes (recursive AND/OR tree). */
+  filters?: FilterNode[];
+  include_deleted?: boolean;
+  expand?: string[];
+  screen?: string;
+  /** Return bounded display previews for fields that declare display.list_preview. */
+  preview?: boolean;
+  /**
+   * Field whitelist. When set, the server returns only these columns plus
+   * primary-key field(s) (auto-injected server-side). Filters/search/sort
+   * still operate against all fields regardless of select. Omit to fetch
+   * every column (default, backwards-compatible).
+   */
+  select?: string[];
+  /**
+   * Row-count strategy for this request. Maps to the `?count=` query param.
+   *   omitted / "window" - rows only, no total (the page-window request;
+   *                        the table never blocks on a count).
+   *   "only"             - total only, no rows (the follow-up count request).
+   *   "with"             - rows + total, using the entity's declared strategy.
+   *   "exact"            - rows + forced exact total.
+   */
+  count?: "window" | "only" | "with" | "exact";
+}
+/** Cursor-based pagination metadata returned by v2 List. */
+interface V2Meta {
+  total: number;
+  limit: number;
+  has_more: boolean;
+  cursor?: string;
+  /** How `total` was produced: "exact" or "estimated". Absent when no count
+   *  was requested. A cross-store cursor total is always "estimated". */
+  count_mode?: string;
+  /** True when a count WAS requested but abandoned because the cold-tier count
+   *  would exceed the interactive scan bound (BC4b). The data window still
+   *  loaded; render NO total ("~N") - distinct from a real `total: 0`. */
+  count_unknown?: boolean;
+}
+/**
+ * Refs map: keyed by entity code (or $-prefixed virtual entity code),
+ * then by record ID, then field values.
+ * Example: { company: { "uuid-1": { id: "uuid-1", name: "Acme" } } }
+ */
+type Refs = Record<string, Record<string, Record<string, unknown>>>;
+/** Per-row status instance. */
+interface V2StatusInstance {
+  group_code: string;
+  status_code: string;
+  status_name?: Record<string, string>;
+  color?: string;
+  set_at?: string;
+  set_by?: string;
+  note?: string;
+}
+/** Per-row property instance. */
+interface V2PropertyInstance {
+  property_code: string;
+  value: unknown;
+  updated_at?: string;
+  updated_by?: string;
+}
+/** Per-row parameter override. */
+/**
+ * The last verification verdict of an evidence-covered row, shipped under the
+ * row's `$evidence` key (the evidence satellite, mirroring `$statuses`). Read
+ * cheaply from the stored verification result - never a live re-verify. Mirrors
+ * the Go `evidence.RowVerdict`. `verdict` is one of: `verified`, `unverified`,
+ * `tampered`, `indeterminate`, `outside_coverage`.
+ */
+interface EvidenceVerdict {
+  verdict: string;
+  verified_at?: string;
+  reason?: string;
+  seq?: number;
+  generation?: number;
+  covered: boolean;
+}
+interface V2ParamInstance {
+  param_code: string;
+  value: unknown;
+}
+/** v2 List response with cursor pagination and response-level $refs. */
+interface V2ListResponse<T = Record<string, unknown>> {
+  data: T[];
+  meta: V2Meta;
+  $refs?: Refs;
+}
+/** v2 List query parameters. */
+interface V2ListParams {
+  select?: string[];
+  expand?: string[];
+  sort?: string;
+  search?: string;
+  filters?: FilterNode[];
+  limit?: number;
+  after?: string;
+  include_deleted?: boolean;
+  /** Request the (estimated) total alongside the window (`?count=with`). The
+   *  cursor UI sends this on the FIRST window only; later windows omit it. */
+  count?: boolean;
+  /** Screen code, so the server applies that screen's `fixed_filters` (a
+   *  cursor list of a `fixed_filters` view, e.g. the audit auth-log, needs
+   *  the same server-side prefilter the offset list gets). */
+  screen?: string;
+  /** Return display-bounded (truncated) values for list cells, matching the
+   *  offset list's `preview: true`. */
+  preview?: boolean;
+}
+/** Per-field resolved display unit codes. */
+type Units = Record<string, string>;
+/**
+ * A raw entity row: an untyped bag of field values keyed by field code. The
+ * single canonical alias for `Record<string, unknown>` rows - import this
+ * instead of re-declaring a local `RowData`/`RowData`. `EnrichedRow` is the
+ * same bag plus typed `$`-prefixed sub-resources.
+ */
+type RowData = Record<string, unknown>;
+/** A row enriched with $-prefixed sub-resources (as returned by Get or write responses). */
+interface EnrichedRow extends RowData {
+  $refs?: Refs;
+  $files?: Record<string, HydratedFile | HydratedFile[] | null>;
+  $statuses?: V2StatusInstance[];
+  $properties?: V2PropertyInstance[];
+  $params?: V2ParamInstance[];
+  $children?: Record<string, Record<string, unknown>[]>;
+  $units?: Units;
+  $evidence?: EvidenceVerdict;
+}
+//#endregion
+//#region src/api/data.d.ts
+/** What a single-record read asks the server to compute beside the row. */
+interface GetEntityOptions {
+  expand?: readonly "evidence"[];
+}
+declare function deleteObject(entity: string, pkValues: PkValues | string): Promise<void>;
+declare function restoreObject(entity: string, pkValues: PkValues | string): Promise<void>;
+/**
+ * Action request body is flat: top-level keys are handler params. The only
+ * reserved control key is `object_ids` (array of object IDs for
+ * single/batch scope). The server resolves entity from the action's
+ * registration; the URL code is fully qualified ("entity.action" for
+ * entity-scoped, "action" for global).
+ */
+type ActionExecuteRequest = Record<string, unknown>;
+interface ActionExecuteResponse {
+  status: string;
+  result?: unknown;
+  audit_operation_id?: string;
+  object_count?: number;
+  /** IDs that succeeded (batch_mode: each responses). */
+  success?: string[];
+  /** Per-item errors (batch_mode: each responses with failures or partial). */
+  errors?: ActionItemError[];
+  /** Per-item skips (batch_mode: each responses where conditions filtered rows). */
+  skipped?: ActionItemSkip[];
+  /**
+   * The action's declared synchronous chain, when it has one. ABSENT means the
+   * action declares no such step - never that a step passed. A failed step does
+   * not change the action's own status: it committed, and an event is free to
+   * fail without undoing a committed write. So "saved" and "saved, and the work
+   * behind it did not run" are the same status and different reports.
+   */
+  events?: EventsReport;
+}
+/** What the platform says the action's synchronous chain did. */
+interface EventsReport {
+  failed_count?: number;
+  timed_out_count?: number;
+  job_ids?: string[];
+  /** In the handler's DECLARED step order, at every depth. */
+  failures?: EventFailure[];
+  /** What the response bounds dropped. Non-zero means there were more. */
+  failures_omitted?: number;
+}
+/** One declared step that did not do its work. */
+interface EventFailure {
+  step: number;
+  handler: string;
+  /** The id a per-object step died on. */
+  object?: string;
+  /** How many objects after it were never reached. */
+  not_attempted?: number;
+  error?: ApiErrorBody;
+  /** This step's OWN chain, when it declared one. */
+  events?: EventsReport;
+}
+interface ActionItemError {
+  id: string;
+  /** The failure, in the one shape every carrier sends. */
+  error: ApiErrorBody;
+}
+interface ActionItemSkip {
+  id: string;
+  reason: string;
+}
+/**
+ * Thrown by executeAction when the platform returns 4xx with the invoke:each
+ * batch shape (all items failed). Carries the per-item details so the UI can
+ * render a meaningful toast instead of a generic "request failed".
+ *
+ * Pre-dispatch failures (auth, unknown action, invoke-shape mismatch) keep
+ * throwing the standard ApiError; use `instanceof ActionBatchError` to
+ * distinguish.
+ */
+declare class ActionBatchError extends Error {
+  readonly status: number;
+  readonly response: ActionExecuteResponse;
+  constructor(status: number, response: ActionExecuteResponse);
+}
+/**
+ * Build a flat action body from handler params + optional object IDs.
+ * Promotes `ids` to the reserved `object_ids` key. Throws if a caller
+ * passes a param literally named `object_ids` (collision with the
+ * reserved control key).
+ */
+declare function buildActionBody(params: Record<string, unknown> | undefined, ids?: string[]): ActionExecuteRequest;
+/**
+ * Invoke an action. The URL `code` must be fully qualified for
+ * entity-scoped actions (e.g. `lead.archive`). For global actions it's the
+ * action code on its own (e.g. `auth.login`).
+ */
+declare function executeAction(code: string, body: ActionExecuteRequest): Promise<ActionExecuteResponse>;
+//#endregion
+//#region src/lib/viewport-category.d.ts
+type ViewportCategory = "phone" | "tablet" | "desktop";
+interface ResponsiveBreakpoints {
+  phoneMax: number;
+  tabletMax: number;
+  /**
+   * The height at or below which a viewport no wider than `tabletMax` is a
+   * phone held sideways. Required, never optional: a missing bound would
+   * silently restore the width-only rule, which is the defect it exists to
+   * remove.
+   */
+  landscapePhoneMaxHeight: number;
+}
+interface ResponsiveViewport {
+  width: number;
+  height: number;
+  touch?: boolean;
+}
+interface ResponsiveMode {
+  category: ViewportCategory;
+  width: number;
+  height: number;
+  isPhone: boolean;
+  isTablet: boolean;
+  isDesktop: boolean;
+  touch: boolean;
+}
+declare const DEFAULT_RESPONSIVE_BREAKPOINTS: ResponsiveBreakpoints;
+/**
+ * The device class, from BOTH viewport axes.
+ *
+ * A phone is a device, not a width. Read from width alone, the same phone is a
+ * phone upright and a tablet on its side - so rotating it swapped cards for a
+ * table, sections for tabs, and the compact header for the desktop one, all at
+ * once. The second clause is that device: no wider than a tablet AND short.
+ *
+ * Height is admitted only UNDER the tablet width ceiling, because a wide short
+ * window (a 1600x480 browser, a wide embed strip) is a desktop, and a height
+ * clause without the ceiling would reclassify it.
+ */
+declare function resolveViewportCategory(viewport: {
+  width: number;
+  height: number;
+  touch?: boolean;
+}, breakpoints?: ResponsiveBreakpoints): ViewportCategory;
+//#endregion
+//#region src/hooks/useResponsiveMode.d.ts
+interface ResponsiveModeProviderProps {
+  children: ReactNode;
+  breakpoints?: ResponsiveBreakpoints;
+  /**
+   * A measured viewport, substituted for `window`'s. Carries a WIDTH, from
+   * which the category is derived. Used by tests to place the app at a size.
+   *
+   * This is NOT how you force a device class - a forced class is not
+   * expressible as a width. Use `viewport` for that.
+   */
+  viewportOverride?: ResponsiveViewport;
+  /**
+   * The deployment's declared device class, from
+   * `branding.chrome.{full,embed}.viewport`. `auto` (the default) derives it
+   * from the measured width, byte for byte as before. A forced value overrides
+   * the width for every consumer of the category at once.
+   */
+  viewport?: ForcedViewport;
+}
+/** `auto` derives from width; anything else forces the category. */
+type ForcedViewport = "auto" | ViewportCategory;
+declare function ResponsiveModeProvider({ children, breakpoints, viewportOverride, viewport: declaredViewport }: ResponsiveModeProviderProps): import("react").JSX.Element;
+declare function useResponsiveMode(): ResponsiveMode;
+//#endregion
+export { EntityField as $, ListParams as A, pickLocalized as At, TenantEnv as B, hasOrGroups as Bt, CURSOR_LANGUAGE_CHANGED as C, pkValuesToDetailId as Ct, EnrichedRow as D, TextFn as Dt, DataResponse as E, MANDATORY_LANGUAGE as Et, PublicParam as F, FilterURLState as Ft, V2PropertyInstance as G, FileFieldDisplay as Gt, V2ListResponse as H, parseFiltersFromURL as Ht, PublicParamsResponse as I, FilterValueResolver as It, Action as J, HydratedFile as Jt, V2StatusInstance as K, FileFieldMode as Kt, Refs as L, NO_VALUE_OPS as Lt, LoginResponse as M, textWithNodes as Mt, ParamLookup as N, FilterNode as Nt, ImpersonationInfo as O, TextVars as Ot, PropertyValue as P, FilterOp as Pt, Entity as Q, StatusInfo as R, OP_LABELS as Rt, BrandingIdentity as S, pkValuesFromId as St, CheckSetupResponse as T, resolveDetailRoute as Tt, V2Meta as U, setFiltersInURL as Ut, V2ListParams as V, parseFilterURLState as Vt, V2ParamInstance as W, FileFieldDef as Wt, ChildRelation as X, UploadedFile as Xt, AreaDef as Y, UploadProgress as Yt, ClassificationTierDef as Z, OrderedMap as Zt, executeAction as _, buildRowDetailHref as _t, ResponsiveMode as a, NavNode as at, ApiErrorBody as b, getPrimaryKeyFields as bt, resolveViewportCategory as c, PropertyDef as ct, ActionExecuteResponse as d, Screen as dt, EnumDef as et, ActionItemError as f, StatusDef as ft, deleteObject as g, buildEntityDetailHref as gt, buildActionBody as h, buildDetailHrefFromId as ht, ResponsiveBreakpoints as i, LocalizedString as it, ListResponse as j, pluralText as jt, ListMeta as k, makeTextFn as kt, ActionBatchError as l, RefConfig as lt, GetEntityOptions as m, StructureDef as mt, useResponsiveMode as n, FilterSpecialValue as nt, ResponsiveViewport as o, ParameterDef as ot, ActionItemSkip as p, StatusGroupDef as pt, isCursorStaleError as q, FileFieldValue as qt, DEFAULT_RESPONSIVE_BREAKPOINTS as r, LanguageDef as rt, ViewportCategory as s, PkValues as st, ResponsiveModeProvider as t, FieldAccessInfo as tt, ActionExecuteRequest as u, Schema as ut, restoreObject as v, extractPkValues as vt, CURSOR_SEMANTICS_MISMATCH as w, pkValuesToId as wt, AuthUser as x, pkValuePartsToId as xt, ApiError as y, fieldDisplayName as yt, Tenant as z, countActiveFilters as zt };