@stage5/lumine 0.2.6 → 0.2.8

package/lib/api.js

@@ -68,6 +68,29 @@ export async function loadBuildFiles({ options, auth, buildId, includeContent })
   });
 }
 
+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));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function loadBuildVersionFiles({
+  options,
+  auth,
+  buildId,
+  versionNumber,
+}) {
+  return await requestJson({
+    url: `${options.apiUrl}/cli/build/${buildId}/versions/${versionNumber}/files`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function resolveBranchBuild({
   options,
   auth,

package/lib/commands.js

@@ -14,6 +14,8 @@ import {
   DEFAULT_TIMEOUT_MS,
   LUMINE_MAIN_CHECKOUT_INSTRUCTIONS,
   LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
+  LUMINE_VERSION_CHECKOUT_INSTRUCTIONS,
+  LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
   MAIN_CHECKOUT_READONLY_COMMANDS,
   PROJECT_METADATA_DIR,
   SDK_REFERENCE_FILE,
@@ -26,6 +28,8 @@ import {
   listOpenSourceBuilds,
   loadBuildFiles,
   loadBuildMetadata,
+  loadBuildVersionFiles,
+  loadBuildVersions,
   loadContributionDiff,
   loadLumineCliVersionInfo,
   loadOpenSourceBuildFiles,
@@ -50,13 +54,16 @@ import {
 } from "./auth.js";
 import { probeUrl, requestJson } from "./http.js";
 import { sdkCommand } from "./sdk.js";
+import { doctorCommand, normalizePreviewUrl } from "./doctor.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
+  defaultVersionCheckoutDir,
   defaultWorkspaceDir,
   parseBoolean,
   resolveBuildId,
   resolveBuildReference,
+  resolveRequiredBuildId,
   shellQuote,
   toCamelCase,
   trimTrailingSlash,
@@ -75,6 +82,7 @@ import {
   writeInstructionFiles,
   writeMainCheckoutMetadata,
   writeProjectFiles,
+  writeVersionCheckoutMetadata,
   writeProjectMetadata,
   writeReferenceInstructions,
   writeReferenceMetadata,
@@ -160,6 +168,14 @@ export async function main() {
     await check(options);
     return;
   }
+  if (options.command === "versions") {
+    await versionsCommand(options);
+    return;
+  }
+  if (options.command === "restore") {
+    await restoreVersion(options);
+    return;
+  }
   if (options.command === "launch") {
     await launch(options);
     return;
@@ -176,6 +192,10 @@ export async function main() {
     await thumbnailCommand(options);
     return;
   }
+  if (options.command === "doctor") {
+    await doctorCommand(options);
+    return;
+  }
 
   printHelp();
 }
@@ -250,6 +270,11 @@ export async function selectProject(options) {
 }
 
 export async function pull(options) {
+  if (options.versionProvided && !(options.pullVersion > 0)) {
+    throw new Error(
+      "Pass a save number: `lumine pull --version <n>` (run `lumine versions` to see save numbers).",
+    );
+  }
   const auth = await resolveAuth(options);
   const localProject = await findLocalProjectMetadata(
     path.resolve(options.dir || process.cwd()),
@@ -264,6 +289,10 @@ export async function pull(options) {
     auth,
     buildId: requestedBuildId,
   });
+  if (options.pullVersion > 0) {
+    await pullVersionBuildFiles({ options, auth, build: selectedBuild });
+    return;
+  }
   if (options.pullMain) {
     await pullMainBuildFiles({ options, auth, build: selectedBuild });
     return;
@@ -681,6 +710,18 @@ export function shouldUseContributionBranch(build) {
   );
 }
 
+// A canonical team build the viewer contributes to: plain pull/restore would
+// switch to their contribution branch, so version-history follow-up commands
+// for THIS build's history need --main. An owner's canonical build is their
+// editable workspace and never needs it.
+export function isCollaboratorMainBuild(build) {
+  return (
+    build?.role === "collaborator" &&
+    build.canWrite !== true &&
+    !Number(build?.contributionRootBuildId || 0)
+  );
+}
+
 export async function ensureDefaultContributionBranch({ options, auth, build }) {
   const rootBuildId =
     Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
@@ -919,6 +960,269 @@ export async function pullMainBuildFiles({ options, auth, build }) {
   );
 }
 
+// Read-only checkout of ONE previous save (`lumine pull --version <n>`).
+// Without --main it targets the build the workspace edits (your branch on team
+// projects); with --main it targets the team project's main history.
+export async function pullVersionBuildFiles({ options, auth, build }) {
+  const versionNumber = options.pullVersion;
+  let targetBuild = build;
+  if (options.pullMain) {
+    const rootBuildId =
+      Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
+    targetBuild =
+      rootBuildId === Number(build?.id || 0)
+        ? build
+        : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
+  } else {
+    targetBuild = await resolveEditableWorkspaceBuild({
+      options,
+      auth,
+      build,
+    });
+  }
+  const buildId = Number(targetBuild?.id || 0);
+  const result = await loadBuildVersionFiles({
+    options,
+    auth,
+    buildId,
+    versionNumber,
+  });
+  const resolvedBuild = result.build || targetBuild;
+  const version = result.version || { version: versionNumber };
+  const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
+  // Same nesting rules as a main checkout: never create a version checkout
+  // inside another Lumine workspace; re-pulling the same checkout refreshes it
+  // in place.
+  const enclosing = options.dir
+    ? null
+    : await findLocalProjectMetadata(process.cwd());
+  const enclosingIsThisCheckout =
+    enclosing?.metadata?.versionCheckout === true &&
+    Number(enclosing.metadata.buildId || 0) === buildId &&
+    Number(enclosing.metadata.checkoutVersion || 0) ===
+      Number(version.version || 0);
+  const dirName = defaultVersionCheckoutDir(resolvedBuild, version.version);
+  const dir = path.resolve(
+    options.dir ||
+      (enclosingIsThisCheckout
+        ? enclosing.rootDir
+        : enclosing
+          ? path.join(path.dirname(enclosing.rootDir), dirName)
+          : dirName),
+  );
+  await writeProjectFiles({ dir, files });
+  if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
+    await removeLocalProjectFilesNotIn({ dir, files });
+  }
+  await writeInstructionFiles({
+    dir,
+    marker: LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
+    content: LUMINE_VERSION_CHECKOUT_INSTRUCTIONS,
+  });
+  await writeSdkReference({ dir });
+  await writeVersionCheckoutMetadata({
+    dir,
+    options,
+    build: resolvedBuild,
+    manifest: result.projectManifest || null,
+    version,
+    pulledAt: new Date().toISOString(),
+  });
+  const summaryText = version.summary ? ` — "${version.summary}"` : "";
+  console.log(
+    `Pulled save v${version.version} of ${formatBuildTitle(resolvedBuild)} (read-only)${summaryText}`,
+  );
+  console.log(
+    `Pulled ${files.length} file${files.length === 1 ? "" : "s"} to ${dir}`,
+  );
+  console.log(
+    isCollaboratorMainBuild(resolvedBuild)
+      ? `Restore it with \`lumine restore ${version.version} --main\` from your branch workspace, then \`lumine save\`.`
+      : `Restore it with \`lumine restore ${version.version}\` from Build ${buildId}'s editable workspace, then \`lumine save\`.`,
+  );
+}
+
+// List a build's previous saves (every workspace/CLI save creates one).
+// Targets the SAME build `lumine pull --version <n>` would snapshot, so the
+// listed numbers and the printed follow-up commands always agree: without
+// --main that's the editable workspace build (a collaborator's branch on team
+// projects), with --main the team project's main.
+export async function versionsCommand(options) {
+  const auth = await resolveAuth(options);
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  const requestedBuildId = options.buildIdFlag
+    ? resolveRequiredBuildId(options.buildIdFlag)
+    : await resolveRequiredBuildIdOrSelected(options, auth, { localProject });
+  const requestedBuild = await loadBuildMetadata({
+    options,
+    auth,
+    buildId: requestedBuildId,
+  });
+  // Standing in a read-only checkout (pull --main / pull --version), the
+  // resolved id IS the build being looked at — don't bounce it to the
+  // viewer's contribution branch.
+  const resolvedFromReadOnlyCheckout =
+    !options.buildIdFlag &&
+    !(resolveBuildReference(options.target).buildId > 0) &&
+    (localProject?.metadata?.mainCheckout === true ||
+      localProject?.metadata?.versionCheckout === true);
+  let buildId = requestedBuildId;
+  if (options.pullMain) {
+    buildId =
+      Number(requestedBuild?.contributionRootBuildId || 0) || requestedBuildId;
+  } else if (!resolvedFromReadOnlyCheckout) {
+    const editableBuild = await resolveEditableWorkspaceBuild({
+      options,
+      auth,
+      build: requestedBuild,
+    });
+    buildId = Number(editableBuild?.id || 0) || requestedBuildId;
+  }
+  const result = await loadBuildVersions({
+    options,
+    auth,
+    buildId,
+    limit: options.limit,
+  });
+  printVersionList({ result });
+}
+
+export function printVersionList({ result }) {
+  const build = result.build || {};
+  const versions = Array.isArray(result.versions) ? result.versions : [];
+  if (!versions.length) {
+    console.log(`No previous saves found for ${formatBuildTitle(build)}.`);
+    return;
+  }
+  console.log(
+    `Previous saves for ${formatBuildTitle(build)} (newest first):`,
+  );
+  for (const version of versions) {
+    const author =
+      version.createdByUsername ||
+      (version.createdByRole === "assistant" ? "Lumine" : null) ||
+      version.createdByRole ||
+      "unknown";
+    const fileText =
+      Number(version.fileCount || 0) > 0
+        ? `${version.fileCount} file${Number(version.fileCount) === 1 ? "" : "s"}`
+        : "single-file save";
+    const summaryText = version.summary ? ` — ${version.summary}` : "";
+    console.log(
+      `  v${version.version}  ${formatVersionTimestamp(version.createdAt)}  by ${author}  (${fileText})${summaryText}`,
+    );
+  }
+  // The follow-up commands must hit exactly the history that was just listed,
+  // regardless of where the user runs them or which flags produced this list.
+  // Embedding the listed build id makes pull workspace-independent; --main is
+  // needed only when the listed build is a canonical team build the viewer
+  // contributes to (plain pull/restore would switch to their branch — mirrors
+  // shouldUseContributionBranch). An owner's canonical build never needs
+  // --main: it IS their editable workspace.
+  const listedBuildId = Number(build.id || 0);
+  const collaboratorMain = isCollaboratorMainBuild(build);
+  const pullTarget = listedBuildId ? ` ${listedBuildId}` : "";
+  console.log(
+    `View one read-only: lumine pull${pullTarget} --version <n>${collaboratorMain ? " --main" : ""}`,
+  );
+  console.log(
+    collaboratorMain
+      ? `Bring one back: lumine restore <n> --main (run from your branch workspace; then lumine save)`
+      : `Bring one back: lumine restore <n> (run from ${listedBuildId ? `Build ${listedBuildId}'s` : "the build's"} editable workspace; then lumine save)`,
+  );
+}
+
+function formatVersionTimestamp(seconds) {
+  const timestamp = Number(seconds || 0);
+  if (!timestamp) return "unknown time";
+  const date = new Date(timestamp * 1000);
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+// Write a previous save's files into the CURRENT editable workspace. Local
+// only on purpose: the user reviews the result and `lumine save` makes it a
+// new version (nothing on the server is rewritten in place). With --main in a
+// branch workspace, the save is read from the team project's MAIN history —
+// the recovery path when work was lost on main itself.
+export async function restoreVersion(options) {
+  // Same strictness as `pull --version`: only a plain positive integer may
+  // reach the workspace-overwriting path below. "2.5" must error, not
+  // silently restore v2.
+  const rawInput = String(options.positional[0] ?? "").trim();
+  let versionNumber = 0;
+  if (rawInput) {
+    if (!/^\d+$/.test(rawInput)) {
+      throw new Error(
+        "Pass a plain save number, e.g. `lumine restore 41` (see `lumine versions`).",
+      );
+    }
+    versionNumber = parseInt(rawInput, 10);
+  } else if (options.pullVersion > 0) {
+    // --version <n>, already strict-parsed by parseArgs.
+    versionNumber = options.pullVersion;
+  } else if (options.versionProvided) {
+    throw new Error(
+      "Pass a plain save number, e.g. `lumine restore 41` (see `lumine versions`).",
+    );
+  }
+  if (!(versionNumber > 0)) {
+    throw new Error(
+      "Pass the save number to restore, e.g. `lumine restore 41` (see `lumine versions`).",
+    );
+  }
+  const auth = await resolveAuth(options);
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  if (!Number(localProject?.metadata?.buildId || 0)) {
+    throw new Error(
+      "Run `lumine restore` inside a pulled Lumine workspace (or pass --dir <workspace>).",
+    );
+  }
+  assertLocalProjectCanBeSaved(localProject);
+  const workspaceBuildId = Number(localProject.metadata.buildId);
+  let sourceBuildId = workspaceBuildId;
+  if (options.pullMain) {
+    const rootBuildId = Number(
+      localProject.metadata.build?.contributionRootBuildId || 0,
+    );
+    if (!rootBuildId) {
+      throw new Error(
+        "--main restores from the team project's main history, which needs a contribution-branch workspace.",
+      );
+    }
+    sourceBuildId = rootBuildId;
+  }
+  const result = await loadBuildVersionFiles({
+    options,
+    auth,
+    buildId: sourceBuildId,
+    versionNumber,
+  });
+  const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
+  if (!files.length) {
+    throw new Error(`Save v${versionNumber} has no files to restore.`);
+  }
+  const dir = resolveProjectDirForSave({ options, localProject });
+  await writeProjectFiles({ dir, files });
+  if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
+    await removeLocalProjectFilesNotIn({ dir, files });
+  }
+  const version = result.version || { version: versionNumber };
+  const sourceBuild = result.build || { id: sourceBuildId };
+  const summaryText = version.summary ? ` ("${version.summary}")` : "";
+  console.log(
+    `Restored ${files.length} file${files.length === 1 ? "" : "s"} from ${formatBuildTitle(sourceBuild)} save v${version.version}${summaryText} into ${dir}`,
+  );
+  console.log("Local only so far — review the files, then run:");
+  console.log(
+    `  lumine save --summary ${shellQuote(`Restore from ${options.pullMain ? "main " : ""}v${version.version}`)}`,
+  );
+}
+
 export function printBuildList(builds) {
   if (!builds.length) {
     console.log("No owned or team Twinkle builds found.");
@@ -1202,6 +1506,9 @@ export function parseArgs(args) {
     "allowWrite",
     "main",
     "yes",
+    "json",
+    "keepAssets",
+    "noBrowser",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -1270,6 +1577,11 @@ export function parseArgs(args) {
     siteUrl: trimTrailingSlash(
       String(raw.siteUrl || process.env.TWINKLE_SITE_URL || DEFAULT_SITE_URL),
     ),
+    previewUrl: normalizePreviewUrl(
+      raw.previewUrl ||
+        process.env.TWINKLE_PREVIEW_URL ||
+        process.env.TWINKLE_BUILD_PREVIEW_URL,
+    ),
     npmRegistryUrl: trimTrailingSlash(
       String(
         raw.npmRegistryUrl ||
@@ -1286,6 +1598,14 @@ export function parseArgs(args) {
     clientName: String(raw.clientName || "Lumine CLI").slice(0, 120),
     dir: raw.dir ? String(raw.dir) : "",
     pullMain: parseBoolean(raw.main, false),
+    // Strict: only a plain positive integer counts. Anything else (missing
+    // value, "foo", a swallowed flag like "--main", "2.5") stays 0 and the
+    // consuming command must reject it via versionProvided instead of
+    // silently falling back to a live pull.
+    versionProvided: Object.prototype.hasOwnProperty.call(raw, "version"),
+    pullVersion: /^\d+$/.test(String(raw.version ?? "").trim())
+      ? parseInt(String(raw.version).trim(), 10)
+      : 0,
     summary: raw.summary ? String(raw.summary) : "",
     publish: parseBoolean(raw.publish, false),
     saveFirst: parseBoolean(raw.save, false),
@@ -1300,6 +1620,9 @@ export function parseArgs(args) {
     openBrowser: parseBoolean(raw.noOpen, false)
       ? false
       : parseBoolean(raw.open, true),
+    json: parseBoolean(raw.json, false),
+    keepAssets: parseBoolean(raw.keepAssets, false),
+    noBrowser: parseBoolean(raw.noBrowser, false),
     updateCheck: parseBoolean(raw.noUpdateCheck, false) ? false : true,
     timeoutMs: Math.max(
       Number(raw.timeoutMs || process.env.TWINKLE_TIMEOUT_MS) ||
@@ -1344,6 +1667,22 @@ export async function resolveRequiredBuildIdOrSelected(
     }
     if (mainBuildId > 0) return mainBuildId;
   }
+  // Same deal for a `pull --version <n>` checkout: read-only commands resolve
+  // the build it snapshots; mutating commands are pointed back at the
+  // editable workspace.
+  if (resolvedLocalProject?.metadata?.versionCheckout === true) {
+    const checkoutBuildId =
+      Number(resolvedLocalProject.metadata.buildId || 0) ||
+      Number(resolvedLocalProject.metadata.build?.id || 0);
+    const checkoutVersion =
+      Number(resolvedLocalProject.metadata.checkoutVersion || 0) || 0;
+    if (!MAIN_CHECKOUT_READONLY_COMMANDS.has(options.command)) {
+      throw new Error(
+        `This is a read-only checkout of a previous save${checkoutVersion ? ` (v${checkoutVersion})` : ""}${checkoutBuildId ? ` for Build ${checkoutBuildId}` : ""}; \`lumine ${options.command}\` isn't available here. Run it from the editable workspace, or pass an explicit Build URL.`,
+      );
+    }
+    if (checkoutBuildId > 0) return checkoutBuildId;
+  }
   if (
     resolvedLocalProject?.metadata &&
     isReadOnlyReferenceMetadata(resolvedLocalProject.metadata)
@@ -1433,6 +1772,9 @@ export function printHelp() {
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
   lumine pull [twinkle-build-url] --main
+  lumine pull [twinkle-build-url] --version <n> [--main]
+  lumine versions [twinkle-build-url] [--main] [--limit <n>]
+  lumine restore <n> [--main]
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
   lumine diff <twinkle-branch-url>
@@ -1452,6 +1794,7 @@ export function printHelp() {
   lumine thumbnail set <file>
   lumine thumbnail capture [--out <file>]
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
+  lumine doctor runtime-assets
 
 Examples:
   npx @stage5/lumine@latest
@@ -1464,6 +1807,9 @@ Examples:
   npx @stage5/lumine@latest diff https://www.twin-kle.com/build/884/4
   npx @stage5/lumine@latest merge https://www.twin-kle.com/build/884/4
   npx @stage5/lumine@latest pull 884 --main
+  npx @stage5/lumine@latest versions --main
+  npx @stage5/lumine@latest pull --version 41 --main
+  npx @stage5/lumine@latest restore 41 --main
   npx @stage5/lumine@latest update-from-main
   npx @stage5/lumine@latest pull
   npx @stage5/lumine@latest save
@@ -1479,14 +1825,17 @@ Examples:
   npx @stage5/lumine@latest thumbnail set art/cover.png
   npx @stage5/lumine@latest thumbnail capture --out capture.png
   npx @stage5/lumine@latest thumbnail generate --model gpt-image-2 --yes
+  npx @stage5/lumine@latest doctor runtime-assets --build 917 --json
 
 Options:
   --api-url <url>       Twinkle API origin
   --site-url <url>      Twinkle website origin
+  --preview-url <url>   Twinkle Build preview origin
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
-  --main                With pull: read-only checkout of the team project's main
+  --main                With pull/versions/restore: target the team project's main
+  --version <n>         With pull: read-only checkout of previous save v<n>
   --title <text>        New Build title
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt
@@ -1503,6 +1852,9 @@ Options:
   --allow-write         Permit sdk methods that mutate app data
   --path <api/...>      Call an sdk endpoint not in the curated list
   --scopes <a,b>        Override requested build API token scopes
+  --json                Print machine-readable output for doctor commands
+  --keep-assets         Keep doctor probe assets instead of deleting them
+  --no-browser          Skip doctor browser probes
   --model <model>       Image model for generate: gpt-image-2 or nano-banana (required, no default)
   --quality <q>         gpt-image-2 quality: low, medium, high (default high)
   --name <fileName>     File name hint for a generated asset

package/lib/constants.js

@@ -88,6 +88,8 @@ export const LUMINE_REFERENCE_INSTRUCTIONS_MARKER =
   "<!-- Lumine CLI Reference Instructions -->";
 export const LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER =
   "<!-- Lumine CLI Main Checkout Instructions -->";
+export const LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER =
+  "<!-- Lumine CLI Version Checkout Instructions -->";
 export const BUNDLED_SDK_REFERENCE_URL = new URL(
   "../sdk/BUILD_SDK_INDEX.md",
   import.meta.url,
@@ -139,6 +141,12 @@ lumine save --summary "Describe the change"
 \`\`\`
 
 - Run lumine check before launch when possible.
+- \`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
+  for inspection; \`lumine restore <n>\` writes that save's files into THIS
+  workspace (local only — review, then lumine save). Use these to recover work
+  lost to a bad edit, merge, or overwrite instead of rebuilding it from memory.
 - Use \`lumine sdk call <namespace.method> '{...}'\` to inspect real endpoint
   data and measure latency (add --repeat <n>); \`lumine sdk list\` shows
   callable methods. It prints the raw HTTP endpoint response, which can differ
@@ -206,6 +214,7 @@ lumine save --summary "Describe the change"
 
 - Use local project files with relative or root-local imports only. Do not add package imports, CDN scripts, external network calls, or app-local /api/* routes.
 - Build apps run in sandboxed iframes without allow-forms. Do not use <form> elements, native form submission, requestSubmit(), or browser form navigation. Build input flows with JavaScript-handled inputs and buttons instead.
+- Interface text must not be selectable on touch devices: long-pressing UI on mobile must not highlight it. Apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls). Keep text inputs and genuinely user-copyable content (story text, chat messages, user-written text) selectable. lumine check flags projects whose reachable files have clickable UI but no user-select: none rule.
 - CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) or game-y words in visible text switch the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 - For Three.js, use import * as THREE from '/build/vendor/three/0.184.0/three.module.min.js';. Addons (OrbitControls, GLTFLoader, ...) live under /build/vendor/three/0.184.0/addons/, e.g. import { OrbitControls } from '/build/vendor/three/0.184.0/addons/controls/OrbitControls.js';. Builds saved with the older /build/vendor/three/0.160.0/ path keep working.
@@ -240,6 +249,22 @@ the workspace to save.
 - To start from this Build, run lumine fork with the source build id and edit the forked workspace.
 - Do not edit another local checkout to bypass reference read-only semantics.
 `;
+export const LUMINE_VERSION_CHECKOUT_INSTRUCTIONS = `${LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER}
+# Lumine Version Checkout (Read-Only)
+
+This directory is a read-only snapshot of ONE PREVIOUS SAVE of a Twinkle Build,
+pulled with \`lumine pull --version <n>\`. Use it to inspect or diff what the
+project looked like at that save; it is not the workspace to edit or save.
+
+## Source Of Truth
+
+- Read .twinkle/lumine-project.json before using these files.
+- metadata.versionCheckout is true here: do not run lumine save from this directory.
+- To bring this save's files back into the live project, run \`lumine restore
+  <n>\` from the editable workspace (then \`lumine save\`), or copy the specific
+  parts you need into that workspace.
+- Do not edit another local checkout to bypass read-only semantics.
+`;
 export const LUMINE_MAIN_CHECKOUT_INSTRUCTIONS = `${LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER}
 # Lumine Main Checkout (Read-Only)
 
@@ -268,6 +293,8 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   // assets never touch main's project files (uploads go to the current
   // user's own asset space), so listing/uploading from a main checkout is safe.
   "assets",
+  // versions only reads save history.
+  "versions",
 ]);
 export const COMMANDS = new Set([
   "workspace",
@@ -289,8 +316,11 @@ export const COMMANDS = new Set([
   "push",
   "check",
   "launch",
+  "versions",
+  "restore",
   "sdk",
   "assets",
   "thumbnail",
+  "doctor",
   "help",
 ]);