@codeyam-editor/codeyam-editor 0.1.2 → 0.1.4

package/npm/launch-config.js

@@ -8,7 +8,14 @@
 // runs on a VM; the history is the cache that makes the last choice the default
 // and past launches one click to re-run.
 
-const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename } = require("./cloud");
+const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename, AGENT_ENV_VARS } = require("./cloud");
+
+/** The build agents a VM's editor terminal can run, as the keys of cloud.js's
+ *  AGENT_ENV_VARS. Deriving the selectable set from that map keeps it a single
+ *  source of truth with the agent→API-key-env-var mapping (cloud.js) and the
+ *  gcp-bootstrap CLI installer, so adding an agent is still a one-line change in
+ *  AGENT_ENV_VARS rather than a list to keep in sync here. */
+const AGENTS = Object.freeze(Object.keys(AGENT_ENV_VARS));
 
 const EMPTY_CONFIG = Object.freeze({
   clientRepo: "",
@@ -18,6 +25,9 @@ const EMPTY_CONFIG = Object.freeze({
   newProjectName: "",
   editorVariant: "dev",
   editorBranch: "",
+  // Build agent provider the VM's editor terminal runs (claude | codex | gemini).
+  // Defaults to claude; cloudUpArgs forwards it as cloud:up's --agent flag.
+  agent: "claude",
 });
 
 /** Coerce a raw form/query object into the canonical launch-config shape: trim
@@ -26,12 +36,17 @@ const EMPTY_CONFIG = Object.freeze({
 function normalizeLaunchConfig(input = {}) {
   const str = (v) => (typeof v === "string" ? v.trim() : "");
   const editorVariant = EDITOR_VARIANTS.includes(input.editorVariant) ? input.editorVariant : "dev";
+  // Coerce an unknown/absent agent to the default rather than rejecting — the
+  // form's agent selector only ever submits a known value, so an out-of-set
+  // agent is a stale query param, not an error.
+  const agent = AGENTS.includes(input.agent) ? input.agent : "claude";
   return {
     clientRepo: str(input.clientRepo),
     clientBranch: str(input.clientBranch),
     newProjectName: str(input.newProjectName),
     editorVariant,
     editorBranch: str(input.editorBranch),
+    agent,
   };
 }
 
@@ -58,22 +73,78 @@ function validateLaunchConfig(cfg) {
   return { ok: true };
 }
 
-/** Phase-1 gate mirror of cloud.js::assertVariantProvisionable — only `dev`
- *  provisions today; staging/production are Phase 2. */
+/** Gate mirror of cloud.js::assertVariantProvisionable — which editor variants
+ *  can be provisioned onto a cloud VM. All three variants now provision: `dev`
+ *  builds the editor image from source, while `staging`/`production` run the
+ *  published npm package (gcp-bootstrap pulls/builds Dockerfile.npm keyed off
+ *  the variant). An unknown variant is excluded so a typo never reaches a
+ *  launch. Pure; no I/O. */
 function isVariantProvisionable(variant) {
-  return variant === "dev";
+  return EDITOR_VARIANTS.includes(variant);
+}
+
+/** Gate for the in-place BINARY-REBUILD operations (the dashboard's "Rebuild
+ *  binary" / "Update & Reset Everything" actions, and reconfigure's trailing
+ *  binary refresh). Historically distinct from `isVariantProvisionable` because a
+ *  packaged variant's rebuild is an npm-reinstall (rebuildStrategy ===
+ *  "npm-reinstall") and that host-script path was not wired — so this stayed
+ *  dev-only and packaged rebuild buttons failed loud. With the npm-reinstall
+ *  branch now wired into `rebuildBinaryHostScript` (it rebuilds the Dockerfile.npm
+ *  image at the variant's dist-tag instead of source-building Dockerfile), every
+ *  provisionable variant is also rebuildable, so this now mirrors
+ *  `isVariantProvisionable` — only an unknown variant is rejected. Pure; no I/O. */
+function isVariantRebuildable(variant) {
+  return isVariantProvisionable(variant);
+}
+
+/** Map an editor variant to the npm dist-tag its package was published under.
+ *  CI publishes `codeyam.com` → "latest" (production) and `staging.codeyam.com`
+ *  → "staging" (see .github/workflows/cicd.yml "Set release variant"). `dev` has
+ *  no published package (it builds the image from source), so return null and let
+ *  callers reject it. This is the single source of truth for the variant→dist-tag
+ *  contract — the Dockerfile.npm build-arg, publish-editor-image.sh's `--from-npm`
+ *  mode, and the future reconfigure path all derive from it so they can't drift.
+ *  Pure; no I/O. */
+function variantNpmDistTag(variant) {
+  if (variant === "production") return "latest";
+  if (variant === "staging") return "staging";
+  return null; // dev / unknown — no packaged dist-tag
+}
+
+/** Map a packaged editor variant to the GHCR image-tag suffix the packaged
+ *  image is pushed under (`<registry>/codeyam-editor-npm:<suffix>`). Lives beside
+ *  `variantNpmDistTag` so the registry naming convention and the dist-tag mapping
+ *  stay one reviewable unit; `scripts/publish-editor-image.sh --from-npm` asserts
+ *  the literal string this returns. `dev` has no packaged image (built from
+ *  source), so return null. Pure; no I/O. */
+function variantImageTag(variant) {
+  if (variant === "production") return "production-latest";
+  if (variant === "staging") return "staging-latest";
+  return null; // dev / unknown — no packaged image
 }
 
 /** Build the `cloud:up` flag array for a launch config + instance name. The
  *  editor source is the canonical codeyam-editor repo (dev variant builds the
  *  image from editorBranch); the client repo/branch is what lands in
- *  /workspace. Decoupled exactly as cloud.js consumes them. */
-function cloudUpArgs(cfg, instanceName, agent = "claude") {
+ *  /workspace. The build agent rides on `cfg.agent` (normalizeLaunchConfig
+ *  guarantees a known value, defaulting to claude), so a single config object
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them. */
+function cloudUpArgs(cfg, instanceName, project) {
   const args = ["--instance-name", instanceName];
+  // Pass the authoritative GCP project (the dashboard's resolved PROJECT)
+  // explicitly so cloud:up never relies on the spawning shell's ambient
+  // `gcloud config get-value project`. Critically, a `--project` flag OVERRIDES
+  // a persisted .codeyam/cloud.json `project` (cloud.js merges
+  // `{ ...existing, ...flags }`), which a bare cloud:up reuses verbatim with no
+  // gcloud fallback — the sticky-wrong-project failure mode where a stale
+  // "gcp-proj" in cloud.json wedges every re-provision with a firewall-create
+  // PERMISSION_DENIED. Omitted when unset to preserve the pre-existing arg shape
+  // (cloud.js then falls back to the gcloud default, as before).
+  if (project) args.push("--project", project);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
   else args.push("--repo", cfg.clientRepo);
-  args.push("--agent", agent, "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
+  args.push("--agent", cfg.agent || "claude", "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
   if (!cfg.newProjectName && cfg.clientBranch) args.push("--branch", cfg.clientBranch);
   if (cfg.editorBranch) args.push("--editor-branch", cfg.editorBranch);
   // The dashboard opens its own per-VM tunnel, so cloud:up must NOT open one:
@@ -193,6 +264,40 @@ function distinctConfigs(history, limit = 12) {
   return out;
 }
 
+/** Display-side companion to `distinctConfigs`: derive the two label strings the
+ *  "recent launches" picker renders for one config, so two configs that differ
+ *  only by build agent (or greenfield project name) look different instead of
+ *  collapsing to identical rows. `distinctConfigs` de-dups on the FULL config, so
+ *  the rows are genuinely distinct launches — the old inline label just never
+ *  surfaced the distinguishing fields (agent, greenfield name).
+ *
+ *  Returns { primary, secondary }:
+ *   - primary:   greenfield (`!clientRepo && newProjectName`) → `new: <name>` so
+ *                two different greenfield projects no longer both read `(none)`;
+ *                else `repoBasename(clientRepo)` + (`@<branch>` when set); else
+ *                `(none)` when there's neither a repo nor a project name.
+ *   - secondary: `editor <variant>` + (`@<editorBranch>` when set) + ` · <agent>`.
+ *
+ *  Normalizes through EMPTY_CONFIG so a pre-`agent` history entry still renders
+ *  `· claude`. Reuses `repoBasename` (cloud.js) so server/browser basename
+ *  semantics stay single-sourced. Pure; no I/O. */
+function recentLaunchDisplay(config) {
+  const cfg = { ...EMPTY_CONFIG, ...(config || {}) };
+  let primary;
+  if (!cfg.clientRepo && cfg.newProjectName) {
+    primary = `new: ${cfg.newProjectName}`;
+  } else if (cfg.clientRepo) {
+    primary = repoBasename(cfg.clientRepo) + (cfg.clientBranch ? `@${cfg.clientBranch}` : "");
+  } else {
+    primary = "(none)";
+  }
+  const secondary =
+    `editor ${cfg.editorVariant || "dev"}` +
+    (cfg.editorBranch ? `@${cfg.editorBranch}` : "") +
+    ` · ${cfg.agent || "claude"}`;
+  return { primary, secondary };
+}
+
 /** The default config to pre-fill the launch form: the most recent launch's
  *  config, or an empty config when there's no history. */
 function defaultConfig(history) {
@@ -258,6 +363,25 @@ function resolveCardIdentity(live, historyCfg) {
   return { project, clientBranch, editorLabel, source };
 }
 
+/** Sticky-merge a VM poll's `clientProject` against the last-known-good value
+ *  so a transient null poll (timeout / partial probe) does not clobber a
+ *  populated identity. The live `clientProject.branch` is the fleet
+ *  classifier's first-choice branch source (`plan_actions` in
+ *  fleet-roll-to-branch.sh); dropping it to null on a missed cycle would
+ *  regress classification to the stale launch-history branch. Mirrors how the
+ *  other live fields tolerate a missed poll: a populated `prev` survives a
+ *  null/absent fresh poll, and a populated fresh poll always wins. Pure; no I/O.
+ *
+ *  @param prev  the previous `state.vms[n].clientProject` (null/undefined ok)
+ *  @param info  the fresh poll result object (null when the probe failed)
+ *  @returns the clientProject to store: fresh value when present, else the
+ *           last-known-good `prev`, else null. */
+function stickyClientProject(prev, info) {
+  const fresh = info && info.clientProject;
+  if (fresh) return fresh;
+  return prev || null;
+}
+
 /** Classify a VM's project KIND as `"self-host"` vs `"guest"` from the live
  *  identity reported in `/api/session-info` (`clientProject.repo`), with
  *  launch-history `clientRepo` as a fallback when live is absent. A guest is
@@ -328,11 +452,21 @@ function resolveEditorSource({ selfHost = false, home = "$HOME" } = {}) {
  *  `$HOME`-bearing path defeats remote expansion: `cd "$ESRC"` then fails with
  *  `cd: $HOME/...: No such file or directory` on every non-self-host VM (the improve34
  *  bug). These paths are fixed constants, not user input — no injection surface, so
- *  `shq()` (which exists to neutralize user input) is the wrong tool. Pure; no I/O. */
+ *  `shq()` (which exists to neutralize user input) is the wrong tool. Pure; no I/O.
+ *
+ *  The primary clone is kept only when it is actually USABLE as an editor source,
+ *  not merely when a `.git` directory exists. A half-cloned / corrupt tree has a
+ *  `.git` dir yet can't build — `git rev-parse` fails and there's no Dockerfile, so
+ *  `docker build "$ESRC"` dies on `open Dockerfile: no such file or directory` (the
+ *  improve39 VM-9 bug). The gate therefore requires a valid work tree AND a
+ *  Dockerfile; otherwise it falls back to the canonical image clone
+ *  `$HOME/codeyam-editor` (the authoritative source provisioning built the image
+ *  from). This preserves the prefer-credentialed-clone behavior, but only when the
+ *  credentialed clone actually works. */
 function editorSourceShellResolve(src) {
   const primary = `ESRC="${src.path}"`;
   if (!src.fallbackPath) return primary;
-  return `${primary}; [ -d "$ESRC/.git" ] || ESRC="${src.fallbackPath}"`;
+  return `${primary}; { git -C "$ESRC" rev-parse --is-inside-work-tree >/dev/null 2>&1 && [ -f "$ESRC/Dockerfile" ]; } || ESRC="${src.fallbackPath}"`;
 }
 
 /** Choose HOW to rebuild the editor binary on a VM, from its shape + the editor
@@ -343,11 +477,12 @@ function editorSourceShellResolve(src) {
  *    - "image-rebuild" — non-self-host `dev`: the binary ships in the
  *                        `codeyam-editor:local` image, so it needs a host-side
  *                        `docker build` + container recreate.
- *    - "npm-reinstall" — a packaged variant (`staging`/`production`, Phase 2):
- *                        the binary is the published editor npm package, so a
- *                        rebuild is a reinstall, not a compile.
- *  Pure; no I/O. The dashboard reuses `isVariantProvisionable` to gate the
- *  not-yet-wired npm-reinstall path; the self-host axis is detected at runtime
+ *    - "npm-reinstall" — a packaged variant (`staging`/`production`): the binary
+ *                        is the published editor npm package, so a rebuild is a
+ *                        reinstall, not a compile.
+ *  Pure; no I/O. `rebuildBinaryHostScript` consumes this to pick its build line
+ *  (the npm-reinstall branch rebuilds the Dockerfile.npm image at the variant's
+ *  dist-tag); the self-host axis is detected at runtime
  *  on the VM (the `[ -f /workspace/Cargo.toml ]` signal is authoritative even
  *  for VMs the dashboard has no launch-history record for). */
 function rebuildStrategy({ selfHost = false, editorVariant = "dev" } = {}) {
@@ -517,11 +652,55 @@ function buildEnvApplyCommand({ gcloud, instance, zone, envFile, container, edit
   return `base64 < ${_shq(envFile)} | ${gcloud} compute ssh ${instance} --tunnel-through-iap --zone=${zone} --command=${_shq(sink)}`;
 }
 
+/** Get authenticated Git URL for checking client branch. */
+function getAuthRepoUrl(repo, token) {
+  if (!repo) return "";
+  if (!token) return repo;
+  const sshRegex = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/;
+  const sshMatch = repo.match(sshRegex);
+  if (sshMatch) {
+    return `https://x-access-token:${token}@github.com/${sshMatch[1]}/${sshMatch[2]}`;
+  }
+  if (repo.startsWith("https://github.com/")) {
+    return repo.replace(/^https:\/\/github\.com\//, `https://x-access-token:${token}@github.com/`);
+  }
+  return repo;
+}
+
+/** Interpret the output of git ls-remote to see if a branch exists. */
+function interpretLsRemote({ stdout = "", code = 0, err = null, repo = "", branch = "" } = {}) {
+  const b = (branch || "").trim();
+  if (!b) {
+    return { ok: true, msg: "using repo default branch" };
+  }
+  if (err || code !== 0) {
+    const errMsg = (err && (err.message || String(err))) || "command failed";
+    return {
+      ok: false,
+      soft: true,
+      msg: `couldn't verify branch: ${errMsg.trim()}`
+    };
+  }
+  const trimmed = (stdout || "").trim();
+  if (trimmed) {
+    return { ok: true };
+  } else {
+    return {
+      ok: false,
+      msg: `branch '${b}' not found in ${repo || "repository"}`
+    };
+  }
+}
+
 module.exports = {
+  AGENTS,
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
   isVariantProvisionable,
+  isVariantRebuildable,
+  variantNpmDistTag,
+  variantImageTag,
   cloudUpArgs,
   classifyContainerWait,
   decideAddSlot,
@@ -529,9 +708,11 @@ module.exports = {
   queuedStatusForAction,
   pushHistory,
   distinctConfigs,
+  recentLaunchDisplay,
   defaultConfig,
   configForVm,
   resolveCardIdentity,
+  stickyClientProject,
   classifyProjectKind,
   resolveCredsSource,
   buildCredsSteps,
@@ -541,4 +722,6 @@ module.exports = {
   editorSourceShellResolve,
   rebuildStrategy,
   decideStartJob,
+  getAuthRepoUrl,
+  interpretLsRemote,
 };

package/npm/preflight-guidance.js

@@ -10,6 +10,15 @@
  * Mirrors the heuristic in `migration_status::is_legacy_config`: a
  * `.codeyam/config.json` whose JSON has a top-level `webapps` key marks a
  * legacy project. Anything else with no `editor.json` is greenfield.
+ *
+ * Rust-side behavior note (improve39): `start_preflight` no longer bails on an
+ * EMPTY greenfield folder — it auto-inits in place and boots the editor's wired
+ * scaffold flow. It still bails (exit 2) for an existing-source `none` folder
+ * (the `greenfieldGuidance` text below) and for legacy. This module is consumed
+ * by the launcher's bail/guidance path only; `classifyProject` does not itself
+ * decide empty-vs-non-empty (the launcher's `planPreflightAction` /
+ * `postLaunchInitBanner` in editor-dev.js own that split and intentionally
+ * auto-init all `none` projects as a local-dev convenience).
  */
 
 const fs = require("node:fs");

package/npm/scenario-check.js

@@ -78,7 +78,10 @@ const {
   loadScenarioInIframe,
   loadScenarioTopLevel,
   waitForStablePage,
+  createNetworkTracker,
+  waitForNetworkQuiet,
   collectContentState,
+  performInteraction,
 } = require("./scenario-playwright");
 
 const {
@@ -272,6 +275,76 @@ function pushRedirectMismatchIssue(issues, requestedUrl, frame, response, config
   );
 }
 
+// Read-only page-state snapshot for `capture-state`: the full localStorage
+// map, a bounded sample of visible text nodes (document order), and — when a
+// selector is given — that element's text. Evaluated in-page against the
+// settled frame so it reflects exactly what a real capture saw (the proxy
+// already injected the scenario's seed into the served HTML). Every read is
+// individually guarded so a sandboxed/cross-origin localStorage never throws
+// the whole capture; the worst case is an empty section, not a failure.
+async function dumpPageState(frame, selector) {
+  return frame.evaluate((sel) => {
+    const localStorage = {};
+    try {
+      for (let i = 0; i < window.localStorage.length; i++) {
+        const key = window.localStorage.key(i);
+        if (key != null) localStorage[key] = window.localStorage.getItem(key);
+      }
+    } catch (_) {
+      /* localStorage may be unavailable (sandboxed/opaque origin) */
+    }
+
+    const visibleText = [];
+    try {
+      // Reject text inside non-rendered tags (SCRIPT/STYLE/etc.) so an
+      // injected proxy script or inline CSS never masquerades as on-screen
+      // text — that noise is exactly what makes a state dump misleading.
+      const SKIP_TAGS = new Set([
+        "SCRIPT",
+        "STYLE",
+        "NOSCRIPT",
+        "TEMPLATE",
+        "HEAD",
+        "TITLE",
+      ]);
+      const walker = document.createTreeWalker(
+        document.body,
+        NodeFilter.SHOW_TEXT,
+        {
+          acceptNode(node) {
+            const parent = node.parentElement;
+            if (parent && SKIP_TAGS.has(parent.tagName)) {
+              return NodeFilter.FILTER_REJECT;
+            }
+            return (node.textContent || "").trim()
+              ? NodeFilter.FILTER_ACCEPT
+              : NodeFilter.FILTER_REJECT;
+          },
+        },
+      );
+      let node;
+      while ((node = walker.nextNode()) && visibleText.length < 40) {
+        const text = (node.textContent || "").replace(/\s+/g, " ").trim();
+        if (text) visibleText.push(text);
+      }
+    } catch (_) {
+      /* no body / detached document */
+    }
+
+    let selectorText = null;
+    if (sel) {
+      try {
+        const el = document.querySelector(sel);
+        if (el) selectorText = (el.textContent || "").replace(/\s+/g, " ").trim();
+      } catch (_) {
+        /* invalid selector — leave selectorText null */
+      }
+    }
+
+    return { localStorage, visibleText, selectorText };
+  }, selector || null);
+}
+
 // `preflight` is injectable (defaulting to the real app-port reachability
 // check) so unit tests that mock the browser can stay network-free.
 async function runScenarioCheck(config, { preflight = assertAppPortReachable } = {}) {
@@ -303,6 +376,11 @@ async function runScenarioCheck(config, { preflight = assertAppPortReachable } =
   await context.addInitScript(getInitScript());
 
   const page = await context.newPage();
+  // Attach the network tracker BEFORE navigation so every request (the document
+  // and every client-side data fetch) is counted. Used after DOM stability to
+  // wait out an in-flight fetch that would otherwise be screenshotted as a
+  // loading skeleton.
+  const networkTracker = createNetworkTracker(page);
   await attachHttpMocks(page, httpMocks);
 
   page.on("pageerror", (error) => {
@@ -361,6 +439,13 @@ async function runScenarioCheck(config, { preflight = assertAppPortReachable } =
       : readStackLoadingMarkers();
     await waitForStablePage(page, frame, 10000, loadingMarkers);
 
+    // DOM-stable does not mean done: a client-side data fetch can still be in
+    // flight (the loading skeleton cleared but its replacement content hasn't
+    // landed). Wait for the network to go quiet — bounded, so a streaming /
+    // long-poll endpoint that never idles caps out and captures anyway rather
+    // than hanging.
+    await waitForNetworkQuiet(networkTracker);
+
     const rejectionMessages = await frame.evaluate(
       () => window.__codeyamUnhandledRejections || [],
     );
@@ -430,18 +515,37 @@ async function runScenarioCheck(config, { preflight = assertAppPortReachable } =
       pushIssue(issues, hydrationIssue);
     }
 
+    // Drive the requested interaction (if any) against the settled frame,
+    // then re-settle, so `preview-interact` captures the RESULT of a click /
+    // fill / press (expanded accordion, open modal) without editing app
+    // source. A no-match target throws here and is caught below as a failed
+    // capture with the candidate-labels hint — never a silent blank shot.
+    if (config.interaction) {
+      await performInteraction(frame, config.interaction);
+      await waitForStablePage(page, frame, 5000, loadingMarkers);
+    }
+
     if (outputPath && loaded) {
       fs.mkdirSync(path.dirname(outputPath), { recursive: true });
       await page.screenshot({ path: outputPath, fullPage: false });
     }
 
-    return buildResult({
+    const result = buildResult({
       loaded,
       hasContent,
       issues,
       outputPath,
       url: frame.url() || url,
     });
+
+    // `capture-state` mode: attach the read-only page-state snapshot so the
+    // backend can report localStorage + rendered text. Off by default, so a
+    // normal error-check capture is byte-for-byte unchanged.
+    if (config.captureState) {
+      result.state = await dumpPageState(frame, config.stateSelector);
+    }
+
+    return result;
   } catch (error) {
     pushIssue(
       issues,
@@ -481,6 +585,7 @@ async function main() {
 
 module.exports = {
   runScenarioCheck,
+  dumpPageState,
   readStackLoadingMarkers,
   applyBrowserState,
   isCrossOriginRequest,

package/npm/scenario-handlers.js

@@ -48,6 +48,22 @@ function handleConsoleMessage(message) {
     return null;
   }
 
+  // Ignore the browser's blocked-script warning for sandboxed mockup-preview
+  // frames. Mockup previews render untrusted AI-generated HTML inside a
+  // `sandbox=""` iframe; the HTML-injection proxy injects an error-capture
+  // <script> tag, which the browser then refuses to run, emitting
+  // "Blocked script execution ... because the frame is sandboxed". That block
+  // is the capture's own injected script being denied — benign for capture
+  // purposes. Match narrowly on BOTH the block phrase and the "sandboxed"
+  // signature so a genuine non-sandbox CSP block ("Blocked script execution"
+  // without "sandboxed") still surfaces as a real issue.
+  if (
+    text.includes("Blocked script execution") &&
+    text.includes("sandboxed")
+  ) {
+    return null;
+  }
+
   return createIssue("console", text);
 }
 

package/npm/scenario-interactivity.js

@@ -92,19 +92,38 @@ function resolveInteractivityExpectation(stack) {
 // mutates anything, so it is safe to run before the screenshot is taken.
 //
 // Returns `{ controlCount, frameworkAttached }` where `frameworkAttached` is
-// `true` (runtime demonstrably attached), `false` (controls exist but no
-// attachment signal — the dead-hydration case), or `null` (no detector for
-// this framework → cannot judge).
+// `true` (runtime demonstrably attached), `false` (framework-owned controls
+// exist but no attachment signal — the dead-hydration case), or `null` (no
+// detector for this framework, OR every interactive control is delegated to a
+// terminal/canvas widget with no hydration marker → cannot judge).
 async function collectHydrationState(frame, { framework } = {}) {
   return frame.evaluate((fw) => {
     const SELECTOR =
       'button, [role="button"], a[href], input:not([type="hidden"]), select, textarea, summary, [onclick]';
+    // Roots of third-party terminal/canvas widgets that mount imperatively and
+    // wire their own (non-framework) event handlers — xterm's `.xterm`, any
+    // `<canvas>`, or an element a component explicitly flags terminal-backed.
+    // Interactive controls inside these (e.g. xterm's hidden helper
+    // `<textarea>`) never carry framework attachment keys even on a fully
+    // hydrated page, so judging hydration from them yields a false "not
+    // interactive" verdict. Stack assumption: `.xterm` is xterm-specific; the
+    // `<canvas>` and `[data-terminal-backed]` entries are framework-agnostic
+    // escape hatches any widget-embedding component can use.
+    const WIDGET_ROOT_SELECTOR = ".xterm, canvas, [data-terminal-backed]";
+
     const controls = Array.from(document.querySelectorAll(SELECTOR));
+    const inWidget = (el) =>
+      !!el &&
+      typeof el.closest === "function" &&
+      el.closest(WIDGET_ROOT_SELECTOR) != null;
+    // Framework-owned controls: those NOT delegated to a terminal/canvas
+    // widget. Only these can prove or disprove that the framework hydrated.
+    const frameworkControls = controls.filter((el) => !inWidget(el));
 
     // Per-framework attachment detectors. Each returns true when the framework
-    // has demonstrably attached its client runtime to a live interactive node.
-    // The presence of a detector for `fw` is itself the signal that we CAN
-    // judge this framework; the default (no detector) means "cannot determine".
+    // has demonstrably attached its client runtime to a live node. The
+    // presence of a detector for `fw` is itself the signal that we CAN judge
+    // this framework; the default (no detector) means "cannot determine".
     const detectors = {
       react: (els) =>
         els.some(
@@ -128,7 +147,34 @@ async function collectHydrationState(frame, { framework } = {}) {
     };
 
     const detector = detectors[fw];
-    const frameworkAttached = detector ? detector(controls) : null;
+
+    // Terminal/canvas scenarios prove hydration with an explicit, framework-
+    // rendered `data-codeyam-hydrated` marker. It counts only when the
+    // framework actually attached to it — a marker that exists in static HTML
+    // but never hydrated fails the same detector and does not count.
+    const markerEl = document.querySelector("[data-codeyam-hydrated]");
+    const markerAttached = detector
+      ? detector(markerEl ? [markerEl] : [])
+      : false;
+
+    let frameworkAttached;
+    if (!detector) {
+      // No detector for this framework — cannot judge (conservative pass).
+      frameworkAttached = null;
+    } else if (detector(frameworkControls) || markerAttached) {
+      // A genuinely framework-owned control attached, or an explicit hydration
+      // marker proves the framework ran — definitively hydrated.
+      frameworkAttached = true;
+    } else if (frameworkControls.length === 0) {
+      // Controls exist but every one lives inside a terminal/canvas widget and
+      // there is no marker — we cannot prove the page is dead, so never flag.
+      frameworkAttached = null;
+    } else {
+      // Framework-owned controls rendered but none attached — the dead-island
+      // signal the gate exists to catch.
+      frameworkAttached = false;
+    }
+
     return { controlCount: controls.length, frameworkAttached };
   }, framework || null);
 }