@stage5/lumine 0.3.86 → 0.3.88

package/README.md

@@ -388,6 +388,68 @@ runs must pass
 models; `xhigh` and `max` require a 2.6 model (flare or sunburst). Estimates describe image output;
 actual battery usage also includes prompt and reference input.
 
+## Previewing and testing like Lumine
+
+`lumine preview` and `lumine test` run Lumine's own preview tools
+(`view_preview` and `run_preview_test`) on Twinkle's capture browser, so
+Codex, Claude Code and Lumine check a build the same way. They are read-only:
+the capture sandbox refuses SDK writes, reward claims, notifications and paid
+app AI, nothing is saved, and no AI or Energy is used. Run them from a pulled
+workspace (they send its files, saved or not) or pass `--saved` to check the
+saved project, and `--build <id>` outside a workspace. They work on builds you
+own; on a team project, preview your own branch.
+
+```bash
+# Screenshot (saved under .twinkle/previews/ unless --out), runtime errors and
+# layout overflow. Actions run in order from the opening screen (up to 24).
+lumine preview --viewport phone --actions '[{"type":"click","x":500,"y":620},{"type":"touch","x":500,"y":700,"endX":500,"endY":300}]'
+
+# A throwaway test: inputs plus checks, each step reported.
+lumine test .twinkle/tests/map-scroll.json
+```
+
+Keep test files under `.twinkle/tests/` (or outside the workspace): anything
+among the project files is uploaded by `lumine save`.
+
+`.twinkle/tests/map-scroll.json`:
+
+```json
+{
+  "name": "world map scrolls to the status bar",
+  "viewport": "phone",
+  "steps": [
+    { "type": "click", "x": 500, "y": 620 },
+    { "type": "expect", "text": "World Map", "state": "visible" },
+    { "type": "touch", "x": 500, "y": 800, "endX": 500, "endY": 200, "durationMs": 400 },
+    { "type": "expect", "selector": "#status", "state": "in_view", "timeoutMs": 1500 },
+    { "type": "expect_value", "path": "game.screen", "op": "equals", "value": "map" },
+    { "type": "call", "module": "/rules.js", "export": "scoreWord", "args": ["CAT"], "op": "equals", "value": 3 }
+  ]
+}
+```
+
+- Inputs: `click`, `touch` (add `endX`/`endY` to drag or swipe, `durationMs`
+  to hold), `scroll` (`deltaY`), `key` (`key`), `wait` (`durationMs`).
+  Coordinates are 0-1000 across the app frame.
+- Checks: `expect` (`text` or a CSS `selector`; `state` visible, in_view,
+  present or absent; `which` any/first/last; `timeoutMs` up to 3000),
+  `expect_value` (a `path` the app keeps on `window`, `op` equals, not_equals,
+  gt, gte, lt, lte, truthy, falsy or contains, and the expected `value`; a
+  string value is read as JSON when it parses, so `"3"` means the number 3),
+  `call` (a project module's export with `args` as a list; `op` may
+  also be throws), `expect_pixels` (a region `x`,`y` to `endX`,`endY` with at
+  least `minShare` % within `tolerance` of `color` #rrggbb).
+- Up to 24 steps; a test stops at the first failed check. The result lists
+  each step as passed, done, failed, could_not_run or not_run, and `checked`
+  lists exactly what passed. A screenshot comes back only when a step fails.
+  A pass proves those checks at that moment in that browser, nothing more:
+  not saving, rewards, shared data or multiplayer.
+- Every call starts at the app's opening screen and closes the page after.
+  You get 8 looks per 10 minutes (the same budget as one Lumine run); a test
+  is one look, a preview is one look per 8 actions.
+- `--json` prints the full result; the exit code is 1 when a preview fails or
+  a test does not pass.
+
 ## Thumbnails
 
 `lumine thumbnail set <file>` uploads a jpg/png/webp (max 8MB) as the build's

package/lib/admin.js

@@ -7507,7 +7507,7 @@ function printRewardBankReport(data) {
   );
   for (const row of data.questionsToReview.reported) {
     console.log(
-      `  reported #${row.id} (${row.reports}, ${row.status}) ${row.ruleId}/${row.topicKey} s${row.step}: ${row.reasons}`,
+      `  reported #${row.id} (${row.reports}, ${row.status}) ${row.ruleId}/${row.topicKey} s${row.step}: ${row.reasons}${typeof row.lastReportedAt === "number" ? ` · last ${new Date(row.lastReportedAt * 1000).toISOString().slice(0, 10)}${row.reportsInWindow ? ` · ${row.reportsInWindow} new in window` : " · none new"}` : ""}`,
     );
   }
   for (const row of data.questionsToReview.hardest) {

package/lib/agent/mcp-server.js

@@ -94,7 +94,10 @@ async function handleMcpMessage({ line, session, tools }) {
     const toolName = String(message?.params?.name || "");
     const toolArguments = message?.params?.arguments || {};
     try {
-      const output = await session.call(toolName, toolArguments);
+      const { output, image } = await session.callTool(
+        toolName,
+        toolArguments,
+      );
       const isError = output?.ok === false || Boolean(output?.error);
       return writeMcpResult(id, {
         content: [
@@ -102,6 +105,16 @@ async function handleMcpMessage({ line, session, tools }) {
             type: "text",
             text: JSON.stringify(output),
           },
+          // A preview screenshot, as an MCP image block in the same result.
+          ...(image?.base64
+            ? [
+                {
+                  type: "image",
+                  data: image.base64,
+                  mimeType: image.mimeType || "image/jpeg",
+                },
+              ]
+            : []),
         ],
         isError,
       });

package/lib/agent/providers/codex.js

@@ -225,16 +225,36 @@ async function runCodexAppServerTurn({
       return;
     }
     try {
-      const output = await toolSession.call(
-        message.params?.tool,
-        message.params?.arguments || {},
-      );
+      // A preview screenshot rides in the same tool result as an image item.
+      const { output, image } =
+        typeof toolSession.callTool === "function"
+          ? await toolSession.callTool(
+              message.params?.tool,
+              message.params?.arguments || {},
+            )
+          : {
+              output: await toolSession.call(
+                message.params?.tool,
+                message.params?.arguments || {},
+              ),
+              image: null,
+            };
       const success = output?.ok !== false && !output?.error;
       send({
         jsonrpc: "2.0",
         id: message.id,
         result: {
-          contentItems: [{ type: "inputText", text: JSON.stringify(output) }],
+          contentItems: [
+            { type: "inputText", text: JSON.stringify(output) },
+            ...(image?.base64
+              ? [
+                  {
+                    type: "inputImage",
+                    imageUrl: `data:${image.mimeType || "image/jpeg"};base64,${image.base64}`,
+                  },
+                ]
+              : []),
+          ],
           success,
         },
       });

package/lib/agent/tool-session.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { executeExternalAgentTool } from "../api.js";
+import { executeExternalAgentTool, runBuildPreviewTool } from "../api.js";
+import { PREVIEW_TOOL_TIMEOUT_MS } from "../preview.js";
 import {
   collectWorkspaceTextFilesLenient,
   resolveLocalProjectFilePath,
@@ -10,6 +11,16 @@ import {
 import { appendAgentTrace } from "./trace.js";
 
 const EXTERNAL_AGENT_MAX_TOOL_CALLS_PER_HOSTED_ROUND = 8;
+// Lumine's preview tools run on Twinkle's capture browser through POST
+// /cli/build/:id/preview-tool (the same route as lumine preview / lumine
+// test), not through /agent/tool. Each call takes one look from the member's
+// shared look quota. Twinkle keeps no page between calls, so this session
+// keeps the walk the last call recorded and sends it back: "continue"
+// replays it before the new input, exactly like a Build run after an edit.
+const EXTERNAL_AGENT_PREVIEW_TOOL_NAMES = new Set([
+  "view_preview",
+  "run_preview_test",
+]);
 
 export async function createExternalAgentToolSession({
   options,
@@ -60,16 +71,68 @@ export class ExternalAgentToolSession {
     this.provider = provider;
     this.projectFiles = projectFiles;
     this.readPaths = [];
+    this.previewWalk = null;
     this.sequence = 0;
     this.queue = Promise.resolve();
   }
 
-  call(name, toolArguments) {
+  // The tool output only (text tools and adapters without image support).
+  async call(name, toolArguments) {
+    return (await this.callTool(name, toolArguments)).output;
+  }
+
+  // { output, image }: image is a preview screenshot ({ mimeType, width,
+  // height, base64 }) for the adapter to attach to the tool result, or null.
+  callTool(name, toolArguments) {
     const pending = this.queue.then(() => this.#call(name, toolArguments));
     this.queue = pending.catch(() => undefined);
     return pending;
   }
 
+  offersPreviewTool(toolName) {
+    return (
+      EXTERNAL_AGENT_PREVIEW_TOOL_NAMES.has(toolName) &&
+      (Array.isArray(this.runtime?.tools) ? this.runtime.tools : []).some(
+        (tool) => tool?.name === toolName,
+      )
+    );
+  }
+
+  async #callPreview(toolName, toolArguments) {
+    try {
+      const result = await runBuildPreviewTool({
+        options: this.options,
+        auth: this.auth,
+        buildId: this.buildId,
+        tool: toolName,
+        arguments: toolArguments,
+        projectFiles: this.projectFiles,
+        agent: { walk: this.previewWalk },
+        timeoutMs: Math.max(
+          Number(this.options?.timeoutMs || 0),
+          PREVIEW_TOOL_TIMEOUT_MS,
+        ),
+      });
+      if (result && "walk" in result) this.previewWalk = result.walk || null;
+      return {
+        output: result?.output ?? { ok: false, error: "No preview result." },
+        image: result?.image?.base64 ? result.image : null,
+      };
+    } catch (error) {
+      // A refusal (look quota, busy, not the owner) is a tool result the
+      // model can act on, not a crash of the pass.
+      if (!error?.status) throw error;
+      return {
+        output: {
+          ok: false,
+          error: String(error.message || "The preview request failed."),
+          ...(error.data?.code ? { code: error.data.code } : {}),
+        },
+        image: null,
+      };
+    }
+  }
+
   async #call(name, toolArguments) {
     this.sequence += 1;
     const sequence = this.sequence;
@@ -98,7 +161,7 @@ export class ExternalAgentToolSession {
         ok: false,
         result: output.error,
       });
-      return output;
+      return { output, image: null };
     }
 
     const toolName = String(name || "").trim();
@@ -114,6 +177,38 @@ export class ExternalAgentToolSession {
           : [],
     });
     const startedAt = Date.now();
+    if (this.offersPreviewTool(toolName)) {
+      try {
+        const { output, image } = await this.#callPreview(
+          toolName,
+          toolArguments,
+        );
+        await appendAgentTrace(this.traceFile, {
+          type: "tool_result",
+          provider: this.provider,
+          phase: this.runtime?.phase || null,
+          sequence,
+          tool: toolName,
+          durationMs: Date.now() - startedAt,
+          ok: output?.ok !== false && !output?.error,
+          changedPaths: [],
+          result: summarizeToolResult(output),
+        });
+        return { output, image };
+      } catch (error) {
+        await appendAgentTrace(this.traceFile, {
+          type: "tool_result",
+          provider: this.provider,
+          phase: this.runtime?.phase || null,
+          sequence,
+          tool: toolName,
+          durationMs: Date.now() - startedAt,
+          ok: false,
+          error: String(error?.message || error).slice(0, 500),
+        });
+        throw error;
+      }
+    }
     const previousFiles = this.projectFiles;
     try {
       const result = await executeExternalAgentTool({
@@ -152,7 +247,7 @@ export class ExternalAgentToolSession {
         changedPaths,
         result: summarizeToolResult(output),
       });
-      return output;
+      return { output, image: null };
     } catch (error) {
       await appendAgentTrace(this.traceFile, {
         type: "tool_result",
@@ -294,8 +389,15 @@ function summarizeToolResult(output) {
     "pathsOmitted",
     "matchCount",
     "filesRead",
+    "capturesLeft",
   ]) {
     if (output[key] !== undefined) summary[key] = output[key];
   }
+  // Preview results: what happened, never the screenshot or page text.
+  if (typeof output.test?.status === "string") summary.test = output.test.status;
+  if (typeof output.interaction?.status === "string") {
+    summary.interaction = output.interaction.status;
+  }
+  if (typeof output.replay?.status === "string") summary.replay = output.replay.status;
   return Object.keys(summary).length > 0 ? summary : "completed";
 }

package/lib/api.js

@@ -246,6 +246,34 @@ export async function validateExternalAgentCandidate({
   });
 }
 
+// Lumine's view_preview / run_preview_test on Twinkle's capture browser.
+// projectFiles null previews the saved project. agent ({ walk }) is the
+// lumine agent form: Lumine's tool contract, one look per call.
+export async function runBuildPreviewTool({
+  options,
+  auth,
+  buildId,
+  tool,
+  arguments: toolArguments,
+  projectFiles,
+  agent,
+  timeoutMs,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/preview-tool`,
+    authToken: auth.token,
+    body: {
+      tool,
+      arguments: toolArguments,
+      ...(Array.isArray(projectFiles) ? { projectFiles } : {}),
+      // lumine agent: one look per call and the walk from its last call.
+      ...(agent ? { agent } : {}),
+    },
+    timeoutMs: timeoutMs || options.timeoutMs,
+  });
+}
+
 export async function loadBuildVersions({ options, auth, buildId, limit }) {
   const url = new URL(`${options.apiUrl}/cli/build/${buildId}/versions`);
   if (limit) url.searchParams.set("limit", String(limit));

package/lib/commands.js

@@ -58,6 +58,7 @@ import {
   writeAssetsManifest,
 } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
+import { previewCommand, testCommand } from "./preview.js";
 import { rewardsCommand, reportRewardDeclaration } from "./rewards.js";
 import { cardcraftCommand } from "./cardcraft.js";
 import { chatlogCommand } from "./chatlog.js";
@@ -305,6 +306,14 @@ export async function main() {
     await thumbnailCommand(options);
     return;
   }
+  if (options.command === "preview") {
+    await previewCommand(options);
+    return;
+  }
+  if (options.command === "test") {
+    await testCommand(options);
+    return;
+  }
   if (options.command === "doctor") {
     await doctorCommand(options);
     return;
@@ -2525,6 +2534,8 @@ export function parseArgs(args) {
     "includePrefix",
     "allowSharedNetwork",
     "send",
+    // lumine preview|test --saved
+    "saved",
   ]);
   // A flag that may stand alone (true) or carry a value: `--confirm` confirms
   // an AI bucket change.
@@ -2942,10 +2953,22 @@ export function parseArgs(args) {
     assetName: raw.name ? String(raw.name) : "",
     transparent: parseBoolean(raw.transparent, false),
     out: raw.out ? String(raw.out) : "",
+    // lumine preview / lumine test (lib/preview.js)
+    previewViewport: raw.viewport ? String(raw.viewport) : "",
+    previewFocus: raw.focus ? String(raw.focus) : "",
+    previewActions: raw.actions ? String(raw.actions) : "",
+    previewSteps: raw.steps ? String(raw.steps) : "",
+    previewName: raw.name ? String(raw.name) : "",
+    previewSaved: parseBoolean(raw.saved, false),
     target:
       raw.url ||
       raw.target ||
-      (command === "rename" || command === "describe" || command === "suggest"
+      (command === "rename" ||
+      command === "describe" ||
+      command === "suggest" ||
+      // the positional is the test file; the build comes from --build or the workspace
+      command === "preview" ||
+      command === "test"
         ? ""
         : command === "suggestions"
           ? suggestionListTarget
@@ -3282,6 +3305,8 @@ export function printHelp() {
   lumine update-from-main [twinkle-branch-url]
   lumine save [--summary <text>] [--publish] [--json]
   lumine check [twinkle-build-url]
+  lumine preview [--viewport phone|desktop] [--actions <json|file>] [--focus <text>] [--out <file>] [--saved] [--build <id>] [--json]
+  lumine test <test.json> | --steps <json|file> [--viewport phone|desktop] [--name <text>] [--out <file>] [--saved] [--build <id>] [--json]
   lumine launch [twinkle-build-url]
   lumine sdk list
   lumine sdk call <namespace.method> [jsonArgs]
@@ -3412,7 +3437,7 @@ export function printHelp() {
   lumine admin member-trace list | on <username> --reason <why> | off <username> | [read] <username> [--since 2h|30m|3d|<iso>] [--source all|client|server] [--type reload,route,chat-select,boot,session,error,rejection,boundary-error,api] [--path <substring>] [--limit 300] [--json]   (the owner trace switched on for specific member accounts to chase a bug they report: on/off are audited admin actions and take effect within 30 s; the website side records page loads with version and bundle, routes, chat channel/subchannel selection, every self-reload with its reason (kept on the device across the reload), error screens and window errors; the API side records each request from that account with its route, status, time and the website version it reported, so a device stuck on an old cached bundle still shows; read prints a plain summary first; 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 jev-images report [--days 1..30] | switch --area <all|arena_paper|arena_picture|study_record|thumbnail|sdk_decide> --mode on|off [--daily-cap <0-5000>] [--build <id>, sdk_decide only, no --daily-cap] | decide --area <area> --key <subject key> --decision <decision> | thumbnails --targets <subject:<id>,build:<id>,...> | --featured [--saved-only] [--json]   (JEV image checks: advisory only; per-area health, cost, agreement with final decisions and escalations for the daily run; switch is owner-only and needs no deploy; thumbnails adds notes for Featured review and never replaces or unfeatures anything)
-  lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements and Auto fallbacks; collection is not review)
+  lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements, Auto fallbacks and self-contradictory JEV answers; collection is not review)
   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/lib/constants.js

@@ -242,6 +242,25 @@ lumine save --summary "Describe the change"
 \`\`\`
 
 - Run lumine check before launch when possible.
+- See and test the app the way Lumine does, on Twinkle's own capture browser
+  (read-only: nothing is saved, no rewards, no AI, no Energy). Both use this
+  workspace's files, saved or not (--saved uses the saved project):
+  - \`lumine preview [--viewport phone|desktop] [--actions <json|file>]\`
+    saves a screenshot (path printed) plus runtime errors and layout overflow.
+    Actions: click, touch (endX/endY to drag), scroll, key, wait, with x/y
+    0-1000 across the app; up to 24, in order from the opening screen.
+  - \`lumine test .twinkle/tests/<name>.json\` runs a throwaway test
+    ({"name","viewport","steps"}; keep test files under .twinkle/tests/, never
+    among the project files, or lumine save uploads them): the same inputs plus checks (expect text or
+    a CSS selector visible/in_view/present/absent, expect_value on a path the
+    app keeps on window, call a project module's export, expect_pixels on a
+    region). It reports each step and lists exactly what passed; a screenshot
+    comes back only when a step fails. Use it before you say a fix works that a
+    screenshot cannot show (a scroll that must end somewhere, a screen several
+    taps deep, a rule in your JS). A pass proves only its listed checks: not
+    saving, rewards, shared data or multiplayer.
+  - Every call starts at the opening screen. 8 looks per 10 minutes, like one
+    Lumine run; previews run on builds you own (use your branch).
 - \`lumine versions\` lists this build's previous saves (add --main inside a
   branch workspace for the team project's main history). \`lumine pull
   --version <n>\` checks a previous save out read-only alongside the workspace
@@ -465,6 +484,9 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "assets",
   // versions only reads save history.
   "versions",
+  // preview/test only read: the capture sandbox never saves or writes.
+  "preview",
+  "test",
 ]);
 export const COMMANDS = new Set([
   "network",
@@ -498,6 +520,8 @@ export const COMMANDS = new Set([
   "save",
   "push",
   "check",
+  "preview",
+  "test",
   "launch",
   "versions",
   "restore",

package/lib/preview.js

@@ -0,0 +1,238 @@
+import fs from "fs/promises";
+import path from "path";
+
+import { runBuildPreviewTool } from "./api.js";
+import { ensureAuth } from "./auth.js";
+import { resolveSdkBuildId } from "./sdk.js";
+import {
+  collectProjectFiles,
+  findLocalProjectMetadata,
+  isReadOnlyReferenceMetadata,
+} from "./workspace.js";
+
+// `lumine preview` and `lumine test` run Lumine's own view_preview and
+// run_preview_test on Twinkle's capture browser (POST
+// /cli/build/:id/preview-tool), so an agent working through the CLI checks a
+// build exactly the way Lumine does in a Build run: same sandbox, same step
+// format, same results. Read-only, no AI and no Energy. Each call starts at
+// the app's opening screen and closes the page when it is done.
+
+export const PREVIEW_TOOL_TIMEOUT_MS = 330_000;
+export const PREVIEW_USAGE = `Usage:
+  lumine preview [--viewport phone|desktop] [--actions <json|file>] [--focus <text>] [--out <file>] [--saved] [--build <id>] [--json]
+  lumine test <test.json> [--viewport phone|desktop] [--name <text>] [--out <file>] [--saved] [--build <id>] [--json]
+  lumine test --steps <json|file> [--name <text>] ...
+Keep test files under .twinkle/tests/ so lumine save never uploads them.`;
+
+function usageError(message) {
+  const error = new Error(`${message}\n${PREVIEW_USAGE}`);
+  error.exitCode = 2;
+  return error;
+}
+
+// A flag value is inline JSON or a path to a JSON file.
+export async function readJsonArgument(value, label) {
+  const text = String(value || "").trim();
+  if (!text) return undefined;
+  if (/^[[{]/.test(text)) {
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw usageError(`${label} is not valid JSON: ${error.message}`);
+    }
+  }
+  let fileText;
+  try {
+    fileText = await fs.readFile(path.resolve(text), "utf8");
+  } catch (error) {
+    throw usageError(`Could not read ${label} file ${text}: ${error.code || error.message}`);
+  }
+  try {
+    return JSON.parse(fileText);
+  } catch (error) {
+    throw usageError(`${label} file ${text} is not valid JSON: ${error.message}`);
+  }
+}
+
+function normalizeViewport(value, fallback = "phone") {
+  const viewport = String(value || fallback).trim().toLowerCase();
+  if (viewport !== "phone" && viewport !== "desktop") {
+    throw usageError(`--viewport must be phone or desktop, not "${value}".`);
+  }
+  return viewport;
+}
+
+// What `lumine test` sends: a test file ({ name, viewport, steps }) or a bare
+// list of steps, with flags taking precedence.
+export async function resolveTestArguments(options) {
+  const fromFile = options.positional?.[0]
+    ? await readJsonArgument(options.positional[0], "test")
+    : undefined;
+  const fromFlag = options.previewSteps
+    ? await readJsonArgument(options.previewSteps, "--steps")
+    : undefined;
+  if (fromFile === undefined && fromFlag === undefined) {
+    throw usageError("Give a test file or --steps.");
+  }
+  const spec = Array.isArray(fromFile) ? { steps: fromFile } : fromFile || {};
+  const steps = fromFlag !== undefined
+    ? Array.isArray(fromFlag) ? fromFlag : fromFlag?.steps
+    : spec.steps;
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw usageError("A test needs a non-empty steps list.");
+  }
+  return {
+    name: String(options.previewName || spec.name || "test").slice(0, 80),
+    viewport: normalizeViewport(options.previewViewport || spec.viewport),
+    steps,
+  };
+}
+
+export async function resolvePreviewArguments(options) {
+  const actions = options.previewActions
+    ? await readJsonArgument(options.previewActions, "--actions")
+    : [];
+  const list = Array.isArray(actions) ? actions : actions?.actions;
+  if (!Array.isArray(list)) throw usageError("--actions must be a JSON list of steps.");
+  return {
+    viewport: normalizeViewport(options.previewViewport),
+    focus: options.previewFocus ? String(options.previewFocus).slice(0, 160) : null,
+    actions: list,
+  };
+}
+
+// The working files in this workspace (saved or not), or none to preview
+// the saved project. A read-only reference checkout is never sent as if it
+// were the build's own files.
+async function resolvePreviewProjectFiles(options, buildId) {
+  if (options.previewSaved) return { projectFiles: null, source: "saved" };
+  const localProject = await findLocalProjectMetadata(
+    options.dir ? path.resolve(options.dir) : process.cwd(),
+  );
+  const localBuildId = Number(localProject?.metadata?.buildId || 0);
+  if (
+    !localProject?.rootDir ||
+    localBuildId !== Number(buildId) ||
+    isReadOnlyReferenceMetadata(localProject.metadata)
+  ) {
+    return { projectFiles: null, source: "saved" };
+  }
+  const files = await collectProjectFiles(localProject.rootDir);
+  return {
+    projectFiles: files.map((file) => ({ path: file.path, content: file.content })),
+    source: "workspace",
+    rootDir: localProject.rootDir,
+  };
+}
+
+function defaultScreenshotPath({ rootDir, kind }) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const base = rootDir
+    ? path.join(rootDir, ".twinkle", "previews")
+    : process.cwd();
+  return path.join(base, `${kind}-${stamp}.jpg`);
+}
+
+async function saveScreenshot({ image, out, rootDir, kind }) {
+  if (!image?.base64) return null;
+  const target = out ? path.resolve(out) : defaultScreenshotPath({ rootDir, kind });
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, Buffer.from(image.base64, "base64"));
+  return target;
+}
+
+export function formatTestReport(output) {
+  const test = output?.test;
+  if (!test) return [output?.error || "The test did not run."];
+  const icon = { passed: "PASS", done: "done", failed: "FAIL", could_not_run: "STOP", not_run: "skip" };
+  const lines = [`Test "${test.name}": ${String(test.status).toUpperCase()}`];
+  for (const step of test.steps || []) {
+    lines.push(`  ${String(step.step).padStart(2)}. [${icon[step.result] || step.result}] ${step.does}${step.observed ? ` (saw: ${step.observed})` : ""}${step.reason ? ` (${step.reason})` : ""}`);
+  }
+  if (test.meaning) lines.push(test.meaning);
+  return lines;
+}
+
+export function formatPreviewReport(output) {
+  if (output?.ok !== true) return [`Preview failed: ${output?.error || "no result"}`];
+  const lines = [];
+  const interaction = output.interaction;
+  if (interaction?.status && interaction.status !== "not_requested") {
+    lines.push(`Input: ${interaction.status}${interaction.completed !== undefined ? ` (${interaction.completed}/${interaction.requested} steps)` : ""}`);
+  }
+  if (output.walk?.steps) lines.push(`Walk: ${output.walk.steps}`);
+  const runtime = output.runtime;
+  if (runtime?.summary) lines.push(`Runtime: ${runtime.summary}`);
+  else if (Array.isArray(runtime?.issues) && runtime.issues.length) {
+    lines.push(`Runtime issues: ${runtime.issues.length}`);
+  }
+  if (output.captureBrowser?.note) lines.push(`Note: ${output.captureBrowser.note}`);
+  return lines;
+}
+
+async function runPreviewTool(options, { tool, args, kind }) {
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  const files = await resolvePreviewProjectFiles(options, buildId);
+  const result = await runBuildPreviewTool({
+    options,
+    auth,
+    buildId,
+    tool,
+    arguments: args,
+    projectFiles: files.projectFiles,
+    timeoutMs: Math.max(options.timeoutMs || 0, PREVIEW_TOOL_TIMEOUT_MS),
+  });
+  const screenshot = await saveScreenshot({
+    image: result?.image,
+    out: options.out,
+    rootDir: files.rootDir,
+    kind,
+  });
+  return { buildId, files, result, screenshot };
+}
+
+function printJson({ buildId, files, result, screenshot }) {
+  console.log(JSON.stringify({
+    buildId,
+    files: files.source,
+    output: result?.output ?? null,
+    screenshot,
+    looks: result?.looks ?? null,
+    looksLeft: result?.looksLeft ?? null,
+  }, null, 2));
+}
+
+export async function previewCommand(options) {
+  if (options.help) {
+    console.log(PREVIEW_USAGE);
+    return;
+  }
+  const args = await resolvePreviewArguments(options);
+  const run = await runPreviewTool(options, { tool: "view_preview", args, kind: "preview" });
+  if (options.json) printJson(run);
+  else {
+    console.log(`Build #${run.buildId} preview (${args.viewport}, ${run.files.source === "workspace" ? "this workspace's files" : "saved files"}):`);
+    for (const line of formatPreviewReport(run.result?.output)) console.log(line);
+    if (run.screenshot) console.log(`Screenshot: ${run.screenshot}`);
+    console.log(`Looks left in this 10-minute window: ${run.result?.looksLeft ?? "?"}`);
+  }
+  if (run.result?.output?.ok !== true) process.exitCode = 1;
+}
+
+export async function testCommand(options) {
+  if (options.help) {
+    console.log(PREVIEW_USAGE);
+    return;
+  }
+  const args = await resolveTestArguments(options);
+  const run = await runPreviewTool(options, { tool: "run_preview_test", args, kind: "test-failure" });
+  if (options.json) printJson(run);
+  else {
+    console.log(`Build #${run.buildId} test (${args.viewport}, ${run.files.source === "workspace" ? "this workspace's files" : "saved files"}):`);
+    for (const line of formatTestReport(run.result?.output)) console.log(line);
+    if (run.screenshot) console.log(`Screenshot at the failed step: ${run.screenshot}`);
+    console.log(`Looks left in this 10-minute window: ${run.result?.looksLeft ?? "?"}`);
+  }
+  if (run.result?.output?.test?.status !== "passed") process.exitCode = 1;
+}

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.81.0
+Version: 1.81.1
 Updated: 2026-11-07
-Generated: 2026-11-07T02:35:09.137Z
+Generated: 2026-11-07T12:02:59.156Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -241,7 +241,7 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
   - Report live player or avatar bounds so the preview host can detect floor, wall, or out-of-bounds issues.
   - Always available in the build iframe.
   - Reports live gameplay bounds in the same coordinate space as setPlayfield.
-  - Use this for moving players or avatars so preview review and auto-fix can detect floor or wall escapes.
+  - Use this for moving players or avatars so the preview check can detect floor or wall escapes.
   - Do not report viewport-relative or screen-pixel rectangles; keep telemetry in stable game/world coordinates.
   - Example: Twinkle.preview.reportGameplayState({ playerBounds: { x: player.x, y: player.y, width: player.width, height: player.height } });
 - getGameplayTelemetry() | scopes: none

package/sdk/LUMINE_ADMIN.md

@@ -5633,7 +5633,7 @@ Legacy aliases such as `subjects list`, `subjects get`, `subjects featured`,
 `comments get`, and `recommend` remain accepted, but the singular command forms
 shown above are the canonical interface.
 
-For bounded case evidence, use `lumine admin jev-routing review --since <UTC-day> --until <next-UTC-day> --json` and follow every cursor, or `--all --checkpoint <persistent-file>`. Daily gather retains every20-event source page for the preceding complete UTC day. The reader covers paired disagreements and Auto fallbacks once per event; synthetic traffic is excluded unless `--include-synthetic` is explicit. It returns only currently unexpired frozen input and labels absent/expired input. A missing endpoint is unavailable coverage, not an empty healthy day. Collection never acknowledges reading or proves classification accuracy. This October28 reader and independent Auto-input capture are local until the matching release is verified.
+For bounded case evidence, use `lumine admin jev-routing review --since <UTC-day> --until <next-UTC-day> --json` and follow every cursor, or `--all --checkpoint <persistent-file>`. Daily gather retains every20-event source page for the preceding complete UTC day. The reader covers paired disagreements, Auto fallbacks and `candidate_inconsistent` events (JEV answered with fields that contradict each other, such as `lumine_turn` edit without `mutate_project`; `inconsistentFields` names them) once per event; synthetic traffic is excluded unless `--include-synthetic` is explicit. It returns only currently unexpired frozen input and labels absent/expired input. A missing endpoint is unavailable coverage, not an empty healthy day. Collection never acknowledges reading or proves classification accuracy. This October28 reader and independent Auto-input capture are local until the matching release is verified.
 
 Before calling a reply unrelated, check its original generation trigger and the bounded `askedAbout` descriptor. A member may have edited the visible turn or asked about linked content. The descriptor explicitly represents current stored metadata, not a separately frozen generation snapshot; never bypass deleted context.