lynkeus-protocol 0.2.0

package/README.md

@@ -0,0 +1,4 @@
+# lynkeus-protocol
+
+Types and version of the wire contract between an app running
+[lynkeus-agent](../agent) and any driver. See [docs/PROTOCOL.md](../../docs/PROTOCOL.md).

package/lib/index.d.ts

@@ -0,0 +1,352 @@
+/** JSON-RPC-shaped messages over a WebSocket the app opens towards the driver; docs/PROTOCOL.md has the prose. */
+export declare const PROTOCOL_VERSION = 1;
+export type Frame = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type ElementKind = 'button' | 'input' | 'text' | 'scroll' | 'switch' | 'image' | 'view';
+/** Why an element is in the tree but not presented: structural, so a device and a host without layout agree. */
+export type HiddenReason = 
+/** Hidden from assistive technology, so it is not presented to anyone. */
+'a11y'
+/** `pointerEvents: 'none'` on it or an ancestor: no touch can reach it. */
+ | 'inert'
+/** Outside the subtree that declared itself modal. */
+ | 'behind-modal'
+/** Outside the last full-window layer the app mounted at its root. */
+ | 'behind-overlay';
+export type Element = {
+    /** Position in tree order: later elements draw on top of earlier ones. */
+    i: number;
+    kind: ElementKind;
+    frame: Frame;
+    enabled: boolean;
+    depth: number;
+    testId?: string;
+    /** Rendered text for `text` elements, or the label of a button/input. */
+    text?: string;
+    accessibilityLabel?: string;
+    /** Masked (`•`) when the field is a secure entry. */
+    value?: string;
+    placeholder?: string;
+    focused?: boolean;
+    /** Index of the nearest listed ancestor, when there is one. */
+    parent?: number;
+    /** React native tag of the host view. */
+    tag?: number;
+    /** A touch at its centre would not reach it: something is on top. */
+    covered?: boolean;
+    /** Not presented at all, and why. A hidden element is not on screen. */
+    hidden?: HiddenReason;
+    /** Its rect lies outside the window: on screen only after scrolling. */
+    offscreen?: boolean;
+};
+export type Screen = {
+    route?: string;
+    params?: unknown;
+    /** Route names from the root navigator down to the focused screen. */
+    path: string[];
+    elements: Element[];
+    /** React commits since the agent started; a change means the UI re-rendered. */
+    commit: number;
+    /** Requests in flight, plus whatever the app's `busy` command reports. */
+    busy: boolean;
+    window: {
+        w: number;
+        h: number;
+    };
+    /** The layer on top, when the app is presenting one over its screen. */
+    presenting?: {
+        i: number;
+        modal: boolean;
+        testId?: string;
+    };
+    /** Milliseconds spent building this snapshot inside the app. */
+    costMs: number;
+};
+/** Where to look for a target: the element this names, then each container up from it, nearest first. */
+export type Scope = {
+    testId: string;
+} | {
+    text: string;
+};
+export type Target = {
+    testId: string;
+    nth?: number;
+    within?: Scope;
+} | {
+    text: string;
+    nth?: number;
+    within?: Scope;
+} | {
+    i: number;
+} | {
+    x: number;
+    y: number;
+};
+export type PressOptions = {
+    /** Finger-down time; a long press is ~600. Default 50. */
+    holdMs?: number;
+    /** `js` calls the element's onPress directly: no touch, no gesture, no animation wait. Needs a testId and an enabled, uncovered control. */
+    mode?: 'native' | 'js';
+};
+export type SwipeParams = {
+    direction?: 'up' | 'down' | 'left' | 'right';
+    /** Swipe on an element (a slider, a sheet handle) from its centre rather than across the window. */
+    target?: Target;
+    /** How far to move, in points; default 60% of the window's extent that way. */
+    distance?: number;
+    from?: {
+        x: number;
+        y: number;
+    };
+    to?: {
+        x: number;
+        y: number;
+    };
+    durationMs?: number;
+};
+export type WaitForParams = {
+    route?: string;
+    target?: Target;
+    /** Satisfied by whichever of these shows up first. */
+    anyOf?: Target[];
+    gone?: boolean;
+    /** Swipe the nearest scrolling container towards the target until it is in the window. */
+    scroll?: boolean;
+    timeoutMs?: number;
+};
+export type TraceEvent = {
+    seq: number;
+    t: number;
+} & ({
+    kind: 'route';
+    route?: string;
+    path: string[];
+} | {
+    kind: 'request';
+    method: string;
+    url: string;
+    status?: number;
+    ms?: number;
+    error?: string;
+} | {
+    kind: 'store';
+    store: string;
+    changed: Record<string, {
+        from: unknown;
+        to: unknown;
+    }>;
+}
+/** Something the app told its analytics, through `qa.event`. */
+ | {
+    kind: 'event';
+    name: string;
+    props?: Record<string, unknown>;
+    route?: string;
+} | {
+    kind: 'command';
+    method: string;
+    ms: number;
+    error?: string;
+}
+/** The host broke a runaway render loop: `renders` updates in `windowMs`. */
+ | {
+    kind: 'stall';
+    renders: number;
+    windowMs: number;
+    component?: string;
+}
+/** A finger on the screen (device builds mounted with `auto()`), resolved to the element under it. */
+ | {
+    kind: 'touch';
+    x: number;
+    y: number;
+    testId?: string;
+    text?: string;
+    route?: string;
+}
+/** Something threw where nothing caught it, and the screen may be gone. */
+ | {
+    kind: 'crash';
+    message: string;
+    stack?: string;
+    route?: string;
+});
+export type RequestRecord = {
+    id: number;
+    method: string;
+    url: string;
+    status?: number;
+    startedAt: number;
+    ms?: number;
+    error?: string;
+};
+/** Every method the core answers. Apps add their own through `qa.register`. */
+export type CoreMethods = {
+    ping: {
+        params: undefined;
+        result: {
+            pong: true;
+            native: boolean;
+            commands: string[];
+        };
+    };
+    screen: {
+        params: undefined;
+        result: Screen;
+    };
+    find: {
+        params: Target;
+        result: Element | null;
+    };
+    press: {
+        params: Target & PressOptions;
+        result: {
+            x: number;
+            y: number;
+            element?: Element;
+            mode: 'native' | 'js';
+        };
+    };
+    type: {
+        params: {
+            text: string;
+            target?: Target;
+            clear?: boolean;
+            paste?: boolean;
+            submit?: boolean;
+        };
+        result: {
+            typed: string;
+            element?: Element;
+        };
+    };
+    swipe: {
+        params: SwipeParams;
+        result: {
+            from: {
+                x: number;
+                y: number;
+            };
+            to: {
+                x: number;
+                y: number;
+            };
+        };
+    };
+    navigate: {
+        params: {
+            name: string;
+            params?: object;
+        };
+        result: {
+            route: string;
+        };
+    };
+    back: {
+        params: undefined;
+        result: {
+            route?: string;
+        };
+    };
+    waitFor: {
+        params: WaitForParams;
+        result: {
+            route?: string;
+            matched?: Target;
+            waitedMs: number;
+        };
+    };
+    idle: {
+        /** `after`: a commit count from before the awaited change; quiet only counts once the app has committed past it. */
+        params: {
+            quietMs?: number;
+            timeoutMs?: number;
+            after?: number;
+        } | undefined;
+        result: {
+            commit: number;
+            idle: boolean;
+        };
+    };
+    deepLink: {
+        params: {
+            url: string;
+        };
+        result: {
+            opened: string;
+        };
+    };
+    requests: {
+        params: {
+            since?: number;
+        } | undefined;
+        result: {
+            inFlight: number;
+            requests: RequestRecord[];
+        };
+    };
+    trace: {
+        params: {
+            since?: number;
+        } | undefined;
+        result: {
+            last: number;
+            events: TraceEvent[];
+        };
+    };
+    dismissKeyboard: {
+        params: undefined;
+        result: boolean;
+    };
+    /** Several calls in one round trip, in order; stops at the first error. */
+    batch: {
+        params: {
+            calls: {
+                method: string;
+                params?: unknown;
+            }[];
+        };
+        result: {
+            results: unknown[];
+        };
+    };
+};
+export type Request = {
+    id: number;
+    method: string;
+    params?: unknown;
+};
+export type Response = {
+    id: number;
+    result: unknown;
+} | {
+    id: number;
+    error: {
+        message: string;
+        code?: string;
+    };
+};
+export type HelloEvent = {
+    event: 'hello';
+    protocolVersion: number;
+    platform: 'ios' | 'android' | string;
+    native: boolean;
+    commands: string[];
+    route?: string;
+    app?: Record<string, unknown>;
+};
+export type NavigationEvent = {
+    event: 'navigation';
+    route?: string;
+};
+/** The driver's first message. `session` is random per driver process, so the app can tell a reconnect (whose resent requests it may have answered) from a new driver reusing request ids. */
+export type AuthEvent = {
+    event: 'auth';
+    session: string;
+    token?: string;
+};
+export type AgentEvent = HelloEvent | NavigationEvent;

package/lib/index.js

@@ -0,0 +1,2 @@
+/** JSON-RPC-shaped messages over a WebSocket the app opens towards the driver; docs/PROTOCOL.md has the prose. */
+export const PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "lynkeus-protocol",
+  "version": "0.2.0",
+  "description": "Wire contract between an app running lynkeus-agent and whatever drives it.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/__tests__/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonamischener/lynkeus.git",
+    "directory": "packages/protocol"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/jonamischener/lynkeus#readme"
+}

package/src/__tests__/shape.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { PROTOCOL_VERSION } from '../index.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const source = fs.readFileSync(path.join(here, '..', 'index.ts'), 'utf8');
+const frozenFile = path.join(here, '..', '..', 'shape.json');
+const agentProtocol = fs.readFileSync(path.join(here, '..', '..', '..', 'agent', 'src', 'protocol.ts'), 'utf8');
+
+const SHAPES = ['ElementKind', 'HiddenReason', 'Frame', 'Element', 'Screen', 'Scope', 'Target'];
+
+const declaration = (name: string): string => {
+  const start = source.search(new RegExp(`export type ${name}\\b`));
+  assert.notEqual(start, -1, `no export type ${name} in the protocol`);
+  let depth = 0;
+  for (let i = start; i < source.length; i++) {
+    const c = source[i];
+    if (c === '{' || c === '(') depth++;
+    else if (c === '}' || c === ')') depth--;
+    else if (c === ';' && depth === 0) return source.slice(start, i + 1);
+  }
+  return source.slice(start);
+};
+
+const normalized = (text: string) =>
+  text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/.*$/gm, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const hash = createHash('sha1')
+  .update(SHAPES.map((n) => normalized(declaration(n))).join('\n'))
+  .digest('hex');
+const agentVersion = Number(/PROTOCOL_VERSION = (\d+)/.exec(agentProtocol)?.[1]);
+
+test('the protocol shapes change only on purpose', () => {
+  if (process.env.UPDATE_PROTOCOL_SHAPE === '1') fs.writeFileSync(frozenFile, `${JSON.stringify({ version: PROTOCOL_VERSION, hash }, null, 2)}\n`);
+  const frozen = JSON.parse(fs.readFileSync(frozenFile, 'utf8')) as { version: number; hash: string };
+  assert.equal(
+    hash,
+    frozen.hash,
+    `${SHAPES.join(', ')} changed. A change a driver of version ${frozen.version} would misread needs PROTOCOL_VERSION bumped; an optional field it can ignore does not. Either way, record the decision with UPDATE_PROTOCOL_SHAPE=1.`,
+  );
+  assert.equal(PROTOCOL_VERSION, frozen.version, 'PROTOCOL_VERSION moved without recording the shape it belongs to (UPDATE_PROTOCOL_SHAPE=1)');
+  assert.equal(agentVersion, PROTOCOL_VERSION, "lynkeus-agent's own PROTOCOL_VERSION must equal this one");
+});

package/src/index.ts

@@ -0,0 +1,191 @@
+/** JSON-RPC-shaped messages over a WebSocket the app opens towards the driver; docs/PROTOCOL.md has the prose. */
+export const PROTOCOL_VERSION = 1;
+
+export type Frame = { x: number; y: number; w: number; h: number };
+
+export type ElementKind = 'button' | 'input' | 'text' | 'scroll' | 'switch' | 'image' | 'view';
+
+/** Why an element is in the tree but not presented: structural, so a device and a host without layout agree. */
+export type HiddenReason =
+  /** Hidden from assistive technology, so it is not presented to anyone. */
+  | 'a11y'
+  /** `pointerEvents: 'none'` on it or an ancestor: no touch can reach it. */
+  | 'inert'
+  /** Outside the subtree that declared itself modal. */
+  | 'behind-modal'
+  /** Outside the last full-window layer the app mounted at its root. */
+  | 'behind-overlay';
+
+export type Element = {
+  /** Position in tree order: later elements draw on top of earlier ones. */
+  i: number;
+  kind: ElementKind;
+  frame: Frame;
+  enabled: boolean;
+  depth: number;
+  testId?: string;
+  /** Rendered text for `text` elements, or the label of a button/input. */
+  text?: string;
+  accessibilityLabel?: string;
+  /** Masked (`•`) when the field is a secure entry. */
+  value?: string;
+  placeholder?: string;
+  focused?: boolean;
+  /** Index of the nearest listed ancestor, when there is one. */
+  parent?: number;
+  /** React native tag of the host view. */
+  tag?: number;
+  /** A touch at its centre would not reach it: something is on top. */
+  covered?: boolean;
+  /** Not presented at all, and why. A hidden element is not on screen. */
+  hidden?: HiddenReason;
+  /** Its rect lies outside the window: on screen only after scrolling. */
+  offscreen?: boolean;
+};
+
+export type Screen = {
+  route?: string;
+  params?: unknown;
+  /** Route names from the root navigator down to the focused screen. */
+  path: string[];
+  elements: Element[];
+  /** React commits since the agent started; a change means the UI re-rendered. */
+  commit: number;
+  /** Requests in flight, plus whatever the app's `busy` command reports. */
+  busy: boolean;
+  window: { w: number; h: number };
+  /** The layer on top, when the app is presenting one over its screen. */
+  presenting?: { i: number; modal: boolean; testId?: string };
+  /** Milliseconds spent building this snapshot inside the app. */
+  costMs: number;
+};
+
+/** Where to look for a target: the element this names, then each container up from it, nearest first. */
+export type Scope = { testId: string } | { text: string };
+export type Target =
+  | { testId: string; nth?: number; within?: Scope }
+  | { text: string; nth?: number; within?: Scope }
+  | { i: number }
+  | { x: number; y: number };
+
+export type PressOptions = {
+  /** Finger-down time; a long press is ~600. Default 50. */
+  holdMs?: number;
+  /** `js` calls the element's onPress directly: no touch, no gesture, no animation wait. Needs a testId and an enabled, uncovered control. */
+  mode?: 'native' | 'js';
+};
+
+export type SwipeParams = {
+  direction?: 'up' | 'down' | 'left' | 'right';
+  /** Swipe on an element (a slider, a sheet handle) from its centre rather than across the window. */
+  target?: Target;
+  /** How far to move, in points; default 60% of the window's extent that way. */
+  distance?: number;
+  from?: { x: number; y: number };
+  to?: { x: number; y: number };
+  durationMs?: number;
+};
+
+export type WaitForParams = {
+  route?: string;
+  target?: Target;
+  /** Satisfied by whichever of these shows up first. */
+  anyOf?: Target[];
+  gone?: boolean;
+  /** Swipe the nearest scrolling container towards the target until it is in the window. */
+  scroll?: boolean;
+  timeoutMs?: number;
+};
+
+export type TraceEvent = { seq: number; t: number } & (
+  | { kind: 'route'; route?: string; path: string[] }
+  | { kind: 'request'; method: string; url: string; status?: number; ms?: number; error?: string }
+  | { kind: 'store'; store: string; changed: Record<string, { from: unknown; to: unknown }> }
+  /** Something the app told its analytics, through `qa.event`. */
+  | { kind: 'event'; name: string; props?: Record<string, unknown>; route?: string }
+  | { kind: 'command'; method: string; ms: number; error?: string }
+  /** The host broke a runaway render loop: `renders` updates in `windowMs`. */
+  | { kind: 'stall'; renders: number; windowMs: number; component?: string }
+  /** A finger on the screen (device builds mounted with `auto()`), resolved to the element under it. */
+  | { kind: 'touch'; x: number; y: number; testId?: string; text?: string; route?: string }
+  /** Something threw where nothing caught it, and the screen may be gone. */
+  | { kind: 'crash'; message: string; stack?: string; route?: string }
+);
+
+export type RequestRecord = {
+  id: number;
+  method: string;
+  url: string;
+  status?: number;
+  startedAt: number;
+  ms?: number;
+  error?: string;
+};
+
+/** Every method the core answers. Apps add their own through `qa.register`. */
+export type CoreMethods = {
+  ping: {
+    params: undefined;
+    result: { pong: true; native: boolean; commands: string[] };
+  };
+  screen: { params: undefined; result: Screen };
+  find: { params: Target; result: Element | null };
+  press: {
+    params: Target & PressOptions;
+    result: { x: number; y: number; element?: Element; mode: 'native' | 'js' };
+  };
+  type: {
+    params: { text: string; target?: Target; clear?: boolean; paste?: boolean; submit?: boolean };
+    result: { typed: string; element?: Element };
+  };
+  swipe: {
+    params: SwipeParams;
+    result: { from: { x: number; y: number }; to: { x: number; y: number } };
+  };
+  navigate: {
+    params: { name: string; params?: object };
+    result: { route: string };
+  };
+  back: { params: undefined; result: { route?: string } };
+  waitFor: {
+    params: WaitForParams;
+    result: { route?: string; matched?: Target; waitedMs: number };
+  };
+  idle: {
+    /** `after`: a commit count from before the awaited change; quiet only counts once the app has committed past it. */
+    params: { quietMs?: number; timeoutMs?: number; after?: number } | undefined;
+    result: { commit: number; idle: boolean };
+  };
+  deepLink: { params: { url: string }; result: { opened: string } };
+  requests: {
+    params: { since?: number } | undefined;
+    result: { inFlight: number; requests: RequestRecord[] };
+  };
+  trace: {
+    params: { since?: number } | undefined;
+    result: { last: number; events: TraceEvent[] };
+  };
+  dismissKeyboard: { params: undefined; result: boolean };
+  /** Several calls in one round trip, in order; stops at the first error. */
+  batch: {
+    params: { calls: { method: string; params?: unknown }[] };
+    result: { results: unknown[] };
+  };
+};
+
+export type Request = { id: number; method: string; params?: unknown };
+export type Response = { id: number; result: unknown } | { id: number; error: { message: string; code?: string } };
+
+export type HelloEvent = {
+  event: 'hello';
+  protocolVersion: number;
+  platform: 'ios' | 'android' | string;
+  native: boolean;
+  commands: string[];
+  route?: string;
+  app?: Record<string, unknown>;
+};
+export type NavigationEvent = { event: 'navigation'; route?: string };
+/** The driver's first message. `session` is random per driver process, so the app can tell a reconnect (whose resent requests it may have answered) from a new driver reusing request ids. */
+export type AuthEvent = { event: 'auth'; session: string; token?: string };
+export type AgentEvent = HelloEvent | NavigationEvent;