lynkeus 0.2.0 → 0.3.0

package/lib/knowledge/contrast.js

@@ -0,0 +1,114 @@
+const AA_NORMAL = 4.5;
+const AA_LARGE = 3;
+// A text box this uniform has a flat background; under it the text sits on a picture or a gradient.
+const PLAIN_SHARE = 0.5;
+// Enough pixels of one color to be glyphs and not the fringe where a glyph meets its background.
+const LEAST_SHARE = 0.004;
+const LEAST_PIXELS = 6;
+const channel = (value) => {
+    const v = value / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+/** WCAG's relative luminance of an sRGB color. */
+export const luminance = ([r, g, b]) => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+/** WCAG's contrast ratio, from 1 (the same color) to 21 (black on white). */
+export const contrastRatio = (a, b) => {
+    const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (light + 0.05) / (dark + 0.05);
+};
+export const hex = (rgb) => `#${rgb.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
+/**
+ * The contrast of the text inside a rectangle of the picture, in pixels. The background is the color most
+ * of the rectangle has; the text is the color, among those with enough pixels to be glyphs, that stands
+ * furthest from it. Anything else in the box (an icon beside a label) can only raise the figure, so a low one
+ * is a finding and a high one is not a certificate.
+ */
+export const measureContrast = (picture, box) => {
+    const left = Math.max(0, Math.floor(box.x));
+    const top = Math.max(0, Math.floor(box.y));
+    const right = Math.min(picture.width, Math.ceil(box.x + box.w));
+    const bottom = Math.min(picture.height, Math.ceil(box.y + box.h));
+    if (right - left < 2 || bottom - top < 2)
+        return undefined;
+    // Colors are gathered 8 levels to a bucket: antialiasing and compression never give one flat value.
+    const buckets = new Map();
+    let total = 0;
+    for (let y = top; y < bottom; y++) {
+        for (let x = left; x < right; x++) {
+            const at = (y * picture.width + x) * 4;
+            const r = picture.data[at];
+            const g = picture.data[at + 1];
+            const b = picture.data[at + 2];
+            const key = ((r >> 3) << 10) | ((g >> 3) << 5) | (b >> 3);
+            const bucket = buckets.get(key);
+            if (bucket) {
+                bucket.count++;
+                bucket.r += r;
+                bucket.g += g;
+                bucket.b += b;
+            }
+            else {
+                buckets.set(key, { count: 1, r, g, b });
+            }
+            total++;
+        }
+    }
+    const colors = [...buckets.values()].map((bucket) => ({
+        count: bucket.count,
+        rgb: [bucket.r / bucket.count, bucket.g / bucket.count, bucket.b / bucket.count],
+    }));
+    const background = colors.reduce((most, color) => (color.count > most.count ? color : most));
+    const least = Math.max(LEAST_PIXELS, total * LEAST_SHARE);
+    let best;
+    for (const color of colors) {
+        if (color === background || color.count < least)
+            continue;
+        const ratio = contrastRatio(color.rgb, background.rgb);
+        if (!best || ratio > best.ratio)
+            best = { ratio, rgb: color.rgb };
+    }
+    // Nothing but background: an empty field, or text the same color as what is behind it.
+    if (!best || best.ratio < 1.05)
+        return undefined;
+    return { ratio: best.ratio, text: best.rgb, background: background.rgb, plain: background.count / total >= PLAIN_SHARE };
+};
+const isLarge = (font) => !!font && (font.size >= 18 || (font.size >= 14 && font.bold === true));
+/** WCAG leaves out what cannot be used (a disabled control) and what is not there to be read. */
+const judged = (e) => !e.hidden &&
+    !e.covered &&
+    !e.offscreen &&
+    e.enabled !== false &&
+    (e.kind === 'text' || e.kind === 'button' || e.kind === 'input') &&
+    (e.text ?? e.value ?? e.placeholder) !== undefined;
+/** A finding for every text on the screen whose contrast falls short, most serious first. */
+export const lintContrast = (screen, picture, options = {}) => {
+    const window = screen.window;
+    if (!window || window.w <= 0)
+        return [];
+    const scale = picture.width / window.w;
+    const out = [];
+    for (const e of screen.elements ?? []) {
+        if (!judged(e) || !e.frame || e.frame.w <= 0 || e.frame.h <= 0)
+            continue;
+        if (e.testId && options.ignore?.some((pattern) => pattern.test(e.testId)))
+            continue;
+        const measured = measureContrast(picture, { x: e.frame.x * scale, y: e.frame.y * scale, w: e.frame.w * scale, h: e.frame.h * scale });
+        if (!measured)
+            continue;
+        const large = isLarge(e.font);
+        const needed = large ? (options.large ?? AA_LARGE) : (options.normal ?? AA_NORMAL);
+        if (measured.ratio >= needed)
+            continue;
+        const said = (e.text ?? e.value ?? e.placeholder ?? '').slice(0, 40);
+        out.push({
+            rule: 'low-contrast',
+            // Over a picture the background is a guess, so it is said and left to a person.
+            severity: measured.plain ? 'warn' : 'info',
+            element: e.i,
+            // The text, not the ratio: a baseline knows the finding again when the measurement moves.
+            subject: said,
+            message: `"${said}" ${measured.ratio.toFixed(1)}:1 (${hex(measured.text)} on ${hex(measured.background)}${measured.plain ? '' : ', over a varied background'}), needs ${needed}:1${large ? ' for large text' : ''}`,
+        });
+    }
+    return out;
+};

package/lib/knowledge/errors.js

@@ -27,7 +27,7 @@ const RULES = [
     {
         re: /Cannot read propert(?:y|ies) of undefined \(reading '(\w+)'\)/,
         cause: (m) => `something the app expected to exist is undefined (reading '${m[1]}')`,
-        fix: () => `look one frame up the stack for the module: a mock returning {} instead of the shape the app reads, or a store not initialised because a service failed earlier.`,
+        fix: () => `look one frame up the stack for the module: a mock returning {} instead of the shape the app reads, or a store not initialized because a service failed earlier.`,
     },
     {
         re: /Jest did not exit one second after the test run has completed/,

package/lib/knowledge/lint.d.ts

@@ -1,10 +1,12 @@
 /** What a person would flag in review, read off one screen: not accessibility certification, the usual suspects. */
 import type { Screen } from 'lynkeus-protocol';
+/** `subject` is what the finding is about, without what was measured: it is how a baseline knows the finding again. */
 export type Finding = {
     rule: string;
     severity: 'warn' | 'info';
     element: number;
     message: string;
+    subject?: string;
 };
 type LintOptions = {
     /** What an untranslated key looks like (default `a.b.c` and `snake_case_key`); `[]` turns the rule off. */

package/lib/knowledge/lint.js

@@ -20,7 +20,7 @@ export const lintScreen = (screen, options = {}) => {
     for (const e of els) {
         const named = e.text ?? e.accessibilityLabel;
         if ((e.kind === 'button' || e.kind === 'switch') && named === undefined && e.testId === undefined) {
-            out.push({ rule: 'unlabeled-control', severity: 'warn', element: e.i, message: `${e.kind} with no text, label or testId` });
+            out.push({ rule: 'unlabeled-control', severity: 'warn', element: e.i, message: `${e.kind} with no text, label or testId`, subject: e.kind });
         }
         if ((e.kind === 'button' || e.kind === 'switch') && e.enabled !== false && e.frame) {
             const { w, h } = e.frame;
@@ -32,11 +32,12 @@ export const lintScreen = (screen, options = {}) => {
                     severity: iconOnly ? 'warn' : 'info',
                     element: e.i,
                     message: `${Math.round(w)}×${Math.round(h)}pt target (< ${minTouch}) ${label(e) ?? ''}`.trim(),
+                    subject: label(e) ?? e.kind,
                 });
             }
         }
         if (e.kind === 'text' && e.text && looksLikeI18nKey(e.text, options.i18nKeyPatterns ?? DEFAULT_I18N_KEY_PATTERNS)) {
-            out.push({ rule: 'untranslated', severity: 'warn', element: e.i, message: `"${e.text}" looks like an i18n key, not copy` });
+            out.push({ rule: 'untranslated', severity: 'warn', element: e.i, message: `"${e.text}" looks like an i18n key, not copy`, subject: e.text });
         }
         if ((e.kind === 'button' || e.kind === 'input' || e.kind === 'switch') && e.covered && e.enabled !== false) {
             out.push({
@@ -44,6 +45,7 @@ export const lintScreen = (screen, options = {}) => {
                 severity: 'info',
                 element: e.i,
                 message: `${e.kind} ${label(e) ?? ''} is covered; a tap would not reach it`.replace('  ', ' ').trim(),
+                subject: label(e) ?? e.kind,
             });
         }
         if (e.frame && win.w > 0 && label(e) !== undefined) {
@@ -54,6 +56,7 @@ export const lintScreen = (screen, options = {}) => {
                     severity: 'info',
                     element: e.i,
                     message: `${label(e)} extends past the ${win.w}×${win.h} window (x${Math.round(x)} y${Math.round(y)} ${Math.round(w)}×${Math.round(h)})`,
+                    subject: label(e),
                 });
             }
         }
@@ -63,6 +66,7 @@ export const lintScreen = (screen, options = {}) => {
                 severity: 'info',
                 element: e.i,
                 message: `"${e.text.slice(0, 30)}" has ${Math.round(e.frame.w)}×${Math.round(e.frame.h)} size`,
+                subject: e.text,
             });
         }
     }
@@ -76,7 +80,13 @@ export const lintScreen = (screen, options = {}) => {
     }
     for (const [id, at] of byTestId)
         if (at.length > 1)
-            out.push({ rule: 'duplicate-testid', severity: 'info', element: at[0], message: `testId "${id}" is on ${at.length} elements (${at.join(', ')})` });
+            out.push({
+                rule: 'duplicate-testid',
+                severity: 'info',
+                element: at[0],
+                message: `testId "${id}" is on ${at.length} elements (${at.join(', ')})`,
+                subject: id,
+            });
     return out;
 };
 export const describeFindings = (findings, route) => {

package/lib/registry.d.ts

@@ -19,6 +19,11 @@ export type Base = {
     err: (line: string) => void;
     /** Inside `lynkeus session` and over MCP: one connection, many commands. */
     attached: boolean;
+    /** The same, but waiting for its app on another port: one per host when several run side by side. */
+    forPort?: (port: number) => {
+        base: Base;
+        stop: () => Promise<void>;
+    };
 };
 export type Ctx = Base & {
     args: string[];

package/lib/targets.d.ts

@@ -1,13 +1,22 @@
 import type { Target } from 'lynkeus-protocol';
 export declare const TARGET_HELP = "#testId | \"text\" | 12 (index) | 100,200";
-/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+/**
+ * `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match.
+ * A text in quotes is that text and nothing else: `"12"` is not an index, and `"Next"` is not a route.
+ */
 export declare const parseTarget: (raw: string) => Target;
 /** A target narrowed to the match nearest another (`--in`) and to a position among the matches (`--nth`). */
 export declare const scopedTarget: (raw: string, flags: {
     in?: unknown;
     nth?: unknown;
 }) => Target;
+/**
+ * A word that starts with a capital is a route (`Home.Main`), as React Navigation names them. A router
+ * that names routes after files (Expo Router's `index`, `(tabs)/settings`) says so: `route:index`.
+ */
 export declare const isRoute: (raw: string) => boolean;
+/** The route a target names, without the prefix that marked it as one. */
+export declare const routeOf: (raw: string) => string;
 export type Expected = {
     testId?: string;
     text?: string;

package/lib/targets.js

@@ -1,6 +1,12 @@
 export const TARGET_HELP = '#testId | "text" | 12 (index) | 100,200';
-/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+/**
+ * `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match.
+ * A text in quotes is that text and nothing else: `"12"` is not an index, and `"Next"` is not a route.
+ */
 export const parseTarget = (raw) => {
+    const quoted = /^(["'])((?:(?!\1).)*)\1$/s.exec(raw);
+    if (quoted)
+        return { text: quoted[2] };
     const nth = /^(.+)\[(\d+)\]$/.exec(raw);
     if (nth && !/^\d+$/.test(nth[1])) {
         const base = parseTarget(nth[1]);
@@ -31,13 +37,20 @@ export const scopedTarget = (raw, flags) => {
         ...(typeof flags.nth === 'number' ? { nth: flags.nth } : {}),
     };
 };
-export const isRoute = (raw) => /^[A-Z]\w*(\.[A-Z]\w*)*$/.test(raw);
+const ROUTE_PREFIX = 'route:';
+/**
+ * A word that starts with a capital is a route (`Home.Main`), as React Navigation names them. A router
+ * that names routes after files (Expo Router's `index`, `(tabs)/settings`) says so: `route:index`.
+ */
+export const isRoute = (raw) => raw.startsWith(ROUTE_PREFIX) || /^[A-Z]\w*(\.[A-Z]\w*)*$/.test(raw);
+/** The route a target names, without the prefix that marked it as one. */
+export const routeOf = (raw) => (raw.startsWith(ROUTE_PREFIX) ? raw.slice(ROUTE_PREFIX.length) : raw);
 /** What a command was looking for, as `why` reads it. */
 export const expectedOf = (raw) => {
     if (!raw)
         return undefined;
     if (isRoute(raw))
-        return { route: raw };
+        return { route: routeOf(raw) };
     const t = parseTarget(raw);
     return 'testId' in t ? { testId: t.testId } : 'text' in t ? { text: t.text } : undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Drive a React Native app running lynkeus-agent from the terminal, a test runner or an MCP client: screens, flows, smoke, crawl, and the app's screen graph.",
   "type": "module",
   "bin": "./lib/cli.js",
@@ -14,7 +14,8 @@
   },
   "files": [
     "lib",
-    "src"
+    "src",
+    "!**/__tests__"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -25,14 +26,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jonamischener/lynkeus.git",
+    "url": "git+https://github.com/lynkeushq/lynkeus.git",
     "directory": "packages/cli"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "lynkeus-client": "^0.2.0",
-    "lynkeus-protocol": "^0.2.0",
+    "lynkeus-client": "^0.3.0",
+    "lynkeus-protocol": "^0.3.0",
     "pngjs": "^7.0.0",
     "ts-morph": "^24.0.0",
     "yaml": "^2"
@@ -43,5 +47,5 @@
     "tsx": "^4.19.2",
     "typescript": "^6.0.3"
   },
-  "homepage": "https://github.com/jonamischener/lynkeus#readme"
+  "homepage": "https://github.com/lynkeushq/lynkeus#readme"
 }

package/src/cases/ahead.ts

@@ -0,0 +1,111 @@
+/**
+ * Setups made ahead of their cases. `case prepare` runs, in the order a suite
+ * will, the setup of every case that needs only the project's fixtures, and
+ * leaves what it produced here, one file a case; `case run` takes the file
+ * when its case starts and goes straight to the steps.
+ *
+ * A case that starts before its setup is ready marks itself started, runs its
+ * own setup, and the preparer skips it. Files are taken with a rename, so two
+ * processes never get the same one.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Case } from './format.js';
+import type { Prepared } from './runner.js';
+
+// What a backend held a quarter of an hour ago may have moved on (a session, a rate).
+const MAX_AGE_MS = 15 * 60_000;
+
+type Kept = { setup: string; at: number; prepared: Prepared };
+
+/** Where setups made ahead wait for their cases: files for a preparer in another process, memory in the same one. */
+export type Store = {
+  start(c: Case): void;
+  started(c: Case): boolean;
+  keep(c: Case, prepared: Prepared): void;
+  take(c: Case): Prepared | undefined;
+  waiting(): number;
+};
+
+export class InMemory implements Store {
+  readonly #started = new Set<string>();
+  readonly #kept = new Map<string, Prepared>();
+
+  start(c: Case): void {
+    this.#started.add(c.id);
+  }
+
+  started(c: Case): boolean {
+    return this.#started.has(c.id);
+  }
+
+  keep(c: Case, prepared: Prepared): void {
+    if (!this.started(c)) this.#kept.set(c.id, prepared);
+  }
+
+  take(c: Case): Prepared | undefined {
+    const prepared = this.#kept.get(c.id);
+    this.#kept.delete(c.id);
+    return prepared;
+  }
+
+  waiting(): number {
+    return this.#kept.size;
+  }
+}
+
+export class Ahead implements Store {
+  constructor(private readonly dir: string) {}
+
+  #file(c: Case, suffix = '.json') {
+    return path.join(this.dir, `${c.id.replace(/[^\w.-]+/g, '_')}${suffix}`);
+  }
+
+  clear(): void {
+    fs.rmSync(this.dir, { recursive: true, force: true });
+    fs.mkdirSync(this.dir, { recursive: true });
+  }
+
+  start(c: Case): void {
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.#file(c, '.started'), '');
+  }
+
+  started(c: Case): boolean {
+    return fs.existsSync(this.#file(c, '.started'));
+  }
+
+  keep(c: Case, prepared: Prepared): void {
+    // Its case started while this was being made, and ran a setup of its own.
+    if (this.started(c)) return;
+    const file = this.#file(c);
+    const kept: Kept = { setup: JSON.stringify(c.setup), at: Date.now(), prepared };
+    fs.writeFileSync(`${file}.tmp`, JSON.stringify(kept));
+    fs.renameSync(`${file}.tmp`, file);
+  }
+
+  /** Setups made and not yet taken by a case that is still to start. */
+  waiting(): number {
+    return fs.readdirSync(this.dir).filter((f) => f.endsWith('.json') && !fs.existsSync(path.join(this.dir, f.replace(/\.json$/, '.started')))).length;
+  }
+
+  /** The case's setup if it was made, is recent and is the setup the case has now. */
+  take(c: Case): Prepared | undefined {
+    const file = this.#file(c);
+    const mine = `${file}.${process.pid}`;
+    try {
+      fs.renameSync(file, mine);
+    } catch {
+      return undefined;
+    }
+    try {
+      const kept = JSON.parse(fs.readFileSync(mine, 'utf8')) as Kept;
+      return kept.setup === JSON.stringify(c.setup) && Date.now() - kept.at < MAX_AGE_MS ? kept.prepared : undefined;
+    } catch {
+      return undefined;
+    } finally {
+      fs.rmSync(mine, { force: true });
+    }
+  }
+}

package/src/cases/fixtures.ts

@@ -8,6 +8,22 @@
  * — and one line out, the step's answer: any JSON object, `"ok": false` and an
  * `error` when it failed. `params` is the step as written; `env` is the same
  * flattened to upper-case strings, for a server that hands them to a script.
+ *
+ * Before the first case lynkeus asks what the server can do —
+ *
+ *   {"command": "lynkeus.describe", "params": {}, "env": {}}
+ *
+ * — and a server that knows answers `{"commands": ["create_user", …]}`. With
+ * that, a case naming a fixture nobody answers is refused before anything
+ * runs. A server that answers `"ok": false`, as one written before this did,
+ * is taken to describe nothing, and its cases run unchecked. A server that is
+ * running but cannot serve (its database is down) adds `"down": "<why>"`, and
+ * no case starts: every one would fail at its first fixture.
+ *
+ * A connection that makes cases' setups ahead of time (`case prepare`) says so
+ * first, with `lynkeus.ahead`, so a server may give its work a lower priority
+ * than the cases running meanwhile. A server that does not know it is free to
+ * answer anything.
  */
 import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
 import path from 'node:path';
@@ -17,6 +33,14 @@ export type FixturesConfig = { command: string; cwd?: string; env?: Record<strin
 
 export type Answer = Record<string, unknown>;
 
+/** The one command that is lynkeus's own and not the project's. */
+export const DESCRIBE = 'lynkeus.describe';
+
+export type Description = { commands: string[]; down?: string };
+
+/** lynkeus's second own command: this connection works ahead of the cases. */
+export const AHEAD = 'lynkeus.ahead';
+
 const envOf = (params: Record<string, unknown>): Record<string, string> =>
   Object.fromEntries(
     Object.entries(params)
@@ -90,6 +114,19 @@ export class Fixtures {
     return answer;
   }
 
+  /** What the server says it answers, or nothing when it does not say. */
+  async describe(): Promise<Description | undefined> {
+    const answer = await this.call(DESCRIBE, {}).catch(() => undefined);
+    const commands = answer?.commands;
+    if (!Array.isArray(commands) || !commands.every((c) => typeof c === 'string')) return undefined;
+    return typeof answer?.down === 'string' && answer.down ? { commands, down: answer.down } : { commands };
+  }
+
+  /** Says this connection works ahead of the cases being run. Whatever the server answers, it goes on. */
+  async ahead(): Promise<void> {
+    await this.call(AHEAD, {}).catch(() => undefined);
+  }
+
   close(): void {
     const child = this.#child;
     this.#child = null;

package/src/cases/flakes.ts

@@ -0,0 +1,67 @@
+/**
+ * How each case has done across runs, kept in one JSON file: the last results,
+ * how often it needed its second chance, the step it last died on. A case that
+ * passes and fails without anything changing is the one to look at first.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { CaseReport } from './runner.js';
+
+const KEPT = 20;
+
+export type Outcome = { at: string; result: CaseReport['result']; retried: boolean; ms?: number; step?: string; error?: string };
+export type Ledger = Record<string, { runs: number; failed: number; retried: number; last: Outcome[] }>;
+
+export class Flakes {
+  private readonly ledger: Ledger;
+
+  constructor(private readonly file: string) {
+    let read: Ledger = {};
+    try {
+      read = JSON.parse(fs.readFileSync(file, 'utf8')) as Ledger;
+    } catch {
+      // No ledger yet, or one this cannot read: start a new one.
+    }
+    this.ledger = read;
+  }
+
+  note(report: CaseReport & { retried?: boolean }, at = new Date()): void {
+    const entry = this.ledger[report.id] ?? { runs: 0, failed: 0, retried: 0, last: [] };
+    this.ledger[report.id] = entry;
+    const broke = report.steps.find((s) => s.status === 'failed');
+    entry.runs += 1;
+    if (report.result === 'failed') entry.failed += 1;
+    if (report.retried) entry.retried += 1;
+    entry.last = [
+      ...entry.last,
+      {
+        at: at.toISOString(),
+        result: report.result,
+        retried: !!report.retried,
+        ms: report.ms,
+        ...(broke ? { step: broke.step, error: broke.error?.split('\n')[0] } : {}),
+      },
+    ].slice(-KEPT);
+  }
+
+  /** How long a case took when it last passed, if the ledger has seen it pass. */
+  lastMs(id: string): number | undefined {
+    return [...(this.ledger[id]?.last ?? [])].reverse().find((o) => o.result === 'passed' && o.ms !== undefined)?.ms;
+  }
+
+  /** The cases among `ids` whose recent runs disagree with each other, worded for a summary. */
+  flaky(ids: string[]): string[] {
+    return ids.flatMap((id) => {
+      const last = this.ledger[id]?.last ?? [];
+      const shaky = last.filter((o) => o.result === 'failed' || o.retried).length;
+      if (shaky === 0 || shaky === last.length) return [];
+      return [`⚠ ${id} is flaky: ${shaky} of its last ${last.length} runs failed or needed a second chance`];
+    });
+  }
+
+  save(): void {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    fs.writeFileSync(this.file, `${JSON.stringify(this.ledger, null, 2)}\n`);
+  }
+}

package/src/cases/format.ts

@@ -106,21 +106,46 @@ export const dig = (json: unknown, dotted: string): unknown => {
   return current;
 };
 
+export type Scope = Record<string, unknown>;
+
+/** Where a seeded case keeps how far its random values have gone; no alias can be named this. */
+const SEED = '~seed';
+
+/**
+ * With LYNKEUS_SEED set, a case's `{{random.*}}` values are the same on every run: two runs of it then show
+ * the same names, which comparing their screens needs. Each case draws its own, so cases side by side differ.
+ */
+export const seeded = (scope: Scope, id: string): void => {
+  const seed = process.env.LYNKEUS_SEED;
+  if (!seed || scope[SEED] !== undefined) return;
+  let hash = 2166136261;
+  for (const char of `${seed}\n${id}`) hash = Math.imul(hash ^ char.charCodeAt(0), 16777619);
+  scope[SEED] = hash >>> 0;
+};
+
 const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
-const random = (kind: string): string | undefined => {
-  if (kind === 'letters') return Array.from({ length: 6 }, () => LETTERS[Math.floor(Math.random() * 26)]).join('');
-  if (kind === 'digits') return Array.from({ length: 6 }, () => Math.floor(Math.random() * 10)).join('');
+const random = (kind: string, scope: Scope): string | undefined => {
+  const next = (): number => {
+    if (typeof scope[SEED] !== 'number') return Math.random();
+    // mulberry32
+    const state = (scope[SEED] + 0x6d2b79f5) >>> 0;
+    scope[SEED] = state;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  if (kind === 'letters') return Array.from({ length: 6 }, () => LETTERS[Math.floor(next() * 26)]).join('');
+  if (kind === 'digits') return Array.from({ length: 6 }, () => Math.floor(next() * 10)).join('');
   return undefined;
 };
 
-export type Scope = Record<string, unknown>;
-
 /** `{{alias.path}}` from what earlier steps answered, `{{random.letters}}`, `{{env.NAME}}`. */
 export const interpolate = <T>(value: T, scope: Scope): T => {
   if (typeof value === 'string') {
     const whole = /^\{\{\s*([\w-]+)\.([\w.*-]+)\s*\}\}$/.exec(value);
     const lookup = (name: string, path: string): unknown => {
-      if (name === 'random') return random(path);
+      if (name === 'random') return random(path, scope);
       if (name === 'env') return process.env[path];
       if (!(name in scope)) throw new Error(`no alias '${name}' (add \`as: ${name}\` to the step that creates it)`);
       return dig(scope[name], path);

package/src/cases/portClaim.ts

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const alive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+};
+
+/**
+ * A run lets go of its driver port between cases, and the app dials whichever driver is listening: two runs
+ * on one port take turns at the app, and each reports steps the other drove. A run claims its ports for as
+ * long as it lasts; what it answers is the release, or why another run holds one.
+ */
+export const claimPorts = (ports: number[], dir = os.tmpdir()): { release: () => void } | { refused: string } => {
+  const held: string[] = [];
+  const release = () => {
+    for (const file of held) {
+      try {
+        if (fs.readFileSync(file, 'utf8').trim() === String(process.pid)) fs.unlinkSync(file);
+      } catch {
+        // Already gone.
+      }
+    }
+  };
+  for (const port of ports) {
+    const file = path.join(dir, `lynkeus-port-${port}.pid`);
+    for (;;) {
+      try {
+        fs.writeFileSync(file, String(process.pid), { flag: 'wx' });
+        held.push(file);
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      }
+      const owner = Number(fs.readFileSync(file, 'utf8').trim());
+      if (Number.isInteger(owner) && owner > 0 && owner !== process.pid && alive(owner)) {
+        release();
+        return {
+          refused: `port ${port} is held by another lynkeus case run (pid ${owner}), which is probably still going: stop it, or give this run other --ports`,
+        };
+      }
+      // Left by a run that ended without letting go.
+      fs.rmSync(file, { force: true });
+    }
+  }
+  return { release };
+};