@stage5/lumine 0.2.5 → 0.2.7

package/lib/thumbnail.js

@@ -0,0 +1,330 @@
+import fs from "fs/promises";
+import path from "path";
+
+import {
+  ASSET_GENERATE_TIMEOUT_MS,
+  THUMBNAIL_CAPTURE_TIMEOUT_MS,
+  THUMBNAIL_CONTENT_TYPE_BY_EXTENSION,
+  THUMBNAIL_MAX_FILE_SIZE_BYTES,
+} from "./constants.js";
+import {
+  captureBuildThumbnailPreview,
+  generateBuildThumbnailRequest,
+  loadBuildFiles,
+  mintBuildApiToken,
+  requestThumbnailSignedUpload,
+  updateBuildThumbnailUrl,
+} from "./api.js";
+import { assertAuthScope, ensureAuth } from "./auth.js";
+import { resolveSdkBuildId } from "./sdk.js";
+import {
+  confirmPrompt,
+  describeGenerateHttpError,
+  formatBatteryPercent,
+  putAssetPartWithRetry,
+  resolveGenerateModel,
+} from "./assets.js";
+import { formatBytes } from "./util.js";
+import { findLocalProjectMetadata } from "./workspace.js";
+
+export async function thumbnailCommand(options) {
+  const subcommand = String(options.positional[0] || "");
+  if (subcommand === "set") {
+    await thumbnailSet(options);
+    return;
+  }
+  if (subcommand === "capture") {
+    await thumbnailCapture(options);
+    return;
+  }
+  if (subcommand === "generate") {
+    await thumbnailGenerate(options);
+    return;
+  }
+  throw new Error(
+    'Usage: lumine thumbnail set <file> | lumine thumbnail capture [--out <file>] | lumine thumbnail generate "<prompt>" --model <gpt-image-2|nano-banana>',
+  );
+}
+
+async function refuseMainCheckout(options) {
+  const local = await findLocalProjectMetadata(
+    options.dir ? path.resolve(options.dir) : process.cwd(),
+  );
+  if (local?.metadata?.mainCheckout === true && !options.buildIdFlag) {
+    throw new Error(
+      "This is a read-only main checkout. Set the thumbnail from your contribution-branch workspace (or pass --build for a build you own).",
+    );
+  }
+}
+
+async function resolveThumbnailContext(options) {
+  await refuseMainCheckout(options);
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const metadata = await loadBuildFiles({
+    options,
+    auth,
+    buildId,
+    includeContent: false,
+  });
+  const build = metadata?.build || {};
+  if (build.canWrite === false) {
+    throw new Error(
+      `You cannot write to Build #${buildId}. Thumbnails can only be set on builds/branches you can save.`,
+    );
+  }
+  return { buildId, auth, build };
+}
+
+async function confirmThumbnailOverwrite({ options, build, buildId }) {
+  if (options.assumeYes) return true;
+  if (!String(build?.thumbnailUrl || "").trim()) return true;
+  const confirmed = await confirmPrompt(
+    `Build #${buildId} already has a thumbnail. Replace it? [y/N] `,
+  );
+  if (confirmed === null) {
+    console.log("Not a TTY — re-run with --yes to replace the thumbnail.");
+    return false;
+  }
+  if (!confirmed) {
+    console.log("Aborted. Thumbnail unchanged.");
+    return false;
+  }
+  return true;
+}
+
+export async function commitThumbnailImage({
+  options,
+  auth,
+  buildId,
+  buffer,
+  contentType,
+}) {
+  const { signedRequest, thumbnailUrl } = await requestThumbnailSignedUpload({
+    options,
+    auth,
+    buildId,
+    fileSize: buffer.length,
+    contentType,
+  });
+  if (!signedRequest || !thumbnailUrl) {
+    throw new Error("The server did not return a thumbnail upload URL.");
+  }
+  await putAssetPartWithRetry({
+    url: signedRequest,
+    chunk: buffer,
+    mimeType: contentType,
+    partLabel: "thumbnail",
+  });
+  const result = await updateBuildThumbnailUrl({
+    options,
+    auth,
+    buildId,
+    thumbnailUrl,
+  });
+  if (result?.success !== true) {
+    throw new Error(result?.error || "Failed to save the thumbnail.");
+  }
+  return { thumbnailUrl, build: result.build || null };
+}
+
+export async function thumbnailSet(options) {
+  const filePath = String(options.positional[1] || "").trim();
+  if (!filePath) {
+    throw new Error("Usage: lumine thumbnail set <file> (jpg, png, or webp)");
+  }
+  const absolutePath = path.resolve(filePath);
+  const extension = path.extname(absolutePath).toLowerCase();
+  const contentType = THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[extension];
+  if (!contentType) {
+    throw new Error(
+      `Unsupported thumbnail type for ${path.basename(absolutePath)}. Thumbnails support ${Object.keys(THUMBNAIL_CONTENT_TYPE_BY_EXTENSION).join(", ")}.`,
+    );
+  }
+  let buffer;
+  try {
+    buffer = await fs.readFile(absolutePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Thumbnail file does not exist: ${filePath}`);
+    }
+    throw error;
+  }
+  if (!buffer.length) {
+    throw new Error(`Thumbnail file is empty: ${filePath}`);
+  }
+  if (buffer.length > THUMBNAIL_MAX_FILE_SIZE_BYTES) {
+    throw new Error(
+      `Thumbnail file is too big (${formatBytes(buffer.length)}; max ${formatBytes(THUMBNAIL_MAX_FILE_SIZE_BYTES)}).`,
+    );
+  }
+
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
+  if (!proceed) return;
+
+  const { thumbnailUrl } = await commitThumbnailImage({
+    options,
+    auth,
+    buildId,
+    buffer,
+    contentType,
+  });
+  console.log(`Thumbnail set for Build #${buildId}:`);
+  console.log(`  ${thumbnailUrl}`);
+  console.log("Tip: thumbnails display ~16:9; the image was uploaded uncropped.");
+}
+
+function decodeImageDataUrl(dataUrl) {
+  const match = String(dataUrl || "").match(
+    /^data:(image\/[a-z+.-]+);base64,(.+)$/i,
+  );
+  if (!match) return null;
+  return {
+    contentType: match[1].toLowerCase(),
+    buffer: Buffer.from(match[2], "base64"),
+  };
+}
+
+export async function thumbnailCapture(options) {
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
+  if (!proceed) return;
+
+  const { token: previewToken } = await mintBuildApiToken({
+    options,
+    auth,
+    buildId,
+    scopes: ["preview:read"],
+  });
+  const previewPath = `/build/preview/build/${buildId}/current?rev=${Number(build.updatedAt || 0)}&buildApiToken=${encodeURIComponent(previewToken)}`;
+
+  console.log("Capturing the app preview server-side... this can take ~30s.");
+  const captureResult = await captureBuildThumbnailPreview({
+    options,
+    auth,
+    buildId,
+    previewPath,
+    timeoutMs: THUMBNAIL_CAPTURE_TIMEOUT_MS,
+  });
+  const decoded = decodeImageDataUrl(captureResult?.imageUrl);
+  if (!decoded) {
+    throw new Error(
+      captureResult?.error || "Preview capture returned no image.",
+    );
+  }
+  if (decoded.buffer.length > THUMBNAIL_MAX_FILE_SIZE_BYTES) {
+    throw new Error("Captured image exceeds the 8MB thumbnail limit.");
+  }
+  if (options.out) {
+    const outPath = path.resolve(String(options.out));
+    await fs.writeFile(outPath, decoded.buffer);
+    console.log(`Saved capture to ${outPath}`);
+  }
+  const normalizedContentType = THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[
+    `.${decoded.contentType.split("/")[1] || "png"}`
+  ]
+    ? decoded.contentType
+    : "image/png";
+  const { thumbnailUrl } = await commitThumbnailImage({
+    options,
+    auth,
+    buildId,
+    buffer: decoded.buffer,
+    contentType: normalizedContentType,
+  });
+  console.log(`Thumbnail captured and set for Build #${buildId}:`);
+  console.log(`  ${thumbnailUrl}`);
+}
+
+export async function thumbnailGenerate(options) {
+  const prompt = String(options.positional[1] || "").trim();
+  const { model, quality } = resolveGenerateModel(options);
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+
+  const requestBody = {
+    model,
+    ...(quality ? { quality } : {}),
+    ...(prompt ? { prompt } : {}),
+  };
+
+  if (!options.assumeYes) {
+    let estimate = null;
+    try {
+      const estimateResult = await generateBuildThumbnailRequest({
+        options,
+        auth,
+        buildId,
+        body: { ...requestBody, estimateOnly: true },
+      });
+      estimate = estimateResult?.estimate || null;
+    } catch (error) {
+      const friendly = describeGenerateHttpError(error);
+      if (friendly) throw new Error(friendly);
+      throw error;
+    }
+    const selectedOption = (estimate?.options || []).find(
+      (option) => option.model === model,
+    );
+    console.log(
+      `Generate a thumbnail with ${model}${quality ? ` (quality ${quality})` : ""}${prompt ? "" : " (prompt auto-composed from the build title/description)"}?`,
+    );
+    if (String(build?.thumbnailUrl || "").trim()) {
+      console.log("  This will REPLACE the existing thumbnail.");
+    }
+    if (selectedOption) {
+      console.log(
+        `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`,
+      );
+    }
+    if (estimate) {
+      console.log(
+        `  Battery remaining now:  ${formatBatteryPercent(estimate.energyRemaining, estimate.fullBatteryUnits)}`,
+      );
+    }
+    const confirmed = await confirmPrompt("Proceed? [y/N] ");
+    if (confirmed === null) {
+      console.log("Not a TTY — re-run with --yes to generate.");
+      return;
+    }
+    if (!confirmed) {
+      console.log("Aborted. Nothing generated.");
+      return;
+    }
+  }
+
+  console.log("Generating the thumbnail... this can take a minute.");
+  let result;
+  try {
+    result = await generateBuildThumbnailRequest({
+      options,
+      auth,
+      buildId,
+      body: requestBody,
+      timeoutMs: ASSET_GENERATE_TIMEOUT_MS,
+    });
+  } catch (error) {
+    const friendly = describeGenerateHttpError(error);
+    if (friendly) throw new Error(friendly);
+    throw error;
+  }
+  if (result?.success !== true || !result?.thumbnailUrl) {
+    throw new Error(result?.error || "Thumbnail generation failed.");
+  }
+  console.log(`Thumbnail generated and set for Build #${buildId}:`);
+  console.log(`  ${result.thumbnailUrl}`);
+  if (result?.asset?.url) {
+    console.log(
+      `The generated image is also stored as reusable asset #${result.asset.id}:`,
+    );
+    console.log(`  ${result.asset.url}`);
+  }
+  const remaining = result?.aiUsagePolicy?.energyRemaining;
+  if (Number.isFinite(Number(remaining))) {
+    console.log(
+      `Battery remaining: ${formatBatteryPercent(Number(remaining), result?.aiUsagePolicy?.fullBatteryUnits)}`,
+    );
+  }
+}

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.5",
+  "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 }