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

package/src/runtime.ts

@@ -0,0 +1,541 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import {
+  activeElement,
+  configuration,
+  contains,
+  isField,
+  isVisible,
+  observeControl,
+} from "./dom.js";
+import type { NativeField } from "./dom.js";
+import { RuntimeError } from "./errors.js";
+import { pause, validateTimeout, withDeadline } from "./operations.js";
+import { Targets } from "./targets.js";
+import { withActionFeedback } from "./action-feedback.js";
+import { captureScreenshot } from "./screenshot.js";
+import type {
+  ActionOptions,
+  PageState,
+  Runtime,
+  RuntimeAction,
+  RuntimeOptions,
+  Target,
+} from "./types.js";
+
+type Verification = () => void;
+interface Edit {
+  apply(signal: AbortSignal): void;
+  accepted(): boolean;
+}
+
+interface FieldSnapshot {
+  configuration: string;
+  form: HTMLFormElement | null;
+  parent: HTMLElement | null;
+}
+
+const textTypes = new Set([
+  "text",
+  "search",
+  "email",
+  "tel",
+  "url",
+  "number",
+  "date",
+  "datetime-local",
+  "time",
+  "month",
+  "week",
+  "color",
+  "range",
+]);
+
+function assignValue(
+  element: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+): void {
+  const view = element.ownerDocument.defaultView!;
+  const prototype =
+    element.tagName === "TEXTAREA"
+      ? view.HTMLTextAreaElement.prototype
+      : view.HTMLInputElement.prototype;
+  // Bypass React's value tracker so its input handler receives the new value.
+  Object.getOwnPropertyDescriptor(prototype, "value")!.set!.call(
+    element,
+    value,
+  );
+}
+
+/** Create this after mounting. Importing the package itself is safe during server rendering. */
+export function createRuntime(options: RuntimeOptions = {}): Runtime {
+  const root = options.root === undefined ? globalThis.document : options.root;
+  if (!root) {
+    throw new TypeError(
+      "Create the runtime in a browser, after the app has mounted.",
+    );
+  }
+
+  const targets = new Targets(root);
+  const document = targets.document;
+  const view = document.defaultView!;
+  const timeoutMs = options.timeoutMs ?? 2000;
+
+  validateTimeout(timeoutMs);
+  let busy = false;
+
+  async function run<T>(
+    settings: ActionOptions,
+    operation: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    if (busy) {
+      throw new RuntimeError(
+        "BUSY",
+        "Another operation is running. Await it before starting the next one.",
+      );
+    }
+
+    busy = true;
+    try {
+      return await withDeadline(
+        settings.timeoutMs ?? timeoutMs,
+        settings.signal,
+        operation,
+      );
+    } finally {
+      busy = false;
+    }
+  }
+
+  function act(
+    settings: ActionOptions,
+    effect: (
+      signal: AbortSignal,
+    ) => void | Verification | Promise<void | Verification>,
+    feedback?: {
+      action: RuntimeAction;
+      target: Target;
+      requireEnabled?: boolean;
+    },
+  ): Promise<PageState> {
+    return run(settings, async (signal) => {
+      const execute = async (): Promise<PageState> => {
+        const verify = await effect(signal);
+
+        // Give controlled inputs and ordinary React event updates a turn to commit.
+        await pause(signal);
+        signal.throwIfAborted();
+        verify?.();
+
+        return targets.getState();
+      };
+
+      return feedback
+        ? withActionFeedback(
+            options,
+            feedback.action,
+            () => targets.resolve(feedback.target, feedback.requireEnabled),
+            signal,
+            execute,
+          )
+        : execute();
+    });
+  }
+
+  function focusTarget(target: Target, signal: AbortSignal): HTMLElement {
+    const element = targets.resolve(target);
+    element.focus({ preventScroll: true });
+    signal.throwIfAborted();
+    targets.resolve(target);
+    return element;
+  }
+
+  function verifyEdit(
+    field: NativeField,
+    before: FieldSnapshot,
+    change: Edit,
+  ): void {
+    // A field replaced or reconfigured during the edit is no longer the same target.
+    const fieldChanged =
+      !contains(root, field) ||
+      !isVisible(field) ||
+      !observeControl(field, root).enabled ||
+      configuration(field) !== before.configuration ||
+      field.form !== before.form ||
+      field.parentElement !== before.parent;
+
+    if (fieldChanged || !change.accepted()) {
+      throw new RuntimeError(
+        "VALUE_REJECTED",
+        "The application did not accept the requested field value.",
+      );
+    }
+  }
+
+  function edit(
+    action: "fill" | "select" | "check",
+    target: Target,
+    settings: ActionOptions,
+    prepare: (field: NativeField) => Edit,
+  ): Promise<PageState> {
+    return act(
+      settings,
+      (signal) => {
+        const element = targets.resolve(target);
+        if (!isField(element)) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "This operation needs a native input, textarea or select.",
+          );
+        }
+
+        if (observeControl(element, root).readOnly) {
+          throw new RuntimeError("READ_ONLY", "The field is read-only.");
+        }
+
+        const change = prepare(element);
+        focusTarget(target, signal);
+
+        const before: FieldSnapshot = {
+          configuration: configuration(element),
+          form: element.form,
+          parent: element.parentElement,
+        };
+
+        change.apply(signal);
+
+        // Check the result after the application has processed the field events.
+        return () => verifyEdit(element, before, change);
+      },
+      { action, target },
+    );
+  }
+
+  function fieldEvents(element: NativeField, signal: AbortSignal): void {
+    element.dispatchEvent(new view.Event("input", { bubbles: true }));
+    signal.throwIfAborted();
+    element.dispatchEvent(new view.Event("change", { bubbles: true }));
+  }
+
+  return {
+    getState: () => targets.getState(),
+    screenshot(settings = {}) {
+      return run(settings, (signal) => captureScreenshot(root, signal));
+    },
+
+    click(target, settings = {}) {
+      return act(settings, () => targets.resolve(target).click(), {
+        action: "click",
+        target,
+      });
+    },
+
+    focus(target, settings = {}) {
+      return act(
+        settings,
+        (signal) => {
+          const element = focusTarget(target, signal);
+          return () => {
+            if (activeElement(document) !== element) {
+              throw new RuntimeError(
+                "UNSUPPORTED",
+                "The control did not receive focus.",
+              );
+            }
+          };
+        },
+        { action: "focus", target },
+      );
+    },
+
+    blur(target, settings = {}) {
+      return act(settings, () => targets.resolve(target).blur(), {
+        action: "blur",
+        target,
+      });
+    },
+
+    setValue(target, value, settings = {}) {
+      return edit("fill", target, settings, (field) => {
+        if (
+          field.tagName === "SELECT" ||
+          (field.tagName === "INPUT" &&
+            !textTypes.has((field as HTMLInputElement).type))
+        ) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Use setValue with a text or value input or a textarea.",
+          );
+        }
+
+        const element = field as HTMLInputElement | HTMLTextAreaElement;
+        const clone = element.cloneNode(true) as typeof element;
+
+        // Check the browser's normalization before changing the real field.
+        assignValue(clone, value);
+        if (
+          clone.value !== value ||
+          (element.maxLength >= 0 && value.length > element.maxLength)
+        ) {
+          throw new RuntimeError(
+            "VALUE_REJECTED",
+            "The requested value does not fit this field.",
+          );
+        }
+
+        return {
+          apply(signal) {
+            assignValue(element, value);
+            fieldEvents(element, signal);
+          },
+          accepted: () => element.value === value,
+        };
+      });
+    },
+
+    selectOption(target, values, settings = {}) {
+      return edit("select", target, settings, (field) => {
+        if (field.tagName !== "SELECT") {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Use selectOption with a native select.",
+          );
+        }
+
+        const select = field as HTMLSelectElement;
+        const options = [...select.options];
+
+        if (
+          new Set(values).size !== values.length ||
+          (!select.multiple && values.length > 1) ||
+          values.some(
+            (value) => !options.some((option) => option.value === value),
+          ) ||
+          options.some(
+            (option) =>
+              values.includes(option.value) &&
+              (option.disabled || option.closest("optgroup[disabled]")),
+          )
+        ) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Choose available option values from getState().",
+          );
+        }
+
+        return {
+          apply(signal) {
+            select.selectedIndex = -1;
+            for (const option of options) {
+              option.selected = values.includes(option.value);
+            }
+
+            fieldEvents(select, signal);
+          },
+          accepted: () =>
+            select.selectedOptions.length === values.length &&
+            [...select.selectedOptions].every((option) =>
+              values.includes(option.value),
+            ),
+        };
+      });
+    },
+
+    setChecked(target, checked, settings = {}) {
+      return edit("check", target, settings, (field) => {
+        const input = field as HTMLInputElement;
+        if (
+          field.tagName !== "INPUT" ||
+          !["checkbox", "radio"].includes(input.type)
+        ) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Use setChecked with a native checkbox or radio.",
+          );
+        }
+
+        if (input.type === "radio" && input.checked && !checked) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Select another radio in the group to change its value.",
+          );
+        }
+
+        return {
+          apply() {
+            if (input.checked !== checked) {
+              input.click();
+            }
+          },
+          accepted: () => input.checked === checked,
+        };
+      });
+    },
+
+    insertText(target, text, settings = {}) {
+      return act(
+        settings,
+        (signal) => {
+          const element = targets.resolve(target);
+          const data = observeControl(element, root);
+
+          if (data.readOnly) {
+            throw new RuntimeError("READ_ONLY", "The editor is read-only.");
+          }
+
+          if (!data.contentEditable && !element.matches("input, textarea")) {
+            throw new RuntimeError(
+              "UNSUPPORTED",
+              "Insert text requires a text field or contenteditable surface.",
+            );
+          }
+
+          focusTarget(target, signal);
+          signal.throwIfAborted();
+
+          // Rich editors own their document and intercept beforeinput. Let them
+          // handle insertion before falling back to the browser editing command.
+          const input = new view.InputEvent("beforeinput", {
+            inputType: "insertText",
+            data: text,
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+          });
+
+          if (!element.dispatchEvent(input)) {
+            signal.throwIfAborted();
+            return () => {
+              if (text && observeControl(element, root).value === data.value) {
+                throw new RuntimeError(
+                  "VALUE_REJECTED",
+                  "The editor did not accept text insertion.",
+                );
+              }
+            };
+          }
+
+          signal.throwIfAborted();
+          targets.resolve(target);
+
+          if (typeof document.execCommand !== "function") {
+            throw new RuntimeError(
+              "UNSUPPORTED",
+              "This browser does not support the text insertion command.",
+            );
+          }
+
+          if (!document.execCommand("insertText", false, text)) {
+            throw new RuntimeError(
+              "VALUE_REJECTED",
+              "The browser or editor rejected text insertion.",
+            );
+          }
+        },
+        { action: "insertText", target },
+      );
+    },
+
+    pressKey(target, key, settings = {}) {
+      return act(
+        settings,
+        (signal) => {
+          if (!key) {
+            throw new TypeError(
+              "Provide a keyboard key, such as Enter or Escape.",
+            );
+          }
+
+          const element = focusTarget(target, signal);
+          const event = {
+            key,
+            bubbles: true,
+            cancelable: true,
+            altKey: settings.altKey ?? false,
+            ctrlKey: settings.ctrlKey ?? false,
+            metaKey: settings.metaKey ?? false,
+            shiftKey: settings.shiftKey ?? false,
+          };
+
+          element.dispatchEvent(new view.KeyboardEvent("keydown", event));
+          signal.throwIfAborted();
+          if (element.isConnected) {
+            element.dispatchEvent(new view.KeyboardEvent("keyup", event));
+          }
+        },
+        { action: "key", target },
+      );
+    },
+
+    scrollIntoView(target, settings = {}) {
+      return act(
+        settings,
+        () => {
+          const element = targets.resolve(target, false);
+          if (typeof element.scrollIntoView !== "function") {
+            throw new RuntimeError(
+              "UNSUPPORTED",
+              "This environment does not support scrollIntoView.",
+            );
+          }
+
+          element.scrollIntoView({
+            block: "nearest",
+            inline: "nearest",
+            behavior: "instant",
+          });
+        },
+        { action: "scroll", target, requireEnabled: false },
+      );
+    },
+
+    goto(path, settings = {}) {
+      return act(settings, async (signal) => {
+        const navigate = options.navigate;
+        if (!navigate) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Pass your router navigation callback to createRuntime.",
+          );
+        }
+
+        const url = new URL(path, document.URL);
+        if (
+          url.origin !== document.location.origin ||
+          !["http:", "https:"].includes(url.protocol)
+        ) {
+          throw new RuntimeError(
+            "UNSUPPORTED",
+            "Navigation must stay within this application origin.",
+          );
+        }
+
+        await navigate(url.pathname + url.search + url.hash, signal);
+        signal.throwIfAborted();
+
+        return () => {
+          if (document.URL !== url.href) {
+            throw new RuntimeError(
+              "VALUE_REJECTED",
+              "The router did not reach the requested URL.",
+            );
+          }
+        };
+      });
+    },
+
+    waitFor(condition, settings = {}) {
+      return run(settings, async (signal) => {
+        while (true) {
+          signal.throwIfAborted();
+          const state = targets.getState();
+
+          if (condition(state)) {
+            return state;
+          }
+
+          await pause(signal, 50);
+        }
+      });
+    },
+  };
+}

package/src/screenshot.ts

@@ -0,0 +1,172 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { RuntimeError } from './errors.js';
+import type { Screenshot } from './types.js';
+
+const privateSelector =
+  'input[type="password"], input[type="file"], [data-ruakit-ignore], [data-ruakit-toolbar]';
+const maxDimension = 8192;
+const maxPixels = 4 * 1024 * 1024;
+const maxBytes = 5 * 1024 * 1024;
+const pngPrefix = 'data:image/png;base64,';
+
+function excluded(element: Element): boolean {
+  let ancestor: Element | null = element;
+  while (ancestor) {
+    if (ancestor.closest(privateSelector)) return true;
+
+    const scope = ancestor.getRootNode();
+    ancestor = 'host' in scope ? (scope as ShadowRoot).host : null;
+  }
+
+  if (['SCRIPT', 'NOSCRIPT', 'HEAD', 'IFRAME'].includes(element.tagName.toUpperCase())) {
+    return true;
+  }
+
+  // SVGs and <use> references bypass html-to-image's child filter.
+  return (
+    element.namespaceURI === 'http://www.w3.org/2000/svg' &&
+    Boolean(element.querySelector(privateSelector) || element.querySelector('use'))
+  );
+}
+
+function pngData(canvas: HTMLCanvasElement, signal: AbortSignal): string {
+  const dataUrl = canvas.toDataURL('image/png');
+  signal.throwIfAborted();
+
+  const data = dataUrl.slice(pngPrefix.length);
+  if (
+    !dataUrl.startsWith(pngPrefix) ||
+    !data.length ||
+    data.length % 4 !== 0 ||
+    data.length > Math.ceil(maxBytes / 3) * 4 ||
+    !/^[A-Za-z0-9+/]+={0,2}$/.test(data)
+  ) {
+    throw new RuntimeError('UNSUPPORTED', 'The screenshot must be a PNG image within 5 MiB.');
+  }
+
+  const bytes = globalThis.atob(data);
+  if (bytes.length > maxBytes || !bytes.startsWith('\x89PNG\r\n\x1a\n')) {
+    throw new RuntimeError('UNSUPPORTED', 'The screenshot must be a PNG image within 5 MiB.');
+  }
+
+  return data;
+}
+
+export async function captureScreenshot(
+  root: Document | HTMLElement,
+  signal: AbortSignal,
+): Promise<Screenshot> {
+  signal.throwIfAborted();
+
+  const document = root.ownerDocument ?? (root as Document);
+  const element =
+    root.nodeType === 9 ? document.documentElement : (root as HTMLElement);
+  const url = document.URL;
+
+  if (!element?.isConnected) {
+    throw new RuntimeError(
+      'STALE_TARGET',
+      'The screenshot root is disconnected.',
+    );
+  }
+  if (excluded(element)) {
+    throw new RuntimeError(
+      'UNSUPPORTED',
+      'The screenshot root is excluded from observation.',
+    );
+  }
+
+  const rect = element.getBoundingClientRect();
+  const width = Math.ceil(
+    Math.max(element.offsetWidth, element.clientWidth) || rect.width,
+  );
+  const height = Math.ceil(
+    Math.max(element.offsetHeight, element.clientHeight) || rect.height,
+  );
+
+  if (
+    !Number.isFinite(width) ||
+    !Number.isFinite(height) ||
+    width < 1 ||
+    height < 1
+  ) {
+    throw new RuntimeError(
+      'UNSUPPORTED',
+      'The screenshot root has no rendered area.',
+    );
+  }
+
+  const scale = Math.min(
+    1,
+    maxDimension / width,
+    maxDimension / height,
+    Math.sqrt(maxPixels / width / height),
+  );
+  const style = document.defaultView?.getComputedStyle(element);
+
+  // Import only on demand. Observation, actions and server rendering do not load the renderer.
+  const { toCanvas } = await import('html-to-image');
+  signal.throwIfAborted();
+
+  const canvas = await toCanvas(element, {
+    width,
+    height,
+    canvasWidth: Math.max(1, Math.floor(width * scale)),
+    canvasHeight: Math.max(1, Math.floor(height * scale)),
+    pixelRatio: 1,
+    includeQueryParams: true,
+    fetchRequestInit: { signal },
+    // Normalize the root's placement in the exported image without changing the live page.
+    style: {
+      margin: '0',
+      top: '0',
+      left: '0',
+      transform: 'none',
+      width: style?.width || `${width}px`,
+      height: style?.height || `${height}px`,
+    },
+    filter: (node) => {
+      signal.throwIfAborted();
+      return node.nodeType !== 1 || !excluded(node);
+    },
+  });
+
+  signal.throwIfAborted();
+  if (document.URL !== url || !element.isConnected) {
+    throw new RuntimeError(
+      'STALE_TARGET',
+      'The page changed during screenshot capture.',
+    );
+  }
+  if (excluded(element)) {
+    throw new RuntimeError(
+      'STALE_TARGET',
+      'The screenshot root became excluded during capture.',
+    );
+  }
+
+  if (
+    !Number.isInteger(canvas.width) ||
+    canvas.width < 1 ||
+    canvas.width > maxDimension ||
+    !Number.isInteger(canvas.height) ||
+    canvas.height < 1 ||
+    canvas.height > maxDimension ||
+    canvas.width * canvas.height > maxPixels
+  ) {
+    throw new RuntimeError(
+      'UNSUPPORTED',
+      'The screenshot exceeds the image dimensions limit.',
+    );
+  }
+  const data = pngData(canvas, signal);
+
+  return {
+    data,
+    mimeType: 'image/png',
+    width: canvas.width,
+    height: canvas.height,
+    capturedAt: Date.now(),
+    url,
+  };
+}