@stage5/lumine 0.2.8 → 0.2.9

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);
@@ -400,9 +400,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 +471,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(
@@ -558,7 +559,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,9 +574,62 @@ export async function readAssetUploadCandidate(filePath) {
   if (!buffer.length) {
     throw new Error(`Asset file is empty: ${filePath}`);
   }
+  if (extension === ".gltf") {
+    assertGltfUploadCandidateHasNoRelativeUris({ fileName, buffer });
+  }
   return { absolutePath, fileName, mimeType, buffer };
 }
 
+function isExternalOrEmbeddedGltfUri(uri) {
+  const normalizedUri = String(uri || "").trim();
+  if (!normalizedUri) return true;
+  if (normalizedUri.startsWith("/") || normalizedUri.startsWith("//")) {
+    return true;
+  }
+  const schemeMatch = normalizedUri.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+  if (!schemeMatch) return false;
+  return ["http", "https", "data"].includes(schemeMatch[1].toLowerCase());
+}
+
+function collectRelativeGltfUris(parsedGltf) {
+  const relativeUris = [];
+  if (!parsedGltf || typeof parsedGltf !== "object") {
+    return relativeUris;
+  }
+  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 && !isExternalOrEmbeddedGltfUri(uri)) {
+      relativeUris.push(uri);
+    }
+  }
+  return relativeUris;
+}
+
+function assertGltfUploadCandidateHasNoRelativeUris({ fileName, buffer }) {
+  let parsedGltf;
+  try {
+    parsedGltf = JSON.parse(buffer.toString("utf8"));
+  } catch {
+    throw new Error(`Invalid .gltf JSON in ${fileName}.`);
+  }
+  const relativeUris = collectRelativeGltfUris(parsedGltf);
+  if (relativeUris.length === 0) {
+    return;
+  }
+  const sampleUris = relativeUris
+    .slice(0, 3)
+    .map((uri) => `"${uri}"`)
+    .join(", ");
+  throw new Error(
+    `${fileName} contains relative glTF URI${
+      relativeUris.length === 1 ? "" : "s"
+    } (${sampleUris}${relativeUris.length > 3 ? ", ..." : ""}). Raw .gltf companion files are stored under separate asset URLs and will not resolve relative to the .gltf. Use .glb, embed data URIs, or rewrite .gltf URIs to absolute uploaded asset URLs before uploading.`,
+  );
+}
+
 export async function uploadRuntimeAsset({
   options,
   auth,

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.9",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {