@stage5/lumine 0.2.8 → 0.2.10

package/lib/assets.js

@@ -275,7 +275,7 @@ export async function assetsUpload(options) {
   const filePaths = options.positional.slice(1);
   if (!filePaths.length) {
     throw new Error(
-      "Usage: lumine assets upload <file...> (images and audio only)",
+      "Usage: lumine assets upload <file...> (runtime media: images, audio, GLB/self-contained glTF, KTX2, HDR, EXR, BIN, DRC)",
     );
   }
   const buildId = await resolveSdkBuildId(options);
@@ -296,39 +296,77 @@ export async function assetsUpload(options) {
   // second asset with a new URL, and the old one keeps eating quota. Project-
   // owner assets are checked too: re-uploading media the project already has
   // defeats the reuse flow.
+  const referencedGltfAssetUrls = candidates.flatMap(
+    (candidate) => candidate.referencedGltfAssetUrls || [],
+  );
+  let existingAssets = [];
+  let existingProjectAssets = [];
   try {
-    const { assets: existingAssets, projectAssets: existingProjectAssets } =
-      await fetchAllRuntimeAssets({
-        options,
-        auth,
-        buildId,
-        buildApiToken: token,
-      });
-    const nameMatches = (asset, fileName) =>
-      asset.originalFileName === fileName || asset.fileName === fileName;
-    for (const candidate of candidates) {
-      const existing = existingAssets.find((asset) =>
-        nameMatches(asset, candidate.fileName),
+    const listedAssets = await fetchAllRuntimeAssets({
+      options,
+      auth,
+      buildId,
+      buildApiToken: token,
+    });
+    existingAssets = listedAssets.assets;
+    existingProjectAssets = listedAssets.projectAssets || [];
+  } catch (error) {
+    if (referencedGltfAssetUrls.length > 0) {
+      throw new Error(
+        "Could not verify this glTF's Twinkle asset URLs. Refresh the asset list and try again.",
+        { cause: error },
       );
-      if (existing) {
-        console.error(
-          `lumine: note — an asset named "${candidate.fileName}" already exists (#${existing.id}). ` +
-            `Uploading creates a NEW asset with a new URL; if this replaces #${existing.id}, update the code and run \`lumine assets delete ${existing.id}\` (or \`lumine assets prune\`).`,
-        );
-        continue;
-      }
-      const projectExisting = (existingProjectAssets || []).find((asset) =>
-        nameMatches(asset, candidate.fileName),
+    }
+  }
+  if (referencedGltfAssetUrls.length > 0) {
+    const knownAssets = [...existingAssets, ...existingProjectAssets];
+    const unverifiedUrls = referencedGltfAssetUrls.filter(
+      (referencedUrl) =>
+        !knownAssets.some((asset) =>
+          runtimeAssetUrlMatchesGltfReference(asset, referencedUrl),
+        ),
+    );
+    if (unverifiedUrls.length > 0) {
+      throw new Error(
+        `The glTF references Twinkle asset URL${
+          unverifiedUrls.length === 1 ? "" : "s"
+        } that do not belong to this Build: ${unverifiedUrls
+          .slice(0, 3)
+          .map((url) => `"${url}"`)
+          .join(
+            ", ",
+          )}${unverifiedUrls.length > 3 ? ", ..." : ""}. Upload or reuse assets listed by \`lumine assets list\`, then use their exact URLs.`,
       );
-      if (projectExisting) {
-        console.error(
-          `lumine: note — the project owner already has an asset named "${candidate.fileName}" (#${projectExisting.id}). ` +
-            `Consider reusing its URL instead of uploading a duplicate:\n  ${projectExisting.url}`,
+    }
+  }
+  if (existingAssets.length > 0 || existingProjectAssets.length > 0) {
+    try {
+      const nameMatches = (asset, fileName) =>
+        asset.originalFileName === fileName || asset.fileName === fileName;
+      for (const candidate of candidates) {
+        const existing = existingAssets.find((asset) =>
+          nameMatches(asset, candidate.fileName),
+        );
+        if (existing) {
+          console.error(
+            `lumine: note — an asset named "${candidate.fileName}" already exists (#${existing.id}). ` +
+              `Uploading creates a NEW asset with a new URL; if this replaces #${existing.id}, update the code and run \`lumine assets delete ${existing.id}\` (or \`lumine assets prune\`).`,
+          );
+          continue;
+        }
+        const projectExisting = existingProjectAssets.find((asset) =>
+          nameMatches(asset, candidate.fileName),
         );
+        if (projectExisting) {
+          console.error(
+            `lumine: note — the project owner already has an asset named "${candidate.fileName}" (#${projectExisting.id}). ` +
+              `Consider reusing its URL instead of uploading a duplicate:\n  ${projectExisting.url}`,
+          );
+        }
       }
+    } catch {
+      // Duplicate-name warnings are advisory only.
     }
-  } catch {
-    // Advisory only — never block an upload on the pre-listing.
   }
   const uploaded = [];
   for (const candidate of candidates) {
@@ -400,9 +438,10 @@ export async function assetsDelete(options) {
 // matching workspace. An asset must be unreferenced by ALL THREE to be a
 // candidate. If the server does not provide `referencedByProject` (older API
 // deployment), prune shows the plan but refuses to delete — the published-
-// snapshot check cannot be done client-side. Structural blind spot, always
+// snapshot check cannot be done client-side. Structural blind spots, always
 // disclosed: references stored in app data (privateDb/sharedDb/viewer DB by
-// Twinkle.files-using apps) are invisible to every scan.
+// Twinkle.files-using apps), and references stored only inside uploaded asset
+// files such as .gltf manifests, are invisible to every scan.
 export async function assetsPrune(options) {
   const buildId = await resolveSdkBuildId(options);
   const auth = await ensureAuth(options);
@@ -470,7 +509,7 @@ export async function assetsPrune(options) {
     );
   }
   console.log(
-    "Caution: asset URLs stored in app data (privateDb/sharedDb/user DBs by apps using Twinkle.files) cannot be detected. If this app stores uploaded-file URLs at runtime, do not prune its assets.",
+    "Caution: asset URLs stored in app data (privateDb/sharedDb/user DBs by apps using Twinkle.files), or referenced only inside uploaded files such as .gltf manifests, cannot be detected. Keep those URLs in project files too, or do not prune this build's assets.",
   );
   if (!serverVerified) {
     console.log(
@@ -502,7 +541,9 @@ export async function assetsPrune(options) {
       body: { assetId: asset.id },
     });
     lastUsage = result?.usage || lastUsage;
-    console.log(`Deleted #${asset.id} ${asset.originalFileName || asset.fileName}`);
+    console.log(
+      `Deleted #${asset.id} ${asset.originalFileName || asset.fileName}`,
+    );
   }
   printAssetUsage(lastUsage);
   await refreshWorkspaceAssetsManifest({
@@ -528,7 +569,12 @@ export async function confirmPrompt(question) {
 // 5MB on slow links) — mirrors the web workspace uploader, plus bounded
 // retries for transient network/5xx failures. 4xx means the presigned URL
 // itself is bad; retrying cannot help.
-export async function putAssetPartWithRetry({ url, chunk, mimeType, partLabel }) {
+export async function putAssetPartWithRetry({
+  url,
+  chunk,
+  mimeType,
+  partLabel,
+}) {
   let lastError = null;
   for (let attempt = 1; attempt <= 3; attempt += 1) {
     try {
@@ -558,7 +604,7 @@ export async function readAssetUploadCandidate(filePath) {
   const mimeType = ASSET_MIME_BY_EXTENSION[extension];
   if (!mimeType) {
     throw new Error(
-      `Unsupported asset type for ${fileName}. Build assets support image and audio files (${Object.keys(ASSET_MIME_BY_EXTENSION).join(", ")}).`,
+      `Unsupported asset type for ${fileName}. Build assets support runtime media files (${Object.keys(ASSET_MIME_BY_EXTENSION).join(", ")}).`,
     );
   }
   let buffer;
@@ -573,7 +619,105 @@ export async function readAssetUploadCandidate(filePath) {
   if (!buffer.length) {
     throw new Error(`Asset file is empty: ${filePath}`);
   }
-  return { absolutePath, fileName, mimeType, buffer };
+  const referencedGltfAssetUrls =
+    extension === ".gltf"
+      ? assertGltfUploadCandidateHasOnlySupportedUris({ fileName, buffer })
+      : [];
+  return {
+    absolutePath,
+    fileName,
+    mimeType,
+    buffer,
+    referencedGltfAssetUrls,
+  };
+}
+
+const TWINKLE_GLTF_ASSET_HOSTS = new Set([
+  "d3jvoamd2k4p0s.cloudfront.net",
+  "www.twin-kle.com",
+  "twin-kle.com",
+]);
+const TWINKLE_GLTF_ASSET_PATH_PREFIXES = [
+  "/attachments/build-runtime/",
+  "/attachments/optimized/",
+];
+
+function isSupportedGltfUri(uri) {
+  const normalizedUri = String(uri || "").trim();
+  if (!normalizedUri) return true;
+  const schemeMatch = normalizedUri.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+  if (!schemeMatch) return false;
+  if (schemeMatch[1].toLowerCase() === "data") return true;
+  let parsedUri;
+  try {
+    parsedUri = new URL(normalizedUri);
+  } catch {
+    return false;
+  }
+  return (
+    parsedUri.protocol === "https:" &&
+    !parsedUri.port &&
+    !parsedUri.username &&
+    !parsedUri.password &&
+    !parsedUri.search &&
+    !parsedUri.hash &&
+    TWINKLE_GLTF_ASSET_HOSTS.has(parsedUri.hostname.toLowerCase()) &&
+    TWINKLE_GLTF_ASSET_PATH_PREFIXES.some((prefix) =>
+      parsedUri.pathname.startsWith(prefix),
+    )
+  );
+}
+
+function collectUnsupportedGltfUris(parsedGltf) {
+  const unsupportedUris = [];
+  if (!parsedGltf || typeof parsedGltf !== "object") {
+    return unsupportedUris;
+  }
+  for (const entry of [
+    ...(Array.isArray(parsedGltf.buffers) ? parsedGltf.buffers : []),
+    ...(Array.isArray(parsedGltf.images) ? parsedGltf.images : []),
+  ]) {
+    const uri = typeof entry?.uri === "string" ? entry.uri.trim() : "";
+    if (uri && !isSupportedGltfUri(uri)) {
+      unsupportedUris.push(uri);
+    }
+  }
+  return unsupportedUris;
+}
+
+function assertGltfUploadCandidateHasOnlySupportedUris({ fileName, buffer }) {
+  let parsedGltf;
+  try {
+    parsedGltf = JSON.parse(buffer.toString("utf8"));
+  } catch {
+    throw new Error(`Invalid .gltf JSON in ${fileName}.`);
+  }
+  const unsupportedUris = collectUnsupportedGltfUris(parsedGltf);
+  if (unsupportedUris.length === 0) {
+    return [
+      ...(Array.isArray(parsedGltf.buffers) ? parsedGltf.buffers : []),
+      ...(Array.isArray(parsedGltf.images) ? parsedGltf.images : []),
+    ]
+      .map((entry) => (typeof entry?.uri === "string" ? entry.uri.trim() : ""))
+      .filter((uri) => uri && !uri.toLowerCase().startsWith("data:"));
+  }
+  const sampleUris = unsupportedUris
+    .slice(0, 3)
+    .map((uri) => `"${uri}"`)
+    .join(", ");
+  throw new Error(
+    `${fileName} contains unsupported glTF URI${
+      unsupportedUris.length === 1 ? "" : "s"
+    } (${sampleUris}${unsupportedUris.length > 3 ? ", ..." : ""}). Raw .gltf companion files are stored under separate asset URLs, and Build apps cannot load arbitrary external URLs. Use .glb, embed data URIs, or rewrite .gltf URIs to Twinkle runtime attachment URLs before uploading.`,
+  );
+}
+
+function runtimeAssetUrlMatchesGltfReference(asset, referencedUrl) {
+  const normalizedReference = String(referencedUrl || "").trim();
+  if (!normalizedReference) return false;
+  return [asset?.url, asset?.thumbUrl].some(
+    (assetUrl) => String(assetUrl || "").trim() === normalizedReference,
+  );
 }
 
 export async function uploadRuntimeAsset({
@@ -607,7 +751,10 @@ export async function uploadRuntimeAsset({
     const parts = [];
     for (let partNumber = 0; partNumber < urls.length; partNumber += 1) {
       const start = partNumber * ASSET_UPLOAD_CHUNK_BYTES;
-      const end = Math.min(start + ASSET_UPLOAD_CHUNK_BYTES, candidate.buffer.length);
+      const end = Math.min(
+        start + ASSET_UPLOAD_CHUNK_BYTES,
+        candidate.buffer.length,
+      );
       const response = await putAssetPartWithRetry({
         url: urls[partNumber],
         chunk: candidate.buffer.subarray(start, end),
@@ -636,7 +783,9 @@ export async function uploadRuntimeAsset({
     });
     const asset = completed?.asset || prepared?.asset;
     if (!asset?.url) {
-      throw new Error(`Upload of ${candidate.fileName} completed without an asset URL.`);
+      throw new Error(
+        `Upload of ${candidate.fileName} completed without an asset URL.`,
+      );
     }
     return asset;
   } catch (error) {
@@ -745,7 +894,9 @@ export async function writeAssetsManifest({
   const unmatchedReferences = refs
     ? refs.filter(
         (ref) =>
-          !knownAssets.some((asset) => runtimeAssetMatchesReference(asset, ref)),
+          !knownAssets.some((asset) =>
+            runtimeAssetMatchesReference(asset, ref),
+          ),
       )
     : null;
   const metadataDir = path.join(dir, PROJECT_METADATA_DIR);
@@ -760,7 +911,9 @@ export async function writeAssetsManifest({
         fetchedAt: new Date().toISOString(),
         usage: usage || null,
         assets: annotatedAssets,
-        ...(annotatedProjectAssets ? { projectAssets: annotatedProjectAssets } : {}),
+        ...(annotatedProjectAssets
+          ? { projectAssets: annotatedProjectAssets }
+          : {}),
         ...(unmatchedReferences ? { unmatchedReferences } : {}),
       },
       null,

package/lib/constants.js

@@ -37,8 +37,9 @@ export const ASSETS_METADATA_FILE = "assets.json";
 // Must match the web workspace's 5MB part size: the server presigns one S3
 // part URL per 5MB of the declared fileSize.
 export const ASSET_UPLOAD_CHUNK_BYTES = 5 * 1024 * 1024;
-// Mirrors the web workspace's asset accept list (images + audio). The server
-// only rejects video, but the platform's asset policy is image/audio.
+// Mirrors the web workspace's runtime asset accept list. The server rejects
+// video; client allowlists keep project asset uploads focused on files loaders
+// can consume from the sandbox.
 export const ASSET_MIME_BY_EXTENSION = {
   ".png": "image/png",
   ".jpg": "image/jpeg",
@@ -60,6 +61,13 @@ export const ASSET_MIME_BY_EXTENSION = {
   ".flac": "audio/flac",
   ".aif": "audio/aiff",
   ".aiff": "audio/aiff",
+  ".glb": "model/gltf-binary",
+  ".gltf": "model/gltf+json",
+  ".ktx2": "image/ktx2",
+  ".hdr": "image/vnd.radiance",
+  ".exr": "image/x-exr",
+  ".bin": "application/octet-stream",
+  ".drc": "application/octet-stream",
 };
 // Mirrors the platform's project-file limits. File count and effective-line
 // limits are hardcoded server constants; the total-byte limit is
@@ -155,22 +163,28 @@ lumine save --summary "Describe the change"
   need --allow-write and mutate real app data.
 - Owned canonical builds may be published only when the user explicitly asks.
 
-## Assets (Images & Audio)
+## Assets (Runtime Media)
 
-- Binary files are NOT project files. Never place images or audio in this
+- Binary files are NOT project files. Never place bundled media in this
   workspace — lumine save rejects binaries. Assets live in Twinkle's asset
   storage and are referenced from code by absolute URL.
 - .twinkle/${ASSETS_METADATA_FILE} lists this build's uploaded assets (the current
   CLI user's uploads) with their URLs. Reference an asset by its \`url\` value.
-- \`lumine assets upload <file...>\` uploads images/audio from disk and prints
-  the URL to use in code. \`lumine assets list\` prints assets and refreshes
+- \`lumine assets upload <file...>\` uploads supported runtime assets (images,
+  audio, GLB/self-contained glTF models, texture maps, HDR/EXR files, and glTF
+  companion files) from disk and prints the URL to use in code. Raw .gltf files
+  with relative companion URIs must be converted to .glb or rewritten to
+  absolute uploaded asset URLs first. Reference every uploaded asset that must
+  survive pruning from project files. \`lumine assets list\`
+  prints assets and refreshes
   .twinkle/${ASSETS_METADATA_FILE}; \`lumine assets delete <assetId>\` removes one;
   \`lumine assets prune\` deletes your uploads that nothing references (server
   checks draft files, published/version snapshots, and derived builds; local
   unsaved edits are scanned too). The server enforces storage quotas.
 - CAUTION: asset URLs an app stores in privateDb/sharedDb/user DBs at runtime
-  (Twinkle.files uploads) are invisible to prune. Never run \`assets prune\` on
-  a build whose app stores uploaded-file URLs in app data.
+  (Twinkle.files uploads), or URLs referenced only inside uploaded files such as
+  .gltf manifests, are invisible to prune. Keep those asset URLs in project
+  files too, or do not run \`assets prune\` for that build.
 - On team projects the manifest also lists \`projectAssets\` (the project
   owner's uploads) and \`unmatchedReferences\` (asset URLs in code matching no
   known asset). Reuse existing asset URLs — do NOT re-upload media the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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.3
-Updated: 2026-07-08
-Generated: 2026-07-08T09:25:17.959Z
+Updated: 2026-07-10
+Generated: 2026-07-10T05:52:15.007Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -277,7 +277,7 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Returns: { text, response, model, aiUsagePolicy }
   - Generate text with the default Lumine text model, optionally streaming text updates through onText.
   - Signed-in viewers only.
-  - Uses gpt-5.4 by default.
+  - Uses Grok 4.5 by default.
   - Each successful text generation consumes AI Energy from the signed-in viewer.
   - history must be an array of { role: 'user' | 'assistant', content: string }. Twinkle.ai.chat does not read a text field.
   - The server keeps the latest 12 valid history entries.
@@ -294,9 +294,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
-  - thinkingMode low uses GPT nano and records free low-energy usage.
-  - thinkingMode medium uses GPT mini and normal AI Energy while AI Energy remains.
-  - thinkingMode high uses the full GPT model and high AI Energy while AI Energy remains.
+  - thinkingMode low uses GPT-5.6 Luna and records free low-energy usage.
+  - thinkingMode medium uses GPT-5.6 Luna and normal AI Energy while AI Energy remains.
+  - thinkingMode high uses Grok 4.5 with high reasoning and high AI Energy while AI Energy remains.
   - If medium or high is requested after AI Energy is empty, the server falls back to low and returns thinkingMode: low.
   - The SDK validates shape and retries malformed JSON, but app code should still validate business-specific enum values.
   - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'medium', prompt: 'Classify the player intent from: ' + playerText, expectedStructure: { action: 'string', targetCharacter: 'string', confidence: 0, shouldAskFollowUp: false } });
@@ -335,10 +335,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - The character route also accepts text or message fields for compatibility, but generated apps should use content.
   - The server keeps the latest 16 valid character history entries.
   - Pass onText/onStatus for streaming dialogue. Omit callbacks for non-streaming dialogue where the promise resolves with the final response.
-  - thinkingMode low uses Lite Mode and records free low-energy usage.
-  - thinkingMode medium uses normal AI Energy: Zero uses GPT mini and Ciel uses Claude Sonnet while AI Energy remains.
-  - thinkingMode high uses high AI Energy: Zero uses the full GPT model and Ciel uses Claude Opus 4.8 while AI Energy remains.
-  - Zero maps low/medium/high to GPT nano/GPT mini/full GPT. Ciel maps low/medium/high to Claude Haiku/Claude Sonnet/Claude Opus 4.8.
+  - thinkingMode low uses Lite Mode: Zero uses Grok 4.5 with low reasoning and Ciel uses Claude Haiku 4.5; usage is recorded as free low-energy usage.
+  - thinkingMode medium uses normal AI Energy: Zero uses Grok 4.5 with medium reasoning and Ciel uses Claude Sonnet 5 while AI Energy remains.
+  - thinkingMode high uses high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 4.8 with extended thinking while AI Energy remains.
   - If medium or high is requested after AI Energy is empty, the server falls back to low and returns thinkingMode: low.
   - Pass roomContext as a short shared scene transcript so Zero and Ciel can know what happened in the same room.
   - includeWebsiteContext defaults to true. Set includeWebsiteContext: false for in-world NPC dialogue that should only use Zero/Ciel's basic character identity plus your scene/instructions.