@qontinui/shared-types 0.2.1

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

@@ -0,0 +1,220 @@
+/**
+ * IR -> WorkflowConfig adapter.
+ *
+ * Single point of translation between authoring-time IR (with provenance,
+ * metadata, effect, crossRefs, visualRefs) and the runtime/storage shape
+ * that ui-bridge-auto consumes. See ADR-001 (decision #6 / #7) for the
+ * boundary rationale.
+ *
+ * The output is intentionally typed structurally — this module has no
+ * runtime dependency on ui-bridge-auto. ui-bridge-auto's own tests verify
+ * end-to-end compatibility with `engine.defineStates(...)` /
+ * `engine.defineTransitions(...)` (see
+ * `ui-bridge-auto/src/__tests__/spike-ir-contract.test.ts`).
+ */
+
+import type { IRElementCriteria } from "./element-criteria";
+import type { IRDocument } from "./document";
+import type { IRState, IRStateCondition } from "./state";
+import type { IRTransition, IRTransitionAction, IRWaitSpec } from "./transition";
+
+// ---------------------------------------------------------------------------
+// Output shapes — structural mirrors of ui-bridge-auto's WorkflowConfig.
+// Kept in sync via ui-bridge-auto's regression test, NOT compile-time
+// imports (qontinui-schemas has no runtime deps by design).
+// ---------------------------------------------------------------------------
+
+/** Mirrors `StateConfig` from ui-bridge-auto/src/config/workflow.ts:47. */
+export interface AdaptedState {
+  id: string;
+  name: string;
+  description?: string;
+  requiredElements: IRElementCriteria[];
+  excludedElements?: IRElementCriteria[];
+  conditions?: IRStateCondition[];
+  isInitial?: boolean;
+  isTerminal?: boolean;
+  blocking?: boolean;
+  group?: string;
+  pathCost?: number;
+}
+
+/**
+ * Mirrors the runtime `TransitionDefinition` shape from
+ * ui-bridge-auto/src/state/state-machine.ts:40.
+ *
+ * Note: ui-bridge-auto has two related Transition shapes — the storage shape
+ * (`TransitionConfig` in config/workflow.ts:54, with action field named
+ * `type`) and the runtime engine shape (`TransitionDefinition` in
+ * state-machine.ts:40, with action field named `action`). The runtime engine
+ * is what consumers actually pass adapter output into via
+ * `engine.defineTransitions(...)`, so the adapter targets the runtime shape.
+ */
+export interface AdaptedTransition {
+  id: string;
+  name: string;
+  description?: string;
+  fromStates: string[];
+  activateStates: string[];
+  /** Adapter normalizes IR's optional `exitStates` to a required array. */
+  exitStates: string[];
+  actions: AdaptedTransitionAction[];
+  pathCost?: number;
+  bidirectional?: boolean;
+}
+
+/**
+ * Mirrors the runtime `TransitionAction` from
+ * ui-bridge-auto/src/state/state-machine.ts:55.
+ *
+ * The IR uses `type` for the action verb (matching the storage-shape
+ * convention); the adapter renames it to `action` for the runtime engine.
+ *
+ * `waitAfter` is narrower than `IRWaitSpec` — the runtime engine accepts
+ * only a subset of wait types and a subset of fields. The adapter drops
+ * IR-only wait variants (e.g., `state`, `condition`) and IR-only fields
+ * (e.g., `property`, `quietPeriodMs`). Authors can still express richer
+ * waits in the IR; they just don't survive the runtime contract.
+ */
+export interface AdaptedWaitAfter {
+  type: "idle" | "element" | "time" | "vanish" | "change" | "stable";
+  query?: IRElementCriteria;
+  ms?: number;
+  timeout?: number;
+}
+
+export interface AdaptedTransitionAction {
+  /** Action verb — renamed from IR's `type` to match the runtime contract. */
+  action: string;
+  target: IRElementCriteria;
+  params?: Record<string, unknown>;
+  waitAfter?: AdaptedWaitAfter;
+}
+
+/** Mirrors `WorkflowConfig` from ui-bridge-auto/src/config/workflow.ts:67. */
+export interface AdaptedWorkflowConfig {
+  id: string;
+  name: string;
+  description?: string;
+  version?: string;
+  states: AdaptedState[];
+  transitions: AdaptedTransition[];
+  initialState?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter implementation
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_IR_VERSIONS = new Set<string>(["1.0"]);
+
+/**
+ * Convert an IR state declaration into the runtime/storage state shape.
+ * Strips IR-only fields (metadata, provenance, elementIds,
+ * incomingTransitions, crossRefs, visualRefs).
+ */
+export function adaptIRState(state: IRState): AdaptedState {
+  const out: AdaptedState = {
+    id: state.id,
+    name: state.name,
+    requiredElements: state.requiredElements,
+  };
+  if (state.description !== undefined) out.description = state.description;
+  if (state.excludedElements !== undefined) out.excludedElements = state.excludedElements;
+  if (state.conditions !== undefined) out.conditions = state.conditions;
+  if (state.isInitial !== undefined) out.isInitial = state.isInitial;
+  if (state.isTerminal !== undefined) out.isTerminal = state.isTerminal;
+  if (state.blocking !== undefined) out.blocking = state.blocking;
+  if (state.group !== undefined) out.group = state.group;
+  if (state.pathCost !== undefined) out.pathCost = state.pathCost;
+  return out;
+}
+
+/**
+ * Wait types the runtime engine accepts. IR-authored waits with other types
+ * (e.g., `state`, `condition`) are dropped from the adapter output.
+ */
+const RUNTIME_WAIT_TYPES = new Set<AdaptedWaitAfter["type"]>([
+  "idle",
+  "element",
+  "time",
+  "vanish",
+  "change",
+  "stable",
+]);
+
+function adaptIRWaitAfter(wait: IRWaitSpec): AdaptedWaitAfter | undefined {
+  if (!RUNTIME_WAIT_TYPES.has(wait.type as AdaptedWaitAfter["type"])) {
+    // IR-authored wait is richer than runtime supports — drop it.
+    // Runtime defaults (default idle behaviour) take over.
+    return undefined;
+  }
+  const out: AdaptedWaitAfter = { type: wait.type as AdaptedWaitAfter["type"] };
+  if (wait.query !== undefined) out.query = wait.query;
+  if (wait.ms !== undefined) out.ms = wait.ms;
+  if (wait.timeout !== undefined) out.timeout = wait.timeout;
+  return out;
+}
+
+/**
+ * Convert an IR transition action into the runtime action shape.
+ * Renames IR's `type` to runtime's `action`; narrows `waitAfter` to the
+ * runtime-accepted subset.
+ */
+export function adaptIRTransitionAction(action: IRTransitionAction): AdaptedTransitionAction {
+  const out: AdaptedTransitionAction = {
+    action: action.type,
+    target: action.target,
+  };
+  if (action.params !== undefined) out.params = action.params;
+  if (action.waitAfter !== undefined) {
+    const adaptedWait = adaptIRWaitAfter(action.waitAfter);
+    if (adaptedWait !== undefined) out.waitAfter = adaptedWait;
+  }
+  return out;
+}
+
+/**
+ * Convert an IR transition declaration into the runtime/storage transition
+ * shape. Strips IR-only fields (effect, metadata, provenance, crossRefs)
+ * and defaults `exitStates` to `[]` when omitted.
+ */
+export function adaptIRTransition(transition: IRTransition): AdaptedTransition {
+  const out: AdaptedTransition = {
+    id: transition.id,
+    name: transition.name,
+    fromStates: transition.fromStates,
+    activateStates: transition.activateStates,
+    exitStates: transition.exitStates ?? [],
+    actions: transition.actions.map(adaptIRTransitionAction),
+  };
+  if (transition.description !== undefined) out.description = transition.description;
+  if (transition.pathCost !== undefined) out.pathCost = transition.pathCost;
+  if (transition.bidirectional !== undefined) out.bidirectional = transition.bidirectional;
+  return out;
+}
+
+/**
+ * Convert a top-level IR document into the runtime `WorkflowConfig` shape.
+ *
+ * Throws on unknown IR versions to fail loudly rather than silently emit
+ * stale shapes.
+ */
+export function adaptIRDocumentToWorkflowConfig(doc: IRDocument): AdaptedWorkflowConfig {
+  if (!SUPPORTED_IR_VERSIONS.has(doc.version)) {
+    throw new Error(
+      `adaptIRDocumentToWorkflowConfig: unsupported IR version "${doc.version}". ` +
+        `Supported: ${Array.from(SUPPORTED_IR_VERSIONS).join(", ")}`,
+    );
+  }
+
+  const out: AdaptedWorkflowConfig = {
+    id: doc.id,
+    name: doc.name,
+    states: doc.states.map(adaptIRState),
+    transitions: doc.transitions.map(adaptIRTransition),
+  };
+  if (doc.description !== undefined) out.description = doc.description;
+  if (doc.initialState !== undefined) out.initialState = doc.initialState;
+  return out;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Top-level IR document.
+ *
+ * Versioned (`'1.0'`) container for the states + transitions that describe
+ * a page or scope of an application. Build plugins emit this shape; the
+ * adapter folds it into ui-bridge-auto's `WorkflowConfig`.
+ */
+
+import type { IRMetadata, IRProvenance } from "./primitives";
+import type { IRState } from "./state";
+import type { IRTransition } from "./transition";
+
+/**
+ * IR schema version. Bump when the shape changes in a backwards-incompatible
+ * way. The adapter rejects documents whose version it does not understand.
+ */
+export type IRVersion = "1.0";
+
+/**
+ * Top-level IR document.
+ */
+export interface IRDocument {
+  /** Schema version. */
+  version: IRVersion;
+  /** Stable document identifier (typically the page or scope name). */
+  id: string;
+  /** Human-readable document name. */
+  name: string;
+  /** Optional description of what this document covers. */
+  description?: string;
+  /** Document-level semantic metadata. */
+  metadata?: IRMetadata;
+  /** Where this document came from. */
+  provenance?: IRProvenance;
+
+  /** State declarations within this document. */
+  states: IRState[];
+  /** Transition declarations within this document. */
+  transitions: IRTransition[];
+
+  /** ID of the initial/starting state, if applicable. */
+  initialState?: string;
+}

package/src/ui-bridge-ir/element-criteria.ts

@@ -0,0 +1,48 @@
+/**
+ * IR's canonical element-matching shape.
+ *
+ * Per decision #7 (SESSION_PROMPTS.md): IR adopts ui-bridge-auto's
+ * `ElementCriteria` as the canonical authoring shape — criteria survive ID
+ * drift and are descriptive rather than identity-based. The shape mirrors
+ * ui-bridge-auto/src/types/match.ts:20 exactly so the IR -> WorkflowConfig
+ * adapter is structurally identity (no rewriting at the criteria level).
+ *
+ * `elementIds: string[]` is an OPTIONAL companion the runtime SDK fills in at
+ * registration time when criteria resolve to specific registered elements.
+ * Authors write criteria; the runtime caches resolutions.
+ */
+
+/**
+ * Minimal criteria to identify a DOM element.
+ *
+ * Mirrors `ElementCriteria` from `ui-bridge-auto/src/types/match.ts:20`.
+ * Kept as a separate copy here (not re-exported) so the IR module has no
+ * runtime dependency on ui-bridge-auto. The adapter is the single point of
+ * type-level reconciliation.
+ */
+export interface IRElementCriteria {
+  /** ARIA role or inferred role. */
+  role?: string;
+  /** HTML tag name (e.g. "div", "button"). Heavily used in legacy specs. */
+  tagName?: string;
+  /** Exact text content (trimmed). */
+  text?: string;
+  /** Substring match on text content (case-insensitive). */
+  textContains?: string;
+  /**
+   * ARIA label (case-insensitive substring match). Synonym of `accessibleName`
+   * for the runtime SDK; the projection prefers `accessibleName` when both are
+   * present.
+   */
+  ariaLabel?: string;
+  /**
+   * Computed accessible name (the same concept legacy specs serialize as
+   * `accessibleName`). Added section 3 so the inverse projection can
+   * round-trip without rewriting to `ariaLabel`.
+   */
+  accessibleName?: string;
+  /** Element ID (exact string or pattern-source string). */
+  id?: string;
+  /** HTML attributes to check (exact string match). */
+  attributes?: Record<string, string>;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @qontinui/shared-types/ui-bridge-ir
+ *
+ * Authoring-time intermediate representation for the UI Bridge redesign.
+ * Build plugins (Vite, Next.js, Metro) emit `IRDocument` instances; the
+ * adapter (`adaptIRToWorkflowConfig`) folds them into ui-bridge-auto's
+ * runtime shape.
+ *
+ * Boundary with `@qontinui/shared-types/state-machine` (per ADR-001 /
+ * decision #6): `state-machine` houses snake_case Rust-generated wire types
+ * for the runtime/db. `ui-bridge-ir` is camelCase, authoring-time, and
+ * carries IR-only fields (provenance, metadata, effect, crossRefs,
+ * visualRefs). The adapter is the single point of translation between the
+ * two namespaces.
+ */
+
+export * from "./primitives";
+export * from "./element-criteria";
+export * from "./state";
+export * from "./transition";
+export * from "./document";
+export * from "./adapter";
+export * from "./projection";

package/src/ui-bridge-ir/ir.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qontinui.io/schemas/ui-bridge-ir/1.0/ir.schema.json",
+  "title": "UI Bridge IR Document",
+  "description": "Authoring-time intermediate representation for the UI Bridge redesign. Build plugins emit instances of this shape; the IR -> WorkflowConfig adapter folds them into ui-bridge-auto's runtime shape.",
+  "type": "object",
+  "required": ["version", "id", "name", "states", "transitions"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["1.0"]
+    },
+    "id": { "type": "string" },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "metadata": { "$ref": "#/$defs/IRMetadata" },
+    "provenance": { "$ref": "#/$defs/IRProvenance" },
+    "initialState": { "type": "string" },
+    "states": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/IRState" }
+    },
+    "transitions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/IRTransition" }
+    }
+  },
+  "$defs": {
+    "IRElementCriteria": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "role": { "type": "string" },
+        "tagName": { "type": "string" },
+        "text": { "type": "string" },
+        "textContains": { "type": "string" },
+        "ariaLabel": { "type": "string" },
+        "accessibleName": { "type": "string" },
+        "id": { "type": "string" },
+        "attributes": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "IRMetadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string" },
+        "purpose": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "relatedElements": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "string" }
+      }
+    },
+    "IRProvenance": {
+      "type": "object",
+      "required": ["source"],
+      "additionalProperties": false,
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["hand-authored", "build-plugin", "ai-generated", "migrated"]
+        },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 },
+        "pluginVersion": { "type": "string" }
+      }
+    },
+    "IRCrossRef": {
+      "type": "object",
+      "required": ["doc", "ref"],
+      "additionalProperties": false,
+      "properties": {
+        "doc": { "type": "string" },
+        "ref": { "type": "string" }
+      }
+    },
+    "IRVisualRef": {
+      "type": "object",
+      "required": ["asset"],
+      "additionalProperties": false,
+      "properties": {
+        "asset": { "type": "string" },
+        "region": {
+          "type": "object",
+          "required": ["x", "y", "width", "height"],
+          "additionalProperties": false,
+          "properties": {
+            "x": { "type": "number" },
+            "y": { "type": "number" },
+            "width": { "type": "number" },
+            "height": { "type": "number" }
+          }
+        },
+        "capturedAt": { "type": "integer" }
+      }
+    },
+    "IRStateCondition": {
+      "type": "object",
+      "required": ["element", "property", "expected"],
+      "additionalProperties": false,
+      "properties": {
+        "element": { "$ref": "#/$defs/IRElementCriteria" },
+        "property": {
+          "type": "string",
+          "enum": ["visible", "enabled", "checked", "expanded", "selected", "text", "value"]
+        },
+        "expected": {},
+        "comparator": {
+          "type": "string",
+          "enum": ["equals", "contains", "matches", "greaterThan", "lessThan"]
+        }
+      }
+    },
+    "IRState": {
+      "type": "object",
+      "required": ["id", "name", "requiredElements"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "requiredElements": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/IRElementCriteria" }
+        },
+        "excludedElements": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/IRElementCriteria" }
+        },
+        "conditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/IRStateCondition" }
+        },
+        "isInitial": { "type": "boolean" },
+        "isTerminal": { "type": "boolean" },
+        "blocking": { "type": "boolean" },
+        "group": { "type": "string" },
+        "pathCost": { "type": "number" },
+        "precondition": { "type": "string" },
+        "elementIds": { "type": "array", "items": { "type": "string" } },
+        "incomingTransitions": { "type": "array", "items": { "type": "string" } },
+        "metadata": { "$ref": "#/$defs/IRMetadata" },
+        "provenance": { "$ref": "#/$defs/IRProvenance" },
+        "crossRefs": { "type": "array", "items": { "$ref": "#/$defs/IRCrossRef" } },
+        "visualRefs": { "type": "array", "items": { "$ref": "#/$defs/IRVisualRef" } }
+      }
+    },
+    "IRWaitSpec": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["idle", "element", "state", "time", "condition", "vanish", "change", "stable"]
+        },
+        "query": { "$ref": "#/$defs/IRElementCriteria" },
+        "stateId": { "type": "string" },
+        "ms": { "type": "number" },
+        "timeout": { "type": "number" },
+        "property": { "type": "string" },
+        "quietPeriodMs": { "type": "number" }
+      }
+    },
+    "IRTransitionAction": {
+      "type": "object",
+      "required": ["type", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string" },
+        "target": { "$ref": "#/$defs/IRElementCriteria" },
+        "params": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "waitAfter": { "$ref": "#/$defs/IRWaitSpec" }
+      }
+    },
+    "IRTransition": {
+      "type": "object",
+      "required": ["id", "name", "fromStates", "activateStates", "actions"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "fromStates": { "type": "array", "items": { "type": "string" } },
+        "activateStates": { "type": "array", "items": { "type": "string" } },
+        "exitStates": { "type": "array", "items": { "type": "string" } },
+        "actions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/IRTransitionAction" }
+        },
+        "pathCost": { "type": "number" },
+        "bidirectional": { "type": "boolean" },
+        "effect": {
+          "type": "string",
+          "enum": ["read", "write", "destructive"]
+        },
+        "metadata": { "$ref": "#/$defs/IRMetadata" },
+        "provenance": { "$ref": "#/$defs/IRProvenance" },
+        "crossRefs": { "type": "array", "items": { "$ref": "#/$defs/IRCrossRef" } }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Primitive IR shapes shared by states, transitions, and adapters.
+ *
+ * IR-only fields (provenance, metadata, effect) live here so that the runtime
+ * adapter can identify and strip them in one place.
+ *
+ * See ADR-001 (qontinui-dev-notes/ui-bridge-redesign/section-1-foundations/)
+ * for the rationale on each field.
+ */
+
+// ---------------------------------------------------------------------------
+// Provenance — where an IR declaration came from
+// ---------------------------------------------------------------------------
+
+/**
+ * Origin of an IR node. Set by the build plugin when extracting JSX wrappers,
+ * by hand when authoring a JSON IR file directly, or by a generation pipeline.
+ */
+export interface IRProvenance {
+  /** How this declaration was authored. */
+  source: "hand-authored" | "build-plugin" | "ai-generated" | "migrated";
+  /** Source file (relative to the build root). */
+  file?: string;
+  /** Line number in the source file (1-based). */
+  line?: number;
+  /** Column in the source file (1-based). */
+  column?: number;
+  /** Build-plugin version that produced this node, if applicable. */
+  pluginVersion?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Metadata — semantic context routed through the useUIAnnotation store at runtime
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-authored semantic context for an IR node. Aligns with the existing
+ * ElementAnnotation shape (ui-bridge/packages/ui-bridge/src/annotations/types.ts)
+ * so the runtime SDK can write straight into the global annotation store
+ * without parallel infrastructure.
+ */
+export interface IRMetadata {
+  /** Short human-readable description of what this state/transition represents. */
+  description?: string;
+  /** What this state/transition is for, intent-wise. */
+  purpose?: string;
+  /** Tags for grouping, filtering, and search. */
+  tags?: string[];
+  /** IDs of related elements/states/transitions. */
+  relatedElements?: string[];
+  /** Free-form notes for nuance that doesn't fit description/purpose. */
+  notes?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Effect — side-effect annotation on transitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether a transition is read-only, mutating, or destructive.
+ *
+ * - "read"        — query/navigate; no persistent state change.
+ * - "write"       — modifies persistent state but is reversible (or has an undo).
+ * - "destructive" — irreversible state change (delete, send, charge, deploy).
+ *
+ * Drives counterfactual analysis (section 6) and gates auto-regression
+ * generation (section 9) — destructive transitions are excluded from
+ * automatic walks.
+ */
+export type IREffect = "read" | "write" | "destructive";
+
+// ---------------------------------------------------------------------------
+// Cross-references between IR documents
+// ---------------------------------------------------------------------------
+
+/**
+ * Pointer from one IR document to a state/transition declared elsewhere.
+ * Used when a transition activates a state owned by another page's IR doc.
+ */
+export interface IRCrossRef {
+  /** Document ID containing the referenced node. */
+  doc: string;
+  /** ID of the referenced state or transition within that document. */
+  ref: string;
+}
+
+// ---------------------------------------------------------------------------
+// Visual references (placeholder for section 8)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pointer to a captured visual reference (screenshot region, design token).
+ * Optional companion data — populated by section 8's visual-fusion work.
+ */
+export interface IRVisualRef {
+  /** Path or content-addressable ID of the captured asset. */
+  asset: string;
+  /** Capture region in viewport coordinates, if applicable. */
+  region?: { x: number; y: number; width: number; height: number };
+  /** Capture timestamp (epoch ms). */
+  capturedAt?: number;
+}