@loaders.gl/tiles 4.4.5 → 5.0.0-alpha.2

package/dist/tileset-3d/common/indexed-archive-tileset-source.d.ts

@@ -0,0 +1,60 @@
+import type { CoreAPI, LoaderOptions, LoaderWithParser, ReadableFile } from '@loaders.gl/loader-utils';
+import type { TilesetSourceResolver } from "./tileset-source.js";
+/** Options for {@link IndexedArchiveTilesetSource}. */
+export type IndexedArchiveTilesetSourceOptions<ArchiveT> = {
+    /** Archive URL or Blob. */
+    data: string | Blob;
+    /** Filename to expose for Blob inputs that do not provide a name. */
+    fallbackFilename: string;
+    /** Archive file extension used as the URL path marker. */
+    archiveExtension: string;
+    /** Path to the root metadata resource inside the archive. */
+    rootPath: string;
+    /** Optional mode passed when loading the root metadata resource. */
+    rootMode?: string;
+    /** Parses an opened readable file into an indexed archive object. */
+    parseArchive: (file: ReadableFile) => Promise<ArchiveT>;
+    /** Loads one resource from the parsed archive. */
+    getFile: (archive: ArchiveT, pathInArchive: string, mode?: string) => Promise<ArrayBuffer>;
+    /** Returns the core API used for local file loading and nested resource parsing. */
+    getCoreApi: () => CoreAPI | undefined;
+    /** Error message to throw when the core API is required but unavailable. */
+    missingCoreApiMessage: string;
+};
+/**
+ * Tileset source resolver backed by an indexed archive such as 3TZ or SLPK.
+ *
+ * The source owns archive opening, archive caching, path resolution, and archive-backed `fetch`
+ * injection. Format-specific parsing and file lookup stay in the owning format module.
+ */
+export declare class IndexedArchiveTilesetSource<ArchiveT> implements TilesetSourceResolver {
+    /** URL exposed to the tileset source that owns this archive source. */
+    readonly sourceUrl: string;
+    private readonly options;
+    private archivePromise?;
+    /**
+     * Creates an indexed archive tileset source.
+     * @param options Archive source options
+     */
+    constructor(options: IndexedArchiveTilesetSourceOptions<ArchiveT>);
+    /**
+     * Loads and parses the archive root metadata resource.
+     * @param url Root URL, ignored because the archive root path is configured explicitly
+     * @param loader Loader used to parse the root metadata
+     * @param loadOptions Loader options forwarded to parsing
+     */
+    loadRoot<DataT>(url: string, loader: LoaderWithParser<DataT>, loadOptions: LoaderOptions): Promise<DataT>;
+    /**
+     * Loads and parses an archive resource relative to a requesting resource URL.
+     * @param url Resource URL
+     * @param loader Loader used to parse the resource
+     * @param loadOptions Loader options forwarded to parsing
+     */
+    loadResource<DataT>(url: string, loader: LoaderWithParser<DataT>, loadOptions: LoaderOptions): Promise<DataT>;
+    private parseArchiveResource;
+    private createArchiveFetch;
+    private loadFile;
+    private openArchiveReadableFile;
+    private resolveArchivePath;
+}
+//# sourceMappingURL=indexed-archive-tileset-source.d.ts.map

package/dist/tileset-3d/common/indexed-archive-tileset-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexed-archive-tileset-source.d.ts","sourceRoot":"","sources":["../../../src/tileset-3d/common/indexed-archive-tileset-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAC,qBAAqB,EAAC,4BAAyB;AAE5D,uDAAuD;AACvD,MAAM,MAAM,kCAAkC,CAAC,QAAQ,IAAI;IACzD,2BAA2B;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxD,kDAAkD;IAClD,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3F,oFAAoF;IACpF,UAAU,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IACtC,4EAA4E;IAC5E,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,2BAA2B,CAAC,QAAQ,CAAE,YAAW,qBAAqB;IACjF,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;IACvE,OAAO,CAAC,cAAc,CAAC,CAAoB;IAE3C;;;OAGG;gBACS,OAAO,EAAE,kCAAkC,CAAC,QAAQ,CAAC;IAKjE;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC/B,WAAW,EAAE,aAAa,GACzB,OAAO,CAAC,KAAK,CAAC;IAUjB;;;;;OAKG;IACG,YAAY,CAAC,KAAK,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC/B,WAAW,EAAE,aAAa,GACzB,OAAO,CAAC,KAAK,CAAC;YAKH,oBAAoB;IA+BlC,OAAO,CAAC,kBAAkB;YAUZ,QAAQ;YAQR,uBAAuB;IAkBrC,OAAO,CAAC,kBAAkB;CA8B3B"}

package/dist/tileset-3d/common/indexed-archive-tileset-source.js

@@ -0,0 +1,125 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+import { BlobFile, HttpFile, path } from '@loaders.gl/loader-utils';
+/**
+ * Tileset source resolver backed by an indexed archive such as 3TZ or SLPK.
+ *
+ * The source owns archive opening, archive caching, path resolution, and archive-backed `fetch`
+ * injection. Format-specific parsing and file lookup stay in the owning format module.
+ */
+export class IndexedArchiveTilesetSource {
+    /** URL exposed to the tileset source that owns this archive source. */
+    sourceUrl;
+    options;
+    archivePromise;
+    /**
+     * Creates an indexed archive tileset source.
+     * @param options Archive source options
+     */
+    constructor(options) {
+        this.options = options;
+        this.sourceUrl = getArchiveSourceUrl(options.data, options.fallbackFilename);
+    }
+    /**
+     * Loads and parses the archive root metadata resource.
+     * @param url Root URL, ignored because the archive root path is configured explicitly
+     * @param loader Loader used to parse the root metadata
+     * @param loadOptions Loader options forwarded to parsing
+     */
+    async loadRoot(url, loader, loadOptions) {
+        return await this.parseArchiveResource(url, this.options.rootPath, loader, loadOptions, this.options.rootMode);
+    }
+    /**
+     * Loads and parses an archive resource relative to a requesting resource URL.
+     * @param url Resource URL
+     * @param loader Loader used to parse the resource
+     * @param loadOptions Loader options forwarded to parsing
+     */
+    async loadResource(url, loader, loadOptions) {
+        const pathInArchive = this.resolveArchivePath(url, url);
+        return await this.parseArchiveResource(url, pathInArchive, loader, loadOptions);
+    }
+    async parseArchiveResource(resourceUrl, pathInArchive, loader, loadOptions, mode) {
+        const coreApi = this.options.getCoreApi();
+        if (!coreApi) {
+            throw new Error(this.options.missingCoreApiMessage);
+        }
+        const data = await this.loadFile(pathInArchive, mode);
+        const archiveFetch = this.createArchiveFetch(resourceUrl);
+        return (await coreApi.parse(data, loader, {
+            ...loadOptions,
+            fetch: archiveFetch
+        }, {
+            url: resourceUrl,
+            fetch: archiveFetch,
+            _parse: coreApi.parse,
+            loaders: [loader],
+            coreApi
+        }));
+    }
+    createArchiveFetch(contextUrl) {
+        return async (input) => {
+            const requestUrl = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+            const pathInArchive = this.resolveArchivePath(requestUrl, contextUrl);
+            const data = await this.loadFile(pathInArchive);
+            return new Response(data, { status: 200 });
+        };
+    }
+    async loadFile(pathInArchive, mode) {
+        this.archivePromise ||= this.openArchiveReadableFile().then(file => this.options.parseArchive(file));
+        const archive = await this.archivePromise;
+        return await this.options.getFile(archive, pathInArchive, mode);
+    }
+    async openArchiveReadableFile() {
+        const { data } = this.options;
+        if (typeof data !== 'string') {
+            return new BlobFile(data);
+        }
+        if (/^https?:\/\//i.test(data)) {
+            return new HttpFile(data);
+        }
+        const coreApi = this.options.getCoreApi();
+        if (!coreApi) {
+            throw new Error(this.options.missingCoreApiMessage);
+        }
+        const response = await coreApi.fetchFile(data);
+        return new BlobFile(await response.arrayBuffer());
+    }
+    resolveArchivePath(request, baseUrl) {
+        const requestWithoutQuery = stripQueryString(request);
+        const archiveRoot = stripQueryString(this.sourceUrl);
+        const baseWithoutQuery = stripQueryString(baseUrl);
+        const basePath = baseWithoutQuery === archiveRoot ? archiveRoot : path.dirname(baseWithoutQuery);
+        const markerExpression = new RegExp(`\\.${this.options.archiveExtension}/(.*)$`, 'i');
+        const markerMatch = requestWithoutQuery.match(markerExpression);
+        if (markerMatch?.[1]) {
+            return markerMatch[1];
+        }
+        const isAbsoluteRequest = /^[a-z][a-z0-9+.-]*:/i.test(requestWithoutQuery) || requestWithoutQuery.startsWith('/');
+        const absoluteRequest = requestWithoutQuery.startsWith(archiveRoot)
+            ? requestWithoutQuery
+            : baseWithoutQuery === archiveRoot && !isAbsoluteRequest
+                ? `${archiveRoot}/${requestWithoutQuery}`
+                : path.resolve(basePath, requestWithoutQuery);
+        if (absoluteRequest === archiveRoot) {
+            return '';
+        }
+        if (absoluteRequest.startsWith(`${archiveRoot}/`)) {
+            return absoluteRequest.slice(archiveRoot.length + 1);
+        }
+        return absoluteRequest.replace(/^\/+/, '');
+    }
+}
+function getArchiveSourceUrl(data, fallbackFilename) {
+    if (typeof data === 'string') {
+        return data;
+    }
+    const fileName = 'name' in data && typeof data.name === 'string' && data.name ? data.name : fallbackFilename;
+    return `memory://${fileName}`;
+}
+function stripQueryString(url) {
+    const queryIndex = url.indexOf('?');
+    return queryIndex >= 0 ? url.slice(0, queryIndex) : url;
+}
+//# sourceMappingURL=indexed-archive-tileset-source.js.map

package/dist/tileset-3d/common/indexed-archive-tileset-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexed-archive-tileset-source.js","sourceRoot":"","sources":["../../../src/tileset-3d/common/indexed-archive-tileset-source.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,+BAA+B;AAC/B,oCAAoC;AAEpC,OAAO,EAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAC,MAAM,0BAA0B,CAAC;AA+BlE;;;;;GAKG;AACH,MAAM,OAAO,2BAA2B;IACtC,uEAAuE;IAC9D,SAAS,CAAS;IAEV,OAAO,CAA+C;IAC/D,cAAc,CAAqB;IAE3C;;;OAGG;IACH,YAAY,OAAqD;QAC/D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/E,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CACZ,GAAW,EACX,MAA+B,EAC/B,WAA0B;QAE1B,OAAO,MAAM,IAAI,CAAC,oBAAoB,CACpC,GAAG,EACH,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,MAAM,EACN,WAAW,EACX,IAAI,CAAC,OAAO,CAAC,QAAQ,CACtB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CAChB,GAAW,EACX,MAA+B,EAC/B,WAA0B;QAE1B,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxD,OAAO,MAAM,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAClF,CAAC;IAEO,KAAK,CAAC,oBAAoB,CAChC,WAAmB,EACnB,aAAqB,EACrB,MAA+B,EAC/B,WAA0B,EAC1B,IAAa;QAEb,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;QACtD,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACtD,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAC1D,OAAO,CAAC,MAAM,OAAO,CAAC,KAAK,CACzB,IAAI,EACJ,MAAM,EACN;YACE,GAAG,WAAW;YACd,KAAK,EAAE,YAAY;SACpB,EACD;YACE,GAAG,EAAE,WAAW;YAChB,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,OAAO,CAAC,KAAK;YACrB,OAAO,EAAE,CAAC,MAAM,CAAC;YACjB,OAAO;SACD,CACT,CAAU,CAAC;IACd,CAAC;IAEO,kBAAkB,CAAC,UAAkB;QAC3C,OAAO,KAAK,EAAE,KAAwB,EAAqB,EAAE;YAC3D,MAAM,UAAU,GACd,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;YAC1F,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACtE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;YAChD,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAC,MAAM,EAAE,GAAG,EAAC,CAAC,CAAC;QAC3C,CAAC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,QAAQ,CAAC,aAAqB,EAAE,IAAa;QACzD,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC,uBAAuB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACjE,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAChC,CAAC;QACF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC;QAC1C,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAEO,KAAK,CAAC,uBAAuB;QACnC,MAAM,EAAC,IAAI,EAAC,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAED,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/C,OAAO,IAAI,QAAQ,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IAEO,kBAAkB,CAAC,OAAe,EAAE,OAAe;QACzD,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,QAAQ,GACZ,gBAAgB,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAClF,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,gBAAgB,QAAQ,EAAE,GAAG,CAAC,CAAC;QACtF,MAAM,WAAW,GAAG,mBAAmB,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAChE,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;QAED,MAAM,iBAAiB,GACrB,sBAAsB,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,mBAAmB,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAC1F,MAAM,eAAe,GAAG,mBAAmB,CAAC,UAAU,CAAC,WAAW,CAAC;YACjE,CAAC,CAAC,mBAAmB;YACrB,CAAC,CAAC,gBAAgB,KAAK,WAAW,IAAI,CAAC,iBAAiB;gBACtD,CAAC,CAAC,GAAG,WAAW,IAAI,mBAAmB,EAAE;gBACzC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;QAElD,IAAI,eAAe,KAAK,WAAW,EAAE,CAAC;YACpC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,eAAe,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;YAClD,OAAO,eAAe,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,IAAmB,EAAE,gBAAwB;IACxE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GACZ,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAC9F,OAAO,YAAY,QAAQ,EAAE,CAAC;AAChC,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC1D,CAAC"}

package/dist/{tileset → tileset-3d/common}/tile-3d.d.ts

@@ -1,9 +1,10 @@
 import { Matrix4 } from '@math.gl/core';
 import type { Tileset3D } from "./tileset-3d.js";
-import type { DoublyLinkedListNode } from "../utils/doubly-linked-list-node.js";
-import { TILE_REFINEMENT } from "../constants.js";
-import { FrameState } from "./helpers/frame-state.js";
-import { CartographicBounds } from "./helpers/bounding-volume.js";
+import type { DoublyLinkedListNode } from "../../utils/doubly-linked-list-node.js";
+import { TILE_REFINEMENT } from "../../constants.js";
+import type { TileChildrenLoadResult, TileContentLoadResult } from "./tileset-source.js";
+import { FrameState } from "../helpers/frame-state.js";
+import { CartographicBounds } from "../helpers/bounding-volume.js";
 import { TilesetTraverser } from "./tileset-traverser.js";
 /**
  * @param tileset - Tileset3D instance
@@ -18,6 +19,8 @@ export type Tile3DProps = {
     parentHeader: Tile3D;
     extendedId: string;
 };
+/** Lifecycle of a source-managed lazy child-header group. */
+export type TileChildrenState = 'unloaded' | 'loading' | 'ready' | 'failed';
 /**
  * A Tile3DHeader represents a tile as Tileset3D. When a tile is first created, its content is not loaded;
  * the content is loaded on-demand when needed based on the view.
@@ -33,9 +36,17 @@ export declare class Tile3D {
     type: string;
     contentUrl: string;
     /** Different refinement algorithms used by I3S and 3D tiles */
-    lodMetricType: 'geometricError' | 'maxScreenThreshold';
-    /** The error, in meters, introduced if this tile is rendered and its children are not. */
+    lodMetricType: string;
+    /**
+     * The world-space geometric error, in meters, introduced if this tile is rendered and its
+     * children are not. For I3S this stores the format's unscaled screen-threshold metric instead.
+     */
     lodMetricValue: number;
+    /**
+     * The source LOD metric before applying the tile's computed transform. Keeping the source value
+     * separate ensures transform updates never compound an already-scaled geometric error.
+     */
+    private _unscaledLodMetricValue;
     /** @todo math.gl is not exporting BoundingVolume base type? */
     boundingVolume: any;
     /**
@@ -47,6 +58,8 @@ export declare class Tile3D {
     gpuMemoryUsageInBytes: number;
     /** The tile's children - an array of Tile3D objects. */
     children: Tile3D[];
+    /** Current lifecycle state for a lazy implicit subtree rooted at this tile. */
+    childrenState: TileChildrenState;
     depth: number;
     viewportIds: any[];
     transform: Matrix4;
@@ -64,10 +77,20 @@ export declare class Tile3D {
     private _frameNumber;
     private _expireDate;
     private _expiredContent;
+    /** In-flight source request shared by repeated traversal frames. */
+    private _childrenPromise;
     private _boundingBox?;
     /** updated every frame for tree traversal and rendering optimizations: */
     _distanceToCamera: number;
     _screenSpaceError: number;
+    /** SSE calculated at the reduced viewport height used to prioritize coarse coverage. */
+    _screenSpaceErrorProgressiveResolution: number;
+    /** Whether this tile should be promoted into the progressive-resolution request pass. */
+    _priorityProgressiveResolution: boolean;
+    /** Angular distance from the camera view axis used to prioritize center tiles. */
+    _foveatedFactor: number;
+    /** Whether this peripheral request is currently inside the camera-motion deferral window. */
+    priorityDeferred: boolean;
     private _visibilityPlaneMask;
     private _visible;
     private _contentBoundingVolume;
@@ -112,6 +135,10 @@ export declare class Tile3D {
     get hasRenderContent(): boolean;
     /** Returns true if tile has children */
     get hasChildren(): any;
+    /** Returns whether traversal may request an unresolved lazy child-header group. */
+    get hasUnloadedChildren(): boolean;
+    /** Returns whether a lazy child-header request is currently in flight. */
+    get childrenLoading(): boolean;
     /**
      * Determines if the tile's content is ready. This is automatically `true` for
      * tiles with empty content.
@@ -148,8 +175,18 @@ export declare class Tile3D {
      * @returns [min, max] each in [longitude, latitude, altitude]
      */
     get boundingBox(): CartographicBounds;
-    /** Get the tile's screen space error. */
-    getScreenSpaceError(frameState: any, useParentLodMetric: any): number;
+    /**
+     * Gets the tile's screen-space error for normal refinement or a reduced-height priority pass.
+     *
+     * I3S already supplies a screen-oriented LOD metric and intentionally ignores the optional 3D
+     * Tiles progressive-resolution height fraction.
+     *
+     * @param frameState - Current camera and viewport measurements.
+     * @param useParentLodMetric - Whether to substitute the parent LOD metric.
+     * @param viewportHeightFraction - Fraction of viewport height represented by the priority pass.
+     * @returns Screen-space LOD error for the current tileset format.
+     */
+    getScreenSpaceError(frameState: any, useParentLodMetric: any, viewportHeightFraction?: number): number;
     /**
      * Make tile unselected than means it won't be shown
      * but it can be still loaded in memory
@@ -159,12 +196,62 @@ export declare class Tile3D {
      * Memory usage of tile on GPU
      */
     _getGpuMemoryUsageInBytes(): number;
+    /**
+     * Returns scheduler priority for render-content requests.
+     *
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
     _getPriority(): number;
+    /**
+     * Returns scheduler priority for lazy child-header requests.
+     *
+     * Contentless implicit placeholders intentionally retain `UNLOADED` content state, so metadata
+     * scheduling skips only that render-content cancellation check and preserves every visibility,
+     * recency, progressive, foveated, and motion-deferral rule.
+     *
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
+    private _getChildrenPriority;
+    /**
+     * Calculates the common scheduler priority for content or hierarchy metadata.
+     *
+     * @param allowUnloadedContent - Whether an empty placeholder may request child metadata.
+     * @returns Numeric priority, or a negative value when the queued request should be cancelled.
+     */
+    private _calculateRequestPriority;
     /**
      *  Requests the tile's content.
      * The request may not be made if the Request Scheduler can't prioritize it.
      */
-    loadContent(): Promise<boolean>;
+    loadContent(): Promise<TileContentLoadResult>;
+    /**
+     * Requests and installs this tile's lazy child-header group through its source.
+     *
+     * The same request scheduler and SSE/foveated priority value used for render content are reused
+     * for subtree metadata. Repeated traversal frames share one promise, and scheduler cancellation
+     * restores the unloaded state so a later frame can retry.
+     *
+     * @param frameState - View state that made the subtree eligible for refinement.
+     * @returns Source load result, or an unloaded result if scheduling was cancelled.
+     */
+    loadChildren(frameState: FrameState): Promise<TileChildrenLoadResult>;
+    /**
+     * Runs one lazy child-header load after obtaining a scheduler token.
+     *
+     * @param frameState - View state forwarded to the source implementation.
+     * @returns Source load result.
+     */
+    private _loadChildrenWithScheduler;
+    /**
+     * Replaces a contentless implicit placeholder with its materialized subtree-root header.
+     *
+     * Transform state is intentionally preserved: the placeholder already owns the composed
+     * transform, and reapplying the root transform here would double-transform bounds and geometric
+     * error. Content and raw geometric error are reinitialized from the newly available header.
+     *
+     * @param materializedHeader - Available root header produced from one subtree resource.
+     */
+    applyImplicitSubtreeHeader(materializedHeader: Record<string, any>): void;
     unloadContent(): boolean;
     /**
      * Update the tile's visibility
@@ -173,6 +260,16 @@ export declare class Tile3D {
      * @return {void}
      */
     updateVisibility(frameState: any, viewportIds: any): void;
+    /**
+     * Updates progressive-resolution and foveated request metrics for a 3D Tiles traversal frame.
+     *
+     * I3S retains its format-specific screen-threshold ordering and is explicitly isolated from
+     * geometric-error scheduling. Orthographic viewports still receive progressive coverage, but
+     * angular foveation is disabled because an orthographic frustum has no perspective field of view.
+     *
+     * @param frameState - Current camera and viewport measurements.
+     */
+    _updateRequestPriorityMetrics(frameState: FrameState): void;
     visibility(frameState: any, parentVisibilityPlaneMask: any): any;
     contentVisibility(): boolean;
     /**
@@ -197,34 +294,41 @@ export declare class Tile3D {
     insideViewerRequestVolume(frameState: FrameState): boolean;
     updateExpiration(): void;
     get extras(): any;
-    _initializeLodMetric(header: any): void;
+    /** Initializes the tile's LOD metric from its header or its nearest available ancestor. */
+    _initializeLodMetric(header: {
+        [key: string]: any;
+    }): void;
     _initializeTransforms(tileHeader: any): void;
+    /**
+     * Updates the world-space LOD metric from the source metric and the complete tile transform.
+     *
+     * 3D Tiles geometric error is a distance in the tile's local meters. Screen-space error (SSE)
+     * compares that distance with a world-space camera distance, so both quantities must use the
+     * same scale. For non-uniform transforms the largest axis scale is deliberately used: this is
+     * conservative and prevents refinement from stopping while any transformed dimension can still
+     * exceed the requested visual error. Rotation and translation do not affect the scale.
+     *
+     * I3S `maxScreenThreshold` is already a screen-space metric and must not be transform-scaled.
+     */
+    _updateLodMetricScale(): void;
     _initializeBoundingVolumes(tileHeader: any): void;
     _initializeContent(tileHeader: any): void;
     _initializeRenderingState(header: any): void;
     _getRefine(refine: any): any;
+    /**
+     * Returns whether loaded content is an external tileset.
+     *
+     * Parsed shape is authoritative because valid external resources may be extensionless, signed,
+     * or use a misleading filename. This method is called only after source loading has populated
+     * `content`.
+     */
     _isTileset(): boolean;
     _onContentLoaded(): void;
     _updateBoundingVolume(header: any): void;
+    /**
+     * Updates the tile's computed transform, world-space geometric error, and bounding volumes.
+     * @param parentTransform - Current computed transform of the parent tile or tileset.
+     */
     _updateTransform(parentTransform?: Matrix4): void;
-    _getLoaderSpecificOptions(loaderId: any): {
-        assetGltfUpAxis: "X" | "Y" | "Z";
-    } | {
-        _tileOptions: {
-            attributeUrls: any;
-            textureUrl: any;
-            textureFormat: any;
-            textureLoaderOptions: any;
-            materialDefinition: any;
-            isDracoGeometry: any;
-            mbs: any;
-        };
-        _tilesetOptions: {
-            store: any;
-            attributeStorageInfo: any;
-            fields: any;
-        };
-        isTileHeader: boolean;
-    };
 }
 //# sourceMappingURL=tile-3d.d.ts.map

package/dist/tileset-3d/common/tile-3d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tile-3d.d.ts","sourceRoot":"","sources":["../../../src/tileset-3d/common/tile-3d.ts"],"names":[],"mappings":"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"}