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

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/** 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@ruakit/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "Observe and interact with the rendered application",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./experimental": {
+      "types": "./dist/experimental/index.d.ts",
+      "import": "./dist/experimental/index.js"
+    }
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "dependencies": {
+    "dom-accessibility-api": "0.7.1",
+    "html-to-image": "1.11.13"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../shared/scripts/minify.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/action-feedback.ts

@@ -0,0 +1,85 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { pause } from './operations.js';
+import type {
+  ActionFeedbackOptions,
+  ActionRect,
+  RuntimeAction,
+  RuntimeActionEvent,
+} from './types.js';
+
+let nextAction = 0;
+
+/** Present one validated local action. The resolver must reject stale or unavailable targets. */
+export async function withActionFeedback<T>(
+  options: ActionFeedbackOptions,
+  action: RuntimeAction,
+  resolve: () => HTMLElement,
+  signal: AbortSignal,
+  effect: (element: HTMLElement) => T | Promise<T>,
+): Promise<T> {
+  signal.throwIfAborted();
+
+  const delay = options.actionDelayMs ?? 0;
+  const validateDelay = (value: number): number => {
+    if (!Number.isInteger(value) || value < 0 || value > 10000)
+      throw new RangeError('actionDelayMs must resolve to an integer from 0 to 10000 milliseconds.');
+    return value;
+  };
+
+  let durationMs = typeof delay === 'function' ? 0 : validateDelay(delay);
+  let element = resolve();
+
+  if (!options.onAction) {
+    return effect(element);
+  }
+
+  const id = ++nextAction;
+  let rect: ActionRect = { left: 0, top: 0, width: 0, height: 0 };
+
+  const notify = (phase: RuntimeActionEvent['phase']): void => {
+    if (element.isConnected) {
+      const bounds = element.getBoundingClientRect();
+      rect = { left: bounds.left, top: bounds.top, width: bounds.width, height: bounds.height };
+    }
+
+    try {
+      options.onAction?.({ id, action, phase, element, rect: { ...rect }, durationMs });
+    } catch {
+      // UI feedback cannot authorize an action or invalidate its result.
+    }
+  };
+
+  try {
+    if (options.scrollToTarget) {
+      element.scrollIntoView?.({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+    }
+
+    signal.throwIfAborted();
+    element = resolve();
+
+    if (typeof delay === 'function') {
+      durationMs = validateDelay(delay(element));
+      signal.throwIfAborted();
+      element = resolve();
+    }
+
+    notify('before');
+    signal.throwIfAborted();
+    if (durationMs) {
+      await pause(signal, durationMs);
+    }
+
+    // Scrolling, UI callbacks and animation time can all change the application.
+    element = resolve();
+    signal.throwIfAborted();
+
+    const result = await effect(element);
+    signal.throwIfAborted();
+    notify('after');
+
+    return result;
+  } catch (error) {
+    notify(signal.aborted ? 'cancelled' : 'failed');
+    throw error;
+  }
+}

package/src/dom.ts

@@ -0,0 +1,307 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import {
+  computeAccessibleDescription,
+  computeAccessibleName,
+  getRole,
+} from 'dom-accessibility-api';
+import type { ControlGroup, ControlState } from './types.js';
+
+export type NativeField = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+export type ControlData = Omit<ControlState, 'target'>;
+
+export const CONTROL_SELECTOR =
+  'button, a[href], input:not([type="hidden"]):not([type="password"]):not([type="file"]), textarea, select, [contenteditable="true"], [contenteditable=""], [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="textbox"], [role="combobox"], [tabindex]';
+const excluded = 'script, style, noscript, template, [data-ruakit-ignore], [data-ruakit-toolbar]';
+const normalize = (value: string): string => value.replace(/\s+/g, ' ').trim();
+
+/** Follow open shadow hosts as well as ordinary DOM ancestors. */
+export function composedParent(element: HTMLElement): HTMLElement | null {
+  if (element.parentElement) return element.parentElement;
+
+  const root = element.getRootNode();
+  return root instanceof element.ownerDocument.defaultView!.ShadowRoot
+    ? (root.host as HTMLElement)
+    : null;
+}
+
+export function contains(root: Document | HTMLElement, element: HTMLElement): boolean {
+  for (let current: HTMLElement | null = element; current; current = composedParent(current)) {
+    if (root.contains(current)) return true;
+  }
+
+  return false;
+}
+
+export function activeElement(document: Document): Element | null {
+  let element = document.activeElement;
+  while (element?.shadowRoot?.activeElement) element = element.shadowRoot.activeElement;
+  return element;
+}
+
+/** Keep discovery within the configured root, including its open shadow trees. */
+export function* controls(root: Document | HTMLElement | ShadowRoot): Generator<HTMLElement> {
+  if (root.nodeType === 1 && (root as HTMLElement).matches(CONTROL_SELECTOR))
+    yield root as HTMLElement;
+  if (root.nodeType === 1 && (root as HTMLElement).shadowRoot)
+    yield* controls((root as HTMLElement).shadowRoot!);
+
+  for (const child of root.children) {
+    if (child.matches(excluded)) continue;
+    yield* controls(child as HTMLElement);
+  }
+}
+
+export function isField(element: HTMLElement): element is NativeField {
+  return ['INPUT', 'TEXTAREA', 'SELECT'].includes(element.tagName);
+}
+
+export function isVisible(element: HTMLElement): boolean {
+  if (
+    !element.isConnected ||
+    !element.getClientRects().length ||
+    element.closest(`${excluded}, [hidden], [inert], [aria-hidden="true"]`)
+  ) {
+    return false;
+  }
+
+  const view = element.ownerDocument.defaultView!;
+  const current = view.getComputedStyle(element);
+  if (current.visibility === 'hidden' || current.visibility === 'collapse') {
+    return false;
+  }
+
+  for (let parent: HTMLElement | null = element; parent; parent = composedParent(parent)) {
+    if (parent.matches(`${excluded}, [hidden], [inert], [aria-hidden="true"]`)) return false;
+    const style = view.getComputedStyle(parent);
+    if (style.display === 'none' || style.opacity === '0') {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** Read rendered text without copying hidden content or field values into page prose. */
+export function visibleText(root: Document | HTMLElement, limit: number): string {
+  if (
+    root.nodeType === 1 &&
+    (root as HTMLElement).matches(`${excluded}, input, textarea, select`)
+  ) {
+    return '';
+  }
+  const document = root.ownerDocument ?? (root as Document);
+  const view = document.defaultView!;
+  const walker = document.createTreeWalker(
+    root,
+    view.NodeFilter.SHOW_ELEMENT | view.NodeFilter.SHOW_TEXT,
+    {
+      acceptNode(node) {
+        if (node.nodeType === view.Node.ELEMENT_NODE) {
+          const element = node as HTMLElement;
+          if (element.matches(`${excluded}, input, textarea, select`)) {
+            return view.NodeFilter.FILTER_REJECT;
+          }
+          // A descendant can override visibility:hidden. Its own text is checked below.
+          const visibility = view.getComputedStyle(element).visibility;
+          return isVisible(element) || visibility === 'hidden' || visibility === 'collapse'
+            ? view.NodeFilter.FILTER_SKIP
+            : view.NodeFilter.FILTER_REJECT;
+        }
+        return node.parentElement && isVisible(node.parentElement)
+          ? view.NodeFilter.FILTER_ACCEPT
+          : view.NodeFilter.FILTER_REJECT;
+      },
+    },
+  );
+  let result = '';
+  while (walker.nextNode()) {
+    const value = normalize(walker.currentNode.textContent ?? '');
+    if (value) {
+      result += (result ? ' ' : '') + value;
+    }
+    if (result.length >= limit) {
+      break;
+    }
+  }
+  return result;
+}
+
+function roleOf(element: HTMLElement): string {
+  const explicit = element.getAttribute('role');
+  if (explicit) {
+    return explicit;
+  }
+  if (element.tagName === 'A') {
+    return 'link';
+  }
+  if (element.tagName === 'BUTTON') {
+    return 'button';
+  }
+  if (element.tagName === 'SELECT') {
+    const select = element as HTMLSelectElement;
+    return select.multiple || select.size > 1 ? 'listbox' : 'combobox';
+  }
+  if (element.tagName === 'INPUT') {
+    const type = (element as HTMLInputElement).type;
+    if (['button', 'submit', 'reset', 'image'].includes(type)) {
+      return 'button';
+    }
+    if (['checkbox', 'radio'].includes(type)) {
+      return type;
+    }
+  }
+  return isField(element) ? 'textbox' : 'control';
+}
+
+const groupRoles = new Set<ControlGroup['role']>([
+  'form',
+  'group',
+  'radiogroup',
+  'region',
+  'dialog',
+  'alertdialog',
+]);
+
+/** Preserve group names without copying complete forms, field values or surrounding page prose. */
+function observeGroups(
+  element: HTMLElement,
+  root: Document | HTMLElement,
+): Pick<ControlData, 'groups' | 'groupsTruncated'> {
+  const groups: ControlGroup[] = [];
+  const ancestors = new Set<HTMLElement>();
+  let truncated = false;
+
+  const add = (container: HTMLElement): void => {
+    if (container.closest(`${excluded}, [hidden], [inert], [aria-hidden="true"]`)) {
+      return;
+    }
+    const role = getRole(container) as ControlGroup['role'] | null;
+    if (!role || !groupRoles.has(role)) {
+      return;
+    }
+    let name = normalize(computeAccessibleName(container));
+    if (!name) {
+      // A direct visible heading also identifies an otherwise unnamed section or group.
+      const heading = [...container.children].find(
+        (child): child is HTMLElement =>
+          child instanceof element.ownerDocument.defaultView!.HTMLElement &&
+          child.matches('h1, h2, h3, h4, h5, h6, [role="heading"]') &&
+          isVisible(child),
+      );
+      if (heading) {
+        name = visibleText(heading, 201);
+      }
+    }
+    if (!name) {
+      return;
+    }
+    if (groups.length === 4) {
+      truncated = true;
+      return;
+    }
+    truncated ||= name.length > 200;
+    groups.push({ role, name: name.slice(0, 200) });
+  };
+
+  const ownerForm =
+    isField(element) || element.tagName === 'BUTTON'
+      ? (element as NativeField | HTMLButtonElement).form
+      : null;
+
+  for (
+    let parent = composedParent(element);
+    parent && contains(root, parent);
+    parent = composedParent(parent)
+  ) {
+    ancestors.add(parent);
+    // A form attribute can associate a field with a different form from its DOM ancestor.
+    if (parent.tagName !== 'FORM' || !ownerForm || parent === ownerForm) {
+      add(parent);
+    }
+  }
+
+  if (ownerForm && contains(root, ownerForm) && !ancestors.has(ownerForm)) {
+    add(ownerForm);
+  }
+
+  return {
+    ...(groups.length ? { groups: groups.reverse() } : {}),
+    ...(truncated ? { groupsTruncated: true } : {}),
+  };
+}
+
+export function observeControl(element: HTMLElement, root: Document | HTMLElement): ControlData {
+  const editable = element.matches('[contenteditable="true"], [contenteditable=""]');
+  const field = isField(element) ? element : undefined;
+  const type = element.tagName === 'INPUT' ? (element as HTMLInputElement).type : '';
+  const select = element.tagName === 'SELECT' ? (element as HTMLSelectElement) : undefined;
+  const row = element.closest<HTMLElement>('tr, li, article, [role="row"], [role="listitem"]');
+  const description = normalize(computeAccessibleDescription(element)).slice(0, 1000);
+  const placeholder = element.matches('input, textarea')
+    ? normalize(element.getAttribute('placeholder') ?? '').slice(0, 1000)
+    : '';
+
+  const data: ControlData = {
+    tag: element.tagName.toLowerCase(),
+    role: editable ? 'textbox' : roleOf(element),
+    ...(editable
+      ? { contentEditable: true, value: element.innerText ?? element.textContent ?? '' }
+      : {}),
+    ...(field ? { type: type || element.tagName.toLowerCase() } : {}),
+    label: normalize(computeAccessibleName(element)).slice(0, 1000),
+    ...(description ? { description } : {}),
+    ...(placeholder ? { placeholder } : {}),
+    ...observeGroups(element, root),
+    context: row && contains(root, row) ? visibleText(row, 1000).slice(0, 1000) : '',
+    enabled: !element.matches(':disabled') && !element.closest('[aria-disabled="true"], [inert]'),
+    readOnly:
+      element.getAttribute('aria-readonly') === 'true' ||
+      Boolean(field && 'readOnly' in field && field.readOnly),
+  };
+
+  if (field) {
+    data.value = field.value;
+    data.valid = field.validity.valid && element.getAttribute('aria-invalid') !== 'true';
+  }
+
+  if (type === 'checkbox' || type === 'radio') {
+    data.checked = (element as HTMLInputElement).checked;
+  } else if (element.hasAttribute('aria-checked')) {
+    data.checked = element.getAttribute('aria-checked') === 'true';
+  }
+
+  if (element.hasAttribute('aria-expanded')) {
+    data.expanded = element.getAttribute('aria-expanded') === 'true';
+  }
+
+  if (select) {
+    data.selectedValues = [...select.selectedOptions].map((option) => option.value);
+    data.options = [...select.options].map((option) => ({
+      value: option.value,
+      label: option.label,
+      enabled: !option.disabled && !option.closest('optgroup[disabled]'),
+    }));
+  }
+
+  return data;
+}
+
+export function configuration(element: HTMLElement): string {
+  return JSON.stringify(
+    [
+      'type',
+      'name',
+      'href',
+      'role',
+      'form',
+      'required',
+      'min',
+      'max',
+      'step',
+      'pattern',
+      'minlength',
+      'maxlength',
+      'multiple',
+    ].map((name) => element.getAttribute(name)),
+  );
+}

package/src/errors.ts

@@ -0,0 +1,14 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+
+export type RuntimeErrorCode =
+  'STALE_TARGET' | 'DISABLED' | 'READ_ONLY' | 'UNSUPPORTED' | 'VALUE_REJECTED' | 'BUSY' | 'TIMEOUT';
+
+export class RuntimeError extends Error {
+  constructor(
+    readonly code: RuntimeErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'RuntimeError';
+  }
+}