@stage5/lumine 0.3.63 → 0.3.64

package/lib/admin-arena.js

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// `lumine admin arena queue|import|status`: Arena's mock-exam item bank
+// (twinkle-api controllers/cli/admin/arena.ts). Papers are written, blind-
+// solved and style-checked by Claude Code agents before they arrive here.
+//   queue                      per exam, mode and item type: live items, the
+//                              fewest unseen left for an active member, refills due
+//   import --dir <paper>       a paper folder of <number>.json items; --audio
+//                              audio/<exam>/<paper> attaches its recordings
+//                              (uploaded first with twinkle-api
+//                              scripts/arena-upload-media.ts); --live serves it
+//                              at once; a dry run (validation only) unless --confirm;
+//                              re-importing a folder retires that paper's earlier items
+//   status --item <id> --to live|retired|checked
+export const ARENA_USAGE =
+  "Usage: lumine admin arena queue | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked [--confirm] [--json]";
+const MAX_ITEMS = 300;
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function confirmed(options) {
+  const confirm = options.adminConfirm;
+  // absent is "", a bare --confirm is "true"
+  if (confirm !== "" && confirm !== "true") {
+    throw validationError("Pass --confirm on its own, without a value.");
+  }
+  return confirm === "true";
+}
+
+function readPaper(dir) {
+  if (!dir) throw validationError(ARENA_USAGE);
+  const folder = path.resolve(dir);
+  let names;
+  try {
+    names = fs.readdirSync(folder).filter((name) => /^\d+\.json$/.test(name));
+  } catch {
+    throw validationError(`Cannot read the folder ${folder}.`);
+  }
+  if (!names.length || names.length > MAX_ITEMS) {
+    throw validationError(`A paper folder holds 1 to ${MAX_ITEMS} <number>.json items.`);
+  }
+  return names
+    .map((name) => JSON.parse(fs.readFileSync(path.join(folder, name), "utf8")))
+    .sort((a, b) => a.number - b.number);
+}
+
+export function buildArenaOperation({ action, options }) {
+  if (!action || action === "queue") {
+    return {
+      name: "arena.queue",
+      method: "GET",
+      path: "/cli/admin/arena/queue",
+      body: undefined,
+      mutates: false,
+      requiresRun: false,
+    };
+  }
+  if (action === "import") {
+    const items = readPaper(options.adminDir);
+    const confirm = confirmed(options);
+    return {
+      name: confirm ? "arena.import" : "arena.import.preview",
+      method: "POST",
+      path: "/cli/admin/arena/items/import",
+      body: {
+        items,
+        live: Boolean(options.adminArenaLive),
+        dryRun: !confirm,
+        ...(options.adminArenaAudio ? { audioPrefix: options.adminArenaAudio } : {}),
+        // the folder name is the paper; re-importing it retires its earlier copy
+        paper: path.basename(path.resolve(options.adminDir)),
+      },
+      mutates: confirm,
+      requiresRun: false,
+      timeoutMs: 120000,
+    };
+  }
+  if (action === "status") {
+    const id = Number(options.adminArenaItem);
+    const to = String(options.adminArenaTo || "");
+    if (!Number.isInteger(id) || id <= 0 || !["live", "retired", "checked"].includes(to)) {
+      throw validationError(ARENA_USAGE);
+    }
+    if (!confirmed(options)) {
+      throw validationError(`This changes what members are served: add --confirm to set item ${id} ${to}.`);
+    }
+    return {
+      name: "arena.status",
+      method: "POST",
+      path: `/cli/admin/arena/items/${id}/status`,
+      body: { status: to },
+      mutates: true,
+      requiresRun: false,
+    };
+  }
+  throw validationError(ARENA_USAGE);
+}
+
+export function formatArenaResult({ operation, data }) {
+  if (operation.name === "arena.queue") {
+    const types = data?.types || [];
+    if (!types.length) return ["No live Arena items yet."];
+    const due = types.filter((t) => t.refillDue);
+    return [
+      ...types.map(
+        (t) =>
+          `${t.examFamily} ${t.difficulty || "normal"} ${t.itemType}: ${t.live} live, ${t.minFresh} unseen for the least-supplied member${
+            t.refillDue ? ` -> write ${t.toWrite}` : ""
+          }`,
+      ),
+      due.length ? `${due.length} type(s) due for a refill.` : "No refill due.",
+    ];
+  }
+  if (operation.name === "arena.import.preview") {
+    return [`Dry run: ${data?.wouldImport ?? 0} item(s) pass validation. Add --confirm to import.`];
+  }
+  if (operation.name === "arena.import") {
+    return [`Imported ${data?.imported ?? 0} item(s).`];
+  }
+  return [`Item ${data?.id} is now ${data?.status}.`];
+}

package/lib/admin-receipts.js

@@ -68,6 +68,13 @@ export function receiptToKeep(operation, result) {
         verified: data.verified === true,
       });
     }
+    // an Arena paper's blurred page: the signed link to the private file is not kept
+    case "approvals.redact":
+      return keep({
+        submissionId: data.submissionId ?? null,
+        page: data.page ?? null,
+        kind: data.kind ?? null,
+      });
     default:
       // Bridge Builder writes answer with the whole crew view: members' who-
       // are-you answers, parents' addresses and questions, held parent emails.

package/lib/admin.js

@@ -47,6 +47,7 @@ import { buildRolesOperation, printRoles } from "./admin-roles.js";
 import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
 import { buildNonogramOperation, formatNonogramResult } from './admin-nonogram.js';
+import { buildArenaOperation, formatArenaResult } from "./admin-arena.js";
 import {
   buildSlidingBlockOperation,
   formatSlidingBlockResult,
@@ -331,9 +332,12 @@ function buildNotableScoringOperation({ action, target, options }) {
   );
 }
 
-// Management approvals (dob/mentor/meetup) and the teacher audit.
+// Management approvals (dob/mentor/meetup, Arena score reports and papers)
+// and the teacher audit.
 const APPROVAL_USAGE =
-  "Use: lumine admin approvals list [--status pending|approved|rejected|settled|all] [--type dob|mentor|meetup] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>] | supermod <id> [--reason <text>]";
+  "Use: lumine admin approvals list [--status pending|approved|rejected|settled|all] [--type dob|mentor|meetup|arenaScore|arenaPaper] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>] | supermod <id> [--reason <text>] | redact <id> --page <n> --file <blurred.jpg|png|pdf>";
+// the API's limit for one blurred page (helpers/arena/reportMedia.ts)
+const ARENA_REDACTION_MAX_BYTES = 5 * 1024 * 1024;
 const TEACHER_USAGE =
   "Use: lumine admin teachers audit [--limit <1-100>] [--cursor <c>] [--all] | branches suggest|networks|confirm|unconfirm|set|clear|apply|list (`lumine admin teachers branches usage` prints each one) | revoke <userId> --reason <text> | review <userId> --decision legit|revoke --note <text> [--fingerprint <fp>] (revoke needs it) | review --all-flagged --expect <id[:fp],...> --note <text>";
 
@@ -343,6 +347,12 @@ function parseApprovalId(target) {
   return Number(raw);
 }
 
+// parseChoice lowercases; the API's Arena types are camelCase
+function parseApprovalType(value) {
+  const type = parseChoice(String(value), "--type", ["dob", "mentor", "meetup", "arenascore", "arenapaper"]);
+  return { arenascore: "arenaScore", arenapaper: "arenaPaper" }[type] || type;
+}
+
 function buildApprovalOperation({ action, target, options }) {
   const reason = String(options.adminReason || "").trim();
   if (!action || action === "list") {
@@ -357,13 +367,7 @@ function buildApprovalOperation({ action, target, options }) {
           "settled",
           "all",
         ]),
-        type: options.adminType
-          ? parseChoice(String(options.adminType), "--type", [
-              "dob",
-              "mentor",
-              "meetup",
-            ])
-          : "",
+        type: options.adminType ? parseApprovalType(options.adminType) : "",
       }),
       { requiresRun: false },
     );
@@ -374,6 +378,29 @@ function buildApprovalOperation({ action, target, options }) {
       requiresRun: false,
     });
   }
+  // An Arena paper's page replaced by the reviewer's blurred copy (names,
+  // student numbers): the image or PDF travels as base64.
+  if (action === "redact") {
+    const page = parseRequiredInteger(options.adminPage, "--page", 1, 99);
+    if (!options.adminFile) throw cliValidationError(APPROVAL_USAGE);
+    const filePath = path.resolve(options.adminFile);
+    let buffer;
+    try {
+      buffer = readFileSync(filePath);
+    } catch {
+      throw cliValidationError(`Could not read ${filePath}.`);
+    }
+    if (!buffer.length || buffer.length > ARENA_REDACTION_MAX_BYTES) {
+      throw cliValidationError("The blurred page must be an image or PDF of at most 5 MB.");
+    }
+    return writeOperation(
+      "approvals.redact",
+      "POST",
+      `/cli/admin/approvals/${id}/redact`,
+      { page, data: buffer.toString("base64") },
+      { requiresRun: false, timeoutMs: 120000 },
+    );
+  }
   // supermod: a teacher signup from academy staff becomes a supermod account
   // (the account type staff get) instead of a teacher (Mikey 2026-10-05).
   if (action === "approve" || action === "reject" || action === "supermod") {
@@ -2661,6 +2688,8 @@ export function parseAdminOperation(options) {
     return buildSlidingBlockOperation({ action, options });
   }
   if (namespace === 'nonogram') return buildNonogramOperation({ action, target, options });
+  // Arena's mock-exam item bank (admin-arena.js); no run.
+  if (namespace === "arena") return buildArenaOperation({ action, options });
   // Stuck Lumine Build plans and their free recheck (admin-build-plans.js).
   if (namespace === "build-plans") {
     return buildBuildPlansOperation({ action, options });
@@ -6777,7 +6806,45 @@ function printReviewEvents(events) {
     );
 }
 
-const APPROVAL_LABELS = { dob: "birthdate", mentor: "teacher", meetup: "meetup" };
+const APPROVAL_LABELS = {
+  dob: "birthdate",
+  mentor: "teacher",
+  meetup: "meetup",
+  arenaScore: "Arena score report",
+  arenaPaper: "Arena paper",
+};
+
+// One line describing an Arena item from its queue content.
+function arenaItemSummary(item) {
+  const c = item.content || {};
+  if (item.type === "arenaScore") {
+    const entry = [c.gradeLabel, c.score != null ? `${c.score}/${c.maxScore ?? "?"}` : null].filter(Boolean).join(" · ");
+    return `${c.sitting || "?"} ${c.exam || c.examKey || ""} · ${entry || "-"}${c.proof ? " · proof photo" : " · no proof"}`;
+  }
+  if (item.type === "arenaPaper") {
+    return `${[c.school, c.gradeLevel, c.year, c.term, c.subject].filter(Boolean).join(" ") || c.examKind || "paper"} · ${c.pages ?? "?"} file${c.pages === 1 ? "" : "s"} (${c.examKind || "?"})`;
+  }
+  return "";
+}
+
+function printArenaEvidence(arena) {
+  if (!arena) return;
+  if (arena.kind === "scoreReport") {
+    console.log(`Report #${arena.reportId}: ${arena.exam?.name || arena.exam?.key} · ${arena.sitting} · grade ${arena.gradeLabel || "-"} · score ${arena.score ?? "-"}${arena.exam?.maxScore ? `/${arena.exam.maxScore}` : ""} · ${arena.status}`);
+    console.log(arena.proofUrl ? `Proof (1-hour link): ${arena.proofUrl}` : "Proof: none sent");
+    console.log(`Reward on approval: ${arena.reward?.xp?.toLocaleString?.("en-US") ?? arena.reward?.xp} XP${arena.reward?.paid ? " (paid)" : ""}`);
+    if (arena.reviewNote) console.log(`Review note: ${arena.reviewNote}`);
+    for (const other of arena.otherReports || []) console.log(`  other report #${other.id}: ${other.title} · ${other.entry || "-"} · ${other.status}`);
+  } else if (arena.kind === "paper") {
+    const t = arena.tags || {};
+    console.log(`Paper #${arena.submissionId}: ${[t.school, t.gradeLevel, t.year, t.term, t.subject].filter(Boolean).join(" ")} (${t.examKind}) · ${arena.status}`);
+    for (const file of arena.files || []) console.log(`  page ${file.page} (${file.kind}${file.redacted ? ", blurred" : ""}, 1-hour link): ${file.url}`);
+    console.log(arena.duplicate ? `Duplicate: ${arena.duplicate.reason} of paper #${arena.duplicate.duplicateOf}` : "Duplicate: none found");
+    console.log(`Rarity: ${arena.rarity || "-"} · reward ${arena.reward?.xp?.toLocaleString?.("en-US") ?? 0} XP + ${arena.reward?.coins ?? 0} coins${arena.reward?.onApprove ? " on approval" : arena.reward?.paid ? " (paid)" : ""}`);
+    if (arena.reviewNote) console.log(`Review note: ${arena.reviewNote}`);
+  }
+  if (arena.check) console.log(`Check: ${arena.check}`);
+}
 const approvalDate = (seconds) =>
   seconds ? new Date(Number(seconds) * 1000).toISOString().slice(0, 10) : "?";
 
@@ -6964,7 +7031,7 @@ function printApprovalResult({ operation, data }) {
     if (!items.length) return console.log("No approval requests.");
     for (const item of items) {
       console.log(
-        `${item.ref} · ${APPROVAL_LABELS[item.type] || item.type} · ${item.status} · ${item.requesterUsername} (#${item.requesterId}) · ${approvalDate(item.requestedAt)}${item.flags ? ` · flags: ${item.flags.length ? item.flags.join(", ") : "none"}` : ""}`,
+        `${item.ref} · ${APPROVAL_LABELS[item.type] || item.type} · ${item.status} · ${item.requesterUsername} (#${item.requesterId}) · ${approvalDate(item.requestedAt)}${item.flags ? ` · flags: ${item.flags.length ? item.flags.join(", ") : "none"}` : ""}${arenaItemSummary(item) ? ` · ${arenaItemSummary(item)}` : ""}`,
       );
     }
     return;
@@ -6975,6 +7042,7 @@ function printApprovalResult({ operation, data }) {
       `${item.ref} · ${APPROVAL_LABELS[item.type] || item.type} · ${item.status} · ${item.requesterUsername} (#${item.requesterId})`,
     );
     printEvidence(data.evidence);
+    printArenaEvidence(data.arena);
     if (data.meetupEvidence) console.log(JSON.stringify(data.meetupEvidence, null, 2));
     return;
   }
@@ -6982,6 +7050,16 @@ function printApprovalResult({ operation, data }) {
     console.log(
       `${data.ref} ${data.status}${data.grantedAs ? ` as ${data.grantedAs}` : ""}: ${APPROVAL_LABELS[data.type] || data.type} request from ${data.requesterUsername} (#${data.requesterId}).`,
     );
+    if (data.reward) {
+      console.log(
+        `Reward: ${data.reward.xp} XP${data.reward.coins ? ` + ${data.reward.coins} coins` : ""}${data.rarity ? ` (${data.rarity})` : ""}${data.duplicateOf ? ` · duplicate of paper #${data.duplicateOf}` : ""} · paid now ${data.paidNow?.xp || 0} XP${data.paidNow?.coins ? ` + ${data.paidNow.coins} coins` : ""}${data.paymentPending ? " · payment still owed: approve again to retry" : ""}`,
+      );
+    }
+    if (data.reviewNote) console.log(`Note for the member: ${data.reviewNote}`);
+    return;
+  }
+  if (operation.name === "approvals.redact") {
+    console.log(`${data.ref}: page ${data.page} replaced with the blurred ${data.kind} (1-hour link: ${data.url}).`);
     return;
   }
   if (operation.name === "teachers.audit") {
@@ -7507,6 +7585,10 @@ function printAdminResult({ operation, result }) {
     printRoles(data);
     return;
   }
+  if (operation.name.startsWith("arena.")) {
+    for (const line of formatArenaResult({ operation, data })) console.log(line);
+    return;
+  }
   if (operation.name.startsWith("sliding-block.")) {
     for (const line of formatSlidingBlockResult({ operation, data }))
       console.log(line);

package/lib/commands.js

@@ -2472,6 +2472,8 @@ export function parseArgs(args) {
   const raw = {};
   const positional = [];
   const booleanFlags = new Set([
+    // lumine admin arena import --live
+    "live",
     "remove",
     "fault",
     "noAnnounce",
@@ -2696,6 +2698,11 @@ export function parseArgs(args) {
     adminOutput: raw.output ? String(raw.output) : "",
     adminOutputDir: raw.outputDir ? String(raw.outputDir) : "",
     adminDir: raw.dir ? String(raw.dir) : "",
+    // lumine admin arena (admin-arena.js)
+    adminArenaAudio: raw.audio ? String(raw.audio) : "",
+    adminArenaLive: parseBoolean(raw.live, false),
+    adminArenaItem: raw.item ? String(raw.item) : "",
+    adminArenaTo: raw.to ? String(raw.to) : "",
     adminClaimFile: raw.claim ? String(raw.claim) : "",
     adminScaffoldFile: raw.scaffold ? String(raw.scaffold) : "",
     adminTargetFile: raw.targetFile ? String(raw.targetFile) : "",
@@ -2854,6 +2861,7 @@ export function parseArgs(args) {
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    adminPage: raw.page ? String(raw.page) : "",
     adminQuestionId: raw.questionId ? String(raw.questionId) : "",
     rewardPreflight: Boolean(raw.preflight),
     rewardApprovalFile: raw.approvalFile ? String(raw.approvalFile) : "",
@@ -3298,7 +3306,7 @@ export function printHelp() {
   lumine admin sponsor integrity get <case-id> [--json]
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
   lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject|revoke <type:id> [--reason <text>] | propose rewards:<id> --dir <edited-snapshot> --config <rules.json>
-  lumine admin approvals list [--status pending|approved|rejected|all] [--type dob|mentor|meetup] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>] | supermod <id> [--reason <text>]   (management approvals with evidence: birthdates, teacher signups, meetups)
+  lumine admin approvals list [--status pending|approved|rejected|all] [--type dob|mentor|meetup|arenaScore|arenaPaper] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>] | supermod <id> [--reason <text>] | redact <id> --page <n> --file <blurred image|pdf>   (management approvals with evidence: birthdates, teacher signups, meetups, Arena score reports and papers with 1-hour file links)
   lumine admin teachers audit [--limit <1-100>] [--cursor <c>] [--all] | revoke <userId> --reason <text>   (approved teachers, a page at a time or --all: new flags first, then changed since your review; revoke removes the status cleanly)
   lumine admin teachers branches suggest | networks | confirm <networkId> --branch <name> [--branch <name>] [--note <text>] | unconfirm <networkId> | set <userId|username> --branch <name> [--note <text>] | clear <userId|username> | apply | list [--branch <name>|none]   (which branch each teacher works at, confirmed by you through the academy networks they use: suggest finds the networks, confirm names their branch (repeat --branch for a building branches share), apply gives teachers the branch most of their actions there point at and lists the unclear ones; set wins over networks)
   lumine admin teachers review <userId> --decision legit|revoke --note <text> [--fingerprint <fp>, required for revoke] | review --all-flagged --expect <id[:fp],...> --note <text>   (record your review of the facts shown; --all-flagged records only the --expect teachers; nothing is recorded if they changed since. A reviewed teacher comes back when its flags or linked accounts change; accounts sharing a network count only when they change a network flag)
@@ -3307,6 +3315,7 @@ export function printHelp() {
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin craft seed --build <id> --file <pairs.json> [--confirm] | stats --build <id> [--limit <1-100>] | revise --build <id> --item <id|name> [--why <text>] [--emoji <emoji>] [--category <field>] [--confirm] | revise --build <id> --pair <pairId|a+b> --why <text> [--confirm] | retire --build <id> --item <id|name> --reason <text> [--confirm] | unfizzle --build <id> [--since <iso>] [--pair <a+b>] [--confirm]   (Twinkle.craft curation: dry run without --confirm)
   lumine admin sliding-block status | add --file <levels.json> [--confirm]   (sliding-block-v1 campaign refills, RushHour: dry run without --confirm; the server solves each board and appends it)
+  lumine admin arena queue | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm   (Arena's mock-exam bank: import is a validation-only dry run without --confirm; upload audio first with twinkle-api scripts/arena-upload-media.ts)
   lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm]   (private reviewed pictures; changes are dry runs without --confirm)
   lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm]   (Lumine Build plans stuck on one milestone: runs, Energy vs estimate, gradings, loop-guard state; recheck re-grades the current milestone with today's evaluator, free for the creator, dry run without --confirm)
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]

package/lib/constants.js

@@ -1,7 +1,10 @@
 import os from "os";
 import path from "path";
 import { LUMINE_BUILDER_STANCE } from "./builderStance.generated.js";
-import { LUMINE_PLATFORM_RULES } from "./platformRules.generated.js";
+import {
+  LUMINE_ESSENTIAL_SDK,
+  LUMINE_PLATFORM_RULES
+} from "./platformRules.generated.js";
 
 export const DEFAULT_API_URL = "https://api.twinkle.network";
 export const DEFAULT_SITE_URL = "https://www.twin-kle.com";
@@ -160,6 +163,10 @@ ${LUMINE_MOBILE_SELECTION_GUIDANCE}
 
 ${LUMINE_PLATFORM_RULES}
 
+## Essential SDK Features (add without being asked)
+
+${LUMINE_ESSENTIAL_SDK}
+
 ${LUMINE_WORLD_UPDATE_GUIDANCE}
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
@@ -187,9 +194,14 @@ ${LUMINE_BUILDER_STANCE}
 
 ${LUMINE_PLATFORM_RULES}
 
+## Essential SDK Features (add without being asked)
+
+${LUMINE_ESSENTIAL_SDK}
+
 \`lumine check\` fails on forms, imports, SDK names, game layout and long-press
-selection, and lists canvas page kind, dialogs and new windows as platform
-rule notices (they do not block); a pass does not prove the other rules.
+selection, and lists canvas page kind, dialogs, new windows and games that do
+not keep the player's place as notices (they do not block); a pass does not
+prove the other rules.
 
 ## Source Of Truth
 

package/lib/platformRules.generated.js

@@ -1,3 +1,4 @@
 // Generated by twinkle-api/scripts/generate-build-sdk-index.mjs from
-// constants/buildSdkManifest.json (platformRules). Do not edit by hand.
+// constants/buildSdkManifest.json (platformRules, essentialSdk). Do not edit by hand.
 export const LUMINE_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.\n\n1. Every page that draws on a <canvas> (2D, WebGL or Three.js) says what kind of page it is on <html>: data-twinkle-game for a game that fills the screen, data-twinkle-document for a normal scrolling page with a drawing pad, chart, visualizer or background effect. Without it, unless the page lays itself out with Twinkle.preview, Twinkle guesses from the canvas, and any canvas larger than 160 px, even one hidden in a tab, locks the page to one screen so it no longer scrolls. Add the attribute together with the first canvas.\n2. Games (data-twinkle-game) size themselves from Twinkle.preview: subscribe with Twinkle.preview.subscribe(listener, { immediate: true }), size canvases and renderers from layout.stage or layout.viewport, and report the play area with Twinkle.preview.setPlayfield(). Never size a game from 100vh/100vw, window.innerWidth/innerHeight or visualViewport, and never draw a fake phone or browser frame unless the creator asks for a device mockup: those fight the host and leave the game blank, cropped or scrolling on phones. Pages marked data-twinkle-document use ordinary CSS layout instead.\n3. alert(), confirm() and prompt() are silently blocked: alert shows nothing, confirm() always returns false (so the action it guards never happens) and prompt() returns null. Use in-page UI instead: a message element, an in-page confirm step, an <input>.\n4. Apps cannot open new windows or tabs: window.open() and target=\"_blank\" links do nothing, and neither does a download link to an uploaded file. Open Twinkle pages with Twinkle.app.openContent(url) from a tap, save files with Twinkle.files.saveAs({ url, fileName }) (or { blob, fileName } for a file the app made), and show other web addresses as plain text.\n5. Do not use <form> elements: native form submission is blocked, so a submit button inside a form does nothing. Handle inputs and buttons in JavaScript.\n6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.\n7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.\n8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.\n9. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.\n10. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.\n11. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.\n12. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.";
+export const LUMINE_ESSENTIAL_SDK = "Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.\n\n1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.\n2. When: The app has more than one view: a list and its details, menus, chapters, pages, settings. Use: Twinkle.app.history.push on each confirmed view change and Twinkle.app.history.subscribe to restore views, so Back and Forward move inside the app instead of leaving it.\n3. When: Progress, collections, unlocks, high scores or settings the viewer expects to still have tomorrow. Use: Twinkle.privateDb (Twinkle.sharedDb for what everyone sees), written on a user action or as an occasional snapshot, never per frame.\n4. When: The app shares or links to something inside itself (a level, a post, a result). Use: Twinkle.app.getShareUrl(pathSegment) for the link, and read the segment back at startup, instead of building twin-kle.com URLs by hand.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.63",
+  "version": "0.3.64",
   "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.71.0
-Updated: 2026-10-24
-Generated: 2026-10-24T10:03:41.930Z
+Version: 1.73.0
+Updated: 2026-10-25
+Generated: 2026-10-25T00:59:10.277Z
 
 ## 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.
@@ -20,6 +20,14 @@ Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed f
 11. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.
 12. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.
 
+## Essential SDK features
+Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.
+
+1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.
+2. When: The app has more than one view: a list and its details, menus, chapters, pages, settings. Use: Twinkle.app.history.push on each confirmed view change and Twinkle.app.history.subscribe to restore views, so Back and Forward move inside the app instead of leaving it.
+3. When: Progress, collections, unlocks, high scores or settings the viewer expects to still have tomorrow. Use: Twinkle.privateDb (Twinkle.sharedDb for what everyone sees), written on a user action or as an occasional snapshot, never per frame.
+4. When: The app shares or links to something inside itself (a level, a post, a result). Use: Twinkle.app.getShareUrl(pathSegment) for the link, and read the segment back at startup, instead of building twin-kle.com URLs by hand.
+
 ## Notes
 - Reward is part of completion: a reward-paying run must stay pending until awarded:true and its canonical receipt (or getReceipt status awarded). Do not show final solved/completed status, advance rewarded progress, or discard finished proof before that. Preserve the exact challenge/proof and acknowledged progress in a durable per-viewer outbox; reconcile getReceipt after a lost reply and retry the same challenge, never inventing a payment. Explain explicit practice, already collected, exhausted approved limits, preview and disclosed zero-value retry outcomes. Use the start response as a conservative elapsed-time reference, and test delayed start, network failure, lost claim reply, reload, day/viewer change and duplicate recovery.
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -119,6 +127,26 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
   - Returns: Canonical shareable deep-link URL string, or null when app info is unavailable
   - Builds a canonical shareable deep link into this app, e.g. https://www.twin-kle.com/app/884/432-the-great-gatsby.
   - Example: await Twinkle.app.getShareUrl('432-the-great-gatsby');
+- lifecycle.onSuspend(getState) | scopes: none
+  - Returns: off function
+  - Keep the viewer's place: Twinkle calls getState() for a small snapshot whenever the app is hidden, goes to the background, or every so often while in use, and hands it back the next time the app starts.
+  - Phones keep few apps loaded: an app that is not on screen can be unloaded at any time (3D apps right away), and the browser can kill the whole tab. Without a snapshot the viewer starts over.
+  - getState() returns a plain JSON object of at most 1 MB and must be quick (a 1.5 s budget, sync or a promise). Save what is needed to put the viewer back: level, position, score in play, the open view, unsaved edits, a quiz in progress.
+  - One handler per app; registering again replaces it. Long-term saves (collections, completed progress) still belong in Twinkle.privateDb.
+  - After a restart with a saved place, Twinkle keeps that place until the viewer does something in the app (a tap or key): snapshots taken while the app is still loading or waiting on a CONTINUE screen are not sent. Call saveNow() if the app changes the place on its own before that.
+  - Example: Twinkle.app.lifecycle.onSuspend(() => ({ level, hp, x: player.x, y: player.y, inventory }));
+- async lifecycle.getResumeState() | scopes: none
+  - Returns: { state, savedAt, reason } or null
+  - At startup, the snapshot this viewer's last session of the app left behind (after an unload, a tab reload or crash), or null.
+  - Resolves once, early; await it before drawing the first screen so the viewer does not see a fresh start flash by.
+  - Check the snapshot's shape before using it: it can come from an older version of the app. Ignore what you do not recognise.
+  - Closing the app with its Close button starts it fresh next time (no snapshot). The Build editor preview always starts fresh.
+  - Example: const saved = await Twinkle.app.lifecycle.getResumeState(); if (saved) restore(saved.state);
+- async lifecycle.saveNow() | scopes: none
+  - Returns: true once Twinkle has the snapshot, false otherwise
+  - Take a snapshot right now, e.g. at a checkpoint or after an important step.
+  - Needs an onSuspend handler. Twinkle already snapshots on hide, background and every 45 s of use, so call this only at moments worth keeping exactly.
+  - Example: await Twinkle.app.lifecycle.saveNow();
 - history.getState() | scopes: none
   - Returns: The current app-owned history state object, or null
   - Read the current Build app view state stored through Twinkle.app.history.
@@ -1015,10 +1043,11 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - cells is a flat list of [x, y, z, paletteIndex] numbers; air is left out. palette entries are block states like "oak_stairs[facing=north,half=bottom]".
   - Private designs are only returned to their designer.
   - Example: const { size, palette, cells } = await Twinkle.minecraft.getDesign({ id: 'harbor_house' }); for (let i = 0; i < cells.length; i += 4) addCube(cells[i], cells[i + 1], cells[i + 2], palette[cells[i + 3]]);
-- async saveDesign({ id, name, summary, category, tags, visibility, parts }) | scopes: content:write
+- async saveDesign({ id, name, summary, category, tags, visibility, parts, cells }) | scopes: content:write
   - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt } }
-  - Save a design (or a new version of your design) from blueprint parts.
+  - Save a design (or a new version of your design) from blueprint parts, or from exact blocks (cells).
   - parts use Zero's blueprint shapes: box, hollow_box, walls, floor, line, block, cylinder, sphere, gable_roof, pyramid_roof; offsets x = east, y = up, z = south; later parts override earlier ones (carve doors/windows with "air"). Up to 60,000 blocks and 96 blocks in each direction.
+  - Exact blocks instead of parts (map art made from a picture, a block-by-block design): cells: { palette: ['white_wool', 'black_concrete', ...], cells: [x, y, z, paletteIndex, x, y, z, paletteIndex, ...] }, offsets as for parts. Up to 256 palette blocks and 60,000 blocks (Mikey 200,000), within 128 wide, 384 tall and 128 deep. Send parts or cells, not both.
   - category is building, decor, farm or path. visibility private (default) or public. Saving the same id again adds a version; only its designer can do that. Rejections come back as 400 minecraft_studio_rejected with a readable message.
   - Who may: any signed-in viewer; they own what they save (they can change or delete it). Only builders and above (access.canKeepPrivate from getDesigns) may keep a design private; for anyone else visibility must be 'public' (omitted means public) or the call fails with 403 minecraft_private_needs_builder. Builders and above save private designs when visibility is omitted. Players have a limit on how many designs they keep.
   - Example: await Twinkle.minecraft.saveDesign({ id: 'harbor_house', name: 'Harbor house', category: 'building', visibility: 'private', parts: [{ shape: 'floor', from: [0, 0, 0], to: [8, 0, 6], block: 'stone_bricks' }, { shape: 'walls', from: [0, 1, 0], to: [8, 4, 6], block: 'spruce_planks' }] });
@@ -1114,6 +1143,16 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Remove the viewer's arrival point in a world (back to the shared arrival).
   - world is a world id such as world, world1, world3, world_nether.
   - Example: await Twinkle.minecraft.clearArrivalPoint({ world: 'world3' });
+- async getMyNotices() | scopes: content:read
+  - Returns: { notices: [{ id, text, from, at, uuid, name }] }
+  - Personal news for the viewer's linked Minecraft accounts, for example that something they wanted and gave up on works now.
+  - Only unread ones. A notice is read once seen anywhere: Zero whispers it when the player joins the server, or the app marks it with markNoticesSeen. Empty when the viewer has no linked Minecraft account. uuid/name say which linked account it is for.
+  - Example: const { notices } = await Twinkle.minecraft.getMyNotices();
+- async markNoticesSeen({ uuid, ids }) | scopes: content:write
+  - Returns: { marked }
+  - Mark personal news as read after showing it (ids from getMyNotices, for that notice's uuid).
+  - Only the viewer's own linked accounts; up to 50 ids at a time.
+  - Example: await Twinkle.minecraft.markNoticesSeen({ uuid: notice.uuid, ids: [notice.id] });
 - async getPlayAreas() | scopes: content:read
   - Returns: { levels: [{ id, name, world, box: [x0,y0,z0,x1,y1,z1], spawn: [x,y,z], by, createdAt, status: 'capturing'|'ready'|'failed', chunkCount, done, blocks }] }
   - Play areas: captured Minecraft builds (a castle, a cathedral) that apps turn into first-person games, newest first.