@saywright/vite 0.0.0-stage → 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,667 @@
+/**
+ * Message protocol between the Saywright studio (parent window) and the
+ * bridge running inside the target app (iframe). Both sides check `ns` and the
+ * message source before trusting anything.
+ */
+export declare const NS: 'saywright';
+/**
+ * The plugin in an app and the studio are updated separately, so each side
+ * says which version of this protocol it speaks (`v`, in hello and ready) and
+ * the oldest of the other side's it still works with (`oldest`). Raise
+ * PROTOCOL_VERSION when a message changes in a way an older side can't follow,
+ * and OLDEST_PROTOCOL when this side stops understanding an older one; adding
+ * a message or an optional field needs neither (unknown ones are ignored).
+ */
+export declare const PROTOCOL_VERSION = 1;
+export declare const OLDEST_PROTOCOL = 1;
+/** Which side has to be updated for a studio and an app's bridge to work together: the app's plugin, the studio, or neither. */
+export declare function outdated(studio: {
+    v: number;
+    oldest?: number;
+}, bridge: {
+    v: number;
+    oldest?: number;
+}): 'plugin' | 'studio' | null;
+/** Where the studio runs unless told otherwise. Not 5173: that is Vite's own default, where your app likely runs. */
+export declare const STUDIO_PORT = 7357;
+export declare const STUDIO_URL = "http://localhost:7357";
+/** Attribute names injected by the Vite plugin at compile time. */
+export declare const SRC_ATTR = "data-ds-src";
+export declare const NAME_ATTR = "data-ds-name";
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** What the studio needs to know about an element in the app. Coordinates are iframe viewport CSS px. */
+export interface ElementInfo {
+    /** Runtime id, stable while the DOM node stays connected. */
+    id: number;
+    /** "src/components/CouponField.tsx:18:9" relative to the app root, or null for unannotated nodes. */
+    src: string | null;
+    /** Component name for component instances ("Button"), otherwise the tag ("div"). */
+    name: string;
+    tag: string;
+    /** Short human label, e.g. "Button · Apply". */
+    label: string;
+    /** Visible text, whitespace-collapsed, at most 80 characters. */
+    text: string;
+    role: string | null;
+    rect: Rect;
+    /** Index of this node among elements sharing the same `src` (lists render one JSX site many times). */
+    index: number;
+    /** When `src` is null: what can find the element in the code. */
+    hint?: SourceHint;
+    /** Pages without source attributes: where React's development build says it came from (see SourceFrame). */
+    frames?: SourceFrame[];
+}
+/**
+ * A place React's development build gives for an element: its own JSX first, then where each component around it
+ * was used. The studio's server maps them to source, skipping those in libraries.
+ */
+export interface SourceFrame {
+    /** As the page reports it: a file, or a module or bundle address and position to map ("http://…/chunk.js:3:120"). */
+    at: string;
+    /** What is written there: the element's tag for its own JSX, else the component ("Button"). */
+    name?: string;
+    /** React 19.0 says where a component is, not where its JSX is: `at` is a place inside the component that wrote `name`. */
+    inside?: boolean;
+    /** The element is this component's outermost element and gets the props set where it is used: an instance site. */
+    root?: boolean;
+}
+/** What identifies an element in its code, for pages that don't say where it was written. */
+export interface SourceHint {
+    /** Telling attributes as the page has them: id, data-testid, name, aria-label, href, the first classes… */
+    attrs: Record<string, string>;
+    /** The component file a framework's development build names (Vue), absolute or relative to the app. */
+    file?: string;
+}
+export interface LocatorInfo {
+    /** Playwright locator expression, e.g. `page.getByTestId('summary-total')`. */
+    code: string;
+    /** Plain words for the recorder list, e.g. `the "Apply" button`. */
+    description: string;
+    /** Current visible text of the element. */
+    text: string;
+    /** The title of the card or row that tells it apart from others like it ("Celadon mug, 12 oz"). */
+    within?: string;
+}
+export type RecordedAction = {
+    kind: 'click';
+    locator: string;
+    description: string;
+} | {
+    kind: 'fill';
+    locator: string;
+    value: string;
+    description: string;
+} | {
+    kind: 'press';
+    locator: string;
+    key: string;
+    description: string;
+};
+/** An element as a test session remembers it. Cheap fields are read at once; `locator`, `description` and `path` when the browser is idle. */
+export interface SessionTarget {
+    /** "src/components/CouponField.tsx:18:9", from the Vite plugin or React's dev info; null when unknown. */
+    src: string | null;
+    /** Component name ("Button") or tag ("div"). */
+    name: string;
+    tag: string;
+    role: string | null;
+    /** What a person would call it: its label, placeholder or text (≤ 60 characters). */
+    label: string;
+    /** Visible text (≤ 80 characters). */
+    text: string;
+    testId?: string;
+    /** Playwright locator, e.g. page.getByRole('button', { name: 'Apply' }). */
+    locator?: string;
+    /** Plain words, e.g. the “Apply” button. */
+    description?: string;
+    /** The title of the card or row that tells it apart from others like it ("Celadon mug, 12 oz"). */
+    within?: string;
+    /** When the locator goes by the element's place in the code (sessions recorded before locators stopped doing so): what it is made of (see shapeOf), to find it again once that place moves. */
+    shape?: string;
+    /** React components from the page down to this element, e.g. "Checkout › CouponField › Button". */
+    path?: string;
+    /** Viewport box: x, y, width, height (CSS px). */
+    rect: [number, number, number, number];
+    /** A link inside running text (exempt from minimum target sizes). */
+    inline?: boolean;
+    /** When `src` is null: what can find it in the code. */
+    hint?: SourceHint;
+}
+/**
+ * Everything a test session records about the app, one event at a time. `t` is
+ * wall-clock time in ms (Date.now() scale) so events from the app, the studio
+ * and the microphone line up; `seq` counts events within one page load (`page`).
+ */
+export type SessionEventBody = {
+    type: 'page';
+    url: string;
+    title: string;
+    referrer: string;
+    viewport: [number, number, number];
+    ua: string;
+    lang: string;
+    reload: boolean;
+    timing?: {
+        ttfb: number;
+        dcl: number;
+        load: number;
+    };
+}
+/** `disabled`: the press landed on a disabled control, which ignores it. */
+ | {
+    type: 'click';
+    x: number;
+    y: number;
+    button: number;
+    pointer: string;
+    el: SessionTarget;
+    count: number;
+    disabled?: boolean;
+} | {
+    type: 'input';
+    el: SessionTarget;
+    value: string;
+    masked: boolean;
+} | {
+    type: 'change';
+    el: SessionTarget;
+    value: string;
+    checked?: boolean;
+} | {
+    type: 'submit';
+    el: SessionTarget;
+} | {
+    type: 'key';
+    key: string;
+    mods: string;
+    el: SessionTarget | null;
+} | {
+    type: 'focus';
+    el: SessionTarget;
+} | {
+    type: 'nav';
+    url: string;
+    title: string;
+    how: 'push' | 'replace' | 'pop' | 'hash';
+} | {
+    type: 'scroll';
+    x: number;
+    y: number;
+    maxY: number;
+    el: SessionTarget | null;
+} | {
+    type: 'resize';
+    w: number;
+    h: number;
+}
+/** The pointer rested on an element for `ms`. */
+ | {
+    type: 'hover';
+    el: SessionTarget;
+    ms: number;
+}
+/** Pointer positions sampled ten times a second: [dt ms, x, y, dt, x, y, …] after `t`. */
+ | {
+    type: 'trail';
+    pts: number[];
+}
+/** `repeat`: the event stands for itself and this many more of the same message within a second (a burst after its first one). */
+ | {
+    type: 'error';
+    kind: 'error' | 'rejection' | 'resource';
+    message: string;
+    stack?: string;
+    source?: string;
+    repeat?: number;
+} | {
+    type: 'console';
+    level: 'error' | 'warn';
+    text: string;
+    stack?: string;
+    repeat?: number;
+}
+/**
+ * `ctype`: the response's content type (a data request answered with a web page is usually a missing route). `stack`: where the request was made, when it went wrong.
+ * `repeat`: the event stands for itself and this many more quick, successful requests to the same address, with the same status, within a
+ * second of one recorded on its own; `ms` is their average.
+ */
+ | {
+    type: 'net';
+    via: 'fetch' | 'xhr';
+    method: string;
+    url: string;
+    status: number;
+    ok: boolean;
+    ms: number;
+    size?: number;
+    error?: string;
+    body?: string;
+    ctype?: string;
+    stack?: string;
+    repeat?: number;
+} | {
+    type: 'perf';
+    metric: 'lcp' | 'cls' | 'inp' | 'longtask' | 'fcp';
+    value: number;
+    el?: SessionTarget | null;
+    detail?: string;
+}
+/** Several fast clicks on the same spot: the user expected something to happen. */
+ | {
+    type: 'rage';
+    x: number;
+    y: number;
+    clicks: number;
+    el: SessionTarget;
+}
+/** A click that changed nothing: no DOM change, navigation, request or focus within a second. */
+ | {
+    type: 'dead';
+    x: number;
+    y: number;
+    el: SessionTarget;
+} | {
+    type: 'vis';
+    hidden: boolean;
+}
+/**
+ * What the screen said at a key moment (start, reload, navigation, error, mark), and once it settled after an action
+ * when it changed (after): the main region's text and the dialogs and messages outside it, line by line.
+ */
+ | {
+    type: 'dom';
+    reason: string;
+    url: string;
+    title: string;
+    headings: string[];
+    text: string;
+} | {
+    type: 'mark';
+    note: string;
+    via: string;
+}
+/** Events the page couldn't keep while the studio wasn't taking them (it holds a few thousand): how many, by type. */
+ | {
+    type: 'dropped';
+    count: number;
+    kinds: Record<string, number>;
+}
+/** Studio only: what the user pointed at with a hand or the mouse, and for how long. */
+ | {
+    type: 'point';
+    el: SessionTarget;
+    ms: number;
+    via: 'hand' | 'mouse';
+}
+/** Studio only: a voice or typed command, and what came of it. */
+ | {
+    type: 'command';
+    text: string;
+    input: 'voice' | 'typed';
+    result: string;
+}
+/** Studio only: a step Autopilot took (`did`), and why. */
+ | {
+    type: 'autopilot';
+    did: string;
+    why: string;
+}
+/** Studio only: a problem Autopilot saw, with what it expected. */
+ | {
+    type: 'observed';
+    severity: 'high' | 'medium' | 'low';
+    title: string;
+    expected: string;
+    actual: string;
+    el: SessionTarget | null;
+};
+export type SessionEvent = SessionEventBody & {
+    seq: number;
+    t: number;
+};
+/** What the bridge posts to the studio server: events from one page load, in order. */
+export interface SessionBatch {
+    page: string;
+    events: SessionEvent[];
+}
+interface Base {
+    ns: typeof NS;
+}
+export type StudioToBridge = Base & ({
+    type: 'hello';
+    v: number;
+    oldest?: number;
+}
+/** Sent every animation frame while pointing. `track` lists ids whose rects should be reported. */
+ | {
+    type: 'probe';
+    seq: number;
+    x: number | null;
+    y: number | null;
+    radius: number;
+    deep: boolean;
+    track: number[];
+    sticky?: boolean;
+} | {
+    type: 'describe';
+    reqId: number;
+    id: number;
+} | {
+    type: 'locator';
+    reqId: number;
+    id: number;
+}
+/** Move from an element: out, in, to the next or previous one; or to the nearest one called `what` ("card"). `id` 0: from nothing. */
+ | {
+    type: 'step';
+    reqId: number;
+    id: number;
+    to: 'parent' | 'child' | 'next' | 'prev';
+} | {
+    type: 'find';
+    reqId: number;
+    id: number;
+    what: string;
+    where: 'any' | 'out' | 'in';
+} | {
+    type: 'resolve';
+    reqId: number;
+    src: string;
+    index: number;
+}
+/**
+ * Replaying a session: find the element a recorded Playwright locator points at, bring it into view, and do
+ * `step` on it (or nothing, just to show where it is). `read`: also answer with what it shows.
+ */
+ | {
+    type: 'replay';
+    reqId: number;
+    locator: string;
+    step?: {
+        kind: 'click' | 'fill' | 'press';
+        value?: string;
+        key?: string;
+        checked?: boolean;
+    };
+    read?: boolean;
+    like?: {
+        tag: string;
+        name: string;
+        text: string;
+        shape?: string;
+    };
+}
+/** Open another page of the app (same origin only), to replay a session from where it started. */
+ | {
+    type: 'goto';
+    url: string;
+} | {
+    type: 'click';
+    reqId: number;
+    x: number;
+    y: number;
+} | {
+    type: 'type';
+    reqId: number;
+    text: string;
+    submit: boolean;
+} | {
+    type: 'scroll';
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+} | {
+    type: 'record';
+    on: boolean;
+}
+/** Report the real mouse position while the user interacts with the app directly (Use / Record modes). */
+ | {
+    type: 'mouse';
+    on: boolean;
+}
+/** Forward the studio's talk and cancel keys (Space outside text fields, Escape) while the app has focus. */
+ | {
+    type: 'keys';
+    on: boolean;
+}
+/** Start or stop recording a test session; events go straight to `endpoint` (the studio server). */
+ | {
+    type: 'session';
+    on: boolean;
+    id?: string;
+    endpoint?: string;
+    key?: string;
+} | {
+    type: 'mark';
+    note: string;
+    via: string;
+}
+/** Check the page for the experts asked (SEO, content, UX, accessibility); `axe`: where to load axe-core from. */
+ | {
+    type: 'review';
+    reqId: number;
+    experts: ExpertId[];
+    axe?: string;
+}
+/** Bring an element into view (by id, or by where it was written when the page has changed) and describe it. */
+ | {
+    type: 'reveal';
+    reqId: number;
+    id: number;
+    src: string | null;
+    index: number;
+}
+/** Autopilot: what the page shows and what can be done on it. */
+ | {
+    type: 'explore';
+    reqId: number;
+});
+export type BridgeToStudio = Base & ({
+    type: 'ready';
+    v: number;
+    oldest?: number;
+    url: string;
+    title: string;
+} | {
+    type: 'probe';
+    seq: number;
+    hit: ElementInfo | null;
+    snapped: boolean;
+    tracked: Record<string, Rect | null>;
+} | {
+    type: 'reply';
+    reqId: number;
+    ok: boolean;
+    info?: ElementInfo | null;
+    locator?: LocatorInfo | null;
+    /** What an element shows (replay, with `read`). */
+    text?: string;
+    /** A page review's results. */
+    review?: PageReview;
+    /** What Autopilot sees of the page. */
+    snapshot?: PageSnapshot;
+    error?: string;
+} | {
+    type: 'recorded';
+    action: RecordedAction;
+}
+/** How far a long request (a page review) has got, from 0 to 1. */
+ | {
+    type: 'progress';
+    reqId: number;
+    done: number;
+} | {
+    type: 'navigated';
+    url: string;
+    title: string;
+} | {
+    type: 'mouse';
+    x: number | null;
+    y: number | null;
+} | {
+    type: 'key';
+    key: 'Space' | 'Escape' | 'Mark';
+    down: boolean;
+}
+/** The session recorder's state, so the studio can show it (a session can resume after a reload). */
+ | {
+    type: 'session';
+    id: string | null;
+    events: number;
+    issues: number;
+}
+/** Something worth a screenshot just happened in the app (navigation, an error, a click…). */
+ | {
+    type: 'moment';
+    reason: string;
+});
+/** What Autopilot sees of a page: where it is, what it says, and what can be done on it. */
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    headings: string[];
+    /** The visible text, shortened. */
+    text: string;
+    /** What can be clicked, filled or chosen: what is on screen first, then the rest in reading order. */
+    controls: PageControl[];
+    /** How many more there were than are listed. */
+    more: number;
+    /** An open dialog's name: only what is in it can be used until it closes. */
+    dialog: string | null;
+    /** The page's visible size, CSS px. */
+    viewport: [number, number];
+    /** The control that has the keyboard focus (its index in `controls`), where a key press goes. */
+    focused?: number | null;
+}
+export interface PageControl {
+    /** The Playwright locator that finds it again, as the recorder writes it. */
+    locator: string;
+    role: string;
+    /** What a person would call it: its label or its text. */
+    name: string;
+    /** A field: its type, what it holds now (never a password's value), whether it must be filled, its choices. */
+    field?: {
+        type: string;
+        value: string;
+        required: boolean;
+        checked?: boolean;
+        options?: string[];
+    };
+    disabled: boolean;
+    /** Outside what the page shows now: reached by scrolling. */
+    offscreen: boolean;
+    /** Where it was written ("src/components/Cart.tsx:18:9"), when known. */
+    src: string | null;
+}
+export type ExpertId = 'seo' | 'content' | 'ux' | 'a11y';
+export type CheckSeverity = 'blocker' | 'high' | 'medium' | 'low' | 'info';
+/** Something a page check found, with the elements it is about. */
+export interface PageCheck {
+    /** The rule: "SEO-16", "CNT-06", "UX-01", "axe:color-contrast". */
+    rule: string;
+    expert: ExpertId;
+    severity: CheckSeverity;
+    title: string;
+    /** What was found, in words, with the numbers. */
+    what: string;
+    /** How to fix it. */
+    fix: string;
+    /** Up to six of the elements it is about. */
+    els?: ElementInfo[];
+    /** Their HTML, shortened. */
+    html?: string[];
+    /** How many there are in all (the elements are a sample). */
+    count?: number;
+    /** WCAG success criteria ("1.4.3"). */
+    wcag?: string[];
+    /** Where the rule comes from. */
+    source?: string;
+}
+/** What a page is, for the experts and the AI: its metadata, structure and text. */
+export interface PageFacts {
+    url: string;
+    title: string;
+    description: string | null;
+    canonical: string | null;
+    robots: string | null;
+    lang: string | null;
+    dir: string | null;
+    viewport: string | null;
+    headings: {
+        level: number;
+        text: string;
+    }[];
+    og: Record<string, string>;
+    jsonLd: string[];
+    words: number;
+    /** The main text, shortened. */
+    text: string;
+    links: {
+        internal: number;
+        external: number;
+    };
+    images: number;
+    forms: {
+        label: string;
+        type: string;
+        autocomplete: string | null;
+        required: boolean;
+    }[];
+    buttons: string[];
+    /** Measured in this browser (lab, not field data). */
+    lcp: number | null;
+    cls: number | null;
+    readability: {
+        lang: 'en' | 'ar';
+        ease: number | null;
+        grade: number | null;
+        sentence: number;
+    } | null;
+    /** The elements that matter most for a review: main headings, the first buttons and links in view, form fields. */
+    elements: ElementInfo[];
+    /** Landmarks as a screen reader lists them (banner, navigation, main…), with their names. */
+    landmarks?: {
+        role: string;
+        name: string;
+    }[];
+    /** Where changes are announced (role="status", "alert", aria-live…) and what each says now. */
+    live?: {
+        role: string;
+        text: string;
+    }[];
+    /** Where the links go, as written in the page (a #/route stays one). */
+    linkTargets?: {
+        text: string;
+        href: string;
+    }[];
+}
+export interface PageReview {
+    facts: PageFacts;
+    checks: PageCheck[];
+    ms: number;
+}
+export declare function isStudioMessage(data: unknown): data is {
+    ns: typeof NS;
+    type: string;
+};
+/**
+ * Text from a page as a single-quoted JavaScript string, for the locators and
+ * tests Saywright writes: quotes, backslashes and every kind of line break are
+ * escaped, so no text can end the string or the line it is on.
+ */
+export declare function jsString(s: string): string;
+/** Text from a page in a `//` comment: on one line, whatever line breaks it had. */
+export declare function jsComment(s: string): string;
+/** Parse "path/to/File.tsx:12:5" into parts. Paths may contain colons on Windows drive letters, so split from the right. */
+export declare function parseSrc(src: string): {
+    file: string;
+    line: number;
+    col: number;
+} | null;
+export {};