@reynsu/nativelens-event-protocol 0.1.1

package/README.md

@@ -0,0 +1,55 @@
+# @reynsu/nativelens-event-protocol
+
+Canonical `RunEvent` discriminated union + Zod schemas for the nativelens event bus.
+
+Published under `@reynsu/` because the `@nativelens` npm scope is not (yet) claimed as an org. Inside the nativelens monorepo this package is still referenced as `@nativelens/event-protocol` (workspace dep); the swap to the published name is a follow-up PR.
+
+This package owns the wire shape that flows between probe ↔ harness ↔ runner ↔ dashboard. It is the single source of truth — consumers cast their internal types into this protocol at boundaries and trust the typed `RunEvent` thereafter.
+
+## Why a separate repo
+
+Per ADR-0002, the protocol used to live as a local mirror inside the `nativelens` monorepo (`packages/event-protocol/`). Extracting it here lets:
+
+- `nativelens` consume a published, version-pinned dep instead of a `workspace:*` symlink.
+- `reactlens` migrate to this protocol once its own event surface aligns (currently `src/runner/events.ts` in that repo).
+- Both consumers evolve independently against a contract that bumps semver explicitly.
+
+## Wire shape (v0.1.0)
+
+`RunEvent` is a discriminated union over `type`:
+
+| Variant | Direction | Purpose |
+|---|---|---|
+| `hello` | probe → harness, runner → harness | Role announcement at connection time |
+| `step:set` | runner → probe | Mark the current `(testId, stepId)` |
+| `step:ack` | probe → runner | Confirm `(testId, stepId)` was applied |
+| `snapshot` | probe → harness | Component tree + testID map for one commit |
+| `test:end` | runner → harness | End of a test, flush boundary |
+| `a11y:violation` | runner → harness | One violation reported by the walker |
+| `hmr:start` / `hmr:end` | probe → harness | Metro hot-reload boundaries; harness silences snapshot persistence between them |
+
+Every variant has a `make*` builder and is in `parseRunEvent` for fail-soft inbound decoding.
+
+## Usage
+
+```ts
+import { parseRunEvent, makeSnapshot, type RunEvent } from '@reynsu/nativelens-event-protocol';
+
+const event = parseRunEvent(rawJsonLine);
+if (event?.type === 'snapshot') {
+  // typed access to tree, testIdIndex, etc.
+}
+```
+
+## Versioning
+
+Pre-1.0: minor bumps may include breaking wire changes; pin to the exact minor in dependents. Post-1.0: strict semver per the wire contract.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+```

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod';
+export declare const SerializedNodeKind: z.ZodEnum<["host", "function", "class", "memo", "forwardRef", "other"]>;
+export type SerializedNodeKind = z.infer<typeof SerializedNodeKind>;
+export type SerializedNode = {
+    fiberId: number;
+    name: string;
+    kind: SerializedNodeKind;
+    props: Record<string, unknown>;
+    hooks: unknown[];
+    children: SerializedNode[];
+};
+export declare const SerializedNodeSchema: z.ZodType<SerializedNode>;
+export type TestIdIndex = Record<string, number>;
+export declare const TestIdIndexSchema: z.ZodType<TestIdIndex>;
+export declare const StepSetSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step:set">;
+    testId: z.ZodString;
+    stepId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "step:set";
+    testId: string;
+    stepId: string;
+}, {
+    type: "step:set";
+    testId: string;
+    stepId: string;
+}>;
+export type StepSet = z.infer<typeof StepSetSchema>;
+export declare function makeStepSet(testId: string, stepId: string): StepSet;
+export declare const StepAckSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step:ack">;
+    testId: z.ZodString;
+    stepId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "step:ack";
+    testId: string;
+    stepId: string;
+}, {
+    type: "step:ack";
+    testId: string;
+    stepId: string;
+}>;
+export type StepAck = z.infer<typeof StepAckSchema>;
+export declare function makeStepAck(testId: string, stepId: string): StepAck;
+export declare const HelloRole: z.ZodEnum<["probe", "runner"]>;
+export type HelloRole = z.infer<typeof HelloRole>;
+export declare const HelloSchema: z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    role: z.ZodEnum<["probe", "runner"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "hello";
+    role: "probe" | "runner";
+}, {
+    type: "hello";
+    role: "probe" | "runner";
+}>;
+export type Hello = z.infer<typeof HelloSchema>;
+export declare function makeHello(role: HelloRole): Hello;
+export declare const TestEndSchema: z.ZodObject<{
+    type: z.ZodLiteral<"test:end">;
+    testId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "test:end";
+    testId: string;
+}, {
+    type: "test:end";
+    testId: string;
+}>;
+export type TestEnd = z.infer<typeof TestEndSchema>;
+export declare function makeTestEnd(testId: string): TestEnd;
+export declare const SnapshotSchema: z.ZodObject<{
+    type: z.ZodLiteral<"snapshot">;
+    commit: z.ZodNumber;
+    testId: z.ZodString;
+    stepId: z.ZodString;
+    ts: z.ZodNumber;
+    tree: z.ZodType<SerializedNode, z.ZodTypeDef, SerializedNode>;
+    testIdIndex: z.ZodType<TestIdIndex, z.ZodTypeDef, TestIdIndex>;
+}, "strip", z.ZodTypeAny, {
+    type: "snapshot";
+    testId: string;
+    stepId: string;
+    commit: number;
+    ts: number;
+    tree: SerializedNode;
+    testIdIndex: TestIdIndex;
+}, {
+    type: "snapshot";
+    testId: string;
+    stepId: string;
+    commit: number;
+    ts: number;
+    tree: SerializedNode;
+    testIdIndex: TestIdIndex;
+}>;
+export type Snapshot = z.infer<typeof SnapshotSchema>;
+export declare function makeSnapshot(payload: Omit<Snapshot, 'type'>): Snapshot;
+export declare const A11yImpactSchema: z.ZodEnum<["minor", "moderate", "serious", "critical"]>;
+export type A11yImpact = z.infer<typeof A11yImpactSchema>;
+export declare const A11yViolationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"a11y:violation">;
+    ruleId: z.ZodString;
+    impact: z.ZodEnum<["minor", "moderate", "serious", "critical"]>;
+    description: z.ZodString;
+    help: z.ZodString;
+    helpUrl: z.ZodOptional<z.ZodString>;
+    targets: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "a11y:violation";
+    ruleId: string;
+    impact: "minor" | "moderate" | "serious" | "critical";
+    description: string;
+    help: string;
+    targets: string[];
+    helpUrl?: string | undefined;
+}, {
+    type: "a11y:violation";
+    ruleId: string;
+    impact: "minor" | "moderate" | "serious" | "critical";
+    description: string;
+    help: string;
+    targets: string[];
+    helpUrl?: string | undefined;
+}>;
+export type A11yViolation = z.infer<typeof A11yViolationSchema>;
+export declare function makeA11yViolation(payload: Omit<A11yViolation, 'type'>): A11yViolation;
+export declare const HmrStartSchema: z.ZodObject<{
+    type: z.ZodLiteral<"hmr:start">;
+}, "strip", z.ZodTypeAny, {
+    type: "hmr:start";
+}, {
+    type: "hmr:start";
+}>;
+export type HmrStart = z.infer<typeof HmrStartSchema>;
+export declare function makeHmrStart(): HmrStart;
+export declare const HmrEndSchema: z.ZodObject<{
+    type: z.ZodLiteral<"hmr:end">;
+}, "strip", z.ZodTypeAny, {
+    type: "hmr:end";
+}, {
+    type: "hmr:end";
+}>;
+export type HmrEnd = z.infer<typeof HmrEndSchema>;
+export declare function makeHmrEnd(): HmrEnd;
+export declare const RunEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"step:set">;
+    testId: z.ZodString;
+    stepId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "step:set";
+    testId: string;
+    stepId: string;
+}, {
+    type: "step:set";
+    testId: string;
+    stepId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"step:ack">;
+    testId: z.ZodString;
+    stepId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "step:ack";
+    testId: string;
+    stepId: string;
+}, {
+    type: "step:ack";
+    testId: string;
+    stepId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    role: z.ZodEnum<["probe", "runner"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "hello";
+    role: "probe" | "runner";
+}, {
+    type: "hello";
+    role: "probe" | "runner";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"snapshot">;
+    commit: z.ZodNumber;
+    testId: z.ZodString;
+    stepId: z.ZodString;
+    ts: z.ZodNumber;
+    tree: z.ZodType<SerializedNode, z.ZodTypeDef, SerializedNode>;
+    testIdIndex: z.ZodType<TestIdIndex, z.ZodTypeDef, TestIdIndex>;
+}, "strip", z.ZodTypeAny, {
+    type: "snapshot";
+    testId: string;
+    stepId: string;
+    commit: number;
+    ts: number;
+    tree: SerializedNode;
+    testIdIndex: TestIdIndex;
+}, {
+    type: "snapshot";
+    testId: string;
+    stepId: string;
+    commit: number;
+    ts: number;
+    tree: SerializedNode;
+    testIdIndex: TestIdIndex;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"test:end">;
+    testId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "test:end";
+    testId: string;
+}, {
+    type: "test:end";
+    testId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"a11y:violation">;
+    ruleId: z.ZodString;
+    impact: z.ZodEnum<["minor", "moderate", "serious", "critical"]>;
+    description: z.ZodString;
+    help: z.ZodString;
+    helpUrl: z.ZodOptional<z.ZodString>;
+    targets: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "a11y:violation";
+    ruleId: string;
+    impact: "minor" | "moderate" | "serious" | "critical";
+    description: string;
+    help: string;
+    targets: string[];
+    helpUrl?: string | undefined;
+}, {
+    type: "a11y:violation";
+    ruleId: string;
+    impact: "minor" | "moderate" | "serious" | "critical";
+    description: string;
+    help: string;
+    targets: string[];
+    helpUrl?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"hmr:start">;
+}, "strip", z.ZodTypeAny, {
+    type: "hmr:start";
+}, {
+    type: "hmr:start";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"hmr:end">;
+}, "strip", z.ZodTypeAny, {
+    type: "hmr:end";
+}, {
+    type: "hmr:end";
+}>]>;
+export type RunEvent = z.infer<typeof RunEventSchema>;
+export declare function parseRunEvent(raw: string): RunEvent | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,kBAAkB,yEAO7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAS1D,CAAC;AAKF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAoC,CAAC;AAQ1F,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,eAAO,MAAM,SAAS,gCAA8B,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,eAAO,MAAM,WAAW;;;;;;;;;EAGtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAEhD;AAED,eAAO,MAAM,aAAa;;;;;;;;;EAGxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;EAQzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,wBAAgB,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,QAAQ,CAEtE;AAID,eAAO,MAAM,gBAAgB,yDAAuD,CAAC;AACrF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;EAS9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,aAAa,CAErF;AAKD,eAAO,MAAM,cAAc;;;;;;EAA6C,CAAC;AACzE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,wBAAgB,YAAY,IAAI,QAAQ,CAEvC;AAED,eAAO,MAAM,YAAY;;;;;;EAA2C,CAAC;AACrE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IASzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAS/D"}

package/dist/index.js

@@ -0,0 +1,119 @@
+// @nativelens/event-protocol
+// Local mirror of the eventual @reactlens/event-protocol package (ADR 0002).
+// Schemas + canonical types for events flowing on the bus.
+import { z } from 'zod';
+// --- Component snapshot ---
+export const SerializedNodeKind = z.enum([
+    'host',
+    'function',
+    'class',
+    'memo',
+    'forwardRef',
+    'other',
+]);
+export const SerializedNodeSchema = z.lazy(() => z.object({
+    fiberId: z.number(),
+    name: z.string(),
+    kind: SerializedNodeKind,
+    props: z.record(z.string(), z.unknown()),
+    hooks: z.array(z.unknown()),
+    children: z.array(SerializedNodeSchema),
+}));
+export const TestIdIndexSchema = z.record(z.string(), z.number());
+// --- RunEvent: discriminated union of every event on the wire ---
+//
+// Each variant ships with a zod schema, a builder, and is included in
+// `parseRunEvent` for inbound decoding. Adding a new variant means: extend
+// the union below, add a builder, and add the schema to the discriminator.
+export const StepSetSchema = z.object({
+    type: z.literal('step:set'),
+    testId: z.string(),
+    stepId: z.string(),
+});
+export function makeStepSet(testId, stepId) {
+    return { type: 'step:set', testId, stepId };
+}
+export const StepAckSchema = z.object({
+    type: z.literal('step:ack'),
+    testId: z.string(),
+    stepId: z.string(),
+});
+export function makeStepAck(testId, stepId) {
+    return { type: 'step:ack', testId, stepId };
+}
+export const HelloRole = z.enum(['probe', 'runner']);
+export const HelloSchema = z.object({
+    type: z.literal('hello'),
+    role: HelloRole,
+});
+export function makeHello(role) {
+    return { type: 'hello', role };
+}
+export const TestEndSchema = z.object({
+    type: z.literal('test:end'),
+    testId: z.string(),
+});
+export function makeTestEnd(testId) {
+    return { type: 'test:end', testId };
+}
+export const SnapshotSchema = z.object({
+    type: z.literal('snapshot'),
+    commit: z.number(),
+    testId: z.string(),
+    stepId: z.string(),
+    ts: z.number(),
+    tree: SerializedNodeSchema,
+    testIdIndex: TestIdIndexSchema,
+});
+export function makeSnapshot(payload) {
+    return { type: 'snapshot', ...payload };
+}
+// `a11y:violation` carries over from reactlens unchanged (ADR 0005 §Event protocol).
+// The walker emits a Violation[]; the runner adapter sends one event per violation.
+export const A11yImpactSchema = z.enum(['minor', 'moderate', 'serious', 'critical']);
+export const A11yViolationSchema = z.object({
+    type: z.literal('a11y:violation'),
+    ruleId: z.string(),
+    impact: A11yImpactSchema,
+    description: z.string(),
+    help: z.string(),
+    helpUrl: z.string().optional(),
+    // testIDs of the affected elements (resolved via testIdIndex on the dashboard).
+    targets: z.array(z.string()),
+});
+export function makeA11yViolation(payload) {
+    return { type: 'a11y:violation', ...payload };
+}
+// HMR coordination events (P12, ADR pending) — signal Metro hot-reload
+// boundaries to the harness so snapshots emitted during a hot reload can be
+// discarded rather than mistaken for end-of-action commits.
+export const HmrStartSchema = z.object({ type: z.literal('hmr:start') });
+export function makeHmrStart() {
+    return { type: 'hmr:start' };
+}
+export const HmrEndSchema = z.object({ type: z.literal('hmr:end') });
+export function makeHmrEnd() {
+    return { type: 'hmr:end' };
+}
+export const RunEventSchema = z.discriminatedUnion('type', [
+    StepSetSchema,
+    StepAckSchema,
+    HelloSchema,
+    SnapshotSchema,
+    TestEndSchema,
+    A11yViolationSchema,
+    HmrStartSchema,
+    HmrEndSchema,
+]);
+export function parseRunEvent(raw) {
+    let candidate;
+    try {
+        candidate = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const result = RunEventSchema.safeParse(candidate);
+    return result.success ? result.data : undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@reynsu/nativelens-event-protocol",
+  "version": "0.1.1",
+  "description": "Canonical RunEvent union + Zod schemas for the nativelens event bus. Consumed by @nativelens/* packages and by reactlens once it migrates per ADR-0002.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reynsu/nativelens-protocol.git"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}

package/src/index.ts

@@ -0,0 +1,171 @@
+// @nativelens/event-protocol
+// Local mirror of the eventual @reactlens/event-protocol package (ADR 0002).
+// Schemas + canonical types for events flowing on the bus.
+
+import { z } from 'zod';
+
+// --- Component snapshot ---
+
+export const SerializedNodeKind = z.enum([
+  'host',
+  'function',
+  'class',
+  'memo',
+  'forwardRef',
+  'other',
+]);
+export type SerializedNodeKind = z.infer<typeof SerializedNodeKind>;
+
+export type SerializedNode = {
+  fiberId: number;
+  name: string;
+  kind: SerializedNodeKind;
+  props: Record<string, unknown>;
+  hooks: unknown[];
+  children: SerializedNode[];
+};
+
+export const SerializedNodeSchema: z.ZodType<SerializedNode> = z.lazy(() =>
+  z.object({
+    fiberId: z.number(),
+    name: z.string(),
+    kind: SerializedNodeKind,
+    props: z.record(z.string(), z.unknown()),
+    hooks: z.array(z.unknown()),
+    children: z.array(SerializedNodeSchema),
+  }),
+);
+
+// testID → fiberId map shipped alongside the tree on `component:snapshot`.
+// Last-write-wins on duplicate testIDs; the probe emits a warning when a
+// collision happens so users surface ambiguous locators.
+export type TestIdIndex = Record<string, number>;
+
+export const TestIdIndexSchema: z.ZodType<TestIdIndex> = z.record(z.string(), z.number());
+
+// --- RunEvent: discriminated union of every event on the wire ---
+//
+// Each variant ships with a zod schema, a builder, and is included in
+// `parseRunEvent` for inbound decoding. Adding a new variant means: extend
+// the union below, add a builder, and add the schema to the discriminator.
+
+export const StepSetSchema = z.object({
+  type: z.literal('step:set'),
+  testId: z.string(),
+  stepId: z.string(),
+});
+export type StepSet = z.infer<typeof StepSetSchema>;
+
+export function makeStepSet(testId: string, stepId: string): StepSet {
+  return { type: 'step:set', testId, stepId };
+}
+
+export const StepAckSchema = z.object({
+  type: z.literal('step:ack'),
+  testId: z.string(),
+  stepId: z.string(),
+});
+export type StepAck = z.infer<typeof StepAckSchema>;
+
+export function makeStepAck(testId: string, stepId: string): StepAck {
+  return { type: 'step:ack', testId, stepId };
+}
+
+export const HelloRole = z.enum(['probe', 'runner']);
+export type HelloRole = z.infer<typeof HelloRole>;
+
+export const HelloSchema = z.object({
+  type: z.literal('hello'),
+  role: HelloRole,
+});
+export type Hello = z.infer<typeof HelloSchema>;
+
+export function makeHello(role: HelloRole): Hello {
+  return { type: 'hello', role };
+}
+
+export const TestEndSchema = z.object({
+  type: z.literal('test:end'),
+  testId: z.string(),
+});
+export type TestEnd = z.infer<typeof TestEndSchema>;
+
+export function makeTestEnd(testId: string): TestEnd {
+  return { type: 'test:end', testId };
+}
+
+export const SnapshotSchema = z.object({
+  type: z.literal('snapshot'),
+  commit: z.number(),
+  testId: z.string(),
+  stepId: z.string(),
+  ts: z.number(),
+  tree: SerializedNodeSchema,
+  testIdIndex: TestIdIndexSchema,
+});
+export type Snapshot = z.infer<typeof SnapshotSchema>;
+
+export function makeSnapshot(payload: Omit<Snapshot, 'type'>): Snapshot {
+  return { type: 'snapshot', ...payload };
+}
+
+// `a11y:violation` carries over from reactlens unchanged (ADR 0005 §Event protocol).
+// The walker emits a Violation[]; the runner adapter sends one event per violation.
+export const A11yImpactSchema = z.enum(['minor', 'moderate', 'serious', 'critical']);
+export type A11yImpact = z.infer<typeof A11yImpactSchema>;
+
+export const A11yViolationSchema = z.object({
+  type: z.literal('a11y:violation'),
+  ruleId: z.string(),
+  impact: A11yImpactSchema,
+  description: z.string(),
+  help: z.string(),
+  helpUrl: z.string().optional(),
+  // testIDs of the affected elements (resolved via testIdIndex on the dashboard).
+  targets: z.array(z.string()),
+});
+export type A11yViolation = z.infer<typeof A11yViolationSchema>;
+
+export function makeA11yViolation(payload: Omit<A11yViolation, 'type'>): A11yViolation {
+  return { type: 'a11y:violation', ...payload };
+}
+
+// HMR coordination events (P12, ADR pending) — signal Metro hot-reload
+// boundaries to the harness so snapshots emitted during a hot reload can be
+// discarded rather than mistaken for end-of-action commits.
+export const HmrStartSchema = z.object({ type: z.literal('hmr:start') });
+export type HmrStart = z.infer<typeof HmrStartSchema>;
+
+export function makeHmrStart(): HmrStart {
+  return { type: 'hmr:start' };
+}
+
+export const HmrEndSchema = z.object({ type: z.literal('hmr:end') });
+export type HmrEnd = z.infer<typeof HmrEndSchema>;
+
+export function makeHmrEnd(): HmrEnd {
+  return { type: 'hmr:end' };
+}
+
+export const RunEventSchema = z.discriminatedUnion('type', [
+  StepSetSchema,
+  StepAckSchema,
+  HelloSchema,
+  SnapshotSchema,
+  TestEndSchema,
+  A11yViolationSchema,
+  HmrStartSchema,
+  HmrEndSchema,
+]);
+export type RunEvent = z.infer<typeof RunEventSchema>;
+
+export function parseRunEvent(raw: string): RunEvent | undefined {
+  let candidate: unknown;
+  try {
+    candidate = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  const result = RunEventSchema.safeParse(candidate);
+  return result.success ? result.data : undefined;
+}