@qontinui/shared-types 0.2.4 → 0.3.0

package/src/ui-bridge-ir/state.ts

@@ -1,90 +1,97 @@
-/**
- * IR-level state declaration.
- *
- * Authoring-time superset of ui-bridge-auto's runtime State shape. The
- * IR -> WorkflowConfig adapter strips IR-only fields (provenance, metadata,
- * elementIds, incomingTransitions, visualRefs) before handing to the runtime.
- */
-
-import type { IRElementCriteria } from "./element-criteria";
-import type { IRCrossRef, IRMetadata, IRProvenance, IRVisualRef } from "./primitives";
-
-/**
- * Property-level condition on a matched element. Mirrors
- * `StateCondition` in ui-bridge-auto/src/types/state.ts:83.
- */
-export interface IRStateCondition {
-  element: IRElementCriteria;
-  property:
-    | "visible"
-    | "enabled"
-    | "checked"
-    | "expanded"
-    | "selected"
-    | "text"
-    | "value";
-  expected: unknown;
-  comparator?: "equals" | "contains" | "matches" | "greaterThan" | "lessThan";
-}
-
-/**
- * IR state declaration.
- *
- * Anchored to ui-bridge-auto's `State` shape (ui-bridge-auto/src/types/state.ts:23)
- * — extends it with IR-only fields. Runtime tracking fields (enteredAt,
- * exitedAt, observationCount) are deliberately absent: those are managed by
- * the state machine at execution time.
- */
-export interface IRState {
-  // Identity --------------------------------------------------------------
-  id: string;
-  name: string;
-  description?: string;
-
-  // Predicates (canonical) -----------------------------------------------
-  /** Element criteria that must ALL be satisfied for this state to be active. */
-  requiredElements: IRElementCriteria[];
-  /** Element criteria where NONE may be satisfied (any match disqualifies). */
-  excludedElements?: IRElementCriteria[];
-  /** Additional property checks on matched elements. */
-  conditions?: IRStateCondition[];
-
-  // Lifecycle / pathfinding hints ----------------------------------------
-  /** Whether this is a valid initial/starting state. */
-  isInitial?: boolean;
-  /** Whether this is a terminal state (no outgoing transitions). */
-  isTerminal?: boolean;
-  /** Whether this state is modal/blocking (e.g., a dialog). */
-  blocking?: boolean;
-  /** Logical group this state belongs to. */
-  group?: string;
-  /** Navigation cost weight for pathfinding (default 1.0). */
-  pathCost?: number;
-  /**
-   * Free-text precondition required for this state to be entered, mirroring
-   * legacy `assertion.precondition` strings (e.g., "A workflow is paused at a
-   * breakpoint"). Authoring-time documentation; not enforced at runtime.
-   */
-  precondition?: string;
-
-  // IR-only fields (stripped by adapter) ---------------------------------
-  /**
-   * Optional companion list of element IDs that resolved at registration
-   * time. The runtime SDK fills this in when criteria resolve to specific
-   * registered elements. Authors do not set this directly.
-   */
-  elementIds?: string[];
-  /**
-   * Derived/computed at IR-emission time — list of transitions that activate
-   * this state. Authoring-time hint for visualization; not authored directly.
-   */
-  incomingTransitions?: string[];
-  /** Semantic metadata routed through useUIAnnotation store at runtime. */
-  metadata?: IRMetadata;
-  /** Where this declaration came from. */
-  provenance?: IRProvenance;
-  /** Cross-document references. */
-  crossRefs?: IRCrossRef[];
-  /** Optional visual reference (section 8). */
-  visualRefs?: IRVisualRef[];
-}
+/**
+ * IR-level state declaration.
+ *
+ * Authoring-time superset of ui-bridge-auto's runtime State shape. The
+ * IR -> WorkflowConfig adapter strips IR-only fields (provenance, metadata,
+ * elementIds, incomingTransitions, visualRefs) before handing to the runtime.
+ */
+
+import type { IRElementCriteria } from "./element-criteria";
+import type { IRAssertion } from "./group";
+import type { IRCrossRef, IRMetadata, IRProvenance, IRVisualRef } from "./primitives";
+
+/**
+ * Property-level condition on a matched element. Mirrors
+ * `StateCondition` in ui-bridge-auto/src/types/state.ts:83.
+ */
+export interface IRStateCondition {
+  element: IRElementCriteria;
+  property:
+    | "visible"
+    | "enabled"
+    | "checked"
+    | "expanded"
+    | "selected"
+    | "text"
+    | "value";
+  expected: unknown;
+  comparator?: "equals" | "contains" | "matches" | "greaterThan" | "lessThan";
+}
+
+/**
+ * IR state declaration.
+ *
+ * Anchored to ui-bridge-auto's `State` shape (ui-bridge-auto/src/types/state.ts:23)
+ * — extends it with IR-only fields. Runtime tracking fields (enteredAt,
+ * exitedAt, observationCount) are deliberately absent: those are managed by
+ * the state machine at execution time.
+ */
+export interface IRState {
+  // Identity --------------------------------------------------------------
+  id: string;
+  name: string;
+  description?: string;
+
+  // Predicates (canonical) -----------------------------------------------
+  /**
+   * State-scoped assertions. Each carries its own assertion_id, description,
+   * severity, category, and an IrElementCriteria target via target.criteria.
+   * Spec-Check (Plan 02) evaluates these against UI Bridge snapshots; policy
+   * filtering via `severity`/`category` is meaningful because each assertion
+   * carries its own metadata (no synthesized stubs).
+   */
+  assertions: IRAssertion[];
+  /** Element criteria where NONE may be satisfied (any match disqualifies). */
+  excludedElements?: IRElementCriteria[];
+  /** Additional property checks on matched elements. */
+  conditions?: IRStateCondition[];
+
+  // Lifecycle / pathfinding hints ----------------------------------------
+  /** Whether this is a valid initial/starting state. */
+  isInitial?: boolean;
+  /** Whether this is a terminal state (no outgoing transitions). */
+  isTerminal?: boolean;
+  /** Whether this state is modal/blocking (e.g., a dialog). */
+  blocking?: boolean;
+  /** Logical group this state belongs to. */
+  group?: string;
+  /** Navigation cost weight for pathfinding (default 1.0). */
+  pathCost?: number;
+  /**
+   * Free-text precondition required for this state to be entered, mirroring
+   * legacy `assertion.precondition` strings (e.g., "A workflow is paused at a
+   * breakpoint"). Authoring-time documentation; not enforced at runtime.
+   */
+  precondition?: string;
+
+  // IR-only fields (stripped by adapter) ---------------------------------
+  /**
+   * Optional companion list of element IDs that resolved at registration
+   * time. The runtime SDK fills this in when criteria resolve to specific
+   * registered elements. Authors do not set this directly.
+   */
+  elementIds?: string[];
+  /**
+   * Derived/computed at IR-emission time — list of transitions that activate
+   * this state. Authoring-time hint for visualization; not authored directly.
+   */
+  incomingTransitions?: string[];
+  /** Semantic metadata routed through useUIAnnotation store at runtime. */
+  metadata?: IRMetadata;
+  /** Where this declaration came from. */
+  provenance?: IRProvenance;
+  /** Cross-document references. */
+  crossRefs?: IRCrossRef[];
+  /** Optional visual reference (section 8). */
+  visualRefs?: IRVisualRef[];
+}

package/src/ui-bridge-ir/transition.ts

@@ -1,92 +1,92 @@
-/**
- * IR-level transition declaration.
- *
- * Anchored to ui-bridge-auto's `Transition` shape
- * (ui-bridge-auto/src/types/transition.ts:103) and extended with IR-only
- * fields (effect, provenance, crossRefs).
- *
- * `exitStates` is a HINT at the IR level — when omitted, the adapter populates
- * `[]` so the runtime contract (which requires the field) is satisfied.
- */
-
-import type { IRElementCriteria } from "./element-criteria";
-import type { IRCrossRef, IREffect, IRMetadata, IRProvenance } from "./primitives";
-
-/**
- * Wait specification for the runtime to settle after an action.
- * Mirrors `WaitSpec` in ui-bridge-auto/src/types/transition.ts:56.
- */
-export interface IRWaitSpec {
-  type: "idle" | "element" | "state" | "time" | "condition" | "vanish" | "change" | "stable";
-  query?: IRElementCriteria;
-  stateId?: string;
-  ms?: number;
-  timeout?: number;
-  property?: string;
-  quietPeriodMs?: number;
-}
-
-/**
- * A single action step within a transition. Mirrors `TransitionAction` in
- * ui-bridge-auto/src/types/transition.ts:81 with the difference that `type`
- * is a free-form string here — the IR doesn't bind authors to a specific
- * action vocabulary; that constraint applies at the runtime adapter layer.
- */
-export interface IRTransitionAction {
-  /** The action to perform (e.g., "click", "type", "submit"). */
-  type: string;
-  /** Criteria to find the target element. */
-  target: IRElementCriteria;
-  /** Action-specific parameters. */
-  params?: Record<string, unknown>;
-  /** Optional wait specification applied after this action completes. */
-  waitAfter?: IRWaitSpec;
-}
-
-/**
- * IR transition declaration.
- *
- * Authoring-time superset of ui-bridge-auto's `Transition`. Reliability
- * tracking fields (successCount, failureCount, averageDurationMs,
- * lastExecutedAt) are deliberately absent — the runtime owns them.
- */
-export interface IRTransition {
-  // Identity --------------------------------------------------------------
-  id: string;
-  name: string;
-  description?: string;
-
-  // Pre/post conditions ---------------------------------------------------
-  /** Precondition: all of these states must be active. */
-  fromStates: string[];
-  /** States to enter after the transition completes. */
-  activateStates: string[];
-  /**
-   * States to leave after the transition completes.
-   *
-   * IR-level HINT: omit it and the adapter defaults to `[]`. The runtime
-   * type (`Transition.exitStates: string[]` in
-   * ui-bridge-auto/src/types/transition.ts:116) requires the field; the
-   * adapter normalizes.
-   */
-  exitStates?: string[];
-
-  // Action sequence -------------------------------------------------------
-  actions: IRTransitionAction[];
-
-  // Pathfinding hints -----------------------------------------------------
-  /** Navigation cost for pathfinding (default 1.0). */
-  pathCost?: number;
-  /** Whether this transition can be reversed. */
-  bidirectional?: boolean;
-
-  // IR-only fields (stripped by adapter) ----------------------------------
-  /** Side-effect annotation. Drives counterfactual + auto-regression gating. */
-  effect?: IREffect;
-  /** Semantic metadata routed through useUIAnnotation store at runtime. */
-  metadata?: IRMetadata;
-  /** Where this declaration came from. */
-  provenance?: IRProvenance;
-  /** Cross-document references. */
-  crossRefs?: IRCrossRef[];
-}
+/**
+ * IR-level transition declaration.
+ *
+ * Anchored to ui-bridge-auto's `Transition` shape
+ * (ui-bridge-auto/src/types/transition.ts:103) and extended with IR-only
+ * fields (effect, provenance, crossRefs).
+ *
+ * `exitStates` is a HINT at the IR level — when omitted, the adapter populates
+ * `[]` so the runtime contract (which requires the field) is satisfied.
+ */
+
+import type { IRElementCriteria } from "./element-criteria";
+import type { IRCrossRef, IREffect, IRMetadata, IRProvenance } from "./primitives";
+
+/**
+ * Wait specification for the runtime to settle after an action.
+ * Mirrors `WaitSpec` in ui-bridge-auto/src/types/transition.ts:56.
+ */
+export interface IRWaitSpec {
+  type: "idle" | "element" | "state" | "time" | "condition" | "vanish" | "change" | "stable";
+  query?: IRElementCriteria;
+  stateId?: string;
+  ms?: number;
+  timeout?: number;
+  property?: string;
+  quietPeriodMs?: number;
+}
+
+/**
+ * A single action step within a transition. Mirrors `TransitionAction` in
+ * ui-bridge-auto/src/types/transition.ts:81 with the difference that `type`
+ * is a free-form string here — the IR doesn't bind authors to a specific
+ * action vocabulary; that constraint applies at the runtime adapter layer.
+ */
+export interface IRTransitionAction {
+  /** The action to perform (e.g., "click", "type", "submit"). */
+  type: string;
+  /** Criteria to find the target element. */
+  target: IRElementCriteria;
+  /** Action-specific parameters. */
+  params?: Record<string, unknown>;
+  /** Optional wait specification applied after this action completes. */
+  waitAfter?: IRWaitSpec;
+}
+
+/**
+ * IR transition declaration.
+ *
+ * Authoring-time superset of ui-bridge-auto's `Transition`. Reliability
+ * tracking fields (successCount, failureCount, averageDurationMs,
+ * lastExecutedAt) are deliberately absent — the runtime owns them.
+ */
+export interface IRTransition {
+  // Identity --------------------------------------------------------------
+  id: string;
+  name: string;
+  description?: string;
+
+  // Pre/post conditions ---------------------------------------------------
+  /** Precondition: all of these states must be active. */
+  fromStates: string[];
+  /** States to enter after the transition completes. */
+  activateStates: string[];
+  /**
+   * States to leave after the transition completes.
+   *
+   * IR-level HINT: omit it and the adapter defaults to `[]`. The runtime
+   * type (`Transition.exitStates: string[]` in
+   * ui-bridge-auto/src/types/transition.ts:116) requires the field; the
+   * adapter normalizes.
+   */
+  exitStates?: string[];
+
+  // Action sequence -------------------------------------------------------
+  actions: IRTransitionAction[];
+
+  // Pathfinding hints -----------------------------------------------------
+  /** Navigation cost for pathfinding (default 1.0). */
+  pathCost?: number;
+  /** Whether this transition can be reversed. */
+  bidirectional?: boolean;
+
+  // IR-only fields (stripped by adapter) ----------------------------------
+  /** Side-effect annotation. Drives counterfactual + auto-regression gating. */
+  effect?: IREffect;
+  /** Semantic metadata routed through useUIAnnotation store at runtime. */
+  metadata?: IRMetadata;
+  /** Where this declaration came from. */
+  provenance?: IRProvenance;
+  /** Cross-document references. */
+  crossRefs?: IRCrossRef[];
+}