@tileflow/dev 0.1.0-alpha.31 → 0.1.0-alpha.32

package/dist/preview.js

@@ -140,11 +140,67 @@ function normalizeTileflowLandmarkManifest(candidate, manifestUrl) {
   };
 }
 
+// src/preview-scene.ts
+var previewSceneClient = String.raw`
+        let sceneStyleRevision = 0;
+        globalThis.__tileflowApplyScene = async (serialized, isCurrent) => {
+          const next = JSON.parse(serialized);
+          if (next.style) {
+            // getStyle() retains renderer instrumentation on sources. It is not authored
+            // style-spec input; MapLibre adds it back from the map's timing option.
+            delete next.style.collectResourceTiming;
+            for (const source of Object.values(next.style.sources || {})) delete source.collectResourceTiming;
+            await loadTileflowStyleFonts(next.style, {fontFaces: previewFontFaces});
+          }
+          if (!isCurrent()) return false;
+          const context = map.getCanvas().getContext("webgl2") || map.getCanvas().getContext("webgl");
+          if (context?.isContextLost()) throw new Error("The map's graphics context is recovering. Try the change again.");
+          if (next.style) {
+            // MapLibre ignores metadata-only diffs. A global-state revision also commits the
+            // new 3D design metadata, without replacing sources, tiles or custom layers.
+            next.style.state = {...next.style.state, "tileflow:preview-revision": ++sceneStyleRevision};
+            const layerOrder = map.getLayersOrder();
+            map.setStyle(next.style, {diff:true});
+            // Custom layers are omitted from the serialized style. A diff can reinsert the
+            // surrounding style layers above them, covering 3D with the flat map. Restore
+            // their placement before the nearest surviving successor, without remounting.
+            let before;
+            for (let index = layerOrder.length - 1; index >= 0; index--) {
+              const id = layerOrder[index], layer = map.getLayer(id);
+              if (!layer) continue;
+              if (layer.type === "custom") map.moveLayer(id, before);
+              before = id;
+            }
+          }
+          previewSearchParameters.set("animation", String(next.animation));
+          previewSearchParameters.delete("trees3d");
+          const visibleTrees = map.getStyle()?.metadata?.["tileflow:vegetation-display"]?.visible ?? true;
+          threeDimensionalControl?.setEnabled(next.buildings3d);
+          treeControl?.setEnabled(visibleTrees);
+          mountCoreScene(map);
+          treeControl?.update();
+          updateGlobeBackdrop(map);
+          const url = new URL(location.href);
+          url.searchParams.delete("scene");
+          url.searchParams.set("map", next.map);
+          url.searchParams.set("theme", next.theme);
+          if (Object.keys(next.controls).length) url.searchParams.set("controls", JSON.stringify(next.controls));
+          else url.searchParams.delete("controls");
+          if (next.animation) url.searchParams.set("animation", String(next.animation));
+          else url.searchParams.delete("animation");
+          history.replaceState(history.state, "", url.href);
+          // Read the current camera here; a slow compile must never undo navigation.
+          writeCameraToUrl(map);
+          map.triggerRepaint();
+          return true;
+        };
+`;
+
 // src/preview-html.ts
-function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticPreview, fontFaces = []) {
-  const styleUrl = preview ? `${basePath}/styles/${preview.mapName}/${preview.themeName}.json` : void 0;
+function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticPreview, fontFaces = [], fitViewport = false, controls) {
+  const styleUrl = preview ? `${basePath}/styles/${preview.mapName}/${preview.themeName}.json${controls ? `?${new URLSearchParams({ controls })}` : ""}` : void 0;
   const mapOptions = preview ? previewMapOptions(preview) : void 0;
-  const viewportCss = preview?.viewport ? `
+  const viewportCss = preview?.viewport && !fitViewport ? `
       html, body { min-height: 100%; margin: 0; }
       body {
         display: grid;
@@ -168,7 +224,6 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       ${viewportCss}
       body { font-family: ui-sans-serif, system-ui, sans-serif; }
       #map {
-        --tileflow-globe-radius: 220px;
         background-color: var(--tileflow-space, #2F5070);
         background-image:
           radial-gradient(circle at 18% 24%, rgba(225, 240, 250, 0.34) 0 1px, transparent 1.4px),
@@ -184,22 +239,8 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           radial-gradient(circle at 72% 62%, rgba(225, 240, 250, 0.22) 0 1px, transparent 1.3px),
           radial-gradient(circle at 42% 78%, rgba(225, 240, 250, 0.18) 0 0.8px, transparent 1.2px);
       }
-      #map.tileflow-globe::before {
-        content: "";
-        position: absolute;
-        z-index: 0;
-        left: 50%;
-        top: 50%;
-        width: calc(var(--tileflow-globe-radius) * 2);
-        height: calc(var(--tileflow-globe-radius) * 2);
-        border: 1px solid var(--tileflow-rim-line, rgba(248, 252, 255, 0.88));
-        border-radius: 50%;
-        box-shadow:
-          0 0 9px 3px var(--tileflow-rim-core, rgba(248, 252, 255, 0.9)),
-          0 0 28px 10px var(--tileflow-rim-glow, rgba(176, 220, 246, 0.52)),
-          0 0 58px 20px var(--tileflow-rim-haze, rgba(132, 195, 232, 0.2));
-        pointer-events: none;
-        transform: translate(-50%, -50%);
+      #map.tileflow-globe .maplibregl-canvas {
+        filter: var(--tileflow-globe-rim, none);
       }
       #map.tileflow-globe > .maplibregl-canvas-container {
         position: relative;
@@ -233,6 +274,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         padding: 12px;
         white-space: pre-wrap;
       }
+      html[data-devtools-embedded=true] .status { display:none !important; }
       .maplibregl-ctrl-group .tileflow-3d-toggle,
       .maplibregl-ctrl-group .tileflow-tree-toggle,
       .maplibregl-ctrl-group .tileflow-theme-toggle {
@@ -253,6 +295,12 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       .maplibregl-ctrl-group .tileflow-theme-toggle:hover {
         background-color: #F1F3F4;
       }
+      .maplibregl-ctrl-group { background:#faf6eb; border:1px solid #e0d5c4; border-radius:3px; box-shadow:0 3px 12px #30251f18; }
+      .maplibregl-ctrl-group button { color:#30251f; }
+      .maplibregl-ctrl-group button + button { border-top-color:#e0d5c4; }
+      .maplibregl-ctrl-group .tileflow-3d-toggle,.maplibregl-ctrl-group .tileflow-tree-toggle,.maplibregl-ctrl-group .tileflow-theme-toggle { color:#30251f; font-weight:500; }
+      .maplibregl-ctrl-group .tileflow-3d-toggle[aria-pressed="true"],.maplibregl-ctrl-group .tileflow-tree-toggle[aria-pressed="true"] { background:#f0dfe0; color:#8c2e3f; }
+      .maplibregl-ctrl-group .tileflow-3d-toggle:hover,.maplibregl-ctrl-group .tileflow-tree-toggle:hover,.maplibregl-ctrl-group .tileflow-theme-toggle:hover { background:#eee4d3; }
     </style>
   </head>
   <body>
@@ -262,19 +310,25 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
     <script type="importmap">{"imports":{"fflate":"${basePath}/__runtime/fflate.js","three":"${basePath}/__runtime/three.module.js"}}</script>
     <script type="module">
       import * as maplibregl from "${basePath}/__runtime/maplibre-gl.mjs";
+      import {createPreviewObserver} from "${basePath}/__runtime/devtools-observer.js";
       import {loadTileflowStyleFonts} from "${basePath}/__runtime/tileflow-browser.js";
       import {registerTileflowContourProtocol} from "${basePath}/__runtime/tileflow-browser.js";
       import {registerTileflowPmtilesProtocol} from "${basePath}/__runtime/tileflow-browser.js";
-      import {createTileflowBuildings3D, createTileflowStreetLights, createTileflowTrees3D} from "${basePath}/__runtime/tileflow-browser.js";
+      import {createTileflowBuildings3D, createTileflowStreetLights, createTileflowVegetation} from "${basePath}/__runtime/tileflow-browser.js";
       import {readTileflowSunPreset, resolveTileflowSun, tileflowDefaultSunPreset} from "${basePath}/__runtime/tileflow-browser.js";
 
       maplibregl.setWorkerUrl("${basePath}/__runtime/maplibre-gl-worker.mjs");
 
+      const devtoolsObserver = window.parent !== window ? createPreviewObserver() : undefined;
+      globalThis.__tileflowDevtoolsObserver = devtoolsObserver;
+      if (window.parent !== window) document.documentElement.dataset.devtoolsEmbedded = "true";
+
       const initialStatus = ${JSON.stringify(initialStatus)};
       const normalizeTileflowLandmarkManifest = ${normalizeTileflowLandmarkManifest.toString()};
       const readBoundedTileflowResponse = ${readBoundedTileflowResponse.toString()};
       const readBoundedTileflowJsonResponse = ${readBoundedTileflowJsonResponse.toString()};
       const initialGeneration = initialStatus.generation;
+      document.documentElement.dataset.tileflowArtifactGeneration = String(initialStatus.lastGoodGeneration ?? initialGeneration);
       const badge = document.getElementById("badge");
       const status = document.getElementById("status");
       const previewLabel = ${JSON.stringify(preview?.label)};
@@ -319,7 +373,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         return fallback;
       }
       let threeDimensionalEnabled = readToggleFromUrl("buildings3d", false);
-      let treesEnabled = readToggleFromUrl("trees3d", false);
+      let treesEnabled = readToggleFromUrl("trees3d", true);
       const landmarkState = {
         active: [],
         cacheLimit: undefined,
@@ -940,14 +994,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           return;
         }
 
-        // A Web Mercator world is 512 * 2^zoom pixels wide. Dividing its
-        // circumference by 2\u03C0 closely tracks MapLibre's on-screen globe radius.
-        const radius = Math.min(
-          4096,
-          ((512 * Math.pow(2, map.getZoom())) / (2 * Math.PI)) * 0.91
-        );
         container.classList.add("tileflow-globe");
-        container.style.setProperty("--tileflow-globe-radius", radius.toFixed(2) + "px");
         applyAtmosphereBackdrop(map, container);
       }
 
@@ -961,12 +1008,16 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           const value = Number.parseInt(match[1], 16);
           return "rgba(" + (value >> 16) + ", " + ((value >> 8) & 255) + ", " + (value & 255) + ", " + alpha + ")";
         };
+        // Use the rendered canvas alpha, as the shared browser atmosphere does.
+        // A zoom-only circle cannot track the globe's latitude, viewport or pitch.
+        const opacity = Math.max(0, Math.min(1, (6 - map.getZoom()) / 3));
+        const core = rgba(atmosphere?.horizonColor ?? "#F8FCFF", opacity * 0.65);
+        const glow = rgba(atmosphere?.horizonColor ?? "#B0DCF6", opacity * 0.4);
         const properties = {
           "--tileflow-space": rgba(atmosphere?.spaceColor, 1),
-          "--tileflow-rim-line": rgba(atmosphere?.horizonColor, 0.88),
-          "--tileflow-rim-core": rgba(atmosphere?.horizonColor, 0.9),
-          "--tileflow-rim-glow": rgba(atmosphere?.horizonColor, 0.52),
-          "--tileflow-rim-haze": rgba(atmosphere?.skyColor, 0.35),
+          "--tileflow-globe-rim": opacity > 0
+            ? "drop-shadow(0 0 2px " + core + ") drop-shadow(0 0 12px " + glow + ")"
+            : "none",
         };
         for (const [name, value] of Object.entries(properties)) {
           if (value) container.style.setProperty(name, value);
@@ -1921,6 +1972,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           (layer) =>
             (layer.id.startsWith("tileflow-label-") &&
               !layer.id.startsWith("tileflow-label-road-")) ||
+            layer.id === "tileflow-poi" ||
             layer.id.startsWith("tileflow-poi-")
         )?.id;
         const treeLayer = map.getLayer("tileflow-vegetation-trees")
@@ -1930,11 +1982,25 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       }
 
       // Core's 3D layers, as an application mounts them: the map's style describes how its
-      // buildings, trees and street lights look, and the controls only show and hide them. With
-      // both controls off the preview draws what Capture draws. The preview shows one theme at a
+      // buildings, trees and street lights look, and the controls only show and hide them. The
+      // vegetation control hides all trees when off. The preview shows one theme at a
       // time, so the style on screen holds the sun and the design.
-      const coreScene = {buildings: undefined, trees: undefined, lights: undefined, buildingsShown: false, treesShown: false};
+      const coreScene = {buildings: undefined, trees: undefined, lights: undefined, buildingsShown: false, animation: "0"};
+      const runtimeLayerVisibility = {};
       globalThis.__tileflowPreviewScene = coreScene;
+      globalThis.__tileflowRuntimeVisibility = (id, visible) => {
+        if (!['tileflow-buildings-3d','tileflow-trees-3d','tileflow-street-lights'].includes(id)) return undefined;
+        if (typeof visible === 'boolean') { runtimeLayerVisibility[id]=visible; mountCoreScene(map); map.triggerRepaint(); }
+        return runtimeLayerVisibility[id] !== false;
+      };
+      // Explicit observation capability: controllers stay private to the preview and expose
+      // only their public state/statistics to the parent inspector.
+      globalThis.__tileflowInspectModels = () => [...(coreScene.buildings?.inspectModels?.() || []), ...(coreScene.trees?.inspectModels?.() || [])];
+      globalThis.__tileflowDescribeRuntimeLayers = () => ({
+        ...(coreScene.buildings ? {"tileflow-buildings-3d": {controller:"Buildings 3D", state:{visible:runtimeLayerVisibility["tileflow-buildings-3d"] !== false, shown:coreScene.buildingsShown, scale:coreScene.buildings.scale}, stats:coreScene.buildings.stats}} : {}),
+        ...(coreScene.trees ? {"tileflow-trees-3d": {controller:"Vegetation", state:{visible:runtimeLayerVisibility["tileflow-trees-3d"] !== false, representation:coreScene.trees.representation}, stats:coreScene.trees.stats}} : {}),
+        ...(coreScene.lights ? {"tileflow-street-lights": {controller:"Street lights", state:{visible:runtimeLayerVisibility["tileflow-street-lights"] !== false, mounted:true}, stats:coreScene.lights.stats}} : {})
+      });
       function coreSceneThemes(map) {
         return {
           getSun() {
@@ -1946,32 +2012,52 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           }
         };
       }
+      let mountingCoreScene = false;
       function mountCoreScene(map) {
-        const metadata = map.getStyle()?.metadata ?? {};
-        const controller = coreSceneThemes(map);
-        if (!coreScene.buildings && metadata["tileflow:buildings"]) {
-          coreScene.buildings = createTileflowBuildings3D({map, controller});
-        }
-        if (!coreScene.trees && metadata["tileflow:vegetation"]) {
-          coreScene.trees = createTileflowTrees3D({map, controller});
-        }
-        // Street lights have no capture fallback, so they shine only with the 3D control on.
-        if (!coreScene.lights && threeDimensionalEnabled && metadata["tileflow:street-lights"]) {
-          coreScene.lights = createTileflowStreetLights({map, controller});
-        } else if (coreScene.lights && !threeDimensionalEnabled) {
-          coreScene.lights.dispose();
-          coreScene.lights = undefined;
-        }
-        const instant = {transition: {duration: 0}};
-        // Only a change of the controls moves the layers, so a style event does not restart them.
-        if (coreScene.buildings && coreScene.buildingsShown !== threeDimensionalEnabled) {
-          coreScene.buildingsShown = threeDimensionalEnabled;
-          void (threeDimensionalEnabled ? coreScene.buildings.show() : coreScene.buildings.hide(instant));
-        }
-        if (coreScene.trees && coreScene.treesShown !== treesEnabled) {
-          coreScene.treesShown = treesEnabled;
-          void (treesEnabled ? coreScene.trees.show() : coreScene.trees.hide(instant));
-        }
+        if (mountingCoreScene) return;
+        mountingCoreScene = true;
+        try {
+          const metadata = map.getStyle()?.metadata ?? {};
+          const controller = coreSceneThemes(map);
+          if (!coreScene.buildings && metadata["tileflow:buildings"]) {
+            coreScene.buildings = createTileflowBuildings3D({map, controller});
+          }
+          if (!coreScene.trees) {
+            if (!previewSearchParameters.has("trees3d")) {
+              treesEnabled = metadata["tileflow:vegetation-display"]?.visible ?? true;
+            }
+            coreScene.trees = createTileflowVegetation({map, controller, visible: treesEnabled,
+              viewMode: threeDimensionalEnabled ? "3d" : "2d", transformRequest: previewTransformRequest});
+          }
+          coreScene.trees.setVisible(treesEnabled && runtimeLayerVisibility["tileflow-trees-3d"] !== false);
+          coreScene.trees.setViewMode(threeDimensionalEnabled ? "3d" : "2d");
+          // Street lights have no capture fallback, so they shine only with the 3D control on.
+          if (!coreScene.lights && threeDimensionalEnabled && metadata["tileflow:street-lights"]) {
+            coreScene.lights = createTileflowStreetLights({map, controller});
+          } else if (coreScene.lights && !threeDimensionalEnabled) {
+            coreScene.lights.dispose();
+            coreScene.lights = undefined;
+          }
+          const lightLayer = map.getLayer("tileflow-street-lights");
+          const lightRenderer = lightLayer?.implementation || lightLayer;
+          if (lightRenderer?.render && !lightRenderer.__previewVisibility) {
+            const render = lightRenderer.render;
+            lightRenderer.render = function(...args) {
+              if (runtimeLayerVisibility["tileflow-street-lights"] !== false) return render.apply(this,args);
+            };
+            lightRenderer.__previewVisibility = true;
+          }
+          const showBuildings = threeDimensionalEnabled && runtimeLayerVisibility["tileflow-buildings-3d"] !== false;
+          const instant = {transition: {duration: 0}};
+          const animation = previewSearchParameters.get('animation') || '0';
+          const duration = animation === 'fade' ? 800 : Math.min(3000, Math.max(0, Number(animation) || 0));
+          // Only a change of the controls moves the layers, so a style event does not restart them.
+          if (coreScene.buildings && (coreScene.buildingsShown !== showBuildings || coreScene.animation !== animation)) {
+            coreScene.buildingsShown = showBuildings;
+            coreScene.animation = animation;
+            void (showBuildings ? coreScene.buildings.show({transition: {duration, mode: animation === "fade" ? "fade" : "grow"}}) : coreScene.buildings.hide(instant));
+          }
+        } finally {mountingCoreScene = false;}
       }
 
       class ThreeDimensionalControl {
@@ -2076,18 +2162,11 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         }
 
         update() {
-          const treeLayer = this.map.getStyle()?.layers?.find(
-            (layer) => layer.id === "tileflow-vegetation-trees"
-          );
-          // Core's 3D trees hide the style's flat trees while they stand (mountCoreScene).
-          if (treeLayer && !this.map.getStyle()?.metadata?.["tileflow:vegetation"]) {
-            if (this.map.getLayoutProperty(treeLayer.id, "visibility") !== "visible") {
-              this.map.setLayoutProperty(treeLayer.id, "visibility", "visible");
-            }
-          }
+          if (this.map.isStyleLoaded()) mountCoreScene(this.map);
+          this.enabled = treesEnabled;
           this.button.textContent = this.enabled ? "TREES ON" : "TREES OFF";
           this.button.setAttribute("aria-pressed", String(this.enabled));
-          this.button.title = this.enabled ? "Show flat trees" : "Show 3D trees";
+          this.button.title = this.enabled ? "Hide vegetation" : "Show vegetation";
         }
 
         onRemove() {
@@ -2183,24 +2262,21 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
             ...visibleLayerGroups,
           ].join(",");
         }
+        const vegetationLayers = map.getStyle()?.metadata?.["tileflow:vegetation-display"]?.flatLayers;
         for (const layer of map.getStyle()?.layers || []) {
-          if (!defaultLayerVisibility.has(layer.id)) {
-            defaultLayerVisibility.set(
-              layer.id,
-              map.getLayoutProperty(layer.id, "visibility") || "visible"
-            );
-          }
           if (layer.type === "symbol" && layer.layout?.["text-field"] !== undefined) {
-            if (!defaultLayerTextField.has(layer.id)) {
+            const hideLabels = !visibleLayerGroups.has("labels");
+            if (hideLabels && !defaultLayerTextField.has(layer.id)) {
               defaultLayerTextField.set(
                 layer.id,
                 map.getLayoutProperty(layer.id, "text-field")
               );
             }
-            const textField = visibleLayerGroups.has("labels")
-              ? defaultLayerTextField.get(layer.id)
-              : "";
+            const restoreText = !hideLabels && defaultLayerTextField.has(layer.id);
+            const textField = hideLabels ? "" : defaultLayerTextField.get(layer.id);
+            if (restoreText) defaultLayerTextField.delete(layer.id);
             if (
+              (hideLabels || restoreText) &&
               !previewLayoutValuesEqual(
                 map.getLayoutProperty(layer.id, "text-field"),
                 textField
@@ -2209,21 +2285,29 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
               map.setLayoutProperty(layer.id, "text-field", textField);
             }
           }
+          // The shared vegetation controller owns every flat representation.
+          if (vegetationLayers?.some((entry) => entry.id === layer.id.split("::")[0])) continue;
           const groups = previewLayerGroups(layer);
+          const hideLayer = groups.some((group) => !visibleLayerGroups.has(group));
+          // Group controls only own the properties they mask. Ordinary style events must
+          // preserve temporary DevTools edits, including visibility and label text.
+          if (hideLayer && !defaultLayerVisibility.has(layer.id)) {
+            defaultLayerVisibility.set(layer.id, map.getLayoutProperty(layer.id, "visibility") || "visible");
+          }
+          if (!hideLayer && !defaultLayerVisibility.has(layer.id)) continue;
           const threeDimensionalToggle = layer.metadata?.["tileflow:3d-toggle"];
           const authoredVisibility = defaultLayerVisibility.get(layer.id);
+          if (!hideLayer) defaultLayerVisibility.delete(layer.id);
           const styleMetadata = map.getStyle()?.metadata ?? {};
           // Core's 3D buildings and trees stand in for compiled extrusions and flat trees.
-          const flatTrees = styleMetadata["tileflow:vegetation"]?.flatLayers ?? [];
           const replacedByCore =
-            (threeDimensionalToggle === "building" && styleMetadata["tileflow:buildings"]) ||
-            (treesEnabled && flatTrees.includes(layer.id.split("::")[0]));
+            threeDimensionalToggle === "building" && styleMetadata["tileflow:buildings"];
           const toggleVisibility = replacedByCore
             ? "none"
             : threeDimensionalToggle === "building" || threeDimensionalToggle === "landmark"
               ? (threeDimensionalEnabled ? "visible" : "none")
               : authoredVisibility;
-          const visibility = groups.some((group) => !visibleLayerGroups.has(group))
+          const visibility = hideLayer
             ? "none"
             : toggleVisibility;
           if (map.getLayoutProperty(layer.id, "visibility") !== visibility) {
@@ -2238,6 +2322,16 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         map.fire("tileflow:visible-layer-groups", {groups: [...visibleLayerGroups]});
       }
 
+      function previewTransformRequest(url) {
+        try {
+          return new URL(url, location.href).hostname === "dev-tiles.tileflow.dev"
+            ? {credentials: "include", url}
+            : {url};
+        } catch {
+          return {url};
+        }
+      }
+
       if (styleUrl) {
         // Dense vector tiles finish in bursts with multiple workers, causing several
         // bucket uploads in one frame. One worker keeps navigation smooth; benchmarks
@@ -2248,23 +2342,16 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         registerTileflowContourProtocol({addProtocol: maplibregl.addProtocol});
         registerTileflowPmtilesProtocol({addProtocol: maplibregl.addProtocol});
         const map = new maplibregl.Map({
-          collectResourceTiming: mapBenchmarkEnabled,
+          collectResourceTiming: mapBenchmarkEnabled || Boolean(devtoolsObserver),
           container: "map",
           style: styleUrl,
-          transformRequest: (url) => {
-            try {
-              return new URL(url, location.href).hostname === "dev-tiles.tileflow.dev"
-                ? {credentials: "include", url}
-                : {url};
-            } catch {
-              return {url};
-            }
-          },
+          transformRequest: previewTransformRequest,
           ...resolveInitialMapOptions(previewMapOptions)
         });
         globalThis.__tileflowPreviewMap = map;
+        devtoolsObserver?.attach(map);
         installMapBenchmark(map);
-        map.addControl(new maplibregl.NavigationControl(), "top-right");
+        if (window.parent === window) map.addControl(new maplibregl.NavigationControl(), "top-right");
         let threeDimensionalControl;
         let treeControl;
         if (isSemanticPreview) {
@@ -2272,8 +2359,16 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           treeControl = new TreeControl();
           map.addControl(threeDimensionalControl, "top-right");
           map.addControl(treeControl, "top-right");
+          // Embedded Map DevTools owns the common Controls sidebar. Keep the controls mounted
+          // for their renderer lifecycle and message bridge, but remove duplicate buttons.
+          if (window.parent !== window) {
+            threeDimensionalControl.container.hidden = true;
+            treeControl.container.hidden = true;
+          }
         }
-        if (previewThemes.length > 1) map.addControl(new ThemeControl(), "top-right");
+        // Map DevTools has a shared theme selector in its Controls panel; keep the map-level
+        // cycling button for standalone previews only.
+        if (previewThemes.length > 1 && window.parent === window) map.addControl(new ThemeControl(), "top-right");
         let ensuringThreeDimensionalLayers;
         const ensureThreeDimensionalLayers = () => {
           if (ensuringThreeDimensionalLayers) return ensuringThreeDimensionalLayers;
@@ -2360,13 +2455,16 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         map.on("tileflow:3d-toggle", ensureThreeDimensionalLayers);
         map.on("tileflow:trees-toggle", ensureThreeDimensionalLayers);
         map.on("load", () => {
+          mountCoreScene(map);
+          treeControl?.update();
           writeCameraToUrl(map);
           updateGlobeBackdrop(map);
           ensureThreeDimensionalLayers();
-          mountCoreScene(map);
         });
         map.on("move", () => updateGlobeBackdrop(map));
+        map.on("style.load", () => updateGlobeBackdrop(map));
         map.on("moveend", () => writeCameraToUrl(map));
+        ${previewSceneClient}
         addEventListener("message", (event) => {
           if (
             window.parent === window ||
@@ -2437,6 +2535,15 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       }
 
       applyStatus(initialStatus);
+      // Embedded previews share their host's stream. Two streams per tab can exhaust Chrome's
+      // six HTTP/1 connections and leave even local module/font requests waiting indefinitely.
+      let unsubscribePreviewStatus;
+      try {
+        if (window.parent !== window) unsubscribePreviewStatus = window.parent.__tileflowDevtoolsHost?.subscribePreviewStatus?.(window, applyStatus);
+      } catch { /* Other embedders keep the standalone stream. */ }
+      if (unsubscribePreviewStatus) {
+        addEventListener("beforeunload", unsubscribePreviewStatus);
+      } else {
       const events = new EventSource(${JSON.stringify(`${basePath}/__events`)});
       // Generations are monotonic only within one dev-server process. A source-code watcher can
       // restart that process at generation 1, so reconnecting after a live connection was lost
@@ -2457,6 +2564,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       for (const eventName of ["building", "ready", "invalid"]) {
         events.addEventListener(eventName, (event) => applyStatus(JSON.parse(event.data)));
       }
+      }
     </script>
   </body>
 </html>`;

package/dist/server.d.ts

@@ -5,7 +5,7 @@ import '@tileflow/core';
 import '@tileflow/core/build';
 import '@tileflow/core/manifest';
 import '@tileflow/core/native-profile';
-import './icons.js';
+import './icons-B84H8Ymu.js';
 import './config.js';
 
 declare const tileflowComparisonSchemaVersion: 1;
@@ -23,16 +23,21 @@ type TileflowComparisonSide = {
     /** Same-origin preview URL below basePath, including its map/theme query. */
     previewUrl: string;
 };
-type TileflowComparisonMode = 'blink' | 'overlay' | 'side-by-side' | 'split';
+type TileflowComparisonMode = 'single' | 'blink' | 'overlay' | 'side-by-side' | 'split';
 type TileflowComparisonOptions = {
     basePath?: string;
     initialMode?: TileflowComparisonMode;
     left: TileflowComparisonSide;
-    right: TileflowComparisonSide;
+    right?: TileflowComparisonSide;
     title?: string;
+    /** Optional local workflow adapter supplied by the CLI or an embedding server. */
+    workbench?: {
+        url: string;
+        handle: TileflowComparisonRequestHandler;
+    };
 };
 /**
- * Compose two existing Tileflow dev handlers behind one same-origin comparison shell.
+ * Compose one or two existing Tileflow dev handlers behind the same-origin Map DevTools.
  *
  * The side handlers retain ownership of styles, sprites, fonts, generations, live
  * events, and last-known-good behavior. This router owns only the shell document and
@@ -46,6 +51,8 @@ type TileflowDevRequestHandlerOptions = {
     config?: string;
     cwd?: string;
     inspection?: boolean;
+    /** Fit scene previews to their pane; capture retains the declared scene frame. */
+    fitViewport?: boolean;
     map?: string;
     onError?: (error: unknown) => void;
     scene?: string;