@codeyam-editor/codeyam-editor 0.1.7 → 0.1.9

package/npm/scenario-playwright.js

@@ -334,16 +334,36 @@ async function collectVisibleTextLength(target) {
 }
 
 // Inject a capture-only stylesheet that snaps entrance animations to their
-// FINAL frame: remove animation/transition timing and force the common
-// "hidden until revealed" symptoms (`opacity:0`, an entrance `transform`) back
-// to their resting values. This is the belt to `scrollThroughDocument`'s
-// suspenders — it covers pure-CSS keyframe entrances that are mid-flight or
-// stuck at an `opacity:0` start state even after the observers fired. It
-// targets the generic CSS symptom, not any framework's reveal class, so it
-// works for any stack. The caller gates this OFF when a scenario declares an
-// interactive state, so an intentionally animated/collapsed interactive frame
-// is never clobbered. Idempotent (a single injected style id) and best-effort.
-// Returns true when the style is present after the call.
+// FINAL frame: remove animation/transition timing, then reveal the elements an
+// entrance animation left INVISIBLE. This is the belt to
+// `scrollThroughDocument`'s suspenders — it covers pure-CSS keyframe entrances
+// that are mid-flight or stuck at an `opacity:0` start state even after the
+// observers fired. It targets the generic CSS symptom, not any framework's
+// reveal class, so it works for any stack. The caller gates this OFF when a
+// scenario declares an interactive state, so an intentionally animated /
+// collapsed interactive frame is never clobbered. Idempotent (a single injected
+// style id) and best-effort. Returns true when the style is present after the
+// call.
+//
+// The reveal is per-element and conditional ON THE ELEMENT BEING INVISIBLE,
+// never a blanket `opacity: 1 !important` / `transform: none !important` over
+// `*`. A blanket rule cannot tell an entrance animation's `opacity: 0` from
+// DELIBERATE, resting state — a disabled control's dim, a muted row, a
+// collapsed chevron's rotation — so it silently flattened every one of them out
+// of every screenshot the capture pipeline produced. Two scenarios differing
+// only in such a state then captured byte-identically and collided in the
+// distinct-capture gate, and the collision was unfixable in the component: the
+// state rendered correctly in a real browser (verified: computed opacity 0.4 vs
+// 1) and was erased only at capture time. Anything already visible is now left
+// exactly as the app rendered it.
+//
+// The reveal's TRANSFORM half additionally stops at the SVG boundary, because a
+// CSS `transform` overrides the SVG `transform` presentation attribute: inside
+// an `<svg>` it erases the static geometry that CONSTRUCTS the drawing instead
+// of neutralizing an entrance animation, so a revealed SVG node lands on the
+// origin. Invisible SVG nodes are therefore revealed in place — opacity forced,
+// transform left alone. See the loop below for why the boundary is
+// `ownerSVGElement` rather than `closest("svg")`.
 async function forceFinalVisualState(target) {
   return target.evaluate(() => {
     const STYLE_ID = "__codeyam_force_final_state";
@@ -356,16 +376,54 @@ async function forceFinalVisualState(target) {
     if (typeof document.createElement !== "function") return false;
     const style = document.createElement("style");
     style.id = STYLE_ID;
+    // Temporal properties only — these carry no resting state, so removing
+    // them cannot erase anything the app meant to show.
     style.textContent =
       "*, *::before, *::after {" +
       "animation: none !important;" +
       "transition: none !important;" +
-      "opacity: 1 !important;" +
-      "transform: none !important;" +
       "}";
     const head = document.head || document.documentElement;
     if (!head || typeof head.appendChild !== "function") return false;
     head.appendChild(style);
+
+    // With animations disabled above, an element held back by an entrance
+    // animation now computes to its pre-animation resting state — typically
+    // `opacity: 0`, often paired with a translate/scale that parks it offscreen.
+    // Reveal exactly those, and only those: a fully transparent element shows
+    // nothing either way, so forcing it can hide no real state, while an element
+    // at any visible opacity is left untouched.
+    //
+    // The transform half of the reveal STOPS at the SVG boundary. A CSS
+    // `transform` overrides the SVG `transform` presentation attribute, so
+    // inside an `<svg>` a forced `transform: none` does not neutralize an
+    // entrance animation — it erases the static rotate/translate/scale that
+    // CONSTRUCTS the drawing, revealing the node collapsed on the origin. The
+    // opacity half is still right there (a node at ~0 shows nothing either
+    // way), so an invisible SVG node is revealed IN PLACE. The boundary test is
+    // `ownerSVGElement` and NOT `closest("svg")`: HTML inside a
+    // `<foreignObject>` is a real HTMLElement with no `ownerSVGElement`, so it
+    // keeps the full reveal — `closest("svg")` would silently strand its
+    // genuine CSS entrance transform.
+    if (typeof document.querySelectorAll !== "function") return true;
+    const INVISIBLE_EPSILON = 0.01;
+    for (const el of document.querySelectorAll("*")) {
+      let computed = null;
+      try {
+        computed = getComputedStyle(el);
+      } catch (_) {
+        continue;
+      }
+      if (!computed) continue;
+      const opacity = parseFloat(computed.opacity);
+      if (!Number.isFinite(opacity) || opacity > INVISIBLE_EPSILON) continue;
+      if (!el.style || typeof el.style.setProperty !== "function") continue;
+      const inSvg =
+        el.ownerSVGElement != null ||
+        (typeof el.tagName === "string" && el.tagName.toLowerCase() === "svg");
+      el.style.setProperty("opacity", "1", "important");
+      if (!inSvg) el.style.setProperty("transform", "none", "important");
+    }
     return true;
   });
 }
@@ -870,6 +928,59 @@ async function collectInteractiveLabels(frame) {
   }, INTERACTIVE_SELECTOR);
 }
 
+// How many candidate labels an error message may echo. Deliberately tighter
+// than `collectInteractiveLabels`' own 20-label read cap: the labels are the
+// USER'S page content, so every one printed is a line of their app leaked into
+// the terminal. Enough to answer "did you mean one of these?", not enough to
+// transcribe the page.
+const CANDIDATE_LABEL_CAP = 8;
+
+// Render the candidate labels for an error message, capped and counted. Shared
+// by the no-match and action-failed paths so the echo policy lives in one place.
+async function candidateLabelSummary(frame) {
+  const candidates = await collectInteractiveLabels(frame);
+  if (candidates.length === 0) return "(none found on page)";
+  const shown = candidates.slice(0, CANDIDATE_LABEL_CAP);
+  const rest = candidates.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")} (+${rest} more)` : shown.join(", ");
+}
+
+// Compose the "no element matched" error, branched on the form the caller
+// ACTUALLY passed. Pure and string-returning so both branches are asserted
+// without a browser.
+//
+// The substring advice ("prefer an exact CSS selector") only applies to a text
+// label. Printing it at a caller who already passed `#id` contradicts its own
+// input and reads as misdirection — the failure mode that sent two sessions
+// hunting a selector bug when the page had simply not hydrated. The candidate
+// labels ride with the text branch for the same reason: they answer "did you
+// mean one of these?", a question only a text match can have asked, and every
+// label printed is a line of the user's own page echoed into the terminal.
+function noMatchGuidance({ targetDesc, matchedByText, candidateLabels }) {
+  const queryParamHint =
+    `Many filter/status/sort states are also reachable directly via a ` +
+    `URL query param (e.g. add "?status=active" to the path) with no ` +
+    `interaction at all.`;
+  if (matchedByText) {
+    return (
+      `preview-interact: no element matched ${targetDesc}. ` +
+      `Text is matched as a case-insensitive SUBSTRING, so a misspelled or ` +
+      `over-specific label matches nothing — prefer an exact/role/testid CSS ` +
+      `selector (e.g. {"selector":"[data-testid=\\"save\\"]"}) for a precise ` +
+      `target. ${queryParamHint} ` +
+      `Candidate interactive labels: ${candidateLabels}`
+    );
+  }
+  return (
+    `preview-interact: no element matched ${targetDesc}. ` +
+    `That is already an exact CSS selector, so nothing on the page matches ` +
+    `it as written — confirm the element is present in THIS state (it may be ` +
+    `behind a tab, dialog, or conditional render), that the id/attribute is ` +
+    `spelled as the markup emits it, and that the page rendered and hydrated ` +
+    `at all. ${queryParamHint}`
+  );
+}
+
 // Describe the elements a substring text match resolved, so an ambiguity
 // warning can name the competing controls (e.g. the preset button "Bet" vs the
 // disclosure button "…or bet on"). Reads each matched element's inner text via
@@ -1017,17 +1128,17 @@ async function performInteraction(
   }
 
   if (matchCount === 0) {
-    const candidates = await collectInteractiveLabels(frame);
-    const candidateList =
-      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
+    // Candidate labels are collected ONLY for the text branch — see
+    // `noMatchGuidance` for why a CSS-selector miss neither needs them nor
+    // should echo the user's page content back at them.
     throw new Error(
-      `preview-interact: no element matched ${targetDesc}. ` +
-        `Text is matched as a case-insensitive SUBSTRING, so a misspelled or ` +
-        `over-specific label matches nothing — prefer an exact/role/testid CSS ` +
-        `selector (e.g. {"selector":"[data-testid=\\"save\\"]"}) for a precise ` +
-        `target. Many filter/status/sort states are also reachable directly via a ` +
-        `URL query param (e.g. add "?status=active" to the path) with no ` +
-        `interaction at all. Candidate interactive labels: ${candidateList}`,
+      noMatchGuidance({
+        targetDesc,
+        matchedByText,
+        candidateLabels: matchedByText
+          ? await candidateLabelSummary(frame)
+          : null,
+      }),
     );
   }
 
@@ -1069,12 +1180,9 @@ async function performInteraction(
         );
     }
   } catch (error) {
-    const candidates = await collectInteractiveLabels(frame);
-    const candidateList =
-      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
     throw new Error(
       `preview-interact: action "${action}" failed against ${targetDesc}: ${error.message || String(error)}. ` +
-        `Candidate interactive labels: ${candidateList}`,
+        `Candidate interactive labels: ${await candidateLabelSummary(frame)}`,
     );
   }
 }
@@ -1151,6 +1259,7 @@ async function performInteractionSequence(
 
 module.exports = {
   logCaptureTiming,
+  defaultReadServerState,
   resolveTcpTarget,
   assertAppPortReachable,
   escapeHtmlAttribute,
@@ -1172,6 +1281,8 @@ module.exports = {
   loadScenarioInIframe,
   loadScenarioTopLevel,
   collectInteractiveLabels,
+  candidateLabelSummary,
+  noMatchGuidance,
   describeMatchCandidates,
   performInteraction,
   waitForPredicate,

package/npm/utils.js

@@ -5,7 +5,23 @@ const fs = require("fs");
 const readline = require("readline");
 
 const rootDir = path.resolve(__dirname, "..");
-const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
+
+/**
+ * Path to the server-state file for `projectDir`.
+ *
+ * The editor server writes its state into the PROJECT it serves, not into the
+ * editor repo — so this must be resolved against the target project. It was
+ * previously a module-level const bound to `rootDir`, which made
+ * `readServerState` return `null` for every external-project launch and left
+ * the pid-based recovery in `stopServer` dead in exactly the configuration
+ * `codeyam-editor-dev` exists to serve.
+ *
+ * Defaults to `process.cwd()` because every in-repo caller already runs from
+ * the project root; external-project callers must pass their `projectDir`.
+ */
+function serverStatePathFor(projectDir = process.cwd()) {
+  return path.join(projectDir, ".codeyam", "server-state.json");
+}
 
 /**
  * Map (process.platform, process.arch) → the platform sub-package that
@@ -459,6 +475,56 @@ function resolveWrappedAppPort(merged, envValue, fallback) {
   return resolveLauncherPort(envValue, mergedValue, fallback);
 }
 
+/** True for a value usable as a TCP port: an integer in 1..=65535. */
+function isUsablePort(value) {
+  return Number.isInteger(value) && value > 0 && value <= 65535;
+}
+
+/**
+ * Resolve the control port a RUNNING server for `projectDir` is actually on.
+ *
+ * Mirrors `resolve_control_port` in
+ * `crates/codeyam-editor/src/commands/editor/control_port.rs`:
+ * `server-state.json` > `CODEYAM_CONTROL_PORT` > the config default. The
+ * editor server runs on a dynamic port whenever the Project Launcher or the
+ * desktop supervisor started it, and `editor.json`'s `proxy.controlPort` is
+ * only the static default — so `server-state.json` is the only reliable
+ * discriminator. The npm launchers used the INVERSE (config only, state file
+ * never consulted), which is why a `--restart` could target a port nothing was
+ * on while the live server sat on another.
+ *
+ * This resolves the port to SEARCH for, never the port to bind: the launcher
+ * deliberately binds the editor repo's own control port (see the comment at
+ * the `SERVER_PORT` resolution in `editor-dev.js`).
+ */
+function resolveRunningControlPort(projectDir = process.cwd(), configPort) {
+  const state = readServerState(projectDir);
+  if (state && isUsablePort(state.controlPort)) return state.controlPort;
+
+  const envValue = process.env.CODEYAM_CONTROL_PORT;
+  if (envValue !== undefined && envValue !== null && String(envValue).trim() !== "") {
+    const parsed = parseInt(String(envValue).trim(), 10);
+    if (isUsablePort(parsed)) return parsed;
+  }
+
+  return configPort;
+}
+
+/**
+ * Resolve the proxy HTTP port the server will bind for `projectDir`.
+ *
+ * Mirrors `resolve_proxy_http_port` in
+ * `crates/codeyam-editor/src/commands/start.rs`: `CODEYAM_PROXY_HTTP_PORT` >
+ * `proxy.httpPort` > 14100 (`default_http_port` in
+ * `crates/types/src/config.rs`). The start path binds this address
+ * unconditionally, so it is the port a second server actually collides on —
+ * the resource the control-port classification never looked at.
+ */
+function resolveProxyHttpPort(merged, envValue, fallback = 14100) {
+  const configured = merged && merged.proxy && merged.proxy.httpPort;
+  return resolveLauncherPort(envValue, configured, fallback);
+}
+
 /** Try to connect to a specific host:port. Returns true if something is listening. */
 function tryConnect(port, host) {
   return new Promise((resolve) => {
@@ -502,17 +568,17 @@ async function waitForPortToClose(port, timeoutMs = 10000, intervalMs = 200) {
   return false;
 }
 
-function readServerState() {
+function readServerState(projectDir = process.cwd()) {
   try {
-    return JSON.parse(fs.readFileSync(serverStatePath, "utf8"));
+    return JSON.parse(fs.readFileSync(serverStatePathFor(projectDir), "utf8"));
   } catch {
     return null;
   }
 }
 
-function clearServerState() {
+function clearServerState(projectDir = process.cwd()) {
   try {
-    fs.unlinkSync(serverStatePath);
+    fs.unlinkSync(serverStatePathFor(projectDir));
   } catch {}
 }
 
@@ -626,6 +692,100 @@ function formatCrossProjectError(port, holder, verb) {
   );
 }
 
+/**
+ * Build the "the proxy port this server must bind is already taken" error
+ * string. Lives next to the other `format*Error` builders so the wording is
+ * unit-testable without a running server. Names the port, the pid holding it,
+ * and the config key to change — the three things the old failure mode made
+ * the user dig out of `.codeyam/logs/editor-server.out.log` by hand.
+ */
+function formatProxyPortConflictError(httpPort, pids = []) {
+  const pidNote = pids.length > 0 ? ` (pid ${pids.join(", ")})` : "";
+  return (
+    `Port ${httpPort} is already in use${pidNote}, and the codeyam-editor ` +
+    `server binds it at startup — spawning now would fail with EADDRINUSE ` +
+    `and leave nothing listening.\n` +
+    `\n` +
+    `Free that port, or change httpPort in .codeyam/editor.local.json, e.g.:\n` +
+    `  codeyam-editor editor config-override proxy.httpPort ${httpPort + 100}`
+  );
+}
+
+/**
+ * Make sure the proxy HTTP port is free before a spawn that would bind it.
+ *
+ * The proxy port — not the control port — is the resource that actually
+ * conflicts: two servers for the same project legitimately resolve DIFFERENT
+ * control ports (the npm wrappers use the editor repo's config, the Rust binary
+ * uses the project's own), but both bind the project's `proxy.httpPort`. So a
+ * control-port classification can report "free" while the spawn is already
+ * doomed, which is exactly how a failed restart came to look like a successful
+ * one.
+ *
+ * Ownership is decided on the control port named by the project's own
+ * `server-state.json`, never by probing the identity endpoint through the proxy
+ * port itself: the proxy forwards to the wrapped app, so a probe there reports
+ * whatever the app answers and would misclassify this project's own server as
+ * foreign. Teardown likewise goes through the control port, where the shutdown
+ * endpoint lives.
+ *
+ * Returns `{ kind: "free" }`, `{ kind: "cleared" }` (a stale same-project server
+ * was stopped), or `{ kind: "conflict", pids }` — the caller owns the policy.
+ * Effects are injected so this is testable without a live server.
+ */
+async function ensureProxyPortAvailable(
+  httpPort,
+  projectDir = process.cwd(),
+  { classify = classifyPortHolder, stop = stopServer, isInUse = isPortInUse } = {},
+) {
+  if (!isUsablePort(httpPort) || !(await isInUse(httpPort))) {
+    return { kind: "free" };
+  }
+
+  const state = readServerState(projectDir);
+  const statePort = state && isUsablePort(state.controlPort) ? state.controlPort : null;
+  if (statePort !== null) {
+    const holder = await classify(statePort, projectDir);
+    if (holder.kind === "same-project") {
+      console.error(
+        `Port ${httpPort} is held by this project's own server on control ` +
+          `port ${statePort}; stopping it before starting a fresh one...`,
+      );
+      await stop(statePort, projectDir);
+      if (await waitForPortToClose(httpPort, 5000, 200)) {
+        return { kind: "cleared" };
+      }
+    }
+  }
+
+  return { kind: "conflict", pids: findListeningPids(httpPort) };
+}
+
+/**
+ * Build the "the launcher is not going to print a URL for a server that never
+ * came up" message, including the tail of the server output log.
+ *
+ * `tail` is the already-read log tail (see `readServerOutputLogTail`) or `null`
+ * when there was nothing readable — passed in rather than read here so the
+ * wording is testable without a filesystem, matching the other `format*Error`
+ * builders. The diagnostic was never missing from that log; it was written to a
+ * file nobody was told to read, which is why the tail is inlined into the
+ * message rather than merely pointed at.
+ */
+function formatLaunchFailureError(port, projectDir, tail = null) {
+  const logPath = path.join(projectDir, ".codeyam", "logs", "editor-server.out.log");
+  const head =
+    `Editor server is not listening on port ${port} — not printing a URL ` +
+    `that would refuse the connection.`;
+  if (tail === null) {
+    return (
+      `${head}\n\nNo readable ${logPath}; also check ` +
+      `${path.join(projectDir, ".codeyam", "logs", "editor-server.log")}.`
+    );
+  }
+  return `${head}\n\n--- tail of ${logPath} ---\n${tail}\n--- end of log tail ---`;
+}
+
 /**
  * Build the "server never bound the port" failure message, shown only after
  * the boot budget AND one automatic retry have both been exhausted. Pure
@@ -833,6 +993,47 @@ function openServerOutputLog(cwd) {
   }
 }
 
+/**
+ * Last `lines` non-empty-trailing lines of the launcher-managed server output
+ * log for `projectDir`, or `null` when there is nothing readable there.
+ *
+ * The diagnostic text for a failed launch was never missing — the exact
+ * `codeyam-editor cannot bind 127.0.0.1:<port>` line sat in this file the whole
+ * time. It was written to a file nobody was told to read, so the launcher
+ * surfaces the tail itself rather than printing a URL and exiting 0.
+ *
+ * Reads at most the trailing 64 KiB so a long-lived append-only log never costs
+ * a full file read. Best-effort by design: a missing or unreadable log degrades
+ * to `null`, never to a throw on the failure path.
+ */
+function readServerOutputLogTail(projectDir = process.cwd(), lines = 40) {
+  const MAX_TAIL_BYTES = 64 * 1024;
+  let fd = null;
+  try {
+    const logPath = path.join(projectDir, ".codeyam", "logs", "editor-server.out.log");
+    fd = fs.openSync(logPath, "r");
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, MAX_TAIL_BYTES);
+    if (length === 0) return null;
+    const buf = Buffer.alloc(length);
+    fs.readSync(fd, buf, 0, length, size - length);
+    const all = buf.toString("utf8").split("\n");
+    while (all.length > 0 && all[all.length - 1].trim() === "") all.pop();
+    if (all.length === 0) return null;
+    return all.slice(-lines).join("\n");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* best-effort close on a diagnostic-only read */
+      }
+    }
+  }
+}
+
 /**
  * Format one launcher-teardown-signal record for
  * `.codeyam/logs/launcher-signals.log`. Pure: every input is passed in, so the
@@ -965,23 +1166,23 @@ function findListeningPids(port, runLsof = defaultRunLsof, sleep = sleepSync) {
 }
 
 /** Stop the Rust backend server if it is running. */
-async function stopServer(port = 14199) {
+async function stopServer(port = 14199, projectDir = process.cwd()) {
   if (!(await isPortInUse(port))) {
-    clearServerState();
+    clearServerState(projectDir);
     return false;
   }
 
   if (await requestServerShutdown(port)) {
     if (await waitForPortToClose(port, 10000, 200)) {
-      clearServerState();
+      clearServerState(projectDir);
       return true;
     }
   }
 
-  const state = readServerState();
+  const state = readServerState(projectDir);
   if (state && Number.isInteger(state.pid) && tryKillPid(state.pid)) {
     if (await waitForPortToClose(port, 5000, 200)) {
-      clearServerState();
+      clearServerState(projectDir);
       return true;
     }
   }
@@ -991,20 +1192,37 @@ async function stopServer(port = 14199) {
   }
 
   if (await waitForPortToClose(port, 5000, 200)) {
-    clearServerState();
+    clearServerState(projectDir);
     return true;
   }
 
   throw new Error(`Server on port ${port} did not stop cleanly`);
 }
 
-/** Stop any existing server on the port, then start a fresh one. */
-async function restartServer(port = 14199) {
-  if (await isPortInUse(port)) {
-    console.error(`Stopping existing server on port ${port}...`);
-    await stopServer(port);
+/**
+ * Stop any existing server for this project, then start a fresh one on `port`.
+ *
+ * `port` is the port to BIND (owned by the editor repo's merged config); the
+ * port to TEAR DOWN is resolved separately via `resolveRunningControlPort`,
+ * because a server started outside the npm wrapper records a different, live
+ * control port in the project's `server-state.json`. Gating teardown on `port`
+ * alone is what let a stale server survive a restart and kill the relaunch with
+ * EADDRINUSE on the proxy port. Both are torn down (deduped) so the restart's
+ * historical guarantee — nothing left on the port we are about to bind — holds
+ * whichever port the live server turned out to be on.
+ */
+async function restartServer(port = 14199, projectDir = process.cwd()) {
+  const runningPort = resolveRunningControlPort(projectDir, port);
+  const seen = new Set();
+  for (const candidate of [runningPort, port]) {
+    if (!isUsablePort(candidate) || seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (await isPortInUse(candidate)) {
+      console.error(`Stopping existing server on port ${candidate}...`);
+      await stopServer(candidate, projectDir);
+    }
   }
-  return ensureServer(port);
+  return ensureServer(port, projectDir);
 }
 
 /**
@@ -1016,8 +1234,8 @@ async function restartServer(port = 14199) {
  * mismatch — silently choosing a different port would just relocate the
  * surprise.
  */
-async function ensureServer(port = 14199) {
-  const holder = await classifyPortHolder(port);
+async function ensureServer(port = 14199, projectDir = process.cwd()) {
+  const holder = await classifyPortHolder(port, projectDir);
   switch (holder.kind) {
     case "foreign":
       console.error(formatForeignListenerError(port));
@@ -1056,6 +1274,21 @@ async function ensureServer(port = 14199) {
       break;
   }
 
+  // The control port is free (or was just taken over), but that is not the port
+  // the spawn is most likely to die on. `start.rs` binds `proxy.httpPort`
+  // unconditionally, so a holder there is a guaranteed EADDRINUSE — knowable
+  // with one probe here, and previously discovered only by reading a log after
+  // a silent failure.
+  const proxyHttpPort = resolveProxyHttpPort(
+    readMergedEditorConfig(projectDir),
+    process.env.CODEYAM_PROXY_HTTP_PORT,
+  );
+  const proxyPort = await ensureProxyPortAvailable(proxyHttpPort, projectDir);
+  if (proxyPort.kind === "conflict") {
+    console.error(formatProxyPortConflictError(proxyHttpPort, proxyPort.pids));
+    process.exit(1);
+  }
+
   const binary = ensureBinary();
   const startTimeoutMs = resolveStartTimeoutMs();
 
@@ -1075,12 +1308,12 @@ async function ensureServer(port = 14199) {
   // editor-server.log). `unref()` keeps the detached child from pinning the
   // launcher's event loop alive on its own.
   const spawnAndAwait = async (timeoutMs) => {
-    const logFd = openServerOutputLog(process.cwd());
+    const logFd = openServerOutputLog(projectDir);
     const child = spawn(
       binary,
       ["start", "--no-open", "--port", String(port)],
       buildServerSpawnOptions({
-        cwd: process.cwd(),
+        cwd: projectDir,
         env: serverSpawnEnv(process.env, { devCheckout: isDevCheckout() }),
         logFd,
       }),
@@ -1215,7 +1448,7 @@ async function awaitServerReadyOrChildExit(child, port, waitForPortFn = waitForP
 
 module.exports = {
   rootDir,
-  serverStatePath,
+  serverStatePathFor,
   binaryName,
   brokerBinaryName,
   platformPackageInfo,
@@ -1241,6 +1474,9 @@ module.exports = {
   classifyPortHolder,
   formatForeignListenerError,
   formatCrossProjectError,
+  formatProxyPortConflictError,
+  formatLaunchFailureError,
+  ensureProxyPortAvailable,
   formatServerStartTimeoutError,
   resolveStartTimeoutMs,
   tryKillPid,
@@ -1264,4 +1500,8 @@ module.exports = {
   readMergedEditorConfig,
   resolveLauncherPort,
   resolveWrappedAppPort,
+  resolveRunningControlPort,
+  resolveProxyHttpPort,
+  isUsablePort,
+  readServerOutputLogTail,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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.7",
-    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.7",
-    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.7",
-    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.7"
+    "@codeyam-editor/codeyam-editor-darwin-arm64": "0.1.9",
+    "@codeyam-editor/codeyam-editor-darwin-x64": "0.1.9",
+    "@codeyam-editor/codeyam-editor-linux-x64": "0.1.9",
+    "@codeyam-editor/codeyam-editor-win32-x64": "0.1.9"
   },
   "keywords": [
     "codeyam",