@codeyam-editor/codeyam-editor 0.1.0-staging.36d3518

package/npm/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const { ensureBinary, uiDistDir } = require("./utils");
+
+const binary = ensureBinary();
+
+const child = spawn(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
+});
+
+child.on("exit", (code) => {
+  process.exit(code ?? 1);
+});

package/npm/container.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const path = require("path");
+/**
+ * Start the container monitoring UI.
+ *
+ * Starts the Rust backend (if not already running) and opens the
+ * inline monitoring UI at http://localhost:14199.
+ */
+
+const { ensureServer, rootDir } = require("./utils");
+const { open } = require("./open");
+
+const PORT = 14199;
+
+async function main() {
+  const serverChild = await ensureServer(PORT);
+  const url = `http://localhost:${PORT}`;
+  console.error(`Container UI: ${url}`);
+  console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
+  open(url);
+  const keepAlive = setInterval(() => {}, 60_000);
+
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    if (serverChild) serverChild.kill("SIGINT");
+    process.exit(0);
+  });
+}
+
+main();

package/npm/editor.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * Start the editor.
+ *
+ * 1. Builds the React UI into ui/dist/ (stable outer shell, no HMR)
+ * 2. Starts the Rust backend which:
+ *    - Serves ui/dist/ as static files on port 14199
+ *    - Launches the Vite dev server (startCommand) on port 5173 for Live Preview HMR
+ *    - Provides the API, WebSocket, and screenshot endpoints
+ * 3. Waits for the Vite dev server to be ready (so the Live Preview iframe works)
+ * 4. Opens http://localhost:14199 in the browser
+ */
+
+const { execSync } = require("child_process");
+const path = require("path");
+const { ensureServer, restartServer, waitForPort, rootDir } = require("./utils");
+const { open } = require("./open");
+
+const SERVER_PORT = 14199;
+const VITE_PORT = 5173;
+// 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;
+const shouldRestart = process.argv.includes("--restart");
+
+async function main() {
+  // Build the UI so the backend can serve it as static files
+  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)...");
+  }
+
+  // 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);
+
+  // 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).
+  console.error("Waiting for Vite dev server...");
+  const viteReady = await waitForPort(VITE_INTERNAL_PORT, 15000, 300);
+  if (!viteReady) {
+    console.error(`Warning: Vite dev server not ready on port ${VITE_INTERNAL_PORT}. Live Preview may not work initially.`);
+  }
+
+  const url = `http://localhost:${SERVER_PORT}`;
+  console.error(`Editor UI: ${url}`);
+  console.error(`Live Preview: http://localhost:${VITE_PORT}`);
+  console.error(`Logs: ${path.join(rootDir, ".codeyam", "logs")}`);
+  open(url);
+  const keepAlive = setInterval(() => {}, 60_000);
+
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    if (serverChild) serverChild.kill("SIGINT");
+    process.exit(0);
+  });
+}
+
+main();

package/npm/open.js

@@ -0,0 +1,15 @@
+const { spawn } = require("child_process");
+
+/** Open a URL in the default browser. */
+function open(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+
+  spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+}
+
+module.exports = { open };

package/npm/postinstall.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for @codeyam-editor/codeyam-editor.
+ *
+ * Downloads the pre-built platform binary and UI assets from GitHub Releases.
+ * Skipped when running in local development (cargo builds from source instead).
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const rootDir = path.resolve(__dirname, "..");
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "codeyam-editor-darwin-arm64",
+  "darwin-x64": "codeyam-editor-darwin-x64",
+  "linux-x64": "codeyam-editor-linux-x64",
+};
+
+function getArtifactName() {
+  const key = `${process.platform}-${process.arch}`;
+  const name = PLATFORM_MAP[key];
+  if (!name) {
+    console.error(
+      `codeyam-editor: unsupported platform ${process.platform} ${process.arch}`
+    );
+    console.error("Supported: macOS (arm64, x64), Linux (x64)");
+    process.exit(0); // Don't fail the install — user may be building from source
+  }
+  return name;
+}
+
+/**
+ * Determine the GitHub release tag from the installed package version.
+ *
+ *  - "0.1.0-staging.abc1234"  -> "staging"
+ *  - "0.1.2"                  -> "latest"
+ */
+function getReleaseTag() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(rootDir, "package.json"), "utf8")
+  );
+  const version = pkg.version || "0.1.0";
+  if (version.includes("-staging")) return "staging";
+  return "latest";
+}
+
+function download() {
+  // Skip if a binary already exists (e.g. local dev with cargo build)
+  const binPath = path.join(rootDir, "bin", "codeyam-editor");
+  if (fs.existsSync(binPath)) {
+    return;
+  }
+
+  // Skip if we're in a dev checkout (has Cargo.toml at root)
+  if (fs.existsSync(path.join(rootDir, "Cargo.toml"))) {
+    return;
+  }
+
+  const artifactName = getArtifactName();
+  const tag = getReleaseTag();
+  const url = `https://github.com/codeyam-ai/codeyam-editor/releases/download/${tag}/${artifactName}.tar.gz`;
+
+  console.error(`Downloading codeyam-editor binary (${artifactName})...`);
+
+  const binDir = path.join(rootDir, "bin");
+  const uiDir = path.join(rootDir, "ui");
+  fs.mkdirSync(binDir, { recursive: true });
+  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 }
+    );
+
+    // Ensure binary is executable
+    if (fs.existsSync(binPath)) {
+      fs.chmodSync(binPath, 0o755);
+    }
+
+    console.error("codeyam-editor installed successfully!");
+  } catch (err) {
+    console.error(`Failed to download codeyam-editor binary from ${url}`);
+    console.error(
+      "You can build from source instead: cargo build --release"
+    );
+    // Don't fail the install — user may want to build from source
+  }
+}
+
+download();

package/npm/scenario-check.js

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { chromium } = require("playwright");
+
+const LOADING_MARKERS = [
+  "Loading scenario...",
+  "Loading tests...",
+  "Loading scenarios...",
+  "disconnected",
+];
+
+function hasLoadingMarkers(text) {
+  return LOADING_MARKERS.some((marker) => text.includes(marker));
+}
+
+function hasRenderableContent(state) {
+  return Boolean(
+    state &&
+      (state.rootChildCount > 0 ||
+        state.rootTextLength > 0 ||
+        state.bodyTextLength > 0),
+  );
+}
+
+const ERROR_PATTERNS = [
+  "not found in registry",
+  "Component not found",
+  "Scenario Error",
+];
+
+function hasErrorPatterns(text) {
+  return ERROR_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function createIssue(kind, message, extra = {}) {
+  return {
+    kind,
+    message,
+    url: extra.url ?? null,
+    status: extra.status ?? null,
+  };
+}
+
+function pushIssue(issues, issue) {
+  const key = JSON.stringify(issue);
+  if (!issues.some((existing) => JSON.stringify(existing) === key)) {
+    issues.push(issue);
+  }
+}
+
+function escapeHtmlAttribute(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll('"', """);
+}
+
+function buildIframeHarness(url) {
+  const escapedUrl = escapeHtmlAttribute(url);
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <style>
+      html, body {
+        margin: 0;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        background: #fff;
+      }
+
+      iframe {
+        display: block;
+        width: 100%;
+        height: 100%;
+        border: 0;
+        background: #fff;
+      }
+    </style>
+  </head>
+  <body>
+    <iframe id="scenario-frame" title="Scenario Preview" src="${escapedUrl}"></iframe>
+  </body>
+</html>`;
+}
+
+function buildResult({ loaded, hasContent, issues, outputPath, url }) {
+  return {
+    ok: loaded && hasContent && issues.length === 0,
+    loaded,
+    hasContent,
+    url,
+    outputPath: outputPath ?? null,
+    issues,
+  };
+}
+
+function normalizeMockCandidates(url) {
+  try {
+    const parsed = new URL(url);
+    return [url, `${parsed.pathname}${parsed.search}`, parsed.pathname];
+  } catch {
+    return [url];
+  }
+}
+
+function findHttpMock(httpMocks, request) {
+  const method = request.method().toUpperCase();
+  const candidates = normalizeMockCandidates(request.url());
+  for (const candidate of candidates) {
+    const key = `${method} ${candidate}`;
+    if (httpMocks[key]) {
+      return httpMocks[key];
+    }
+  }
+  return null;
+}
+
+async function attachHttpMocks(page, httpMocks) {
+  if (!httpMocks || Object.keys(httpMocks).length === 0) return;
+
+  await page.route("**/*", async (route) => {
+    const mock = findHttpMock(httpMocks, route.request());
+    if (!mock) {
+      await route.continue();
+      return;
+    }
+
+    const headers = { ...(mock.headers || {}) };
+    let body;
+    if (mock.body !== undefined) {
+      body =
+        typeof mock.body === "string" ? mock.body : JSON.stringify(mock.body);
+      const hasContentType = Object.keys(headers).some(
+        (key) => key.toLowerCase() === "content-type",
+      );
+      if (!hasContentType) {
+        headers["content-type"] = "application/json";
+      }
+    }
+
+    await route.fulfill({
+      status: mock.status || 200,
+      headers,
+      body,
+    });
+  });
+
+  // Disable the in-page fetch mock by returning an empty active-mocks.json.
+  // The HTML injects a script that synchronously loads this file and
+  // monkey-patches window.fetch, which would bypass Playwright's route
+  // interception. This route is registered AFTER **/* so it takes priority
+  // (Playwright uses LIFO ordering for route handlers).
+  await page.route("**/active-mocks.json", async (route) => {
+    await route.fulfill({
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: "[]",
+    });
+  });
+}
+
+async function collectContentState(target) {
+  return target.evaluate(() => {
+    const root = document.getElementById("root");
+    return {
+      bodyTextLength: document.body.innerText.trim().length,
+      rootChildCount: root ? root.childElementCount : 0,
+      rootTextLength: root ? (root.textContent || "").trim().length : 0,
+    };
+  });
+}
+
+async function waitForStablePage(page, target, timeoutMs = 10000) {
+  const started = Date.now();
+  let lastHtml = "";
+  let stableCount = 0;
+
+  while (Date.now() - started < timeoutMs) {
+    await page.waitForTimeout(500);
+
+    const pageState = await target.evaluate(() => ({
+      bodyText: document.body.innerText,
+      html: document.body.innerHTML,
+    }));
+
+    if (
+      !hasLoadingMarkers(pageState.bodyText) &&
+      pageState.html === lastHtml
+    ) {
+      stableCount += 1;
+      if (stableCount >= 2) return;
+    } else {
+      stableCount = 0;
+    }
+
+    lastHtml = pageState.html;
+  }
+}
+
+async function loadScenarioInIframe(page, url) {
+  const responsePromise = page
+    .waitForResponse(
+      (response) =>
+        response.request().resourceType() === "document" &&
+        response.url() === url,
+      { timeout: 30000 },
+    )
+    .catch(() => null);
+
+  await page.setContent(buildIframeHarness(url), { waitUntil: "domcontentloaded" });
+
+  const frameHandle = await page.waitForSelector("#scenario-frame", {
+    state: "attached",
+    timeout: 30000,
+  });
+  const frame = await frameHandle.contentFrame();
+  if (!frame) {
+    throw new Error("Scenario iframe did not attach");
+  }
+
+  await frame.waitForLoadState("load", { timeout: 30000 });
+  const response = await responsePromise;
+  return { frame, response };
+}
+
+async function runScenarioCheck(config) {
+  const { url, outputPath, width, height, httpMocks = {} } = config;
+  const issues = [];
+  const browser = await chromium.launch();
+  const context = await browser.newContext({
+    viewport: { width: width || 1440, height: height || 900 },
+  });
+
+  // Context-level init script runs in ALL frames (including cross-origin iframes)
+  await context.addInitScript(() => {
+    window.__codeyamUnhandledRejections = [];
+    window.addEventListener("unhandledrejection", (event) => {
+      const reason = event.reason;
+      const message =
+        reason instanceof Error ? reason.message : String(reason);
+      window.__codeyamUnhandledRejections.push(message);
+    });
+
+    // Stub WebSocket during capture to prevent terminal reconnection spam.
+    // Returns an object that behaves like a closed WebSocket — the terminal
+    // will attempt to reconnect a few times then give up silently.
+    window.WebSocket = class StubWebSocket {
+      static CONNECTING = 0;
+      static OPEN = 1;
+      static CLOSING = 2;
+      static CLOSED = 3;
+      readyState = 3;
+      onopen = null;
+      onclose = null;
+      onerror = null;
+      onmessage = null;
+      send() {}
+      close() {}
+      addEventListener() {}
+      removeEventListener() {}
+      dispatchEvent() { return false; }
+      constructor() {
+        // Fire onerror then onclose on next tick so the terminal sees a failed connection
+        setTimeout(() => {
+          if (this.onerror) this.onerror(new Event("error"));
+          if (this.onclose) this.onclose(new CloseEvent("close"));
+        }, 0);
+      }
+    };
+  });
+
+  const page = await context.newPage();
+  await attachHttpMocks(page, httpMocks);
+
+  page.on("pageerror", (error) => {
+    pushIssue(
+      issues,
+      createIssue("pageerror", error.message || String(error), {
+        url: page.url() || url,
+      }),
+    );
+  });
+
+  page.on("console", (message) => {
+    if (message.type() !== "error") return;
+    const text = message.text();
+    // Ignore known dev-server WebSocket/HMR errors from Vite proxy
+    if (
+      text.includes("WebSocket connection to") ||
+      text.includes("Unsupported Media Type")
+    ) {
+      return;
+    }
+    pushIssue(
+      issues,
+      createIssue("console", text, {
+        url: page.url() || url,
+      }),
+    );
+  });
+
+  page.on("requestfailed", (request) => {
+    pushIssue(
+      issues,
+      createIssue(
+        "requestfailed",
+        request.failure()?.errorText || "Request failed",
+        { url: request.url() },
+      ),
+    );
+  });
+
+  let loaded = false;
+
+  try {
+    const { frame, response } = await loadScenarioInIframe(page, url);
+    loaded = true;
+
+    if (response && response.status() >= 400) {
+      pushIssue(
+        issues,
+        createIssue("navigation", `Navigation returned HTTP ${response.status()}`, {
+          url: response.url(),
+          status: response.status(),
+        }),
+      );
+    }
+
+    await waitForStablePage(page, frame);
+
+    const rejectionMessages = await frame.evaluate(
+      () => window.__codeyamUnhandledRejections || [],
+    );
+    for (const message of rejectionMessages) {
+      pushIssue(
+        issues,
+        createIssue("unhandledrejection", message, {
+          url: page.url() || url,
+        }),
+      );
+    }
+
+    const contentState = await collectContentState(frame);
+    const hasContent = hasRenderableContent(contentState);
+
+    if (!hasContent) {
+      pushIssue(
+        issues,
+        createIssue("blank", "Page rendered no visible content", {
+          url: page.url() || url,
+        }),
+      );
+    }
+
+    // Check for known error states in the rendered content
+    const bodyText = await frame.evaluate(() => document.body.innerText || "");
+    if (hasErrorPatterns(bodyText)) {
+      pushIssue(
+        issues,
+        createIssue("error-state", `Page contains error content: ${bodyText.slice(0, 200)}`, {
+          url: page.url() || url,
+        }),
+      );
+    }
+
+    if (outputPath && loaded) {
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      await page.screenshot({ path: outputPath, fullPage: false });
+    }
+
+    return buildResult({
+      loaded,
+      hasContent,
+      issues,
+      outputPath,
+      url: frame.url() || url,
+    });
+  } catch (error) {
+    pushIssue(
+      issues,
+      createIssue("navigation", error.message || String(error), { url }),
+    );
+
+    return buildResult({
+      loaded,
+      hasContent: false,
+      issues,
+      outputPath,
+      url,
+    });
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  const config = JSON.parse(process.argv[2] || "{}");
+
+  if (!config.url) {
+    console.error(
+      "Usage: node scenario-check.js '{\"url\":\"...\",\"outputPath\":\"...\",\"width\":1440,\"height\":900}'",
+    );
+    process.exit(1);
+  }
+
+  const result = await runScenarioCheck(config);
+  console.log(JSON.stringify(result));
+}
+
+module.exports = {
+  attachHttpMocks,
+  buildResult,
+  buildIframeHarness,
+  createIssue,
+  findHttpMock,
+  hasErrorPatterns,
+  hasLoadingMarkers,
+  hasRenderableContent,
+  loadScenarioInIframe,
+  normalizeMockCandidates,
+  pushIssue,
+  runScenarioCheck,
+  waitForStablePage,
+};
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message || String(error));
+    process.exit(1);
+  });
+}

package/npm/utils.js

@@ -0,0 +1,243 @@
+const { execSync, spawn, spawnSync } = require("child_process");
+const net = require("net");
+const path = require("path");
+const fs = require("fs");
+
+const rootDir = path.resolve(__dirname, "..");
+const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
+
+/** Find the compiled binary — check npm-installed location first, then dev builds. */
+function findBinary() {
+  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)
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** Return the binary path — build from source only if no pre-built binary exists. */
+function ensureBinary() {
+  const existing = findBinary();
+  if (existing) return existing;
+
+  // No pre-built binary; try building from source (local dev workflow).
+  try {
+    execSync("cargo --version", { stdio: "ignore" });
+  } catch {
+    console.error(
+      "codeyam-editor binary not found. Try reinstalling:\n" +
+      "  npm install @codeyam-editor/codeyam-editor\n"
+    );
+    process.exit(1);
+  }
+
+  console.error("Building codeyam-editor...");
+  try {
+    execSync("cargo build", { cwd: rootDir, stdio: "inherit" });
+  } catch {
+    console.error("Failed to build. Is Rust installed? https://rustup.rs/");
+    process.exit(1);
+  }
+
+  const binary = findBinary();
+  if (!binary) {
+    console.error("Binary not found after build.");
+    process.exit(1);
+  }
+  return binary;
+}
+
+/** Resolve the UI dist directory for the binary to serve. */
+function uiDistDir() {
+  return path.join(rootDir, "ui", "dist");
+}
+
+/** Try to connect to a specific host:port. Returns true if something is listening. */
+function tryConnect(port, host) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    socket.setTimeout(300);
+    socket.once("connect", () => { socket.destroy(); resolve(true); });
+    socket.once("error", () => { socket.destroy(); resolve(false); });
+    socket.once("timeout", () => { socket.destroy(); resolve(false); });
+    socket.connect(port, host);
+  });
+}
+
+/** Check if a port is in use (tries both IPv4 and IPv6). */
+async function isPortInUse(port) {
+  return (await tryConnect(port, "127.0.0.1")) || (await tryConnect(port, "::1"));
+}
+
+/**
+ * Poll a port until something is listening, or timeout.
+ * Returns true if the port became active, false on timeout.
+ */
+async function waitForPort(port, timeoutMs = 10000, intervalMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortInUse(port)) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+/**
+ * Poll until a port stops listening, or timeout.
+ * Returns true if the port became inactive, false on timeout.
+ */
+async function waitForPortToClose(port, timeoutMs = 10000, intervalMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!(await isPortInUse(port))) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+function readServerState() {
+  try {
+    return JSON.parse(fs.readFileSync(serverStatePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function clearServerState() {
+  try {
+    fs.unlinkSync(serverStatePath);
+  } catch {}
+}
+
+async function requestServerShutdown(port = 14199, timeoutMs = 1500) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/api/editor-server/shutdown`, {
+      method: "POST",
+      signal: controller.signal,
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function tryKillPid(pid) {
+  try {
+    process.kill(pid, "SIGINT");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findListeningPids(port) {
+  if (process.platform === "win32") return [];
+
+  const result = spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
+    encoding: "utf8",
+  });
+
+  if (result.error) return [];
+
+  return result.stdout
+    .split(/\s+/)
+    .map((line) => parseInt(line, 10))
+    .filter((pid) => Number.isInteger(pid));
+}
+
+/** Stop the Rust backend server if it is running. */
+async function stopServer(port = 14199) {
+  if (!(await isPortInUse(port))) {
+    clearServerState();
+    return false;
+  }
+
+  if (await requestServerShutdown(port)) {
+    if (await waitForPortToClose(port, 10000, 200)) {
+      clearServerState();
+      return true;
+    }
+  }
+
+  const state = readServerState();
+  if (state && Number.isInteger(state.pid) && tryKillPid(state.pid)) {
+    if (await waitForPortToClose(port, 5000, 200)) {
+      clearServerState();
+      return true;
+    }
+  }
+
+  for (const pid of findListeningPids(port)) {
+    tryKillPid(pid);
+  }
+
+  if (await waitForPortToClose(port, 5000, 200)) {
+    clearServerState();
+    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);
+  }
+  return ensureServer(port);
+}
+
+/** Start the Rust backend server if not already running. Returns the child process (or null if already running). */
+async function ensureServer(port = 14199) {
+  if (await isPortInUse(port)) {
+    console.error(`Server already running on port ${port}`);
+    return null;
+  }
+
+  const binary = ensureBinary();
+  const child = spawn(binary, ["start", "--no-open", "--port", String(port)], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+    detached: false,
+    env: { ...process.env, CODEYAM_EDITOR_UI_DIR: uiDistDir() },
+  });
+
+  const ready = await waitForPort(port);
+  if (!ready) {
+    console.error("Server failed to start within 10 seconds");
+    child.kill();
+    process.exit(1);
+  }
+
+  return child;
+}
+
+module.exports = {
+  rootDir,
+  serverStatePath,
+  findBinary,
+  ensureBinary,
+  uiDistDir,
+  tryConnect,
+  isPortInUse,
+  waitForPort,
+  waitForPortToClose,
+  readServerState,
+  stopServer,
+  restartServer,
+  ensureServer,
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@codeyam-editor/codeyam-editor",
+  "version": "0.1.0-staging.36d3518",
+  "description": "Language-agnostic managed execution sandbox for scenario-driven development",
+  "bin": {
+    "codeyam-editor": "./npm/cli.js"
+  },
+  "scripts": {
+    "postinstall": "node ./npm/postinstall.js"
+  },
+  "dependencies": {
+    "playwright": "^1.58.2"
+  },
+  "keywords": [
+    "codeyam",
+    "editor",
+    "development",
+    "scenarios"
+  ],
+  "homepage": "https://codeyam.com/",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "npm/",
+    "bin/",
+    "ui/"
+  ]
+}