Extracts optional production debug code to an asynchronously loaded debug module

GitOrigin-RevId: 0753cdaab1204ef1d564d16cf85e56ee9611b88f

Author: dcoj

modules/debug.ts

@@ -0,0 +1,7 @@
+// UMD/CDN entry: the Debug namespace is available synchronously at import time,
+// and `prepareDebug()` is a no-op that resolves immediately. The Rollup
+// `esm-substitution-resolver` plugin swaps this file for `debug_esm.ts` in ESM
+// builds, where the debug chunk is dynamically imported instead.
+export {DebugModule} from './debug_imports';
+
+export async function prepareDebug() { return Promise.resolve(); }

modules/debug_esm.ts

@@ -0,0 +1,21 @@
+import {warnOnce} from '../src/util/util';
+
+import type {DebugModule as DebugModuleType} from './debug_imports';
+
+// ESM entry: the DebugModule namespace starts out empty. `prepareDebug()` dynamically
+// imports the debug chunk and copies the validators onto `DebugModule` in place, so
+// callers that captured a reference to `DebugModule` before loading see the populated
+// surface afterwards.
+export const DebugModule: Partial<typeof DebugModuleType> = {loaded: false};
+
+let pending: Promise<void> | null = null;
+
+export function prepareDebug(): Promise<void> {
+    if (pending !== null) return pending;
+    pending = import('./debug_imports').then(({DebugModule: loaded}) => {
+        Object.assign(DebugModule, loaded);
+    }).catch(() => {
+        warnOnce('Could not load Debug module; style validation is disabled.');
+    });
+    return pending;
+}

modules/debug_imports.ts

@@ -0,0 +1,50 @@
+// Non-production code paths: style-spec validators, the style-diff algorithm,
+// and the debug-overlay draw functions. Lifted out of `core.js` so consumers
+// that disable validation (`{validate: false}`), never call
+// `setStyle(..., {diff: true})` after initial load, and never toggle any
+// `map.show*` debug flag never download these ~25KB gz.
+//
+// Importing this file is what causes Rollup to emit the `debug.js` chunk
+// (see chunkFileNames in rollup.config.esm.ts).
+import {
+    validateStyle,
+    validateSource,
+    validateLight,
+    validateLights,
+    validateTerrain,
+    validateFog,
+    validateSnow,
+    validateRain,
+    validateLayer,
+    validateFilter,
+    validatePaintProperty,
+    validateLayoutProperty,
+    validateModel,
+} from '../src/style-spec/validate_style.min';
+import diffStyles from '../src/style-spec/diff';
+import drawDebug, {drawDebugPadding, drawDebugQueryGeometry} from '../src/render/draw_debug';
+import drawCollisionDebug from '../src/render/draw_collision_debug';
+
+// Named `DebugModule` (not `Debug`) so call sites aren't stripped out by the
+// Rollup config for prod builds.
+export const DebugModule = {
+    loaded: true,
+    validateStyle,
+    validateSource,
+    validateLight,
+    validateLights,
+    validateTerrain,
+    validateFog,
+    validateSnow,
+    validateRain,
+    validateLayer,
+    validateFilter,
+    validatePaintProperty,
+    validateLayoutProperty,
+    validateModel,
+    diffStyles,
+    drawDebug,
+    drawDebugPadding,
+    drawDebugQueryGeometry,
+    drawCollisionDebug,
+};

package.json

@@ -230,6 +230,11 @@
         "dist/esm/*.js"
       ]
     },
+    {
+      "limit": "50 kb",
+      "name": "Debug Module (brotli)",
+      "path": "dist/esm/debug.js"
+    },
     {
       "gzip": true,
       "limit": "600 kb",

rollup.config.esm.ts

@@ -28,6 +28,7 @@ function esmConfig(dir: string, workerSuffix: string, emitVisualizer = false): R
                     if (chunk.facadeModuleId.endsWith('hd_worker_imports.ts')) return 'hd.worker.js';
                     if (chunk.facadeModuleId.endsWith('standard_main_imports.ts')) return 'standard.shared.js';
                     if (chunk.facadeModuleId.endsWith('standard_worker_imports.ts')) return 'standard.worker.js';
+                    if (chunk.facadeModuleId.endsWith('debug_imports.ts')) return 'debug.js';
                 }
                 // Identify each code-split chunk by a foundational module/file rather than by
                 // chunk.name, which is derived from rollup's representative-module selection
@@ -92,7 +93,7 @@ export default (): RollupOptions[] => {
     ];
 };
 
-const filesToSub = new Set(['hd_main', 'hd_worker', 'standard_main', 'standard_worker']);
+const filesToSub = new Set(['hd_main', 'hd_worker', 'standard_main', 'standard_worker', 'debug']);
 
 function esmSubstitutions(workerSuffix: string): Plugin {
     return {

src/render/draw_symbol.ts

@@ -1,5 +1,5 @@
 import Point from '@mapbox/point-geometry';
-import drawCollisionDebug from './draw_collision_debug';
+import {DebugModule} from '../../modules/debug';
 import SegmentVector from '../data/segment';
 import * as symbolProjection from '../symbol/projection';
 import {mat4, vec3, vec4} from 'gl-matrix';
@@ -111,12 +111,12 @@ function drawSymbols(painter: Painter, sourceCache: SourceCache, layer: SymbolSt
         }
     }
 
-    if (sourceCache.map.showCollisionBoxes) {
+    if (sourceCache.map.showCollisionBoxes && DebugModule.drawCollisionDebug) {
 
-        drawCollisionDebug(painter, sourceCache, layer, coords, layer.paint.get('text-translate'),
+        DebugModule.drawCollisionDebug(painter, sourceCache, layer, coords, layer.paint.get('text-translate'),
             layer.paint.get('text-translate-anchor'), true);
 
-        drawCollisionDebug(painter, sourceCache, layer, coords, layer.paint.get('icon-translate'),
+        DebugModule.drawCollisionDebug(painter, sourceCache, layer, coords, layer.paint.get('icon-translate'),
             layer.paint.get('icon-translate-anchor'), false);
     }
 }

src/render/painter.ts

@@ -32,7 +32,7 @@ import {HD, prepareHD} from '../../modules/hd_main';
 import hillshade from './draw_hillshade';
 import raster, {prepare as prepareRaster} from './draw_raster';
 import background from './draw_background';
-import {default as drawDebug, drawDebugPadding, drawDebugQueryGeometry} from './draw_debug';
+import {DebugModule} from '../../modules/debug';
 import custom from './draw_custom';
 import sky from './draw_sky';
 import Atmosphere from './draw_atmosphere';
@@ -1531,16 +1531,16 @@ class Painter {
                 }
             });
             if (selectedSource) {
-                if (this.options.showTileBoundaries) {
+                if (this.options.showTileBoundaries && DebugModule.drawDebug) {
                     // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
-                    drawDebug(this, selectedSource, selectedSource.getVisibleCoordinates(), Color.red, false, this.options.showParseStatus);
+                    DebugModule.drawDebug(this, selectedSource, selectedSource.getVisibleCoordinates(), Color.red, false, this.options.showParseStatus);
                 }
 
                 Debug.run(() => {
                     if (!selectedSource) return;
-                    if (this.options.showQueryGeometry) {
+                    if (this.options.showQueryGeometry && DebugModule.drawDebugQueryGeometry) {
                         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
-                        drawDebugQueryGeometry(this, selectedSource, selectedSource.getVisibleCoordinates());
+                        DebugModule.drawDebugQueryGeometry(this, selectedSource, selectedSource.getVisibleCoordinates());
                     }
                     if (this.options.showTileAABBs) {
                         // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
@@ -1551,13 +1551,13 @@ class Painter {
         }
 
         Debug.run(() => {
-            if (this.terrain && this._debugParams.showTerrainProxyTiles) {
-                drawDebug(this, this.terrain.proxySourceCache, this.terrain.proxyCoords, new Color(1.0, 0.8, 0.1, 1.0), true, this.options.showParseStatus);
+            if (this.terrain && this._debugParams.showTerrainProxyTiles && DebugModule.drawDebug) {
+                DebugModule.drawDebug(this, this.terrain.proxySourceCache, this.terrain.proxyCoords, new Color(1.0, 0.8, 0.1, 1.0), true, this.options.showParseStatus);
             }
         });
 
-        if (this.options.showPadding) {
-            drawDebugPadding(this);
+        if (this.options.showPadding && DebugModule.drawDebugPadding) {
+            DebugModule.drawDebugPadding(this);
         }
 
         // Set defaults for most GL values so that anyone using the state after the render

src/style/style.ts

@@ -12,7 +12,7 @@ import Terrain, {DrapeRenderMode} from './terrain';
 import Fog from './fog';
 import Snow from './snow';
 import Rain from './rain';
-import {pick, clone, deepEqual, filterObject, cartesianPositionToSpherical, warnOnce} from '../util/util';
+import {clone, deepEqual, filterObject, cartesianPositionToSpherical, warnOnce} from '../util/util';
 import {getJSON, getReferrer, ResourceType} from '../util/ajax';
 import {isMapboxURL} from '../util/mapbox_url';
 import {stripQueryParameters} from '../util/url';
@@ -26,6 +26,7 @@ import {createExpression} from '../style-spec/expression/index';
 import {HD, prepareHD as prepareHDMain} from '../../modules/hd_main';
 import {prepareStandard as prepareStandardMain} from '../../modules/standard_main';
 import {HD_ROAD_COVERAGE_SOURCE_LAYER} from '../source/frc_coverage_snapshot';
+import {DebugModule, prepareDebug} from '../../modules/debug';
 import {
     validateStyle,
     validateLayoutProperty,
@@ -52,7 +53,6 @@ import styleSpec from '../style-spec/reference/latest';
 import {getGlobalWorkerPool as getWorkerPool} from '../util/worker_pool_factory';
 import deref from '../style-spec/deref';
 import emptyStyle from '../style-spec/empty';
-import diffStyles, {operations as diffOperations} from '../style-spec/diff';
 import {
     registerForPluginStateChange,
     evented as rtlTextPluginEvented,
@@ -177,7 +177,9 @@ const createConfigExpression = (option: OptionSpecification, value: unknown) =>
     return createExpression(value, propertySpec);
 };
 
-const supportedDiffOperations = pick(diffOperations, [
+// Operations the diff algorithm may emit that we handle incrementally without a full restyle.
+// Maintained as a plain Set of string constants — see src/style-spec/diff.ts.
+const supportedDiffOperations: ReadonlySet<string> = new Set([
     'addLayer',
     'removeLayer',
     'setLights',
@@ -207,7 +209,7 @@ const supportedDiffOperations = pick(diffOperations, [
     // 'setSprite',
 ]);
 
-const ignoredDiffOperations = pick(diffOperations, [
+const ignoredDiffOperations: ReadonlySet<string> = new Set([
     'setCenter',
     'setZoom',
     'setBearing',
@@ -645,6 +647,11 @@ class Style extends Evented<MapEvents> {
     _diffStyle(style: StyleSpecification | string, onStarted: (err: Error | null, isUpdateNeeded: boolean) => void, onFinished?: () => void) {
         this.globalId = this._getGlobalId(style);
 
+        // Fetch dev chunk, for string/URL path the fetch parallelises with the JSON request;
+        // for object path, validation will run synchronously and no-op for the first call
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        prepareDebug();
+
         const handleStyle = (json: StyleSpecification, callback: (err: Error | null, isUpdateNeeded: boolean) => void) => {
             try {
                 callback(null, this.setState(json, onFinished));
@@ -684,12 +691,18 @@ class Style extends Evented<MapEvents> {
         const validate = typeof options.validate === 'boolean' ?
             options.validate : !isMapboxURL(url);
 
+        // Preload the dev-chunk fetch with the style JSON
+        // correctness is enforced via await in `_load`
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        if (validate) prepareDebug();
+
         this.globalId = this._getGlobalId(url);
         url = this.map._requestManager.normalizeStyleURL(url, options.accessToken);
         this.resolvedImports.add(url);
 
         const cachedImport = this.importsCache.get(url);
-        if (cachedImport) return this._load(cachedImport, validate);
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        if (cachedImport) { this._load(cachedImport, validate); return; }
 
         const controller = new AbortController();
         this._request = {cancel: () => controller.abort()};
@@ -698,6 +711,7 @@ class Style extends Evented<MapEvents> {
             const {data: json} = await getJSON<StyleSpecification>(request, controller.signal);
             this._request = null;
             this.importsCache.set(url, json);
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
             this._load(json, validate);
         };
         load().catch((err: Error) => {
@@ -709,15 +723,23 @@ class Style extends Evented<MapEvents> {
     loadJSON(json: StyleSpecification, options: StyleSetterOptions = {}): void {
         this.fire(new Event('dataloading', {dataType: 'style'}));
 
+        const validate = options.validate !== false;
+        // Preload the dev-chunk fetch with the browser.frame()
+        // correctness is enforced via await in `_load`
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        if (validate) prepareDebug();
+
         this.globalId = this._getGlobalId(json);
         this._request = browser.frame(() => {
             this._request = null;
-            this._load(json, options.validate !== false);
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            this._load(json, validate);
         });
     }
 
     loadEmpty() {
         this.fire(new Event('dataloading', {dataType: 'style'}));
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
         this._load(empty, false);
     }
 
@@ -764,7 +786,12 @@ class Style extends Evented<MapEvents> {
                     // unnecessary animation frame delay when the data is already available.
                     style.fire(new Event('dataloading', {dataType: 'style'}));
                     style.globalId = style._getGlobalId(json);
-                    queueMicrotask(() => style._load(json, validate));
+                    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                    if (validate) prepareDebug();
+                    queueMicrotask(() => {
+                        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                        style._load(json, validate);
+                    });
                 } else {
                     style.loadJSON(json, {validate});
                 }
@@ -896,7 +923,7 @@ class Style extends Evented<MapEvents> {
         return this.isRootStyle() && (json.fragment || (!!json.schema && json.fragment !== false));
     }
 
-    _load(json: StyleSpecification, validate: boolean) {
+    async _load(json: StyleSpecification, validate: boolean) {
         // This style was loaded as a root style, but it is marked as a fragment and/or has a schema. We instead load
         // it as an import with the well-known ID "basemap" to make sure that we don't expose the internals.
         if (this._isInternalStyle(json)) {
@@ -907,14 +934,23 @@ class Style extends Evented<MapEvents> {
                 ...(json.zoom ? {zoom: json.zoom} : {}),
                 ...(json.light ? {light: json.light} : {})}) as StyleSpecification;
             this._importedAsBasemap = true;
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
             this._load(style, validate);
             return;
         }
 
         this.updateConfig(this._config, json.schema);
 
-        if (validate && emitValidationErrors(this, validateStyle(json))) {
-            return;
+        // In ESM builds, the dev chunk (validators) is dynamically imported.
+        // Await it before validating top-level style JSON so the call below
+        // is meaningful — `validateStyle` no-ops when `Debug` isn't loaded yet.
+        if (validate) {
+            await prepareDebug();
+            // Check the map wasn't removed while awaiting the dev chunk.
+            if (!this.dispatcher.actors.length) return;
+            if (emitValidationErrors(this, validateStyle(json))) {
+                return;
+            }
         }
 
         this._loaded = true;
@@ -2233,14 +2269,19 @@ class Style extends Evented<MapEvents> {
         nextState = clone(nextState);
         nextState.layers = deref(nextState.layers);
 
-        const changes = diffStyles(this.serialize(), nextState)
-            .filter(op => !(op.command in ignoredDiffOperations));
+        // `DebugModule.diffStyles` should be preloaded by `_diffStyle` before this runs
+        // otherwise throw so `_diffStyle`'s try/catch falls back to full restyle
+        if (!DebugModule.diffStyles) {
+            throw new Error('Debug module not loaded; cannot diff style.');
+        }
+        const changes = DebugModule.diffStyles(this.serialize(), nextState)
+            .filter(op => !ignoredDiffOperations.has(op.command));
 
         if (changes.length === 0) {
             return false;
         }
 
-        const unimplementedOps = changes.filter(op => !(op.command in supportedDiffOperations));
+        const unimplementedOps = changes.filter(op => !supportedDiffOperations.has(op.command));
         if (unimplementedOps.length > 0) {
             throw new Error(`Unimplemented: ${unimplementedOps.map(op => op.command).join(', ')}.`);
         }