@webskill/sdk 0.3.0 → 0.5.0

package/dist/ui-react.d.ts

@@ -1,20 +1,279 @@
-import { C as UiSurfaceDrafts, D as UiSurfaceSnapshot, S as UiSurfaceActionResponse, _ as RenderResultRequest, b as UiSurfaceAction, o as InteractionRequest, s as InteractionResponse, v as UiBridge, w as UiSurfaceEvent, x as UiSurfaceActionRequest } from "./types-AmKCKJn_-VGabeXK4.js";
-import { B as UiSpecNode } from "./index-wiV5X8Rz.js";
+import { C as UiSpecEvent, D as UiSurfaceActionResponse, E as UiSurfaceActionRequest, S as UiSpecDrafts, T as UiSpecSnapshot, b as UiBridge, c as InteractionResponse, mt as UiSpecNode, s as InteractionRequest, x as UiSpecActionCapability, y as RenderResultRequest } from "./types-D_hoCri8-BnNPiZCi.js";
+import { b as InteractionSpecLabels } from "./index-Bsqg4ftU.js";
 import { z } from "zod";
 import { ComponentType, ReactNode } from "react";
+import "react/jsx-runtime";
+//#region ../../node_modules/.pnpm/@json-render+core@0.19.0_zod@4.4.3/node_modules/@json-render/core/dist/store-utils-D98Czbil.d.ts
+/**
+ * Confirmation dialog configuration
+ */
+interface ActionConfirm {
+  title: string;
+  message: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  variant?: "default" | "danger";
+}
+/**
+ * Action success handler
+ */
+type ActionOnSuccess = {
+  navigate: string;
+} | {
+  set: Record<string, unknown>;
+} | {
+  action: string;
+};
+/**
+ * Action error handler
+ */
+type ActionOnError = {
+  set: Record<string, unknown>;
+} | {
+  action: string;
+};
+/**
+ * Action binding — maps an event to an action invocation.
+ *
+ * Used inside the `on` field of a UIElement:
+ * ```json
+ * { "on": { "press": { "action": "setState", "params": { "statePath": "/x", "value": 1 } } } }
+ * ```
+ */
+interface ActionBinding {
+  /** Action name (must be in catalog) */
+  action: string;
+  /** Parameters to pass to the action handler */
+  params?: Record<string, DynamicValue>;
+  /** Confirmation dialog before execution */
+  confirm?: ActionConfirm;
+  /** Handler after successful execution */
+  onSuccess?: ActionOnSuccess;
+  /** Handler after failed execution */
+  onError?: ActionOnError;
+  /** Whether to prevent default browser behavior (e.g. navigation on links) */
+  preventDefault?: boolean;
+}
+/**
+ * Dynamic value - can be a literal or a `{ $state }` reference to the state model.
+ *
+ * Used in action params and validation args where values can either be
+ * hardcoded or resolved from state at runtime.
+ */
+type DynamicValue<T = unknown> = T | {
+  $state: string;
+};
+/**
+ * Base UI element structure for v2
+ */
+interface UIElement<T extends string = string, P = Record<string, unknown>> {
+  /** Component type from the catalog */
+  type: T;
+  /** Component props */
+  props: P;
+  /** Child element keys (flat structure) */
+  children?: string[];
+  /** Visibility condition */
+  visible?: VisibilityCondition;
+  /** Event bindings — maps event names to action bindings */
+  on?: Record<string, ActionBinding | ActionBinding[]>;
+  /** Repeat children once per item in a state array */
+  repeat?: {
+    statePath: string;
+    key?: string;
+  };
+  /**
+   * State watchers — maps JSON Pointer state paths to action bindings.
+   * When the value at a watched path changes, the bound actions fire.
+   * Useful for cascading dependencies (e.g. country → city option loading).
+   */
+  watch?: Record<string, ActionBinding | ActionBinding[]>;
+}
+/**
+ * Shared comparison operators for visibility conditions.
+ *
+ * Use at most ONE comparison operator per condition. If multiple are
+ * provided, only the first matching one is evaluated (precedence:
+ * eq > neq > gt > gte > lt > lte). With no operator, truthiness is checked.
+ *
+ * `not` inverts the final result of whichever operator (or truthiness
+ * check) is used.
+ */
+type ComparisonOperators = {
+  eq?: unknown;
+  neq?: unknown;
+  gt?: number | {
+    $state: string;
+  };
+  gte?: number | {
+    $state: string;
+  };
+  lt?: number | {
+    $state: string;
+  };
+  lte?: number | {
+    $state: string;
+  };
+  not?: true;
+};
+/**
+ * A single state-based condition.
+ * Resolves `$state` to a value from the state model, then applies the operator.
+ * Without an operator, checks truthiness.
+ *
+ * When `not` is `true`, the result of the entire condition is inverted.
+ * For example `{ $state: "/count", gt: 5, not: true }` means "NOT greater than 5".
+ */
+type StateCondition = {
+  $state: string;
+} & ComparisonOperators;
+/**
+ * A condition that resolves `$item` to a field on the current repeat item.
+ * Only meaningful inside a `repeat` scope.
+ *
+ * Use `""` to reference the whole item, or `"field"` for a specific field.
+ */
+type ItemCondition = {
+  $item: string;
+} & ComparisonOperators;
+/**
+ * A condition that resolves `$index` to the current repeat array index.
+ * Only meaningful inside a `repeat` scope.
+ */
+type IndexCondition = {
+  $index: true;
+} & ComparisonOperators;
+/** A single visibility condition (state, item, or index). */
+type SingleCondition = StateCondition | ItemCondition | IndexCondition;
+/**
+ * AND wrapper — all child conditions must be true.
+ * This is the explicit form of the implicit array AND (`SingleCondition[]`).
+ * Unlike the implicit form, `$and` supports nested `$or` and `$and` conditions.
+ */
+type AndCondition = {
+  $and: VisibilityCondition[];
+};
+/**
+ * OR wrapper — at least one child condition must be true.
+ */
+type OrCondition = {
+  $or: VisibilityCondition[];
+};
+/**
+ * Visibility condition types.
+ * - `boolean` — always/never
+ * - `SingleCondition` — single condition (`$state`, `$item`, or `$index`)
+ * - `SingleCondition[]` — implicit AND (all must be true)
+ * - `AndCondition` — `{ $and: [...] }`, explicit AND (all must be true)
+ * - `OrCondition` — `{ $or: [...] }`, at least one must be true
+ */
+type VisibilityCondition = boolean | SingleCondition | SingleCondition[] | AndCondition | OrCondition;
+/**
+ * State model type
+ */
+type StateModel = Record<string, unknown>;
+//#endregion
+//#region ../../node_modules/.pnpm/@json-render+react@0.19.0_react@19.2.8_zod@4.4.3/node_modules/@json-render/react/dist/index.d.ts
+/**
+ * State setter function for updating application state
+ */
+type SetState = (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
+/**
+ * Handle returned by the `on()` function for a specific event.
+ * Provides metadata about the event binding and a method to fire it.
+ *
+ * @example
+ * ```ts
+ * const press = on("press");
+ * if (press.shouldPreventDefault) e.preventDefault();
+ * press.emit();
+ * ```
+ */
+interface EventHandle {
+  /** Fire the event (resolve action bindings) */
+  emit: () => void;
+  /** Whether any binding requested preventDefault */
+  shouldPreventDefault: boolean;
+  /** Whether any handler is bound to this event */
+  bound: boolean;
+}
+/**
+ * Props passed to component renderers
+ */
+interface ComponentRenderProps<P = Record<string, unknown>> {
+  /** The element being rendered */
+  element: UIElement<string, P>;
+  /** Rendered children */
+  children?: ReactNode;
+  /** Emit a named event. The renderer resolves the event to action binding(s) from the element's `on` field. Always provided by the renderer. */
+  emit: (event: string) => void;
+  /** Get an event handle with metadata (shouldPreventDefault, bound). Use when you need to inspect event bindings. */
+  on: (event: string) => EventHandle;
+  /**
+   * Two-way binding paths resolved from `$bindState` / `$bindItem` expressions.
+   * Maps prop name → absolute state path for write-back.
+   * Only present when at least one prop uses `{ $bindState: "..." }` or `{ $bindItem: "..." }`.
+   */
+  bindings?: Record<string, string>;
+  /** Whether the parent is loading */
+  loading?: boolean;
+}
+/**
+ * Component renderer type
+ */
+type ComponentRenderer<P = Record<string, unknown>> = ComponentType<ComponentRenderProps<P>>;
+/**
+ * Registry of component renderers
+ */
+type ComponentRegistry = Record<string, ComponentRenderer<any>>;
+/**
+ * Result returned by defineRegistry
+ */
+interface DefineRegistryResult {
+  /** Component registry for `<Renderer registry={...} />` */
+  registry: ComponentRegistry;
+  /**
+   * Create ActionProvider-compatible handlers.
+   * Accepts getter functions so handlers always read the latest state/setState
+   * (e.g. from React refs).
+   */
+  handlers: (getSetState: () => SetState | undefined, getState: () => StateModel) => Record<string, (params: Record<string, unknown>) => Promise<void>>;
+  /**
+   * Execute an action by name imperatively
+   * (for use outside the React tree, e.g. initial state loading).
+   */
+  executeAction: (actionName: string, params: Record<string, unknown> | undefined, setState: SetState, state?: StateModel) => Promise<void>;
+}
+//#endregion
 //#region ../ui-react/dist/index.d.ts
 //#region src/surfaceStore.d.ts
 /** Observable, revision-checked snapshot store for framework-neutral UI surfaces. @experimental */
 declare class UiSurfaceStore {
   #private;
   subscribe: (listener: () => void) => (() => void);
-  get snapshots(): readonly UiSurfaceSnapshot[];
-  apply(event: UiSurfaceEvent): void;
+  get snapshots(): readonly UiSpecSnapshot[];
+  apply(event: UiSpecEvent): void;
 }
 //#endregion
 //#region src/bridgeState.d.ts
+/**
+ * 一次被丢弃的 surface action（FR-11.7）。
+ *
+ * 丢弃本身是对的（重放/串扰防护），但静默丢弃会让「点了没反应」变成无从排查的现象。
+ * @experimental
+ */
+interface DroppedSurfaceActionWarning {
+  /** duplicate：nonce 已被消费；no-pending：当前没有等待中的动作；mismatch：与待决动作不是同一个 */
+  reason: 'duplicate' | 'no-pending' | 'mismatch';
+  nonce: string;
+  message: string;
+  /** 丢弃发生时的待决状态，用于定位串扰 */
+  pending: UiSurfaceActionRequest | null;
+}
 interface ReactBridgeStateOptions {
   onSurfaceDraftChange?(runId: string, surfaceId: string, value: Record<string, unknown>): Promise<void> | void;
+  /** 覆盖默认的 console.warn 上报（测试与宿主遥测用）。@experimental */
+  onDroppedSurfaceAction?(warning: DroppedSurfaceActionWarning): void;
 }
 /**
  * React 桥接状态：UiBridge 实现 + useSyncExternalStore 兼容订阅。
@@ -30,9 +289,9 @@ declare class ReactBridgeState implements UiBridge {
   streamingRunId: string | null;
   streamingText: string;
   constructor(options?: ReactBridgeStateOptions);
-  get surfaceSnapshots(): readonly UiSurfaceSnapshot[];
-  surfaceDrafts(runId: string): UiSurfaceDrafts;
-  restoreSurfaceDrafts(runId: string, drafts: UiSurfaceDrafts | undefined): void;
+  get surfaceSnapshots(): readonly UiSpecSnapshot[];
+  surfaceDrafts(runId: string): UiSpecDrafts;
+  restoreSurfaceDrafts(runId: string, drafts: UiSpecDrafts | undefined): void;
   setSurfaceDraft(runId: string, surfaceId: string, value: Record<string, unknown>): void;
   /** React useSyncExternalStore 兼容订阅 */
   subscribe: (listener: () => void) => (() => void);
@@ -42,9 +301,12 @@ declare class ReactBridgeState implements UiBridge {
   /** runtime 交互超时/取消：卸载表单并以 cancelled resolve pending Promise（防悬挂 + 残留） */
   cancel(id: string): void;
   renderResult(input: RenderResultRequest): Promise<void>;
-  renderSurface(event: UiSurfaceEvent): Promise<void>;
+  renderSurface(event: UiSpecEvent): Promise<void>;
   requestSurfaceAction(input: UiSurfaceActionRequest): Promise<UiSurfaceActionResponse>;
-  /** Resolves exactly one pending action capability; stale or duplicate nonces are ignored. */
+  /**
+   * Resolves exactly one pending action capability; stale or duplicate nonces are ignored.
+   * Every ignored response is reported through `onDroppedSurfaceAction` (FR-11.7).
+   */
   resolveSurfaceAction(response: UiSurfaceActionResponse): boolean;
   cancelSurfaceAction(nonce: string): void;
   onTextDelta(runId: string, delta: string): Promise<void>;
@@ -72,14 +334,16 @@ declare function StreamingText({ bridge }: {
 interface CustomSurfaceActionEvent {
   surfaceId: string;
   actionId: string;
-  intent: UiSurfaceAction['intent'];
+  intent: UiSpecActionCapability['intent'];
   nonce?: string;
+  /** 提交动作所属的表单容器；一张 surface 只有一个表单时省略 */
+  scopeId?: string;
   value?: Record<string, unknown>;
 }
 interface RegisteredSurfaceProps<Props> {
   surfaceId: string;
   props: Props;
-  actions: readonly UiSurfaceAction[];
+  actions: readonly UiSpecActionCapability[];
   onAction?(event: CustomSurfaceActionEvent): void;
 }
 interface SurfaceRegistration<Props> {
@@ -102,7 +366,7 @@ interface UiSurfaceActionEvent {
   runId?: string;
   surfaceId: string;
   actionId: string;
-  intent: UiSurfaceAction['intent'];
+  intent: UiSpecActionCapability['intent'];
   nonce?: string;
   value?: Record<string, unknown>;
 }
@@ -114,10 +378,10 @@ interface UiSurfaceListProps {
   onAction?(event: UiSurfaceActionEvent): void;
 }
 interface UiSurfaceSnapshotListProps {
-  snapshots: readonly UiSurfaceSnapshot[];
+  snapshots: readonly UiSpecSnapshot[];
   registry?: SurfaceRegistry;
   onAction?(event: UiSurfaceActionEvent): void;
-  drafts?: UiSurfaceDrafts;
+  drafts?: UiSpecDrafts;
   onDraftChange?(event: {
     runId: string;
     surfaceId: string;
@@ -135,35 +399,103 @@ declare const NATIVE_SPEC_COMPONENTS: readonly string[];
 interface NativeSpecSurfaceProps {
   surfaceId: string;
   spec: UiSpecNode;
-  actions: readonly UiSurfaceAction[];
+  actions: readonly UiSpecActionCapability[];
   registry?: SurfaceRegistry;
+  /** 草稿归属的运行；缺省表示不持久化（历史回放） */
+  runId?: string;
+  draft?: Record<string, unknown>;
   onAction?(event: CustomSurfaceActionEvent): void;
+  onDraftChange?(event: {
+    runId: string;
+    surfaceId: string;
+    value: Record<string, unknown>;
+  }): void;
 }
 /**
  * Native 档的 catalog registry：把声明树渲染成 ui-kit 组件。
  * 越界组件名不静默降级，渲染成英文错误行（21 号文档 §8 第 5 条）。
+ *
+ * 表单行为（草稿跨刷新、必填拦截、默认值）由本组件承接——
+ * 节点树取代六类 surface 后，这里是 native 档唯一的渲染实现。
  */
-declare function NativeSpecSurface({ surfaceId, spec, actions, registry, onAction }: NativeSpecSurfaceProps): import("react").JSX.Element;
+declare function NativeSpecSurface({ surfaceId, spec, actions, registry, runId, draft, onAction, onDraftChange }: NativeSpecSurfaceProps): import("react").JSX.Element;
 //#endregion
 //#region src/catalog/JsonRenderSpecSurface.d.ts
 interface JsonRenderSpecSurfaceProps {
   spec: UiSpecNode;
+  surfaceId: string;
+  actions?: readonly UiSpecActionCapability[];
+  onAction?: (event: CustomSurfaceActionEvent) => void;
 }
 /**
  * `vercel` 档：同一份 catalog 声明树交给 json-render 的 Registry 渲染。
  * `@json-render/*` 是 optional peer，未安装时给出英文说明而不是空白。
  */
-declare function JsonRenderSpecSurface({ spec }: JsonRenderSpecSurfaceProps): import("react").JSX.Element | null;
+declare function JsonRenderSpecSurface({ spec, surfaceId, actions, onAction }: JsonRenderSpecSurfaceProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/catalog/jsonRenderRegistry.d.ts
+/** catalog 的 action 名与 `UiSpecActionCapability['intent']` 一一对应 */
+type JsonRenderActionDispatch = (intent: string, params: Record<string, unknown>) => void;
+/**
+ * registry 是白名单：catalog 之外的组件名在 Renderer 里直接落到 fallback。
+ *
+ * 工厂而非模块级单例：action 的派发出口要绑定到具体 surface 的回传通道，
+ * 模块级单例会让同屏两个 surface 互相串台。
+ */
+declare function createJsonRenderRegistry(dispatch: JsonRenderActionDispatch): DefineRegistryResult;
+//#endregion
+//#region src/interaction/specInteractionChannel.d.ts
+/** 一次待决交互（节点树由 react 层交给本档的 spec surface 渲染） */
+interface SpecInteractionSession {
+  request: InteractionRequest;
+  spec: UiSpecNode;
+}
+/**
+ * 探测 json-render 渲染器是否可用（@json-render/* 为 optional peer）。
+ * 交互视图据此在缺包时调 SpecInteractionChannel.fail，让复合桥粘性降级 native 而不是悬挂请求。
+ */
+declare function probeJsonRenderAvailability(): Promise<boolean>;
+/**
+ * 非 native 档的交互通道（路径 A，三档共用）：
+ * - request() 把 InteractionRequest 经 interactionToUiSpec 转成 catalog 节点树并挂起，
+ *   react 层订阅 current 后用本档已有的 spec 渲染路径（*SpecSurface）渲染；
+ * - 表单提交/取消经 handleAction 回传（submit → shapeInteractionValue；cancel → cancelled）；
+ * - react 层初始化失败调 fail()：挂起请求 reject（桥据此粘性降级 native）并记录原因；
+ * - attach/detach 标记渲染视图是否挂载（未挂载时桥直接降级 native，不悬挂请求）。
+ */
+declare class SpecInteractionChannel {
+  #private;
+  /** 宿主注入的界面文案（本地化）；未设时用 FormModel 的英文默认值 */
+  labelsFor: (request: InteractionRequest) => InteractionSpecLabels;
+  /** React useSyncExternalStore 兼容订阅 */
+  subscribe: (listener: () => void) => (() => void);
+  get current(): SpecInteractionSession | undefined;
+  get isAttached(): boolean;
+  /** react 层初始化失败原因（optional peer 未安装等）；记录后粘性生效 */
+  get failure(): string | undefined;
+  attach(): void;
+  detach(): void;
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+  /** runtime 交互超时/取消：以 cancelled resolve 挂起的 request（防悬挂 + 残留） */
+  cancel(id: string): void;
+  /** react 层动作回传：submit 归形提交值，其余意图（cancel）按取消收尾 */
+  handleAction(event: CustomSurfaceActionEvent): void;
+  /** react 层初始化失败：挂起请求 reject 并记录原因（桥读取后降级 native） */
+  fail(message: string): void;
+}
 //#endregion
 //#region src/catalog/OpenUiSpecSurface.d.ts
 interface OpenUiSpecSurfaceProps {
   spec: UiSpecNode;
+  surfaceId: string;
+  actions?: readonly UiSpecActionCapability[];
+  onAction?: (event: CustomSurfaceActionEvent) => void;
 }
 /**
  * `openui` 档：同一份 catalog 声明树经 openui-lang 交给 OpenUI 的 Renderer。
  * `@openuidev/react-lang` 是 optional peer，未安装时给出英文说明而不是空白。
  */
-declare function OpenUiSpecSurface({ spec }: OpenUiSpecSurfaceProps): import("react").JSX.Element | null;
+declare function OpenUiSpecSurface({ spec, surfaceId, actions, onAction }: OpenUiSpecSurfaceProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/catalog/catalogComponents.d.ts
 type CatalogNodeProps = {
@@ -171,10 +503,10 @@ type CatalogNodeProps = {
   children?: ReactNode;
 };
 /**
- * catalog 16 个组件的展示实现：json-render 与 OpenUI 两档共用同一份，
+ * catalog 展示类组件的实现：json-render 与 OpenUI 两档共用同一份，
  * 避免"一个 catalog、多套 registry"退化成多套各自演进的视觉。
  * 交互（表单值收集 / action 回传）由各档的宿主组件负责。
  */
 declare const catalogComponentImpls: Record<string, (input: CatalogNodeProps) => ReactNode>;
 //#endregion
-export { type CatalogNodeProps, type CustomSurfaceActionEvent, InteractionForm, JsonRenderSpecSurface, type JsonRenderSpecSurfaceProps, NATIVE_SPEC_COMPONENTS, NativeSpecSurface, type NativeSpecSurfaceProps, OpenUiSpecSurface, type OpenUiSpecSurfaceProps, ReactBridgeState, type RegisteredSurfaceProps, ResultBlocks, StreamingText, type SurfaceRegistration, SurfaceRegistry, type UiSurfaceActionEvent, UiSurfaceList, type UiSurfaceListProps, UiSurfaceSnapshotList, type UiSurfaceSnapshotListProps, UiSurfaceStore, catalogComponentImpls };
+export { type CatalogNodeProps, type CustomSurfaceActionEvent, type DroppedSurfaceActionWarning, InteractionForm, type JsonRenderActionDispatch, JsonRenderSpecSurface, type JsonRenderSpecSurfaceProps, NATIVE_SPEC_COMPONENTS, NativeSpecSurface, type NativeSpecSurfaceProps, OpenUiSpecSurface, type OpenUiSpecSurfaceProps, ReactBridgeState, type ReactBridgeStateOptions, type RegisteredSurfaceProps, ResultBlocks, SpecInteractionChannel, type SpecInteractionSession, StreamingText, type SurfaceRegistration, SurfaceRegistry, type UiSurfaceActionEvent, UiSurfaceList, type UiSurfaceListProps, UiSurfaceSnapshotList, type UiSurfaceSnapshotListProps, UiSurfaceStore, catalogComponentImpls, createJsonRenderRegistry, probeJsonRenderAvailability };