@codeyam-editor/codeyam-editor 0.1.2 → 0.1.3

package/npm/fleet-reset.js

@@ -31,30 +31,97 @@
 // Best-effort: a no-remote / queue-disabled project legitimately exits
 // non-zero, and we should not block the reset.
 //
-// Between the cp-asides and the `rm -rf` we cooperatively pause the editor
-// server (`stop-server --hold-for-restart`). Without that, the server keeps
-// writing to `.codeyam/logs/editor-server.log` and `.codeyam/run/` between
-// when `rm -rf` enumerates the dir and when it tries to `rmdir` the empty
-// directory — it surfaces as `rm: cannot remove '.codeyam': Directory not
-// empty`, which the dashboard reports as `error`. SIGUSR2 closes listeners +
-// stops the dev-server and parks the PID; the parent script's trailing
-// `restart-server --force-in-container` then resurrects via the existing
-// SIGUSR1 in-place reexec. Fail-soft `|| true` so a server that's already
-// dead (e.g. the reset is rerun after a partial failure) doesn't block the
-// chain.
+// Before the wipe we QUIESCE ALL WRITERS: park the editor server
+// (`stop-server --hold-for-restart`) AND stop the PTY broker
+// (`pty-broker stop`). Parking only the editor server is insufficient — the
+// broker is a SEPARATE process (and hooks / agent subprocesses can fire), so
+// it keeps re-creating `.codeyam/logs/` and `.codeyam/run/` between when the
+// wipe enumerates the dir and when it removes it. That race surfaced live
+// (VM-1, 2026-06-01) as `rm: cannot remove '.codeyam': Directory not empty`,
+// aborting the whole reset. Both quiesce calls are fail-soft `|| true` so a
+// server/broker that's already dead (e.g. the reset is rerun after a partial
+// failure) doesn't block the chain.
+//
+// The wipe itself is RETRY-RESILIENT instead of a single `rm -rf .codeyam`
+// that aborts the &&-chain on one transient re-creation: a bounded loop of
+// `find .codeyam -mindepth 1 -delete` empties the contents and tolerates a
+// brief re-create, then proceeds even if `.codeyam` is still non-empty after
+// best-effort (a soft retry, never a hard failure — `git checkout`/`init`
+// repopulates over whatever remains). Emptying contents (not removing the dir)
+// also sidesteps the `rmdir` race entirely.
+//
+// The destructive region (park → broker-stop → wipe → restore) is made
+// FAILURE-SAFE with an EXIT trap installed before the park and disarmed after
+// a successful restore. If ANY step in that region aborts the chain, the trap
+// still restores tracked `.codeyam` (or re-inits), copies the two preserved
+// infra files back, and runs `restart-server --force-in-container` before
+// exiting non-zero — so a failed deep-clean self-recovers to a working
+// (un-reset, but UP) VM instead of leaving it parked-and-down with a
+// half-wiped `.codeyam`, and still reports the failure. The happy path is
+// unchanged: the restore steps run, the trap is disarmed, and the caller's
+// own trailing `restart-server` resurrects the parked server.
 function codeyamDeepCleanSteps(E) {
+  // Restore primitives shared by the happy path and the trap recovery body.
+  const restoreCodeyam = `git checkout HEAD -- .codeyam 2>/dev/null || ${E} init`;
+  const restoreElj =
+    'test -f /tmp/cy-elj.bak && mkdir -p .codeyam && cp /tmp/cy-elj.bak .codeyam/editor.local.json';
+  const restoreSs =
+    'test -f /tmp/cy-ss.bak && mkdir -p .codeyam && cp /tmp/cy-ss.bak .codeyam/server-state.json';
+  // Recovery body: restore .codeyam + the two infra backups, then resurrect the
+  // parked server. Runs ONLY on the failure path (the happy path's own restore
+  // steps remove the backups; recovery here intentionally leaves them in place
+  // because on a mid-region abort those steps never ran).
+  const recover =
+    `${restoreCodeyam}; ( ${restoreElj}; true ); ( ${restoreSs}; true ); ` +
+    `${E} editor restart-server --force-in-container || true`;
   return [
     `( ${E} editor branch-queue release-mine --yes 2>/dev/null; true )`,
     '( cp .codeyam/editor.local.json /tmp/cy-elj.bak 2>/dev/null; true )',
     '( cp .codeyam/server-state.json /tmp/cy-ss.bak 2>/dev/null; true )',
+    // A brace group (NOT a subshell) so the function + trap persist into the
+    // current shell where the rest of the &&-chain runs.
+    `{ __cy_recover() { ${recover}; }; trap '__cy_recover; exit 1' EXIT; }`,
     `(${E} editor stop-server --hold-for-restart --force-in-container || true)`,
-    'rm -rf .codeyam',
-    `( git checkout HEAD -- .codeyam 2>/dev/null || ${E} init )`,
-    '( test -f /tmp/cy-elj.bak && mkdir -p .codeyam && cp /tmp/cy-elj.bak .codeyam/editor.local.json && rm -f /tmp/cy-elj.bak; true )',
-    '( test -f /tmp/cy-ss.bak && mkdir -p .codeyam && cp /tmp/cy-ss.bak .codeyam/server-state.json && rm -f /tmp/cy-ss.bak; true )',
+    `(${E} editor pty-broker stop || true)`,
+    '( for i in 1 2 3 4 5; do find .codeyam -mindepth 1 -delete 2>/dev/null; [ -z "$(ls -A .codeyam 2>/dev/null)" ] && break; sleep 0.2; done; true )',
+    `( ${restoreCodeyam} )`,
+    `( ${restoreElj} && rm -f /tmp/cy-elj.bak; true )`,
+    `( ${restoreSs} && rm -f /tmp/cy-ss.bak; true )`,
+    // Restore succeeded — disarm the failure-safe trap so normal completion
+    // (and the caller's trailing session-reset + restart) doesn't re-trigger it.
+    'trap - EXIT',
   ];
 }
 
+// Belt-and-suspenders broker-ensure, appended after the trailing
+// `restart-server` in every reset recipe. The PRIMARY fix lives in the
+// editor server's `ensure_broker_running`: it now `rm -f`s the stale
+// socket and retries the spawn, so the reexec'd `start` (which
+// restart-server triggers) reliably respawns the broker with no
+// down-window. This step is the safety net for an OLDER in-container
+// binary whose `restart-server` predates that fix — it mirrors the
+// vm-watchdog's recovery so a reset still ends broker-up regardless of
+// which binary is installed.
+//
+// Shape: status-gated and idempotent. `pty-broker status` exits non-zero
+// only when no broker is reachable; ONLY then does the `||` branch fire
+// (`rm -f` the stale socket — mirroring the watchdog — then `nohup` a
+// detached daemon). When a broker is already alive the status succeeds
+// and the respawn branch never runs, so a healthy broker is NEVER killed.
+// Wrapped in `( …; true )` so it can never break the reset's &&-chain
+// (a down broker that fails to respawn must not abort the rest of the
+// reset). The socket glob + `pty-broker daemon` invocation match the
+// watchdog (`scripts/operator/vm-watchdog.sh`) and the per-project
+// `$TMPDIR`/`/tmp` socket layout (`socket_path_for`).
+function codeyamBrokerEnsureStep(E) {
+  return (
+    `( ${E} editor pty-broker status >/dev/null 2>&1 || ` +
+    `( rm -f /tmp/codeyam-pty-broker-*.sock; ` +
+    `nohup ${E} editor pty-broker daemon </dev/null >/tmp/broker-spawn.log 2>&1 & disown ); ` +
+    'true )'
+  );
+}
+
 // Build the in-container bash for "Reset client" — hard-clean the CLIENT
 // project (/workspace) on ANY VM shape. The decisions encoded here:
 //   - Reset to HEAD, NOT origin: `git reset --hard` (bare) discards uncommitted
@@ -85,6 +152,9 @@ function resetClientScript({ E, gitReseedBody }) {
     `${E} editor session-reset`,
     'echo ">> [4/5] restarting server to respawn the broker (no rebuild)"',
     `(${E} editor restart-server --force-in-container || true)`,
+    // Belt-and-suspenders: ensure a broker is live even on an older binary
+    // whose restart-server doesn't yet respawn it. Idempotent / status-gated.
+    codeyamBrokerEnsureStep(E),
     'echo ">> [5/5] re-seeding git credential cache"',
     `( ( ${gitReseedBody} ) || echo "WARN git cache re-seed failed" )`,
   ].join(' && ');
@@ -138,7 +208,15 @@ function resetEditorStateScript({ E }) {
     // docker-exec returns cleanly, so `|| true` keeps a broker-down VM green.
     'echo ">> [4/4] restarting server to respawn the broker (no rebuild)"',
     `(${E} editor restart-server --force-in-container || true)`,
+    // Belt-and-suspenders: ensure a broker is live even on an older binary
+    // whose restart-server doesn't yet respawn it. Idempotent / status-gated.
+    codeyamBrokerEnsureStep(E),
   ].join(' && ');
 }
 
-module.exports = { codeyamDeepCleanSteps, resetClientScript, resetEditorStateScript };
+module.exports = {
+  codeyamDeepCleanSteps,
+  codeyamBrokerEnsureStep,
+  resetClientScript,
+  resetEditorStateScript,
+};

package/npm/launch-config.js

@@ -58,10 +58,54 @@ 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
@@ -258,6 +302,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 +391,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 +416,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" } = {}) {
@@ -522,6 +596,9 @@ module.exports = {
   normalizeLaunchConfig,
   validateLaunchConfig,
   isVariantProvisionable,
+  isVariantRebuildable,
+  variantNpmDistTag,
+  variantImageTag,
   cloudUpArgs,
   classifyContainerWait,
   decideAddSlot,
@@ -532,6 +609,7 @@ module.exports = {
   defaultConfig,
   configForVm,
   resolveCardIdentity,
+  stickyClientProject,
   classifyProjectKind,
   resolveCredsSource,
   buildCredsSteps,

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 {
@@ -303,6 +306,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 +369,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,6 +445,16 @@ 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 });

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);
 }

package/npm/scenario-playwright.js

@@ -219,6 +219,73 @@ async function waitForAnimationsSettled(
   return { settled: false, elapsedMs: Date.now() - started };
 }
 
+// Track in-flight network requests on a Playwright page so a capture can wait
+// for client-side data fetches to settle before screenshotting. The
+// resource-timing API (`performance.getEntriesByType("resource")`) only records
+// COMPLETED requests, so it cannot see a fetch that is still in flight — the
+// exact window where a client-fetch page shows a loading skeleton. We count
+// request starts against finishes/failures instead. Returns a live view:
+// `inFlight()` is the current outstanding count and `lastActivityMs()` is the
+// timestamp of the most recent request start OR completion (0 when the page has
+// made no requests since the tracker attached). Attach BEFORE navigation so
+// every request is counted. Stack-agnostic — it observes raw HTTP activity, not
+// any framework's fetch wrapper.
+function createNetworkTracker(page) {
+  let inFlight = 0;
+  let lastActivityMs = 0;
+  const bump = () => {
+    lastActivityMs = Date.now();
+  };
+  if (page && typeof page.on === "function") {
+    page.on("request", () => {
+      inFlight += 1;
+      bump();
+    });
+    const settle = () => {
+      inFlight = Math.max(0, inFlight - 1);
+      bump();
+    };
+    page.on("requestfinished", settle);
+    page.on("requestfailed", settle);
+  }
+  return {
+    inFlight: () => inFlight,
+    lastActivityMs: () => lastActivityMs,
+  };
+}
+
+// Bounded network-quiet wait: after the DOM is stable a client-side data fetch
+// can still be in flight — the loading skeleton is gone but the fetched rows
+// haven't replaced it yet, so a screenshot here catches the in-between frame.
+// Wait until no request has been outstanding for `quietWindowMs`, hard-capped at
+// `overallTimeoutMs`. Two properties matter:
+//   - A page that made NO requests (lastActivityMs stays 0) is already quiet and
+//     returns on the first poll, so server-rendered captures incur no extra wait.
+//   - A streaming / long-poll endpoint that never goes idle hits the cap and the
+//     caller captures anyway — the wait can never hang the capture.
+async function waitForNetworkQuiet(
+  tracker,
+  { quietWindowMs = 500, overallTimeoutMs = 5000, pollIntervalMs = 100 } = {},
+) {
+  const started = Date.now();
+  while (Date.now() - started < overallTimeoutMs) {
+    const idleForMs = Date.now() - tracker.lastActivityMs();
+    if (tracker.inFlight() === 0 && idleForMs >= quietWindowMs) {
+      const elapsedMs = Date.now() - started;
+      logCaptureTiming("network-quiet", { outcome: "quiet", elapsedMs });
+      return { quiet: true, elapsedMs };
+    }
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  const elapsedMs = Date.now() - started;
+  logCaptureTiming("network-quiet", {
+    outcome: "capped",
+    elapsedMs,
+    inFlight: tracker.inFlight(),
+  });
+  return { quiet: false, elapsedMs };
+}
+
 // `loadingMarkers` are the project's app-specific loading strings (from
 // stack.json `capture.loadingMarkers`); they extend the codeyam-harness
 // defaults so a stable-but-still-loading app screen counts as "not ready"
@@ -233,15 +300,41 @@ async function waitForStablePage(page, target, timeoutMs = 10000, loadingMarkers
   while (Date.now() - started < timeoutMs) {
     await page.waitForTimeout(500);
 
-    const pageState = await target.evaluate(() => ({
-      bodyText: document.body?.innerText ?? "",
-      html: document.body?.innerHTML ?? "",
-    }));
+    const pageState = await target.evaluate(() => {
+      const getById = document.getElementById;
+      const root =
+        typeof getById === "function" ? document.getElementById("root") : null;
+      return {
+        bodyText: document.body?.innerText ?? "",
+        html: document.body?.innerHTML ?? "",
+        // Whether the SPA mount point exists AND has painted anything. An
+        // existing-but-empty `<div id="root">` is the pre-paint window of a
+        // slow-first-paint scenario (e.g. a live-session app that spends a few
+        // seconds connecting before the gate UI mounts). `rootExists` lets us
+        // distinguish that from a mid-redirect/teardown `null` body, where
+        // there is no root to wait on and a stable-empty page is legitimately
+        // settled.
+        rootExists: !!root,
+        rootChildCount: root ? root.childElementCount : 0,
+      };
+    });
 
     lastHadLoadingMarkers = hasLoadingMarkers(pageState.bodyText, loadingMarkers);
     lastHtmlChanged = pageState.html !== lastHtml;
 
-    if (!lastHadLoadingMarkers && !lastHtmlChanged) {
+    // A mounted-but-unpainted root is "still loading", not "settled": the HTML
+    // can sit byte-stable for a second or two while the SPA boots, which would
+    // otherwise satisfy the stability check and capture a blank frame before
+    // first paint. Treat an existing root with zero children AND no body text
+    // as not-ready so the loop keeps polling until the app actually paints (or
+    // the overall timeout fires, by which point real content is present). A
+    // `null` body (rootExists=false) is unaffected — it stays trivially stable.
+    const rootUnpainted =
+      pageState.rootExists &&
+      pageState.rootChildCount === 0 &&
+      (pageState.bodyText ?? "").trim().length === 0;
+
+    if (!lastHadLoadingMarkers && !lastHtmlChanged && !rootUnpainted) {
       stableCount += 1;
       if (stableCount >= 2) {
         const remaining = () => Math.max(0, timeoutMs - (Date.now() - started));
@@ -339,6 +432,88 @@ async function loadScenarioTopLevel(
   return { frame: page.mainFrame(), response };
 }
 
+// Collect up to 20 distinct visible labels of interactive elements on the
+// page — buttons, links, role=button, form controls, <summary>, and anything
+// with an onclick. Used to build an ACTIONABLE error when an interaction's
+// target matches nothing: the agent reliably knows a label it rendered, so
+// listing the real candidates turns a silent blank capture into a "did you
+// mean one of these?" hint. Pure read (no clicks); falls back to value /
+// aria-label / placeholder when an element has no text.
+async function collectInteractiveLabels(frame) {
+  return frame.evaluate(() => {
+    const selector =
+      "button, a[href], [role=button], input, select, textarea, summary, [onclick]";
+    const nodes = Array.from(document.querySelectorAll(selector));
+    const labels = nodes
+      .map((node) => {
+        const text =
+          (node.innerText || node.textContent || "").trim() ||
+          (typeof node.value === "string" ? node.value.trim() : "") ||
+          (node.getAttribute && node.getAttribute("aria-label")) ||
+          (node.getAttribute && node.getAttribute("placeholder")) ||
+          "";
+        return String(text).trim();
+      })
+      .filter((label) => label.length > 0);
+    return Array.from(new Set(labels)).slice(0, 20);
+  });
+}
+
+// Drive a single user-style interaction against the settled frame before the
+// screenshot, so an interactive state (expanded accordion, open modal, filled
+// field) can be captured without editing app source.
+//
+// The target is matched by visible `text` (preferred — the agent reliably
+// knows the label it rendered) or a CSS `selector`. `action` is click / fill /
+// press; `value` carries the text for `fill` or the key for `press` (e.g.
+// `Enter`). On a no-match target this THROWS with the list of candidate
+// interactive labels — the capture script's outer catch turns that into a
+// failed capture with an actionable message, never a silent blank screenshot.
+async function performInteraction(frame, interaction, { timeoutMs = 5000 } = {}) {
+  const { action, selector, text, value } = interaction || {};
+
+  let locator;
+  let targetDesc;
+  if (typeof text === "string" && text.length > 0) {
+    locator = frame.getByText(text, { exact: false }).first();
+    targetDesc = `text "${text}"`;
+  } else if (typeof selector === "string" && selector.length > 0) {
+    locator = frame.locator(selector).first();
+    targetDesc = `selector "${selector}"`;
+  } else {
+    throw new Error(
+      "preview-interact: interaction requires a `text` or `selector` target",
+    );
+  }
+
+  const matchCount = await locator.count();
+  if (matchCount === 0) {
+    const candidates = await collectInteractiveLabels(frame);
+    const candidateList =
+      candidates.length > 0 ? candidates.join(", ") : "(none found on page)";
+    throw new Error(
+      `preview-interact: no element matched ${targetDesc}. ` +
+        `Candidate interactive labels: ${candidateList}`,
+    );
+  }
+
+  switch (action) {
+    case "click":
+      await locator.click({ timeout: timeoutMs });
+      break;
+    case "fill":
+      await locator.fill(value ?? "", { timeout: timeoutMs });
+      break;
+    case "press":
+      await locator.press(value || "Enter", { timeout: timeoutMs });
+      break;
+    default:
+      throw new Error(
+        `preview-interact: unknown action "${action}" (expected click | fill | press)`,
+      );
+  }
+}
+
 module.exports = {
   logCaptureTiming,
   resolveTcpTarget,
@@ -349,7 +524,11 @@ module.exports = {
   collectImageStates,
   waitForImagesSettled,
   waitForAnimationsSettled,
+  createNetworkTracker,
+  waitForNetworkQuiet,
   waitForStablePage,
   loadScenarioInIframe,
   loadScenarioTopLevel,
+  collectInteractiveLabels,
+  performInteraction,
 };