@stage5/lumine 0.2.7 → 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/commands.js

@@ -54,6 +54,7 @@ import {
 } from "./auth.js";
 import { probeUrl, requestJson } from "./http.js";
 import { sdkCommand } from "./sdk.js";
+import { doctorCommand, normalizePreviewUrl } from "./doctor.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
@@ -191,6 +192,10 @@ export async function main() {
     await thumbnailCommand(options);
     return;
   }
+  if (options.command === "doctor") {
+    await doctorCommand(options);
+    return;
+  }
 
   printHelp();
 }
@@ -1501,6 +1506,9 @@ export function parseArgs(args) {
     "allowWrite",
     "main",
     "yes",
+    "json",
+    "keepAssets",
+    "noBrowser",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -1569,6 +1577,11 @@ export function parseArgs(args) {
     siteUrl: trimTrailingSlash(
       String(raw.siteUrl || process.env.TWINKLE_SITE_URL || DEFAULT_SITE_URL),
     ),
+    previewUrl: normalizePreviewUrl(
+      raw.previewUrl ||
+        process.env.TWINKLE_PREVIEW_URL ||
+        process.env.TWINKLE_BUILD_PREVIEW_URL,
+    ),
     npmRegistryUrl: trimTrailingSlash(
       String(
         raw.npmRegistryUrl ||
@@ -1607,6 +1620,9 @@ export function parseArgs(args) {
     openBrowser: parseBoolean(raw.noOpen, false)
       ? false
       : parseBoolean(raw.open, true),
+    json: parseBoolean(raw.json, false),
+    keepAssets: parseBoolean(raw.keepAssets, false),
+    noBrowser: parseBoolean(raw.noBrowser, false),
     updateCheck: parseBoolean(raw.noUpdateCheck, false) ? false : true,
     timeoutMs: Math.max(
       Number(raw.timeoutMs || process.env.TWINKLE_TIMEOUT_MS) ||
@@ -1778,6 +1794,7 @@ export function printHelp() {
   lumine thumbnail set <file>
   lumine thumbnail capture [--out <file>]
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
+  lumine doctor runtime-assets
 
 Examples:
   npx @stage5/lumine@latest
@@ -1808,10 +1825,12 @@ Examples:
   npx @stage5/lumine@latest thumbnail set art/cover.png
   npx @stage5/lumine@latest thumbnail capture --out capture.png
   npx @stage5/lumine@latest thumbnail generate --model gpt-image-2 --yes
+  npx @stage5/lumine@latest doctor runtime-assets --build 917 --json
 
 Options:
   --api-url <url>       Twinkle API origin
   --site-url <url>      Twinkle website origin
+  --preview-url <url>   Twinkle Build preview origin
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
@@ -1833,6 +1852,9 @@ Options:
   --allow-write         Permit sdk methods that mutate app data
   --path <api/...>      Call an sdk endpoint not in the curated list
   --scopes <a,b>        Override requested build API token scopes
+  --json                Print machine-readable output for doctor commands
+  --keep-assets         Keep doctor probe assets instead of deleting them
+  --no-browser          Skip doctor browser probes
   --model <model>       Image model for generate: gpt-image-2 or nano-banana (required, no default)
   --quality <q>         gpt-image-2 quality: low, medium, high (default high)
   --name <fileName>     File name hint for a generated asset

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
@@ -321,5 +335,6 @@ export const COMMANDS = new Set([
   "sdk",
   "assets",
   "thumbnail",
+  "doctor",
   "help",
 ]);

package/lib/doctor.js

@@ -0,0 +1,720 @@
+import { createRequire } from "module";
+
+import { buildApiJson, mintBuildApiToken } from "./api.js";
+import { ensureAuth, assertAuthScope } from "./auth.js";
+import { uploadRuntimeAsset } from "./assets.js";
+import { requestJson } from "./http.js";
+import { resolveSdkBuildId } from "./sdk.js";
+import { formatBytes, trimTrailingSlash } from "./util.js";
+
+const DEFAULT_PREVIEW_URL = "https://preview.lumine.app";
+const DOCTOR_SOURCE = "lumine-runtime-assets-doctor";
+const PREVIEW_IFRAME_SANDBOX = "allow-scripts allow-downloads allow-pointer-lock";
+
+export async function doctorCommand(options) {
+  const topic = String(options.positional[0] || "runtime-assets").trim();
+  if (topic !== "runtime-assets") {
+    throw new Error("Usage: lumine doctor runtime-assets [--build <id>] [--json] [--keep-assets] [--no-browser]");
+  }
+  await runtimeAssetsDoctor(options);
+}
+
+export async function runtimeAssetsDoctor(options) {
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  await assertAuthScope({ options, auth, scope: "build:check" });
+
+  const { token: buildApiToken } = await mintBuildApiToken({
+    options,
+    auth,
+    buildId,
+    scopes: ["files:read", "files:write", "preview:read"],
+  });
+
+  const result = {
+    ok: false,
+    buildId,
+    checkedAt: new Date().toISOString(),
+    uploadedAssets: [],
+    cloudfront: [],
+    previewSession: null,
+    browser: null,
+    cleanup: [],
+  };
+  const uploadedAssets = [];
+
+  try {
+    const candidates = makeRuntimeAssetProbeCandidates();
+    for (const candidate of candidates) {
+      const asset = await uploadRuntimeAsset({
+        options,
+        auth,
+        buildId,
+        buildApiToken,
+        candidate,
+      });
+      uploadedAssets.push(asset);
+      result.uploadedAssets.push(formatAssetForReport(asset));
+    }
+
+    for (const asset of uploadedAssets) {
+      result.cloudfront.push(await probeCloudFrontAsset(asset, options));
+    }
+
+    if (options.noBrowser) {
+      result.previewSession = {
+        ok: false,
+        skipped: true,
+        reason: "browser_probe_disabled",
+      };
+      result.browser = {
+        ok: false,
+        skipped: true,
+        reason: "browser_probe_disabled",
+      };
+    } else {
+      result.previewSession = await createRuntimeAssetsPreviewSession({
+        options,
+        auth,
+        buildId,
+        hdrAsset: findAssetByExtension(uploadedAssets, ".hdr"),
+        glbAsset: findAssetByExtension(uploadedAssets, ".glb"),
+      });
+      result.browser = await runBrowserLoaderProbe({
+        siteUrl: options.siteUrl,
+        previewUrl: options.previewUrl,
+        previewEntryUrl: result.previewSession.previewEntryUrl,
+        timeoutMs: options.timeoutMs,
+      });
+    }
+
+    result.headersOk = cloudFrontRequiredProbesPass(result.cloudfront);
+    result.complete = Boolean(result.browser?.ok);
+    result.ok = result.headersOk && (options.noBrowser || result.complete);
+  } catch (error) {
+    result.ok = false;
+    result.headersOk = cloudFrontRequiredProbesPass(result.cloudfront);
+    result.complete = false;
+    result.error = {
+      message: error?.message || String(error),
+      status: error?.status || null,
+      data: error?.data || null,
+    };
+    if (!result.previewSession) {
+      result.previewSession = {
+        ok: false,
+        error: result.error.message,
+        status: result.error.status,
+      };
+    }
+  } finally {
+    if (!options.keepAssets) {
+      for (const asset of uploadedAssets) {
+        result.cleanup.push(
+          await deleteRuntimeAssetQuietly({
+            options,
+            auth,
+            buildId,
+            buildApiToken,
+            asset,
+          }),
+        );
+      }
+    } else {
+      result.cleanup.push({
+        skipped: true,
+        reason: "keep_assets",
+        assetIds: uploadedAssets.map((asset) => Number(asset.id || 0)).filter(Boolean),
+      });
+    }
+  }
+
+  printRuntimeAssetsDoctorResult(result, options);
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+function makeRuntimeAssetProbeCandidates() {
+  const stamp = new Date().toISOString().replace(/[^0-9A-Za-z]+/g, "-");
+  return [
+    {
+      absolutePath: null,
+      fileName: `lumine-doctor-env-${stamp}.hdr`,
+      mimeType: "image/vnd.radiance",
+      buffer: makeMinimalHdr(),
+    },
+    {
+      absolutePath: null,
+      fileName: `lumine-doctor-scene-${stamp}.glb`,
+      mimeType: "model/gltf-binary",
+      buffer: makeMinimalGlb(),
+    },
+  ];
+}
+
+function makeMinimalHdr() {
+  const header = "#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 1 +X 1\n";
+  return Buffer.concat([
+    Buffer.from(header, "ascii"),
+    Buffer.from([255, 255, 255, 128]),
+  ]);
+}
+
+function makeMinimalGlb() {
+  const json = JSON.stringify({
+    asset: { version: "2.0", generator: "lumine-runtime-assets-doctor" },
+    scene: 0,
+    scenes: [{ nodes: [] }],
+    nodes: [],
+  });
+  const jsonPadding = (4 - (Buffer.byteLength(json) % 4)) % 4;
+  const jsonChunk = Buffer.concat([
+    Buffer.from(json, "utf8"),
+    Buffer.alloc(jsonPadding, 0x20),
+  ]);
+  const totalLength = 12 + 8 + jsonChunk.length;
+  const buffer = Buffer.alloc(totalLength);
+  buffer.writeUInt32LE(0x46546c67, 0);
+  buffer.writeUInt32LE(2, 4);
+  buffer.writeUInt32LE(totalLength, 8);
+  buffer.writeUInt32LE(jsonChunk.length, 12);
+  buffer.writeUInt32LE(0x4e4f534a, 16);
+  jsonChunk.copy(buffer, 20);
+  return buffer;
+}
+
+function formatAssetForReport(asset) {
+  return {
+    id: Number(asset?.id || 0),
+    fileName: asset?.fileName || "",
+    originalFileName: asset?.originalFileName || asset?.fileName || "",
+    mimeType: asset?.mimeType || null,
+    sizeBytes: Number(asset?.sizeBytes || 0),
+    url: asset?.url || "",
+  };
+}
+
+function findAssetByExtension(assets, extension) {
+  return assets.find((asset) =>
+    String(asset?.fileName || asset?.originalFileName || "")
+      .toLowerCase()
+      .endsWith(extension),
+  );
+}
+
+async function probeCloudFrontAsset(asset, options) {
+  const probes = buildCloudFrontProbeSpecs(options);
+  const requests = [];
+  for (const probe of probes) {
+    requests.push(await probeCloudFrontGet(asset.url, probe, options.timeoutMs));
+  }
+  return {
+    asset: formatAssetForReport(asset),
+    requests,
+  };
+}
+
+function buildCloudFrontProbeSpecs(options) {
+  const probes = [
+    {
+      label: "opaque sandbox",
+      origin: "null",
+      required: true,
+    },
+    {
+      label: "preview origin",
+      origin: normalizeOrigin(options.previewUrl),
+      required: false,
+    },
+    {
+      label: "site origin",
+      origin: normalizeOrigin(options.siteUrl),
+      required: false,
+    },
+    {
+      label: "no Origin",
+      origin: null,
+      required: false,
+    },
+  ];
+  const merged = new Map();
+  for (const probe of probes) {
+    if (probe.origin === "") continue;
+    const key = probe.origin === null ? "no-origin" : probe.origin;
+    const existing = merged.get(key);
+    if (!existing) {
+      merged.set(key, probe);
+      continue;
+    }
+    existing.required = existing.required || probe.required;
+    existing.label = existing.required ? existing.label : probe.label;
+  }
+  return Array.from(merged.values());
+}
+
+function normalizeOrigin(value) {
+  try {
+    return new URL(String(value || "")).origin;
+  } catch {
+    return "";
+  }
+}
+
+function cloudFrontRequiredProbesPass(cloudfront) {
+  if (!cloudfront.length) return false;
+  return cloudfront.every((entry) =>
+    entry.requests.filter((request) => request.required).length > 0 &&
+    entry.requests
+      .filter((request) => request.required)
+      .every((request) => request.ok && request.corsAllowed),
+  );
+}
+
+async function probeCloudFrontGet(url, probe, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const startedAt = Date.now();
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: probe.origin ? { origin: probe.origin } : {},
+      signal: controller.signal,
+    });
+    const body = await response.arrayBuffer();
+    const headers = pickHeaders(response.headers);
+    const corsAllowed = accessControlAllowOriginMatches({
+      headers,
+      origin: probe.origin,
+    });
+    return {
+      label: probe.label,
+      origin: probe.origin,
+      required: probe.required,
+      ok: response.ok,
+      status: response.status,
+      ms: Date.now() - startedAt,
+      bytes: body.byteLength,
+      hasAccessControlAllowOrigin: Boolean(headers["access-control-allow-origin"]),
+      corsAllowed,
+      headers,
+    };
+  } catch (error) {
+    return {
+      label: probe.label,
+      origin: probe.origin,
+      required: probe.required,
+      ok: false,
+      status: 0,
+      ms: Date.now() - startedAt,
+      bytes: 0,
+      hasAccessControlAllowOrigin: false,
+      corsAllowed: false,
+      error: error?.message || String(error),
+      headers: {},
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function accessControlAllowOriginMatches({ headers, origin }) {
+  const acao = String(headers["access-control-allow-origin"] || "").trim();
+  if (!acao) return false;
+  // No-Origin requests are telemetry only. They are not browser CORS checks, so
+  // report ACAO presence but never let this path affect required pass/fail.
+  if (origin === null) return true;
+  return acao === "*" || acao === origin;
+}
+
+function pickHeaders(headers) {
+  const keys = [
+    "access-control-allow-origin",
+    "access-control-allow-methods",
+    "access-control-expose-headers",
+    "content-type",
+    "content-length",
+    "cache-control",
+    "etag",
+    "x-cache",
+    "via",
+    "x-amz-cf-pop",
+  ];
+  const picked = {};
+  for (const key of keys) {
+    const value = headers.get(key);
+    if (value !== null) picked[key] = value;
+  }
+  return picked;
+}
+
+async function createRuntimeAssetsPreviewSession({
+  options,
+  auth,
+  buildId,
+  hdrAsset,
+  glbAsset,
+}) {
+  if (!hdrAsset?.url || !glbAsset?.url) {
+    throw new Error("Runtime asset probe did not produce both .hdr and .glb URLs.");
+  }
+  const session = await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/preview-session`,
+    authToken: auth.token,
+    body: {
+      entryPath: "/index.html",
+      files: [
+        {
+          path: "/index.html",
+          content: buildRuntimeAssetsProbeHtml({
+            hdrUrl: hdrAsset.url,
+            glbUrl: glbAsset.url,
+          }),
+        },
+      ],
+    },
+    timeoutMs: options.timeoutMs,
+  });
+  const entryUrl = String(session?.entryUrl || "");
+  if (!entryUrl) {
+    throw new Error("Twinkle did not return a preview-session entry URL.");
+  }
+  return {
+    ok: true,
+    sessionId: session.sessionId || null,
+    entryUrl,
+    previewEntryUrl: `${options.previewUrl}${entryUrl}`,
+  };
+}
+
+function buildRuntimeAssetsProbeHtml({ hdrUrl, glbUrl }) {
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Lumine Runtime Assets Doctor</title>
+</head>
+<body>
+  <script type="module">
+    const source = ${JSON.stringify(DOCTOR_SOURCE)};
+    const hdrUrl = ${JSON.stringify(hdrUrl)};
+    const glbUrl = ${JSON.stringify(glbUrl)};
+
+    function headersToObject(headers) {
+      const result = {};
+      for (const [key, value] of headers.entries()) {
+        result[key.toLowerCase()] = value;
+      }
+      return result;
+    }
+
+    async function fetchAsset(url) {
+      const response = await fetch(url, {
+        method: 'GET',
+        mode: 'cors',
+        cache: 'no-store',
+        credentials: 'omit'
+      });
+      const body = await response.arrayBuffer();
+      return {
+        ok: response.ok,
+        status: response.status,
+        type: response.type,
+        url: response.url,
+        bytes: body.byteLength,
+        headers: headersToObject(response.headers)
+      };
+    }
+
+    async function loadHdr(url) {
+      const { RGBELoader } = await import('/build/vendor/three/0.184.0/addons/loaders/RGBELoader.js');
+      const texture = await new Promise((resolve, reject) => {
+        new RGBELoader().load(url, resolve, undefined, reject);
+      });
+      return {
+        ok: true,
+        width: texture && texture.image ? texture.image.width || null : null,
+        height: texture && texture.image ? texture.image.height || null : null,
+        type: texture ? texture.type || null : null
+      };
+    }
+
+    async function loadGlb(url) {
+      const { GLTFLoader } = await import('/build/vendor/three/0.184.0/addons/loaders/GLTFLoader.js');
+      const gltf = await new Promise((resolve, reject) => {
+        new GLTFLoader().load(url, resolve, undefined, reject);
+      });
+      return {
+        ok: true,
+        sceneType: gltf && gltf.scene ? gltf.scene.type || null : null,
+        sceneChildren: gltf && gltf.scene && gltf.scene.children ? gltf.scene.children.length : null,
+        scenes: gltf && gltf.scenes ? gltf.scenes.length : null
+      };
+    }
+
+    async function run() {
+      const result = {
+        source,
+        ok: false,
+        href: location.href,
+        origin: location.origin,
+        crossOriginIsolated: window.crossOriginIsolated === true,
+        hdrFetch: null,
+        glbFetch: null,
+        hdrLoader: null,
+        glbLoader: null
+      };
+      try {
+        result.hdrFetch = await fetchAsset(hdrUrl);
+        result.glbFetch = await fetchAsset(glbUrl);
+        result.hdrLoader = await loadHdr(hdrUrl).catch((error) => ({
+          ok: false,
+          name: error && error.name ? error.name : null,
+          error: error && error.message ? error.message : String(error)
+        }));
+        result.glbLoader = await loadGlb(glbUrl).catch((error) => ({
+          ok: false,
+          name: error && error.name ? error.name : null,
+          error: error && error.message ? error.message : String(error)
+        }));
+        result.ok = Boolean(
+          result.hdrFetch && result.hdrFetch.ok &&
+          result.glbFetch && result.glbFetch.ok &&
+          result.hdrLoader && result.hdrLoader.ok &&
+          result.glbLoader && result.glbLoader.ok
+        );
+      } catch (error) {
+        result.error = error && error.message ? error.message : String(error);
+      }
+      window.parent.postMessage(result, '*');
+    }
+
+    run();
+  </script>
+</body>
+</html>`;
+}
+
+async function runBrowserLoaderProbe({
+  siteUrl,
+  previewUrl,
+  previewEntryUrl,
+  timeoutMs,
+}) {
+  const playwright = await loadPlaywright();
+  if (!playwright?.chromium) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: "playwright_not_available",
+      message:
+        "Install Playwright or set LUMINE_PLAYWRIGHT_MODULE to enable the sandboxed loader probe.",
+      previewEntryUrl,
+    };
+  }
+
+  const browser = await playwright.chromium.launch({ headless: true });
+  const page = await browser.newPage({
+    viewport: { width: 1280, height: 900 },
+  });
+  const consoleMessages = [];
+  page.on("console", (message) => {
+    consoleMessages.push({
+      type: message.type(),
+      text: message.text().slice(0, 500),
+    });
+  });
+
+  try {
+    const harnessUrl = buildBrowserHarnessUrl(siteUrl);
+    await page.route(harnessUrl, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "text/html; charset=utf-8",
+        headers: { "cache-control": "no-store" },
+        body: buildOuterSandboxHarness(previewEntryUrl),
+      });
+    });
+    await page.goto(harnessUrl, {
+      waitUntil: "domcontentloaded",
+      timeout: timeoutMs,
+    });
+    const loaderResult = await waitForBrowserProbeResult(page, timeoutMs);
+    return {
+      ok: Boolean(loaderResult?.ok),
+      harnessUrl,
+      previewOrigin: previewUrl,
+      previewEntryUrl,
+      sandbox: PREVIEW_IFRAME_SANDBOX,
+      result: loaderResult,
+      consoleMessages,
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+function buildBrowserHarnessUrl(siteUrl) {
+  const url = new URL("/__lumine-doctor/runtime-assets-harness", siteUrl);
+  url.searchParams.set("t", String(Date.now()));
+  return url.toString();
+}
+
+async function waitForBrowserProbeResult(page, timeoutMs) {
+  try {
+    await page.waitForFunction(
+      () => Boolean(window.__lumineRuntimeAssetsDoctorResult),
+      null,
+      { timeout: timeoutMs },
+    );
+    return await page.evaluate(() => window.__lumineRuntimeAssetsDoctorResult);
+  } catch (error) {
+    return {
+      ok: false,
+      error: error?.message || "Timed out waiting for runtime asset probe message.",
+    };
+  }
+}
+
+async function loadPlaywright() {
+  const require = createRequire(import.meta.url);
+  const candidates = [
+    process.env.LUMINE_PLAYWRIGHT_MODULE,
+    "playwright",
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      return require(candidate);
+    } catch {
+      // Try the next candidate.
+    }
+  }
+  return null;
+}
+
+function buildOuterSandboxHarness(previewEntryUrl) {
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Lumine Runtime Assets Doctor Harness</title>
+</head>
+<body>
+  <script>
+    window.__lumineRuntimeAssetsDoctorResult = null;
+    window.addEventListener('message', (event) => {
+      if (!event || !event.data || event.data.source !== ${JSON.stringify(DOCTOR_SOURCE)}) return;
+      window.__lumineRuntimeAssetsDoctorResult = event.data;
+    });
+  </script>
+  <iframe
+    title="Lumine runtime assets doctor"
+    sandbox="${PREVIEW_IFRAME_SANDBOX}"
+    src="${escapeHtmlAttribute(previewEntryUrl)}"
+    style="width: 800px; height: 600px; border: 0;"
+  ></iframe>
+</body>
+</html>`;
+}
+
+function escapeHtmlAttribute(value) {
+  return String(value || "")
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+async function deleteRuntimeAssetQuietly({
+  options,
+  auth,
+  buildId,
+  buildApiToken,
+  asset,
+}) {
+  const assetId = Number(asset?.id || 0);
+  if (!assetId) {
+    return { ok: false, assetId, error: "missing_asset_id" };
+  }
+  try {
+    await buildApiJson({
+      options,
+      auth,
+      buildId,
+      buildApiToken,
+      endpointPath: "api/files/delete",
+      body: { assetId },
+    });
+    return { ok: true, assetId };
+  } catch (error) {
+    return {
+      ok: false,
+      assetId,
+      status: error?.status || null,
+      error: error?.message || String(error),
+    };
+  }
+}
+
+function printRuntimeAssetsDoctorResult(result, options) {
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`Runtime asset doctor for Build #${result.buildId}`);
+  for (const asset of result.uploadedAssets) {
+    console.log(
+      `- uploaded #${asset.id} ${asset.originalFileName} ${formatBytes(asset.sizeBytes)}`,
+    );
+    console.log(`  ${asset.url}`);
+  }
+
+  for (const entry of result.cloudfront) {
+    console.log(`- CloudFront ${entry.asset.originalFileName}`);
+    for (const request of entry.requests) {
+      const origin = request.origin === null ? "(no Origin)" : request.origin;
+      const acao = request.headers["access-control-allow-origin"] || "(missing)";
+      const contentType = request.headers["content-type"] || "(missing)";
+      const required = request.required ? "required" : "info";
+      const cors = request.corsAllowed ? "allowed" : "blocked";
+      console.log(
+        `  GET ${request.label} [${required}] Origin ${origin}: ` +
+          `${request.ok ? "ok" : "fail"} ${request.status} ` +
+          `ACAO=${acao} CORS=${cors} Content-Type=${contentType} bytes=${request.bytes}`,
+      );
+    }
+  }
+
+  if (result.previewSession?.previewEntryUrl) {
+    console.log(`- preview session: ${result.previewSession.previewEntryUrl}`);
+  }
+  if (result.error?.message) {
+    const status = result.error.status ? ` (${result.error.status})` : "";
+    console.log(`- error: ${result.error.message}${status}`);
+  }
+  if (result.browser?.skipped) {
+    console.log(`- browser loader probe: skipped (${result.browser.reason})`);
+    if (result.browser.message) console.log(`  ${result.browser.message}`);
+  } else if (result.browser) {
+    console.log(`- browser loader probe: ${result.browser.ok ? "ok" : "fail"}`);
+    const loader = result.browser.result || {};
+    console.log(`  HDRLoader: ${loader.hdrLoader?.ok ? "ok" : "fail"}`);
+    console.log(`  GLTFLoader: ${loader.glbLoader?.ok ? "ok" : "fail"}`);
+  }
+  for (const cleanup of result.cleanup) {
+    if (cleanup.skipped) {
+      console.log(`- cleanup: skipped (${cleanup.reason})`);
+    } else {
+      console.log(`- cleanup asset #${cleanup.assetId}: ${cleanup.ok ? "ok" : "fail"}`);
+    }
+  }
+  const suffix = result.ok && !result.complete ? " (browser skipped)" : "";
+  console.log(`Result: ${result.ok ? "ok" : "fail"}${suffix}`);
+}
+
+export function normalizePreviewUrl(value) {
+  return trimTrailingSlash(String(value || DEFAULT_PREVIEW_URL));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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-07-05
-Generated: 2026-07-05T06:47:32.349Z
+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.
@@ -22,12 +22,27 @@ Generated: 2026-07-05T06:47:32.349Z
 - 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