@codeyam-editor/codeyam-editor 0.1.0-staging.c9412f0 → 0.1.1

package/npm/container.js

@@ -8,7 +8,7 @@ const path = require("path");
  * inline monitoring UI at http://localhost:14199.
  */
 
-const { ensureServer, rootDir } = require("./utils");
+const { ensureServer, rootDir, killChildProcess } = require("./utils");
 const { open } = require("./open");
 
 const PORT = 14199;
@@ -23,9 +23,13 @@ async function main() {
 
   process.on("SIGINT", () => {
     clearInterval(keepAlive);
-    if (serverChild) serverChild.kill("SIGINT");
+    killChildProcess(serverChild);
     process.exit(0);
   });
 }
 
-main();
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/npm/editor-dev.js

@@ -19,7 +19,7 @@
 const { execSync, spawn } = require("child_process");
 const path = require("path");
 const fs = require("fs");
-const { ensureServer, restartServer, waitForPort, ensureBinary, uiDistDir, rootDir } = require("./utils");
+const { ensureServer, restartServer, waitForPort, ensureBinary, uiDistDir, rootDir, killChildProcess } = require("./utils");
 const { open } = require("./open");
 
 // Tell the Rust binary to emit "codeyam-editor-dev" in all instructions,
@@ -29,9 +29,13 @@ process.env.CODEYAM_CLI = "codeyam-editor-dev";
 const args = process.argv.slice(2);
 const KNOWN_SUBCOMMANDS = ["start", "init", "editor"];
 
-/** Check if the first non-flag argument is a known subcommand. */
-function hasSubcommand() {
-  for (const arg of args) {
+/**
+ * Check if the first non-flag argument is a known subcommand.
+ * Accepts an explicit argv array so the helper is testable without mutating
+ * process.argv (the module-level `args` const is the production default).
+ */
+function hasSubcommand(argv = args) {
+  for (const arg of argv) {
     if (arg.startsWith("-")) continue;
     return KNOWN_SUBCOMMANDS.includes(arg);
   }
@@ -48,73 +52,77 @@ function buildBinary() {
   }
 }
 
-// --- Passthrough mode: build binary, then forward to it ---
-if (hasSubcommand()) {
-  buildBinary();
-  const binary = ensureBinary();
-  const child = spawn(binary, args, {
-    stdio: "inherit",
-    cwd: process.cwd(),
-    env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
-  });
-  child.on("exit", (code) => {
-    process.exit(code ?? 1);
-  });
-} else {
-  // --- Launcher mode: build everything, start server, open browser ---
-  const SERVER_PORT = 14199;
-  const shouldRestart = args.includes("--restart");
-
-  function readProjectPort() {
-    try {
-      const configPath = path.join(process.cwd(), ".codeyam", "editor.json");
-      const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-      return config.port || 3000;
-    } catch {
-      return 3000;
-    }
-  }
-
-  async function main() {
-    const projectDir = process.cwd();
-    console.error(`Editor repo: ${rootDir}`);
-    console.error(`Target project: ${projectDir}`);
+module.exports = { hasSubcommand, buildBinary };
 
+if (require.main === module) {
+  // --- Passthrough mode: build binary, then forward to it ---
+  if (hasSubcommand()) {
     buildBinary();
-
-    // Build the UI from the editor repo
-    console.error("Building UI...");
-    try {
-      execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
-    } catch {
-      console.error("Failed to build UI. Continuing with existing build (if any)...");
-    }
-
-    const serverChild = shouldRestart
-      ? await restartServer(SERVER_PORT)
-      : await ensureServer(SERVER_PORT);
-
-    const appPort = readProjectPort();
-    const viteInternalPort = appPort + 1;
-    console.error(`Waiting for dev server on port ${viteInternalPort}...`);
-    const viteReady = await waitForPort(viteInternalPort, 15000, 300);
-    if (!viteReady) {
-      console.error(`Warning: Dev server not ready on port ${viteInternalPort}. Live Preview may not work initially.`);
-    }
-
-    const url = `http://localhost:${SERVER_PORT}`;
-    console.error(`Editor UI: ${url}`);
-    console.error(`Live Preview: http://localhost:${appPort}`);
-    console.error(`Project: ${projectDir}`);
-    open(url);
-    const keepAlive = setInterval(() => {}, 60_000);
-
-    process.on("SIGINT", () => {
-      clearInterval(keepAlive);
-      if (serverChild) serverChild.kill("SIGINT");
-      process.exit(0);
+    const binary = ensureBinary();
+    const child = spawn(binary, args, {
+      stdio: "inherit",
+      cwd: process.cwd(),
+      env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
+    });
+    child.on("exit", (code) => {
+      process.exit(code ?? 1);
     });
+  } else {
+    // --- Launcher mode: build everything, start server, open browser ---
+    const SERVER_PORT = 14199;
+    const shouldRestart = args.includes("--restart");
+
+    const readProjectPort = () => {
+      try {
+        const configPath = path.join(process.cwd(), ".codeyam", "editor.json");
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        return config.port || 3000;
+      } catch {
+        return 3000;
+      }
+    };
+
+    const launcherMain = async () => {
+      const projectDir = process.cwd();
+      console.error(`Editor repo: ${rootDir}`);
+      console.error(`Target project: ${projectDir}`);
+
+      buildBinary();
+
+      // Build the UI from the editor repo
+      console.error("Building UI...");
+      try {
+        execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
+      } catch {
+        console.error("Failed to build UI. Continuing with existing build (if any)...");
+      }
+
+      const serverChild = shouldRestart
+        ? await restartServer(SERVER_PORT)
+        : await ensureServer(SERVER_PORT);
+
+      const appPort = readProjectPort();
+      const viteInternalPort = appPort + 1;
+      console.error(`Waiting for dev server on port ${viteInternalPort}...`);
+      const viteReady = await waitForPort(viteInternalPort, 15000, 300);
+      if (!viteReady) {
+        console.error(`Warning: Dev server not ready on port ${viteInternalPort}. Live Preview may not work initially.`);
+      }
+
+      const url = `http://localhost:${SERVER_PORT}`;
+      console.error(`Editor UI: ${url}`);
+      console.error(`Live Preview: http://localhost:${appPort}`);
+      console.error(`Project: ${projectDir}`);
+      open(url);
+      const keepAlive = setInterval(() => {}, 60_000);
+
+      process.on("SIGINT", () => {
+        clearInterval(keepAlive);
+        killChildProcess(serverChild);
+        process.exit(0);
+      });
+    };
+
+    launcherMain();
   }
-
-  main();
 }

package/npm/editor.js

@@ -13,12 +13,14 @@
  */
 
 const { execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
 const path = require("path");
-const { ensureServer, restartServer, waitForPort, rootDir } = require("./utils");
+const { ensureServer, stopServer, isPortInUse, waitForPort, rootDir, killChildProcess } = require("./utils");
 const { open } = require("./open");
 
-const SERVER_PORT = 14199;
-const VITE_PORT = 5173;
+const SERVER_PORT = parseInt(process.env.CODEYAM_EDITOR_PORT || "14199", 10);
+const VITE_PORT = parseInt(process.env.PORT || "5173", 10);
 // The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
 // VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
 const VITE_INTERNAL_PORT = VITE_PORT + 1;
@@ -28,16 +30,107 @@ function buildBinary() {
   console.error("Building Rust binary...");
   try {
     execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+    return true;
   } catch {
     console.error("Failed to build Rust binary. Continuing with existing build (if any)...");
+    return false;
+  }
+}
+
+// Resolve <CARGO_HOME>/bin (falling back to $HOME/.cargo/bin). Mirrors
+// `installed_binary_path()` in crates/control-api/src/pty_broker_startup.rs
+// — the Rust broker auto-spawn execs the binary at this path, so we MUST
+// keep it in sync with the freshly-built debug binary or `npm run editor`
+// will start a server whose PTY-broker auto-spawn execs a stale install.
+function cargoBinDir() {
+  if (process.env.CARGO_HOME) return path.join(process.env.CARGO_HOME, "bin");
+  return path.join(os.homedir(), ".cargo", "bin");
+}
+
+// Install target/debug/codeyam-editor to <cargo_bin>/codeyam-editor
+// atomically (write to tmp in same dir, then rename), and refresh the
+// codeyam-editor-pty-broker hardlink so it points at the new inode.
+//
+// The PTY broker auto-spawn (control-api/src/pty_broker_startup.rs) always
+// resolves the *installed* path, NOT current_exe() — that was a deliberate
+// fix to prevent a fork-bomb where test binaries spawned themselves. So a
+// fresh `target/debug/codeyam-editor` is not enough; the install path must
+// be refreshed too. Without this, build tabs hang on "Reconnecting..."
+// because the broker daemon errors out (`unrecognized subcommand`) before
+// the UDS socket opens.
+function installBinary() {
+  const srcPath = path.join(rootDir, "target", "debug", "codeyam-editor");
+  if (!fs.existsSync(srcPath)) {
+    console.error(`Skipping install: ${srcPath} not found.`);
+    return;
+  }
+  const binDir = cargoBinDir();
+  const dstPath = path.join(binDir, "codeyam-editor");
+  const linkPath = path.join(binDir, "codeyam-editor-pty-broker");
+  const tmpPath = path.join(binDir, `.codeyam-editor.tmp.${process.pid}`);
+  console.error(`Installing fresh binary to ${dstPath}...`);
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.copyFileSync(srcPath, tmpPath);
+    fs.chmodSync(tmpPath, 0o755);
+    fs.renameSync(tmpPath, dstPath);
+    try {
+      fs.unlinkSync(linkPath);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    fs.linkSync(dstPath, linkPath);
+  } catch (err) {
+    console.error(`Failed to install binary: ${err.message}`);
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+}
+
+// Evict Rust build artifacts not touched in the last day so target/ doesn't
+// grow unboundedly. Must run after the old server is stopped (it holds files
+// in target/debug/ open) and before the new server starts. Non-fatal.
+function sweepStaleArtifacts() {
+  console.error("Sweeping stale Rust build artifacts (idle >1 day)...");
+  try {
+    execSync("cargo sweep --time 1", { stdio: "inherit", cwd: rootDir });
+  } catch {
+    console.error("cargo-sweep failed (install with `cargo install cargo-sweep`). Continuing.");
   }
 }
 
 async function main() {
+  // Sync ports to editor.json so the Rust backend uses them
+  const editorJsonPath = path.join(rootDir, ".codeyam", "editor.json");
+  if (fs.existsSync(editorJsonPath)) {
+    const editorJson = JSON.parse(fs.readFileSync(editorJsonPath, "utf8"));
+    editorJson.port = VITE_PORT;
+    editorJson.startCommand = `cd ui && npx vite --port ${VITE_PORT}`;
+    
+    const uiApp = editorJson.apps?.find(a => a.dir === "ui");
+    if (uiApp) {
+      uiApp.port = VITE_PORT;
+      uiApp.startCommand = `npx vite --port ${VITE_PORT}`;
+    }
+    
+    if (editorJson.proxy) {
+      editorJson.proxy.controlPort = SERVER_PORT;
+      editorJson.proxy.httpPort = SERVER_PORT - 99;
+      editorJson.proxy.dbPort = SERVER_PORT - 98;
+    }
+    fs.writeFileSync(editorJsonPath, JSON.stringify(editorJson, null, 2));
+  }
+
   // Rebuild the Rust binary so code changes are picked up on restart.
   // This script is only invoked from a source checkout (via `npm run editor`),
   // so Cargo.toml and the crates tree are always present.
-  buildBinary();
+  const buildOk = buildBinary();
+  // Refresh <cargo_bin>/codeyam-editor (and the pty-broker hardlink) so
+  // the broker auto-spawn execs a binary that knows the `pty-broker
+  // daemon` subcommand. Skip if the build failed — installing a stale
+  // debug binary over a working install is worse than leaving it.
+  if (buildOk) {
+    installBinary();
+  }
 
   // Build the UI so the backend can serve it as static files
   console.error("Building UI...");
@@ -51,10 +144,17 @@ async function main() {
   }
 
   // Start the Rust backend — it serves ui/dist/ and launches the Vite dev
-  // server (configured via startCommand in editor.json) for Live Preview HMR
-  const serverChild = shouldRestart
-    ? await restartServer(SERVER_PORT)
-    : await ensureServer(SERVER_PORT);
+  // server (configured via startCommand in editor.json) for Live Preview HMR.
+  // On --restart: stop the existing server first, sweep stale artifacts while
+  // target/ is idle (no process holding files open), then start fresh.
+  if (shouldRestart && (await isPortInUse(SERVER_PORT))) {
+    console.error(`Stopping existing server on port ${SERVER_PORT}...`);
+    await stopServer(SERVER_PORT);
+  }
+  if (shouldRestart) {
+    sweepStaleArtifacts();
+  }
+  const serverChild = await ensureServer(SERVER_PORT);
 
   // Wait for the actual Vite dev server on the internal port (not the reverse
   // proxy on VITE_PORT, which starts immediately with the Rust binary).
@@ -73,9 +173,19 @@ async function main() {
 
   process.on("SIGINT", () => {
     clearInterval(keepAlive);
-    if (serverChild) serverChild.kill("SIGINT");
+    killChildProcess(serverChild);
     process.exit(0);
   });
 }
 
-main();
+module.exports = {
+  buildBinary,
+  cargoBinDir,
+  installBinary,
+  main,
+  sweepStaleArtifacts,
+};
+
+if (require.main === module) {
+  main();
+}

package/npm/postinstall.js

@@ -5,11 +5,17 @@
  *
  * Downloads the pre-built platform binary and UI assets from GitHub Releases.
  * Skipped when running in local development (cargo builds from source instead).
+ *
+ * Cross-platform: uses Node-native `fetch` + the `tar` npm package to download
+ * and extract. Avoids depending on `curl` / `tar` system binaries — those exist
+ * on macOS and Linux but not on a default Windows install, and the previous
+ * `curl | tar xz` shell pipe was the original Windows-install blocker.
  */
 
 const fs = require("fs");
 const path = require("path");
-const { execSync } = require("child_process");
+const { Readable } = require("stream");
+const tar = require("tar");
 
 const rootDir = path.resolve(__dirname, "..");
 
@@ -17,8 +23,15 @@ const PLATFORM_MAP = {
   "darwin-arm64": "codeyam-editor-darwin-arm64",
   "darwin-x64": "codeyam-editor-darwin-x64",
   "linux-x64": "codeyam-editor-linux-x64",
+  "win32-x64": "codeyam-editor-win32-x64",
 };
 
+function binaryName() {
+  return process.platform === "win32"
+    ? "codeyam-editor.exe"
+    : "codeyam-editor";
+}
+
 function getArtifactName() {
   const key = `${process.platform}-${process.arch}`;
   const name = PLATFORM_MAP[key];
@@ -26,7 +39,10 @@ function getArtifactName() {
     console.error(
       `codeyam-editor: unsupported platform ${process.platform} ${process.arch}`
     );
-    console.error("Supported: macOS (arm64, x64), Linux (x64)");
+    console.error("Supported: macOS (arm64, x64), Linux (x64), Windows (x64)");
+    console.error(
+      "You can build from source instead: cargo build --release"
+    );
     process.exit(0); // Don't fail the install — user may be building from source
   }
   return name;
@@ -47,9 +63,22 @@ function getReleaseTag() {
   return "latest";
 }
 
-function download() {
+async function downloadAndExtract(url, dest) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  await new Promise((resolve, reject) => {
+    Readable.fromWeb(res.body)
+      .pipe(tar.x({ cwd: dest }))
+      .on("finish", resolve)
+      .on("error", reject);
+  });
+}
+
+async function download() {
   // Skip if a binary already exists (e.g. local dev with cargo build)
-  const binPath = path.join(rootDir, "bin", "codeyam-editor");
+  const binPath = path.join(rootDir, "bin", binaryName());
   if (fs.existsSync(binPath)) {
     return;
   }
@@ -71,13 +100,9 @@ function download() {
   fs.mkdirSync(uiDir, { recursive: true });
 
   try {
-    // Download and extract in one step using curl + tar
-    execSync(
-      `curl -fsSL "${url}" | tar xz -C "${rootDir}"`,
-      { stdio: ["ignore", "inherit", "inherit"], timeout: 120000 }
-    );
+    await downloadAndExtract(url, rootDir);
 
-    // Ensure binary is executable
+    // Ensure binary is executable. No-op on Windows but harmless.
     if (fs.existsSync(binPath)) {
       fs.chmodSync(binPath, 0o755);
     }
@@ -85,6 +110,7 @@ function download() {
     console.error("codeyam-editor installed successfully!");
   } catch (err) {
     console.error(`Failed to download codeyam-editor binary from ${url}`);
+    console.error(`  Reason: ${err.message}`);
     console.error(
       "You can build from source instead: cargo build --release"
     );
@@ -92,4 +118,15 @@ function download() {
   }
 }
 
-download();
+module.exports = {
+  PLATFORM_MAP,
+  binaryName,
+  getArtifactName,
+  getReleaseTag,
+  downloadAndExtract,
+  download,
+};
+
+if (require.main === module) {
+  download();
+}

package/npm/scenario-check.js

@@ -43,6 +43,8 @@ const {
   handleRequestFailed,
 } = require("./scenario-handlers");
 
+const BLANK_RETRY_DELAY_MS = 500;
+
 async function runScenarioCheck(config) {
   const { url, outputPath, width, height, httpMocks = {} } = config;
   const issues = [];
@@ -113,8 +115,18 @@ async function runScenarioCheck(config) {
       );
     }
 
-    const contentState = await collectContentState(frame);
-    const hasContent = hasRenderableContent(contentState);
+    // Cold-start retry: a single re-collect after a short pause covers
+    // the React.lazy / Suspense-fallback race that flagged 4-of-59
+    // scenarios as blank against a cold Vite dev server on 2026-04-30.
+    // One retry is enough — the Suspense window is sub-second in
+    // practice, longer waits just slow down genuine blank-render bugs.
+    let contentState = await collectContentState(frame);
+    let hasContent = hasRenderableContent(contentState);
+    if (!hasContent) {
+      await new Promise((r) => setTimeout(r, BLANK_RETRY_DELAY_MS));
+      contentState = await collectContentState(frame);
+      hasContent = hasRenderableContent(contentState);
+    }
 
     if (!hasContent) {
       pushIssue(
@@ -192,6 +204,7 @@ async function main() {
 
 module.exports = {
   runScenarioCheck,
+  main,
 };
 
 if (require.main === module) {

package/npm/scenario-playwright.js

@@ -181,6 +181,7 @@ async function loadScenarioInIframe(page, url, { background } = {}) {
 }
 
 module.exports = {
+  escapeHtmlAttribute,
   buildIframeHarness,
   collectContentState,
   collectImageStates,

package/npm/utils.js

@@ -6,12 +6,22 @@ const fs = require("fs");
 const rootDir = path.resolve(__dirname, "..");
 const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
 
+/**
+ * Platform-correct executable filename for the codeyam-editor binary.
+ * Windows requires the `.exe` extension; on Unix the binary has no extension.
+ * Accepts an explicit platform so the helper is testable across platforms.
+ */
+function binaryName(platform = process.platform) {
+  return platform === "win32" ? "codeyam-editor.exe" : "codeyam-editor";
+}
+
 /** Find the compiled binary — check npm-installed location first, then dev builds. */
 function findBinary() {
+  const name = binaryName();
   const candidates = [
-    path.join(rootDir, "bin", "codeyam-editor"),       // npm install (postinstall)
-    path.join(rootDir, "target", "debug", "codeyam-editor"),   // local dev (debug)
-    path.join(rootDir, "target", "release", "codeyam-editor"), // local dev (release)
+    path.join(rootDir, "bin", name),                   // npm install (postinstall)
+    path.join(rootDir, "target", "debug", name),       // local dev (debug)
+    path.join(rootDir, "target", "release", name),     // local dev (release)
   ];
 
   for (const candidate of candidates) {
@@ -136,14 +146,38 @@ async function requestServerShutdown(port = 14199, timeoutMs = 1500) {
 
 function tryKillPid(pid) {
   try {
-    process.kill(pid, "SIGINT");
+    // On Windows, `process.kill(pid, "SIGINT")` either errors or no-ops
+    // depending on Node version. Drop the signal so Node maps to a
+    // platform TerminateProcess. Less graceful, but the child does exit.
+    if (process.platform === "win32") {
+      process.kill(pid);
+    } else {
+      process.kill(pid, "SIGINT");
+    }
     return true;
   } catch {
     return false;
   }
 }
 
+/**
+ * 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 —
+ * `child.kill("SIGINT")` is unreliable on Windows.
+ */
+function killChildProcess(child) {
+  if (!child) return;
+  if (process.platform === "win32") {
+    child.kill();
+  } else {
+    child.kill("SIGINT");
+  }
+}
+
 function findListeningPids(port) {
+  // Process discovery on Windows is best-effort — `lsof` is not installed and
+  // a `netstat -ano` parser is a follow-up. The API-shutdown path and the
+  // PID-file path together stop the server cleanly in normal operation.
   if (process.platform === "win32") return [];
 
   const result = spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
@@ -229,6 +263,7 @@ async function ensureServer(port = 14199) {
 module.exports = {
   rootDir,
   serverStatePath,
+  binaryName,
   findBinary,
   ensureBinary,
   uiDistDir,
@@ -237,7 +272,12 @@ module.exports = {
   waitForPort,
   waitForPortToClose,
   readServerState,
+  clearServerState,
+  requestServerShutdown,
+  tryKillPid,
+  findListeningPids,
   stopServer,
   restartServer,
   ensureServer,
+  killChildProcess,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam-editor/codeyam-editor",
-  "version": "0.1.0-staging.c9412f0",
+  "version": "0.1.1",
   "description": "Language-agnostic managed execution sandbox for scenario-driven development",
   "bin": {
     "codeyam-editor": "./npm/cli.js"
@@ -9,7 +9,8 @@
     "postinstall": "node ./npm/postinstall.js"
   },
   "dependencies": {
-    "playwright": "^1.58.2"
+    "playwright": "^1.58.2",
+    "tar": "^7.5.13"
   },
   "keywords": [
     "codeyam",