@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/scenario-playwright.js

@@ -146,20 +146,54 @@ function defaultReadServerState() {
   return JSON.parse(fs.readFileSync(statePath, "utf8"));
 }
 
-// Resolve the `localhost` origin that serves the iframe-harness route. The
-// harness is mounted on the editor's control-api listener, whose port is
-// recorded in `.codeyam/server-state.json` as `controlPort` (the same file the
-// top-level loader already reads for `appPort`). Returns
-// `http://localhost:<controlPort>` — a secure context the nested iframe
-// inherits — or null when the state file is missing/unreadable, in which case
-// the caller falls back to the legacy in-page `setContent` harness.
-// `readStateFile` is injectable so the resolver is unit-testable without disk.
-function resolveHarnessOrigin({ readStateFile = defaultReadServerState } = {}) {
+// Resolve the loopback origin that serves the iframe-harness route. The harness
+// is mounted on the editor's control-api listener, whose port is recorded in
+// `.codeyam/server-state.json` as `controlPort` (the same file the top-level
+// loader already reads for `appPort`). Returns `http://127.0.0.1:<controlPort>`
+// — a secure context the nested iframe inherits, exactly as `localhost` is — or
+// null when the state file is missing/unreadable, in which case the caller falls
+// back to the legacy in-page `setContent` harness. `readStateFile` is injectable
+// so the resolver is unit-testable without disk.
+//
+// The HOST is taken from `targetUrl` — the URL the iframe will load — and only
+// the port comes from server-state. That mirroring is load-bearing, because the
+// two capture modes address the editor by different loopback spellings:
+// `/__codeyam_preview` captures are pinned to `127.0.0.1` (PROXY_CAPTURE_LOOPBACK
+// in handlers.rs, matching the forwarder's own pinning) while direct app-port
+// captures use `localhost`. `localhost` and `127.0.0.1` are DIFFERENT sites to
+// the cookie jar, so whenever the harness host and the iframe host disagree the
+// nested load is cross-site — and the `cy_session` cookie is `SameSite=Lax`,
+// which rides top-level navigations only. It is therefore withheld from the
+// iframe request (and from the `/api/*` calls the framed page makes), and the
+// token-gated routes answer 401 on a non-loopback bind.
+//
+// Hardcoding EITHER spelling only moves the failure between the two modes:
+// `localhost` 401s every `/__codeyam_preview` capture, `127.0.0.1` 401s the
+// framed page's own `/api/scenarios` + `/api/render-environment` calls. Raising
+// the cookie to `SameSite=None` fixes neither — Chromium rejects `None` without
+// `Secure`, and these origins are plain http. Mirroring the target's host is what
+// keeps the harness same-site in both modes, which is also the same-origin model
+// the `/__codeyam_preview` subpath proxy exists to provide.
+//
+// `targetUrl` omitted or unparseable falls back to `127.0.0.1`, the spelling the
+// proxy-route capture (the token-gated one) uses.
+function resolveHarnessOrigin({
+  readStateFile = defaultReadServerState,
+  targetUrl = null,
+} = {}) {
   try {
     const state = readStateFile();
     const port = state && state.controlPort;
     if (typeof port === "number" && port > 0) {
-      return `http://localhost:${port}`;
+      let host = "127.0.0.1";
+      if (targetUrl) {
+        try {
+          host = new URL(targetUrl).hostname || host;
+        } catch (_) {
+          /* unparseable target — keep the proxy-route default */
+        }
+      }
+      return `http://${host}:${port}`;
     }
   } catch (_) {
     /* missing/unreadable state — fall back to setContent */
@@ -336,6 +370,110 @@ async function forceFinalVisualState(target) {
   });
 }
 
+// Center the isolated-component wrapper in the viewport before the shot.
+//
+// The capture pipeline always shoots the full viewport (`page.screenshot({
+// fullPage: false })`) and never an element clip, so an isolation page that
+// does not center its own component strands it in the top-left corner of every
+// frame. Next.js does this in its isolation layout and the query-param stacks
+// do it in `.codeyam/harness/isolate.tsx`, but the server-rendered scaffolds
+// historically did not — and neither do pages hand-authored before that was
+// fixed. This pass closes the gap at capture time, for any stack.
+//
+// It MEASURES rather than assumes: a wrapper that is already centered is left
+// alone, so pages that already do the right thing are byte-identical. The
+// `#codeyam-capture` marker (the cross-stack isolation convention; expo emits
+// it via `nativeID`) is the gate, so an ordinary route capture is never
+// touched. Centering is applied to `<body>` and to each ancestor strictly
+// between body and the wrapper — never to the wrapper itself, which frequently
+// carries the component's own padding/background and must keep its own box.
+// Each axis independently falls back to `flex-start` when the wrapper overflows
+// the viewport, so an oversized component loses its bottom/right edge rather
+// than being clipped symmetrically out of its top/left one.
+//
+// Idempotent (a single injected style id), best-effort, and returns a small
+// result object describing what it did.
+async function centerCaptureWrapper(target) {
+  return target.evaluate(() => {
+    const STYLE_ID = "__codeyam_center_capture";
+    const ANCESTOR_CLASS = "__codeyam-center-ancestor";
+    // Subpixel layout and fractional scrollbar widths make exact gap equality
+    // unreliable; a couple of px of slop keeps already-centered pages on the
+    // no-op branch.
+    const TOLERANCE_PX = 2;
+
+    if (typeof document.getElementById !== "function") {
+      return { applied: false, reason: "no-dom" };
+    }
+    if (document.getElementById(STYLE_ID)) {
+      return { applied: false, reason: "already-applied" };
+    }
+    const wrapper = document.getElementById("codeyam-capture");
+    if (!wrapper || typeof wrapper.getBoundingClientRect !== "function") {
+      return { applied: false, reason: "no-capture-marker" };
+    }
+
+    const rect = wrapper.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    const leftGap = rect.left;
+    const rightGap = viewportWidth - rect.right;
+    const topGap = rect.top;
+    const bottomGap = viewportHeight - rect.bottom;
+
+    const fitsHorizontally = rect.width <= viewportWidth;
+    const fitsVertically = rect.height <= viewportHeight;
+    const centeredHorizontally =
+      fitsHorizontally && Math.abs(leftGap - rightGap) <= TOLERANCE_PX;
+    const centeredVertically =
+      fitsVertically && Math.abs(topGap - bottomGap) <= TOLERANCE_PX;
+
+    if (centeredHorizontally && centeredVertically) {
+      return { applied: false, reason: "already-centered" };
+    }
+
+    const horizontal = fitsHorizontally ? "center" : "flex-start";
+    const vertical = fitsVertically ? "center" : "flex-start";
+
+    // Stamp the ancestor chain so the injected rule targets exactly the
+    // elements between <body> and the wrapper and cannot leak elsewhere.
+    let node = wrapper.parentElement;
+    while (node && node !== document.body) {
+      if (node.classList && typeof node.classList.add === "function") {
+        node.classList.add(ANCESTOR_CLASS);
+      }
+      node = node.parentElement;
+    }
+
+    if (typeof document.createElement !== "function") {
+      return { applied: false, reason: "no-dom" };
+    }
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent =
+      "body, ." +
+      ANCESTOR_CLASS +
+      " {" +
+      "margin: 0;" +
+      "min-height: 100vh;" +
+      "display: flex;" +
+      "align-items: " +
+      vertical +
+      ";" +
+      "justify-content: " +
+      horizontal +
+      ";" +
+      "}";
+    const head = document.head || document.documentElement;
+    if (!head || typeof head.appendChild !== "function") {
+      return { applied: false, reason: "no-dom" };
+    }
+    head.appendChild(style);
+    return { applied: true, horizontal, vertical };
+  });
+}
+
 async function collectImageStates(target) {
   return target.evaluate(() =>
     Array.from(document.images || []).map((img) => ({
@@ -575,9 +713,31 @@ async function loadScenarioInIframe(
     // and the nested scenario iframe inherits it (the Sveltia-class fix). The
     // inner iframe `src` is still `url`, so the document-response probe above is
     // unchanged.
-    await page.goto(buildHarnessUrl(resolvedHarnessOrigin, url, background), {
+    const harnessUrl = buildHarnessUrl(resolvedHarnessOrigin, url, background);
+    const harnessResponse = await page.goto(harnessUrl, {
       waitUntil: "domcontentloaded",
     });
+    // Fail loudly on a fail-closed harness-auth rejection BEFORE the blind 30s
+    // `#scenario-frame` wait below. On a non-loopback (0.0.0.0 / cloud) bind the
+    // harness control-API route is session-token-gated; a generated
+    // `.codeyam/capture.js` (or an editor binary) that predates the `cy_session`
+    // cookie injection navigates without a token -> the server refuses the
+    // request with 401 -> the harness document never renders -> every component
+    // scenario times out on `#scenario-frame` with a generic Playwright error
+    // that hides the real cause. Surfacing the 401 here turns that blind timeout
+    // into a one-line root cause on the very first failing capture, naming both
+    // fixes. (Route/page scenarios navigate top-level to the un-gated app proxy,
+    // so they never hit this path.)
+    if (harnessResponse && harnessResponse.status() === 401) {
+      throw new Error(
+        `Capture harness route ${harnessUrl} returned 401 (fail-closed ` +
+          `session-token auth on a non-loopback bind). The capture script did not ` +
+          `send the \`cy_session\` token — most often a generated ` +
+          `\`.codeyam/capture.js\` (or an editor binary) that predates session-token ` +
+          `injection. Fixes: refresh the editor binary on this VM, or set ` +
+          `\`CODEYAM_INSECURE_BIND=1\` and restart the editor.`,
+      );
+    }
   } else {
     // Degraded fallback: no resolvable harness origin (server-state missing), so
     // use the legacy in-page harness. The top-level document is then
@@ -677,6 +837,14 @@ async function loadScenarioTopLevel(
   }
 }
 
+// The CSS selector for "clickable / interactive" elements — buttons, links,
+// role=button, form controls, <summary>, and anything with an onclick. Shared
+// by the candidate-label collector (below) and the text-target resolver
+// (`resolveTextTarget`), which prefers an interactive element over a plain
+// text node when a click/press label matches both.
+const INTERACTIVE_SELECTOR =
+  "button, a[href], [role=button], input, select, textarea, summary, [onclick]";
+
 // 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
@@ -685,9 +853,7 @@ async function loadScenarioTopLevel(
 // 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]";
+  return frame.evaluate((selector) => {
     const nodes = Array.from(document.querySelectorAll(selector));
     const labels = nodes
       .map((node) => {
@@ -701,7 +867,39 @@ async function collectInteractiveLabels(frame) {
       })
       .filter((label) => label.length > 0);
     return Array.from(new Set(labels)).slice(0, 20);
-  });
+  }, INTERACTIVE_SELECTOR);
+}
+
+// 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
+// Playwright's `allInnerTexts`, caps the list at 5, and trims each to a single
+// short line. Pure read; degrades to a count-only description if the locator
+// API or the page can't produce texts.
+async function describeMatchCandidates(baseLocator, matchCount) {
+  const CAP = 5;
+  const MAX_LEN = 60;
+  let texts = [];
+  try {
+    if (typeof baseLocator.allInnerTexts === "function") {
+      texts = await baseLocator.allInnerTexts();
+    }
+  } catch (_) {
+    texts = [];
+  }
+  const described = texts
+    .map((t) => String(t).replace(/\s+/g, " ").trim())
+    .filter((t) => t.length > 0)
+    .slice(0, CAP)
+    .map((t) => (t.length > MAX_LEN ? `${t.slice(0, MAX_LEN)}…` : t))
+    .map((t) => `"${t}"`);
+  if (described.length === 0) {
+    return [`${matchCount} elements (text unavailable)`];
+  }
+  if (matchCount > described.length) {
+    described.push(`…and ${matchCount - described.length} more`);
+  }
+  return described;
 }
 
 // Drive a single user-style interaction against the settled frame before the
@@ -714,16 +912,103 @@ async function collectInteractiveLabels(frame) {
 // `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 } = {}) {
+//
+// Resolve a visible-text target to the element most likely intended, instead
+// of blindly taking the first substring hit. A bare
+// `getByText(text, { exact: false })` is a case-insensitive SUBSTRING match, so
+// a label can land on a plain text node or a placeholder rather than the chip /
+// button the agent meant (observed: a `"Japan"` click hit placeholder text, not
+// the chip; a `"Bet"` click hit a disclosure button described "or bet on"). We
+// try increasingly-loose locators in priority order and take the first that
+// matches anything:
+//   1. exact + interactive   (for click/press)
+//   2. exact
+//   3. substring + interactive   (for click/press)
+//   4. substring
+// so an exact, clickable element wins over a substring plain-text node. Returns
+// the winning tier's locator plus its match count; when nothing matches at all,
+// returns the substring locator (count 0) so the caller's zero-match error path
+// still fires with its candidate-label hint.
+async function resolveTextTarget(frame, text, action) {
+  const preferInteractive = action === "click" || action === "press";
+  const exactBase = frame.getByText(text, { exact: true });
+  const substrBase = frame.getByText(text, { exact: false });
+
+  const tiers = [];
+  // `.and()` (Playwright ≥1.34) intersects two locators to the elements
+  // matching both — here, the text element that is ALSO interactive. Guard on
+  // its presence so a locator without `.and` degrades to text-only tiers.
+  if (preferInteractive && typeof exactBase.and === "function") {
+    const interactive = frame.locator(INTERACTIVE_SELECTOR);
+    tiers.push(exactBase.and(interactive));
+    tiers.push(exactBase);
+    tiers.push(substrBase.and(interactive));
+    tiers.push(substrBase);
+  } else {
+    tiers.push(exactBase);
+    tiers.push(substrBase);
+  }
+
+  for (const loc of tiers) {
+    const count = await loc.count();
+    if (count > 0) {
+      return { baseLocator: loc, matchCount: count };
+    }
+  }
+  return { baseLocator: substrBase, matchCount: 0 };
+}
+
+// Pick the single element to act on from a resolved locator. When more than one
+// candidate remains within the winning tier, prefer a VISIBLE element over a
+// hidden one rather than acting on raw `.first()` (a hidden duplicate — an
+// off-screen menu clone, an aria-hidden mirror — is almost never the intended
+// target). Degrades to `.first()` when the locator API lacks a visible filter
+// or no candidate is visible.
+async function pickBestCandidate(baseLocator, matchCount) {
+  if (matchCount <= 1) {
+    return baseLocator.first();
+  }
+  try {
+    if (typeof baseLocator.filter === "function") {
+      const visible = baseLocator.filter({ visible: true });
+      if ((await visible.count()) > 0) {
+        return visible.first();
+      }
+    }
+  } catch (_) {
+    // Locator API without a `{ visible: true }` filter — fall through.
+  }
+  return baseLocator.first();
+}
+
+// Text matching prefers an EXACT, INTERACTIVE element over a looser substring /
+// plain-text hit (see `resolveTextTarget`), so the first attempt lands on the
+// chip or button the agent meant. When a genuine ambiguity survives that
+// resolution (>1 candidate in the winning tier), we still act — on the best
+// visible candidate — but push an actionable warning naming every candidate
+// into the optional `warnings` array so the agent can switch to an exact
+// selector; a zero-match throws an error that spells out the substring caveat
+// and the exact-selector / URL-query-param alternatives.
+async function performInteraction(
+  frame,
+  interaction,
+  { timeoutMs = 5000, warnings } = {},
+) {
   const { action, selector, text, value } = interaction || {};
 
-  let locator;
+  let baseLocator;
   let targetDesc;
+  let matchedByText = false;
+  let matchCount;
   if (typeof text === "string" && text.length > 0) {
-    locator = frame.getByText(text, { exact: false }).first();
+    const resolved = await resolveTextTarget(frame, text, action);
+    baseLocator = resolved.baseLocator;
+    matchCount = resolved.matchCount;
     targetDesc = `text "${text}"`;
+    matchedByText = true;
   } else if (typeof selector === "string" && selector.length > 0) {
-    locator = frame.locator(selector).first();
+    baseLocator = frame.locator(selector);
+    matchCount = await baseLocator.count();
     targetDesc = `selector "${selector}"`;
   } else {
     throw new Error(
@@ -731,14 +1016,34 @@ async function performInteraction(frame, interaction, { timeoutMs = 5000 } = {})
     );
   }
 
-  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}`,
+        `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}`,
+    );
+  }
+
+  const locator = await pickBestCandidate(baseLocator, matchCount);
+
+  // Ambiguity warning: a text target that still resolves >1 element within the
+  // winning tier acts on the best visible candidate, which may not be the one
+  // intended. Name the competing elements instead of silently proceeding. Only
+  // fires for text matches — an explicit selector that matches many is the
+  // caller's deliberate choice.
+  if (matchedByText && matchCount > 1 && Array.isArray(warnings)) {
+    warnings.push(
+      `preview-interact: ${targetDesc} matched ${matchCount} elements — acting on the best visible candidate. ` +
+        `Text resolution prefers an exact, interactive match, but several remain, so this may not be the element you meant. ` +
+        `Candidates: ${(await describeMatchCandidates(baseLocator, matchCount)).join(" | ")}. ` +
+        `Use an exact/role/testid selector to disambiguate.`,
     );
   }
 
@@ -829,11 +1134,12 @@ async function performInteractionSequence(
     settleMs = 5000,
     loadingMarkers,
     settle = waitForStablePage,
+    warnings,
   } = {},
 ) {
   for (let i = 0; i < interactions.length; i += 1) {
     try {
-      await performInteraction(frame, interactions[i], { timeoutMs });
+      await performInteraction(frame, interactions[i], { timeoutMs, warnings });
     } catch (err) {
       // Prefix the failing step's index so a miss in a multi-step sequence is
       // locatable, matching the model-side `interactions[i]` validator.
@@ -856,6 +1162,7 @@ module.exports = {
   scrollThroughDocument,
   collectVisibleTextLength,
   forceFinalVisualState,
+  centerCaptureWrapper,
   collectImageStates,
   waitForImagesSettled,
   waitForAnimationsSettled,
@@ -865,6 +1172,7 @@ module.exports = {
   loadScenarioInIframe,
   loadScenarioTopLevel,
   collectInteractiveLabels,
+  describeMatchCandidates,
   performInteraction,
   waitForPredicate,
   performInteractionSequence,

package/npm/script-drift.js

@@ -76,6 +76,77 @@ function classifyScriptDrift({ files }) {
   return { verdict: 'clean', staleFiles: [] };
 }
 
+/**
+ * Decide, for one streamed provisioning script, whether the VM should receive the
+ * canonical remote-tip bytes or the local on-disk copy. The remote tip is the
+ * reviewed, canonical source: a checkout that is merely *behind* origin (a normal,
+ * expected consequence of an active fleet landing commits to these scripts) then
+ * streams exactly the bytes the drift guard expects — never stale on-disk bytes,
+ * never a false STALE abort. The local copy wins only when the operator authored
+ * content the remote tip does not have — an uncommitted (dirty) edit or a committed
+ * local-ahead change (developer mode / diverged) — or when the remote facts are
+ * unavailable (offline fallback, so an offline operator can still provision).
+ *
+ * @param {Object} file
+ * @param {string|null} file.localHash
+ * @param {string|null} file.remoteHash  null/undefined ⇒ remote unreachable
+ * @param {string|null} file.baseHash
+ * @param {boolean} file.dirty
+ * @returns {'remote' | 'local'}
+ */
+function streamedScriptSource({ localHash, remoteHash, baseHash, dirty }) {
+  // Remote unreachable / ref missing → the only bytes we have are on disk.
+  if (remoteHash === null || remoteHash === undefined) {
+    return 'local';
+  }
+  // Uncommitted local edit → the operator is provisioning unreviewed bytes on
+  // purpose (developer mode, or an explicit CODEYAM_SKIP_SCRIPT_DRIFT_CHECK bypass).
+  if (dirty) {
+    return 'local';
+  }
+  // Local content the remote tip does not have (committed local-ahead, or a genuine
+  // divergence): local differs from the remote tip AND from the merge base → honor
+  // the local commit rather than silently overwriting it with the remote tip.
+  if (localHash !== remoteHash && localHash !== baseHash) {
+    return 'local';
+  }
+  // Clean, or merely behind the remote tip → stream the canonical remote-tip bytes.
+  return 'remote';
+}
+
+/**
+ * Decide what the streamed-script drift preflight should do, from the classifier
+ * verdict plus which streamed files carry uncommitted edits. A checkout that is
+ * merely *behind* origin (verdict 'stale') is benign — the add streams the
+ * canonical remote-tip bytes (see streamedScriptSource), so it never blocks. The
+ * guard fires ('block') only for local content the remote tip does not have: an
+ * uncommitted (dirty) edit, or a genuine divergence. A committed local-ahead
+ * change is developer mode — warn, don't block.
+ *
+ * @param {Object} o
+ * @param {string} o.verdict      classifyScriptDrift verdict
+ * @param {string[]} [o.staleFiles] files the classifier flagged (the diverged set)
+ * @param {string[]} [o.dirtyFiles] streamed files with uncommitted local edits
+ * @returns {{ block: boolean, reason: 'clean'|'behind'|'local-ahead'|'dirty'|'diverged', blockedFiles: string[] }}
+ */
+function scriptDriftGuardAction({ verdict, staleFiles = [], dirtyFiles = [] }) {
+  if (verdict === 'diverged') {
+    return { block: true, reason: 'diverged', blockedFiles: staleFiles };
+  }
+  if (dirtyFiles.length > 0) {
+    return { block: true, reason: 'dirty', blockedFiles: dirtyFiles };
+  }
+  if (verdict === 'stale') {
+    return { block: false, reason: 'behind', blockedFiles: [] };
+  }
+  if (verdict === 'local-ahead') {
+    return { block: false, reason: 'local-ahead', blockedFiles: [] };
+  }
+  return { block: false, reason: 'clean', blockedFiles: [] };
+}
+
 module.exports = {
-  classifyScriptDrift
+  classifyScriptDrift,
+  streamedScriptSource,
+  scriptDriftGuardAction
 };

package/npm/utils.js

@@ -103,6 +103,34 @@ function findBinary() {
   return null;
 }
 
+/**
+ * Whether this install is a dev checkout (the source tree) rather than an
+ * npm-installed package. Signalled by a `Cargo.toml` at `rootDir` — present in
+ * the git checkout, absent in the npm install dir. The single source of truth
+ * for the checkout-vs-installed distinction; both `ensureBinary` (build-from-
+ * source vs error) and `serverSpawnEnv` (distribution-channel gating) read it.
+ * Accepts an explicit dir so it is unit-testable against a temp tree.
+ */
+function isDevCheckout(dir = rootDir) {
+  return fs.existsSync(path.join(dir, "Cargo.toml"));
+}
+
+/**
+ * Env for a launched editor-server, tagging the distribution channel so the
+ * server's update-availability check knows an npm install can be upgraded via
+ * `npm install -g …@latest`. Pure: returns a NEW object, never mutates the
+ * input.
+ *
+ * Installed (non-dev-checkout) → set `CODEYAM_DISTRIBUTION=npm`, so the server
+ * polls the npm registry and surfaces the upgrade banner. Dev checkout → leave
+ * the env untouched (any pre-existing value from the parent env is preserved),
+ * so a `codeyam-editor` run from source is never nagged to "upgrade".
+ */
+function serverSpawnEnv(baseEnv, { devCheckout } = {}) {
+  if (devCheckout) return { ...baseEnv };
+  return { ...baseEnv, CODEYAM_DISTRIBUTION: "npm" };
+}
+
 /**
  * Return the binary path, building from source if we're in a dev checkout.
  *
@@ -120,9 +148,9 @@ function ensureBinary() {
   const existing = findBinary();
   if (existing) return existing;
 
-  const isDevCheckout = fs.existsSync(path.join(rootDir, "Cargo.toml"));
+  const devCheckout = isDevCheckout();
 
-  if (!isDevCheckout) {
+  if (!devCheckout) {
     const info = platformPackageInfo();
     if (!info) {
       console.error(
@@ -1051,7 +1079,11 @@ async function ensureServer(port = 14199) {
     const child = spawn(
       binary,
       ["start", "--no-open", "--port", String(port)],
-      buildServerSpawnOptions({ cwd: process.cwd(), env: process.env, logFd }),
+      buildServerSpawnOptions({
+        cwd: process.cwd(),
+        env: serverSpawnEnv(process.env, { devCheckout: isDevCheckout() }),
+        logFd,
+      }),
     );
     if (logFd !== null) {
       try {
@@ -1192,6 +1224,8 @@ module.exports = {
   findBrokerBinary,
   verifyBrokerBinaryPresent,
   ensureBinary,
+  isDevCheckout,
+  serverSpawnEnv,
   staleBinaryBanner,
   enforceFreshBinary,
   uiDistDir,

package/package.json

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