@stage5/lumine 0.3.16 → 0.3.17

package/lib/admin-owner-trace.js

@@ -4,7 +4,16 @@
 // no daily run needed. The server keeps 30 days.
 
 export const OWNER_TRACE_USAGE =
-  "Usage: lumine admin owner-trace [--since 2h|30m|3d|<iso>|<unix>] [--type route,feed-open,scroll-anchor,content-scroll,error,...] [--path <substring>] [--limit 300] [--json].";
+  "Usage: lumine admin owner-trace [--since 2h|30m|3d|<iso>|<unix>] [--type route,feed-open,scroll-anchor,content-scroll,error,...] [--perf] [--path <substring>] [--limit 300] [--json].";
+
+// --perf: only the performance events (tap-to-page timeline, slow API
+// requests, main-thread stalls, page load).
+export const OWNER_TRACE_PERF_TYPES = [
+  "nav-timing",
+  "slow-request",
+  "stall",
+  "page-load",
+];
 
 const MAX_LIMIT = 2000;
 
@@ -41,7 +50,16 @@ export function buildOwnerTraceOperation(options) {
   const query = new URLSearchParams();
   query.set("since", normalizeSince(options.adminSince));
   query.set("limit", String(limit));
-  if (options.adminType) query.set("type", String(options.adminType));
+  const types = String(options.adminType || "")
+    .split(",")
+    .map((type) => type.trim())
+    .filter(Boolean);
+  if (options.adminPerf) {
+    for (const type of OWNER_TRACE_PERF_TYPES) {
+      if (!types.includes(type)) types.push(type);
+    }
+  }
+  if (types.length) query.set("type", types.join(","));
   if (options.adminPath) query.set("path", String(options.adminPath));
   return {
     name: "owner-trace.read",
@@ -107,6 +125,27 @@ export function describeOwnerTraceEvent(event) {
       return `${data.e || "?"} ${pairs(data, ["e"])}`.trim();
     case "content-scroll":
       return `${data.phase} ${data.ct}:${data.id} scrollTop=${data.st} height=${data.sh} viewport=${data.vh}`;
+    case "nav-timing":
+      return describeNavTiming(data);
+    case "slow-request": {
+      const extra = [
+        data.q ? `queued ${data.q}ms` : "",
+        data.tries ? `${data.tries} tries` : "",
+      ].filter(Boolean);
+      return `${data.m || "?"} ${data.api || "?"} → ${data.status ?? "?"} in ${data.ms}ms${extra.length ? ` (${extra.join(", ")})` : ""}`;
+    }
+    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": {
+      const parts = [
+        data.type || "",
+        data.ttfb !== undefined ? `ttfb ${data.ttfb}` : "",
+        data.dcl !== undefined ? `domcontentloaded ${data.dcl}` : "",
+        data.load !== undefined ? `load ${data.load}` : "",
+        data.route !== undefined ? `first route ${data.route}` : "",
+      ].filter(Boolean);
+      return `${parts.join(" · ")} ms${data.cached ? " (document from cache)" : ""}`;
+    }
     case "error":
     case "rejection":
       return `${data.msg || "(no message)"}${data.src ? ` (${data.src}:${data.line}:${data.col})` : ""}${data.status ? ` HTTP ${data.status}` : ""}`;
@@ -115,6 +154,29 @@ export function describeOwnerTraceEvent(event) {
   }
 }
 
+// "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) {
+  const end = data.ready ?? data.commit;
+  const head =
+    end !== undefined
+      ? `${data.via === "url" || data.via === "pop" ? "start" : "tap"}→${data.ready !== undefined ? "ready" : "page"} ${end}ms`
+      : `cut after ${data.total}ms`;
+  const steps = [
+    data.url !== undefined ? `url +${data.url}` : "",
+    data.gate !== undefined
+      ? `gate +${data.gate}${data.probe ? ` (probe ${data.probe}${data.probeMs ? `, waited ${data.probeMs}ms` : ""})` : ""}`
+      : "",
+    data.commit !== undefined ? `commit +${data.commit}` : "",
+    data.ready !== undefined ? `ready +${data.ready}` : "",
+  ].filter(Boolean);
+  const tail = [
+    data.result ? `gate ${data.result}` : "",
+    data.cut ? `cut by ${data.cut}` : "",
+  ].filter(Boolean);
+  return [head, `${data.nav || "?"} via ${data.via || "?"}`, ...steps, ...tail].join(" · ");
+}
+
 export function formatOwnerTrace(data) {
   const events = Array.isArray(data?.events) ? data.events : [];
   const lines = [];

package/lib/commands.js

@@ -2381,6 +2381,7 @@ export function parseArgs(args) {
     "all",
     "resume",
     "sinceRun",
+    "perf",
     "includeLegacy",
     "includePrivateEvidence",
     "reviewed",
@@ -2497,6 +2498,7 @@ export function parseArgs(args) {
     adminSinceRun: Boolean(raw.sinceRun),
     adminSince: raw.since ? String(raw.since) : "",
     adminPath: raw.path ? String(raw.path) : "",
+    adminPerf: Boolean(raw.perf),
     adminIncludeLegacy: Boolean(raw.includeLegacy),
     adminIncludePrivateEvidence: parseBoolean(
       raw.includePrivateEvidence,
@@ -3081,7 +3083,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] [--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; 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] [--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 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]
   lumine admin comment post --draft-id <id> [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.16",
+  "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

@@ -1378,6 +1378,7 @@ else's is a no-op and the upload route refuses them); the server keeps 30 days.
 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`
@@ -1390,6 +1391,17 @@ 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