@qontinui/shared-types 0.2.1

package/src/render-log.ts

@@ -0,0 +1,371 @@
+/**
+ * Shared Render Log Types
+ *
+ * These types define the render logging schema used across:
+ * - qontinui-runner (Tauri desktop app) - Component-level logging
+ * - qontinui-web (Next.js web app) - Full DOM snapshot logging
+ *
+ * The runner reads both its own logs and web's logs for verification
+ * in AI feedback loops.
+ *
+ * NOTE: Field names use snake_case to match Rust/Python JSON serialization.
+ * This ensures compatibility across all services.
+ */
+
+// =============================================================================
+// Common Types
+// =============================================================================
+
+/**
+ * Trigger types for render log capture.
+ * What caused the render log to be captured.
+ */
+export type RenderLogTrigger =
+  | "mount" // Component/page mounted
+  | "navigation" // Page navigation occurred
+  | "mutation" // DOM mutation detected (web only)
+  | "data_update" // Data changed (runner components)
+  | "prop_change" // Props changed (runner components)
+  | "manual" // Explicitly triggered capture
+  | "interval"; // Periodic capture
+
+/**
+ * DOM mutation types (for web's MutationObserver).
+ */
+export type DomMutationType = "childList" | "attributes" | "characterData";
+
+// =============================================================================
+// Base Render Log Entry
+// =============================================================================
+
+/**
+ * Base render log entry with common fields.
+ * Extended by component logs and DOM snapshot logs.
+ */
+export interface RenderLogEntryBase {
+  /** Unique identifier for this log entry */
+  id: string;
+
+  /** Unix timestamp in milliseconds when the capture occurred */
+  timestamp: number;
+
+  /** What triggered this capture */
+  trigger: RenderLogTrigger;
+
+  /** Session ID for grouping related captures */
+  session_id?: string;
+}
+
+// =============================================================================
+// Runner Component Render Log (Lightweight)
+// =============================================================================
+
+/**
+ * Component-level render log entry.
+ * Used by qontinui-runner to log what data components render.
+ *
+ * Components explicitly call logRender() with their rendered data.
+ * This is lightweight and focused on verifying data display.
+ */
+export interface ComponentRenderLogEntry extends RenderLogEntryBase {
+  /** Type discriminator */
+  type: "component";
+
+  /** Component name (e.g., "RunRecapTab", "StatusBanner") */
+  component: string;
+
+  /** The data that was rendered (component-specific structure) */
+  data: Record<string, unknown>;
+
+  /** Sections that are visible/expanded in the component */
+  visible_sections?: string[];
+
+  /** Associated task run ID if applicable */
+  task_run_id?: number;
+}
+
+// =============================================================================
+// Web DOM Snapshot Render Log (Comprehensive)
+// =============================================================================
+
+/**
+ * Bounding rectangle for an element.
+ */
+export interface ElementRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Single DOM element in a snapshot.
+ * Recursive structure representing the DOM tree.
+ */
+export interface DomElementSnapshot {
+  /** HTML tag name (lowercase) */
+  tag: string;
+
+  /** Element ID if present */
+  id?: string;
+
+  /** CSS class list */
+  class_list: string[];
+
+  /** Direct text content (not from children) */
+  text_content?: string;
+
+  /** Length of innerHTML (for size estimation) */
+  inner_html_length?: number;
+
+  /** Bounding rectangle relative to viewport */
+  rect?: ElementRect;
+
+  /** Whether the element is visible */
+  is_visible: boolean;
+
+  /** Computed opacity */
+  opacity?: number;
+
+  /** Computed display value */
+  display?: string;
+
+  /** Key HTML attributes */
+  attributes: Record<string, string>;
+
+  /** Selected computed styles */
+  computed_styles?: Record<string, string>;
+
+  /** Child elements (recursive) */
+  children: DomElementSnapshot[];
+}
+
+/**
+ * Form data extracted from the page.
+ */
+export interface FormSnapshot {
+  id?: string;
+  action?: string;
+  method?: string;
+  inputs: Array<{
+    type: string;
+    name: string;
+    value: string;
+  }>;
+}
+
+/**
+ * Link data extracted from the page.
+ */
+export interface LinkSnapshot {
+  href: string;
+  text: string;
+}
+
+/**
+ * Image data extracted from the page.
+ */
+export interface ImageSnapshot {
+  src: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * Full DOM snapshot data.
+ * Contains the entire page state for debugging.
+ *
+ * NOTE: The snapshot is stored as JSONB in the database, so field names
+ * in the nested structure (root, forms, links, images) may vary by
+ * implementation. The web frontend uses camelCase internally but that's
+ * stored as-is in the JSONB field.
+ */
+export interface DomSnapshot {
+  /** Root element tree (document.body) */
+  root: DomElementSnapshot | null;
+
+  /** Total number of elements in the tree */
+  total_elements: number;
+
+  /** Concatenated visible text (truncated) */
+  visible_text?: string;
+
+  /** Forms on the page */
+  forms: FormSnapshot[];
+
+  /** Links on the page */
+  links: LinkSnapshot[];
+
+  /** Images on the page */
+  images: ImageSnapshot[];
+
+  /** JavaScript console errors captured */
+  errors: string[];
+
+  /** JavaScript console warnings captured */
+  warnings: string[];
+}
+
+/**
+ * Full DOM snapshot render log entry.
+ * Used by qontinui-web to capture entire page state.
+ *
+ * Automatically captured via MutationObserver on DOM changes.
+ * Provides comprehensive debugging data.
+ */
+export interface DomSnapshotRenderLogEntry extends RenderLogEntryBase {
+  /** Type discriminator */
+  type: "dom_snapshot";
+
+  /** Current page URL */
+  page_url: string;
+
+  /** Page title */
+  page_title?: string;
+
+  /** Type of DOM mutation that triggered capture (if mutation trigger) */
+  mutation_type?: DomMutationType;
+
+  /** CSS selector of the element that was mutated */
+  target_selector?: string;
+
+  /** The full DOM snapshot */
+  snapshot: DomSnapshot;
+
+  /** Viewport dimensions */
+  viewport_width?: number;
+  viewport_height?: number;
+
+  /** Scroll position */
+  scroll_x?: number;
+  scroll_y?: number;
+
+  /** Time taken to capture the snapshot in milliseconds */
+  capture_duration_ms?: number;
+
+  /** Number of elements captured */
+  element_count?: number;
+
+  /** User ID if authenticated (web only) */
+  user_id?: string;
+}
+
+// =============================================================================
+// Union Type
+// =============================================================================
+
+/**
+ * Any render log entry.
+ * Use the `type` field to discriminate.
+ */
+export type RenderLogEntry =
+  | ComponentRenderLogEntry
+  | DomSnapshotRenderLogEntry;
+
+// =============================================================================
+// API Types (for REST endpoints)
+// =============================================================================
+
+/**
+ * Request to create a render log entry (web API).
+ */
+export interface CreateRenderLogRequest {
+  session_id: string;
+  page_url: string;
+  page_title?: string;
+  trigger: RenderLogTrigger;
+  mutation_type?: DomMutationType;
+  target_selector?: string;
+  snapshot: DomSnapshot;
+  viewport_width?: number;
+  viewport_height?: number;
+  scroll_x?: number;
+  scroll_y?: number;
+  capture_duration_ms?: number;
+  element_count?: number;
+}
+
+/**
+ * Render log response from web API.
+ * Includes database-generated fields.
+ */
+export interface RenderLogResponse {
+  id: number;
+  session_id: string;
+  timestamp: string; // ISO 8601 datetime
+  page_url: string;
+  page_title?: string;
+  trigger: RenderLogTrigger;
+  mutation_type?: DomMutationType;
+  target_selector?: string;
+  snapshot: DomSnapshot;
+  viewport_width?: number;
+  viewport_height?: number;
+  scroll_x?: number;
+  scroll_y?: number;
+  capture_duration_ms?: number;
+  element_count?: number;
+  user_id?: string;
+}
+
+/**
+ * Summary of a render log (without full snapshot).
+ */
+export interface RenderLogSummary {
+  id: number;
+  session_id: string;
+  timestamp: string;
+  page_url: string;
+  page_title?: string;
+  trigger: RenderLogTrigger;
+  mutation_type?: DomMutationType;
+  element_count?: number;
+  capture_duration_ms?: number;
+}
+
+/**
+ * Paginated list of render logs.
+ */
+export interface RenderLogList {
+  items: RenderLogSummary[];
+  total: number;
+  page: number;
+  page_size: number;
+  has_more: boolean;
+}
+
+/**
+ * Render logging statistics.
+ */
+export interface RenderLogStats {
+  enabled: boolean;
+  total_snapshots: number;
+  total_sessions: number;
+  oldest_snapshot?: string;
+  newest_snapshot?: string;
+  storage_used_bytes: number;
+  image_count: number;
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Check if a render log entry is a component log.
+ */
+export function isComponentRenderLog(
+  entry: RenderLogEntry,
+): entry is ComponentRenderLogEntry {
+  return entry.type === "component";
+}
+
+/**
+ * Check if a render log entry is a DOM snapshot log.
+ */
+export function isDomSnapshotRenderLog(
+  entry: RenderLogEntry,
+): entry is DomSnapshotRenderLogEntry {
+  return entry.type === "dom_snapshot";
+}

package/src/runner/_api.ts

@@ -0,0 +1,14 @@
+/**
+ * Runner Types
+ *
+ * Canonical wire-format types for a registered runner. One row per registered
+ * runner; the same shape is served to every consumer (mobile, web, runner UI).
+ *
+ * Types generated from Rust (source of truth:
+ * `qontinui-schemas/rust/src/runner.rs`). Do not edit by hand — regenerate via
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+export type { Runner } from "../generated/Runner";
+export type { RunnerStatus } from "../generated/RunnerStatus";
+export type { RunnerUiError } from "../generated/RunnerUiError";
+export type { RunnerCrash } from "../generated/RunnerCrash";

package/src/runner/index.ts

@@ -0,0 +1 @@
+export * from "./_api";

package/src/scheduler/_api.ts

@@ -0,0 +1,21 @@
+// Types generated from Rust (source of truth: qontinui-schemas/rust/src/scheduler.rs).
+// Do not edit by hand — regenerate via `just generate-types` (or
+// `qontinui-runner/src-tauri/scripts/generate_types.sh`).
+export type { ScheduleExpression } from "../generated/ScheduleExpression";
+export type { ConditionScheduleConfig } from "../generated/ConditionScheduleConfig";
+export type { ScheduleConditions } from "../generated/ScheduleConditions";
+export type { IdleCondition } from "../generated/IdleCondition";
+export type { RepositoryInactiveCondition } from "../generated/RepositoryInactiveCondition";
+export type { RepositoryWatch } from "../generated/RepositoryWatch";
+export type { ConditionStatus } from "../generated/ConditionStatus";
+export type { ScheduledTask } from "../generated/ScheduledTask";
+export type { ScheduledTaskType } from "../generated/ScheduledTaskType";
+export type { ScheduledTaskStatus } from "../generated/ScheduledTaskStatus";
+export type { TaskExecutionRecord } from "../generated/TaskExecutionRecord";
+export type { SchedulerSettings } from "../generated/SchedulerSettings";
+export type { SchedulerStatus } from "../generated/SchedulerStatus";
+export type { NextTaskInfo } from "../generated/NextTaskInfo";
+export type { CreateScheduledTaskRequest } from "../generated/CreateScheduledTaskRequest";
+export type { UpdateScheduledTaskRequest } from "../generated/UpdateScheduledTaskRequest";
+export type { CatchUpPolicy } from "../generated/CatchUpPolicy";
+export type { McpConnectionRef } from "../generated/McpConnectionRef";

package/src/scheduler/index.ts

@@ -0,0 +1 @@
+export * from "./_api";

package/src/state-machine/_api.ts

@@ -0,0 +1,145 @@
+/**
+ * Unified State Machine types for the Qontinui ecosystem.
+ *
+ * These types are the single source of truth for state machine data structures
+ * used by both qontinui-web and qontinui-runner. They use snake_case to match
+ * the API/database layer.
+ *
+ * Architecture:
+ * - Config: A named state machine configuration (collection of states + transitions)
+ * - State: A UI state defined by which elements are present
+ * - Transition: A named action sequence that moves between states
+ * - Action: A single UI interaction (click, type, navigate, etc.)
+ *
+ * Runtime navigation (pathfinding through states) is handled by the qontinui
+ * Python library using multistate. The TypeScript pathfinding types here are
+ * for the graph editor's path preview only.
+ *
+ * Most wire types in this module are generated from Rust (source of truth:
+ * qontinui-schemas/rust/src/state_machine.rs). Do not edit those by hand —
+ * regenerate via `just generate-types` (or the runner's generate_types.sh).
+ * A small number of UI-only sugar types remain hand-authored below.
+ */
+
+// =============================================================================
+// Action Types
+// =============================================================================
+
+export type { StandardActionType } from "../generated/StandardActionType";
+export type { Point } from "../generated/Point";
+export type { ScrollDirection } from "../generated/ScrollDirection";
+export type { MouseButton } from "../generated/MouseButton";
+export type { TransitionActionValue } from "../generated/TransitionActionValue";
+export type { TransitionAction } from "../generated/TransitionAction";
+
+// =============================================================================
+// Domain Knowledge
+// =============================================================================
+
+export type { DomainKnowledge } from "../generated/DomainKnowledge";
+
+// =============================================================================
+// State Machine Config
+// =============================================================================
+
+export type { StateMachineConfig } from "../generated/StateMachineConfig";
+export type { StateMachineConfigCreate } from "../generated/StateMachineConfigCreate";
+export type { StateMachineConfigUpdate } from "../generated/StateMachineConfigUpdate";
+export type { StateMachineConfigFull } from "../generated/StateMachineConfigFull";
+
+// =============================================================================
+// State
+// =============================================================================
+
+export type { StateMachineState } from "../generated/StateMachineState";
+export type { StateMachineStateCreate } from "../generated/StateMachineStateCreate";
+export type { StateMachineStateUpdate } from "../generated/StateMachineStateUpdate";
+
+// =============================================================================
+// Transition
+// =============================================================================
+
+export type { StateMachineTransition } from "../generated/StateMachineTransition";
+export type { StateMachineTransitionCreate } from "../generated/StateMachineTransitionCreate";
+export type { StateMachineTransitionUpdate } from "../generated/StateMachineTransitionUpdate";
+
+// =============================================================================
+// Pathfinding (Graph Editor Visualization)
+// =============================================================================
+
+/**
+ * These pathfinding types are for the graph editor's path preview feature.
+ * Runtime navigation uses the qontinui Python library (multistate) directly.
+ */
+
+export type { PathfindingRequest } from "../generated/PathfindingRequest";
+export type { PathfindingStep } from "../generated/PathfindingStep";
+export type { PathfindingResult } from "../generated/PathfindingResult";
+
+// =============================================================================
+// Execution Results (Runtime)
+// =============================================================================
+
+export type { TransitionExecutionResult } from "../generated/TransitionExecutionResult";
+export type { NavigationResult } from "../generated/NavigationResult";
+export type { ActiveStatesResult } from "../generated/ActiveStatesResult";
+
+export type { TransitionInfo } from "../generated/TransitionInfo";
+export type { AvailableTransitionsResult } from "../generated/AvailableTransitionsResult";
+
+// =============================================================================
+// Initial States
+// =============================================================================
+
+export type { InitialStatesSource } from "../generated/InitialStatesSource";
+export type { InitialStateRef } from "../generated/InitialStateRef";
+export type { ResolvedInitialStates } from "../generated/ResolvedInitialStates";
+export type { ResolvedInitialStatesResult } from "../generated/ResolvedInitialStatesResult";
+
+// =============================================================================
+// Discovery
+// =============================================================================
+
+export type { DiscoveryStrategy } from "../generated/DiscoveryStrategy";
+
+// =============================================================================
+// Graph Display Types (ReactFlow)
+// =============================================================================
+
+// NOTE: `StateNodeData` is kept hand-authored because the generated DTO
+// intentionally omits the `onStartElementDrag` callback (a UI-layer concern
+// with no Rust analogue). Downstream ReactFlow nodes need the callback, so we
+// can't silently substitute the generated shape. The rest of the fields match
+// the generated `StateNodeData` one-for-one.
+
+/**
+ * Data passed to a state node in the ReactFlow graph editor.
+ *
+ * UI-only sugar: mirrors the generated `StateNodeData` but adds the
+ * `onStartElementDrag` callback that the graph editor wires up at render time.
+ */
+export interface StateNodeData {
+  stateId: string;
+  name: string;
+  elementCount: number;
+  confidence: number;
+  elementIds: string[];
+  description: string | null;
+  isBlocking: boolean;
+  isSelected: boolean;
+  isInitial: boolean;
+  outgoingCount?: number;
+  incomingCount?: number;
+  isDropTarget?: boolean;
+  onStartElementDrag?: (stateId: string, elementId: string) => void;
+  /** Optional map of element ID → base64 thumbnail image (data URL or raw base64 PNG). */
+  elementThumbnails?: Record<string, string>;
+}
+
+export type { TransitionEdgeData } from "../generated/TransitionEdgeData";
+
+// =============================================================================
+// Export/Import
+// =============================================================================
+
+export type { StateMachineExportFormat } from "../generated/StateMachineExportFormat";

package/src/state-machine/index.ts

@@ -0,0 +1 @@
+export * from "./_api";

package/src/targets/_api.ts

@@ -0,0 +1,47 @@
+/**
+ * Target Configuration Types
+ *
+ * Discriminated union of 14 action-target variants (image, region, text,
+ * coordinates, stateImage, stateRegion, stateLocation, stateString,
+ * currentPosition, lastFindResult, resultIndex, allResults, resultByImage,
+ * accessibility) + supporting search/pattern/OCR options.
+ *
+ * Source of truth: qontinui-schemas/rust/src/targets.rs.
+ *
+ * Wire format: `type` discriminator uses camelCase ("stateImage",
+ * "currentPosition", "resultByImage", etc.).
+ */
+
+import type { TargetConfig } from "../generated/TargetConfig";
+
+export type { TargetConfig } from "../generated/TargetConfig";
+export type { SearchStrategy } from "../generated/SearchStrategy";
+export type { MatchMethod } from "../generated/MatchMethod";
+export type { PollingConfig } from "../generated/PollingConfig";
+export type { PatternOptions } from "../generated/PatternOptions";
+export type { MatchAdjustment } from "../generated/MatchAdjustment";
+export type { SearchOptions } from "../generated/SearchOptions";
+export type { OcrEngine } from "../generated/OcrEngine";
+export type { TextMatchType } from "../generated/TextMatchType";
+export type { TextSearchOptions } from "../generated/TextSearchOptions";
+
+// Per-variant narrowed aliases for consumers that want to Omit/Extend a
+// single target shape. `TargetConfig` itself is the discriminated union;
+// each alias is `TargetConfig` narrowed on the `type` discriminator.
+export type ImageTarget = Extract<TargetConfig, { type: "image" }>;
+export type RegionTarget = Extract<TargetConfig, { type: "region" }>;
+export type TextTarget = Extract<TargetConfig, { type: "text" }>;
+export type CoordinatesTarget = Extract<TargetConfig, { type: "coordinates" }>;
+export type StateStringTarget = Extract<TargetConfig, { type: "stateString" }>;
+export type StateRegionTarget = Extract<TargetConfig, { type: "stateRegion" }>;
+export type StateLocationTarget = Extract<TargetConfig, { type: "stateLocation" }>;
+export type StateImageTarget = Extract<TargetConfig, { type: "stateImage" }>;
+export type CurrentPositionTarget = Extract<TargetConfig, { type: "currentPosition" }>;
+export type LastFindResultTarget = Extract<TargetConfig, { type: "lastFindResult" }>;
+export type ResultIndexTarget = Extract<TargetConfig, { type: "resultIndex" }>;
+export type AllResultsTarget = Extract<TargetConfig, { type: "allResults" }>;
+export type ResultByImageTarget = Extract<TargetConfig, { type: "resultByImage" }>;
+export type AccessibilityTarget = Extract<TargetConfig, { type: "accessibility" }>;
+
+/** Wire-format type discriminator string for `TargetConfig`. */
+export type TargetType = TargetConfig["type"];

package/src/targets/index.ts

@@ -0,0 +1 @@
+export * from "./_api";