fix(deck.gl-geotiff): Honor extent in MosaicLayer

[kylebarron]

Note

This PR was written by Claude (Claude Code), not by @kylebarron.

MosaicLayer accepts extent and passes it to its inner TileLayer, which hands it to MosaicTileset2D. But MosaicTileset2D overrides getTileIndices and never reads this.opts.extent, so the prop does nothing. Every source whose bbox meets the viewport is still fetched, rendered and reported by onViewportLoad, with no warning. It has been this way since MosaicLayer was added in #184.

#684 makes the same fix for RasterTileset2D, the repo's only other Tileset2D subclass, and its description lists MosaicTileset2D as not changed there. Ref #684

Reproduction

new MosaicLayer({
  id: "mosaic",
  sources: [
    { bbox: [0, 0, 10, 10] }, // A
    { bbox: [20, 0, 30, 10] }, // B
    { bbox: [40, 0, 50, 10] }, // C
  ],
  extent: [15, -5, 35, 5], // overlaps only B
  getSource: async (source) => {
    console.log("fetching", source.bbox);
  },
  renderSource: () => null,
});

In a viewport that shows all three sources (longitude 25, latitude 5, zoom 3, 512×512), main fetches all three. I ran a version of this with named sources and an onViewportLoad callback through deck.gl's LayerManager in vitest (no GPU device, public API only), logging what getSource fetched and what onViewportLoad reported:

main     extent=[15,-5,35,5]: fetched=["A","B","C"] onViewportLoad=["A","B","C"]
this PR  extent=[15,-5,35,5]: fetched=["B"] onViewportLoad=["B"]

On main, changing extent on later renders (none, then [15,-5,35,5], then [5,-5,25,5], then none) never changes the selection. With this PR, onViewportLoad reports ["A","B","C"], ["B"], ["A","B"], then ["A","B","C"].

Fix

• MosaicTileset2D.getTileIndices keeps its zoom gate and its Flatbush search of the viewport, then drops the hits whose bbox doesn't overlap extent. It reads this.opts.extent on every call, because TileLayer updates it through setOptions. The filter runs before the hits are mapped, so a source's default tile id is still its position in sources.
• It uses the same rule as deck.gl's TileLayer (OSMNode.update's insideBounds) and fix(deck.gl-raster): Infer missing TileMatrixSet bounds and honor extent #684. The overlap is strict, so a source that only touches the extent at an edge or a corner is skipped. Each source is tested against the whole extent, not against the part of it in view, so a source that is on screen and overlaps the extent off-screen still loads (it is drawn in full).
• extent is no longer picked from TileLayerProps. MosaicLayerProps now declares it with TSDoc, which covers:
  • the format: WGS84 [minLng, minLat, maxLng, maxLat]
  • that an overlapping source is drawn in full, so to limit what it loads, pass the same extent to the layers renderSource returns
  • that unlike deck.gl's TileLayer, it doesn't keep sources loading below minZoom

Tests

There's a new MosaicTileset2D extent block in tests/mosaic-tileset-2d.test.ts. Its tests check that the tileset:

• selects only the sources that overlap an asymmetric extent
• keeps array-position ids when the extent skips an earlier source
• skips sources that only touch the extent, at an east/west edge and at a north edge
• keeps a visible source whose overlap with the extent is off-screen, and skips an on-screen source that misses the extent
• applies an extent changed through setOptions on the next call

Red/green: with only mosaic-tileset-2d.ts and mosaic-layer.ts reverted to main, all 5 new tests fail (Tests 5 failed | 6 passed (11)). With this PR, Tests 11 passed (11). I also tried these wrong versions of the fix, and each one fails at least one test:

• inclusive comparisons, on both axes or on y alone
• the extent read with its axes swapped
• searching viewport ∩ extent instead of testing each source
• the extent captured once in the constructor
• ids numbered after filtering

Checks:

• pnpm --filter @developmentseed/deck.gl-geotiff test: Test Files 7 passed (7), Tests 38 passed (38).
• pnpm --filter @developmentseed/deck.gl-geotiff typecheck passes under TypeScript 6.0.3. I haven't run it under TypeScript 7 (chore(deps-dev): upgrade to TypeScript 7 #685); CI will.
• pnpm exec biome ci .: Checked 385 files ... No fixes applied.

Open questions and judgment calls

• Merge after fix(deck.gl-raster): Infer missing TileMatrixSet bounds and honor extent #684? The TSDoc tells users to pass extent to the layers renderSource returns. That only limits what a COGLayer loads once fix(deck.gl-raster): Infer missing TileMatrixSet bounds and honor extent #684 makes RasterTileset2D read extent. If this PR lands first, that sentence is ahead of the code until fix(deck.gl-raster): Infer missing TileMatrixSet bounds and honor extent #684 does.
• minZoom. I kept the existing zoom gate, so setting extent does not keep sources loading below minZoom, unlike in deck.gl's TileLayer. fix(deck.gl-raster): Infer missing TileMatrixSet bounds and honor extent #684 makes the same choice.
• A MosaicLayer-level test? This PR doesn't change how MosaicLayer forwards extent, and no test covers that forwarding yet. A test that renderTileLayer(...) passes extent to the inner TileLayer needs no LayerManager. Turning the end-to-end reproduction above into a test would make it the repo's first LayerManager test. Without a device, deck.gl swallows updateState errors there, so it could only assert positive outcomes.
• fix(mosaic): Make MosaicLayer repeat over world copies (antimeridian) #639 and feat: antimeridian support #673 rewrite the same lines of getTileIndices, so whichever lands second needs a manual merge. In feat: antimeridian support #673 the check moves into its per-source loop, as a continue when extent is set and !overlaps(source.bbox, extent), after the source === undefined guard. In fix(mosaic): Make MosaicLayer repeat over world copies (antimeridian) #639 it stays a .filter on [...matched] before the .map. Since feat: antimeridian support #673 shifts antimeridian-crossing bboxes so that maxX > 180, should the check also test each bbox shifted by ±360? Otherwise a source stored as [178, -10, 182, 10] misses an extent like [-179, -10, -175, 10]. An extent that itself crosses the antimeridian isn't supported, as in deck.gl.

Related bug, not fixed here

MosaicLayer's getSources closure (() => this.props.sources) stays bound to the first layer instance. TileLayer creates the tileset once, and deck.gl moves state to each new layer instance but leaves the old instance's props as they were. So after the first render, the tileset pairs the rebuilt spatial index with the first sources array. In the same LayerManager setup, with no extent (main gives the same results):

# sources grow after the first render
sources=["A"]: fetched=["A"] onViewportLoad=["A"]
sources=["A","B","C"]: fetched=[] onViewportLoad=null
# sources shrink after the first render
sources=["A","B","C"]: fetched=["A","B","C"] onViewportLoad=["A","B","C"]
sources=["C"]: fetched=[] onViewportLoad=["A"]

So filtering sources yourself is not a reliable substitute for extent once the layer has rendered. #673 switches the closure to this.state.sources, which would fix this; it probably deserves its own issue. The new filter assumes, like the existing .map, that every index hit has a matching entry in sources, so it doesn't make this worse.

🤖 Written by Claude Code