@bitmagic/cli 0.1.22 → 0.1.24

package/dist/editor/shell-page.js

@@ -1,5 +1,5 @@
 /**
- * The editor shell: the page that plays the Creator's role for a CLI-lane project.
+ * The dev view: the page that plays the Creator's role for a CLI-lane project.
  *
  * The whole feature rests on one fact — the visual editor is ALREADY in every scaffolded project.
  * `VENDORED_DIRS` in `scaffold/project.ts` ships `engine/editor/` and `engine/debug/`, and
@@ -12,6 +12,25 @@
  * plain `tsc`, which copies no static files. `smoke/harness.ts` and `scaffold/project-files.ts`
  * both do the same.
  *
+ * ── One iframe, two tabs ─────────────────────────────────────────────────────────────────────
+ *
+ * **Game** and **Editor** are the same loaded world in two engine modes, not two pages. A second
+ * iframe would mean a second WebGL context and a second copy of the world on a creator's laptop,
+ * and switching would cost a full reload each way — which defeats the point of having both in one
+ * window. So a tab switch is three postMessages, and play state survives a trip to the editor.
+ *
+ * The exact sequences are in `applyTab()`, and each line of them is load-bearing:
+ *   - `SET_EDITOR_MODE {enabled:false}` alone does NOT give you the game back. It restores the
+ *     camera and player controls (`EditorManager.disableEditorMode`) but leaves the HUD hidden —
+ *     hiding it is `EditorTabHandler`'s job, keyed on the *tab*, so undoing it needs
+ *     `SET_EDITOR_TAB {tab:'prompt'}`.
+ *   - `LOAD_GAME {skipMenu:true}` leaves the engine in READY, not PLAYING (`showEditorPreview`).
+ *     The Game tab therefore has to `START_GAME` the first time; only afterwards is unpausing the
+ *     right move.
+ *   - Pointer lock cannot be taken from here — a parent-frame message grants the iframe no user
+ *     activation. `enterPlayingMode` knows that and shows its own overlay, so the creator's first
+ *     click inside the game captures the mouse. Same as the web Creator.
+ *
  * ── Four things that fail silently if changed ────────────────────────────────────────────────
  *
  *  1. `?source=creator` on the iframe URL. Without it `isCreatorMode` is false
@@ -20,10 +39,10 @@
  *  2. `GAME_TEMPLATE_READY` must arrive before `LOAD_GAME` is posted. The engine registers its
  *     listener only after `await initI18n()`, and a `LOAD_GAME` landing before that is DROPPED,
  *     not queued — the symptom is a game that never loads, pointing at the wrong culprit.
- *  3. `REQUEST_ASSETS` / `ADD_OBJECT` / `MARK_OBJECT_MODIFIED` use a FLAT envelope
- *     (`{ type, assets }`), not the `{ type, data }` one the rest of the protocol uses. That is
- *     the Creator's existing shape (`useIframeMessages.ts:1149`, `:332`) and the engine reads the
- *     fields off the message directly.
+ *  3. `REQUEST_ASSETS` / `ADD_OBJECT` / `MARK_OBJECT_MODIFIED` / `GAME_STATE_CHANGED` use a FLAT
+ *     envelope (`{ type, assets }`), not the `{ type, data }` one the rest of the protocol uses.
+ *     That is the Creator's existing shape (`useIframeMessages.ts:1149`, `:332`) and the engine
+ *     reads the fields off the message directly.
  *  4. The autosave poll, rather than an event. `TransformControlsManager`'s mouseUp reaches
  *     `EditorManager.commitTransformChange()`, which only mutates a `Set` — the engine posts
  *     nothing. Polling `CHECK_SCENE_CHANGES` is what the Creator does too, just on tab switch
@@ -31,6 +50,14 @@
  */
 /** How often the shell asks the engine whether anything changed. A `Set` read; effectively free. */
 const POLL_INTERVAL_MS = 500;
+/**
+ * How recently a scene save must have landed for the creator to count as "still working".
+ *
+ * An auto-reload during a gizmo drag throws the drag away, and the shell cannot see a drag: the
+ * iframe is cross-origin, so there is no mousedown to watch. The last save is the closest visible
+ * proxy for a hand on the mouse, and the cost of being wrong is only a banner instead of a reload.
+ */
+const ACTIVE_EDIT_WINDOW_MS = 3000;
 /** Attribute-safe. `gameId` comes from `bitmagic.json`, but it lands inside an HTML attribute. */
 function escapeAttr(value) {
     return value
@@ -45,11 +72,11 @@ export function renderEditorShell(options) {
 <html lang="en">
 <head>
 <meta charset="utf-8">
-<title>bitmagic edit — ${escapeAttr(options.gameId)}</title>
+<title>bitmagic dev — ${escapeAttr(options.gameId)}</title>
 <style>
   :root { color-scheme: dark; }
   * { box-sizing: border-box; }
-  /* Flex column rather than calc() heights: the banners come and go, and two of them at once
+  /* Flex column rather than calc() heights: the banners come and go, and three of them at once
      must not push the viewport into a scrollbar. */
   body { margin: 0; height: 100vh; display: flex; flex-direction: column;
          background: #101014; color: #e6e6ea; font: 13px/1.45 ui-sans-serif, system-ui, sans-serif; }
@@ -57,18 +84,29 @@ export function renderEditorShell(options) {
          background: #17171d; border-bottom: 1px solid #26262e; }
   #bar .id { color: #8a8a99; font-family: ui-monospace, monospace; }
   #bar .spacer { flex: 1; }
+  #tabs { display: flex; gap: 2px; background: #101014; border: 1px solid #26262e; border-radius: 6px;
+          padding: 2px; }
+  .tab { background: transparent; border: 0; border-radius: 4px; color: #9a9aab; padding: 3px 14px;
+         font: inherit; cursor: pointer; }
+  .tab:hover { color: #e6e6ea; background: #22222a; }
+  .tab.active { background: #3352c4; color: #fff; }
   #status { display: flex; align-items: center; gap: 6px; }
   #dot { width: 8px; height: 8px; border-radius: 50%; background: #4a4a57; }
   #dot.saving { background: #d9a441; }
   #dot.saved  { background: #4caf72; }
   #dot.error  { background: #e0564f; }
+  #auto { display: flex; align-items: center; gap: 5px; color: #8a8a99; cursor: pointer; }
+  #auto input { margin: 0; }
   button { background: #26262e; color: #e6e6ea; border: 1px solid #34343f; border-radius: 5px;
            padding: 4px 10px; font: inherit; cursor: pointer; }
   button:hover { background: #30303a; }
+  #tabs .tab:hover { background: #22222a; }
+  #tabs .tab.active:hover { background: #3352c4; }
   .banner { display: none; align-items: center; gap: 12px; flex: none; padding: 8px 12px;
             background: #3a2c12; border-bottom: 1px solid #574018; color: #f0d9a8; }
   .banner.show { display: flex; }
-  #terrain-banner { background: #3d1f1c; border-bottom-color: #6b2f28; color: #f3c3bd; }
+  #terrain-banner, #build-banner { background: #3d1f1c; border-bottom-color: #6b2f28; color: #f3c3bd; }
+  #build-banner code { font-family: ui-monospace, monospace; }
   #frame { display: block; flex: 1; width: 100%; border: 0; min-height: 0; }
   #hq-overlay { display: none; position: fixed; inset: 0; background: rgba(8,8,12,.72);
                 align-items: center; justify-content: center; z-index: 10; }
@@ -89,19 +127,30 @@ export function renderEditorShell(options) {
 </head>
 <body>
   <div id="bar">
-    <strong>bitmagic edit</strong>
+    <strong>bitmagic dev</strong>
     <span class="id">${escapeAttr(options.gameId)}</span>
+    <div id="tabs">
+      <button class="tab active" type="button" data-tab="game">Game</button>
+      <button class="tab" type="button" data-tab="editor">Editor</button>
+    </div>
     <span class="spacer"></span>
+    <label id="auto" title="Reload the game when the project changes on disk">
+      <input id="auto-toggle" type="checkbox" checked> Auto-reload
+    </label>
     <span id="status"><span id="dot"></span><span id="status-text">Loading…</span></span>
     <button id="reload" type="button">Reload</button>
   </div>
+  <div id="build-banner" class="banner">
+    <span id="build-message"></span>
+    <span>The game still shows the last build that compiled.</span>
+  </div>
   <div id="banner" class="banner">
     <span>src/work/world.json changed on disk — this scene is out of date.</span>
     <button id="banner-reload" type="button">Reload scene</button>
   </div>
   <div id="terrain-banner" class="banner">
     <span><strong>Terrain edits are not saved yet.</strong>
-      Sculpting the ground needs an asset upload that <code>bitmagic edit</code> does not do — these
+      Sculpting the ground needs an asset upload that <code>bitmagic dev</code> does not do — these
       voxel changes will be lost. Discard them, or press Cancel in the terrain toolbar.</span>
     <button id="terrain-discard" type="button">Discard terrain edits</button>
   </div>
@@ -127,23 +176,51 @@ export function renderEditorShell(options) {
   'use strict';
   var GAME_URL = ${JSON.stringify(gameUrl)};
   var POLL_MS = ${POLL_INTERVAL_MS};
+  var ACTIVE_EDIT_MS = ${ACTIVE_EDIT_WINDOW_MS};
+  var TAB_KEY = 'bitmagic.dev.tab';
+  var AUTO_KEY = 'bitmagic.dev.autoReload';
 
   var frame = document.getElementById('frame');
   var dot = document.getElementById('dot');
   var statusText = document.getElementById('status-text');
   var banner = document.getElementById('banner');
   var terrainBanner = document.getElementById('terrain-banner');
+  var buildBanner = document.getElementById('build-banner');
+  var autoToggle = document.getElementById('auto-toggle');
 
   var loaded = false;
   var saving = false;
   var markersDirty = false;
   var lastKnownMtime = 0;
   var pollTimer = null;
+  // Retires the running poll on its own schedule; see stopLoop(). Distinct from 'generation',
+  // which retires a boot — a tab switch changes what the loop does without reloading anything.
+  var loopToken = 0;
   var waiters = [];
-  // Bumped by reload(). Every async step checks it, so a reload triggered mid-boot cannot leave
+  // Bumped by start(). Every async step checks it, so a reload triggered mid-boot cannot leave
   // two polling loops running against one iframe.
   var generation = 0;
 
+  // The engine's own view of itself, from GAME_STATE_CHANGED. The Game tab needs it to tell
+  // "never started" (START_GAME) from "paused for the editor" (unpause) — see applyTab.
+  var gameState = '';
+  var activeTab = 'game';
+  var autoReload = true;
+  // When a scene save last landed. See ACTIVE_EDIT_WINDOW_MS.
+  var lastLocalEditAt = 0;
+
+  // localStorage is unavailable in some privacy modes, and losing a preference must not lose the
+  // page. Defaults below are the ones a first-time creator gets anyway.
+  function readPref(key, fallback) {
+    try {
+      var stored = window.localStorage.getItem(key);
+      return stored === null ? fallback : stored;
+    } catch (error) { return fallback; }
+  }
+  function writePref(key, value) {
+    try { window.localStorage.setItem(key, value); } catch (error) { /* see readPref */ }
+  }
+
   function setStatus(kind, text) {
     dot.className = kind || '';
     statusText.textContent = text;
@@ -184,6 +261,21 @@ export function renderEditorShell(options) {
     }
 
     switch (message.type) {
+      case 'GAME_STATE_CHANGED':
+        gameState = message.state || '';
+        if (activeTab === 'game' && loaded) {
+          setStatus(gameState === 'playing' ? 'saved' : '', gameState === 'playing' ? 'Playing' : 'Ready');
+        }
+        break;
+
+      case 'TAB_SWITCH_BLOCKED':
+        // The engine refuses to leave a tab with unsaved terrain changes
+        // (GameRuntimeController.canSwitchToEditorTab). applyTab checks for that first, so this is
+        // the backstop for a race — put the creator back where the engine actually is.
+        selectTab('editor', { fromEngine: true });
+        terrainBanner.classList.add('show');
+        break;
+
       case 'REQUEST_ASSETS':
         // Re-read rather than serving the copy captured at boot: an agent may have generated an
         // asset since this page loaded, and a stale list is an empty asset palette with no
@@ -332,10 +424,12 @@ export function renderEditorShell(options) {
         setStatus('error', 'Generation failed');
         return;
       }
-      showHqNote(job.message + ' Reload to see it in the scene.', '');
+      showHqNote(job.message + ' Reloading to show it.', '');
       setStatus('saved', 'Generated');
       // The asset changed under the running engine, so the open scene is showing the old mesh.
-      banner.classList.add('show');
+      // The generation wrote world.json through the sidecar, which suppresses its own writes from
+      // the watcher, so this is the only thing that will bring the new mesh in.
+      if (autoReload) start(); else banner.classList.add('show');
     };
     void tick();
   }
@@ -345,9 +439,82 @@ export function renderEditorShell(options) {
     void confirmHq();
   });
 
+  /**
+   * Put the engine into the mode the given tab means.
+   *
+   * Order is not cosmetic in either direction — see the "One iframe, two tabs" note in this file's
+   * header for what each message is actually undoing.
+   */
+  function applyTab(tab) {
+    if (tab === 'editor') {
+      // Mirrors the Creator's enterEditorMode(): pause, turn the editor on (this is what unpacks
+      // InstancedMeshes so clicks can hit an individual instance), then configure the free camera
+      // and hide the HUD.
+      post('SET_PAUSE', { paused: true });
+      post('SET_EDITOR_MODE', { enabled: true });
+      post('SET_EDITOR_TAB', { tab: 'scene' });
+      setStatus('saved', 'Ready');
+      return;
+    }
+
+    terrainBanner.classList.remove('show');
+    var resumable = gameState === 'playing' || gameState === 'paused';
+    if (resumable) {
+      // Unpause BEFORE the tab message: SET_EDITOR_TAB 'prompt' enables player controls only when
+      // the engine already considers itself playing, so the other order leaves a running game the
+      // creator cannot steer.
+      post('SET_PAUSE', { paused: false });
+      post('SET_EDITOR_MODE', { enabled: false });
+      post('SET_EDITOR_TAB', { tab: 'prompt' });
+    } else {
+      // Never started: LOAD_GAME with skipMenu leaves the engine in READY, so there is nothing to
+      // unpause and the Play button is what we are standing in for.
+      post('SET_EDITOR_MODE', { enabled: false });
+      post('SET_EDITOR_TAB', { tab: 'prompt' });
+      post('START_GAME');
+    }
+    setStatus('saved', 'Playing');
+    // Without this the first keypress goes to the shell, not the game.
+    frame.focus();
+  }
+
+  /**
+   * Switch tabs, saving anything the editor was holding first.
+   *
+   * The terrain check is a precondition rather than a reaction: the engine refuses to leave a tab
+   * with unsaved voxel edits, and finding that out from TAB_SWITCH_BLOCKED means having already
+   * sent SET_EDITOR_MODE — leaving the editor half off, with no HUD and no gizmo.
+   */
+  async function selectTab(tab, options) {
+    var fromEngine = options && options.fromEngine === true;
+    if (tab === activeTab && !fromEngine) return;
+
+    if (activeTab === 'editor' && tab === 'game' && loaded && !fromEngine) {
+      await flush();
+      post('CHECK_TERRAIN_CHANGES');
+      var terrain = await await_('TERRAIN_HAS_CHANGES', 2000);
+      if (terrain && terrain.hasChanges === true) {
+        terrainBanner.classList.add('show');
+        return;
+      }
+    }
+
+    activeTab = tab;
+    writePref(TAB_KEY, tab);
+    var buttons = document.querySelectorAll('.tab');
+    for (var i = 0; i < buttons.length; i++) {
+      buttons[i].classList.toggle('active', buttons[i].getAttribute('data-tab') === tab);
+    }
+    if (!loaded) return;
+    applyTab(tab);
+    // One loop for both tabs; the work inside it is what differs (see runLoop()).
+    runLoop();
+  }
+
   async function boot(gen) {
     loaded = false;
     markersDirty = false;
+    gameState = '';
     banner.classList.remove('show');
     terrainBanner.classList.remove('show');
     setStatus('', 'Loading…');
@@ -372,7 +539,15 @@ export function renderEditorShell(options) {
       setStatus('error', 'The game never finished booting — try "bitmagic verify"');
       return;
     }
-    post('LOAD_GAME', { gameId: project.gameId, gameData: project.gameData, skipMenu: true });
+    // currentTab is honoured by the engine's own LOAD_GAME handler, which sets the camera and
+    // player controls for it — so booting straight into the right mode rather than correcting it
+    // afterwards.
+    post('LOAD_GAME', {
+      gameId: project.gameId,
+      gameData: project.gameData,
+      skipMenu: true,
+      currentTab: activeTab === 'editor' ? 'scene' : 'prompt'
+    });
     var started = await gameLoaded;
     if (gen !== generation) return;
     if (!started) {
@@ -380,15 +555,8 @@ export function renderEditorShell(options) {
       return;
     }
 
-    // Mirrors the Creator's enterEditorMode(): pause, turn the editor on (this is what unpacks
-    // InstancedMeshes so clicks can hit an individual instance), then configure the free camera
-    // and hide the HUD.
-    post('SET_PAUSE', { paused: true });
-    post('SET_EDITOR_MODE', { enabled: true });
-    post('SET_EDITOR_TAB', { tab: 'scene' });
-
     loaded = true;
-    setStatus('saved', 'Ready');
+    applyTab(activeTab);
   }
 
   async function flush() {
@@ -418,6 +586,7 @@ export function renderEditorShell(options) {
       }
       lastKnownMtime = result.worldMtimeMs || lastKnownMtime;
       markersDirty = false;
+      if (result.applied > 0) lastLocalEditAt = Date.now();
       // Only once the write landed: clearing earlier would drop the edit on a failed save.
       post('CLEAR_SCENE_CHANGES');
       setStatus('saved', result.applied > 0 ? 'Saved to world.json' : 'Ready');
@@ -448,16 +617,21 @@ export function renderEditorShell(options) {
     terrainBanner.classList.toggle('show', terrain.hasChanges === true);
   }
 
+  /**
+   * The pre-SSE way of noticing an agent's edit, kept as the fallback for a dropped stream.
+   *
+   * EventSource reconnects on its own, but a reload signal sent while it was down is simply gone —
+   * there is no replay. This poll is what closes that hole, and it costs one stat() per tick.
+   */
   async function checkExternalEdits() {
     if (!loaded || saving) return;
     try {
       var state = await (await fetch('/api/state')).json();
       // Anything other than the mtime our own last write produced is someone else's edit — most
-      // likely the creator's agent. Offer a reload rather than taking one: an unprompted reload
-      // would discard a drag in progress.
+      // likely the creator's agent.
       if (state.worldMtimeMs && state.worldMtimeMs !== lastKnownMtime
           && state.worldMtimeMs !== state.lastWrittenMtimeMs) {
-        banner.classList.add('show');
+        onChangeSignal('world.json');
       }
     } catch (error) {
       // The sidecar is this page's own server; if it is gone the reload button is the only
@@ -465,30 +639,115 @@ export function renderEditorShell(options) {
     }
   }
 
+  /**
+   * Something changed on disk. Reload, or explain why we did not.
+   *
+   * The two refusals are the same judgement the banner has always encoded: an unprompted reload
+   * that discards work the creator can see themselves doing is worse than a stale frame with a
+   * button on it. What changed is who is usually writing — an agent, not the human — so the
+   * default flipped from "always ask" to "ask only when the human is in the middle of something".
+   */
+  function onChangeSignal(reason) {
+    // Logged because "why did my game just reload?" is otherwise unanswerable from the browser.
+    console.log('[bitmagic dev] change signalled:', reason);
+    if (!autoReload) { banner.classList.add('show'); return; }
+    if (activeTab === 'editor' && (saving || Date.now() - lastLocalEditAt < ACTIVE_EDIT_MS)) {
+      banner.classList.add('show');
+      return;
+    }
+    start();
+  }
+
+  /**
+   * Retire the running poll.
+   *
+   * The token, rather than clearTimeout alone: a tick that is mid-await ignores a cleared timer and
+   * schedules the next one anyway, so a reload or a tab switch during one would leave two loops
+   * against a single iframe — each saving the same scene changes the other just cleared.
+   */
+  function stopLoop() {
+    loopToken += 1;
+    if (pollTimer) clearTimeout(pollTimer);
+    pollTimer = null;
+  }
+
   // One serial loop rather than two timers: a flush and an mtime check must never overlap, or the
   // check reads the mtime of a write that has not finished being accounted for.
-  async function loop(gen) {
-    if (gen !== generation) return;
-    await flush();
-    await checkTerrainEdits();
-    await checkExternalEdits();
-    if (gen !== generation) return;
-    pollTimer = setTimeout(function () { loop(gen); }, POLL_MS);
+  function runLoop() {
+    stopLoop();
+    var token = loopToken;
+    void (async function tick() {
+      if (token !== loopToken) return;
+      // The Game tab has nothing to save and no gizmo to warn about; only the disk check applies
+      // there, and only as the SSE fallback.
+      if (activeTab === 'editor') {
+        await flush();
+        await checkTerrainEdits();
+      }
+      await checkExternalEdits();
+      if (token !== loopToken) return;
+      pollTimer = setTimeout(tick, POLL_MS);
+    })();
   }
 
   function start() {
-    if (pollTimer) clearTimeout(pollTimer);
+    stopLoop();
     var gen = ++generation;
-    boot(gen).then(function () { loop(gen); });
+    boot(gen).then(function () {
+      if (gen === generation) runLoop();
+    });
+  }
+
+  /**
+   * The push channel (editor/reload-bus.ts). EventSource reconnects by itself, so there is no retry
+   * loop here — a dropped stream degrades to the mtime poll above until the browser reopens it.
+   */
+  function listenForEvents() {
+    var events = new EventSource('/api/events/stream');
+    events.addEventListener('reload', function (event) {
+      var payload = {};
+      try { payload = JSON.parse(event.data); } catch (error) { /* reason is a label */ }
+      onChangeSignal(payload.reason || 'change');
+    });
+    events.addEventListener('build', function (event) {
+      var payload = {};
+      try { payload = JSON.parse(event.data); } catch (error) { /* see above */ }
+      if (payload.status === 'failed') {
+        document.getElementById('build-message').textContent = payload.message || 'The build failed.';
+        buildBanner.classList.add('show');
+        setStatus('error', 'Build failed');
+        return;
+      }
+      buildBanner.classList.remove('show');
+      if (payload.status === 'building') setStatus('saving', 'Building…');
+    });
   }
 
-  document.getElementById('reload').addEventListener('click', start);
-  document.getElementById('banner-reload').addEventListener('click', start);
+  document.getElementById('reload').addEventListener('click', function () { start(); });
+  document.getElementById('banner-reload').addEventListener('click', function () { start(); });
   document.getElementById('terrain-discard').addEventListener('click', function () {
     post('REVERT_TERRAIN_CHANGES');
     terrainBanner.classList.remove('show');
   });
+  var tabButtons = document.querySelectorAll('.tab');
+  for (var t = 0; t < tabButtons.length; t++) {
+    tabButtons[t].addEventListener('click', function (event) {
+      void selectTab(event.currentTarget.getAttribute('data-tab'), {});
+    });
+  }
+  autoToggle.addEventListener('change', function () {
+    autoReload = autoToggle.checked;
+    writePref(AUTO_KEY, autoReload ? '1' : '0');
+    if (autoReload) banner.classList.remove('show');
+  });
 
+  autoReload = readPref(AUTO_KEY, '1') !== '0';
+  autoToggle.checked = autoReload;
+  // Applied through selectTab so the button states and the stored preference cannot disagree with
+  // the variable. 'loaded' is false here, so it only sets up the UI — boot() applies the mode.
+  activeTab = readPref(TAB_KEY, 'game') === 'editor' ? 'editor' : 'game';
+  void selectTab(activeTab, { fromEngine: true });
+  listenForEvents();
   start();
 })();
 </script>

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,oGAAoG;AACpG,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,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;;;;yBAIgB,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBA6C5B,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAmC9B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;kBACxB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgXjC,CAAC;AACF,CAAC"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAwD3B,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA8C9B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;kBACxB,gBAAgB;yBACT,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAikB7C,CAAC;AACF,CAAC"}

package/dist/editor/watch.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Deciding *when* the browser should reload.
+ *
+ * The hard part is not noticing a change — `fs.watch` does that — it is not reloading at the wrong
+ * moment. Three wrong moments, each of which this file exists to avoid:
+ *
+ *  1. **Mid-burst.** An agent editing five files produces five reloads unless the writes are let
+ *     go quiet first. Hence the debounce.
+ *  2. **Mid-compile.** A `.ts` edit changes `src/` long before `tsc --watch` finishes emitting
+ *     `dist/`, and every module the project loads resolves into `dist/`. Reloading on the source
+ *     write shows the creator the *old* build and reads as "my change did nothing". Hence the
+ *     compile gate: reloads are held while a compile is open and released when it lands clean.
+ *  3. **After a failed compile.** `dist/` still holds the last good emit, so a reload would show
+ *     working code for broken source — the most confusing outcome of the three. The pending reload
+ *     is dropped and the shell is told the build failed instead.
+ *
+ * `ReloadCoordinator` holds all of that and touches no I/O, so it is testable with fake timers and
+ * no filesystem. `watchProject` and `pipeTscWatch` are the thin I/O shells that feed it.
+ */
+import { type ChildProcess } from 'child_process';
+import type { BuildStatus } from './reload-bus.js';
+/**
+ * How long the writes must stay quiet before a reload fires.
+ *
+ * Long enough that `tsc --watch` (which has its own ~250 ms debounce before it reports
+ * `File change detected`) has almost always opened its compile by the time this elapses, so the
+ * gate below actually gets to hold the reload. Too short and a `.ts` edit produces two reloads —
+ * one stale, one correct — instead of one.
+ */
+export declare const RELOAD_QUIET_MS = 700;
+/**
+ * How long after one of our own writes to ignore file events.
+ *
+ * `/api/scene/save` and the HQ generation both write `world.json`, and a reload fired at the
+ * creator's own gizmo drag would throw away the drag that caused it. `fs.watch` delivers
+ * asynchronously but promptly, so this only has to outlast the delivery, not the write.
+ */
+export declare const OWN_WRITE_GRACE_MS = 400;
+export interface ReloadCoordinatorOptions {
+    onReload: (reason: string) => void;
+    onBuild: (status: BuildStatus, message?: string) => void;
+    quietMs?: number;
+}
+export declare class ReloadCoordinator {
+    private readonly options;
+    private timer;
+    private pendingReason;
+    private compiling;
+    private suppressUntil;
+    private stopped;
+    constructor(options: ReloadCoordinatorOptions);
+    /** A file under a watched directory changed. Arms — or re-arms — the quiet window. */
+    noteFileChange(reason: string): void;
+    /**
+     * Reload as soon as it is safe to — now, or the moment the compile in flight lands clean.
+     *
+     * The wait is the whole point for `bitmagic reload`: an agent's stop hook fires immediately after
+     * its last edit, which is precisely when `tsc` is still compiling it. Returns whether the reload
+     * was queued behind a compile rather than sent, so the command can say which happened.
+     */
+    requestNow(reason: string): {
+        queued: boolean;
+    };
+    /** The sidecar wrote `world.json` itself; the resulting file events are not news. */
+    noteOwnWrite(): void;
+    noteCompileStart(): void;
+    noteCompileEnd(errorCount: number): void;
+    stop(): void;
+    /** Send the pending reload, unless a compile is still open — then it waits for `noteCompileEnd`. */
+    private release;
+}
+export interface ProjectWatcher {
+    close(): void;
+}
+/**
+ * Watch the two directories that decide what the browser shows: `src/` (what the agent and the
+ * creator edit — including `work/world.json`) and `dist/` (what the page actually loads).
+ *
+ * `dist/` is watched as well as `src/` even though the compile gate already covers the normal
+ * `tsc --watch` path, because it is what a build run outside this process — a manual `tsc`, an
+ * editor's own compiler — lands in, and that should reach the browser too.
+ *
+ * A directory that cannot be watched is skipped with a note rather than failing the command: a
+ * missing `dist/` means "not built yet", and losing auto-reload is a smaller loss than losing
+ * `bitmagic dev`.
+ */
+export declare function watchProject(root: string, coordinator: ReloadCoordinator, log: (message: string) => void): ProjectWatcher;
+/**
+ * Feed one line of `tsc --watch` output to the coordinator. Exported for its test — the markers are
+ * tsc's own wording, and a version that changes them would otherwise break auto-reload silently.
+ */
+export declare function noteTscLine(line: string, coordinator: ReloadCoordinator): void;
+/**
+ * Spawn `tsc --watch` with its output piped through us instead of inherited.
+ *
+ * Piping is what makes the compile gate possible — the only signal that a build finished, and
+ * whether it finished clean, is tsc's own `Found N errors` line. Every line is re-echoed verbatim,
+ * so the creator sees exactly what an inherited stdio would have shown, and `--pretty` is forced
+ * back on when our own stdout is a terminal (tsc drops colour the moment it is piped).
+ */
+export declare function pipeTscWatch(tsc: string, cwd: string, coordinator: ReloadCoordinator): ChildProcess;