@stage5/lumine 0.2.6 → 0.2.7

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,
@@ -53,10 +57,12 @@ import { sdkCommand } from "./sdk.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
+  defaultVersionCheckoutDir,
   defaultWorkspaceDir,
   parseBoolean,
   resolveBuildId,
   resolveBuildReference,
+  resolveRequiredBuildId,
   shellQuote,
   toCamelCase,
   trimTrailingSlash,
@@ -75,6 +81,7 @@ import {
   writeInstructionFiles,
   writeMainCheckoutMetadata,
   writeProjectFiles,
+  writeVersionCheckoutMetadata,
   writeProjectMetadata,
   writeReferenceInstructions,
   writeReferenceMetadata,
@@ -160,6 +167,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;
@@ -250,6 +265,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 +284,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 +705,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 +955,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.");
@@ -1286,6 +1585,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),
@@ -1344,6 +1651,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 +1756,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>
@@ -1464,6 +1790,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
@@ -1486,7 +1815,8 @@ Options:
   --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

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,6 +316,8 @@ export const COMMANDS = new Set([
   "push",
   "check",
   "launch",
+  "versions",
+  "restore",
   "sdk",
   "assets",
   "thumbnail",

package/lib/util.js

@@ -86,6 +86,13 @@ export function defaultMainCheckoutDir(build) {
   return `twinkle-main-${titleSlug || "build"}-${buildId}`;
 }
 
+export function defaultVersionCheckoutDir(build, versionNumber) {
+  const titleSlug = slugify(build?.title || "");
+  const buildId = Number(build?.id || 0) || "build";
+  const version = Number(versionNumber || 0) || "version";
+  return `twinkle-v${version}-${titleSlug || "build"}-${buildId}`;
+}
+
 export function resolveRequiredBuildId(value) {
   const buildId = resolveBuildReference(value).buildId;
   if (buildId > 0) return buildId;

package/lib/workspace.js

@@ -491,6 +491,54 @@ export async function writeMainCheckoutMetadata({
   );
 }
 
+// Metadata for a read-only `pull --version <n>` checkout of one previous save:
+// versionCheckout marks it so save can point back at the restore flow.
+export async function writeVersionCheckoutMetadata({
+  dir,
+  options,
+  build,
+  manifest,
+  version,
+  pulledAt,
+}) {
+  const metadataDir = path.join(dir, PROJECT_METADATA_DIR);
+  await fs.mkdir(metadataDir, { recursive: true });
+  const buildId = Number(build?.id || 0) || null;
+  await fs.writeFile(
+    path.join(metadataDir, PROJECT_METADATA_FILE),
+    JSON.stringify(
+      {
+        schemaVersion: 1,
+        buildId,
+        readOnly: true,
+        versionCheckout: true,
+        checkoutVersion: Number(version?.version || 0) || null,
+        checkoutVersionSummary: version?.summary || null,
+        checkoutVersionCreatedAt: Number(version?.createdAt || 0) || null,
+        build: {
+          id: buildId,
+          title: build?.title || (buildId ? `Build ${buildId}` : ""),
+          role: build?.role || "collaborator",
+          ownerUsername: build?.ownerUsername || null,
+          contributionStatus: "none",
+          contributionRootBuildId:
+            Number(build?.contributionRootBuildId || 0) || null,
+          canWrite: false,
+          canPublish: false,
+        },
+        apiUrl: options.apiUrl,
+        siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
+        manifest,
+        pulledAt,
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
 export async function findLocalProjectMetadata(startDir) {
   let current = path.resolve(startDir || process.cwd());
   while (true) {
@@ -527,6 +575,14 @@ export function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only checkout of main${rootBuildId ? ` for Build ${rootBuildId}` : ""}. Make edits in your branch workspace (\`lumine pull${rootBuildId ? ` ${rootBuildId}` : ""}\`), and run \`lumine update-from-main\` there to bring main's changes into it.`,
     );
   }
+  if (metadata.versionCheckout === true) {
+    const checkoutBuildId =
+      Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
+    const checkoutVersion = Number(metadata.checkoutVersion || 0) || 0;
+    throw new Error(
+      `This is a read-only checkout of a previous save${checkoutVersion ? ` (v${checkoutVersion})` : ""}${checkoutBuildId ? ` for Build ${checkoutBuildId}` : ""}. To bring this save back, run \`lumine restore${checkoutVersion ? ` ${checkoutVersion}` : " <n>"}\` from the editable workspace, then \`lumine save\`.`,
+    );
+  }
   if (isReadOnlyReferenceMetadata(metadata)) {
     const sourceBuildId =
       Number(metadata.reference?.sourceBuildId || 0) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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.26.2
-Updated: 2026-06-09
-Generated: 2026-06-18T12:26:29.648Z
+Updated: 2026-07-05
+Generated: 2026-07-05T06:47:32.349Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -21,6 +21,7 @@ Generated: 2026-06-18T12:26:29.648Z
 - Use Twinkle.world for realtime multiplayer rooms, avatar presence, movement, emotes, and lightweight actions; world sessions are disposable and durable MMO state belongs in sharedDb/privateDb.
 - Use Twinkle.characters.chat for real Zero/Ciel NPC dialogue with shared room context and AI Energy-aware thinking modes.
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
+- Interface text must not be selectable on touch devices: apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls) so mobile long-press does not highlight UI. Keep text inputs and genuinely user-copyable content selectable.
 
 ## Token Scopes
 files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write
@@ -49,6 +50,22 @@ files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb
   - Returns: Viewer info
   - Forces a fresh fetch from the parent.
 
+### Twinkle.app
+- async getInfo() | scopes: none
+  - Returns: App info object from the parent (includes appUrl) or null
+  - Cached after the first call for the iframe session.
+- async getShareUrl(pathSegment) | scopes: none
+  - 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');
+- async navigate(target) | scopes: none
+  - Returns: { success, src }
+  - Navigate to another Build preview route through the parent bridge without dropping Twinkle SDK access.
+  - Use this for in-app Build preview/world switches instead of window.location.assign, location.replace, or setting location.href.
+  - The parent validates that the target is still a Build preview URL before navigating.
+  - External URLs are rejected and do not receive the Build bridge nonce.
+  - Example: await Twinkle.app.navigate('./arena.html');
+
 ### Twinkle.preview
 - getLayout() | scopes: none
   - Returns: { mode, viewport, stage, safeInsets, playfield }