@stage5/lumine 0.2.6 → 0.2.8

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.8",
   "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
+Version: 1.26.3
+Updated: 2026-07-08
+Generated: 2026-07-08T09:25:17.959Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -21,12 +21,28 @@ 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.
+- Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.
 
 ## 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
 
 ## Namespaces
 
+### Twinkle
+- isAudioMuted() | scopes: none
+  - Returns: boolean
+  - Returns whether the host runtime currently has this Build app tab muted.
+  - The host automatically mutes standard <audio>/<video> elements and Web Audio nodes connected to AudioContext.destination.
+  - Use this only when your app manages audio outside those standard paths.
+  - Example: if (Twinkle.isAudioMuted()) pauseCustomMixerOutput();
+- onAudioMuteChange(listener, options?) | scopes: none
+  - Returns: unsubscribe function
+  - Subscribe to host tab mute changes for custom audio engines.
+  - The listener receives the current muted boolean immediately by default.
+  - Pass { immediate: false } to skip the initial callback.
+  - Example: const unsubscribe = Twinkle.onAudioMuteChange((muted) => customMixer.setMuted(muted));
+
 ### Twinkle.capabilities
 - async get() | scopes: none
   - Returns: Capability snapshot
@@ -49,6 +65,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 }