@bitmagic/cli 0.1.39 → 0.1.41

package/dist/editor/shell-page.js

@@ -48,8 +48,39 @@
  *     nothing. Polling `CHECK_SCENE_CHANGES` is what the Creator does too, just on tab switch
  *     instead of on a timer, and it covers drags, deletes, adds and inspector edits with one path.
  */
+import { decodeForgeMapHeights, renderForgeMapRgba, } from '@bitmagic/world-forger/pipeline/forge-map-render.js';
+import { FORGE_MAP_PALETTE } from '@bitmagic/world-forger/pipeline/layout-map.js';
+import { ASSET_DETAIL_CSS, ASSET_DETAIL_HTML } from './asset-detail-panel.js';
 /** How often the shell asks the engine whether anything changed. A `Set` read; effectively free. */
 const POLL_INTERVAL_MS = 500;
+/**
+ * What the map is drawn at, in device pixels — about twice the assets panel's inner width.
+ *
+ * Deliberately larger than it displays. A 128-sample raster drawn 1:1 and then stretched to the
+ * panel gives single-pixel object dots blown up to blocks; drawn at 2-3x and scaled DOWN by the
+ * browser, the same dots land as clean marks and the terrain keeps its shading.
+ */
+const MAP_CANVAS_WIDTH = 464;
+/**
+ * The forge map's renderer, as SOURCE, so this page and the Creator draw the same picture.
+ *
+ * This page has no module loader — it is a string this file assembles — so it cannot import the
+ * way the Creator does. The alternative to shipping the function's own text is a hand-written
+ * second implementation, and the first time the hillshade is tuned the two maps stop agreeing
+ * about what a level looks like.
+ *
+ * Two things make this safe rather than clever: `cli` builds with plain `tsc` and never minifies,
+ * and `forge-map-render.ts` is written to have no free identifiers (its header says so and says
+ * why), so its text is complete on its own. A test round-trips the interpolated copy against the
+ * imported one, so a change that breaks the trick fails there rather than in a creator's browser.
+ */
+function forgeMapRendererSource() {
+    return [
+        `const FORGE_MAP_PALETTE = ${JSON.stringify(FORGE_MAP_PALETTE)};`,
+        `const decodeForgeMapHeights = ${decodeForgeMapHeights.toString()};`,
+        `const renderForgeMapRgba = ${renderForgeMapRgba.toString()};`,
+    ].join('\n  ');
+}
 /**
  * How recently a scene save must have landed for the creator to count as "still working".
  *
@@ -121,6 +152,8 @@ export function renderEditorShell(options) {
   #assets-head .count { margin-left: auto; color: #6a6a7a; letter-spacing: 0; }
   #assets-empty { padding: 14px 10px; color: #6a6a7a; }
   .row { display: flex; gap: 9px; padding: 8px 10px; border-bottom: 1px solid #1e1e26; }
+  .row.clickable { cursor: pointer; }
+  .row.clickable:hover, .row.clickable:focus-visible { background: #1b1b23; outline: none; }
   .row .thumb { width: 46px; height: 46px; flex: none; border-radius: 4px; background: #1e1e26;
                 display: flex; align-items: center; justify-content: center; font-size: 18px;
                 color: #55556a; overflow: hidden; }
@@ -139,14 +172,11 @@ export function renderEditorShell(options) {
   .row.job .thumb { color: #d9a441; }
   .row.job .message { color: #9a9aab; font-size: 11px; overflow: hidden; text-overflow: ellipsis;
                       white-space: nowrap; }
-  .row.job.failed .thumb { color: #e0564f; }
-  .row.job.failed .message { color: #e0938e; white-space: normal; }
   /* The forge's five steps. A whole run is half an hour, so this is what the panel is for. */
   .steps { margin-top: 5px; font-size: 11px; }
   .step { display: flex; align-items: baseline; gap: 5px; color: #55556a; line-height: 1.6; }
   .step.running { color: #d9d9e2; }
   .step.done { color: #7c8f7f; }
-  .step.stopped { color: #e0938e; }
   .step .glyph { width: 9px; flex: none; text-align: center; }
   .step .label { flex: none; }
   .step .tail { min-width: 0; flex: 1; overflow: hidden; text-overflow: ellipsis;
@@ -155,6 +185,12 @@ export function renderEditorShell(options) {
   .bar { height: 3px; margin: 3px 0 4px 14px; border-radius: 2px; background: #26262e;
          overflow: hidden; }
   .bar .fill { height: 100%; background: #d9a441; }
+  /* The level's shape, drawn from the forge artifact — twenty-plus minutes before it is playable.
+     image-rendering: pixelated because the canvas is drawn at an integer multiple of the raster
+     and any further scaling should keep the object dots as dots. */
+  .job-map { margin-top: 7px; }
+  .job-map canvas { display: block; width: 100%; height: auto; border-radius: 4px;
+                    border: 1px solid #26262e; image-rendering: pixelated; }
   /* What the level being built contains — known minutes before the level itself exists. */
   .job-summary { margin-top: 6px; padding-top: 6px; border-top: 1px solid #1e1e26;
                  color: #8a8a99; font-size: 11px; line-height: 1.6; }
@@ -177,6 +213,7 @@ export function renderEditorShell(options) {
              background: #101014; border: 1px solid #26262e; }
   #hq-note.show { display: block; }
   #hq-note code { display: block; margin-top: 6px; color: #9fd0a8; word-break: break-all; }
+${ASSET_DETAIL_CSS}
 </style>
 </head>
 <body>
@@ -235,12 +272,16 @@ export function renderEditorShell(options) {
       </div>
     </div>
   </div>
+${ASSET_DETAIL_HTML}
 <script>
 (function () {
   'use strict';
   var GAME_URL = ${JSON.stringify(gameUrl)};
   var POLL_MS = ${POLL_INTERVAL_MS};
   var ACTIVE_EDIT_MS = ${ACTIVE_EDIT_WINDOW_MS};
+  var MAP_CANVAS_WIDTH = ${MAP_CANVAS_WIDTH};
+  // The forge map's renderer, shared verbatim with the Creator — see forgeMapRendererSource().
+  ${forgeMapRendererSource()}
   var TAB_KEY = 'bitmagic.dev.tab';
   var AUTO_KEY = 'bitmagic.dev.autoReload';
   var ASSETS_KEY = 'bitmagic.dev.assets';
@@ -330,6 +371,13 @@ export function renderEditorShell(options) {
     var message = event.data;
     if (!message || typeof message.type !== 'string') return;
 
+    // The asset overlay's viewer is a second sender on this window. Its replies are routed by
+    // source, before the waiter list below gets to match anything on type alone.
+    if (assetFrame && event.source === assetFrame.contentWindow) {
+      onAssetPreviewMessage(message);
+      return;
+    }
+
     waiters = waiters.filter(function (waiter) {
       if (waiter.type !== message.type) return true;
       clearTimeout(waiter.timer);
@@ -836,7 +884,7 @@ export function renderEditorShell(options) {
     return typeof value === 'number' && isFinite(value) ? value.toLocaleString() : '';
   }
 
-  var STEP_GLYPHS = { pending: '○', running: '⟳', done: '✓', stopped: '✕' };
+  var STEP_GLYPHS = { pending: '○', running: '⟳', done: '✓' };
 
   /**
    * The trailing text for one step: its duration once finished, its counts while it runs.
@@ -861,14 +909,11 @@ export function renderEditorShell(options) {
    * snapshot (cli/src/forge/progress.ts), so this draws one list and never has to know which
    * machine a row came from.
    */
-  function stepsBlock(progress, jobFailed) {
+  function stepsBlock(progress) {
     var block = el('div', 'steps');
     for (var i = 0; i < progress.steps.length; i++) {
       var step = progress.steps[i];
-      // A failed job leaves its running step running forever — the process died before it could
-      // say otherwise. The job's own status is the authority, so the row that was in flight is the
-      // one that stopped.
-      var status = jobFailed && step.status === 'running' ? 'stopped' : step.status;
+      var status = step.status;
       var line = el('div', 'step ' + status);
       line.appendChild(el('span', 'glyph' + (status === 'running' ? ' spin' : ''), STEP_GLYPHS[status]));
       line.appendChild(el('span', 'label', step.label + (step.resumed ? ' (resumed)' : '')));
@@ -888,6 +933,53 @@ export function renderEditorShell(options) {
     return block;
   }
 
+  /**
+   * A forge's map, fetched once per job and drawn into a canvas.
+   *
+   * Fetched rather than carried on the job record, because the record is re-read at 1 Hz for the
+   * whole run and the map never changes after it arrives. Cached by job id so the panel's rebuild
+   * (which throws every row away and makes new ones) does not re-request it every second.
+   */
+  var mapCache = {};
+  var mapFetching = {};
+
+  function drawMap(canvas, map) {
+    var scale = Math.max(1, Math.floor(MAP_CANVAS_WIDTH / Math.max(map.width, map.height)));
+    var render = renderForgeMapRgba(map, decodeForgeMapHeights(map), FORGE_MAP_PALETTE, scale);
+    canvas.width = render.width;
+    canvas.height = render.height;
+    var ctx = canvas.getContext('2d');
+    if (!ctx) return;
+    var image = ctx.createImageData(render.width, render.height);
+    image.data.set(render.rgba);
+    ctx.putImageData(image, 0, 0);
+  }
+
+  function mapBlock(jobId) {
+    var block = el('div', 'job-map');
+    var canvas = document.createElement('canvas');
+    block.appendChild(canvas);
+    var cached = mapCache[jobId];
+    if (cached) {
+      drawMap(canvas, cached);
+      return block;
+    }
+    if (!mapFetching[jobId]) {
+      mapFetching[jobId] = true;
+      fetch('/api/jobs/' + encodeURIComponent(jobId) + '/layout')
+        .then(function (r) { return r.ok ? r.json() : null; })
+        .then(function (payload) {
+          if (!payload || !payload.layout) return;
+          mapCache[jobId] = payload.layout;
+          // Re-render rather than drawing into this canvas: by the time the fetch lands the 1 Hz
+          // ticker has almost certainly replaced the row this element belongs to.
+          void refreshAssets();
+        })
+        .catch(function () { /* no map is a panel without a picture, never an error to show */ });
+    }
+    return block;
+  }
+
   /** What the level contains — the answer that exists long before the level does. */
   function summaryBlock(summary) {
     var headline = [];
@@ -911,50 +1003,81 @@ export function renderEditorShell(options) {
     return block;
   }
 
+  /**
+   * A generation in flight. Only ever in flight: the sidecar serves running jobs and nothing else,
+   * because a failure is a tool diagnostic for whoever ran the command — see project/jobs.ts. A job
+   * that fails leaves this list the same way one that succeeds does, by no longer being in it.
+   */
   function jobRow(job) {
-    var failed = job.status === 'failed';
-    var row = el('div', 'row job' + (failed ? ' failed' : ''));
+    var row = el('div', 'row job');
     var thumb = el('div', 'thumb');
-    thumb.appendChild(el('span', failed ? '' : 'spin', failed ? '!' : '⟳'));
+    thumb.appendChild(el('span', 'spin', '⟳'));
     row.appendChild(thumb);
     var body = el('div', 'body');
     body.appendChild(el('div', 'name', job.label || job.kind));
-    var meta = el('div', 'meta', job.kind + (failed ? '' : ' · ' + formatElapsed(job.startedAt)));
-    body.appendChild(meta);
+    body.appendChild(el('div', 'meta', job.kind + ' · ' + formatElapsed(job.startedAt)));
     var progress = job.progress;
     var hasSteps = progress && Array.isArray(progress.steps) && progress.steps.length > 0;
-    // The single-line message stays the whole story for every kind that has no steps, and stays
-    // the FAILURE story even for a forge: the step list says which step stopped, never why.
-    if (failed || !hasSteps) {
-      body.appendChild(el('div', 'message', failed ? (job.error || 'Failed') : (job.message || '')));
-    }
+    // A forge is the one kind with more than a sentence to say. Everything else keeps the single
+    // line, which for those is the whole story.
     if (hasSteps) {
-      body.appendChild(stepsBlock(progress, failed));
+      body.appendChild(stepsBlock(progress));
       var summary = progress.summary ? summaryBlock(progress.summary) : null;
       if (summary) body.appendChild(summary);
+      if (job.hasLayout) body.appendChild(mapBlock(job.jobId));
+    } else {
+      body.appendChild(el('div', 'message', job.message || ''));
     }
     row.appendChild(body);
     return row;
   }
 
   /**
-   * The URL the engine should draw a thumbnail from, or null when there is nothing to draw.
+   * How the engine should draw this asset's thumbnail, or null when there is nothing to draw.
+   *
+   * 'sourceGlbUrl' before 'url' because many CLI-lane meshes are voxelized: 'url' is then a .vxl,
+   * and the GLB the forger started from renders in one message with nothing to fetch here.
    *
-   * 'sourceGlbUrl' before 'url' because most CLI-lane meshes are voxelized: 'url' is then a .vxl,
-   * which the GLB preview renderer cannot read, while 'sourceGlbUrl' is the original the forger or
-   * the generator started from. An asset with neither — a sound, an animation, a level — keeps its
-   * glyph, which is the honest answer for something with no appearance.
+   * A .vxl with NO GLB source used to fall through to a glyph, and that was most of the panel —
+   * across the sampled project worlds it is 153 such assets against 144 with a GLB source, and
+   * every fresh project starts in the bad half: templates/standard-3d ships nine assets, all vxl,
+   * none with a sourceGlbUrl or a screenshotUrl. So the whole assets panel of a new project was
+   * grey boxes. Those now go the voxel route, which the engine has been able to draw the entire
+   * time (VoxelMessageHandlers.handleGenerateVoxelPreview) and which the web Creator has used since
+   * before this lane existed.
+   *
+   * An asset with neither — a sound, an animation, a level — keeps its glyph, which is the honest
+   * answer for something with no appearance.
    */
-  function previewSourceFor(asset) {
-    var url = asset.sourceGlbUrl || asset.url;
-    if (typeof url !== 'string' || url === '') return null;
+  var MAX_VXL_PREVIEW_BYTES = 8 * 1024 * 1024;
+
+  function previewJobFor(asset) {
+    var glb = asset.sourceGlbUrl || asset.url;
     // Double-escaped because this whole page is a template literal: a single backslash is consumed
     // by the literal, and the browser would receive the invalid regex /.(glb|gltf)(?|$)/.
-    return /\\.(glb|gltf)(\\?|$)/i.test(url) ? url : null;
+    if (typeof glb === 'string' && /\\.(glb|gltf)(\\?|$)/i.test(glb)) return { kind: 'glb', url: glb };
+    var url = asset.url;
+    if (typeof url !== 'string' || !/\\.vxl(\\?|$)/i.test(url)) return null;
+    // The voxel message carries the FILE, so this one costs a fetch and a structured clone of the
+    // whole thing. The templates' files are 0.5-2.5 KB; a multi-megabyte one is a hitch on the
+    // render thread in exchange for a 46px tile, and the glyph is the better trade.
+    if (typeof asset.size === 'number' && asset.size > MAX_VXL_PREVIEW_BYTES) return null;
+    return { kind: 'vxl', url: url };
   }
 
   function assetRow(asset, isFresh, hasPreview) {
-    var row = el('div', 'row' + (isFresh ? ' fresh' : ''));
+    var row = el('div', 'row clickable' + (isFresh ? ' fresh' : ''));
+    // A row is a button: the panel is a list of things you can look at. Job rows deliberately are
+    // not — there is nothing to show for an asset that does not exist yet.
+    row.setAttribute('role', 'button');
+    row.setAttribute('tabindex', '0');
+    row.title = 'Open a preview of this asset';
+    row.addEventListener('click', function () { openAssetDetail(asset, hasPreview); });
+    row.addEventListener('keydown', function (event) {
+      if (event.key !== 'Enter' && event.key !== ' ') return;
+      event.preventDefault();
+      openAssetDetail(asset, hasPreview);
+    });
     var thumb = el('div', 'thumb');
     var type = String(asset.type || '').toLowerCase();
     if (type === 'image' && typeof asset.url === 'string' && asset.url !== '') {
@@ -972,7 +1095,7 @@ export function renderEditorShell(options) {
       thumb.appendChild(cached);
     } else {
       thumb.appendChild(el('span', '', glyphFor(asset.type)));
-      if (previewSourceFor(asset) !== null) queuePreview(asset);
+      if (previewJobFor(asset) !== null) queuePreview(asset);
     }
     row.appendChild(thumb);
 
@@ -1035,26 +1158,71 @@ export function renderEditorShell(options) {
   }
 
   /**
-   * Ask the game to draw the thumbnails the cache is missing — one at a time, and never twice for
+   * Ask the game to draw the thumbnails the cache is missing — one at a time, and at most twice for
    * the same asset in one session.
    *
-   * Serial on purpose. Each render is a GLB fetch and a draw in the SAME renderer the creator is
-   * playing in, and a forged city has hundreds of assets: firing them all at once would stutter the
-   * game to decorate a side panel. 'attempted' covers the failures too, so an asset whose GLB 404s
-   * is asked for once rather than on every render pass forever.
+   * Serial on purpose. Each render is a fetch and a draw in the SAME renderer the creator is playing
+   * in, and a forged city has hundreds of assets: firing them all at once would stutter the game to
+   * decorate a side panel.
+   *
+   * Two rather than one attempt, and the second is not defensive padding. GENERATE_VOXEL_PREVIEW is
+   * in the engine's REQUIRES_GAME_LOADED set (the GLB one is not), so a request arriving while a
+   * game is loading is QUEUED and silently never answered. Marked attempted-once, that asset would
+   * keep its glyph for the rest of the session; the retry costs one extra message and the cap keeps
+   * a genuinely broken asset from asking forever.
    */
+  var MAX_PREVIEW_ATTEMPTS = 2;
   var previewQueue = [];
-  var previewAttempted = {};
+  var previewAttempts = {};
   var previewRunning = false;
   var previewRequestId = 0;
 
   function queuePreview(asset) {
-    if (previewAttempted[asset.id]) return;
-    previewAttempted[asset.id] = true;
+    var attempts = previewAttempts[asset.id] || 0;
+    if (attempts >= MAX_PREVIEW_ATTEMPTS) return;
+    previewAttempts[asset.id] = attempts + 1;
     previewQueue.push(asset);
     void drainPreviewQueue();
   }
 
+  /**
+   * Both preview messages use the FLAT envelope and both are answered by requestId, so neither can
+   * go through the request() helper — it matches on type alone.
+   */
+  function requestGlbPreview(url, requestId) {
+    postFlat({ type: 'GENERATE_GLB_PREVIEW', requestId: requestId, glbUrl: url });
+    return await_('GLB_PREVIEW_RESPONSE', 15000);
+  }
+
+  /**
+   * The voxel counterpart, ported from the web Creator's useAssetsEditor.requestVoxelPreview.
+   *
+   * The bytes come through the sidecar rather than straight from the asset host: this message
+   * carries the file itself, and a browser fetch would make voxel thumbnails depend on that host's
+   * CORS headers — see /api/assets/source.
+   */
+  async function requestVoxelPreview(url, requestId) {
+    var bytes;
+    try {
+      var source = await fetch('/api/assets/source?url=' + encodeURIComponent(url));
+      if (!source.ok) throw new Error('sidecar answered ' + source.status);
+      bytes = new Uint8Array(await source.arrayBuffer());
+    } catch (error) {
+      // Worth a line: without one, an asset the sidecar cannot reach is a grey tile with no reason.
+      console.warn('[bitmagic dev] no voxel preview for ' + url, error);
+      return null;
+    }
+    postFlat({
+      type: 'GENERATE_VOXEL_PREVIEW',
+      requestId: requestId,
+      // A plain number array, which is what the engine handler reads (new Uint8Array(data.vxlData)).
+      // Not an ArrayBuffer: this page ships with the CLI and talks to whatever engine the project
+      // has vendored, so the wire shape has to keep working against older ones.
+      vxlData: Array.prototype.slice.call(bytes)
+    });
+    return await_('VOXEL_PREVIEW_RESPONSE', 15000);
+  }
+
   async function drainPreviewQueue() {
     if (previewRunning) return;
     previewRunning = true;
@@ -1065,20 +1233,24 @@ export function renderEditorShell(options) {
         // pass rather than being dropped — refreshAssets re-queues on every render.
         if (!loaded) return;
         var asset = previewQueue.shift();
-        var source = previewSourceFor(asset);
-        if (source === null) continue;
+        var job = previewJobFor(asset);
+        if (job === null) continue;
 
         previewRequestId += 1;
-        // Deliberately not the request() helper: this message uses the FLAT envelope, and the reply
-        // has to be matched on requestId (below) rather than on type alone.
         var requestId = 'preview-' + previewRequestId;
-        postFlat({ type: 'GENERATE_GLB_PREVIEW', requestId: requestId, glbUrl: source });
-        var response = await await_('GLB_PREVIEW_RESPONSE', 15000);
-        // Verified rather than assumed: a late answer from a request that already timed out would
-        // otherwise be cached under the NEXT asset's id, which is a wrong picture rather than a
-        // missing one — much the worse failure.
-        if (!response || response.requestId !== requestId) continue;
-        if (!response.success || !response.previewBase64) continue;
+        var response = job.kind === 'vxl'
+          ? await requestVoxelPreview(job.url, requestId)
+          : await requestGlbPreview(job.url, requestId);
+
+        // The requestId is verified rather than assumed: a late answer from a request that already
+        // timed out would otherwise be cached under the NEXT asset's id, which is a wrong picture
+        // rather than a missing one — much the worse failure.
+        if (!response || response.requestId !== requestId || !response.success || !response.previewBase64) {
+          // Back of the queue, behind everything else, and only while attempts remain. This is the
+          // path a request swallowed by REQUIRES_GAME_LOADED takes.
+          queuePreview(asset);
+          continue;
+        }
 
         var saved = await (await fetch('/api/assets/preview', {
           method: 'POST',
@@ -1126,6 +1298,196 @@ export function renderEditorShell(options) {
     }, 1000);
   }
 
+  /**
+   * The asset overlay — everything a 46px tile cannot show.
+   *
+   * The viewer itself is an iframe onto '/asset-preview', which the dev sidecar serves from this
+   * same origin. It is not part of the game: the game keeps its own WebGL context in the frame
+   * behind this dialog, and the two never share a renderer.
+   */
+  var assetOverlay = document.getElementById('asset-overlay');
+  var assetFrame = document.getElementById('asset-frame');
+  var assetImage = document.getElementById('asset-image');
+  var assetAudio = document.getElementById('asset-audio');
+  var assetNote = document.getElementById('asset-note');
+  var assetFacts = document.getElementById('asset-facts');
+  var assetResetButton = document.getElementById('asset-reset');
+  var assetPausedByOverlay = false;
+  var assetReturnFocus = null;
+  var assetLoadTimer = null;
+
+  var IMAGE_TYPES = { image: 1, skybox: 1 };
+  var AUDIO_TYPES = { audio: 1, sound: 1, 'sound-effect': 1 };
+
+  /**
+   * What the VIEWER should load — which is not always what the thumbnail drew.
+   *
+   * previewJobFor prefers a voxelized asset's GLB source, because one message with no fetch is the
+   * cheaper way to fill a 46px tile. Here the creator has asked to look at a specific asset, so it
+   * shows the asset: a .vxl is drawn as voxels even when the mesh it was baked from is on record.
+   */
+  function detailJobFor(asset) {
+    var url = asset.url;
+    if (typeof url === 'string' && /\\.vxl(\\?|$)/i.test(url)) {
+      if (typeof asset.size === 'number' && asset.size > MAX_VXL_PREVIEW_BYTES) return null;
+      return { kind: 'vxl', url: url };
+    }
+    var glb = asset.sourceGlbUrl || url;
+    if (typeof glb === 'string' && /\\.(glb|gltf)(\\?|$)/i.test(glb)) return { kind: 'glb', url: glb };
+    return null;
+  }
+
+  function fact(term, value) {
+    if (!value) return;
+    assetFacts.appendChild(el('dt', '', term));
+    assetFacts.appendChild(el('dd', term === 'Id' ? 'mono' : '', value));
+  }
+
+  /** Extent in world units, which is the number that says whether a prop is door-sized. */
+  function dimensionsOf(asset) {
+    var box = asset.boundingBox;
+    if (!box || typeof box.minX !== 'number') return '';
+    var round = function (n) { return Math.round(n * 10) / 10; };
+    return round(box.maxX - box.minX) + ' × ' + round(box.maxY - box.minY) + ' × ' + round(box.maxZ - box.minZ);
+  }
+
+  function showAssetNote(text) {
+    assetNote.textContent = text;
+    assetNote.classList.remove('hidden');
+  }
+
+  function openAssetDetail(asset, hasPreview) {
+    assetReturnFocus = document.activeElement;
+    document.getElementById('asset-name').textContent = asset.name || asset.id || 'unnamed';
+    document.getElementById('asset-sub').textContent =
+      (asset.hqGeneratedAt ? 'High quality · ' : asset.placeholder === true ? 'Placeholder · ' : '')
+      + (asset.type || 'unknown');
+
+    assetFacts.textContent = '';
+    fact('Size', formatSize(asset.size));
+    fact('Extent', dimensionsOf(asset));
+    fact('Voxels', typeof asset.voxelCount === 'number' ? String(asset.voxelCount) : '');
+    fact('Id', asset.id || '');
+
+    assetNote.classList.add('hidden');
+    assetFrame.classList.add('hidden');
+    assetImage.classList.add('hidden');
+    assetAudio.classList.add('hidden');
+    assetResetButton.classList.add('hidden');
+    if (assetLoadTimer) clearTimeout(assetLoadTimer);
+
+    var type = String(asset.type || '').toLowerCase();
+    var job = detailJobFor(asset);
+
+    if (IMAGE_TYPES[type] === 1 && typeof asset.url === 'string' && asset.url !== '') {
+      // An image is already the thing. Loading a 3D viewer to show a picture would be theatre.
+      assetImage.src = asset.url;
+      assetImage.classList.remove('hidden');
+    } else if (AUDIO_TYPES[type] === 1 && typeof asset.url === 'string' && asset.url !== '') {
+      assetAudio.src = asset.url;
+      assetAudio.classList.remove('hidden');
+    } else if (job !== null) {
+      assetResetButton.classList.remove('hidden');
+      assetFrame.classList.remove('hidden');
+      assetFrame.src = '/asset-preview?kind=' + job.kind + '&url=' + encodeURIComponent(job.url);
+      // Not a deadline for the load — a big mesh over a slow CDN legitimately takes a while, and
+      // replacing a working viewer with an apology would be worse than waiting. This only speaks
+      // when the page has said nothing at all, which is what a module graph that failed to load
+      // looks like: the page's own catch reports every error it can see, and cannot report that.
+      assetLoadTimer = setTimeout(function () {
+        showAssetNote('Still loading. If this does not clear, check the dev server output.');
+      }, 12000);
+    } else {
+      showAssetThumbnailFallback(asset, hasPreview,
+        'There is nothing to draw for this asset type — it has no mesh and no picture.');
+    }
+
+    assetOverlay.classList.add('show');
+    document.getElementById('asset-close').focus();
+
+    // The game is a WebGL context and a physics step running behind a dialog nobody is looking at.
+    // The Editor tab is already paused by applyTab, so this only fires on the Game tab.
+    if (activeTab === 'game' && gameState === 'playing') {
+      post('SET_PAUSE', { paused: true });
+      assetPausedByOverlay = true;
+    }
+  }
+
+  /** When the viewer cannot show it, show the tile that was already rendered, and say why. */
+  function showAssetThumbnailFallback(asset, hasPreview, reason) {
+    assetFrame.classList.add('hidden');
+    assetResetButton.classList.add('hidden');
+    if (hasPreview) {
+      assetImage.src = '/api/assets/preview/' + encodeURIComponent(asset.id) + '.png';
+      assetImage.classList.remove('hidden');
+    }
+    showAssetNote(reason);
+  }
+
+  function closeAssetDetail() {
+    if (!assetOverlay.classList.contains('show')) return false;
+    assetOverlay.classList.remove('show');
+    if (assetLoadTimer) clearTimeout(assetLoadTimer);
+    // about:blank rather than hiding it: an idle iframe would hold a WebGL context and a render
+    // loop for the rest of the session, next to the game that needs both.
+    assetFrame.src = 'about:blank';
+    assetImage.removeAttribute('src');
+    assetAudio.pause();
+    assetAudio.removeAttribute('src');
+    if (assetPausedByOverlay) {
+      post('SET_PAUSE', { paused: false });
+      assetPausedByOverlay = false;
+    }
+    if (assetReturnFocus && assetReturnFocus.focus) assetReturnFocus.focus();
+    assetReturnFocus = null;
+    return true;
+  }
+
+  /**
+   * Replies from the preview iframe, matched by SOURCE rather than by type.
+   *
+   * The message listener below resolves its waiters on type alone, so a second sender on this
+   * window could answer a request meant for the game. Today their vocabularies do not overlap;
+   * this is what keeps that from being a silent bug the day one of them gains a name the other
+   * already uses.
+   */
+  function onAssetPreviewMessage(message) {
+    if (message.type === 'ASSET_PREVIEW_READY') {
+      if (assetLoadTimer) clearTimeout(assetLoadTimer);
+      assetNote.classList.add('hidden');
+      if (typeof message.triangles === 'number' && message.triangles > 0) {
+        fact('Triangles', message.triangles.toLocaleString());
+      }
+    } else if (message.type === 'ASSET_PREVIEW_FAILED') {
+      if (assetLoadTimer) clearTimeout(assetLoadTimer);
+      assetFrame.src = 'about:blank';
+      showAssetNote(message.error || 'The preview could not be loaded.');
+    }
+  }
+
+  assetResetButton.addEventListener('click', function () {
+    if (assetFrame.contentWindow) {
+      assetFrame.contentWindow.postMessage({ type: 'RESET_VIEW' }, window.location.origin);
+    }
+  });
+  document.getElementById('asset-copy').addEventListener('click', function () {
+    var id = assetFacts.querySelector('dd.mono');
+    if (id && navigator.clipboard) void navigator.clipboard.writeText(id.textContent);
+  });
+  document.getElementById('asset-close').addEventListener('click', closeAssetDetail);
+  assetOverlay.addEventListener('mousedown', function (event) {
+    // mousedown, not click: a drag that starts inside the viewer and ends on the backdrop is a
+    // creator turning the model, not a creator dismissing the dialog.
+    if (event.target === assetOverlay) closeAssetDetail();
+  });
+
+  // The page had no keyboard handling at all before this, so #hq-overlay gains Escape with it.
+  document.addEventListener('keydown', function (event) {
+    if (event.key !== 'Escape') return;
+    if (closeAssetDetail()) return;
+    hqOverlay.classList.remove('show');
+  });
+
   /**
    * Lend the cached thumbnails to the engine's own asset palette.
    *

package/dist/editor/shell-page.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell-page.js","sourceRoot":"","sources":["../../src/editor/shell-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,oGAAoG;AACpG,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC,kGAAkG;AAClG,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3B,CAAC;AASD,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,MAAM,OAAO,GAAG,oBAAoB,OAAO,CAAC,QAAQ,2BAA2B,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IACpH,OAAO;;;;wBAIe,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBA8G3B,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAwD9B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;kBACxB,gBAAgB;yBACT,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgnC7C,CAAC;AACF,CAAC"}
+{"version":3,"file":"shell-page.js","sourceRoot":"","sources":["../../src/editor/shell-page.ts"],"names":[],"mappings":"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"}

package/dist/forge/progress.d.ts

@@ -25,7 +25,7 @@
  * (`ForgeTransportOptions.onProgress`), so the counts arrive as ordinary step events and the
  * second, parallel path is gone.
  */
-import { type ForgeProgressEvent, type ForgeProgressSummary, type ForgeStepKey } from '@bitmagic/world-forger/pipeline/index.js';
+import { type ForgeLayoutMap, type ForgeProgressEvent, type ForgeProgressSummary, type ForgeStepKey } from '@bitmagic/world-forger/pipeline/index.js';
 export type ForgeStepStatus = 'pending' | 'running' | 'done';
 export interface ForgeStepState {
     key: ForgeStepKey;
@@ -59,6 +59,14 @@ export interface ForgeProgressTrackerOptions {
     log: (message: string) => void;
     /** Job-record writer. Receives a fresh snapshot; may be omitted when nothing is watching. */
     report?: (snapshot: ForgeProgressSnapshot) => void;
+    /**
+     * The level's map, handed over the once it arrives.
+     *
+     * A separate sink rather than a field on the snapshot, and that is the point: the snapshot is
+     * rewritten on every tick, and ~25KB of raster in it would be rewritten with it for the rest of
+     * a thirty-minute run. Routing it out here makes "written once" structural.
+     */
+    onLayout?: (layout: ForgeLayoutMap) => void;
     now?: () => number;
     /** Overridden in tests. */
     logIntervalMs?: number;