Skip to content

Official Codebase of 3DCodeVerse

Python
7.2 KB
Raw Blame
/**
 * Node-side driver around the page host: serve the workspace, launch the
 * browser, open the host page, boot the scene, collect console / page errors.
 * All three scene CLIs (render / probe / check_shaders) go through here.
 */

import fs from 'node:fs';
import path from 'node:path';
import { importMapHtml, launchBrowser, RUNTIME_MOUNT, serveWorkspace } from './host_env.mjs';

const SHADER_NOISE_RE = /shader|program not valid|glsl|WebGL|compile|THREE\.WebGLProgram/i;
const MAX_CONSOLE = 60;
const CONTROL_RE = new RegExp('[\\u0000-\\u001f]+', 'g');

function hostHtml() {
  return [
    '<!doctype html><html><head><meta charset="utf-8"><title>3dcode scene host</title>',
    importMapHtml(),
    '<style>html,body{margin:0;background:#000;overflow:hidden}</style></head><body>',
    `<script type="module" src="${RUNTIME_MOUNT}lib/scene_host.mjs"></script></body></html>`,
  ].join('\n');
}

function clean(s) {
  return String(s).replace(CONTROL_RE, ' ').trim();
}

/**
 * createScene() boot timeout for a driver: 60% of the driver budget capped at
 * 20 s — always below the watchdog so a hung boot is an agent-attributed scene
 * failure (exit 1 with boot.stage = 'createScene'), never a watchdog kill (exit 3).
 */
export function createTimeoutMs(driverTimeoutMs) {
  return Math.min(20000, Math.max(1000, Math.round(0.6 * driverTimeoutMs)));
}

/**
 * Error line for a puppeteer 'requestfailed' event, or null when it must be
 * ignored.  Chrome intermittently fires requestfailed with net::ERR_ABORTED
 * for a same-origin fetch that already received a 200 and was fully consumed
 * (three's FileLoader stream wrapper) — a phantom failure that used to fail
 * the render_console / scene_probe gates ~10% of rounds.  Real load failures
 * are still reported by the 404 'response' handler and LoadingManager.onError.
 */
export function requestFailureLine(url, base, hasResponse, errorText) {
  if (!url.startsWith(base)) return null;
  if (hasResponse || errorText === 'net::ERR_ABORTED') return null;
  return `request failed: ${url.slice(base.length)} (${errorText || '?'})`;
}

/**
 * Open the host for workspace `wsRoot`.  `onBoot()` is called once the page is ready, right before
 * the scene module is imported and createScene() runs (probe_scene.mjs: the watchdog's phase, D111).
 * @returns {Promise<{page, browser, base, gpu, renderer, errors, boot, close}>}
 */
export async function openHost(wsRoot, { width = 1024, height = 576, gpu = 'auto', sceneRel = 'src/scene.js', createSceneTimeoutMs = 0, settle = true, cameraRepair = false, post = true, postOptions = null, glb = null, onBoot = null } = {}) {
  wsRoot = path.resolve(wsRoot);
  // an offline scene (`glb`: its census GLB) boots the harness adapter, never a workspace module
  const sceneFile = glb || path.join(wsRoot, sceneRel);
  if (!fs.existsSync(sceneFile)) {
    throw new Error(glb ? `missing census GLB ${glb}` : `missing ${sceneRel} in workspace ${wsRoot}`);
  }
  const sceneUrl = glb ? `${RUNTIME_MOUNT}lib/glb_scene.mjs` : `/${sceneRel}`;
  const srv = await serveWorkspace(wsRoot, { hostHtml: hostHtml(), glb });
  const errors = { console: [], page: [], shader_console: [], warnings: [] };
  let launched = null;
  let page = null;
  try {
    launched = await launchBrowser({ gpu });
    page = await launched.browser.newPage();
    await page.setViewport({ width, height, deviceScaleFactor: 1 });
    page.on('console', (m) => {
      const type = m.type();
      if (type !== 'error' && type !== 'warning') return;
      const text = clean(m.text());
      if (!text) return;
      const isShader = SHADER_NOISE_RE.test(text);
      // Chrome's bare resource-load line duplicates the 404 the response handler
      // already reported with the URL and a hint; keep it out of the error bucket.
      const isResourceNoise = /Failed to load resource/.test(text);
      const bucket = type === 'warning' || isResourceNoise ? errors.warnings : (isShader ? errors.shader_console : errors.console);
      if (bucket.length < MAX_CONSOLE && !bucket.includes(text)) bucket.push(text.slice(0, 600));
    });
    page.on('pageerror', (e) => {
      const text = clean((e && (e.stack || e.message)) || e);
      if (errors.page.length < MAX_CONSOLE) errors.page.push(text.slice(0, 800));
    });
    page.on('requestfailed', (req) => {
      const line = requestFailureLine(req.url(), srv.base, !!req.response(), req.failure()?.errorText || '?');
      if (line) errors.console.push(line);
    });
    page.on('response', (res) => {
      if (res.status() === 404 && res.url().startsWith(srv.base)) {
        const rel = res.url().slice(srv.base.length);
        // a missing GLB/texture is a WARNING (the scene still boots and renders
        // without it — the judge sees the absence); a missing MODULE is fatal.
        const bucket = rel.startsWith('/assets/') || rel.startsWith('/public/') ? errors.warnings : errors.console;
        bucket.push(`404 not found: ${rel}` + (bucket === errors.console ? " (imports must be 'three', 'three/addons/*' or relative; assets under public/assets → '/assets/...')" : ' (build/copy the asset into public/assets/)'));
      }
    });
    await page.goto(`${srv.base}/__host.html`, { waitUntil: 'load', timeout: 60000 });
    await page.waitForFunction('window.__c3v_ready === true', { timeout: 60000 });
    if (onBoot) onBoot();
    const boot = await page.evaluate(
      (o) => window.__c3v.boot(o),
      { sceneUrl, width, height, createSceneTimeoutMs, settle, cameraRepair, post, postOptions },
    );
    const close = async () => {
      // page first, then release: a SHARED browser (connect-first reuse) must get
      // its pages closed by us and be disconnected, never closed.  Each step is
      // time-bounded: the result is already in hand when close() runs.
      await bounded(page.close(), 3000);
      await bounded(launched.release(), 3000);
      await bounded(srv.close(), 2000);
    };
    return { page, browser: launched.browser, base: srv.base, gpu: launched.gpu, renderer: launched.renderer, errors, boot, close };
  } catch (e) {
    if (page) await page.close().catch(() => {});
    if (launched?.browser) await launched.release().catch(() => {});
    await srv.close();
    throw e;
  }
}

/** Await `work`, but at most `ms` — cleanup must never dominate a driver's wall time
 * (a wedged shared browser once cost 100 s per render in page.close alone; the daemon's
 * page reaper picks up anything a bounded close leaves behind). */
export function bounded(work, ms) {
  let timer = null;
  return Promise.race([
    Promise.resolve(work).catch(() => {}),
    new Promise((res) => { timer = setTimeout(res, ms); if (timer.unref) timer.unref(); }),
  ]).finally(() => { if (timer) clearTimeout(timer); });
}

/** Flatten the collected errors into the summary shape used by all drivers. */
export function errorSummary(errors, boot) {
  const consoleErrors = [...errors.console, ...errors.page.map((p) => `pageerror: ${p}`)];
  if (boot && boot.error) consoleErrors.unshift(`boot[${boot.stage}]: ${boot.error}`);
  const warnings = [...errors.warnings];
  for (const le of (boot && boot.load_errors) || []) warnings.push(`load: ${le}`);
  return {
    console_errors: consoleErrors,
    console_warnings: warnings,
    shader_console: errors.shader_console,
  };
}