@timeax/digital-service-engine 0.0.1

package/dist/react/index.d.cts

@@ -0,0 +1,1572 @@
+import { NodeProps } from 'reactflow';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+type PricingRole = "base" | "utility";
+type FieldType = "custom" | (string & {});
+/** ── Marker types (live inside meta; non-breaking) ───────────────────── */
+type QuantityMark = {
+    quantity?: {
+        valueBy: "value" | "length" | "eval";
+        code?: string;
+        multiply?: number;
+        clamp?: {
+            min?: number;
+            max?: number;
+        };
+        fallback?: number;
+    };
+};
+type UtilityMark = {
+    utility?: {
+        rate: number;
+        mode: "flat" | "per_quantity" | "per_value" | "percent";
+        valueBy?: "value" | "length";
+        percentBase?: "service_total" | "base_service" | "all";
+        label?: string;
+    };
+};
+type WithQuantityDefault = {
+    quantityDefault?: number;
+};
+/** ---------------- Core schema (as you designed) ---------------- */
+interface BaseFieldUI {
+    name?: string;
+    label: string;
+    required?: boolean;
+    /** Host-defined prop names → typed UI nodes */
+    ui?: Record<string, Ui>;
+    /** Host-defined prop names → runtime default values (untyped base) */
+    defaults?: Record<string, unknown>;
+}
+type Ui = UiString | UiNumber | UiBoolean | UiAnyOf | UiArray | UiObject;
+/** string */
+interface UiString {
+    type: "string";
+    enum?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+/** number */
+interface UiNumber {
+    type: "number";
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+}
+/** boolean */
+interface UiBoolean {
+    type: "boolean";
+}
+/** enumerated choices */
+interface UiAnyOf {
+    type: "anyOf";
+    multiple?: boolean;
+    items: Array<{
+        type: "string" | "number" | "boolean";
+        title?: string;
+        description?: string;
+        value: string | number | boolean;
+    }>;
+}
+/** arrays: homogeneous (item) or tuple (items) */
+interface UiArray {
+    type: "array";
+    item?: Ui;
+    items?: Ui[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+}
+/** objects: nested props */
+interface UiObject {
+    type: "object";
+    fields: Record<string, Ui>;
+    required?: string[];
+    order?: string[];
+}
+/** ---------------- Typed defaults helpers ---------------- */
+/**
+ * UiValue<U>: given a Ui node U, infer the runtime value type.
+ */
+type UiValue<U extends Ui> = U extends {
+    type: "string";
+} ? string : U extends {
+    type: "number";
+} ? number : U extends {
+    type: "boolean";
+} ? boolean : U extends {
+    type: "anyOf";
+    multiple: true;
+} ? Array<U["items"][number]["value"]> : U extends {
+    type: "anyOf";
+} ? U["items"][number]["value"] : U extends {
+    type: "array";
+    item: infer I extends Ui;
+} ? Array<UiValue<I>> : U extends {
+    type: "array";
+    items: infer T extends Ui[];
+} ? {
+    [K in keyof T]: UiValue<T[K]>;
+} : U extends {
+    type: "object";
+    fields: infer F extends Record<string, Ui>;
+} ? {
+    [K in keyof F]?: UiValue<F[K]>;
+} : unknown;
+/**
+ * FieldWithTypedDefaults<T>: same shape as BaseFieldUI, but:
+ *  - ui is a concrete map T (propName → Ui node)
+ *  - defaults are auto-typed from T via UiValue
+ */
+type FieldWithTypedDefaults<T extends Record<string, Ui>> = Omit<BaseFieldUI, "ui" | "defaults"> & {
+    ui: T;
+    defaults?: Partial<{
+        [K in keyof T]: UiValue<T[K]>;
+    }>;
+};
+type FieldOption = {
+    id: string;
+    label: string;
+    value?: string | number;
+    service_id?: number;
+    pricing_role?: PricingRole;
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+};
+type Field = BaseFieldUI & {
+    id: string;
+    type: FieldType;
+    bind_id?: string | string[];
+    name?: string;
+    options?: FieldOption[];
+    description?: string;
+    component?: string;
+    pricing_role?: PricingRole;
+    meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
+        multi?: boolean;
+    };
+} & ({
+    button?: false;
+    service_id?: undefined;
+} | ({
+    button: true;
+    service_id?: number;
+} & WithQuantityDefault));
+type ConstraintKey = string;
+/**
+ * Back-compat alias: older code may still import FlagKey.
+ * Keeping this prevents a wave of TS errors while still allowing any string key.
+ */
+type FlagKey = ConstraintKey;
+type Tag = {
+    id: string;
+    label: string;
+    bind_id?: string;
+    service_id?: number;
+    includes?: string[];
+    excludes?: string[];
+    meta?: Record<string, unknown> & WithQuantityDefault;
+    /**
+     * Which flags are set for this tag. If a flag is not set, it's inherited from the nearest ancestor with a value set.
+     */
+    constraints?: Partial<Record<ConstraintKey, boolean>>;
+    /** Which ancestor defined the *effective* value for each flag (nearest source). */
+    constraints_origin?: Partial<Record<ConstraintKey, string>>;
+    /**
+     * Present only when a child explicitly set a different value but was overridden
+     * by an ancestor during normalisation.
+     */
+    constraints_overrides?: Partial<Record<ConstraintKey, {
+        from: boolean;
+        to: boolean;
+        origin: string;
+    }>>;
+};
+type ServiceProps = {
+    order_for_tags?: Record<string, string[]>;
+    filters: Tag[];
+    fields: Field[];
+    includes_for_buttons?: Record<string, string[]>;
+    excludes_for_buttons?: Record<string, string[]>;
+    schema_version?: string;
+    fallbacks?: ServiceFallback;
+};
+type ServiceIdRef = number | string;
+type NodeIdRef = string;
+type ServiceFallback = {
+    /** Node-scoped fallbacks: prefer these when that node’s primary service fails */
+    nodes?: Record<NodeIdRef, ServiceIdRef[]>;
+    /** Primary→fallback list used when no node-scoped entry is present */
+    global?: Record<ServiceIdRef, ServiceIdRef[]>;
+};
+
+type NodeKind = "tag" | "field" | "comment" | "option";
+type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
+type GraphNode = {
+    id: string;
+    kind: NodeKind;
+    bind_type?: "bound" | "utility" | null;
+    errors?: string[];
+    label: string;
+};
+type GraphEdge = {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    meta?: Record<string, unknown>;
+};
+type GraphSnapshot = {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+type FlowNode = NodeProps<{
+    node: GraphNode;
+    [x: string]: any;
+}>;
+
+type CommentId = string;
+type ThreadId = string;
+type CommentAnchor = {
+    type: "node";
+    nodeId: string;
+    offset?: {
+        dx: number;
+        dy: number;
+    };
+} | {
+    type: "edge";
+    edgeId: string;
+    t?: number;
+} | {
+    type: "free";
+    position: {
+        x: number;
+        y: number;
+    };
+};
+type CommentMessage = {
+    id: CommentId;
+    isMain?: boolean;
+    authorId?: string;
+    authorName?: string;
+    body: string;
+    createdAt: number;
+    editedAt?: number;
+    meta?: Record<string, unknown>;
+};
+type CommentThread = {
+    id: ThreadId;
+    anchor?: CommentAnchor;
+    resolved: boolean;
+    createdAt: number;
+    updatedAt: number;
+    messages: CommentMessage[];
+    meta?: Record<string, unknown>;
+    _sync?: "pending" | "synced" | "error";
+};
+
+type Viewport = {
+    x: number;
+    y: number;
+    zoom: number;
+};
+type NodePos = {
+    x: number;
+    y: number;
+};
+type NodePositions = Record<string, NodePos>;
+type DraftWire = {
+    from: string;
+    kind: EdgeKind;
+};
+type CanvasState = {
+    graph: GraphSnapshot;
+    positions: NodePositions;
+    selection: Set<string>;
+    highlighted: Set<string>;
+    hoverId?: string;
+    viewport: Viewport;
+    draftWire?: DraftWire;
+    version: number;
+};
+type CanvasEvents = {
+    "graph:update": GraphSnapshot;
+    "state:change": CanvasState;
+    "selection:change": {
+        ids: string[];
+    };
+    "viewport:change": Viewport;
+    "hover:change": {
+        id?: string;
+    };
+    "wire:preview": {
+        from: string;
+        to?: string;
+        kind: EdgeKind;
+    };
+    "wire:commit": {
+        from: string;
+        to: string;
+        kind: EdgeKind;
+    };
+    "wire:cancel": {
+        from: string;
+    };
+    error: {
+        message: string;
+        code?: string;
+        meta?: any;
+    };
+    "comment:thread:create": {
+        thread: CommentThread;
+    };
+    "comment:thread:update": {
+        thread: CommentThread;
+    };
+    "comment:thread:delete": {
+        threadId: string;
+    };
+    "comment:message:create": {
+        threadId: string;
+        message: CommentMessage;
+    };
+    "comment:resolve": {
+        thread: CommentThread;
+        resolved: boolean;
+    };
+    "comment:move": {
+        thread: CommentThread;
+    };
+    "comment:select": {
+        threadId?: string;
+    };
+    "edge:change": EdgeKind;
+    "comment:sync": {
+        op: "create_thread" | "add_message" | "edit_message" | "delete_message" | "move_thread" | "resolve_thread" | "delete_thread";
+        threadId: string;
+        messageId?: string;
+        status: "scheduled" | "retrying" | "succeeded" | "failed" | "cancelled";
+        attempt: number;
+        nextDelayMs?: number;
+        error?: any;
+    };
+};
+type NodeView = GraphNode & {
+    position?: NodePos;
+};
+type EdgeView = GraphEdge;
+type CanvasOptions = {
+    initialViewport?: Partial<Viewport>;
+    autoEmitState?: boolean;
+};
+
+type CommentNode = {
+    id: string;
+    text: string;
+    status: "open" | "resolved";
+    anchor?: {
+        kind: "tag" | "field" | "option";
+        id: string;
+    };
+    replies?: Array<{
+        id: string;
+        text: string;
+        created_at: string;
+        author?: string;
+    }>;
+    xy?: {
+        x: number;
+        y: number;
+    };
+    meta?: Record<string, unknown>;
+};
+type EdgeRoute = {
+    id: string;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+};
+type LayoutState = {
+    canvas: CanvasState;
+    edges?: EdgeRoute[];
+};
+type EditorSnapshot = {
+    props: ServiceProps;
+    layout?: LayoutState;
+    comments?: CommentNode[];
+    meta?: Record<string, unknown>;
+};
+
+type TimeRangeEstimate = {
+    min_seconds?: number;
+    max_seconds?: number;
+    label?: string;
+    meta?: Record<string, unknown>;
+};
+type SpeedEstimate = {
+    amount?: number;
+    per?: "minute" | "hour" | "day" | "week" | "month";
+    unit?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+};
+type ServiceEstimates = {
+    start?: TimeRangeEstimate;
+    speed?: SpeedEstimate;
+    average?: TimeRangeEstimate;
+    meta?: Record<string, unknown>;
+};
+type ServiceFlag = {
+    enabled: boolean;
+    description: string;
+    meta?: Record<string, unknown>;
+};
+type IdType = string | number;
+type ServiceFlags = Record<string, ServiceFlag>;
+type DgpServiceCapability = {
+    id: IdType;
+    name?: string;
+    rate: number;
+    min?: number;
+    max?: number;
+    category?: string;
+    flags?: ServiceFlags;
+    estimates?: ServiceEstimates;
+    meta?: Record<string, unknown>;
+    [x: string]: any;
+};
+type DgpServiceMap = Record<string, DgpServiceCapability> & Record<number, DgpServiceCapability>;
+
+type ValidationCode = "root_missing" | "cycle_in_tags" | "bad_bind_reference" | "duplicate_id" | "duplicate_tag_label" | "duplicate_field_name" | "label_missing" | "duplicate_visible_label" | "bad_option_key" | "option_include_exclude_conflict" | "service_field_missing_service_id" | "user_input_field_has_service_option" | "rate_mismatch_across_base" | "utility_without_base" | "unsupported_constraint" | "constraint_contradiction" | "custom_component_missing" | "policy_violation" | "field_unbound" | "constraint_overridden" | "unsupported_constraint_option" | "custom_component_unresolvable" | "quantity_multiple_markers" | "utility_with_service_id" | "utility_missing_rate" | "utility_invalid_mode" | "fallback_bad_node" | "fallback_unknown_service" | "fallback_cycle" | "fallback_no_primary" | "fallback_rate_violation" | "fallback_constraint_mismatch" | "fallback_no_tag_context";
+type ValidationError = {
+    code: ValidationCode;
+    message: string;
+    severity: "error" | "warning" | "info";
+    nodeId?: string;
+    details?: Record<string, unknown> & {
+        affectedIds?: string[];
+    };
+};
+type ServiceWhereOp = "eq" | "neq" | "in" | "nin" | "exists" | "truthy" | "falsy" | "sw";
+/**
+ * Host-extensible service filter clause.
+ * `path` should usually be "service.<prop>" or "service.meta.<prop>" etc.
+ */
+type ServiceWhereClause = {
+    path: string;
+    op?: ServiceWhereOp;
+    value?: unknown;
+};
+type DynamicRule = {
+    id: string;
+    label?: string;
+    scope: "global" | "visible_group";
+    subject: "services";
+    /**
+     * Package-level filter surface:
+     * - role/tag/field are core to the builder schema
+     * - where[] allows hosts to filter against extra service properties (handler_id/platform_id/type/key/category_id/etc.)
+     */
+    filter?: {
+        role?: "base" | "utility" | "both";
+        tag_id?: string | string[];
+        field_id?: string | string[];
+        where?: ServiceWhereClause[];
+    };
+    /**
+     * Projection is intentionally open:
+     * hosts may project custom service properties.
+     */
+    projection?: "service.id" | "service.name" | "service.rate" | "service.min" | "service.max" | "service.category" | string;
+    op: "all_equal" | "unique" | "no_mix" | "all_true" | "any_true" | "max_count" | "min_count";
+    value?: number | boolean;
+    severity?: "error" | "warning";
+    message?: string;
+};
+type ValidatorOptions = {
+    serviceMap?: DgpServiceMap;
+    allowUnsafe?: boolean;
+    selectedOptionKeys?: string[];
+    globalUtilityGuard?: boolean;
+    policies?: DynamicRule[];
+    fallbackSettings?: FallbackSettings;
+};
+type RatePolicy = {
+    kind: "lte_primary";
+} | {
+    kind: "within_pct";
+    pct: number;
+} | {
+    kind: "at_least_pct_lower";
+    pct: number;
+};
+type FallbackSettings = {
+    /** Require fallbacks to satisfy tag constraints (dripfeed/refill/cancel) when a tag context is known. Default: true */
+    requireConstraintFit?: boolean;
+    /** Rate rule policy. Default: { kind: 'lte_primary' } i.e. candidate.rate <= primary.rate */
+    ratePolicy?: RatePolicy;
+    /** When multiple candidates remain, choose first (priority) or cheapest. Default: 'priority' */
+    selectionStrategy?: "priority" | "cheapest";
+    /** Validation mode: 'strict' → node-scoped violations reported as ValidationError; 'dev' → only collect diagnostics. Default: 'strict' */
+    mode?: "strict" | "dev";
+};
+
+/** Options you can set on the builder (used for validation/visibility) */
+type BuilderOptions = Omit<ValidatorOptions, "serviceMap"> & {
+    serviceMap?: DgpServiceMap;
+    /** max history entries for undo/redo */
+    historyLimit?: number;
+    /**
+     * Field ids whose options should be shown as nodes in the graph.
+     * If a field id is NOT in this set, its options are not materialized as nodes:
+     * - include/exclude wires keyed by an option id will be drawn from the FIELD instead.
+     */
+    showOptionNodes?: Set<string> | string[];
+};
+interface Builder {
+    /** Replace current payload (injects root if missing, rebuilds indexes) */
+    load(props: ServiceProps): void;
+    /** Graph for visualisation */
+    tree(): GraphSnapshot;
+    /** Deterministic save payload (drops unbound utility fields, prunes dead maps) */
+    cleanedProps(): ServiceProps;
+    /** Validation errors for current state */
+    errors(): ValidationError[];
+    /**
+     * Compute IDs of fields visible under a tag.
+     * If selectedOptionKeys provided, applies option-level include/exclude.
+     * NOTE: keys are “button ids”: either option.id or field.id for option-less buttons.
+     */
+    visibleFields(tagId: string, selectedOptionKeys?: string[]): string[];
+    /** Update builder options (validator context etc.) */
+    setOptions(patch: Partial<BuilderOptions>): void;
+    /** History */
+    undo(): boolean;
+    redo(): boolean;
+    /** Access the current props (already normalised) */
+    getProps(): ServiceProps;
+    /** Service map for validation/rules */
+    getServiceMap(): DgpServiceMap;
+    getConstraints(): {
+        id: string;
+        label: string;
+        description: string;
+        value: string;
+    }[];
+}
+
+type Env = "client" | "workspace";
+type VisibleGroup = {
+    tagId?: string;
+    tag?: Tag;
+    fields: Field[];
+    fieldIds: string[];
+    parentTags?: Tag[];
+    childrenTags?: Tag[];
+    /** In order of selection: tag base (unless overridden) then selected options */
+    services?: DgpServiceCapability[];
+};
+type VisibleGroupResult = {
+    kind: "single";
+    group: VisibleGroup;
+} | {
+    kind: "multi";
+    groups: string[];
+};
+type ChangeEvt = {
+    ids: string[];
+    primary?: string;
+};
+type Listener = (e: ChangeEvt) => void;
+type SelectionOptions = {
+    env?: Env;
+    rootTagId?: string;
+    /** Resolve service capability from an id (used for `services` array) */
+    resolveService?: (id: any) => DgpServiceCapability | undefined;
+};
+declare class Selection {
+    private readonly builder;
+    private readonly opts;
+    private set;
+    private primaryId;
+    private currentTagId;
+    private onChangeFns;
+    constructor(builder: Builder, opts: SelectionOptions);
+    replace(id?: string | null): void;
+    add(id: string): void;
+    remove(id: string): void;
+    toggle(id: string): void;
+    many(ids: Iterable<string>, primary?: string): void;
+    clear(): void;
+    all(): ReadonlySet<string>;
+    has(id: string): boolean;
+    primary(): string | undefined;
+    currentTag(): string | undefined;
+    onChange(fn: Listener): () => void;
+    visibleGroup(): VisibleGroupResult;
+    private emit;
+    private updateCurrentTagFrom;
+    private resolveTagContextId;
+    private selectedButtonTriggerIds;
+    private computeGroupForTag;
+    private addServiceByRole;
+    private findOptionById;
+}
+
+type EditorEvents = {
+    "editor:command": {
+        name: string;
+        payload?: any;
+    };
+    "editor:change": {
+        props: ServiceProps;
+        reason: string;
+        command?: string;
+    };
+    "editor:undo": {
+        stackSize: number;
+        index: number;
+    };
+    "editor:redo": {
+        stackSize: number;
+        index: number;
+    };
+    "editor:error": {
+        message: string;
+        code?: string;
+        meta?: any;
+    };
+};
+type Command = {
+    name: string;
+    do(): void;
+    undo(): void;
+};
+type EditorOptions = {
+    historyLimit?: number;
+    validateAfterEach?: boolean;
+    /** Sync existence check; return true if the service exists. */
+    serviceExists?: (id: number) => boolean;
+    /** Optional local index; used if serviceExists is not provided. */
+    serviceMap?: Record<number, unknown>;
+    /** Raw policies JSON; will be compiled on demand by filterServicesForVisibleGroup. */
+    policiesRaw?: unknown;
+    selectionProps?: SelectionOptions;
+};
+type ConnectKind = "bind" | "include" | "exclude";
+
+interface ButtonValue {
+    id: string;
+    value: string | number;
+    service_id?: number;
+    pricing_role?: "base" | "utility";
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+}
+type Scalar = string | number | boolean | ButtonValue | null;
+type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
+type QuantityRule$1 = {
+    valueBy: "value" | "length" | "eval";
+    code?: string;
+};
+type UtilityLineItem = {
+    nodeId: string;
+    mode: UtilityMode;
+    rate: number;
+    inputs: {
+        quantity: number;
+        value?: Scalar | Scalar[];
+        valueBy?: "value" | "length" | "eval";
+        evalCodeUsed?: boolean;
+    };
+};
+type ServiceFallbacks = {
+    nodes?: Record<string, Array<string | number>>;
+    global?: Record<string | number, Array<string | number>>;
+};
+type FallbackDiagnostics = {
+    scope: "node" | "global";
+    nodeId?: string;
+    primary: string | number;
+    candidate: string | number;
+    reasons: Array<"rate_violation" | "constraint_mismatch" | "unknown_service" | "ambiguous_context">;
+};
+type SnapshotContext = {
+    /** The single active tag id for this order */
+    tag: string;
+    /** Effective (post-propagation) constraints on that tag */
+    constraints: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+    /**
+     * Per-node evaluation context:
+     * - For the active tag node itself: the same tag id.
+     * - For an option node: parent's field.bind_id must include this tag to be applicable; otherwise null.
+     * - For a field node (optional to include later): same rule as option, derived from field.bind_id.
+     */
+    nodeContexts: Record<string, string | null>;
+    /** Client pruning policy used (so server can mirror/compare). */
+    policy: {
+        ratePolicy: {
+            kind: "lte_primary" | "none";
+            thresholdPct?: number;
+        };
+        requireConstraintFit: boolean;
+    };
+};
+type OrderSnapshot = {
+    version: "1";
+    mode: "prod" | "dev";
+    builtAt: string;
+    selection: {
+        tag: string;
+        fields: Array<{
+            id: string;
+            type: string;
+            selectedOptions?: string[];
+        }>;
+    };
+    inputs: {
+        form: Record<string, Scalar | Scalar[]>;
+        selections: Record<string, string[]>;
+    };
+    quantity: number;
+    quantitySource: {
+        kind: "field" | "tag" | "option" | "default";
+        id?: string;
+        rule?: QuantityRule$1;
+        defaultedFromHost?: boolean;
+    };
+    services: Array<string | number>;
+    serviceMap: Record<string, Array<string | number>>;
+    fallbacks?: {
+        nodes?: Record<string, Array<string | number>>;
+        global?: Record<string | number, Array<string | number>>;
+    };
+    utilities?: UtilityLineItem[];
+    warnings?: {
+        utility?: Array<{
+            nodeId: string;
+            reason: string;
+        }>;
+        fallbacks?: FallbackDiagnostics[];
+    };
+    meta?: {
+        schema_version?: string;
+        workspaceId?: string;
+        builder?: {
+            commit?: string;
+        };
+        context?: SnapshotContext;
+    };
+};
+
+/** Exported alias so the schema generator can target an array */
+type AdminPolicies = DynamicRule[];
+
+type EventMap = Record<string, unknown>;
+declare class EventBus<E extends EventMap> {
+    private listeners;
+    on<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
+    once<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
+    emit<K extends keyof E>(event: K, payload: E[K]): void;
+    clear(): void;
+}
+
+type PolicyDiagnostic = {
+    ruleIndex: number;
+    ruleId?: string;
+    severity: "error" | "warning";
+    message: string;
+    path?: string;
+};
+
+interface BackendError {
+    readonly meta?: any;
+    readonly code: string;
+    readonly message: string;
+    readonly status?: number;
+    readonly hint?: string;
+    readonly cause?: unknown;
+}
+type BackendResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: BackendError;
+};
+type Result<T> = Promise<BackendResult<T>>;
+interface Actor {
+    readonly id: string;
+    readonly name?: string;
+    readonly roles?: readonly string[];
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+interface Author {
+    readonly id: string;
+    readonly name: string;
+    readonly handle?: string;
+    readonly avatarUrl?: string;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+}
+type PermissionsMap = Readonly<Record<string, boolean>>;
+interface Branch {
+    readonly id: string;
+    readonly name: string;
+    readonly isMain: boolean;
+    readonly headVersionId?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+interface MergeResult {
+    readonly sourceId: string;
+    readonly targetId: string;
+    readonly conflicts?: number;
+    readonly message?: string;
+}
+type ServicesInput = readonly DgpServiceCapability[] | DgpServiceMap;
+interface ServicesBackend {
+    get(workspaceId: string): Result<ServicesInput>;
+    refresh(workspaceId: string, params?: Readonly<{
+        since?: number | string;
+    }>): Result<ServicesInput>;
+}
+interface BranchParticipant {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly branchId: string;
+    /** points into Authors directory */
+    readonly authorId: string;
+    /** roles are intentionally loose; host decides taxonomy */
+    readonly roles?: readonly string[];
+    readonly canRead: boolean;
+    readonly canWrite: boolean;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+}
+interface BranchAccessBackend {
+    listParticipants(workspaceId: string, branchId: string): Result<readonly BranchParticipant[]>;
+    refreshParticipants(workspaceId: string, branchId: string, params?: Readonly<{
+        since?: number | string;
+    }>): Result<readonly BranchParticipant[]>;
+}
+interface ServiceSnapshot {
+    readonly schema_version: string;
+    readonly data: EditorSnapshot;
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+interface Draft {
+    readonly id: string;
+    readonly branchId: string;
+    readonly status: "uncommitted";
+    readonly etag?: string;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+interface Commit {
+    readonly id: string;
+    readonly branchId: string;
+    readonly message?: string;
+    readonly versionId?: string;
+    readonly etag?: string;
+    readonly createdAt: string;
+}
+interface SnapshotsLoadResult {
+    readonly head?: Commit;
+    readonly draft?: Draft;
+    readonly snapshot: ServiceSnapshot;
+}
+interface SnapshotsBackend {
+    load(params: Readonly<{
+        workspaceId: string;
+        branchId: string;
+        actorId: string;
+        versionId?: string;
+    }>): Result<SnapshotsLoadResult>;
+    autosave(params: Readonly<{
+        workspaceId: string;
+        branchId: string;
+        actorId: string;
+        snapshot: ServiceSnapshot;
+        clientId?: string;
+        since?: number | string;
+        etag?: string;
+    }>): Result<Readonly<{
+        draft: Draft;
+    }>>;
+    save(params: Readonly<{
+        workspaceId: string;
+        branchId: string;
+        actorId: string;
+        snapshot: ServiceSnapshot;
+        message?: string;
+        draftId?: string;
+        etag?: string;
+    }>): Result<Readonly<{
+        commit: Commit;
+    }>>;
+    publish(params: Readonly<{
+        workspaceId: string;
+        actorId: string;
+        draftId: string;
+        message?: string;
+    }>): Result<Readonly<{
+        commit: Commit;
+    }>>;
+    discard(params: Readonly<{
+        workspaceId: string;
+        actorId: string;
+        draftId: string;
+    }>): Result<void>;
+    refresh(params: Readonly<{
+        workspaceId: string;
+        branchId: string;
+        actorId: string;
+        since?: number | string;
+    }>): Result<Readonly<{
+        head?: Commit;
+        draft?: Draft;
+    }>>;
+}
+interface TemplateValidator {
+    readonly type: string;
+    readonly rule?: unknown;
+    readonly message?: string;
+}
+interface FieldTemplate {
+    readonly id: string;
+    /** Unique key (per workspace, optionally per branch) used to reference this template */
+    readonly key: string;
+    readonly name: string;
+    /** logical kind e.g. "text", "number", "date", "select", "relation", ... */
+    readonly kind: string;
+    /** Optional branch scoping (can be global if undefined) */
+    readonly branchId?: string;
+    /** Canonical, builder-consumable definition (shape up to your app) */
+    readonly definition: Readonly<Record<string, unknown>>;
+    /** Default values the editor may inject when using this template */
+    readonly defaults?: Readonly<Record<string, unknown>>;
+    /** UI metadata (icons, color, sizing, render hints, etc.) */
+    readonly ui?: Readonly<Record<string, unknown>>;
+    /** Client- or server-side validators */
+    readonly validators?: readonly TemplateValidator[];
+    readonly tags?: readonly string[];
+    readonly category?: string;
+    /** Published templates are selectable by default in the editor palette */
+    readonly published: boolean;
+    /** Incremented on every update */
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** Narrow list/search input */
+interface TemplatesListParams {
+    readonly workspaceId: string;
+    readonly branchId?: string;
+    readonly q?: string;
+    readonly tags?: readonly string[];
+    readonly category?: string;
+    readonly since?: string | number;
+}
+interface TemplateCreateInput {
+    readonly key?: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly branchId?: string;
+    readonly definition: Readonly<Record<string, unknown>>;
+    readonly defaults?: Readonly<Record<string, unknown>>;
+    readonly ui?: Readonly<Record<string, unknown>>;
+    readonly validators?: readonly TemplateValidator[];
+    readonly tags?: readonly string[];
+    readonly category?: string;
+    readonly published?: boolean;
+}
+interface TemplateUpdatePatch {
+    readonly name?: string;
+    readonly kind?: string;
+    readonly branchId?: string | null;
+    readonly definition?: Readonly<Record<string, unknown>>;
+    readonly defaults?: Readonly<Record<string, unknown>> | null;
+    readonly ui?: Readonly<Record<string, unknown>> | null;
+    readonly validators?: readonly TemplateValidator[] | null;
+    readonly tags?: readonly string[] | null;
+    readonly category?: string | null;
+    readonly published?: boolean;
+}
+interface TemplatesBackend {
+    list(params: TemplatesListParams): Result<readonly FieldTemplate[]>;
+    get(id: string): Result<FieldTemplate | null>;
+    getByKey(workspaceId: string, key: string, branchId?: string): Result<FieldTemplate | null>;
+    create(workspaceId: string, input: TemplateCreateInput): Result<FieldTemplate>;
+    update(id: string, patch: TemplateUpdatePatch): Result<FieldTemplate>;
+    clone(source: Readonly<{
+        id?: string;
+        key?: string;
+    }>, opts?: Readonly<{
+        newKey?: string;
+        name?: string;
+        branchId?: string;
+        asDraft?: boolean;
+    }>): Result<FieldTemplate>;
+    publish(id: string): Result<FieldTemplate>;
+    unpublish(id: string): Result<FieldTemplate>;
+    delete(id: string): Result<void>;
+    refresh(params: Omit<TemplatesListParams, "q" | "tags" | "category">): Result<readonly FieldTemplate[]>;
+}
+interface AuthorsBackend {
+    list(workspaceId: string): Result<readonly Author[]>;
+    get(authorId: string): Result<Author | null>;
+    refresh(workspaceId: string): Result<readonly Author[]>;
+}
+interface PermissionsBackend {
+    get(workspaceId: string, actor: Actor): Result<PermissionsMap>;
+    refresh(workspaceId: string, actor: Actor): Result<PermissionsMap>;
+}
+interface BranchesBackend {
+    list(workspaceId: string): Result<readonly Branch[]>;
+    create(workspaceId: string, name: string, opts?: Readonly<{
+        fromId?: string;
+    }>): Result<Branch>;
+    setMain(workspaceId: string, branchId: string): Result<Branch>;
+    merge(workspaceId: string, sourceId: string, targetId: string): Result<MergeResult>;
+    delete(workspaceId: string, branchId: string): Result<void>;
+    refresh(workspaceId: string): Result<readonly Branch[]>;
+}
+interface WorkspaceInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Shared request scope for host backends (workspace + optional branch + optional actor).
+ * This is intentionally transport-agnostic and minimal so other layers (e.g. canvas/comments)
+ * can reuse it without redefining identity types.
+ */
+interface BackendScope {
+    readonly workspaceId: string;
+    readonly actorId: string;
+    readonly branchId: string;
+}
+/**
+ * Generic canvas comments backend contract.
+ *
+ * We keep this in workspace backend so HOSTS have a single place to implement
+ * transport-agnostic interfaces.
+ *
+ * The canvas module can “bind” these generics to its concrete types.
+ */
+interface CommentsBackend<ThreadDTO = unknown, MessageDTO = unknown, AnchorDTO = unknown> {
+    listThreads(ctx: BackendScope): Result<readonly ThreadDTO[]>;
+    createThread(ctx: BackendScope, input: {
+        anchor?: AnchorDTO;
+        body: string;
+        meta?: Record<string, unknown>;
+    }): Result<ThreadDTO>;
+    addMessage(ctx: BackendScope, input: {
+        threadId: string;
+        body: string;
+        meta?: Record<string, unknown>;
+    }): Result<MessageDTO>;
+    editMessage(ctx: BackendScope, input: {
+        threadId: string;
+        messageId: string;
+        body: string;
+    }): Result<MessageDTO>;
+    deleteMessage(ctx: BackendScope, input: {
+        threadId: string;
+        messageId: string;
+    }): Result<void>;
+    moveThread(ctx: BackendScope, input: {
+        threadId: string;
+        anchor: AnchorDTO;
+    }): Result<ThreadDTO>;
+    resolveThread(ctx: BackendScope, input: {
+        threadId: string;
+        resolved: boolean;
+    }): Result<ThreadDTO>;
+    deleteThread(ctx: BackendScope, input: {
+        threadId: string;
+    }): Result<void>;
+}
+/**
+ * Policies are stored as raw JSON for round-tripping (comments/formatting, etc.),
+ * and compiled into DynamicRule[] for runtime validation.
+ *
+ * Scope rules:
+ * - If branchId is provided -> branch-scoped policies
+ * - If branchId is omitted  -> workspace-scoped policies
+ */
+interface PolicyScope extends BackendScope {
+}
+interface PoliciesLoadResult {
+    /** the raw JSON the host stored (authoring format) */
+    readonly raw: unknown;
+    /** optional precompiled rules (host may compile server-side) */
+    readonly compiled?: readonly DynamicRule[];
+    /** optional diagnostics (host may compile server-side) */
+    readonly diagnostics?: readonly PolicyDiagnostic[];
+    readonly updatedAt?: string;
+    readonly etag?: string;
+}
+/**
+ * Transport contract for policy storage/compilation.
+ *
+ * - UI can compile locally via compilePolicies()
+ * - Host can also compile/validate server-side by implementing compile()
+ */
+interface PoliciesBackend {
+    load(ctx: PolicyScope): Result<PoliciesLoadResult | null>;
+    save(ctx: PolicyScope, input: Readonly<{
+        raw: unknown;
+        etag?: string;
+    }>): Result<Readonly<{
+        updatedAt?: string;
+        etag?: string;
+    }>>;
+    /** Optional server-side compile/validate (for shared editing / enforcement). */
+    compile?(ctx: PolicyScope, input: Readonly<{
+        raw: unknown;
+    }>): Result<Readonly<{
+        policies: readonly DynamicRule[];
+        diagnostics: readonly PolicyDiagnostic[];
+    }>>;
+    /** Optional: reset/delete policies at scope (branch or workspace). */
+    clear?(ctx: PolicyScope): Result<Readonly<{
+        updatedAt?: string;
+    }>>;
+}
+interface WorkspaceBackend {
+    readonly info: WorkspaceInfo;
+    readonly authors: AuthorsBackend;
+    readonly permissions: PermissionsBackend;
+    readonly branches: BranchesBackend;
+    /** branch-scoped access control / participants */
+    readonly access: BranchAccessBackend;
+    /** first-class services channel */
+    readonly services: ServicesBackend;
+    readonly templates: TemplatesBackend;
+    readonly snapshots: SnapshotsBackend;
+    /** dynamic policies: workspace-scoped and/or branch-scoped rules */
+    readonly policies: PoliciesBackend;
+    readonly comments: CommentsBackend<CommentThread, CommentMessage, CommentAnchor>;
+}
+
+type RetryOptions = {
+    enabled?: boolean;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    /** Run the first attempt immediately (no initial delay) */
+    immediateFirst?: boolean;
+};
+
+type CommentsDeps = {
+    backend?: CommentsBackend<CommentThread, CommentMessage, CommentAnchor>;
+    getScope?: () => BackendScope | undefined;
+    retry?: RetryOptions;
+};
+declare class CommentsAPI {
+    private threads;
+    private bus;
+    private deps;
+    private retry;
+    constructor(bus: EventBus<CanvasEvents>, deps?: CommentsDeps);
+    private scope;
+    private emitSync;
+    loadAll(): Promise<void>;
+    list(): CommentThread[];
+    get(id: ThreadId): CommentThread | undefined;
+    create(anchor: CommentAnchor, initialBody: string, meta?: Record<string, unknown>): Promise<ThreadId>;
+    reply(threadId: ThreadId, body: string, meta?: Record<string, unknown>): Promise<CommentId>;
+    editMessage(threadId: ThreadId, messageId: CommentId, body: string): Promise<void>;
+    deleteMessage(threadId: ThreadId, messageId: CommentId): Promise<void>;
+    move(threadId: ThreadId, anchor: CommentAnchor): Promise<void>;
+    resolve(threadId: ThreadId, value?: boolean): Promise<void>;
+    deleteThread(threadId: ThreadId): Promise<void>;
+    retryJob(jobId: string): boolean;
+    cancelJob(jobId: string): boolean;
+    pendingJobs(): string[];
+    private ensure;
+}
+
+type CanvasBackend = {
+    comments?: WorkspaceBackend["comments"];
+};
+type CanvasBackendOptions = {
+    backend?: CanvasBackend;
+    workspaceId?: string;
+} & Partial<BackendScope>;
+
+type WireKind = "bind" | "include" | "exclude" | "service";
+type TagRef = {
+    kind: "tag";
+    id: string;
+};
+type FieldRef = {
+    kind: "field";
+    id: string;
+};
+type OptionRef = {
+    kind: "option";
+    fieldId: string;
+    id: string;
+};
+type NodeRef = TagRef | FieldRef | OptionRef;
+type DuplicateOptions = {
+    withChildren?: boolean;
+    copyBindings?: boolean;
+    copyIncludesExcludes?: boolean;
+    copyOptionMaps?: boolean;
+    id?: string;
+    labelStrategy?: (old: string) => string;
+    nameStrategy?: (old?: string) => string | undefined;
+    optionIdStrategy?: (old: string) => string;
+};
+declare class Editor {
+    private builder;
+    private api;
+    private readonly opts;
+    private history;
+    private index;
+    private txnDepth;
+    private txnLabel?;
+    private stagedBefore?;
+    private _lastPolicyDiagnostics?;
+    constructor(builder: Builder, api: CanvasAPI, opts?: EditorOptions);
+    getProps(): ServiceProps;
+    transact(label: string, fn: () => void): void;
+    exec(cmd: Command): void;
+    undo(): boolean;
+    redo(): boolean;
+    clearService(id: string): void;
+    duplicate(ref: NodeRef, opts?: DuplicateOptions): string;
+    /**
+     * Update the display label for a node and refresh the graph so node labels stay in sync.
+     * Supports: tag ("t:*"), field ("f:*"), option ("o:*").
+     * IDs are NOT changed; only the human-readable label.
+     */
+    reLabel(id: string, nextLabel: string): void;
+    /**
+     * Assign or change a field's `name`. Only allowed when the field (and its options) have NO service mapping.
+     * - If `nextName` is empty/blank → removes the `name`.
+     * - Emits an error if the field or any of its options carry a `service_id`.
+     * - Emits an error if `nextName` collides with an existing field's name (case-sensitive).
+     */
+    setFieldName(fieldId: string, nextName: string | null | undefined): void;
+    getLastPolicyDiagnostics(): PolicyDiagnostic[] | undefined;
+    private duplicateTag;
+    private duplicateField;
+    private duplicateOption;
+    private uniqueId;
+    private uniqueOptionId;
+    /**
+     * Reorder a node:
+     * - Tag: among its siblings (same bind_id) inside filters[]
+     * - Field: inside order_for_tags[scopeTagId] (you must pass scopeTagId)
+     * - Option: use placeOption() instead
+     */
+    placeNode(id: string, opts: {
+        scopeTagId?: string;
+        beforeId?: string;
+        afterId?: string;
+        index?: number;
+    }): void;
+    placeOption(optionId: string, opts: {
+        beforeId?: string;
+        afterId?: string;
+        index?: number;
+    }): void;
+    addOption(fieldId: string, input: {
+        id?: string;
+        label: string;
+        service_id?: number;
+        pricing_role?: "base" | "utility" | "addon";
+        [k: string]: any;
+    }): string;
+    updateOption(optionId: string, patch: Partial<{
+        label: string;
+        service_id: number;
+        pricing_role: "base" | "utility" | "addon";
+    } & Record<string, any>>): void;
+    removeOption(optionId: string): void;
+    editLabel(id: string, label: string): void;
+    editName(fieldId: string, name: string | undefined): void;
+    setService(id: string, input: {
+        service_id?: number;
+        pricing_role?: "base" | "utility";
+    }): void;
+    addTag(partial: Omit<Tag, "id" | "label"> & {
+        id?: string;
+        label: string;
+    }): void;
+    updateTag(id: string, patch: Partial<Tag>): void;
+    removeTag(id: string): void;
+    addField(partial: Omit<Field, "id" | "label" | "type"> & {
+        id?: string;
+        label: string;
+        type: Field["type"];
+    }): void;
+    updateField(id: string, patch: Partial<Field>): void;
+    removeField(id: string): void;
+    remove(id: string): void;
+    getNode(id: string): {
+        kind: "tag";
+        data?: Tag;
+        owners: {
+            parentTagId?: string;
+        };
+    } | {
+        kind: "field";
+        data?: Field;
+        owners: {
+            bindTagIds: string[];
+        };
+    } | {
+        kind: "option";
+        data?: any;
+        owners: {
+            fieldId?: string;
+        };
+    };
+    getFieldQuantityRule(id: string): QuantityRule | undefined;
+    setFieldQuantityRule(id: string, rule: unknown): void;
+    clearFieldQuantityRule(id: string): void;
+    /** Walk ancestors for a tag and detect if parent→child would create a cycle */
+    private wouldCreateTagCycle;
+    private wouldCreateIncludeExcludeCycle;
+    include(receiverId: string, idOrIds: string | string[]): void;
+    exclude(receiverId: string, idOrIds: string | string[]): void;
+    connect(kind: WireKind, fromId: string, toId: string): void;
+    disconnect(kind: WireKind, fromId: string, toId: string): void;
+    setConstraint(tagId: string, flag: string, value: boolean | undefined): void;
+    /**
+     * Clear a constraint override by removing the local constraint that conflicts with an ancestor.
+     */
+    clearConstraintOverride(tagId: string, flag: string): void;
+    /**
+     * Clear a constraint from a tag and its descendants.
+     * If a descendant has an override, it assigns that override's value as local.
+     */
+    clearConstraint(tagId: string, flag: string): void;
+    private replaceProps;
+    private patchProps;
+    private afterMutation;
+    private commit;
+    private makeSnapshot;
+    private loadSnapshot;
+    private pushHistory;
+    private genId;
+    private emit;
+    /**
+     * Suggest/filter candidate services against the current visible-group
+     * (single tag) context.
+     *
+     * - Excludes services already used in this group.
+     * - Applies capability presence, tag constraints, rate policy, and compiled policies.
+     *
+     * @param candidates    service ids to evaluate
+     * @param ctx
+     * @param ctx.tagId     active visible-group tag id
+     * @param ctx.usedServiceIds  services already selected for this visible group (first is treated as "primary" for rate policy)
+     * @param ctx.effectiveConstraints  effective constraints for the active tag (dripfeed/refill/cancel)
+     * @param ctx.policies  raw JSON policies (will be compiled via compilePolicies)
+     * @param ctx.fallback  fallback/rate settings (defaults applied if omitted)
+     */
+    filterServicesForVisibleGroup(candidates: Array<number | string>, ctx: {
+        tagId: string;
+        usedServiceIds: Array<number | string>;
+        effectiveConstraints?: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+        policies?: unknown;
+        fallback?: FallbackSettings;
+    }): ServiceCheck[];
+}
+type QuantityRule = {
+    valueBy: "value" | "length" | "eval";
+    code?: string;
+};
+type ServiceCheck = {
+    id: number | string;
+    ok: boolean;
+    fitsConstraints: boolean;
+    passesRate: boolean;
+    passesPolicies: boolean;
+    policyErrors?: string[];
+    policyWarnings?: string[];
+    reasons: Array<"constraint_mismatch" | "rate_policy" | "policy_error" | "missing_capability">;
+    cap?: DgpServiceCapability;
+    rate?: number;
+};
+
+declare class CanvasAPI {
+    private bus;
+    private readonly state;
+    readonly builder: Builder;
+    readonly editor: Editor;
+    private readonly autoEmit;
+    readonly comments: CommentsAPI;
+    readonly selection: Selection;
+    constructor(builder: Builder, opts?: CanvasOptions & CanvasBackendOptions);
+    on: <K extends keyof CanvasEvents>(event: K, handler: (payload: CanvasEvents[K]) => void) => () => void;
+    once: <K extends keyof CanvasEvents>(event: K, handler: (payload: CanvasEvents[K]) => void) => () => void;
+    emit<K extends keyof CanvasEvents>(event: K, payload: CanvasEvents[K]): void;
+    snapshot(): CanvasState;
+    getGraph(): GraphSnapshot;
+    getSelection(): string[];
+    getViewport(): Viewport;
+    refreshGraph(): void;
+    setPositions(pos: NodePositions): void;
+    setPosition(id: string, x: number, y: number): void;
+    select(ids: string[] | Set<string>): void;
+    addToSelection(ids: string[] | Set<string>): void;
+    toggleSelection(id: string): void;
+    clearSelection(): void;
+    selectComments(threadId?: string): void;
+    setHighlighted(ids: string[] | Set<string>): void;
+    setHover(id?: string): void;
+    setViewport(v: Partial<Viewport>): void;
+    startWire(from: string, kind: DraftWire["kind"]): void;
+    previewWire(to?: string): void;
+    commitWire(to: string): void;
+    cancelWire(): void;
+    private bump;
+    dispose(): void;
+    undo(): void;
+    private edgeRel;
+    getEdgeRel(): EdgeKind;
+    setEdgeRel(rel: EdgeKind): void;
+    /** Internal mirror of which fields should show their options as nodes. */
+    private shownOptionFields;
+    /** Return the field ids whose options are currently set to be visible as nodes. */
+    getShownOptionFields(): string[];
+    /** True if this field’s options are shown as nodes. */
+    isFieldOptionsShown(fieldId: string): boolean;
+    /**
+     * Set visibility of option nodes for a field, then rebuild the graph.
+     * When shown = true, the Builder will emit option nodes for this field.
+     */
+    setFieldOptionsShown(fieldId: string, shown: boolean): void;
+    /** Toggle option-node visibility for a field. Returns the new visibility. */
+    toggleFieldOptions(fieldId: string): boolean;
+    /**
+     * Replace the whole set of fields whose options are visible as nodes.
+     * Useful for restoring a saved UI state.
+     */
+    setShownOptionFields(ids: Iterable<string>): void;
+    getConstraints(): {
+        id: string;
+        label: string;
+        description: string;
+        value: string;
+    }[];
+    getServiceProps(): ServiceProps;
+}
+
+type FormSnapshot = {
+    values: Record<string, Scalar | Scalar[]>;
+    selections: Record<string, string[]>;
+};
+type FormApi = {
+    /** Scalar/array value by fieldId (non-option inputs) */
+    get: (fieldId: string) => Scalar | Scalar[] | undefined;
+    set: (fieldId: string, value: Scalar | Scalar[]) => void;
+    /** Option selections by fieldId (array of optionIds) */
+    getSelections: (fieldId: string) => string[];
+    setSelections: (fieldId: string, optionIds: string[]) => void;
+    toggleSelection: (fieldId: string, optionId: string) => void;
+    /** Read-only snapshot for debugging */
+    snapshot: () => FormSnapshot;
+    /** Simple subscribe (re-render triggers) */
+    subscribe: (fn: () => void) => () => void;
+};
+declare function FormProvider({ initial, children, }: {
+    initial?: Partial<FormSnapshot>;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Strict hook (throws if no provider) */
+declare function useFormApi(): FormApi;
+/** Optional hook (returns null if no provider) */
+declare function useOptionalFormApi(): FormApi | null;
+/** Field-scoped helpers */
+declare function useFormField(fieldId: string): {
+    value: Scalar | Scalar[] | undefined;
+    set: (value: Scalar | Scalar[]) => void;
+};
+declare function useFormSelections(fieldId: string): {
+    selected: string[];
+    set: (optionIds: string[]) => void;
+    toggle: (optionId: string) => void;
+};
+
+/** Matches your InputWrapper’s expectations */
+type InputKind = string;
+type InputVariant = 'default' | (string & {});
+type InputAdapter = {
+    /** Prop name where the value goes on the host component (default: "value") */
+    valueProp?: string;
+    /** Prop name of the change handler on the host component (default: "onChange") */
+    changeProp?: string;
+    /**
+     * Normalize the host's change payload into a Scalar | Scalar[] your form will store.
+     * If omitted, `next as Scalar | Scalar[]` is used.
+     */
+    getValue?: (next: unknown, prev: unknown) => Scalar | Scalar[];
+};
+type InputDescriptor = {
+    Component: React.ComponentType<Record<string, unknown>>;
+    adapter?: InputAdapter;
+    defaultProps?: Record<string, unknown>;
+};
+type VariantMap = Map<InputVariant, InputDescriptor>;
+type RegistryStore = Map<InputKind, VariantMap>;
+type Registry = {
+    get(kind: InputKind, variant?: InputVariant): InputDescriptor | undefined;
+    register(kind: InputKind, descriptor: InputDescriptor, variant?: InputVariant): void;
+    unregister(kind: InputKind, variant?: InputVariant): void;
+    registerMany(entries: Array<{
+        kind: InputKind;
+        descriptor: InputDescriptor;
+        variant?: InputVariant;
+    }>): void;
+    /** low-level escape hatch */
+    _store: RegistryStore;
+};
+declare function createInputRegistry(): Registry;
+/** Helper used by InputWrapper */
+declare function resolveInputDescriptor(registry: Registry, kind: InputKind, variant?: InputVariant): InputDescriptor | undefined;
+
+type InputsCtxValue = {
+    registry: Registry;
+    register: (kind: InputKind, descriptor: InputDescriptor, variant?: InputVariant) => void;
+    unregister: (kind: InputKind, variant?: InputVariant) => void;
+    registerMany: (entries: Array<{
+        kind: InputKind;
+        descriptor: InputDescriptor;
+        variant?: InputVariant;
+    }>) => void;
+};
+declare function Provider({ children, initialRegistry, }: {
+    children: ReactNode;
+    /** Optional pre-built registry (e.g., you registered built-ins/customs before mounting) */
+    initialRegistry?: Registry;
+}): react_jsx_runtime.JSX.Element;
+declare function useInputs(): InputsCtxValue;
+
+type InputWrapperProps = {
+    field: Field;
+    disabled?: boolean;
+    /** Extra props to forward to the host component (low priority, overridden by adapter wiring). */
+    extraProps?: Record<string, unknown>;
+};
+type OnChangeValue = ButtonValue | ButtonValue[];
+declare function Wrapper({ field, disabled, extraProps, }: InputWrapperProps): react_jsx_runtime.JSX.Element | null;
+
+export { type AdminPolicies, type BaseFieldUI, type ButtonValue, CanvasAPI, type CanvasEvents, type CanvasOptions, type CanvasState, type Command, type CommentAnchor, type CommentId, type CommentMessage, type CommentNode, type CommentThread, type ConnectKind, type ConstraintKey, type DgpServiceCapability, type DgpServiceMap, type DraftWire, type DynamicRule, type EdgeKind, type EdgeRoute, type EdgeView, type EditorEvents, type EditorOptions, type EditorSnapshot, EventBus, type EventMap, type FallbackDiagnostics, type FallbackSettings, type Field, type FieldOption, type FieldType, type FieldWithTypedDefaults, type FlagKey, type FlowNode, type FormApi, FormProvider, type FormSnapshot, type GraphEdge, type GraphNode, type GraphSnapshot, type IdType, type InputAdapter, type InputDescriptor, type InputKind, type InputVariant, type InputWrapperProps, type LayoutState, type NodeIdRef, type NodeKind, type NodePos, type NodePositions, type NodeView, type OnChangeValue, type OrderSnapshot, type PricingRole, Provider, type QuantityMark, type QuantityRule$1 as QuantityRule, type RatePolicy, type Registry, type Scalar, type ServiceEstimates, type ServiceFallback, type ServiceFallbacks, type ServiceFlag, type ServiceFlags, type ServiceIdRef, type ServiceProps, type ServiceWhereClause, type ServiceWhereOp, type SnapshotContext, type SpeedEstimate, type Tag, type ThreadId, type TimeRangeEstimate, type Ui, type UiAnyOf, type UiArray, type UiBoolean, type UiNumber, type UiObject, type UiString, type UiValue, type UtilityLineItem, type UtilityMark, type UtilityMode, type ValidationCode, type ValidationError, type ValidatorOptions, type Viewport, type WithQuantityDefault, Wrapper, createInputRegistry, resolveInputDescriptor, useFormApi, useFormField, useFormSelections, useInputs, useOptionalFormApi };