@codeyam-editor/codeyam-editor 0.1.2 → 0.1.4

package/npm/scenario-playwright.js

@@ -219,6 +219,73 @@ async function waitForAnimationsSettled(
   return { settled: false, elapsedMs: Date.now() - started };
 }
 
+// Track in-flight network requests on a Playwright page so a capture can wait
+// for client-side data fetches to settle before screenshotting. The
+// resource-timing API (`performance.getEntriesByType("resource")`) only records
+// COMPLETED requests, so it cannot see a fetch that is still in flight — the
+// exact window where a client-fetch page shows a loading skeleton. We count
+// request starts against finishes/failures instead. Returns a live view:
+// `inFlight()` is the current outstanding count and `lastActivityMs()` is the
+// timestamp of the most recent request start OR completion (0 when the page has
+// made no requests since the tracker attached). Attach BEFORE navigation so
+// every request is counted. Stack-agnostic — it observes raw HTTP activity, not
+// any framework's fetch wrapper.
+function createNetworkTracker(page) {
+  let inFlight = 0;
+  let lastActivityMs = 0;
+  const bump = () => {
+    lastActivityMs = Date.now();
+  };
+  if (page && typeof page.on === "function") {
+    page.on("request", () => {
+      inFlight += 1;
+      bump();
+    });
+    const settle = () => {
+      inFlight = Math.max(0, inFlight - 1);
+      bump();
+    };
+    page.on("requestfinished", settle);
+    page.on("requestfailed", settle);
+  }
+  return {
+    inFlight: () => inFlight,
+    lastActivityMs: () => lastActivityMs,
+  };
+}
+
+// Bounded network-quiet wait: after the DOM is stable a client-side data fetch
+// can still be in flight — the loading skeleton is gone but the fetched rows
+// haven't replaced it yet, so a screenshot here catches the in-between frame.
+// Wait until no request has been outstanding for `quietWindowMs`, hard-capped at
+// `overallTimeoutMs`. Two properties matter:
+//   - A page that made NO requests (lastActivityMs stays 0) is already quiet and
+//     returns on the first poll, so server-rendered captures incur no extra wait.
+//   - A streaming / long-poll endpoint that never goes idle hits the cap and the
+//     caller captures anyway — the wait can never hang the capture.
+async function waitForNetworkQuiet(
+  tracker,
+  { quietWindowMs = 500, overallTimeoutMs = 5000, pollIntervalMs = 100 } = {},
+) {
+  const started = Date.now();
+  while (Date.now() - started < overallTimeoutMs) {
+    const idleForMs = Date.now() - tracker.lastActivityMs();
+    if (tracker.inFlight() === 0 && idleForMs >= quietWindowMs) {
+      const elapsedMs = Date.now() - started;
+      logCaptureTiming("network-quiet", { outcome: "quiet", elapsedMs });
+      return { quiet: true, elapsedMs };
+    }
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  const elapsedMs = Date.now() - started;
+  logCaptureTiming("network-quiet", {
+    outcome: "capped",
+    elapsedMs,
+    inFlight: tracker.inFlight(),
+  });
+  return { quiet: false, elapsedMs };
+}
+
 // `loadingMarkers` are the project's app-specific loading strings (from
 // stack.json `capture.loadingMarkers`); they extend the codeyam-harness
 // defaults so a stable-but-still-loading app screen counts as "not ready"
@@ -233,15 +300,41 @@ async function waitForStablePage(page, target, timeoutMs = 10000, loadingMarkers
   while (Date.now() - started < timeoutMs) {
     await page.waitForTimeout(500);
 
-    const pageState = await target.evaluate(() => ({
-      bodyText: document.body?.innerText ?? "",
-      html: document.body?.innerHTML ?? "",
-    }));
+    const pageState = await target.evaluate(() => {
+      const getById = document.getElementById;
+      const root =
+        typeof getById === "function" ? document.getElementById("root") : null;
+      return {
+        bodyText: document.body?.innerText ?? "",
+        html: document.body?.innerHTML ?? "",
+        // Whether the SPA mount point exists AND has painted anything. An
+        // existing-but-empty `<div id="root">` is the pre-paint window of a
+        // slow-first-paint scenario (e.g. a live-session app that spends a few
+        // seconds connecting before the gate UI mounts). `rootExists` lets us
+        // distinguish that from a mid-redirect/teardown `null` body, where
+        // there is no root to wait on and a stable-empty page is legitimately
+        // settled.
+        rootExists: !!root,
+        rootChildCount: root ? root.childElementCount : 0,
+      };
+    });
 
     lastHadLoadingMarkers = hasLoadingMarkers(pageState.bodyText, loadingMarkers);
     lastHtmlChanged = pageState.html !== lastHtml;
 
-    if (!lastHadLoadingMarkers && !lastHtmlChanged) {
+    // A mounted-but-unpainted root is "still loading", not "settled": the HTML
+    // can sit byte-stable for a second or two while the SPA boots, which would
+    // otherwise satisfy the stability check and capture a blank frame before
+    // first paint. Treat an existing root with zero children AND no body text
+    // as not-ready so the loop keeps polling until the app actually paints (or
+    // the overall timeout fires, by which point real content is present). A
+    // `null` body (rootExists=false) is unaffected — it stays trivially stable.
+    const rootUnpainted =
+      pageState.rootExists &&
+      pageState.rootChildCount === 0 &&
+      (pageState.bodyText ?? "").trim().length === 0;
+
+    if (!lastHadLoadingMarkers && !lastHtmlChanged && !rootUnpainted) {
       stableCount += 1;
       if (stableCount >= 2) {
         const remaining = () => Math.max(0, timeoutMs - (Date.now() - started));
@@ -339,6 +432,88 @@ async function loadScenarioTopLevel(
   return { frame: page.mainFrame(), response };
 }
 
+// Collect up to 20 distinct visible labels of interactive elements on the
+// page — buttons, links, role=button, form controls, <summary>, and anything
+// with an onclick. Used to build an ACTIONABLE error when an interaction's
+// target matches nothing: the agent reliably knows a label it rendered, so
+// listing the real candidates turns a silent blank capture into a "did you
+// mean one of these?" hint. Pure read (no clicks); falls back to value /
+// aria-label / placeholder when an element has no text.
+async function collectInteractiveLabels(frame) {
+  return frame.evaluate(() => {
+    const selector =
+      "button, a[href], [role=button], input, select, textarea, summary, [onclick]";
+    const nodes = Array.from(document.querySelectorAll(selector));
+    const labels = nodes
+      .map((node) => {
+        const text =
+          (node.innerText || node.textContent || "").trim() ||
+          (typeof node.value === "string" ? node.value.trim() : "") ||
+          (node.getAttribute && node.getAttribute("aria-label")) ||
+          (node.getAttribute && node.getAttribute("placeholder")) ||
+          "";
+        return String(text).trim();
+      })
+      .filter((label) => label.length > 0);
+    return Array.from(new Set(labels)).slice(0, 20);
+  });
+}
+
+// Drive a single user-style interaction against the settled frame before the
+// screenshot, so an interactive state (expanded accordion, open modal, filled
+// field) can be captured without editing app source.
+//
+// The target is matched by visible `text` (preferred — the agent reliably
+// knows the label it rendered) or a CSS `selector`. `action` is click / fill /
+// press; `value` carries the text for `fill` or the key for `press` (e.g.
+// `Enter`). On a no-match target this THROWS with the list of candidate
+// interactive labels — the capture script's outer catch turns that into a
+// failed capture with an actionable message, never a silent blank screenshot.
+async function performInteraction(frame, interaction, { timeoutMs = 5000 } = {}) {
+  const { action, selector, text, value } = interaction || {};
+
+  let locator;
+  let targetDesc;
+  if (typeof text === "string" && text.length > 0) {
+    locator = frame.getByText(text, { exact: false }).first();
+    targetDesc = `text "${text}"`;
+  } else if (typeof selector === "string" && selector.length > 0) {
+    locator = frame.locator(selector).first();
+    targetDesc = `selector "${selector}"`;
+  } else {
+    throw new Error(
+      "preview-interact: interaction requires a `text` or `selector` target",
+    );
+  }
+
+  const matchCount = await locator.count();
+  if (matchCount === 0) {
+    const candidates = await collectInteractiveLabels(frame);
+    const candidateList =
+      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
+    throw new Error(
+      `preview-interact: no element matched ${targetDesc}. ` +
+        `Candidate interactive labels: ${candidateList}`,
+    );
+  }
+
+  switch (action) {
+    case "click":
+      await locator.click({ timeout: timeoutMs });
+      break;
+    case "fill":
+      await locator.fill(value ?? "", { timeout: timeoutMs });
+      break;
+    case "press":
+      await locator.press(value || "Enter", { timeout: timeoutMs });
+      break;
+    default:
+      throw new Error(
+        `preview-interact: unknown action "${action}" (expected click | fill | press)`,
+      );
+  }
+}
+
 module.exports = {
   logCaptureTiming,
   resolveTcpTarget,
@@ -349,7 +524,11 @@ module.exports = {
   collectImageStates,
   waitForImagesSettled,
   waitForAnimationsSettled,
+  createNetworkTracker,
+  waitForNetworkQuiet,
   waitForStablePage,
   loadScenarioInIframe,
   loadScenarioTopLevel,
+  collectInteractiveLabels,
+  performInteraction,
 };

package/npm/utils.js

@@ -8,14 +8,20 @@ const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
 
 /**
  * Map (process.platform, process.arch) → the platform sub-package that
- * carries the matching native binary. Kept as a small data table so adding
- * a new platform (e.g. linux/arm64) is one entry, not a new branch.
+ * carries the matching native binaries. Each sub-package ships TWO
+ * binaries side-by-side in its `bin/` dir: the `codeyam-editor` monolith
+ * and the dedicated `codeyam-editor-pty-broker` daemon (its own
+ * executable file / inode, for a stable honest process name). They live
+ * in the same dir so the broker auto-spawn's sibling-of-current-exe
+ * resolution finds the broker next to the monolith with no copying.
+ * Kept as a small data table so adding a new platform (e.g. linux/arm64)
+ * is one entry, not a new branch.
  */
 const PLATFORM_PACKAGES = {
-  "darwin-arm64": { pkg: "@codeyam-editor/codeyam-editor-darwin-arm64", binary: "codeyam-editor" },
-  "darwin-x64":   { pkg: "@codeyam-editor/codeyam-editor-darwin-x64",   binary: "codeyam-editor" },
-  "linux-x64":    { pkg: "@codeyam-editor/codeyam-editor-linux-x64",    binary: "codeyam-editor" },
-  "win32-x64":    { pkg: "@codeyam-editor/codeyam-editor-win32-x64",    binary: "codeyam-editor.exe" },
+  "darwin-arm64": { pkg: "@codeyam-editor/codeyam-editor-darwin-arm64", binary: "codeyam-editor", broker: "codeyam-editor-pty-broker" },
+  "darwin-x64":   { pkg: "@codeyam-editor/codeyam-editor-darwin-x64",   binary: "codeyam-editor", broker: "codeyam-editor-pty-broker" },
+  "linux-x64":    { pkg: "@codeyam-editor/codeyam-editor-linux-x64",    binary: "codeyam-editor", broker: "codeyam-editor-pty-broker" },
+  "win32-x64":    { pkg: "@codeyam-editor/codeyam-editor-win32-x64",    binary: "codeyam-editor.exe", broker: "codeyam-editor-pty-broker.exe" },
 };
 
 /**
@@ -27,6 +33,14 @@ function binaryName(platform = process.platform) {
   return platform === "win32" ? "codeyam-editor.exe" : "codeyam-editor";
 }
 
+/**
+ * Platform-correct executable filename for the dedicated broker binary.
+ * Mirrors {@link binaryName} for the second shipped binary.
+ */
+function brokerBinaryName(platform = process.platform) {
+  return platform === "win32" ? "codeyam-editor-pty-broker.exe" : "codeyam-editor-pty-broker";
+}
+
 /** Look up the platform sub-package metadata for a given platform/arch pair. */
 function platformPackageInfo(platform = process.platform, arch = process.arch) {
   return PLATFORM_PACKAGES[`${platform}-${arch}`] || null;
@@ -62,10 +76,25 @@ function findBinary() {
   }
 
   const name = binaryName();
-  const devCandidates = [
-    path.join(rootDir, "target", "debug", name),
-    path.join(rootDir, "target", "release", name),
-  ];
+  // Target directories to search, in precedence order. A custom
+  // CARGO_TARGET_DIR (cloud VMs set CARGO_TARGET_DIR=/codeyam-build-target)
+  // wins over the default ./target — cargo builds ONLY into the configured
+  // dir, so ./target may be stale or absent. Honoring it here keeps
+  // `ensureBinary` from building successfully and then failing to locate the
+  // result. CARGO_TARGET_DIR may be absolute or relative to the workspace
+  // root; path.resolve handles both (an absolute value ignores rootDir).
+  const targetDirs = [];
+  const customTarget = process.env.CARGO_TARGET_DIR;
+  if (customTarget) {
+    targetDirs.push(path.resolve(rootDir, customTarget));
+  }
+  targetDirs.push(path.join(rootDir, "target"));
+
+  const devCandidates = [];
+  for (const dir of targetDirs) {
+    devCandidates.push(path.join(dir, "debug", name));
+    devCandidates.push(path.join(dir, "release", name));
+  }
   for (const candidate of devCandidates) {
     if (fs.existsSync(candidate)) return candidate;
   }
@@ -133,48 +162,71 @@ function ensureBinary() {
     console.error("Binary not found after build.");
     process.exit(1);
   }
+  verifyBrokerBinaryPresent(binary);
   return binary;
 }
 
-/** Resolve the UI dist directory for the binary to serve. */
-function uiDistDir() {
-  return path.join(rootDir, "ui", "dist");
-}
-
 /**
- * True when `cwd` IS the editor repo root (or is nested under it), so the
- * wrapper is being used to develop the editor itself rather than against an
- * external client project. Compares realpath-resolved paths so a symlinked
- * checkout (`~/work/foo` → `/Volumes/dev/foo`) still matches — the same
- * convention `crates/control-api/src/state.rs:203` documents for the
- * server-side identity probe.
- *
- * Pure and synchronous (uses `fs.realpathSync`). On a realpath failure (an
- * unreadable path, race with a moved file) the un-resolved value is used as
- * a fallback — the same defensive shape `canonicalisePath` uses, so the
- * wrapper never bails on a transient fs hiccup.
- *
- * Gate for the dev wrapper's passthrough `cargo build`: when the target
- * project is the editor itself, rebuilding makes sense (the developer is
- * iterating on editor source). When it is any other project, the rebuild
- * does nothing of value and ripples into the stale-binary watcher's
- * SIGUSR1 re-exec, resetting the user's session for no reason. The
- * `CODEYAM_DEV_REBUILD=1` env preserves the one legitimate "editing the
- * editor against a client project" workflow.
+ * Resolve the dedicated broker binary path. Mirrors {@link findBinary}:
+ * the published platform sub-package ships it next to the monolith, and
+ * a dev `cargo build` produces it under target/debug|release. Returns
+ * null if it can't be located — the Rust broker auto-spawn then falls
+ * back to the monolith `editor pty-broker daemon` shim, so a missing
+ * broker binary degrades gracefully rather than breaking the editor.
  */
-function isSelfHostTarget(cwd, repoRoot) {
-  const safeReal = (p) => {
+function findBrokerBinary() {
+  const info = platformPackageInfo();
+  if (info && info.broker) {
     try {
-      return fs.realpathSync(p);
-    } catch {
-      return p;
+      const resolved = require.resolve(`${info.pkg}/bin/${info.broker}`, {
+        paths: [rootDir],
+      });
+      if (fs.existsSync(resolved)) return resolved;
+    } catch (e) {
+      if (e.code !== "MODULE_NOT_FOUND") throw e;
     }
-  };
-  const cwdReal = safeReal(cwd);
-  const repoReal = safeReal(repoRoot);
-  if (cwdReal === repoReal) return true;
-  const sep = path.sep;
-  return cwdReal.startsWith(repoReal.endsWith(sep) ? repoReal : repoReal + sep);
+  }
+
+  const name = brokerBinaryName();
+  const targetDirs = [];
+  const customTarget = process.env.CARGO_TARGET_DIR;
+  if (customTarget) {
+    targetDirs.push(path.resolve(rootDir, customTarget));
+  }
+  targetDirs.push(path.join(rootDir, "target"));
+
+  for (const dir of targetDirs) {
+    for (const profile of ["debug", "release"]) {
+      const candidate = path.join(dir, profile, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Best-effort check that the dedicated broker binary sits next to the
+ * monolith (the layout the broker auto-spawn's sibling resolution
+ * expects). Logs a one-line note when it's missing — never throws or
+ * exits, because the Rust side degrades to the monolith shim. `monolith`
+ * is the resolved monolith binary path; the broker is expected as its
+ * sibling.
+ */
+function verifyBrokerBinaryPresent(monolith) {
+  const sibling = path.join(path.dirname(monolith), brokerBinaryName());
+  if (fs.existsSync(sibling)) return;
+  const located = findBrokerBinary();
+  if (located) return;
+  console.error(
+    "Note: dedicated broker binary (codeyam-editor-pty-broker) not found next to " +
+    `${monolith}. The PTY broker will fall back to the monolith \`editor pty-broker daemon\` ` +
+    "shim. Reinstall the platform sub-package, or run `cargo build -p codeyam-pty-broker`."
+  );
+}
+
+/** Resolve the UI dist directory for the binary to serve. */
+function uiDistDir() {
+  return path.join(rootDir, "ui", "dist");
 }
 
 /**
@@ -568,6 +620,114 @@ function tryKillPid(pid) {
   }
 }
 
+/**
+ * True when the launcher is attached to an interactive terminal — i.e. a human
+ * could have typed Ctrl+C. Headless / agent-driven launchers (cloud containers,
+ * `npm run editor` under a supervisor) have no tty here. Used to decide whether a
+ * received SIGINT is a deliberate "stop the editor" (forward it) or a stray
+ * group / spurious signal that must NOT reap the now-detached server.
+ */
+function isInteractiveLauncher(stream = process.stdout) {
+  return Boolean(stream && stream.isTTY);
+}
+
+/**
+ * Spawn options for the editor server child. The server is spawned `detached:
+ * true` so it leads its OWN session + process group (setsid), decoupling its
+ * lifetime from the launcher's controlling terminal and process group — a stray
+ * tty Ctrl+C or a group-wide `kill(-pgid, SIGINT)` can no longer reach it. stdio
+ * is detached from the terminal for the same reason (an inherited tty can still
+ * deliver tty signals to a detached child): stdout/stderr go to `logFd` when one
+ * is supplied, else are ignored — the Rust server writes its own
+ * `.codeyam/logs/editor-server.log` regardless.
+ */
+function buildServerSpawnOptions({ cwd, env, logFd = null }) {
+  return {
+    stdio: logFd === null ? "ignore" : ["ignore", logFd, logFd],
+    cwd,
+    detached: true,
+    env,
+  };
+}
+
+/**
+ * Open (creating dirs as needed) the launcher-managed server stdout/stderr log
+ * in append mode and return its fd, or null if it can't be opened. Kept separate
+ * from the Rust server's own structured `editor-server.log` so the two streams
+ * never interleave. Best-effort: a failure here just means the detached server's
+ * stdio is ignored, never that the launch itself fails.
+ */
+function openServerOutputLog(cwd) {
+  try {
+    const dir = path.join(cwd, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    return fs.openSync(path.join(dir, "editor-server.out.log"), "a");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format one launcher-teardown-signal record for
+ * `.codeyam/logs/launcher-signals.log`. Pure: every input is passed in, so the
+ * formatting is unit-testable without a real signal or `ps`. Captures the
+ * launcher's own pid/ppid/pgid, whether it was interactive (a tty Ctrl+C) vs
+ * headless (a stray/spurious signal), the decision taken (forwarded teardown vs
+ * kept the server alive), and a best-effort `ps` group snapshot so the SENDER of
+ * a spurious `kill()` can be identified on the next repro.
+ */
+function formatLauncherSignalRecord({ signal, pid, ppid, pgid, interactive, forwarded, ps, timestamp }) {
+  const lines = [
+    `[${timestamp}] launcher-signal signal=${signal} pid=${pid} ppid=${ppid} pgid=${pgid} ` +
+      `interactive=${interactive} action=${forwarded ? "forwarded-teardown" : "ignored-kept-server-alive"}`,
+  ];
+  if (ps && ps.trim() !== "") {
+    lines.push(ps.trimEnd());
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Append a launcher-teardown-signal forensic record. Called from each launcher's
+ * SIGINT handler BEFORE it decides whether to forward, so a server reaped by a
+ * stray group SIGINT (or a spurious `kill()` to a headless launcher) always
+ * leaves a trail naming the launcher's process group. Best-effort: never throws,
+ * so a logging failure can never block the teardown decision.
+ */
+function logLauncherTeardownSignal(signal, projectDir, { interactive, forwarded }) {
+  try {
+    const pid = process.pid;
+    const ppid = typeof process.ppid === "number" ? process.ppid : -1;
+    let pgid = -1;
+    let ps = "";
+    if (process.platform !== "win32") {
+      const pgidOut = spawnSync("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8" });
+      if (!pgidOut.error) {
+        pgid = parseInt(pgidOut.stdout.trim(), 10);
+      }
+      if (Number.isInteger(pgid) && pgid > 0) {
+        const grp = spawnSync("ps", ["-o", "pid,ppid,pgid,tpgid,comm", "-g", String(pgid)], { encoding: "utf8" });
+        if (!grp.error) ps = grp.stdout;
+      }
+    }
+    const dir = path.join(projectDir, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    const record = formatLauncherSignalRecord({
+      signal,
+      pid,
+      ppid,
+      pgid,
+      interactive: Boolean(interactive),
+      forwarded: Boolean(forwarded),
+      ps,
+      timestamp: new Date().toISOString(),
+    });
+    fs.appendFileSync(path.join(dir, "launcher-signals.log"), record);
+  } catch {
+    /* best-effort forensics — never block teardown on a logging failure */
+  }
+}
+
 /**
  * Send the platform-correct termination signal to a spawned child process.
  * Used by editor.js / editor-dev.js / container.js when the user hits Ctrl+C —
@@ -674,12 +834,29 @@ async function ensureServer(port = 14199) {
   const binary = ensureBinary();
   // UI bundle is embedded in the Rust binary; CODEYAM_EDITOR_UI_DIR is
   // now an explicit dev-override only.
-  const child = spawn(binary, ["start", "--no-open", "--port", String(port)], {
-    stdio: "inherit",
-    cwd: process.cwd(),
-    detached: false,
-    env: process.env,
-  });
+  //
+  // The server is spawned into its OWN session/process group (detached: true)
+  // with stdio detached from the launcher's controlling terminal, so a stray
+  // tty Ctrl+C or a group-wide SIGINT can no longer reap it — its lifetime is
+  // governed only by the launcher's deliberate teardown forward and the
+  // pidfile / API-shutdown paths. stdout/stderr are appended to
+  // `.codeyam/logs/editor-server.out.log` (the Rust server also writes its own
+  // editor-server.log). `unref()` keeps the detached child from pinning the
+  // launcher's event loop alive on its own.
+  const logFd = openServerOutputLog(process.cwd());
+  const child = spawn(
+    binary,
+    ["start", "--no-open", "--port", String(port)],
+    buildServerSpawnOptions({ cwd: process.cwd(), env: process.env, logFd }),
+  );
+  if (logFd !== null) {
+    try {
+      fs.closeSync(logFd);
+    } catch {
+      /* child holds its own dup of the fd; the launcher's copy is no longer needed */
+    }
+  }
+  child.unref();
 
   const { outcome, exitedBeforeBind } = await awaitServerReadyOrChildExit(child, port);
 
@@ -688,7 +865,8 @@ async function ensureServer(port = 14199) {
     const detail = signal != null ? `signal ${signal}` : `code ${code}`;
     console.error(
       `codeyam-editor server exited (${detail}) before binding port ${port}. ` +
-        "Likely a preflight bail; see output above.",
+        "Likely a preflight bail; see .codeyam/logs/editor-server.out.log " +
+        "and .codeyam/logs/editor-server.log.",
     );
     // Always propagate as a real failure — even on code 0 the caller
     // needs to know the server isn't running.
@@ -734,11 +912,13 @@ module.exports = {
   rootDir,
   serverStatePath,
   binaryName,
+  brokerBinaryName,
   platformPackageInfo,
   PLATFORM_PACKAGES,
   findBinary,
+  findBrokerBinary,
+  verifyBrokerBinaryPresent,
   ensureBinary,
-  isSelfHostTarget,
   staleBinaryBanner,
   enforceFreshBinary,
   uiDistDir,
@@ -760,6 +940,11 @@ module.exports = {
   restartServer,
   ensureServer,
   awaitServerReadyOrChildExit,
+  isInteractiveLauncher,
+  buildServerSpawnOptions,
+  openServerOutputLog,
+  formatLauncherSignalRecord,
+  logLauncherTeardownSignal,
   killChildProcess,
   deepMergeJson,
   stripUnderscoreTopLevelKeys,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Language-agnostic managed execution sandbox for scenario-driven development",
   "bin": {
     "codeyam-editor": "./npm/cli.js"
@@ -9,10 +9,10 @@
     "playwright": "^1.58.2"
   },
   "optionalDependencies": {
-    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.2",
-    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.2",
-    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.2",
-    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.2"
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.4",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.4",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.4",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.4"
   },
   "keywords": [
     "codeyam",