@web-auto/camo 0.1.18 → 0.1.20

package/src/services/controller/selectors.js

@@ -0,0 +1,54 @@
+export function normalizeSelectors(rawSelectors) {
+  const out = [];
+  const pushCss = (css, extra = {}) => {
+    if (typeof css !== 'string' || !css.trim()) return;
+    out.push({
+      css: css.trim(),
+      ...(typeof extra.variant === 'string' ? { variant: extra.variant } : {}),
+      ...(Number.isFinite(Number(extra.score)) ? { score: Number(extra.score) } : {}),
+    });
+  };
+
+  const splitLegacySelector = (rawSelector) => {
+    if (typeof rawSelector !== 'string') return [];
+    return rawSelector
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+  };
+
+  if (Array.isArray(rawSelectors)) {
+    for (const item of rawSelectors) {
+      if (typeof item === 'string') {
+        for (const css of splitLegacySelector(item)) pushCss(css);
+        continue;
+      }
+      if (item && typeof item === 'object') {
+        if (typeof item.css === 'string') {
+          pushCss(item.css, item);
+        } else if (typeof item.selector === 'string') {
+          for (const css of splitLegacySelector(item.selector)) pushCss(css, item);
+        } else if (typeof item.id === 'string' && item.id) {
+          pushCss(`#${item.id}`, item);
+        } else if (Array.isArray(item.classes) && item.classes.length > 0) {
+          pushCss(`.${item.classes.filter(Boolean).join('.')}`, item);
+        }
+      }
+    }
+  } else if (typeof rawSelectors === 'string') {
+    for (const css of splitLegacySelector(rawSelectors)) pushCss(css);
+  } else if (rawSelectors && typeof rawSelectors === 'object') {
+    if (typeof rawSelectors.css === 'string') {
+      pushCss(rawSelectors.css, rawSelectors);
+    } else if (typeof rawSelectors.selector === 'string') {
+      for (const css of splitLegacySelector(rawSelectors.selector)) pushCss(css, rawSelectors);
+    }
+  }
+
+  const dedup = new Map();
+  for (const item of out) {
+    const key = `${item.css}::${item.variant || ''}::${item.score || ''}`;
+    if (!dedup.has(key)) dedup.set(key, item);
+  }
+  return Array.from(dedup.values());
+}

package/src/services/controller/transport.js

@@ -0,0 +1,118 @@
+import WebSocket from 'ws';
+
+export function createTransport({ env = process.env, defaults = {}, debugLog = null } = {}) {
+  const getBrowserWsUrl = () => {
+    if (env.CAMO_WS_URL) return env.CAMO_WS_URL;
+    const host = env.CAMO_WS_HOST || defaults.wsHost || '127.0.0.1';
+    const port = Number(env.CAMO_WS_PORT || defaults.wsPort || 8765);
+    return `ws://${host}:${port}`;
+  };
+
+  const getBrowserHttpBase = () => {
+    if (env.CAMO_BROWSER_HTTP_BASE) return env.CAMO_BROWSER_HTTP_BASE.replace(/\/$/, '');
+    const host = env.CAMO_BROWSER_HTTP_HOST || defaults.httpHost || '127.0.0.1';
+    const port = Number(env.CAMO_BROWSER_HTTP_PORT || defaults.httpPort || 7704);
+    const protocol = env.CAMO_BROWSER_HTTP_PROTO || defaults.httpProtocol || 'http';
+    return `${protocol}://${host}:${port}`;
+  };
+
+  const browserServiceCommand = async (action, args, options = {}) => {
+    const timeoutMs = typeof options.timeoutMs === 'number' && options.timeoutMs > 0
+      ? options.timeoutMs
+      : 20000;
+    const profileId = (args?.profileId || args?.profile || args?.sessionId || '').toString();
+    debugLog?.('browserServiceCommand:start', { action, profileId, timeoutMs });
+    const res = await fetch(`${getBrowserHttpBase()}/command`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action, args }),
+      signal: AbortSignal.timeout ? AbortSignal.timeout(timeoutMs) : undefined,
+    });
+
+    const raw = await res.text();
+    let data = {};
+    try {
+      data = raw ? JSON.parse(raw) : {};
+    } catch {
+      data = { raw };
+    }
+
+    if (!res.ok) {
+      debugLog?.('browserServiceCommand:http_err', { action, profileId, status: res.status, raw: raw?.slice?.(0, 200) });
+      throw new Error(data?.error || data?.body?.error || `browser-service command "${action}" HTTP ${res.status}`);
+    }
+    if (data && data.ok === false) {
+      debugLog?.('browserServiceCommand:ok_false', { action, profileId, error: data.error });
+      throw new Error(data.error || `browser-service command "${action}" failed`);
+    }
+    if (data && data.error) {
+      debugLog?.('browserServiceCommand:body_err', { action, profileId, error: data.error });
+      throw new Error(data.error);
+    }
+    debugLog?.('browserServiceCommand:ok', { action, profileId });
+    return data.body ?? data;
+  };
+
+  const sendWsCommand = (wsUrl, payload, timeoutMs = 15000) => new Promise((resolve, reject) => {
+    const socket = new WebSocket(wsUrl);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.terminate();
+      reject(new Error('WebSocket command timeout'));
+    }, timeoutMs);
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      socket.removeAllListeners();
+    };
+
+    socket.once('open', () => {
+      try {
+        socket.send(JSON.stringify(payload));
+      } catch (err) {
+        cleanup();
+        if (!settled) {
+          settled = true;
+          reject(err);
+        }
+      }
+    });
+
+    socket.once('message', (data) => {
+      cleanup();
+      if (settled) return;
+      settled = true;
+      try {
+        resolve(JSON.parse(data.toString('utf-8')));
+      } catch (err) {
+        reject(err);
+      } finally {
+        socket.close();
+      }
+    });
+
+    socket.once('error', (err) => {
+      cleanup();
+      if (settled) return;
+      settled = true;
+      reject(err);
+    });
+
+    socket.once('close', () => {
+      cleanup();
+      if (!settled) {
+        settled = true;
+        reject(new Error('WebSocket closed before response'));
+      }
+    });
+  });
+
+  return {
+    getBrowserWsUrl,
+    getBrowserHttpBase,
+    browserServiceCommand,
+    sendWsCommand,
+  };
+}

package/src/utils/browser-service.mjs

@@ -9,7 +9,7 @@ import { BROWSER_SERVICE_URL, loadConfig, setRepoRoot } from './config.mjs';
 import { touchSessionActivity } from '../lifecycle/session-registry.mjs';
 
 const require = createRequire(import.meta.url);
-const DEFAULT_API_TIMEOUT_MS = 30000;
+const DEFAULT_API_TIMEOUT_MS = 90000;
 
 function resolveApiTimeoutMs(options = {}) {
   const optionValue = Number(options?.timeoutMs);
@@ -23,6 +23,78 @@ function resolveApiTimeoutMs(options = {}) {
   return DEFAULT_API_TIMEOUT_MS;
 }
 
+function resolveWsUrl() {
+  const cfg = loadConfig();
+  const explicit = String(process.env.CAMO_WS_URL || '').trim();
+  if (explicit) return explicit;
+  const host = String(process.env.CAMO_WS_HOST || '127.0.0.1').trim() || '127.0.0.1';
+  const port = Number(process.env.CAMO_WS_PORT || 8765) || 8765;
+  return `ws://${host}:${port}`;
+}
+
+async function openWs() {
+  if (typeof WebSocket !== 'function') {
+    throw new Error('Global WebSocket is unavailable in this Node runtime');
+  }
+  const wsUrl = resolveWsUrl();
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(wsUrl);
+    const timer = setTimeout(() => {
+      try { socket.close(); } catch {}
+      reject(new Error(`WebSocket connect timeout: ${wsUrl}`));
+    }, 8000);
+    socket.addEventListener('open', () => {
+      clearTimeout(timer);
+      resolve(socket);
+    });
+    socket.addEventListener('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`WebSocket connect failed: ${err?.message || String(err)}`));
+    });
+  });
+}
+
+export async function callWS(action, payload = {}, options = {}) {
+  const timeoutMs = resolveApiTimeoutMs(options);
+  const socket = await openWs();
+  const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const sessionId = String(payload?.profileId || payload?.sessionId || payload?.profile || '').trim();
+  const message = {
+    type: 'command',
+    request_id: requestId,
+    session_id: sessionId,
+    data: { command_type: 'dev_command', action, parameters: payload },
+  };
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      try { socket.close(); } catch {}
+      reject(new Error(`browser-service ws timeout after ${timeoutMs}ms: ${action}`));
+    }, timeoutMs);
+
+    socket.addEventListener('message', (event) => {
+      try {
+        const data = typeof event.data === 'string' ? JSON.parse(event.data) : JSON.parse(String(event.data));
+        if (data?.type === 'response' && data.request_id === requestId) {
+          clearTimeout(timer);
+          try { socket.close(); } catch {}
+          resolve(data?.data ?? data);
+        }
+      } catch (err) {
+        clearTimeout(timer);
+        try { socket.close(); } catch {}
+        reject(err);
+      }
+    });
+
+    socket.send(JSON.stringify(message));
+  });
+}
+
+export function findRepoRootCandidate() {
+  return null;
+}
+
 function isTimeoutError(error) {
   const name = String(error?.name || '').toLowerCase();
   const message = String(error?.message || '').toLowerCase();
@@ -342,64 +414,17 @@ export function ensureCamoufox() {
   console.log('Camoufox installed.');
 }
 
-const START_SCRIPT_REL = path.join('runtime', 'infra', 'utils', 'scripts', 'service', 'start-browser-service.mjs');
-const CONTROLLER_SERVER_REL = path.join('services', 'controller', 'src', 'server.mjs');
+const CONTROLLER_SERVER_REL = path.join('src', 'services', 'browser-service', 'index.js');
 
-function hasStartScript(root) {
-  if (!root) return false;
-  return fs.existsSync(path.join(root, START_SCRIPT_REL));
-}
 
 function hasControllerServer(root) {
   if (!root) return false;
   return fs.existsSync(path.join(root, CONTROLLER_SERVER_REL));
 }
 
-function walkUpForRepoRoot(startDir) {
-  if (!startDir) return null;
-  let cursor = path.resolve(startDir);
-  for (;;) {
-    if (hasStartScript(cursor)) return cursor;
-    const parent = path.dirname(cursor);
-    if (parent === cursor) return null;
-    cursor = parent;
-  }
-}
 
-function scanCommonRepoRoots() {
-  const home = os.homedir();
-  const roots = [
-    path.join(home, 'Documents', 'github'),
-    path.join(home, 'github'),
-    path.join(home, 'code'),
-    path.join(home, 'projects'),
-    path.join('/Volumes', 'extension', 'code'),
-    path.join('C:', 'code'),
-    path.join('D:', 'code'),
-    path.join('C:', 'projects'),
-    path.join('D:', 'projects'),
-    path.join('C:', 'Users', os.userInfo().username, 'code'),
-    path.join('C:', 'Users', os.userInfo().username, 'projects'),
-    path.join('C:', 'Users', os.userInfo().username, 'Documents', 'github'),
-  ].filter(Boolean);
 
-  for (const root of roots) {
-    if (!fs.existsSync(root)) continue;
-    try {
-      const entries = fs.readdirSync(root, { withFileTypes: true });
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        if (!entry.name.toLowerCase().includes('webauto')) continue;
-        const candidate = path.join(root, entry.name);
-        if (hasStartScript(candidate)) return candidate;
-      }
-    } catch {
-      // ignore scanning errors and continue
-    }
-  }
 
-  return null;
-}
 
 function scanCommonInstallRoots() {
   const home = os.homedir();
@@ -416,75 +441,32 @@ function scanCommonInstallRoots() {
   ].filter(Boolean);
 
   for (const root of nodeModuleRoots) {
-    const candidate = path.join(root, '@web-auto', 'webauto');
+    const candidate = path.join(root, '@web-auto', 'camo');
     if (hasControllerServer(candidate)) return candidate;
   }
   return null;
 }
 
-export function findRepoRootCandidate() {
-  const cfg = loadConfig();
-  const candidates = [
-    process.env.WEBAUTO_REPO_ROOT,
-    cfg.repoRoot,
-    process.cwd(),
-    path.join('/Volumes', 'extension', 'code', 'webauto'),
-    path.join('/Volumes', 'extension', 'code', 'WebAuto'),
-    path.join(os.homedir(), 'Documents', 'github', 'webauto'),
-    path.join(os.homedir(), 'Documents', 'github', 'WebAuto'),
-    path.join(os.homedir(), 'github', 'webauto'),
-    path.join(os.homedir(), 'github', 'WebAuto'),
-    path.join('C:', 'code', 'webauto'),
-    path.join('C:', 'code', 'WebAuto'),
-    path.join('C:', 'Users', os.userInfo().username, 'code', 'webauto'),
-    path.join('C:', 'Users', os.userInfo().username, 'code', 'WebAuto'),
-  ].filter(Boolean);
 
-  for (const root of candidates) {
-    if (hasStartScript(root)) {
-      if (cfg.repoRoot !== root) {
-        setRepoRoot(root);
-      }
-      return root;
-    }
-  }
 
-  for (const startDir of [process.cwd()]) {
-    const found = walkUpForRepoRoot(startDir);
-    if (found) {
-      if (cfg.repoRoot !== found) {
-        setRepoRoot(found);
-      }
-      return found;
-    }
-  }
 
-  const scanned = scanCommonRepoRoots();
-  if (scanned) {
-    if (cfg.repoRoot !== scanned) {
-      setRepoRoot(scanned);
-    }
-    return scanned;
-  }
 
-  return null;
-}
 
 export function findInstallRootCandidate() {
   const cfg = loadConfig();
   const currentDir = path.dirname(fileURLToPath(import.meta.url));
-  const siblingInScopedNodeModules = path.resolve(currentDir, '..', '..', '..', 'webauto');
+  const siblingInScopedNodeModules = path.resolve(currentDir, '..', '..', '..', 'camo');
   const candidates = [
-    process.env.WEBAUTO_INSTALL_DIR,
-    process.env.WEBAUTO_PACKAGE_ROOT,
-    process.env.WEBAUTO_REPO_ROOT,
+    process.env.CAMO_INSTALL_DIR,
+    process.env.CAMO_PACKAGE_ROOT,
+    process.env.CAMO_REPO_ROOT,
     cfg.repoRoot,
     siblingInScopedNodeModules,
     process.cwd(),
   ].filter(Boolean);
 
   try {
-    const pkgPath = require.resolve('@web-auto/webauto/package.json');
+    const pkgPath = require.resolve('@web-auto/camo/package.json');
     candidates.push(path.dirname(pkgPath));
   } catch {
     // ignore resolution failures in npx-only environments
@@ -504,34 +486,27 @@ export function findInstallRootCandidate() {
 export async function ensureBrowserService() {
   if (await checkBrowserService()) return;
 
-  const repoRoot = findRepoRootCandidate();
-  if (repoRoot) {
-    const scriptPath = path.join(repoRoot, START_SCRIPT_REL);
-    console.log('Starting browser-service daemon...');
-    execSync(`node "${scriptPath}"`, { stdio: 'inherit', cwd: repoRoot });
-  } else {
-    const installRoot = findInstallRootCandidate();
-    if (!installRoot) {
-      throw new Error(
-        `Cannot locate browser-service launcher (${START_SCRIPT_REL} or ${CONTROLLER_SERVER_REL}). ` +
-        'Set WEBAUTO_INSTALL_DIR=<@web-auto/webauto install dir> or WEBAUTO_REPO_ROOT=<repo root>.',
-      );
-    }
-    const scriptPath = path.join(installRoot, CONTROLLER_SERVER_REL);
-    const env = {
-      ...process.env,
-      WEBAUTO_REPO_ROOT: String(process.env.WEBAUTO_REPO_ROOT || '').trim() || installRoot,
-    };
-    const child = spawn(process.execPath, [scriptPath], {
-      cwd: installRoot,
-      detached: true,
-      stdio: 'ignore',
-      windowsHide: true,
-      env,
-    });
-    child.unref();
-    console.log(`Starting browser-service daemon (packaged webauto, pid=${child.pid || 'unknown'})...`);
+  const installRoot = findInstallRootCandidate();
+  if (!installRoot) {
+    throw new Error(
+      `Cannot locate browser-service launcher (${CONTROLLER_SERVER_REL}). ` +
+      'Ensure @web-auto/camo is installed or set CAMO_INSTALL_DIR.',
+    );
   }
+  const scriptPath = path.join(installRoot, CONTROLLER_SERVER_REL);
+  const env = {
+    ...process.env,
+    CAMO_REPO_ROOT: String(process.env.CAMO_REPO_ROOT || '').trim() || installRoot,
+  };
+  const child = spawn(process.execPath, [scriptPath], {
+    cwd: installRoot,
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    env,
+  });
+  child.unref();
+  console.log(`Starting browser-service daemon (pid=${child.pid || 'unknown'})...`);
 
   for (let i = 0; i < 20; i += 1) {
     await new Promise((r) => setTimeout(r, 400));

package/src/utils/config.mjs

@@ -19,50 +19,58 @@ function normalizePathForPlatform(input, platform = process.platform) {
   return isWinPath ? pathApi.normalize(raw) : path.resolve(raw);
 }
 
-function normalizeLegacyWebautoRoot(input, platform = process.platform) {
+function normalizeLegacyCamoRoot(input, platform = process.platform) {
   const pathApi = platform === 'win32' ? path.win32 : path;
   const resolved = normalizePathForPlatform(input, platform);
   const base = pathApi.basename(resolved).toLowerCase();
-  if (base === '.webauto' || base === 'webauto') return resolved;
-  return pathApi.join(resolved, '.webauto');
+  if (base === '.camo' || base === 'camo') return resolved;
+  return pathApi.join(resolved, '.camo');
 }
 
-export function resolveWebautoRoot(options = {}) {
+export function resolveCamoRoot(options = {}) {
   const env = options.env || process.env;
   const platform = String(options.platform || process.platform);
   const pathApi = platform === 'win32' ? path.win32 : path;
   const homeDir = String(options.homeDir || os.homedir());
-  const explicitDataRoot = String(env.WEBAUTO_DATA_ROOT || env.WEBAUTO_HOME || '').trim();
+  const explicitDataRoot = String(env.CAMO_DATA_ROOT || env.CAMO_HOME || '').trim();
   if (explicitDataRoot) return normalizePathForPlatform(explicitDataRoot, platform);
 
-  const legacyRoot = String(env.WEBAUTO_ROOT || env.WEBAUTO_PORTABLE_ROOT || '').trim();
-  if (legacyRoot) return normalizeLegacyWebautoRoot(legacyRoot, platform);
+  const legacyRoot = String(env.CAMO_ROOT || env.CAMO_PORTABLE_ROOT || '').trim();
+  if (legacyRoot) return normalizeLegacyCamoRoot(legacyRoot, platform);
 
   const dDriveExists = typeof options.hasDDrive === 'boolean'
     ? options.hasDDrive
     : hasDrive('D');
   if (platform === 'win32') {
-    return dDriveExists ? 'D:\\webauto' : pathApi.join(homeDir, '.webauto');
+    return dDriveExists ? 'D:\\camo' : pathApi.join(homeDir, '.camo');
   }
-  return pathApi.join(homeDir, '.webauto');
+  return pathApi.join(homeDir, '.camo');
+}
+
+// Backward-compatible export name; camo no longer uses legacy paths.
+export function resolveLegacyRoot(options = {}) {
+  return resolveCamoRoot(options);
 }
 
 export function resolveProfilesDir(options = {}) {
   const env = options.env || process.env;
   const platform = String(options.platform || process.platform);
-  const explicitProfileRoot = String(env.WEBAUTO_PROFILE_ROOT || '').trim();
+  const explicitProfileRoot = String(env.CAMO_PROFILE_ROOT || env.CAMO_PATHS_PROFILES || '').trim();
   if (explicitProfileRoot) {
     return normalizePathForPlatform(explicitProfileRoot, platform);
   }
   const pathApi = platform === 'win32' ? path.win32 : path;
-  return pathApi.join(resolveWebautoRoot(options), 'profiles');
+  return pathApi.join(resolveCamoRoot(options), 'profiles');
 }
 
-export const CONFIG_DIR = resolveWebautoRoot();
+export const CONFIG_DIR = resolveCamoRoot();
 export const PROFILES_DIR = resolveProfilesDir();
 export const CONFIG_FILE = path.join(CONFIG_DIR, 'camo-cli.json');
 export const PROFILE_META_FILE = 'camo-profile.json';
-export const BROWSER_SERVICE_URL = process.env.WEBAUTO_BROWSER_URL || 'http://127.0.0.1:7704';
+export const BROWSER_SERVICE_URL = process.env.CAMO_BROWSER_URL
+  || process.env.CAMO_BROWSER_HTTP_URL
+  || process.env.CAMO_BROWSER_HOST
+  || 'http://127.0.0.1:7704';
 
 export function ensureDir(p) {
   if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
@@ -202,12 +210,5 @@ export function setProfileWindowSize(profileId, width, height) {
       height: Math.floor(parsedHeight),
       updatedAt: now,
     },
-  });
-}
-
-const START_SCRIPT_REL = path.join('runtime', 'infra', 'utils', 'scripts', 'service', 'start-browser-service.mjs');
-
-export function hasStartScript(root) {
-  if (!root) return false;
-  return fs.existsSync(path.join(root, START_SCRIPT_REL));
+ });
 }

package/src/utils/help.mjs

@@ -20,8 +20,9 @@ INITIALIZATION:
   create profile <profileId>                Create a new profile
 
 CONFIG:
-  config repo-root [path]                   Get or set persisted webauto repo root
+  config repo-root [path]                   Get or set persisted camo repo root
   highlight-mode [status|on|off]            Global highlight mode for click/type/scroll (default: on)
+  attach <profileId|sessionId>             Attach to session via WS; read JSON commands from stdin
 
 BROWSER CONTROL:
   init                                      Ensure camoufox + ensure browser-service daemon
@@ -87,7 +88,6 @@ WINDOW:
   window resize [profileId] --width <w> --height <h> Resize browser window
 
 MOUSE:
-  mouse move [profileId] --x <x> --y <y> [--steps <n>]  Move mouse to coordinates
   mouse click [profileId] --x <x> --y <y> [--button left|right|middle] [--clicks <n>] [--delay <ms>]  Click at coordinates
   mouse wheel [profileId] [--deltax <px>] [--deltay <px>]  Scroll wheel
 
@@ -134,7 +134,6 @@ EXAMPLES:
   camo cookies auto start --interval 5000
   camo window move --x 100 --y 100
   camo window resize --width 1920 --height 1080
-  camo mouse move --x 500 --y 300
   camo mouse click --x 500 --y 300 --button left
   camo mouse wheel --deltay -300
   camo system display
@@ -145,6 +144,7 @@ EXAMPLES:
   camo lock list
   camo unlock myprofile
   camo stop
+  echo '{"action":"stop","args":{"profileId":"myprofile"}}' | camo attach myprofile
 
 CONTAINER FILTER & SUBSCRIPTION:
   container init [--source <dir>] [--force]         Initialize subscription dir + migrate container sets
@@ -172,12 +172,14 @@ PROGRESS EVENTS:
   (non-events commands auto-start daemon by default)
 
 ENV:
-  WEBAUTO_BROWSER_URL                       Default: http://127.0.0.1:7704
-  WEBAUTO_INSTALL_DIR                       Optional @web-auto/webauto install dir
-  WEBAUTO_REPO_ROOT                         Optional webauto repo root (dev mode)
-  WEBAUTO_DATA_ROOT / WEBAUTO_HOME         Optional data root (Windows default D:\\webauto)
-  WEBAUTO_PROFILE_ROOT                      Optional profile dir override
-  WEBAUTO_ROOT                              Legacy data root (auto-appends .webauto if needed)
+  CAMO_BROWSER_URL                           Default: http://127.0.0.1:7704
+  CAMO_INSTALL_DIR                           Optional @web-auto/camo install dir
+  CAMO_REPO_ROOT                             Optional camo repo root (dev mode)
+  CAMO_DATA_ROOT / CAMO_HOME                Optional data root (Windows default D:\\camo)
+  CAMO_PROFILE_ROOT                          Optional profile dir override
+  CAMO_ROOT                                  Legacy data root (auto-appends .camo if needed)
+  CAMO_WS_URL                                Optional ws://host:port override
+  CAMO_WS_HOST / CAMO_WS_PORT                WS host/port for browser-service
   CAMO_PROGRESS_EVENTS_FILE                 Optional path override for progress jsonl
   CAMO_PROGRESS_WS_HOST / CAMO_PROGRESS_WS_PORT   Progress daemon host/port (defaults: 127.0.0.1:7788)
 `);

package/src/utils/ws-client.mjs

@@ -0,0 +1,30 @@
+export function resolveWsUrl() {
+  const explicit = String(process.env.CAMO_WS_URL || '').trim();
+  if (explicit) return explicit;
+  const host = String(process.env.CAMO_WS_HOST || '127.0.0.1').trim() || '127.0.0.1';
+  const port = Number(process.env.CAMO_WS_PORT || 8765) || 8765;
+  return `ws://${host}:${port}`;
+}
+
+export async function ensureWsClient(wsUrl = resolveWsUrl()) {
+  if (typeof WebSocket !== 'function') {
+    throw new Error('Global WebSocket is unavailable in this Node runtime');
+  }
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(wsUrl);
+    const timer = setTimeout(() => {
+      try { socket.close(); } catch {}
+      reject(new Error(`WebSocket connect timeout: ${wsUrl}`));
+    }, 8000);
+
+    socket.addEventListener('open', () => {
+      clearTimeout(timer);
+      resolve(socket);
+    });
+
+    socket.addEventListener('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`WebSocket connect failed: ${err?.message || String(err)}`));
+    });
+  });
+}