@ruakit/runtime 0.0.0-stage → 0.1.0-alpha.1

package/src/targets.ts

@@ -0,0 +1,141 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import {
+  configuration,
+  activeElement,
+  contains,
+  controls,
+  isField,
+  isVisible,
+  observeControl,
+  visibleText,
+} from './dom.js';
+import type { ControlData } from './dom.js';
+import { RuntimeError } from './errors.js';
+import type { PageState, Target } from './types.js';
+
+interface Binding {
+  element: HTMLElement;
+  target: Target;
+  data: ControlData;
+  configuration: string;
+  parent: Element | null;
+  form: HTMLFormElement | null;
+  url: string;
+}
+
+let nextRuntime = 0;
+
+export class Targets {
+  readonly document: Document;
+  private readonly prefix = `runtime-${++nextRuntime}`;
+  private readonly ids = new WeakMap<HTMLElement, string>();
+  private bindings = new Map<string, Binding>();
+  private sequence = 0;
+  private version = 0;
+
+  constructor(readonly root: Document | HTMLElement) {
+    this.document = root.ownerDocument ?? (root as Document);
+    if (!this.document.defaultView) {
+      throw new TypeError('Create the runtime in a browser, after the app has mounted.');
+    }
+  }
+
+  getState(): PageState {
+    const next = new Map<string, Binding>();
+    let truncated = false;
+
+    for (const element of controls(this.root)) {
+      if (
+        !isVisible(element) ||
+        element.matches('input[type="hidden"], input[type="password"], input[type="file"]')
+      ) {
+        continue;
+      }
+
+      if (next.size === 200) {
+        truncated = true;
+        break;
+      }
+
+      let id = this.ids.get(element);
+      if (!id) {
+        id = `${this.prefix}:${++this.sequence}`;
+        this.ids.set(element, id);
+      }
+
+      const data = observeControl(element, this.root);
+      const previous = this.bindings.get(id);
+      const unchanged = previous && this.matches(previous, data);
+
+      next.set(id, {
+        element,
+        target: { id, version: unchanged ? previous.target.version : ++this.version },
+        data,
+        configuration: configuration(element),
+        parent: element.parentElement,
+        form: isField(element) ? element.form : null,
+        url: this.document.URL,
+      });
+    }
+
+    this.bindings = next;
+    const text = visibleText(this.root, 20001);
+    const focused = [...next.values()].find(
+      ({ element }) => element === activeElement(this.document),
+    )?.target;
+
+    return {
+      url: this.document.URL,
+      title: this.document.title,
+      text: text.slice(0, 20000),
+      controls: [...next.values()].map(({ target, data }) => ({
+        target: { ...target },
+        ...structuredClone(data),
+      })),
+      focused: focused ? { ...focused } : null,
+      truncated:
+        truncated ||
+        text.length > 20000 ||
+        [...next.values()].some(
+          ({ data }) =>
+            data.context.length === 1000 ||
+            data.label.length === 1000 ||
+            data.description?.length === 1000 ||
+            data.placeholder?.length === 1000 ||
+            data.groupsTruncated === true,
+        ),
+    };
+  }
+
+  resolve(target: Target, requireEnabled = true): HTMLElement {
+    const binding = this.bindings.get(target.id);
+    if (
+      !binding ||
+      binding.target.version !== target.version ||
+      !contains(this.root, binding.element) ||
+      !isVisible(binding.element) ||
+      !this.matches(binding, observeControl(binding.element, this.root))
+    ) {
+      throw new RuntimeError(
+        'STALE_TARGET',
+        'The control changed. Call getState() and choose it again.',
+      );
+    }
+
+    if (requireEnabled && !binding.data.enabled) {
+      throw new RuntimeError('DISABLED', 'The control is disabled.');
+    }
+
+    return binding.element;
+  }
+
+  private matches(binding: Binding, data: ControlData): boolean {
+    return (
+      binding.url === this.document.URL &&
+      binding.parent === binding.element.parentElement &&
+      binding.form === (isField(binding.element) ? binding.element.form : null) &&
+      binding.configuration === configuration(binding.element) &&
+      JSON.stringify(binding.data) === JSON.stringify(data)
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,135 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+
+/** A reference returned by getState. Keep both fields when passing it across a boundary. */
+export interface Target {
+  id: string;
+  version: number;
+}
+
+/** A named enclosing form, fieldset, section, ARIA group or dialog. Outer groups come first. */
+export interface ControlGroup {
+  role: 'form' | 'group' | 'radiogroup' | 'region' | 'dialog' | 'alertdialog';
+  name: string;
+}
+
+export interface ControlState {
+  target: Target;
+  tag: string;
+  type?: string;
+  role: string;
+  /** Computed accessible name. Empty when the control has no accessible name. */
+  label: string;
+  description?: string;
+  /** A field hint, reported separately from the accessible name. */
+  placeholder?: string;
+  /** Up to four nearest named groups, ordered from outermost to innermost. */
+  groups?: ControlGroup[];
+  /** A group name or enclosing group was omitted because of observation limits. */
+  groupsTruncated?: boolean;
+  context: string;
+  enabled: boolean;
+  readOnly: boolean;
+  value?: string;
+  checked?: boolean;
+  expanded?: boolean;
+  selectedValues?: string[];
+  options?: { value: string; label: string; enabled: boolean }[];
+  valid?: boolean;
+  contentEditable?: boolean;
+}
+
+export interface PageState {
+  url: string;
+  title: string;
+  text: string;
+  controls: ControlState[];
+  focused: Target | null;
+  /** Text or controls were omitted because the observation limit was reached. */
+  truncated: boolean;
+}
+
+export interface ActionOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface KeyOptions extends ActionOptions {
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+}
+
+export type RuntimeAction =
+  'click' | 'focus' | 'blur' | 'fill' | 'select' | 'check' | 'insertText' | 'key' | 'scroll';
+
+export interface ActionRect {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Local UI feedback only. DOM references never enter planner requests or receipts. */
+export interface RuntimeActionEvent {
+  readonly id: number;
+  readonly action: RuntimeAction;
+  readonly phase: 'before' | 'after' | 'cancelled' | 'failed';
+  readonly element: HTMLElement;
+  readonly rect: ActionRect;
+  readonly durationMs: number;
+}
+
+export interface ActionFeedbackOptions {
+  /** Observational callback. Exceptions are ignored; targets are revalidated before execution. */
+  onAction?: (event: RuntimeActionEvent) => void;
+  /** Movement allowance in ms, or a resolver called after scrolling. Integer 0–10000; defaults to 0. */
+  actionDelayMs?: number | ((element: HTMLElement) => number);
+  /** Scroll feedback targets into view before cursor movement. Defaults to false. */
+  scrollToTarget?: boolean;
+}
+
+export interface RuntimeOptions extends ActionFeedbackOptions {
+  /** Defaults to the current document. Use an app container to limit observation and actions. */
+  root?: Document | HTMLElement;
+  /** Connect your router here. Resolve once navigation has committed. */
+  navigate?: (path: string, signal: AbortSignal) => void | Promise<void>;
+  /** Default operation deadline, in milliseconds. Defaults to 2000. */
+  timeoutMs?: number;
+}
+
+export interface ScreenshotImage {
+  /** Raw base64 image bytes, without a data URL prefix. Maximum decoded size: 5 MiB. */
+  data: string;
+  mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
+  width: number;
+  height: number;
+}
+export interface Screenshot extends ScreenshotImage {
+  capturedAt: number;
+  url: string;
+}
+
+/** Each action returns a fresh observation. It does not establish that a larger task succeeded. */
+export interface Runtime {
+  getState(): PageState;
+  /** Render the configured root to PNG on demand using html-to-image. Private UI is excluded. */
+  screenshot(options?: ActionOptions): Promise<Screenshot>;
+  click(target: Target, options?: ActionOptions): Promise<PageState>;
+  focus(target: Target, options?: ActionOptions): Promise<PageState>;
+  blur(target: Target, options?: ActionOptions): Promise<PageState>;
+  /** Insert text at the current selection using the browser editing command. */
+  insertText(target: Target, text: string, options?: ActionOptions): Promise<PageState>;
+  setValue(target: Target, value: string, options?: ActionOptions): Promise<PageState>;
+  selectOption(
+    target: Target,
+    values: readonly string[],
+    options?: ActionOptions,
+  ): Promise<PageState>;
+  setChecked(target: Target, checked: boolean, options?: ActionOptions): Promise<PageState>;
+  /** Dispatch keydown/keyup to a control. Browser shortcuts and text insertion are not simulated. */
+  pressKey(target: Target, key: string, options?: KeyOptions): Promise<PageState>;
+  scrollIntoView(target: Target, options?: ActionOptions): Promise<PageState>;
+  goto(path: string, options?: ActionOptions): Promise<PageState>;
+  waitFor(condition: (state: PageState) => boolean, options?: ActionOptions): Promise<PageState>;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.