@razohq/razo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitchell Lombardo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# razo
+
+**Playwright UI controls that narrate every action twice: a readable sentence in the report, and a structured JSON artifact built for AI failure analysis.**
+
+Page objects have existed for years. razo turns every test into a structured narration — actions and assertions with human names — designed so an AI can analyze failures without guessing. **The output is the product, not the wrapper.**
+
+When a test fails, you don't get a bare `locator timed out`. You get *which business action* failed and *what was expected*, both as a readable story in the Playwright HTML report and as machine-readable JSON:
+
+```json
+{
+  "test": "export a model without choosing quality",
+  "status": "failed",
+  "steps": [
+    { "action": "fill",   "controlType": "field",  "name": "Filename", "detail": "mi-llavero", "status": "passed" },
+    { "action": "choose", "controlType": "select", "name": "Format",   "detail": "3MF",        "status": "passed" },
+    { "action": "click",  "controlType": "button", "name": "Export",   "status": "passed" },
+    { "action": "assert-text", "controlType": "label", "name": "Export status",
+      "expected": "Exported mi-llavero.3mf (Standard)", "actual": "Error: missing fields",
+      "status": "failed", "error": "expect(locator).toHaveText(expected) failed ..." }
+  ]
+}
+```
+
+A model reading this can answer: *"the export never happened — a filename was typed and a format chosen, but nobody selected the quality, and the app responded 'Error: missing fields'"*.
+
+## Install
+
+```bash
+npm install -D @razohq/razo @playwright/test
+```
+
+## Quickstart
+
+Every control takes a `data-testid` and a **human name**. Every method emits a `test.step()` sentence plus a structured `StepEvent`:
+
+```ts
+import { Button, Input, Select, Label } from '@razohq/razo';
+
+const filename = new Input(page, 'filename', 'Filename');
+const format = new Select(page, 'format', 'Format');
+const exportBtn = new Button(page, 'export', 'Export');
+const status = new Label(page, 'status', 'Export status');
+
+await filename.fill('mi-llavero');        // Type "mi-llavero" into field "Filename"
+await format.choose('3MF');               // Choose "3MF" in select "Format"
+await exportBtn.click({ as: 'Confirm the export' }); // business-level override
+await status.expectText('Exported mi-llavero.3mf (Standard)');
+```
+
+Controls: `Button`, `Input`, `TextArea`, `RadioButton`, `Checkbox`, `Select` (single and `chooseMany` for multiple), `Slider`, `FileInput`, `Link`, `Label` (assertions only), `Switch`, `Combobox`, `Table`, `Dialog`, `Tabs`, `Image`, `DatePicker`, `Menu`, `Tooltip` (via `aria-describedby`), and `Editor` (contenteditable). Every control requires a name — an anonymous control breaks the narration, so the constructor rejects it.
+
+Controls can be scoped inside another control with `{ within }` — the narration stays business-level while the `StepEvent` selector carries the full chain:
+
+```ts
+const dialog = new Dialog(page, 'confirm-dialog', 'Confirm export');
+const yes = new Button(page, 'confirm-yes', 'Yes, export', { within: dialog });
+// StepEvent selector: [data-testid="confirm-dialog"] [data-testid="confirm-yes"]
+```
+
+Universal interactions on every control: `hover`, `doubleClick`, `rightClick`, `press(key)`, `focus`, `scrollTo`, and `dragTo(target)` — each with its own grammar sentence (`Hover over button "Export"`, `Drag file input "Model" onto button "Upload zone"`).
+
+Narrated assertions on every control: `expectVisible`, `expectHidden`, `expectEnabled`, `expectDisabled`, `expectFocused`, `expectText`, `expectContainsText`, `expectAttribute`, `expectCount` (for repeated testids) — plus control-specific ones (`Checkbox.expectChecked`, `RadioButton.expectSelected`, `Slider.expectValue`, `FileInput.expectFile`, `Link.expectHref`, `Input.expectEmpty`, `Switch.expectOn/expectOff`, `Table.expectRowCount/expectRowContains`, `Dialog.expectOpen/expectClosed`, `Tabs.expectActive`, `Image.expectAlt/expectLoaded`, `DatePicker.expectDate`, `Combobox.expectSelected`). On failure the event includes `expected` and the `actual` value read from the DOM.
+
+## Locating controls
+
+A plain string means `data-testid` — the recommended, stable path (pair it with the auto-testid Vite plugin below). But razo also accepts Playwright's user-facing locators, so it works on apps that were never instrumented:
+
+```ts
+new Button(page, 'export', 'Export');                                  // data-testid
+new Button(page, { role: 'button', name: 'Export', exact: true }, 'Export');
+new Input(page, { label: 'Filename' }, 'Filename');
+new Input(page, { placeholder: 'my-app e2e' }, 'Project name');
+new Button(page, { text: 'Upload to cloud' }, 'Upload to cloud');
+new Image(page, { altText: 'Model preview' }, 'Model preview');
+new Label(page, { css: '#status' }, 'Export status');
+new Button(page, { locator: page.getByTestId('export').first() }, 'Export'); // escape hatch
+```
+
+The narration never depends on the strategy — only the `StepEvent.selector` changes, and it stays readable (`role=button[name="Export"]`, `label="Filename"`, `css=#status`). Note: a raw `{ locator }` is already bound to the page, so it ignores `{ within }` scoping.
+
+## The AI artifact: wiring the reporter
+
+```ts
+// playwright.config.ts
+export default defineConfig({
+  reporter: [['html'], ['@razohq/razo/reporter']],
+  // recommended: action/assertion timeouts below the test timeout, so a hanging
+  // action fails inside its step (emitting its StepEvent) instead of killing
+  // the test with no narration
+  expect: { timeout: 3_000 },
+  use: { actionTimeout: 5_000 },
+});
+```
+
+The reporter writes one `test-results/<test>/razo-steps.json` per test (configurable via `[['@razohq/razo/reporter', { outputDir: '...' }]]`).
+
+### The `StepEvent` contract
+
+Each step in `razo-steps.json` is a `StepEvent` — the artifact contract AI tooling can build on:
+
+| Field | Meaning |
+|---|---|
+| `action` | Grammar verb: `click`, `fill`, `choose`, `attach`, `set`, `assert-text`, ... |
+| `controlType` | `button`, `field`, `select`, `slider`, `radio group`, ... |
+| `name` | The control's human name (`"Export"`, `"Filename"`) |
+| `sentence` | The sentence exactly as shown in the Playwright report |
+| `detail` | Action payload (typed text, chosen option, attached file) |
+| `expected` | Assertions: what was expected |
+| `actual` | Failed assertions: what was actually found in the DOM |
+| `selector` | Stable selector (`[data-testid="..."]`) |
+| `status` | `passed` \| `failed` |
+| `error` | Error message (ANSI-free) when failed |
+| `timestamp` | ISO 8601 |
+
+The sentence grammar lives in one place — fixed templates per verb — so the narration is predictable and parseable.
+
+## Auto `data-testid` (Vite plugin)
+
+The other half: a stable hook with zero maintenance. A component declares who it is and the plugin generates the testid in dev/test:
+
+```html
+<button data-component="SaveButton">Save</button>
+<!-- becomes -->
+<button data-component="SaveButton" data-testid="save-button">Save</button>
+```
+
+**Alignment rule:** `data-testid` = kebab-case of the component name (`NewsletterOptIn` → `newsletter-opt-in`). A manual `data-testid` always wins.
+
+```ts
+// vite.config.ts — register only in dev/test if you don't want it in production
+import { autoTestId, toTestId } from '@razohq/razo/vite';
+export default defineConfig({ plugins: [autoTestId()] });
+
+// consuming it from a test
+new Button(page, toTestId('SaveButton'), 'Save'); // getByTestId('save-button')
+```
+
+`vite` is an optional peer dependency — if you don't use the plugin, you don't need it.
+
+## Self-healing locators
+
+Deterministic by design: no AI runs inside your tests. Because every control
+already declares a type and a human name, razo can recover from locator drift
+without guessing:
+
+- When a control's primary locator stops resolving, razo tries the control's
+  explicit `fallbacks` (in order), then the implicit `role + accessible name`
+  derived from its type and name. The first spec matching exactly one element
+  wins.
+
+```ts
+new Button(page, 'export-v1', 'Export', {
+  fallbacks: [{ text: 'Export' }], // optional; tried before role=button[name="Export"]
+});
+```
+
+- A healed step passes and its StepEvent carries
+  `healed: { from, to }` — CI stays green, the drift stays visible in the
+  report and the artifact.
+- `RAZO_HEALING=fail` turns healing into a diagnosis: the step fails with a
+  "locator drift" error naming the working locator. `RAZO_HEALING=off`
+  disables it.
+- Healing only triggers when the element cannot be found at all. An element
+  that exists but fails an action or assertion fails normally — healing never
+  masks a product regression.
+- When nothing heals, the failed StepEvent includes `domCandidates` (same-role
+  elements on the page) so `razo-analyze` can propose the corrected locator.
+
+## Notes
+
+- razo runs inside Playwright's Node workers only (not component-testing browser context).
+- Loading the CJS entry in your config and the ESM entry in specs is safe: events travel as Playwright attachments, so there is no shared module state.
+
+## License
+
+MIT

package/dist/chunk-UCLP2ILU.mjs

@@ -0,0 +1,20 @@
+// src/reporting/events.ts
+import { test } from "@playwright/test";
+function stripAnsi(text) {
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+var AI_STEP_ATTACHMENT = "ai-step";
+function emitStepEvent(event) {
+  test.info().attachments.push({
+    name: AI_STEP_ATTACHMENT,
+    contentType: "application/json",
+    body: Buffer.from(JSON.stringify(event))
+  });
+}
+
+export {
+  stripAnsi,
+  AI_STEP_ATTACHMENT,
+  emitStepEvent
+};
+//# sourceMappingURL=chunk-UCLP2ILU.mjs.map

package/dist/chunk-UCLP2ILU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/reporting/events.ts"],"sourcesContent":["import { test } from '@playwright/test';\n\n/**\n * Structured event that accompanies every narrated sentence.\n * This is the artifact an AI analyzer consumes: one entry per action\n * or assertion, with status and business context.\n */\nexport interface StepEvent {\n  /** Grammar verb: 'click', 'fill', 'assert-text', ... */\n  action: string;\n  /** Control type: 'button', 'input', 'select', ... */\n  controlType: string;\n  /** Human-readable control name (\"Export\", \"Filename\") */\n  name: string;\n  /** The sentence exactly as it appears in the Playwright report */\n  sentence: string;\n  /** Action payload (typed text, chosen option) */\n  detail?: string;\n  /** Assertions only: what was expected */\n  expected?: string;\n  /** Failed assertions only: what was actually found */\n  actual?: string;\n  /** Stable selector of the control */\n  selector: string;\n  status: 'passed' | 'failed';\n  /** Error message when status === 'failed' */\n  error?: string;\n  /** Set when the primary locator stopped resolving and a fallback found the element. */\n  healed?: { from: string; to: string };\n  /** Failed locator-not-found steps: same-role elements on the page, for the analyzer. */\n  domCandidates?: string[];\n  timestamp: string;\n}\n\n/** Artifacts are meant for an AI, not a terminal: no ANSI codes. */\nexport function stripAnsi(text: string): string {\n  // eslint-disable-next-line no-control-regex\n  return text.replace(/\\x1b\\[[0-9;]*m/g, '');\n}\n\n/** Attachment name under which events travel to the reporter. */\nexport const AI_STEP_ATTACHMENT = 'ai-step';\n\n/**\n * Emits a StepEvent as an attachment of the running test. Attachments\n * cross the worker → reporter boundary, so AiReporter can collect them\n * in onTestEnd without shared state.\n */\nexport function emitStepEvent(event: StepEvent): void {\n  test.info().attachments.push({\n    name: AI_STEP_ATTACHMENT,\n    contentType: 'application/json',\n    body: Buffer.from(JSON.stringify(event)),\n  });\n}\n"],"mappings":";AAAA,SAAS,YAAY;AAmCd,SAAS,UAAU,MAAsB;AAE9C,SAAO,KAAK,QAAQ,mBAAmB,EAAE;AAC3C;AAGO,IAAM,qBAAqB;AAO3B,SAAS,cAAc,OAAwB;AACpD,OAAK,KAAK,EAAE,YAAY,KAAK;AAAA,IAC3B,MAAM;AAAA,IACN,aAAa;AAAA,IACb,MAAM,OAAO,KAAK,KAAK,UAAU,KAAK,CAAC;AAAA,EACzC,CAAC;AACH;","names":[]}

package/dist/events-D_lCLx1V.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Structured event that accompanies every narrated sentence.
+ * This is the artifact an AI analyzer consumes: one entry per action
+ * or assertion, with status and business context.
+ */
+interface StepEvent {
+    /** Grammar verb: 'click', 'fill', 'assert-text', ... */
+    action: string;
+    /** Control type: 'button', 'input', 'select', ... */
+    controlType: string;
+    /** Human-readable control name ("Export", "Filename") */
+    name: string;
+    /** The sentence exactly as it appears in the Playwright report */
+    sentence: string;
+    /** Action payload (typed text, chosen option) */
+    detail?: string;
+    /** Assertions only: what was expected */
+    expected?: string;
+    /** Failed assertions only: what was actually found */
+    actual?: string;
+    /** Stable selector of the control */
+    selector: string;
+    status: 'passed' | 'failed';
+    /** Error message when status === 'failed' */
+    error?: string;
+    /** Set when the primary locator stopped resolving and a fallback found the element. */
+    healed?: {
+        from: string;
+        to: string;
+    };
+    /** Failed locator-not-found steps: same-role elements on the page, for the analyzer. */
+    domCandidates?: string[];
+    timestamp: string;
+}
+/** Attachment name under which events travel to the reporter. */
+declare const AI_STEP_ATTACHMENT = "ai-step";
+/**
+ * Emits a StepEvent as an attachment of the running test. Attachments
+ * cross the worker → reporter boundary, so AiReporter can collect them
+ * in onTestEnd without shared state.
+ */
+declare function emitStepEvent(event: StepEvent): void;
+
+export { AI_STEP_ATTACHMENT as A, type StepEvent as S, emitStepEvent as e };

package/dist/events-D_lCLx1V.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Structured event that accompanies every narrated sentence.
+ * This is the artifact an AI analyzer consumes: one entry per action
+ * or assertion, with status and business context.
+ */
+interface StepEvent {
+    /** Grammar verb: 'click', 'fill', 'assert-text', ... */
+    action: string;
+    /** Control type: 'button', 'input', 'select', ... */
+    controlType: string;
+    /** Human-readable control name ("Export", "Filename") */
+    name: string;
+    /** The sentence exactly as it appears in the Playwright report */
+    sentence: string;
+    /** Action payload (typed text, chosen option) */
+    detail?: string;
+    /** Assertions only: what was expected */
+    expected?: string;
+    /** Failed assertions only: what was actually found */
+    actual?: string;
+    /** Stable selector of the control */
+    selector: string;
+    status: 'passed' | 'failed';
+    /** Error message when status === 'failed' */
+    error?: string;
+    /** Set when the primary locator stopped resolving and a fallback found the element. */
+    healed?: {
+        from: string;
+        to: string;
+    };
+    /** Failed locator-not-found steps: same-role elements on the page, for the analyzer. */
+    domCandidates?: string[];
+    timestamp: string;
+}
+/** Attachment name under which events travel to the reporter. */
+declare const AI_STEP_ATTACHMENT = "ai-step";
+/**
+ * Emits a StepEvent as an attachment of the running test. Attachments
+ * cross the worker → reporter boundary, so AiReporter can collect them
+ * in onTestEnd without shared state.
+ */
+declare function emitStepEvent(event: StepEvent): void;
+
+export { AI_STEP_ATTACHMENT as A, type StepEvent as S, emitStepEvent as e };

package/dist/index.d.mts

@@ -0,0 +1,336 @@
+import { Page, Locator } from '@playwright/test';
+export { A as AI_STEP_ATTACHMENT, S as StepEvent, e as emitStepEvent } from './events-D_lCLx1V.mjs';
+
+interface SentenceContext {
+    controlType: string;
+    name: string;
+    detail?: string;
+    expected?: string;
+}
+/**
+ * Sentence grammar: one fixed template per verb, in a single place,
+ * so the narration is predictable and parseable by an AI.
+ */
+declare const SENTENCES: {
+    readonly click: (c: SentenceContext) => string;
+    readonly fill: (c: SentenceContext) => string;
+    readonly clear: (c: SentenceContext) => string;
+    readonly select: (c: SentenceContext) => string;
+    readonly check: (c: SentenceContext) => string;
+    readonly uncheck: (c: SentenceContext) => string;
+    readonly choose: (c: SentenceContext) => string;
+    readonly 'choose-many': (c: SentenceContext) => string;
+    readonly open: (c: SentenceContext) => string;
+    readonly attach: (c: SentenceContext) => string;
+    readonly set: (c: SentenceContext) => string;
+    readonly 'assert-visible': (c: SentenceContext) => string;
+    readonly 'assert-enabled': (c: SentenceContext) => string;
+    readonly 'assert-disabled': (c: SentenceContext) => string;
+    readonly 'assert-text': (c: SentenceContext) => string;
+    readonly 'assert-checked': (c: SentenceContext) => string;
+    readonly 'assert-unchecked': (c: SentenceContext) => string;
+    readonly 'assert-selected': (c: SentenceContext) => string;
+    readonly 'assert-value': (c: SentenceContext) => string;
+    readonly 'assert-href': (c: SentenceContext) => string;
+    readonly hover: (c: SentenceContext) => string;
+    readonly 'double-click': (c: SentenceContext) => string;
+    readonly 'right-click': (c: SentenceContext) => string;
+    readonly press: (c: SentenceContext) => string;
+    readonly focus: (c: SentenceContext) => string;
+    readonly 'scroll-to': (c: SentenceContext) => string;
+    readonly drag: (c: SentenceContext) => string;
+    readonly 'assert-hidden': (c: SentenceContext) => string;
+    readonly 'assert-focused': (c: SentenceContext) => string;
+    readonly 'assert-contains-text': (c: SentenceContext) => string;
+    readonly 'assert-attribute': (c: SentenceContext) => string;
+    readonly 'assert-empty': (c: SentenceContext) => string;
+    readonly 'turn-on': (c: SentenceContext) => string;
+    readonly 'turn-off': (c: SentenceContext) => string;
+    readonly 'assert-on': (c: SentenceContext) => string;
+    readonly 'assert-off': (c: SentenceContext) => string;
+    readonly pick: (c: SentenceContext) => string;
+    readonly 'assert-row-count': (c: SentenceContext) => string;
+    readonly 'assert-row-contains': (c: SentenceContext) => string;
+    readonly close: (c: SentenceContext) => string;
+    readonly 'assert-open': (c: SentenceContext) => string;
+    readonly 'assert-closed': (c: SentenceContext) => string;
+    readonly 'open-tab': (c: SentenceContext) => string;
+    readonly 'assert-active-tab': (c: SentenceContext) => string;
+    readonly 'assert-alt': (c: SentenceContext) => string;
+    readonly 'assert-loaded': (c: SentenceContext) => string;
+    readonly 'pick-date': (c: SentenceContext) => string;
+    readonly 'assert-count': (c: SentenceContext) => string;
+    readonly 'assert-tooltip': (c: SentenceContext) => string;
+};
+type StepAction = keyof typeof SENTENCES;
+interface StepOptions {
+    /** Action payload (typed text, chosen option) */
+    detail?: string;
+    /** Assertions only: expected value */
+    expected?: string;
+    /** On assertion failure: how to read the value actually found */
+    readActual?: () => Promise<string>;
+    /** Sentence override for business-level narration ("Confirm the export") */
+    as?: string;
+}
+interface ControlOptions {
+    /** Scope the control inside another one (e.g. a button within a dialog). */
+    within?: Control;
+    /**
+     * Deterministic healing alternatives, tried in order when the primary
+     * locator stops resolving. After these, the implicit `role + name`
+     * fallback derived from the control type is tried. See RAZO_HEALING.
+     */
+    fallbacks?: LocatorSpec[];
+}
+type AriaRole = Parameters<Page['getByRole']>[0];
+/**
+ * How to find a control. A plain string means data-testid (the recommended,
+ * stable path — see the auto-testid Vite plugin); the object forms map 1:1
+ * to Playwright's user-facing locators, so razo works on apps that were
+ * never instrumented. `{ locator }` is the full escape hatch.
+ */
+type LocatorSpec = string | {
+    testId: string;
+} | {
+    role: AriaRole;
+    name?: string;
+    exact?: boolean;
+} | {
+    label: string;
+    exact?: boolean;
+} | {
+    placeholder: string;
+} | {
+    text: string;
+    exact?: boolean;
+} | {
+    altText: string;
+} | {
+    title: string;
+} | {
+    css: string;
+} | {
+    locator: Locator;
+};
+declare abstract class Control {
+    readonly page: Page;
+    readonly name: string;
+    protected abstract readonly controlType: string;
+    /** @deprecated Only set when the control was located by testid; use `selector`. */
+    readonly testId: string;
+    private _locator;
+    private _selector;
+    private readonly parent?;
+    private readonly fallbacks;
+    /**
+     * Root that fallbacks resolve against — read lazily so a child control
+     * follows its `within` parent even after the PARENT healed.
+     */
+    private get healRoot();
+    private get withinPrefix();
+    /** The Playwright locator currently backing this control. */
+    get locator(): Locator;
+    /** Readable selector, chained through `within` parents; travels in every StepEvent. */
+    get selector(): string;
+    constructor(page: Page, locate: LocatorSpec, name: string, options?: ControlOptions);
+    /**
+     * Core of the framework: runs `fn` inside a test.step titled with the
+     * grammar sentence, and emits the matching structured StepEvent —
+     * also (especially) when it fails.
+     */
+    protected step<T>(action: StepAction, options: StepOptions, fn: () => Promise<T>): Promise<T>;
+    /** True when the primary locator currently matches nothing (safe: never throws). */
+    private primaryGone;
+    /** First fallback (explicit, then implicit role+name) resolving to exactly one element. */
+    private findHealingSpec;
+    /**
+     * Same-role elements on the page, as evidence for the analyzer to propose
+     * a replacement locator. Best-effort: capped, time-boxed, never throws.
+     */
+    private collectDomCandidates;
+    expectVisible(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectEnabled(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectDisabled(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectText(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** The control as it appears in the narration: `button "Export"`. */
+    describe(): string;
+    hover(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    doubleClick(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    rightClick(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    press(key: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    focus(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    scrollTo(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    dragTo(target: Control, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectHidden(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectFocused(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectContainsText(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectAttribute(attribute: string, expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** For repeated testids (list items): how many elements the control matches. */
+    expectCount(expected: number, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Button extends Control {
+    protected readonly controlType = "button";
+    click(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Input extends Control {
+    protected readonly controlType: string;
+    /** For a field, "text" means its value, not its DOM content. */
+    expectText(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    fill(value: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    clear(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectEmpty(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Radio group: the testId points at the group container. */
+declare class RadioButton extends Control {
+    protected readonly controlType = "radio group";
+    select(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectSelected(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Checkbox extends Control {
+    protected readonly controlType = "checkbox";
+    private readActualState;
+    expectChecked(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectUnchecked(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    check(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    uncheck(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Select extends Control {
+    protected readonly controlType = "select";
+    /** Chooses an option by its visible label. */
+    choose(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** Chooses several options by label (for <select multiple>). */
+    chooseMany(optionLabels: string[], options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Link extends Control {
+    protected readonly controlType = "link";
+    open(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectHref(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * Read-only element (status messages, headings). It has no actions:
+ * it exists so outcome verifications are narrated too.
+ */
+declare class Label extends Control {
+    protected readonly controlType = "label";
+}
+
+declare class FileInput extends Control {
+    protected readonly controlType = "file input";
+    /** Attaches one or more files by path. The narration shows the file names. */
+    attach(files: string | string[], options?: Pick<StepOptions, 'as'>): Promise<void>;
+    clear(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** Asserts the name of the file currently selected. */
+    expectFile(expectedName: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Slider extends Control {
+    protected readonly controlType = "slider";
+    /**
+     * Sets the slider value. Range inputs cannot be filled, so the value is
+     * set in the DOM and the input/change events the app listens to are fired.
+     */
+    setValue(value: number | string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectValue(expected: number | string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Same behavior as Input; only the narration names it differently. */
+declare class TextArea extends Input {
+    protected readonly controlType = "text area";
+}
+
+/** ARIA switch (role="switch" with aria-checked). Actions are idempotent. */
+declare class Switch extends Control {
+    protected readonly controlType = "switch";
+    private readState;
+    turnOn(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    turnOff(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectOn(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectOff(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * ARIA combobox: the testId points at the text input; options are looked up
+ * by role anywhere on the page (comboboxes often render their listbox in a
+ * portal outside the input's subtree).
+ */
+declare class Combobox extends Control {
+    protected readonly controlType = "combobox";
+    search(text: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    pick(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectSelected(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Read-only table assertions over tbody rows. */
+declare class Table extends Control {
+    protected readonly controlType = "table";
+    private rows;
+    expectRowCount(expected: number, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectRowContains(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Native <dialog> or role="dialog". close() sends Escape. */
+declare class Dialog extends Control {
+    protected readonly controlType = "dialog";
+    private readState;
+    close(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectOpen(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectClosed(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** ARIA tablist: the testId points at the tablist container. */
+declare class Tabs extends Control {
+    protected readonly controlType = "tabs";
+    open(tab: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectActive(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Image extends Control {
+    protected readonly controlType = "image";
+    expectAlt(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectLoaded(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Native input[type="date"]; dates travel in ISO format (YYYY-MM-DD). */
+declare class DatePicker extends Control {
+    protected readonly controlType = "date picker";
+    pick(isoDate: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectDate(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * Dropdown menu: the testId points at the trigger button; menu items are
+ * looked up by role anywhere on the page (menus often render in portals).
+ */
+declare class Menu extends Control {
+    protected readonly controlType = "menu";
+    choose(item: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * Tooltip: the testId points at the TRIGGER element. The tooltip content is
+ * resolved through the trigger's aria-describedby (the accessible pattern),
+ * so it works wherever the tooltip node is rendered.
+ */
+declare class Tooltip extends Control {
+    protected readonly controlType = "tooltip";
+    private tooltipText;
+    /** Hovers the trigger and asserts the tooltip content. */
+    expectContent(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** contenteditable region. Inherits expectText/expectContainsText from the base. */
+declare class Editor extends Control {
+    protected readonly controlType = "editor";
+    write(text: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    clear(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+export { Button, Checkbox, Combobox, Control, type ControlOptions, DatePicker, Dialog, Editor, FileInput, Image, Input, Label, Link, type LocatorSpec, Menu, RadioButton, Select, Slider, type StepAction, type StepOptions, Switch, Table, Tabs, TextArea, Tooltip };