@qontinui/shared-types 0.2.1

package/README.md

@@ -0,0 +1,128 @@
+# @qontinui/shared-types
+
+Shared TypeScript types for the Qontinui ecosystem.
+
+## Overview
+
+This package provides TypeScript type definitions shared across:
+- **qontinui-runner** - Tauri desktop app
+- **qontinui-web** - Next.js web app
+
+## Installation
+
+```bash
+# From npm
+npm install @qontinui/shared-types
+```
+
+## Releasing
+
+The package is published to npm by a tag-triggered GitHub Actions workflow
+(`.github/workflows/publish.yml`). Tags use the `ts-v*` prefix so the
+workflow only fires for TypeScript-package releases (this repo also hosts
+the Rust `qontinui-types` crate, which may eventually have its own tag
+scheme).
+
+```bash
+# 1. Bump the version in ts/package.json
+# 2. Commit the version bump
+# 3. Tag and push
+git tag ts-v0.2.2
+git push --tags
+```
+
+The workflow runs `npm ci && npm run build && npm publish --access public`
+from the `ts/` directory using the org-level `NPM_TOKEN` secret.
+
+## Local development (hot-reload via npm link)
+
+To work on `@qontinui/shared-types` and have a consumer pick up changes
+without publishing, use `npm link`:
+
+```bash
+# In this package
+cd qontinui-schemas/ts
+npm install
+npm run build
+npm link
+
+# In the consuming project (e.g. qontinui-runner, qontinui-web/frontend)
+npm link @qontinui/shared-types
+```
+
+To unlink when finished:
+
+```bash
+# In the consumer
+npm unlink --no-save @qontinui/shared-types
+npm install
+
+# In this package (optional, removes the global symlink)
+cd qontinui-schemas/ts
+npm unlink
+```
+
+## Usage
+
+```typescript
+import {
+  RenderLogEntry,
+  ComponentRenderLogEntry,
+  DomSnapshotRenderLogEntry,
+  isComponentRenderLog,
+  isDomSnapshotRenderLog,
+} from "@qontinui/shared-types";
+
+// Type guard usage
+function processRenderLog(entry: RenderLogEntry) {
+  if (isComponentRenderLog(entry)) {
+    console.log("Component:", entry.component);
+    console.log("Data:", entry.data);
+  } else if (isDomSnapshotRenderLog(entry)) {
+    console.log("Page:", entry.page_url);
+    console.log("Elements:", entry.element_count);
+  }
+}
+```
+
+## Types
+
+### Render Logging
+
+Types for the render logging system used for AI-assisted debugging:
+
+- **`ComponentRenderLogEntry`** - Runner's component-level logging
+- **`DomSnapshotRenderLogEntry`** - Web's full DOM snapshot logging
+- **`RenderLogEntry`** - Union type for both
+- **`CreateRenderLogRequest`** - API request type
+- **`RenderLogResponse`** - API response type
+- **`RenderLogStats`** - Statistics about render logs
+
+### Naming Convention
+
+Field names use **camelCase**. All public Rust structs are annotated with
+`#[serde(rename_all = "camelCase")]` and `#[serde(deny_unknown_fields)]`, so
+the generated TypeScript interfaces are closed (no `[k: string]: unknown`
+fallback) and expect camelCase keys at construction time.
+
+See [CONTRACT.md](./CONTRACT.md) for the full wire-format contract, the
+reasoning, and the migration guide for consumer code.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run watch
+```
+
+## Related
+
+- [qontinui-schemas](../) - Python schemas (same repo)
+- [qontinui-runner](../../qontinui-runner) - Desktop app
+- [qontinui-web](../../qontinui-web) - Web app

package/dist/Region.d-BbpFAWF4.d.cts

@@ -0,0 +1,88 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Coordinate system identifier. Always specify which system you are working
+ * with to avoid confusion in multi-monitor setups.
+ */
+type CoordinateSystem = "screen" | "virtual" | "monitor_relative";
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * X,Y coordinates with optional coordinate system specification.
+ *
+ * Coordinates without an explicit `system` default to
+ * [`CoordinateSystem::Screen`] for backward compatibility.
+ */
+interface Coordinates {
+  /**
+   * Monitor index (required when `system` is `MonitorRelative`).
+   */
+  monitorIndex?: number | null;
+  /**
+   * Coordinate system. `None` defaults to `Screen`.
+   */
+  system?: CoordinateSystem | null;
+  /**
+   * X coordinate (horizontal position).
+   */
+  x: number;
+  /**
+   * Y coordinate (vertical position).
+   */
+  y: number;
+}
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * Rectangular region on screen. Like [`Coordinates`], can optionally specify
+ * which coordinate system the `x`/`y` are in.
+ */
+interface Region {
+  /**
+   * Height of the region (must be positive).
+   */
+  height: number;
+  /**
+   * Monitor index (required when `system` is `MonitorRelative`).
+   */
+  monitorIndex?: number | null;
+  /**
+   * Coordinate system. `None` defaults to `Screen`.
+   */
+  system?: CoordinateSystem | null;
+  /**
+   * Width of the region (must be positive).
+   */
+  width: number;
+  /**
+   * X coordinate of the top-left corner.
+   */
+  x: number;
+  /**
+   * Y coordinate of the top-left corner.
+   */
+  y: number;
+}
+
+export type { Coordinates as C, Region as R, CoordinateSystem as a };

package/dist/Region.d-BbpFAWF4.d.ts

@@ -0,0 +1,88 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Coordinate system identifier. Always specify which system you are working
+ * with to avoid confusion in multi-monitor setups.
+ */
+type CoordinateSystem = "screen" | "virtual" | "monitor_relative";
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * X,Y coordinates with optional coordinate system specification.
+ *
+ * Coordinates without an explicit `system` default to
+ * [`CoordinateSystem::Screen`] for backward compatibility.
+ */
+interface Coordinates {
+  /**
+   * Monitor index (required when `system` is `MonitorRelative`).
+   */
+  monitorIndex?: number | null;
+  /**
+   * Coordinate system. `None` defaults to `Screen`.
+   */
+  system?: CoordinateSystem | null;
+  /**
+   * X coordinate (horizontal position).
+   */
+  x: number;
+  /**
+   * Y coordinate (vertical position).
+   */
+  y: number;
+}
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * Rectangular region on screen. Like [`Coordinates`], can optionally specify
+ * which coordinate system the `x`/`y` are in.
+ */
+interface Region {
+  /**
+   * Height of the region (must be positive).
+   */
+  height: number;
+  /**
+   * Monitor index (required when `system` is `MonitorRelative`).
+   */
+  monitorIndex?: number | null;
+  /**
+   * Coordinate system. `None` defaults to `Screen`.
+   */
+  system?: CoordinateSystem | null;
+  /**
+   * Width of the region (must be positive).
+   */
+  width: number;
+  /**
+   * X coordinate of the top-left corner.
+   */
+  x: number;
+  /**
+   * Y coordinate of the top-left corner.
+   */
+  y: number;
+}
+
+export type { Coordinates as C, Region as R, CoordinateSystem as a };

package/dist/accessibility.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/accessibility/index.ts
+var accessibility_exports = {};
+module.exports = __toCommonJS(accessibility_exports);
+//# sourceMappingURL=accessibility.cjs.map

package/dist/accessibility.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/accessibility/index.ts"],"sourcesContent":["export * from \"./_api\";\r\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/accessibility.d.cts

@@ -0,0 +1,396 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * ARIA/UIA accessibility roles. Based on WAI-ARIA 1.2 with extensions for
+ * Windows UI Automation and other platform-specific accessibility APIs.
+ */
+type AccessibilityRole =
+  | "application"
+  | "document"
+  | "article"
+  | "banner"
+  | "complementary"
+  | "contentinfo"
+  | "form"
+  | "main"
+  | "navigation"
+  | "region"
+  | "search"
+  | "button"
+  | "checkbox"
+  | "combobox"
+  | "dialog"
+  | "gridcell"
+  | "link"
+  | "listbox"
+  | "menu"
+  | "menubar"
+  | "menuitem"
+  | "menuitemcheckbox"
+  | "menuitemradio"
+  | "option"
+  | "progressbar"
+  | "radio"
+  | "radiogroup"
+  | "scrollbar"
+  | "searchbox"
+  | "slider"
+  | "spinbutton"
+  | "switch"
+  | "tab"
+  | "tablist"
+  | "tabpanel"
+  | "textbox"
+  | "toolbar"
+  | "tooltip"
+  | "tree"
+  | "treegrid"
+  | "treeitem"
+  | "alert"
+  | "alertdialog"
+  | "grid"
+  | "heading"
+  | "img"
+  | "list"
+  | "listitem"
+  | "log"
+  | "marquee"
+  | "math"
+  | "note"
+  | "separator"
+  | "status"
+  | "table"
+  | "cell"
+  | "columnheader"
+  | "row"
+  | "rowgroup"
+  | "rowheader"
+  | "timer"
+  | "definition"
+  | "directory"
+  | "figure"
+  | "group"
+  | "paragraph"
+  | "term"
+  | "generic"
+  | "static_text"
+  | "none"
+  | "unknown"
+  | "window"
+  | "pane"
+  | "titlebar"
+  | "edit"
+  | "custom"
+  | "dataitem"
+  | "datepicker"
+  | "calendar"
+  | "hyperlink"
+  | "splitbutton";
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Accessibility capture backend. Each variant corresponds to a platform
+ * accessibility API implementation.
+ */
+type AccessibilityBackend = "auto" | "cdp" | "uia" | "atspi" | "ax" | "none";
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Accessibility state flags for a node.
+ *
+ * These flags represent the current interactive state of an element.
+ * Tri-state booleans use `Option<bool>` — `None` means "not applicable."
+ */
+interface AccessibilityState {
+  /**
+   * Checkable element's checked state.
+   */
+  isChecked?: boolean | null;
+  /**
+   * Element is disabled / non-interactive.
+   */
+  isDisabled: boolean;
+  /**
+   * Element content can be edited.
+   */
+  isEditable: boolean;
+  /**
+   * Expandable element's expansion state.
+   */
+  isExpanded?: boolean | null;
+  /**
+   * Element can receive focus.
+   */
+  isFocusable: boolean;
+  /**
+   * Element has keyboard focus.
+   */
+  isFocused: boolean;
+  /**
+   * Element is hidden from the accessibility tree.
+   */
+  isHidden: boolean;
+  /**
+   * Element is a modal dialog.
+   */
+  isModal: boolean;
+  /**
+   * Element allows multiple selections.
+   */
+  isMultiselectable: boolean;
+  /**
+   * Pressable element's pressed state.
+   */
+  isPressed?: boolean | null;
+  /**
+   * Element is read-only.
+   */
+  isReadonly: boolean;
+  /**
+   * Element value is required.
+   */
+  isRequired: boolean;
+  /**
+   * Selectable element's selection state.
+   */
+  isSelected?: boolean | null;
+}
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * Bounding rectangle for an accessibility node. Coordinates are screen
+ * pixels, typically absolute screen coordinates.
+ */
+interface AccessibilityBounds {
+  height: number;
+  width: number;
+  x: number;
+  y: number;
+}
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * A node in the accessibility tree.
+ *
+ * Each node represents an element in the accessibility hierarchy with its
+ * role, name, value, state, and bounds. The `ref` field provides a stable
+ * identifier for AI-driven automation (e.g., `@e1`, `@e2`).
+ */
+interface AccessibilityNode {
+  /**
+   * Automation ID / test-ID attribute.
+   */
+  automationId?: string | null;
+  /**
+   * Bounding rectangle in screen coordinates.
+   */
+  bounds?: AccessibilityBounds | null;
+  /**
+   * Child nodes in the tree.
+   */
+  children: AccessibilityNode[];
+  /**
+   * CSS class name or control class.
+   */
+  className?: string | null;
+  /**
+   * Accessible description (additional context).
+   */
+  description?: string | null;
+  /**
+   * HTML tag name (for web elements).
+   */
+  htmlTag?: string | null;
+  /**
+   * Whether the element accepts user interaction.
+   */
+  isInteractive: boolean;
+  /**
+   * Hierarchical level (for headings, tree items).
+   */
+  level?: number | null;
+  /**
+   * Accessible name (label).
+   */
+  name?: string | null;
+  /**
+   * Reference ID like `@e1`, `@e2` for AI interaction.
+   */
+  ref: string;
+  role: AccessibilityRole;
+  /**
+   * Current state flags.
+   */
+  state?: AccessibilityState & {};
+  /**
+   * URL for link elements.
+   */
+  url?: string | null;
+  /**
+   * Current value (for inputs).
+   */
+  value?: string | null;
+}
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * Complete accessibility-tree snapshot.
+ *
+ * Full accessibility tree at a point in time, with metadata about the
+ * capture source and summary statistics.
+ */
+interface AccessibilitySnapshot {
+  backend: AccessibilityBackend;
+  /**
+   * Number of interactive nodes.
+   */
+  interactiveNodes: number;
+  root: AccessibilityNode;
+  /**
+   * Unix timestamp of capture.
+   */
+  timestamp: number;
+  /**
+   * Page / window title.
+   */
+  title?: string | null;
+  /**
+   * Total number of nodes in the tree.
+   */
+  totalNodes: number;
+  /**
+   * Page URL (for web targets).
+   */
+  url?: string | null;
+}
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * Role criterion for [`AccessibilitySelector`] — either a single role or a
+ * list of roles (any match).
+ */
+type RoleCriterion = AccessibilityRole | AccessibilityRole[];
+
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+
+
+/**
+ * Selector for finding nodes in an accessibility tree.
+ *
+ * Provides flexible matching criteria for locating elements by role, name,
+ * automation ID, or other attributes. Multiple criteria are combined with
+ * AND logic.
+ */
+interface AccessibilitySelector {
+  /**
+   * Required ancestor selector.
+   */
+  ancestor?: AccessibilitySelector | null;
+  /**
+   * Match by automation / test ID.
+   */
+  automationId?: string | null;
+  /**
+   * Whether string matching is case-sensitive.
+   */
+  caseSensitive: boolean;
+  /**
+   * Match by CSS / control class name.
+   */
+  className?: string | null;
+  /**
+   * Match by HTML tag name.
+   */
+  htmlTag?: string | null;
+  /**
+   * Filter by interactivity.
+   */
+  isInteractive?: boolean | null;
+  /**
+   * Maximum tree depth to search.
+   */
+  maxDepth?: number | null;
+  /**
+   * Exact name match.
+   */
+  name?: string | null;
+  /**
+   * Partial name match (contains).
+   */
+  nameContains?: string | null;
+  /**
+   * Regex pattern for name matching.
+   */
+  namePattern?: string | null;
+  /**
+   * Match by role (single or list).
+   */
+  role?: RoleCriterion | null;
+  /**
+   * Required state flags (partial match).
+   */
+  state?: AccessibilityState | null;
+  /**
+   * Exact value match.
+   */
+  value?: string | null;
+  /**
+   * Partial value match (contains).
+   */
+  valueContains?: string | null;
+}
+
+export type { AccessibilityBackend, AccessibilityBounds, AccessibilityNode, AccessibilityRole, AccessibilitySelector, AccessibilitySnapshot, AccessibilityState };