@alloy-js/core 0.23.0-dev.9 → 0.24.0-dev.1

package/dist/dev/src/debug/message-format.test.js

@@ -0,0 +1,836 @@
+import { createComponent as _$createComponent } from "@alloy-js/core/jsx-runtime";
+/**
+ * Tests that verify the WebSocket message format produced by the server
+ * matches what the devtools frontend expects. Each test renders something,
+ * collects the raw JSON messages over the WebSocket, and checks the shape.
+ *
+ * Tests subscribe to specific channels to validate the subscription mechanism
+ * and avoid filtering noise from unrelated channels.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import WebSocket from "ws";
+import { createMessageCollector } from "../../testing/devtools-utils.js";
+import { Declaration } from "../components/Declaration.js";
+import { For } from "../components/For.js";
+import { Output } from "../components/Output.js";
+import { Scope } from "../components/Scope.js";
+import { SourceFile } from "../components/SourceFile.js";
+import { enableDevtools, resetDevtoolsServerForTests } from "../devtools/devtools-server.js";
+import { effect, ref } from "../reactivity.js";
+import { renderAsync } from "../render.js";
+import { flushJobsAsync } from "../scheduler.js";
+import { debug } from "./index.js";
+let socket;
+let port;
+beforeEach(async () => {
+  debug.effect.reset();
+  const server = await enableDevtools({
+    port: 0
+  });
+  port = server.port;
+  socket = new WebSocket(`ws://127.0.0.1:${port}`);
+  await new Promise((resolve, reject) => {
+    socket?.once("open", resolve);
+    socket?.once("error", reject);
+  });
+});
+afterEach(async () => {
+  if (socket) {
+    socket.close();
+    socket = undefined;
+  }
+  await resetDevtoolsServerForTests();
+  debug.effect.reset();
+});
+
+// ---------------------------------------------------------------------------
+// Subscriptions
+// ---------------------------------------------------------------------------
+
+describe("subscriptions", () => {
+  it("only receives messages for subscribed channels", async () => {
+    // Subscribe to render only — should NOT see effects, refs, etc.
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 60,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const types = new Set(messages.map(m => m.type));
+    // Should have render messages
+    expect(types.has("render:node_added")).toBe(true);
+    // Should NOT have effect/ref/symbol/scope/edge messages
+    expect(types.has("effect:added")).toBe(false);
+    expect(types.has("ref:added")).toBe(false);
+    expect(types.has("symbol:added")).toBe(false);
+    expect(types.has("scope:added")).toBe(false);
+  });
+  it("receives messages from multiple subscribed channels", async () => {
+    const collector = await createMessageCollector(socket, ["render", "effects", "refs"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 80,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const types = new Set(messages.map(m => m.type));
+    expect(types.has("render:node_added")).toBe(true);
+    expect(types.has("effect:added")).toBe(true);
+    expect(types.has("ref:added")).toBe(true);
+    // Not subscribed to these
+    expect(types.has("symbol:added")).toBe(false);
+    expect(types.has("scope:added")).toBe(false);
+  });
+  it("lifecycle signals are received regardless of subscription", async () => {
+    // Subscribe to nothing useful — lifecycle signals bypass subscriptions
+    const collector = await createMessageCollector(socket, ["diagnostics"]);
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 96,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    expect(messages.some(m => m.type === "render:complete")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// render channel
+// ---------------------------------------------------------------------------
+
+describe("render:node_added", () => {
+  it("root node has null parent_id and kind 'root'", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 111,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const root = messages.find(m => m.type === "render:node_added" && m.kind === "root");
+    expect(root).toMatchObject({
+      type: "render:node_added",
+      id: expect.any(Number),
+      parent_id: null,
+      kind: "root",
+      seq: expect.any(Number)
+    });
+  });
+  it("component node has numeric id, parent_id, and name", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 129,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const output = messages.find(m => m.type === "render:node_added" && m.name === "Output");
+    expect(output).toMatchObject({
+      type: "render:node_added",
+      id: expect.any(Number),
+      parent_id: expect.any(Number),
+      kind: "component",
+      name: "Output"
+    });
+  });
+  it("text node has string value", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 147,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const text = messages.find(m => m.type === "render:node_added" && m.kind === "text");
+    expect(text).toBeDefined();
+    expect(text.value).toBe("hello");
+    expect(text.parent_id).toEqual(expect.any(Number));
+  });
+  it("non-text node has null value (not undefined)", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 161,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const component = messages.find(m => m.type === "render:node_added" && m.kind === "component");
+    expect(component.value).toBeNull();
+  });
+});
+describe("render:node_removed", () => {
+  it("is emitted when a reactive component removes children", async () => {
+    const show = ref(true);
+    const collector = await createMessageCollector(socket, ["render"]);
+    function Conditional() {
+      return () => show.value ? "visible" : "";
+    }
+    await renderAsync(_$createComponent(Output, {
+      get children() {
+        return _$createComponent(Conditional, {}, {
+          fileName: import.meta.url,
+          lineNumber: 183,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 182,
+      columnNumber: 7
+    }));
+    const renderMessages = await collector.waitForRender();
+
+    // Verify the text node "visible" was added
+    const textAdded = renderMessages.find(m => m.type === "render:node_added" && m.value === "visible");
+    expect(textAdded).toBeDefined();
+
+    // Toggle visibility to trigger removal
+    show.value = false;
+    await flushJobsAsync();
+    const flushMessages = await collector.waitForFlush();
+    collector.stop();
+    const removed = flushMessages.filter(m => m.type === "render:node_removed");
+    expect(removed.length).toBeGreaterThan(0);
+    expect(removed[0]).toMatchObject({
+      type: "render:node_removed",
+      id: expect.any(Number)
+    });
+  });
+});
+describe("render:node_updated", () => {
+  it("emits node_added during reactive list growth", async () => {
+    const items = ref(["a"]);
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      get children() {
+        return _$createComponent(For, {
+          each: items,
+          children: item => [item]
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 217,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 216,
+      columnNumber: 7
+    }));
+    await collector.waitForRender();
+
+    // Add an item to trigger reactive update
+    items.value = [...items.value, "b"];
+    await flushJobsAsync();
+    const flushMessages = await collector.waitForFlush();
+    collector.stop();
+
+    // Reactive updates produce new node_added messages for new content
+    const added = flushMessages.filter(m => m.type === "render:node_added");
+    expect(added.length).toBeGreaterThan(0);
+    // Should contain the new "b" text node
+    const bNode = added.find(m => m.value === "b");
+    expect(bNode).toBeDefined();
+  });
+});
+describe("render:reset", () => {
+  it("is sent before node_added messages", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 240,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const renderMessages = messages.filter(m => m.type === "render:reset" || m.type === "render:node_added" || m.type === "render:complete");
+    expect(renderMessages[0]).toMatchObject({
+      type: "render:reset"
+    });
+  });
+});
+describe("render:complete", () => {
+  it("is sent after all node_added messages", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 257,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const renderMessages = messages.filter(m => m.type === "render:reset" || m.type === "render:node_added" || m.type === "render:complete");
+    const last = renderMessages[renderMessages.length - 1];
+    expect(last).toMatchObject({
+      type: "render:complete"
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// effects channel
+// ---------------------------------------------------------------------------
+
+describe("effect:added", () => {
+  it("has id, effect_type, and seq", async () => {
+    const collector = await createMessageCollector(socket, ["effects"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 279,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const effects = messages.filter(m => m.type === "effect:added");
+    expect(effects.length).toBeGreaterThan(0);
+    const e = effects[0];
+    expect(e).toMatchObject({
+      type: "effect:added",
+      id: expect.any(Number),
+      seq: expect.any(Number)
+    });
+    expect("effect_type" in e).toBe(true);
+  });
+});
+describe("effect:updated", () => {
+  it("is emitted when an effect's component is set", async () => {
+    const collector = await createMessageCollector(socket, ["effects"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 299,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const updated = messages.filter(m => m.type === "effect:updated");
+    // Effects get updated with component info during render
+    if (updated.length > 0) {
+      expect(updated[0]).toMatchObject({
+        type: "effect:updated"
+      });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// refs channel
+// ---------------------------------------------------------------------------
+
+describe("ref:added", () => {
+  it("has id, kind, and seq", async () => {
+    const collector = await createMessageCollector(socket, ["refs"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 320,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const refs = messages.filter(m => m.type === "ref:added");
+    expect(refs.length).toBeGreaterThan(0);
+    const r = refs[0];
+    expect(r).toMatchObject({
+      type: "ref:added",
+      id: expect.any(Number),
+      seq: expect.any(Number)
+    });
+    // kind is nullable
+    expect("kind" in r).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// edges channel
+// ---------------------------------------------------------------------------
+
+describe("edge:track and edge:trigger", () => {
+  it("emits edge messages with effect_id and ref_id", async () => {
+    const collector = await createMessageCollector(socket, ["edges"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 345,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const edges = messages.filter(m => m.type === "edge:track" || m.type === "edge:trigger");
+    expect(edges.length).toBeGreaterThan(0);
+    const edge = edges[0];
+    expect(edge).toMatchObject({
+      seq: expect.any(Number),
+      effect_id: expect.any(Number)
+    });
+    // ref_id is present (may be null for some edge types)
+    expect("ref_id" in edge).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// symbols channel
+// ---------------------------------------------------------------------------
+
+describe("symbol:added", () => {
+  it("has id, name, boolean flags, and seq", async () => {
+    const collector = await createMessageCollector(socket, ["symbols"]);
+    await renderAsync(_$createComponent(Output, {
+      get children() {
+        return _$createComponent(Scope, {
+          name: "myScope",
+          get children() {
+            return _$createComponent(Declaration, {
+              name: "Foo",
+              children: "foo content"
+            }, {
+              fileName: import.meta.url,
+              lineNumber: 374,
+              columnNumber: 11
+            });
+          }
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 373,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 372,
+      columnNumber: 7
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const symbols = messages.filter(m => m.type === "symbol:added");
+    expect(symbols.length).toBeGreaterThan(0);
+    const sym = symbols.find(m => m.name === "Foo");
+    expect(sym).toBeDefined();
+    expect(sym).toMatchObject({
+      type: "symbol:added",
+      id: expect.any(Number),
+      name: "Foo",
+      seq: expect.any(Number)
+    });
+    // Boolean flags are 0/1 integers
+    expect([0, 1]).toContain(sym.is_member);
+    expect([0, 1]).toContain(sym.is_transient);
+    expect([0, 1]).toContain(sym.is_alias);
+    // Nullable fields exist as keys
+    expect("scope_id" in sym).toBe(true);
+    expect("owner_symbol_id" in sym).toBe(true);
+    expect("metadata" in sym).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scopes channel
+// ---------------------------------------------------------------------------
+
+describe("scope:added", () => {
+  it("has id, name, is_member_scope, and seq", async () => {
+    const collector = await createMessageCollector(socket, ["scopes"]);
+    await renderAsync(_$createComponent(Output, {
+      get children() {
+        return _$createComponent(Scope, {
+          name: "TestScope",
+          children: "content"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 412,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 411,
+      columnNumber: 7
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const scopes = messages.filter(m => m.type === "scope:added");
+    expect(scopes.length).toBeGreaterThan(0);
+    const scope = scopes.find(s => s.name === "TestScope");
+    expect(scope).toBeDefined();
+    expect(scope).toMatchObject({
+      type: "scope:added",
+      id: expect.any(Number),
+      name: "TestScope",
+      seq: expect.any(Number)
+    });
+    expect([0, 1]).toContain(scope.is_member_scope);
+    expect("parent_id" in scope).toBe(true);
+    expect("metadata" in scope).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// files channel
+// ---------------------------------------------------------------------------
+
+describe("file:added", () => {
+  it("has path, filetype, and seq", async () => {
+    const collector = await createMessageCollector(socket, ["files"]);
+    await renderAsync(_$createComponent(Output, {
+      get children() {
+        return _$createComponent(SourceFile, {
+          path: "test.ts",
+          filetype: "typescript",
+          children: "content"
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 444,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 443,
+      columnNumber: 7
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const files = messages.filter(m => m.type === "file:added");
+    expect(files.length).toBeGreaterThan(0);
+    const file = files.find(f => f.path.endsWith("test.ts"));
+    expect(file).toBeDefined();
+    expect(file).toMatchObject({
+      type: "file:added",
+      path: expect.stringContaining("test.ts"),
+      filetype: "typescript",
+      seq: expect.any(Number)
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// directories channel
+// ---------------------------------------------------------------------------
+
+describe("directory:added", () => {
+  it("has path and seq", async () => {
+    const collector = await createMessageCollector(socket, ["directories"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 473,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const dirs = messages.filter(m => m.type === "directory:added");
+    expect(dirs.length).toBeGreaterThan(0);
+    expect(dirs[0]).toMatchObject({
+      type: "directory:added",
+      path: expect.any(String),
+      seq: expect.any(Number)
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scheduler channel
+// ---------------------------------------------------------------------------
+
+describe("scheduler:job", () => {
+  it("is emitted during synchronous flush", async () => {
+    // Scheduler events are only traced during synchronous flushJobs(),
+    // not flushJobsAsync(). Subscribe to scheduler + render to see them.
+    const collector = await createMessageCollector(socket, ["scheduler", "render"]);
+    // A simple render triggers flushJobs internally
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 501,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const jobs = messages.filter(m => m.type === "scheduler:job");
+    // Scheduler events occur during the synchronous flush inside renderAsync
+    if (jobs.length > 0) {
+      expect(jobs[0]).toMatchObject({
+        type: "scheduler:job",
+        seq: expect.any(Number)
+      });
+      expect("event" in jobs[0] || "jobs_run" in jobs[0]).toBe(true);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// lifecycle channel
+// ---------------------------------------------------------------------------
+
+describe("effect:lifecycle", () => {
+  it("is emitted for effect lifecycle events", async () => {
+    const collector = await createMessageCollector(socket, ["lifecycle"]);
+    const r = ref(0);
+    effect(() => {
+      void r.value;
+    });
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 529,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+
+    // Trigger a lifecycle event
+    r.value = 1;
+    await flushJobsAsync();
+    const flushMessages = await collector.waitForFlush();
+    collector.stop();
+    const all = [...messages, ...flushMessages];
+    const lifecycle = all.filter(m => m.type === "effect:lifecycle");
+    if (lifecycle.length > 0) {
+      expect(lifecycle[0]).toMatchObject({
+        type: "effect:lifecycle",
+        seq: expect.any(Number)
+      });
+      expect("effect_id" in lifecycle[0]).toBe(true);
+      expect("event" in lifecycle[0]).toBe(true);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// diagnostics channel
+// ---------------------------------------------------------------------------
+
+describe("diagnostics:report", () => {
+  it("has message, severity, and seq", async () => {
+    const {
+      insertDiagnostic
+    } = await import("./trace-writer.js");
+    const collector = await createMessageCollector(socket, ["diagnostics"]);
+
+    // Insert a diagnostic directly through the trace writer
+    insertDiagnostic("test warning", "warning", undefined, undefined, undefined, undefined);
+
+    // Render to get a completion signal for the collector
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 571,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const diags = messages.filter(m => m.type === "diagnostics:report");
+    expect(diags.length).toBeGreaterThan(0);
+    expect(diags[0]).toMatchObject({
+      type: "diagnostics:report",
+      message: "test warning",
+      severity: "warning",
+      seq: expect.any(Number)
+    });
+    // Nullable source location fields exist
+    expect("source_file" in diags[0]).toBe(true);
+    expect("source_line" in diags[0]).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// errors channel
+// ---------------------------------------------------------------------------
+
+describe("render:error", () => {
+  it("has name, message, and seq", async () => {
+    const {
+      insertRenderError
+    } = await import("./trace-writer.js");
+    const collector = await createMessageCollector(socket, ["errors"]);
+
+    // Insert an error directly through the trace writer
+    insertRenderError("Error", "kaboom", "Error: kaboom\n  at ...", undefined);
+
+    // Render to get a completion signal
+    await renderAsync(_$createComponent(Output, {}, {
+      fileName: import.meta.url,
+      lineNumber: 603,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const errors = messages.filter(m => m.type === "render:error");
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toMatchObject({
+      type: "render:error",
+      name: "Error",
+      message: "kaboom",
+      seq: expect.any(Number)
+    });
+    expect("stack" in errors[0]).toBe(true);
+    expect("component_stack" in errors[0]).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// flushJobs:complete lifecycle signal
+// ---------------------------------------------------------------------------
+
+describe("flushJobs:complete", () => {
+  it("is emitted after a reactive flush", async () => {
+    const items = ref(["a"]);
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      get children() {
+        return _$createComponent(For, {
+          each: items,
+          children: item => [item]
+        }, {
+          fileName: import.meta.url,
+          lineNumber: 632,
+          columnNumber: 9
+        });
+      }
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 631,
+      columnNumber: 7
+    }));
+    await collector.waitForRender();
+    items.value = ["a", "b"];
+    await flushJobsAsync();
+    const flushMessages = await collector.waitForFlush();
+    collector.stop();
+
+    // waitForFlush resolves on flushJobs:complete, so if we get here it was received
+    expect(flushMessages.some(m => m.type === "flushJobs:complete")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// debugger:info (connection handshake)
+// ---------------------------------------------------------------------------
+
+describe("debugger:info", () => {
+  it("is sent on connection before any other messages", async () => {
+    // Close the existing socket so the server accepts a new one
+    socket.close();
+    await new Promise(resolve => setTimeout(resolve, 100));
+    const freshSocket = new WebSocket(`ws://127.0.0.1:${port}`);
+    const firstMessage = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("No debugger:info received")), 3000);
+      freshSocket.once("message", data => {
+        clearTimeout(timeout);
+        resolve(JSON.parse(String(data)));
+      });
+    });
+    await new Promise((resolve, reject) => {
+      freshSocket.once("open", resolve);
+      freshSocket.once("error", reject);
+    });
+    const first = await firstMessage;
+    freshSocket.close();
+    // Replace socket so afterEach doesn't close an already-closed socket
+    socket = undefined;
+    expect(first).toMatchObject({
+      type: "debugger:info",
+      version: expect.any(String)
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// null vs undefined contract
+// ---------------------------------------------------------------------------
+
+describe("null vs undefined contract", () => {
+  it("nullable fields arrive as null (not undefined or missing)", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 695,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+
+    // Root node: parent_id should be explicit null
+    const root = messages.find(m => m.type === "render:node_added" && m.kind === "root");
+    expect(root).toBeDefined();
+    expect(root.parent_id).toBeNull();
+    expect("parent_id" in root).toBe(true);
+
+    // Component node: value should be null, not undefined
+    const component = messages.find(m => m.type === "render:node_added" && m.kind === "component");
+    expect(component).toBeDefined();
+    expect(component.value).toBeNull();
+    expect("value" in component).toBe(true);
+
+    // source_file is nullable
+    expect("source_file" in root).toBe(true);
+  });
+  it("non-null fields have correct types", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 723,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const text = messages.find(m => m.type === "render:node_added" && m.kind === "text");
+    expect(text).toBeDefined();
+    // value is a string for text nodes
+    expect(typeof text.value).toBe("string");
+    // id is always a number
+    expect(typeof text.id).toBe("number");
+    // parent_id is a number for non-root nodes
+    expect(typeof text.parent_id).toBe("number");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// seq ordering
+// ---------------------------------------------------------------------------
+
+describe("seq ordering", () => {
+  it("messages have monotonically increasing seq", async () => {
+    const collector = await createMessageCollector(socket, ["render"]);
+    await renderAsync(_$createComponent(Output, {
+      children: "hello"
+    }, {
+      fileName: import.meta.url,
+      lineNumber: 748,
+      columnNumber: 23
+    }));
+    const messages = await collector.waitForRender();
+    collector.stop();
+    const seqs = messages.filter(m => typeof m.seq === "number").map(m => m.seq);
+    for (let i = 1; i < seqs.length; i++) {
+      expect(seqs[i]).toBeGreaterThan(seqs[i - 1]);
+    }
+  });
+});
+//# sourceMappingURL=message-format.test.js.map