visgl · ibgreen · Mar 30, 2026 · Mar 23, 2026 · Mar 23, 2026 · Mar 23, 2026
diff --git a/docs/README.mdx b/docs/README.mdx
@@ -35,7 +35,7 @@ loaders.gl provides a wide selection of loaders organized into categories:
 | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | [Table Loaders](/docs/specifications/category-table)              | Streaming tabular loaders for [CSV](/docs/modules/csv/api-reference/csv-loader), [JSON](/docs/modules/json/api-reference/json-loader), [Arrow](/docs/modules/arrow/api-reference/arrow-loader) etc                                                                                                                                                                                                                                                                                      |
 | [Geospatial Loaders](/docs/specifications/category-gis)           | Loaders for geospatial formats such as [GeoJSON](/docs/modules/json/api-reference/geojson-loader) [KML](/docs/modules/kml/api-reference/kml-loader), [WKT/WKB](/docs/modules/wkt/api-reference/wkt-loader), [Mapbox Vector Tiles](/docs/modules/mvt/api-reference/mvt-loader) etc.                                                                                                                                                                                                   |
-| [Image Loaders](/docs/specifications/category-image)              | Loaders for [images](/docs/modules/images/api-reference/image-loader), [compressed textures](/docs/modules/textures/api-reference/compressed-texture-loader), [supercompressed textures (Basis)](/docs/modules/textures/api-reference/basis-loader). Utilities for [mipmapped arrays](/docs/modules/textures/api-reference/load-image-array), [cubemaps](/docs/modules/textures/api-reference/load-image-cube), [binary images](/docs/modules/images/api-reference/binary-image-api) and more. |
+| [Image Loaders](/docs/specifications/category-image)              | Loaders for [images](/docs/modules/images/api-reference/image-loader), [compressed textures](/docs/modules/textures/api-reference/compressed-texture-loader), [supercompressed textures (Basis)](/docs/modules/textures/api-reference/basis-loader), [composite image textures](/docs/modules/textures/api-reference/image-texture-cube-loader), [binary images](/docs/modules/images/api-reference/binary-image-api) and more. |
 | [Pointcloud and Mesh Loaders](/docs/specifications/category-mesh) | Loaders for point cloud and simple mesh formats such as [Draco](/docs/modules/draco/api-reference/draco-loader), [LAS](/docs/modules/las/api-reference/las-loader), [PCD](/docs/modules/pcd/api-reference/pcd-loader), [PLY](/docs/modules/ply/api-reference/ply-loader), [OBJ](/docs/modules/obj/api-reference/obj-loader), and [Terrain](/docs/modules/terrain/api-reference/terrain-loader).                                                                                            |
 | [Scenegraph Loaders](/docs/specifications/category-scenegraph)    | [glTF](/docs/modules/gltf/api-reference/gltf-loader) loader                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | [Tiled Data Loaders](/docs/specifications/category-3d-tiles)         | Loaders for 3D tile formats such as [3D Tiles](/docs/modules/3d-tiles/api-reference/tiles-3d-loader), [I3S](/docs/modules/i3s/api-reference/i3s-loader) and potree                                                                                                                                                                                                                                                                                                                             |

diff --git a/docs/developer-guide/composite-loaders.md b/docs/developer-guide/composite-loaders.md
@@ -44,3 +44,25 @@ The `parse*WithContext()` functions exported by `@loaders.gl/loader-utils` are t
 ## LoaderContext
 
 When a loader is being called (i.e. one of its `parse*()` functions is being called), a `LoaderContext` object is supplied.
+
+## Base URL Handling
+
+Composite loaders should resolve relative sub-resources from `context.baseUrl`.
+
+- `load(url, loader)` derives the effective base URL from the top-level resource URL and stores it on `context.baseUrl`
+- subloader and associated-resource resolution should prefer `context.baseUrl`
+- `options.core.baseUrl` is only a fallback for entrypoints that do not have a source URL, such as `parse(text, loader, options)`
+- once a loader has a context, it should not keep forwarding `core.baseUrl` into subloader options; child loads should resolve from their own context instead
+
+This keeps base URL state in one place and avoids passing ad hoc base values between composite loaders.
+
+## Forwarding Loader Lists
+
+When a composite loader parses sub-resources, it should preserve the top-level loader list so callers can provide additional member loaders.
+
+- prefer calling subloaders with an array such as `[ImageLoader]`, not a single forced loader
+- preserve `context.loaders` so caller-supplied loaders can participate in selection
+- when possible, parse the fetched `Response` rather than a detached `ArrayBuffer`, so subloader selection can still use the member URL and MIME type
+- if a child resource has its own URL, update the child context so downstream loaders see the correct `context.url` and `context.baseUrl`
+
+This pattern lets a composite loader provide a default member loader while still allowing applications to extend subresource handling.
diff --git a/docs/docs-sidebar.json b/docs/docs-sidebar.json
@@ -421,9 +421,10 @@
         "label": "@loaders.gl/textures",
         "items": [
           "modules/textures/README",
-          "modules/textures/api-reference/load-image",
-          "modules/textures/api-reference/load-image-array",
-          "modules/textures/api-reference/load-image-cube"
+          "modules/textures/api-reference/image-texture-loader",
+          "modules/textures/api-reference/image-texture-array-loader",
+          "modules/textures/api-reference/image-texture-cube-loader",
+          "modules/textures/api-reference/image-texture-cube-array-loader"
         ]
       },
       {

diff --git a/docs/modules/textures/README.md b/docs/modules/textures/README.md
@@ -26,6 +26,10 @@ npm install @loaders.gl/core
 | [`BasisLoader`](/docs/modules/textures/api-reference/basis-loader)                          | Basis Universal textures as `TextureLevel[][]`  |
 | [`CompressedTextureLoader`](/docs/modules/textures/api-reference/compressed-texture-loader) | KTX, DDS and PVR mip chains as `TextureLevel[]` |
 | [`CrunchWorkerLoader`](/docs/modules/textures/api-reference/crunch-loader)                  | Crunch mip chains as `TextureLevel[]`           |
+| [`ImageTextureLoader`](/docs/modules/textures/api-reference/image-texture-loader)           | Manifest-driven single image or mip chain       |
+| [`ImageTextureArrayLoader`](/docs/modules/textures/api-reference/image-texture-array-loader) | Manifest-driven texture arrays                  |
+| [`ImageTextureCubeLoader`](/docs/modules/textures/api-reference/image-texture-cube-loader)  | Manifest-driven cubemaps                        |
+| [`ImageTextureCubeArrayLoader`](/docs/modules/textures/api-reference/image-texture-cube-array-loader) | Manifest-driven cube arrays                     |
 
 ## Return Types
 
@@ -55,19 +59,17 @@ A `TextureLevel` describes one mip level of one texture image.
 
 See [`BasisLoader`](/docs/modules/textures/api-reference/basis-loader) and [`CompressedTextureLoader`](/docs/modules/textures/api-reference/compressed-texture-loader) for loader-specific options and return shapes.
 
-## Texture APIs
+## Composite Image Loaders
 
-The textures API offers functions to load "composite" images for WebGL textures, cube textures and image mip levels.
+The textures module also includes manifest-driven loaders for composite image textures:
 
-These functions take a `getUrl` parameter that enables the app to supply the url for each "sub-image", and return a single promise enabling applications to for instance load all the faces of a cube texture, with one image for each mip level for each face in a single async operation.
+- [`ImageTextureLoader`](/docs/modules/textures/api-reference/image-texture-loader) for a single image or mip chain
+- [`ImageTextureArrayLoader`](/docs/modules/textures/api-reference/image-texture-array-loader) for texture arrays, including mipmapped layers
+- [`ImageTextureCubeLoader`](/docs/modules/textures/api-reference/image-texture-cube-loader) for cubemaps, including mipmapped faces
+- [`ImageTextureCubeArrayLoader`](/docs/modules/textures/api-reference/image-texture-cube-array-loader) for cube arrays
 
-| Function                                                                  | Description                                                                                                           |
-| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| [`loadImage`](/docs/modules/textures/api-reference/load-image)            | Load a single image                                                                                                   |
-| [`loadImageArray`](/docs/modules/textures/api-reference/load-image-array) | Load an array of images, e.g. for a `Texture2DArray` or `Texture3D`                                                   |
-| [`loadImageCube`](/docs/modules/textures/api-reference/load-image-cube)   | Load a map of 6 images for the faces of a cube map, or a map of 6 arrays of images for the mip levels of the 6 faces. |
-
-As with all loaders.gl functions, while these functions are intended for use in WebGL applications, they do not call any WebGL functions, and do not actually create any WebGL textures..
+These loaders resolve relative member URLs against the manifest URL, or against `options.core.baseUrl` when parsing an in-memory manifest.
+Member assets are parsed with `ImageLoader` by default, and additional loaders passed to top-level `load()` are also available for manifest members.
 
 ## Attributions
 

diff --git a/docs/modules/textures/api-reference/image-texture-array-loader.md b/docs/modules/textures/api-reference/image-texture-array-loader.md
@@ -0,0 +1,77 @@
+# ImageTextureArrayLoader
+
+A loader for texture arrays described by a JSON manifest.
+
+| Loader         | Characteristic                        |
+| -------------- | ------------------------------------- |
+| File Format    | JSON manifest                         |
+| File Extension | `.json`                               |
+| File Type      | Text                                  |
+| Data Format    | `(ImageType \| ImageType[])[]`        |
+| Supported APIs | `load`, `parse`                       |
+
+## Usage
+
+```typescript
+import {load} from '@loaders.gl/core';
+import {ImageTextureArrayLoader} from '@loaders.gl/textures';
+
+const images = await load('texture-array.image-texture-array.json', ImageTextureArrayLoader);
+```
+
+Member images are parsed with `ImageLoader` by default. If you pass a loader array to `load()`, those additional loaders are also available for array layers and mip levels.
+
+## Manifest
+
+Texture array:
+
+```json
+{
+  "shape": "image-texture-array",
+  "layers": ["layer-0.png", "layer-1.png"]
+}
+```
+
+Texture array with mipmaps:
+
+```json
+{
+  "shape": "image-texture-array",
+  "layers": [
+    ["layer-0-0.png", "layer-0-1.png"],
+    ["layer-1-0.png", "layer-1-1.png"]
+  ]
+}
+```
+
+Each entry in `layers` can be either:
+
+- a single image path
+- an array of image paths representing mip levels
+- a template source object
+
+Template source example:
+
+```json
+{
+  "shape": "image-texture-array",
+  "layers": [
+    {"mipLevels": "auto", "template": "layer-{index}-{lod}.png"},
+    {"mipLevels": "auto", "template": "layer-{index}-{lod}.png"}
+  ]
+}
+```
+
+Supported template placeholders are `{lod}` and `{index}`.
+Use `\\{` and `\\}` to include literal braces in filenames.
+
+## Options
+
+| Option         | Type     | Default | Description                                                                 |
+| -------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `core.baseUrl` | `string` | -       | Base URL used to resolve relative member paths when parsing an in-memory manifest. |
+
+## Output
+
+- single-image layers return parsed images
+- mipmapped layers return arrays of parsed images
diff --git a/docs/modules/textures/api-reference/image-texture-cube-array-loader.md b/docs/modules/textures/api-reference/image-texture-cube-array-loader.md
@@ -0,0 +1,94 @@
+# ImageTextureCubeArrayLoader
+
+A loader for texture cube arrays described by a JSON manifest.
+
+| Loader         | Characteristic                |
+| -------------- | ----------------------------- |
+| File Format    | JSON manifest                 |
+| File Extension | `.json`                       |
+| File Type      | Text                          |
+| Data Format    | `Record<number, ImageType>[]` |
+| Supported APIs | `load`, `parse`               |
+
+## Usage
+
+```typescript
+import {load} from '@loaders.gl/core';
+import {ImageTextureCubeArrayLoader} from '@loaders.gl/textures';
+
+const imageCubeArray = await load(
+  'environment.image-texture-cube-array.json',
+  ImageTextureCubeArrayLoader
+);
+```
+
+Member faces are parsed with `ImageLoader` by default. If you pass a loader array to `load()`, those additional loaders are also available for cube-array faces and mip levels.
+
+## Manifest
+
+```json
+{
+  "shape": "image-texture-cube-array",
+  "layers": [
+    {
+      "faces": {
+        "+X": "sky-right.png",
+        "-X": "sky-left.png",
+        "+Y": "sky-top.png",
+        "-Y": "sky-bottom.png",
+        "+Z": "sky-front.png",
+        "-Z": "sky-back.png"
+      }
+    },
+    {
+      "faces": {
+        "+X": "irr-right.png",
+        "-X": "irr-left.png",
+        "+Y": "irr-top.png",
+        "-Y": "irr-bottom.png",
+        "+Z": "irr-front.png",
+        "-Z": "irr-back.png"
+      }
+    }
+  ]
+}
+```
+
+Each layer is a cubemap manifest fragment. Each face entry can be either:
+
+- a single image path
+- an array of image paths representing mip levels
+- a template source object
+
+Template source example:
+
+```json
+{
+  "shape": "image-texture-cube-array",
+  "layers": [
+    {
+      "faces": {
+        "+X": {"mipLevels": "auto", "template": "cube-{index}-{face}-{lod}.png"},
+        "-X": {"mipLevels": "auto", "template": "cube-{index}-{face}-{lod}.png"},
+        "+Y": {"mipLevels": "auto", "template": "cube-{index}-{face}-{lod}.png"},
+        "-Y": {"mipLevels": "auto", "template": "cube-{index}-{face}-{lod}.png"},
+        "+Z": {"mipLevels": "auto", "template": "cube-{index}-{face}-{lod}.png"},
+        "-Z": {"mipLevels": "auto", "template": "cube-{index}-{face}-{lod}.png"}
+      }
+    }
+  ]
+}
+```
+
+Supported template placeholders are `{lod}`, `{index}`, `{face}`, `{direction}`, `{axis}`, and `{sign}`.
+Use `\\{` and `\\}` to include literal braces in filenames.
+
+## Options
+
+| Option         | Type     | Default | Description                                                                 |
+| -------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `core.baseUrl` | `string` | -       | Base URL used to resolve relative member paths when parsing an in-memory manifest. |
+
+## Output
+
+Returns an array of cubemap objects keyed by WebGL cubemap face enum.
diff --git a/docs/modules/textures/api-reference/image-texture-cube-loader.md b/docs/modules/textures/api-reference/image-texture-cube-loader.md
@@ -0,0 +1,93 @@
+# ImageTextureCubeLoader
+
+A loader for cubemaps described by a JSON manifest.
+
+| Loader         | Characteristic               |
+| -------------- | ---------------------------- |
+| File Format    | JSON manifest                |
+| File Extension | `.json`                      |
+| File Type      | Text                         |
+| Data Format    | `Record<number, ImageType>`  |
+| Supported APIs | `load`, `parse`              |
+
+## Usage
+
+```typescript
+import {load} from '@loaders.gl/core';
+import {ImageTextureCubeLoader} from '@loaders.gl/textures';
+
+const imageCube = await load('environment.image-texture-cube.json', ImageTextureCubeLoader);
+```
+
+Member faces are parsed with `ImageLoader` by default. If you pass a loader array to `load()`, those additional loaders are also available for cubemap faces and mip levels.
+
+## Manifest
+
+Cubemap:
+
+```json
+{
+  "shape": "image-texture-cube",
+  "faces": {
+    "+X": "right.png",
+    "-X": "left.png",
+    "+Y": "top.png",
+    "-Y": "bottom.png",
+    "+Z": "front.png",
+    "-Z": "back.png"
+  }
+}
+```
+
+Cubemap with mipmaps:
+
+```json
+{
+  "shape": "image-texture-cube",
+  "faces": {
+    "+X": ["right-0.png", "right-1.png"],
+    "-X": ["left-0.png", "left-1.png"],
+    "+Y": ["top-0.png", "top-1.png"],
+    "-Y": ["bottom-0.png", "bottom-1.png"],
+    "+Z": ["front-0.png", "front-1.png"],
+    "-Z": ["back-0.png", "back-1.png"]
+  }
+}
+```
+
+Face names follow luma.gl conventions: `'+X'`, `'-X'`, `'+Y'`, `'-Y'`, `'+Z'`, `'-Z'`.
+
+Each face entry can be either:
+
+- a single image path
+- an array of image paths representing mip levels
+- a template source object
+
+Template source example:
+
+```json
+{
+  "shape": "image-texture-cube",
+  "faces": {
+    "+X": {"mipLevels": "auto", "template": "cube-{face}-{lod}.png"},
+    "-X": {"mipLevels": "auto", "template": "cube-{face}-{lod}.png"},
+    "+Y": {"mipLevels": "auto", "template": "cube-{face}-{lod}.png"},
+    "-Y": {"mipLevels": "auto", "template": "cube-{face}-{lod}.png"},
+    "+Z": {"mipLevels": "auto", "template": "cube-{face}-{lod}.png"},
+    "-Z": {"mipLevels": "auto", "template": "cube-{face}-{lod}.png"}
+  }
+}
+```
+
+Supported template placeholders are `{lod}`, `{face}`, `{direction}`, `{axis}`, and `{sign}`.
+Use `\\{` and `\\}` to include literal braces in filenames.
+
+## Options
+
+| Option         | Type     | Default | Description                                                                 |
+| -------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `core.baseUrl` | `string` | -       | Base URL used to resolve relative member paths when parsing an in-memory manifest. |
+
+## Output
+
+Returns a cubemap object keyed by WebGL cubemap face enum.