@stage5/lumine 0.3.14 → 0.3.17

package/lib/sponsor-preview.js

@@ -0,0 +1,271 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { createCdpPipe, findChromeExecutable } from "./build-review.js";
+
+// `lumine sponsor job preview` renders a Workshop job's saved draft from the
+// Twinkle preview origin: the same version URL (with SDK injection and asset
+// rewrites) that the requester's workspace "App preview" frame loads. It runs
+// top-level in headless Chrome, without the Twinkle host page around it, so
+// host-bridged SDK calls (sign-in identity, saves, rewards) are not exercised.
+
+export const DEFAULT_PREVIEW_RENDER_MS = 8_000;
+export const MAX_PREVIEW_RENDER_MS = 30_000;
+const MAX_PREVIEW_LOG_LINES = 200;
+
+export function normalizePreviewRenderMs(value) {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_PREVIEW_RENDER_MS;
+  }
+  const parsed = Number(value);
+  if (
+    !Number.isSafeInteger(parsed) ||
+    parsed < 1_000 ||
+    parsed > MAX_PREVIEW_RENDER_MS
+  ) {
+    throw new Error(
+      `--wait-ms for a job preview must be an integer between 1000 and ${MAX_PREVIEW_RENDER_MS}.`,
+    );
+  }
+  return parsed;
+}
+
+// The preview URL carries a short-lived preview credential for the
+// requester's workspace; nothing the CLI prints or stores keeps it.
+export function redactPreviewCredential(value) {
+  // Plain (?buildApiToken=…), percent-encoded (buildApiToken%3D…, as in a
+  // nested URL) and double-encoded (%253D) forms all lose their value.
+  return String(value ?? "").replace(
+    /(buildApiToken(?:=|%3D|%253D))(?:[A-Za-z0-9._~+\/-]|%(?!26|2526|23|2523)[0-9A-Fa-f]{2})+/gi,
+    "$1<redacted>",
+  );
+}
+
+const PAGE_STATE_EXPRESSION = `(() => {
+  const body = document.body;
+  const visible = (el) => {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    return rect.width > 1 && rect.height > 1 && style.display !== 'none' &&
+      style.visibility !== 'hidden' && Number(style.opacity || 1) > 0;
+  };
+  const media = body
+    ? [...body.querySelectorAll('canvas, img, svg, video')].filter(visible).length
+    : 0;
+  const text = body ? String(body.innerText || '').replace(/\\s+/g, ' ').trim() : '';
+  return {
+    readyState: document.readyState,
+    title: document.title || '',
+    textLength: text.length,
+    textSample: text.slice(0, 160),
+    visibleMediaCount: media,
+    elementCount: body ? body.querySelectorAll('*').length : 0
+  };
+})()`;
+
+function remoteArgumentText(argument) {
+  if (Object.hasOwn(argument || {}, "value")) {
+    const value = argument.value;
+    return typeof value === "string" ? value : JSON.stringify(value);
+  }
+  return String(argument?.description || argument?.type || "");
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function waitForPageTarget(cdp) {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const result = await cdp.send("Target.getTargets");
+    const page = (result.targetInfos || []).find(
+      (target) => target.type === "page",
+    );
+    if (page) return page;
+    await delay(100);
+  }
+  throw new Error("Chrome did not open a page for the job preview.");
+}
+
+export async function renderDraftPreview({
+  url,
+  outputDir,
+  waitMs = DEFAULT_PREVIEW_RENDER_MS,
+  browserPath = "",
+}) {
+  let executable;
+  try {
+    executable = findChromeExecutable(browserPath);
+  } catch (error) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: "browser_not_found",
+      message: String(error?.message || error),
+    };
+  }
+  const profileDir = mkdtempSync(path.join(outputDir, "browser-profile-"));
+  const screenshotPath = path.join(outputDir, "preview.png");
+  const child = spawn(
+    executable,
+    [
+      "--headless=new",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-background-networking",
+      "--disable-component-update",
+      "--disable-sync",
+      "--hide-scrollbars",
+      "--mute-audio",
+      "--remote-debugging-pipe",
+      `--user-data-dir=${profileDir}`,
+      "--window-size=1280,900",
+      "about:blank",
+    ],
+    { stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"] },
+  );
+  const closed = new Promise((resolve) => {
+    child.once("error", () => resolve({ code: -1 }));
+    child.once("close", (code) => resolve({ code: Number(code ?? -1) }));
+  });
+  const hardKill = setTimeout(() => child.kill("SIGTERM"), waitMs + 30_000);
+  const consoleLines = [];
+  const exceptions = [];
+  const failedRequests = [];
+  let documentStatus = null;
+  const requestUrls = new Map();
+  const push = (list, line) => {
+    if (list.length < MAX_PREVIEW_LOG_LINES) {
+      list.push(redactPreviewCredential(line).slice(0, 500));
+    }
+  };
+  try {
+    const cdp = createCdpPipe(child);
+    const enableDomains = (sessionId) =>
+      Promise.all([
+        cdp.send("Runtime.enable", {}, sessionId),
+        cdp.send("Log.enable", {}, sessionId),
+        cdp.send("Network.enable", {}, sessionId),
+      ]).catch(() => undefined);
+    cdp.onEvent((message) => {
+      const params = message.params || {};
+      if (message.method === "Runtime.consoleAPICalled") {
+        const values = (params.args || []).map(remoteArgumentText);
+        push(consoleLines, `[console.${params.type || "log"}] ${values.join(" ")}`);
+      } else if (message.method === "Runtime.exceptionThrown") {
+        const details = params.exceptionDetails || {};
+        push(
+          exceptions,
+          details.exception?.description || details.text || "Uncaught exception",
+        );
+      } else if (message.method === "Log.entryAdded") {
+        const entry = params.entry || {};
+        if (entry.level === "error" || entry.level === "warning") {
+          push(
+            consoleLines,
+            `[${entry.level}] ${entry.text || ""}${entry.url ? ` (${entry.url})` : ""}`,
+          );
+        }
+      } else if (message.method === "Network.requestWillBeSent") {
+        if (params.requestId && requestUrls.size < 2_000) {
+          requestUrls.set(params.requestId, String(params.request?.url || ""));
+        }
+      } else if (message.method === "Network.responseReceived") {
+        const response = params.response || {};
+        const status = Number(response.status || 0);
+        if (params.type === "Document" && documentStatus === null) {
+          documentStatus = status;
+        }
+        if (status >= 400) push(failedRequests, `${status} ${response.url || ""}`);
+      } else if (message.method === "Network.loadingFailed") {
+        if (!params.canceled) {
+          push(
+            failedRequests,
+            `${params.errorText || "failed"} (${params.type || "request"}) ${requestUrls.get(params.requestId) || ""}`.trim(),
+          );
+        }
+      } else if (message.method === "Target.attachedToTarget") {
+        const sessionId = String(params.sessionId || "");
+        if (sessionId) void enableDomains(sessionId);
+      }
+    });
+    const target = await waitForPageTarget(cdp);
+    const attached = await cdp.send("Target.attachToTarget", {
+      targetId: target.targetId,
+      flatten: true,
+    });
+    const sessionId = String(attached.sessionId || "");
+    if (!sessionId) throw new Error("Chrome did not attach to the preview page.");
+    await cdp.send("Page.enable", {}, sessionId);
+    await enableDomains(sessionId);
+    await cdp.send(
+      "Target.setAutoAttach",
+      { autoAttach: true, waitForDebuggerOnStart: false, flatten: true },
+      sessionId,
+    );
+    await cdp.send("Page.navigate", { url }, sessionId);
+    await delay(waitMs);
+    const evaluated = await cdp.send(
+      "Runtime.evaluate",
+      { expression: PAGE_STATE_EXPRESSION, returnByValue: true },
+      sessionId,
+    );
+    const page = evaluated.result?.value || null;
+    const screenshot = await cdp.send(
+      "Page.captureScreenshot",
+      { format: "png", fromSurface: true, captureBeyondViewport: false },
+      sessionId,
+    );
+    let screenshotBytes = 0;
+    if (screenshot.data) {
+      const buffer = Buffer.from(screenshot.data, "base64");
+      writeFileSync(screenshotPath, buffer);
+      screenshotBytes = buffer.length;
+    }
+    await cdp.send("Browser.close").catch(() => undefined);
+    await Promise.race([closed, delay(5_000)]);
+    const blank =
+      !page || (Number(page.textLength || 0) === 0 &&
+        Number(page.visibleMediaCount || 0) === 0);
+    const problems = [
+      ...(documentStatus !== null && documentStatus >= 400
+        ? [`The preview document answered HTTP ${documentStatus}.`]
+        : []),
+      ...(exceptions.length > 0
+        ? [`${exceptions.length} uncaught exception(s) while the draft started.`]
+        : []),
+      ...(blank ? ["The page shows no text, canvas, image, svg or video after the wait."] : []),
+    ];
+    return {
+      ok: problems.length === 0,
+      skipped: false,
+      waitMs,
+      documentStatus,
+      page,
+      problems,
+      exceptions,
+      console: consoleLines,
+      failedRequests,
+      screenshot: screenshotBytes > 0
+        ? { path: screenshotPath, bytes: screenshotBytes }
+        : null,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      skipped: false,
+      error: redactPreviewCredential(String(error?.message || error)),
+      exceptions,
+      console: consoleLines,
+      failedRequests,
+      screenshot: null,
+    };
+  } finally {
+    clearTimeout(hardKill);
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+    await Promise.race([closed, delay(5_000)]);
+    rmSync(profileDir, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.14",
+  "version": "0.3.17",
   "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.63.0
 Updated: 2026-09-28
-Generated: 2026-10-05T14:12:15.800Z
+Generated: 2026-10-06T10:12:09.371Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -1527,19 +1527,19 @@ world.updatePresence({ x, y, z, facing });
   - Requires an open challenge of the learner's own (build_reward_challenge_not_open, HTTP 409 otherwise). Limit: 120 characters (build_reward_answer_text_invalid, 400), rate limited to a burst of 4 then one read every 5 seconds (build_reward_throttled, 429). build_reward_answer_reader_unavailable (503) means the reader is down: ask the learner to type just the number.
   - Drafts and owner previews return mode 'preview' and need no open challenge.
 - await Twinkle.rewards.getChallengeBoard() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, puzzles: [{ ruleId, title, setKey, rating, solvers, failers, failures, daysStanding, status: "untouched" | "undefeated" | "defeated" }], topSolvers: [{ rank, userId, username, profilePicUrl, rating, solves, hardestSolve: { ruleId, setKey, rating } | null }], recentSolves: [{ id, userId, username, ruleId, setKey, tier: "solved" | "first-solve" | "hard-won" | "legendary", attempt, firstSolve, failersBefore, failuresBefore, daysStanding, puzzleRating, at }], me: { rating, solves, rank } | null } | { mode: "preview", puzzles: [], topSolvers: [], recentSolves: [], me: null, message }
+  - Returns: { mode: "live", dayKey, puzzles: [{ ruleId, title, setKey, rating, solvers, failers, failures?, daysStanding, status: "untouched" | "undefeated" | "defeated" }], topSolvers: [{ rank, userId, username, profilePicUrl, rating, solves, hardestSolve: { ruleId, setKey, rating } | null }], recentSolves: [{ id, userId, username, ruleId, setKey, tier: "solved" | "first-solve" | "hard-won" | "legendary", firstTry, firstSolve, failersBefore, daysStanding, puzzleRating, at }], me: { rating, solves, rank } | null } | { mode: "preview", puzzles: [], topSolvers: [], recentSolves: [], me: null, message }
   - Front-page difficulty board for until-earned quiz bounties: what is being tried and failed, who is rated highest, and the latest defeats.
   - Computed by Twinkle from its own receipts and attempts, never from anything the app submits. Puzzles are Elo-rated against players: a player's first miss on a puzzle is a win for the puzzle, a solve is a win for the player, and repeat misses by one player never stack.
-  - puzzles lists today's set for each until-earned rule. status 'undefeated' means someone tried and nobody has solved it yet; show it as a standing challenge. failers is how many different players missed it; failures is total wrong answers.
-  - tier on a recent solve says how loudly to celebrate: 'legendary' (first solve of a long-undefeated puzzle), 'hard-won', 'first-solve', or plain 'solved'. It is fixed at solve time, so it never changes later.
+  - puzzles lists today's set for each until-earned rule. status 'undefeated' means someone tried and nobody has solved it yet; show it as a standing challenge. failers is how many different players missed it; failures is total wrong answers, sent only while the puzzle is still unsolved (absent on defeated puzzles, so a solver's own misses cannot be worked out).
+  - tier on a recent solve says how loudly to celebrate: 'legendary' (first solve of a long-undefeated puzzle), 'hard-won', 'first-solve', or plain 'solved'. It is fixed at solve time, so it never changes later. firstTry is true when the solver got it on the first try; which try it took and the solver's own wrong answers are never shown to other players, so never reconstruct them.
   - No questions, answers, guides or private work are ever returned. Names are the same public names the XP leaderboard shows; other players who missed a puzzle are counted, never named. Drafts and previews return mode 'preview' with empty lists.
 - await Twinkle.rewards.getTimeline({ ruleId?, cursor?, limit? } = {}) | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, attempt, story: { tier, attempt, failersBefore, failuresBefore, daysStanding } | null, puzzle: { rating, solvers, failers, failures } | null, vault: { rating, solvers, failers, failures } | null, rematchOpen }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
+  - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, firstTry, story: { tier, firstTry, failersBefore, daysStanding } | null, puzzle: { rating, solvers, failers } | null, vault: { rating, solvers, failers, failures } | null, rematchOpen }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
   - Browse confirmed solves of retired until-earned quiz bounties, newest first.
   - A solve appears only after the next site reset (UTC midnight, 9 AM Korea). Today’s solves, unsolved sets, standing quizzes and dated quizzes are excluded. The server decides retirement; client dates cannot unlock content. Zero-reward correct solves are included.
   - One entry per solve receipt, with firstSolver identifying the first receipt for that rule and set across approved versions. limit defaults to 20, max 50; pass nextCursor unchanged for older solves and omit it when changing ruleId. Pages may have fewer entries when old question sheets cannot be recovered; continue while nextCursor is present.
   - No daily-claim limit applies to reading. Requires the current approved published runtime grant; previews return an empty timeline. Never awards or changes balances. Open a receipt with getArchivedProblem to load the original question and guide.
-  - Museum fields: story is how THAT solve went, fixed at solve time (tier 'solved' | 'first-solve' | 'hard-won' | 'legendary', the solver's attempt, how many other players had missed it and how often, days it stood); null for receipts older than solve logging. puzzle is the official challenge rating and counts now; vault is the puzzle's living practice stats (its own rating, practice solvers, players whose first practice answer missed, all wrong practice answers), or null before anyone practised it. Counts only: players who missed are never named.
+  - Museum fields: story is how THAT solve went, fixed at solve time (tier 'solved' | 'first-solve' | 'hard-won' | 'legendary', firstTry: whether the solver got it on the first try, never which try, how many other players had missed it, days it stood); null for receipts older than solve logging. puzzle is the official challenge rating and counts now (no total wrong answers: it is solved, and that total would give away the solver's own misses); vault is the puzzle's living practice stats (its own rating, practice solvers, players whose first practice answer missed, all wrong practice answers), or null before anyone practised it. Counts only: players who missed are never named.
   - rematchOpen is true on the entry that is today's daily rematch while the viewer can still answer it for pay: label it and open it as the rematch, not as a lesson. Daily-rematch receipts are never timeline entries.
 - await Twinkle.rewards.getArchivedProblem({ receiptId, withGuide?: true }) | scopes: rewards:claim
   - Returns: { mode: "live", entry: <same solve entry as getTimeline, with rematchOpen>, questions: [{ prompt, hint?, guide? }], rematchOpen } | { mode: "preview", entry: null, questions: [], message }

package/sdk/LUMINE_ADMIN.md

@@ -198,6 +198,12 @@ IP evidence, private messages, or unrelated activity. `--include-private-evidenc
 adds DOB values and verified email addresses only; exact device IDs are never
 returned.
 
+The CLI sends `identity inspect` and `identity network` as reads, so it keeps
+no copy of the result on disk; the server still records who looked, when and
+why, one audit row per call. When a case needs a kept copy (a bullying or police
+matter, say), add `--output <file>`: the result is written there with
+owner-only (0600) permissions, and nowhere else.
+
 Every inspection requires a concrete `--reason`. Before loading the evidence,
 the API commits a private `identity.inspect` audit receipt containing the real
 operator, requested target, reason, and whether private evidence was requested.
@@ -1176,7 +1182,7 @@ lumine admin identity network <userId|username> --reason <text> [--include-priva
 **Network evidence** (`users_actions` addresses, added 2026-10-04): the account's most recently used addresses (up to 8), and for each one who else acted from it.
 - An address more than 8 other accounts use is a **shared network** (an academy, a school, a café): it is only counted, never listed, because it links strangers. Teachers and students at the same academy share one.
 - An address 8 or fewer other accounts use is a **small network** (a home): every account on it is listed with its age, role and account type. The person's own linked accounts (email, device, bucket) are marked `their linked account` and never raise a flag; logged-out visits are not accounts. If the addresses cannot be read (time cap), the pack still answers, with `network_evidence_unavailable`.
-- Addresses are masked (`58.151.x.59`) with a stable `addressId` for comparing reports; `--include-private-evidence` on `identity network` shows the full address. `identity network` commits an access receipt with your reason before reading anything, like `identity inspect`.
+- Addresses are masked (`58.151.x.59`) with a stable `addressId` for comparing reports; `--include-private-evidence` on `identity network` shows the full address. `identity network` commits a server-side access audit row with your reason before reading anything, like `identity inspect`; neither leaves a local copy unless you pass `--output <file>`.
 - Only each address's newest 5,000 actions and each person's newest 5,000 are read (index-bounded, replica, time-capped), so `older history not read` can appear.
 
 **Flags.** A linked account counts as a *minor* only with a recorded age under 18, and as a *member* when it holds no teacher/staff role (most accounts record no age, so "member" does not mean student):
@@ -1362,6 +1368,40 @@ those exact files and does not depend on keeping the review copy. Re-offers
 reuse the media; a failed transaction cleans up its copied objects. Declining
 leaves the offered media as unused uploads in the creator's library.
 
+### Owner client trace (any time, read-only; added 2026-10-06)
+
+When Mikey reports a UI issue from his phone, read what his browser did
+before guessing. Only the owner's own signed-in browser records it (everyone
+else's is a no-op and the upload route refuses them); the server keeps 30 days.
+
+```bash
+lumine admin owner-trace --since 30m                       # readable timeline, oldest first
+lumine admin owner-trace --since 2026-10-06T09:00 --type route,feed-open
+lumine admin owner-trace --path /comments/123 --json        # raw rows
+lumine admin owner-trace --since 1h --perf                 # performance events only
+```
+
+Event types: `session` (version, viewport, platform, PWA or tab), `route`
+(PUSH/POP/REPLACE, previous path, Home feed navigation/intent ids and action),
+`feed-open` (content type and id, open/comment/reward/recommend, how it was
+triggered and the tapped element's tag, card position), `scroll-anchor` (the
+scroll-anchor diagnostics: save/restore/cancel with scroll numbers),
+`content-scroll` (scrollTop at mount, when the content is ready, and 1 s/3 s
+later), `error`/`rejection` (short message and source file), `visibility`,
+`pagehide`, `trace-dropped`. Times are the phone's clock in this machine's
+time zone. Ids and paths only, never message text or other members' content.
+
+Performance events (`--perf` shows only these): `nav-timing` (one per
+navigation: ms from the tap to the URL change, the deploy-probe gate release
+with the probe's outcome current/armed/timeout/failed/throttled/backoff/pending
+and how long the tap waited for it, the route commit and, on content pages,
+content-ready; `cut by next-nav` means another navigation started before this
+one committed), `slow-request` (API requests over 1 s: method, path pattern
+with query keys only, status, ms, scheduler queue time), `stall` (main-thread
+gaps over 200 ms while the page is visible, bursts within 1 s coalesced) and
+`page-load` (once per load: TTFB, DOMContentLoaded, load, first route ready,
+ms since navigation start).
+
 ### Reward question-bank seeding (every full daily review; added 2026-09-28)
 
 `generated-quiz` rules fill a question bank on the server: a question is