@declarion/react 0.60.0 → 0.63.0

package/dist-lib/types/schema.d.ts

@@ -1,1089 +0,0 @@
-import { OrderedMap } from "./ordmap";
-import type { FileFieldDef } from "./files";
-import type { IconDef } from "../stores/icon-registry.d.ts";
-import type { FilterNode } from "../lib/filters.d.ts";
-import type { TextFn } from "../lib/language.d.ts";
-export { OrderedMap };
-export type { IconDef };
-export 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.
- */
-export 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.
- */
-export interface EmptyStateDef {
-    title?: LocalizedString;
-    body?: LocalizedString;
-    learn_more_url?: string;
-}
-/**
- * Reserved sentinel value for Screen.detail_screen (list screens). Disables
- * row-click navigation even when the entity declares a canonical detail. Paired
- * with Go's engine.DetailScreenNone - keep the literal "none" in sync.
- */
-export declare const DETAIL_SCREEN_NONE = "none";
-export declare const DISPLAY_KEY = "$display";
-export declare function getDisplayValue(t: TextFn, row: Record<string, unknown> | null | undefined, entity: {
-    display?: {
-        display_field?: string;
-    };
-    fields?: {
-        get(name: string): EntityField | undefined;
-    };
-} | null | undefined): string | undefined;
-export declare function resolveRefRecordLabel(t: TextFn, record: Record<string, unknown>, displayKey: string | undefined, fallback: string): string;
-export declare function screenTitleForPath(t: TextFn, pathname: string, screens: Record<string, Screen> | undefined, entities?: Record<string, Entity>): {
-    title: string;
-    icon?: string;
-    exact: boolean;
-} | undefined;
-export declare function fieldDisplayName(t: TextFn, field: EntityField, fieldName: string, entities?: Record<string, Entity>): string;
-export interface RefDisplay {
-    field: string;
-}
-export 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. */
-export 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. */
-export interface ScreenFilterSpecialValues {
-    mode?: "append" | "replace" | "clear";
-    values?: FilterSpecialValue[];
-}
-/** Normalizes a handler-param ref (scalar entity-code string OR structured
- *  object) into a RefConfig. One helper shared by filters, SmartDetailPage
- *  fields, and ActionDialog params so the scalar shorthand and structured form
- *  reach the relation combobox identically. */
-export declare function normalizeRefConfig(ref: string | RefConfig | undefined): RefConfig | undefined;
-/** Computes the effective filter_special_values for a field on a screen by
- *  merging the field-level list with an optional screen override per its mode
- *  (append [default] / replace / clear). Pure; mirrors the engine's
- *  EffectiveFilterSpecialValues so the SDK and loader agree. */
-export declare function effectiveFilterSpecialValues(fieldValues: FilterSpecialValue[] | undefined, override: ScreenFilterSpecialValues | undefined): FilterSpecialValue[];
-export interface UnitConfig {
-    storage: string;
-    display?: string;
-}
-export interface EntityField {
-    /**
-     * 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").
- */
-export 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;
-}
-export interface StructureDef {
-    name: LocalizedString;
-    description?: LocalizedString;
-    fields: OrderedMap<EntityField>;
-}
-export type ChildDisplayMode = "table" | "timeline" | "list" | "cards";
-export 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";
-}
-export interface CardsConfig {
-    columns_count?: number;
-    header_field?: string;
-    badge_field?: string;
-}
-export interface ChildQuickAdd {
-    fields: string[];
-    defaults?: Record<string, unknown>;
-    placeholder?: LocalizedString;
-}
-export 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";
-}
-export interface ChildRelation {
-    entity: string;
-    foreign_key: string | string[];
-    display?: ChildDisplay;
-    quick_add?: ChildQuickAdd;
-}
-export interface StatusDef {
-    code: string;
-    name: LocalizedString;
-    description?: LocalizedString;
-    color?: string;
-    is_final?: boolean;
-}
-export interface StatusGroupDef {
-    name: LocalizedString;
-    description?: LocalizedString;
-    is_main?: boolean;
-    initial: string;
-    statuses: StatusDef[];
-    transitions?: Record<string, string[]>;
-    display_mode?: "pill" | "stepper";
-}
-export interface PropertyDef {
-    name: LocalizedString;
-    description?: LocalizedString;
-    type: string;
-    display?: EntityField["display"];
-    values?: EntityField["values"];
-    enum?: string;
-    ref?: RefConfig;
-    structure?: string;
-    readonly?: boolean;
-}
-export declare function propertyToField(prop: PropertyDef): EntityField;
-export interface EnumDef {
-    name: LocalizedString;
-    description?: LocalizedString;
-    values: Array<{
-        code: string;
-        name: LocalizedString;
-        description?: LocalizedString;
-        color?: string;
-    }>;
-}
-export 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;
-}
-export interface AssociationDisplay {
-    name?: LocalizedString;
-    description?: LocalizedString;
-    icon?: string;
-}
-export interface AssociationDef {
-    target: string;
-    display?: AssociationDisplay;
-    source: string;
-    code: string;
-}
-export type EntityMutationOp = "create" | "update" | "delete" | "restore";
-export interface EntityMutations {
-    create?: boolean;
-    update?: boolean;
-    delete?: boolean;
-    restore?: boolean;
-}
-export 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`). */
-export interface OpSet {
-    read?: boolean;
-    write?: boolean;
-    delete?: boolean;
-}
-export interface CardSpec {
-    title_field?: string;
-    subtitle_field?: string;
-    badge_fields?: string[];
-    fields?: string[];
-    meta_fields?: string[];
-    hide_empty_fields?: boolean;
-    max_body_fields?: number;
-}
-export interface Entity {
-    table: 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>;
-    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;
-    };
-}
-export interface ExportConfig {
-    enabled?: boolean;
-}
-export declare function entityAllowsMutation(entity: Pick<Entity, "readonly" | "mutations"> | undefined, op: EntityMutationOp): boolean;
-export declare function entityAllowsCreateRoute(entity: Pick<Entity, "disable_defaults"> | undefined): boolean;
-export declare function getPrimaryKeyFields(entity: Entity): string[];
-export type PkValues = Record<string, string>;
-export declare function extractPkValues(entity: Entity, record: Record<string, unknown>): PkValues;
-export declare function pkValuePartsToId(values: string[]): string;
-export declare function pkValuesToId(pkValues: PkValues): string;
-export declare function pkValuesToDetailId(entity: Entity, pkValues: PkValues): string;
-export declare function singlePkValues(entity: Entity, value: string): PkValues | undefined;
-export declare function pkValuesFromId(id: string, expectedCount: number): string[] | null;
-export declare function resolveDetailRoute(list: Pick<Screen, "detail_screen"> | undefined, entity: Pick<Entity, "detail_screen"> | undefined, allScreens: Record<string, {
-    route?: string;
-}> | undefined): string | null;
-export declare function buildDetailHrefFromId(list: Pick<Screen, "detail_screen">, id: string, entity: Pick<Entity, "detail_screen"> | undefined, allScreens: Record<string, {
-    route?: string;
-}> | undefined): string | null;
-export declare function buildEntityDetailHref(list: Pick<Screen, "detail_screen">, entity: Entity | undefined, allScreens: Record<string, {
-    route?: string;
-}> | undefined, pkValues: PkValues): string | null;
-export declare function buildRowDetailHref(list: Pick<Screen, "detail_screen">, entity: Entity | undefined, allScreens: Record<string, {
-    route?: string;
-}> | undefined, row: Record<string, unknown>): string | null;
-export declare function isCompositePk(entity: Entity): boolean;
-export type SizeValue = string;
-export interface SectionBadgeConfig {
-    text: LocalizedString;
-    tone?: "indigo" | "emerald" | "amber" | "rose" | "sky" | "violet" | "slate" | "teal";
-    dot?: boolean;
-}
-export interface SectionNode {
-    name: LocalizedString;
-    items: LayoutNode[];
-    collapsed?: boolean;
-    columns?: number;
-    icon?: string;
-    badge?: SectionBadgeConfig;
-    emphasis?: "primary" | "secondary";
-}
-export interface RowConfig {
-    items: LayoutNode[];
-    gap?: number;
-    resizable?: boolean;
-    stack_below?: number | "never";
-    width?: SizeValue;
-    height?: SizeValue;
-}
-export interface ColumnConfig {
-    items: LayoutNode[];
-    gap?: number;
-    width?: SizeValue;
-    height?: SizeValue;
-}
-export interface TabsConfig {
-    items: LayoutNode[];
-}
-export interface WidgetNode {
-    type: string;
-    inputs?: Record<string, string>;
-    options?: Record<string, unknown>;
-}
-export interface LayoutField {
-    code: string;
-    actions?: Action[];
-    structure?: string;
-    detail_screen?: string;
-}
-export interface LayoutNode {
-    row?: RowConfig;
-    column?: ColumnConfig;
-    tabs?: TabsConfig;
-    section?: SectionNode;
-    children?: string;
-    associated?: 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";
-}
-export interface AuditLineDef {
-    label: LocalizedString;
-    at?: string;
-    by?: string;
-}
-export 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. */
-export interface ScreenVisibility {
-    public: boolean;
-    required_permission: string;
-    source: string;
-}
-export type ViewportKey = "phone" | "tablet" | "desktop";
-export type ListPresentation = "table" | "cards";
-export type RecordListPresentation = "split" | "drilldown" | "stacked";
-export type DetailTabsPresentation = "sections" | "scroll";
-export type DetailSidebarPresentation = "inline" | "hidden";
-export type RelatedRecordsPresentation = "cards" | "table";
-export interface ResponsiveDetailLayout {
-    header_card?: boolean;
-    tabs?: DetailTabsPresentation;
-    sidebar?: DetailSidebarPresentation;
-    related_records?: RelatedRecordsPresentation;
-}
-export interface ResponsiveListBranch {
-    presentation?: ListPresentation;
-}
-export interface ResponsiveDetailBranch {
-    header_card?: boolean;
-    tabs?: DetailTabsPresentation;
-}
-export interface ScreenResponsiveViewport {
-    presentation?: ListPresentation | RecordListPresentation;
-    layout?: ResponsiveDetailLayout;
-    list?: ResponsiveListBranch;
-    detail?: ResponsiveDetailBranch;
-}
-export type ScreenResponsive = Partial<Record<ViewportKey, ScreenResponsiveViewport>>;
-export 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;
-}
-export 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[];
-}
-export 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;
-}
-export interface InlineEditConfig {
-    enabled?: boolean;
-    /** dblclick | enter | always */
-    trigger?: string;
-}
-export interface ColumnSpec {
-    inline_edit?: boolean;
-    width?: string;
-}
-export interface ActivityRailConfig {
-    children: string;
-    /** left | right (default right) */
-    position?: string;
-    width?: number;
-}
-/** System view (preset) defined in screen YAML. Read-only. */
-export interface ViewDefinition {
-    code: string;
-    name: LocalizedString;
-    description?: LocalizedString;
-    icon?: string;
-    filters?: FilterNode[];
-    columns?: string[];
-    sort?: string;
-}
-export interface NavNode {
-    screen?: string;
-    name?: LocalizedString;
-    icon?: string;
-    items?: NavNode[];
-    area?: string;
-    badge?: string;
-    children?: NavNode[];
-}
-export interface AreaDef {
-    code: string;
-    name?: LocalizedString;
-    icon?: string;
-    position?: number;
-    home_screen?: string;
-    required_permission?: string;
-}
-export interface AccentDef {
-    color?: string;
-    color_2?: string;
-    soft?: string;
-    ring?: string;
-    on_dark?: string;
-    on_light?: string;
-}
-export interface HandlerParamDisplay {
-    name?: LocalizedString;
-    description?: LocalizedString;
-    widget?: string;
-}
-export 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>;
-}
-export interface ActionCondition {
-    status?: string[];
-    field?: string;
-    op?: string;
-    value?: unknown;
-}
-export interface UISetFieldStep {
-    target: string;
-    value: unknown;
-}
-export interface UIShowToastStep {
-    kind?: "success" | "error" | "info";
-    message: string;
-}
-export 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>"}
- */
-export 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).
- */
-export 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).
- */
-export type ActionLayoutNode = ActionLayoutLeaf | ActionLayoutGroup;
-/**
- * Single row-state condition for visible_if / enabled_if / conditions.
- * Operators: eq | ne | in | not_in | gt | lt | ge | le.
- */
-export 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).
- */
-export type ActionConditionList = ActionConditionEntry[];
-export 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;
-}
-export interface LanguageDef {
-    code: string;
-    name: LocalizedString;
-}
-export interface HandlerDef {
-    code: string;
-    type: string;
-    entity?: string;
-    display?: {
-        name?: LocalizedString;
-        description?: LocalizedString;
-        icon?: string;
-    };
-    params?: OrderedMap<HandlerParam>;
-}
-export 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.
- */
-export 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;
-}