@stage5/lumine 0.3.46 → 0.3.48

package/lib/admin-owner-trace.js

@@ -13,6 +13,8 @@ export const OWNER_TRACE_PERF_TYPES = [
   "slow-request",
   "stall",
   "page-load",
+  "scroll-perf",
+  "scroll-frame",
 ];
 
 const MAX_LIMIT = 2000;
@@ -134,6 +136,10 @@ export function describeOwnerTraceEvent(event) {
       ].filter(Boolean);
       return `${data.m || "?"} ${data.api || "?"} → ${data.status ?? "?"} in ${data.ms}ms${extra.length ? ` (${extra.join(", ")})` : ""}`;
     }
+    case "scroll-perf":
+      return describeScrollPerf(data);
+    case "scroll-frame":
+      return describeScrollFrame(data);
     case "stall":
       return `main thread blocked ${data.ms}ms${data.n > 1 ? ` (${data.n} stalls, ${data.total}ms blocked over ${data.span}ms)` : ""}`;
     case "page-load": {
@@ -154,6 +160,55 @@ export function describeOwnerTraceEvent(event) {
   }
 }
 
+// One Home/page scroll burst: frame pacing plus what was on screen.
+function describeScrollPerf(data) {
+  const cards = (data.context?.cards || [])
+    .map((card) => card.key)
+    .filter(Boolean);
+  const source = data.frameSource
+    ? `${data.frameSource.source === "loaf" ? `LoAF ${data.frameSource.loafFrames ?? 0} long frame(s)` : "no LoAF"} · card renders ${data.frameSource.cardRenders} mounts ${data.frameSource.cardMounts} · img loads ${data.frameSource.imgLoads}`
+    : "";
+  return [
+    `${data.frames ?? 0} frames over ${data.spanMs ?? 0}ms`,
+    `mean ${data.meanFrameMs ?? "?"}ms max ${data.maxFrameMs ?? "?"}ms`,
+    `>50ms ${data.over50 ?? 0} >100ms ${data.over100 ?? 0}`,
+    cards.length ? `cards ${cards.join(",")}` : "",
+    source,
+    data.reason ? `(${data.reason})` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+// One slow frame of a scroll burst: Long Animation Frame scripts (Chrome) or
+// the feed card types that rendered in it (every browser).
+function describeScrollFrame(data) {
+  const counts = (label, map) => {
+    const entries = Object.entries(map || {});
+    return entries.length
+      ? `${label} ${entries.map(([type, n]) => `${type}×${n}`).join(",")}`
+      : "";
+  };
+  const loaf = data.loaf;
+  const head = loaf
+    ? `slow frame ${loaf.ms}ms (LoAF, blocking ${loaf.blockingMs ?? "?"}ms${loaf.styleLayoutShare != null ? `, style/layout ${Math.round(loaf.styleLayoutShare * 100)}%` : ""}${data.gapMs != null ? `, rAF gap ${data.gapMs}ms` : ""})`
+    : `slow frame ${data.gapMs}ms (rAF gap, no LoAF)`;
+  const scripts = (loaf?.scripts || []).map(
+    (script) =>
+      `${script.ms}ms ${script.src || "?"}${script.fn ? ` ${script.fn}` : ""} [${script.type || "?"}${script.invoker ? ` ${script.invoker}` : ""}]${script.forcedLayoutMs ? ` forced layout ${script.forcedLayoutMs}ms` : ""}`,
+  );
+  return [
+    head,
+    data.offsetMs != null ? `+${data.offsetMs}ms` : "",
+    scripts.length ? `scripts: ${scripts.join("; ")}` : "",
+    counts("rendered", data.renders),
+    counts("mounted", data.mounts),
+    data.imgLoads ? `${data.imgLoads} img load(s)` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
 // "tap→page 4210ms · PUSH via nav · url +90 · gate +4180 (probe timeout,
 // waited 4100ms) · commit +4210 · ready +4600": offsets are ms from the tap.
 function describeNavTiming(data) {

package/lib/admin.js

@@ -7622,6 +7622,12 @@ function printAdminResult({ operation, result }) {
       `Confirmed Build #${data.review.buildId} runtime at published artifact #${data.review.publishedArtifactVersionId}.`,
     );
     console.log(`Screenshot: ${data.screenshotPath}`);
+    const teardown = data.review.browser?.teardownWarning;
+    if (teardown) {
+      console.log(
+        `Teardown warning: Chrome ended with ${teardown.signal ? `signal ${teardown.signal}` : `code ${teardown.exitCode}`} (${teardown.signature}) after the evidence was captured and Browser.close was sent; the review is still confirmed.`,
+      );
+    }
     if (data.review.interaction) {
       console.log(
         `Interaction script: ${data.review.interaction.stepsCompleted}/${data.review.interaction.stepsPlanned} step(s) ${data.review.interaction.status}.`,

package/lib/build-review.js

@@ -745,6 +745,9 @@ async function runChromeReview({
   });
   let stdout = "";
   let stderr = "";
+  // Only what Chrome printed after our own Browser.close, so a teardown
+  // signature is never matched against a message from before the close.
+  let stderrAfterClose = null;
   const consoleLines = [];
   const append = (current, chunk) => `${current}${chunk}`.slice(-2_000_000);
   child.stdout.on("data", (chunk) => {
@@ -752,6 +755,9 @@ async function runChromeReview({
   });
   child.stderr.on("data", (chunk) => {
     stderr = append(stderr, chunk);
+    if (stderrAfterClose !== null) {
+      stderrAfterClose = `${stderrAfterClose}${chunk}`.slice(-200_000);
+    }
   });
   const closed = new Promise((resolve, reject) => {
     child.once("error", reject);
@@ -908,22 +914,36 @@ async function runChromeReview({
         }
       }
     }
+    // Everything the receipt relies on is in hand before the close; a
+    // nonzero exit can only be read as teardown when that is true and Chrome
+    // was still running when we asked it to close.
+    const evidenceCompleteBeforeClose =
+      Boolean(screenshot.data) &&
+      isRuntimeReady(readiness) &&
+      (!interaction || interactionResult?.status === "completed");
+    const exitedBeforeClose =
+      child.exitCode !== null || child.signalCode !== null;
+    const closeRequestedAt = Date.now();
+    stderrAfterClose = "";
     await cdp.send("Browser.close").catch(() => {});
     let forcedTermination = false;
     const closeResult = await Promise.race([
       closed,
       delay(5_000).then(() => {
         forcedTermination = true;
-        child.kill("SIGTERM");
-        return closed;
+        return stopChrome(child, closed);
       }),
     ]);
     return {
       ...closeResult,
       closeRequested: true,
       forcedTermination,
+      evidenceCompleteBeforeClose,
+      exitedBeforeClose,
+      closeDurationMs: Date.now() - closeRequestedAt,
       stdout,
       stderr,
+      stderrAfterClose,
       consoleLines: consoleLines.slice(-MAX_CAPTURED_LOG_LINES),
       runtimeReadiness: {
         ...(readiness || {}),
@@ -934,24 +954,85 @@ async function runChromeReview({
     };
   } finally {
     clearTimeout(timer);
-    if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+    if (child.exitCode === null && child.signalCode === null)
+      await stopChrome(child, closed).catch(() => {});
   }
 }
 
+// SIGTERM, then SIGKILL if Chrome is still there after 3 s: a browser wedged
+// in teardown (the case this review must tolerate) can ignore SIGTERM, and
+// the review must never hang or leave Chrome running.
+async function stopChrome(child, closed) {
+  child.kill("SIGTERM");
+  const ended = await Promise.race([closed, delay(3_000).then(() => null)]);
+  if (ended) return ended;
+  child.kill("SIGKILL");
+  return closed;
+}
+
 const CHROME_KILLED_AFTER_CLOSE_CODE = 2;
 
-// Chrome sometimes exits 2 (RESULT_CODE_KILLED) while tearing down a
-// GPU-heavy page after our own Browser.close. Every piece of evidence was
-// captured before that close, so that one shutdown result is cleanup, not a
-// failed review. Any other code, a signal, or our forced kill still fails.
-export function reviewBrowserExitedCleanly(browser) {
-  return (
-    browser?.code === 0 ||
-    (browser?.code === CHROME_KILLED_AFTER_CLOSE_CODE &&
-      !browser.signal &&
-      browser.closeRequested === true &&
-      browser.forcedTermination === false)
-  );
+// Lines Chrome prints when its own shutdown, not the page, went wrong.
+// "Teardown watchdog expired" is the network-service watchdog that kills a
+// browser whose services do not stop in time after Browser.close.
+// Anchored to the start of the line: Chrome prints the bare message (seen
+// 10-19) or behind its own ERROR/FATAL prefix. A page console line is
+// "[pid:tid:...:INFO:CONSOLE:n] \"...\"", so page text cannot match.
+const CHROME_TEARDOWN_SIGNATURES = [
+  {
+    id: "teardown_watchdog_expired",
+    pattern:
+      /^(?:\[[^\]]*:(?:ERROR|FATAL):[^\]]*\]\s*)?teardown watchdog expired/i,
+  },
+];
+
+function chromeTeardownSignature(stderrAfterClose) {
+  for (const line of String(stderrAfterClose || "").split(/\r?\n/)) {
+    const match = CHROME_TEARDOWN_SIGNATURES.find(({ pattern }) =>
+      pattern.test(line),
+    );
+    if (match) return { id: match.id, line: line.trim().slice(0, 400) };
+  }
+  return null;
+}
+
+// Capture validity and process cleanup are separate questions. Exit 0 is
+// clean. A nonzero exit (or our forced stop) is accepted as a teardown
+// warning only when all page evidence was complete before our own
+// Browser.close, Chrome was still running when we sent it, and the exit is
+// a known shutdown outcome: exit 2 (RESULT_CODE_KILLED) on its own, or any
+// exit with a teardown signature printed after the close. Anything else,
+// including every exit before the evidence was complete, fails the review.
+export function classifyReviewBrowserExit(browser) {
+  if (browser?.code === 0 && !browser?.signal) {
+    return { accepted: true, teardownWarning: null };
+  }
+  const afterOwnClose =
+    browser?.closeRequested === true &&
+    browser?.exitedBeforeClose === false &&
+    browser?.evidenceCompleteBeforeClose === true;
+  if (!afterOwnClose) return { accepted: false, teardownWarning: null };
+  const signature = chromeTeardownSignature(browser.stderrAfterClose);
+  const killedAfterClose =
+    browser.code === CHROME_KILLED_AFTER_CLOSE_CODE &&
+    !browser.signal &&
+    browser.forcedTermination === false;
+  if (!signature && !killedAfterClose) {
+    return { accepted: false, teardownWarning: null };
+  }
+  return {
+    accepted: true,
+    teardownWarning: {
+      exitCode: browser.code,
+      signal: browser.signal || null,
+      forcedTermination: browser.forcedTermination === true,
+      closeDurationMs: Number.isFinite(browser.closeDurationMs)
+        ? browser.closeDurationMs
+        : null,
+      signature: signature?.id || "exit_2_after_close",
+      stderrLine: signature?.line || null,
+    },
+  };
 }
 
 // The last few Chrome stderr lines, for diagnosing a nonzero exit.
@@ -1032,7 +1113,8 @@ export async function runManagedBuildReview({ options, authToken, buildId }) {
   const interactionOutcome = browser.interaction || null;
   const interactionCompleted =
     !interaction || interactionOutcome?.status === "completed";
-  const browserExitedCleanly = reviewBrowserExitedCleanly(browser);
+  const browserExit = classifyReviewBrowserExit(browser);
+  const browserExitedCleanly = browserExit.accepted;
   const confirmed =
     browserExitedCleanly &&
     screenshotBytes > 0 &&
@@ -1057,7 +1139,15 @@ export async function runManagedBuildReview({ options, authToken, buildId }) {
       signal: browser.signal,
       closeRequested: browser.closeRequested === true,
       forcedTermination: browser.forcedTermination === true,
-      exitedCleanly: browserExitedCleanly,
+      exitedCleanly: browser.code === 0 && !browser.signal,
+      evidenceCompleteBeforeClose: browser.evidenceCompleteBeforeClose === true,
+      exitedBeforeClose: browser.exitedBeforeClose === true,
+      closeDurationMs: Number.isFinite(browser.closeDurationMs)
+        ? browser.closeDurationMs
+        : null,
+      // Set when the page evidence is valid but Chrome's own shutdown ended
+      // nonzero; the review stays confirmed and this says what happened.
+      teardownWarning: browserExit.teardownWarning,
       stderrTail: browser.code === 0 ? null : chromeStderrTail(browser.stderr),
       runtimeReadiness: browser.runtimeReadiness,
     },
@@ -1097,7 +1187,9 @@ export async function runManagedBuildReview({ options, authToken, buildId }) {
               screenshotBytes > 0 &&
               browser.runtimeReadiness?.ready === true &&
               interactionCompleted
-            ? `Chrome exited with ${browser.signal ? `signal ${browser.signal}` : `code ${browser.code}`}${browser.forcedTermination ? " after the CLI had to stop it" : ""} once the review evidence was captured. The app loaded and the screenshots are in the receipt, but the receipt is not confirmed; see browser.stderrTail and review again.`
+            ? browser.exitedBeforeClose === true
+              ? `Chrome exited with ${browser.signal ? `signal ${browser.signal}` : `code ${browser.code}`} before the CLI asked it to close, so the run is not trusted. The screenshots are in the receipt; see browser.stderrTail and review again.`
+              : `Chrome exited with ${browser.signal ? `signal ${browser.signal}` : `code ${browser.code}`}${browser.forcedTermination ? " after the CLI had to stop it" : ""} while closing, with no known teardown signature. The app loaded and the screenshots are in the receipt, but the receipt is not confirmed; see browser.stderrTail and review again.`
             : interactionFailure
             ? `Interaction step ${interactionOutcome?.failedStep?.index ?? "?"} (${interactionOutcome?.failedStep?.kind ?? "?"}) failed: ${interactionOutcome?.failedStep?.error ?? "unknown"} The receipt lists the ${interactionOutcome?.stepsCompleted ?? 0} completed step(s) and their screenshots; fix the script and review again.`
             : "The isolated Build runtime did not become visibly reviewable before the observation window ended.",

package/lib/commands.js

@@ -3311,7 +3311,7 @@ export function printHelp() {
   lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]
   lumine admin reward-bank seed <buildId> [--max-step 3] [--identity zero|ciel|auto] [--json]   (writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy; inside a daily run or on its own, owner only)
   lumine admin reward-bank report <buildId> [--days 1] [--json]   (question-bank telemetry: generation outcomes, learners, payouts, ladder, questions to review)
-  lumine admin owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load] [--perf] [--path <substring>] [--limit 300] [--json]   (what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load; --perf shows only those; kept 30 days)
+  lumine admin owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load,scroll-perf,scroll-frame] [--perf] [--path <substring>] [--limit 300] [--json]   (what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load, scroll frame pacing and slow-frame attribution (Long Animation Frame scripts on Chrome, feed card renders on Safari); --perf shows only those; kept 30 days)
   lumine admin roles [--min-level 1] [--limit 50] [--json]   (every user type with its management level and who holds it; admin pages need level 3, achievement points never pass level 2)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]

package/lib/constants.js

@@ -350,7 +350,7 @@ lumine save --summary "Describe the change"
 - Use local project files with relative or root-local imports only. Do not add package imports, CDN scripts, external network calls, or app-local /api/* routes.
 - Build apps run in sandboxed iframes without allow-forms. Do not use <form> elements, native form submission, requestSubmit(), or browser form navigation. Build input flows with JavaScript-handled inputs and buttons instead.
 ${LUMINE_MOBILE_SELECTION_GUIDANCE}
-- CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) switches the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
+- CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body except a small one on screen (both sides at most 160 CSS px: a visualizer, a sparkle, an icon) switches the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. A hidden or not-yet-sized canvas counts too, and a page that sets data-twinkle-game keeps this layout with any canvas. Document-style apps with a larger canvas (a chart, a drawing pad, a background effect) set data-twinkle-document on <html> or <body>, or call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot and then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 ${LUMINE_THREE_VENDOR_GUIDANCE}
 ${LUMINE_MATH_VENDOR_GUIDANCE}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.68.0
 Updated: 2026-10-16
-Generated: 2026-10-18T22:57:11.632Z
+Generated: 2026-10-19T05:26:13.264Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -25,7 +25,7 @@ Generated: 2026-10-18T22:57:11.632Z
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
 - Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
 - Mobile long-press must not select game UI or open browser Copy/Look Up/image menus. The SDK provides no-selection/callout defaults for standard buttons, button-like ARIA controls, and canvases. Mark the entire custom gameplay wrapper data-twinkle-no-select, including HUD, labels, scores, menus, controls, and empty play space; also style it with user-select: none, -webkit-user-select: none, and -webkit-touch-callout: none for local previews. Protecting only one button or the canvas is insufficient. This behavior is independent of Twinkle.preview layout mode.
-- Played game pages block text selection, the long-press menu and page pinch-zoom everywhere except inputs, textareas, contenteditable and data-twinkle-selectable text, so text a game shows for copying (a chat log, a word to copy) needs data-twinkle-selectable. A page is a played game when the app sets data-twinkle-game on <html> or <body>, or, for apps that do not lay themselves out with Twinkle.preview, when a play-sized canvas is on screen: rendered, not pointer-events:none, and covering at least 30% of the viewport by its layout size; the page then stays a played game while that canvas is in the document, even hidden between screens. Set data-twinkle-game on a game that sizes itself with Twinkle.preview, a DOM-only game, or a small-canvas game; set data-twinkle-document to keep a canvas page (charts, drawing pad) an ordinary page; set data-twinkle-allow-zoom to keep page pinch-zoom on a game. Page layout is not affected by any of this.
+- Played game pages block text selection, the long-press menu and page pinch-zoom everywhere except inputs, textareas, contenteditable and data-twinkle-selectable text, so text a game shows for copying (a chat log, a word to copy) needs data-twinkle-selectable. A page is a played game when the app sets data-twinkle-game on <html> or <body>, or, for apps that do not lay themselves out with Twinkle.preview, when a play-sized canvas is on screen: rendered, not pointer-events:none, and covering at least 30% of the viewport by its layout size; the page then stays a played game while that canvas is in the document, even hidden between screens. Set data-twinkle-game on a game that sizes itself with Twinkle.preview, a DOM-only game, or a small-canvas game; set data-twinkle-document to keep a canvas page (charts, drawing pad) an ordinary page, which also keeps it out of viewport-app layout so it scrolls; set data-twinkle-allow-zoom to keep page pinch-zoom on a game. Viewport-app layout (html/body pinned to the screen, no page scroll) turns on for any canvas except a small one on screen (both sides at most 160 CSS px); data-twinkle-game keeps it for any canvas, and data-twinkle-document or laying the page out with Twinkle.preview turns it off.
 - Keep inputs/contenteditable usable. Mark genuinely copyable story/chat/user-written text data-twinkle-selectable and style it with user-select: text, -webkit-user-select: text, and -webkit-touch-callout: default. SDK defaults have low specificity so existing explicit copyable-text styles remain effective. Preserve document/reader selection; do not block document-wide touch/pointer events or disable scrolling/zoom to prevent selection.
 - Verify mobile long presses on controls, HUD, and empty play space in Safari and Chromium; confirm held controls still work and release/cancel correctly, and scrolling, typing, and copying still work. lumine check only detects a missing no-selection rule, not selector coverage or mobile behavior.
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.