Shared raster tile layers

vector/raster sources support registration, TileJSON, setTiles/setUrl and metadata lifecycle. Raster sources now display through standard addLayer. Multiple layers share a source and respect shared ordering, visibility and raster-opacity. Planar, pitched and globe views use the same decoded tiles, rendered by the independent SqsMap engine.

import {map} from 'sqsmap';
map.addSource('imagery', {type:'raster',tiles:['https://your-server.example/{z}/{x}/{y}.png'],tileSize:256,attribution:'Your provider'});
map.addLayer({id:'imagery-layer',type:'raster',source:'imagery',paint:{'raster-opacity':0.8}});
await map.sqs.flush({render:true});
const source = await map.getSource('imagery');
console.log(await source.sqs.getTileMetadata());
console.log((await map.sqs.getSourceInfo('imagery')).tileState);
await source.setTiles(['https://your-server.example/new/{z}/{x}/{y}.png']);
map.removeLayer('imagery-layer');map.removeSource('imagery');
await map.sqs.flush();

Specify exactly one of url or tiles. Templates require credential-free absolute HTTP(S) URLs and z/x/y, 1–8 addresses, 4096 bytes per address and64KiB configuration. TMS resolves negative y; minzoom/maxzoom are integers0–24, bounds support the date line, tileSize is256 or512. TileJSON uses the existing Source resource policy with a1MiB response budget. Relative templates resolve against its URL; explicit zoom/bounds/scheme override downloaded values.

The view schedules raster requests: at most64 visible tiles,32 pending requests and64MiB decoded pixels per map. Each response permits4MiB PNG/JPEG/WebP and edges up to1024. Canonical tile coordinates share downloads and pixels across world wraps. Hiding/removing layers, moving the view, updating sources, replacing styles and destruction cancel obsolete requests; late responses cannot overwrite a newer generation. Failed refresh retains existing pixels; unavailable areas remain empty. Parent/child fallback, shared-source fading and the remaining raster paint properties are not connected yet.

SourceInfo.tileMetadata describes configuration; tileState exposes visibleTiles/readyTiles/pendingTiles/cachedTiles/byteLength. Without display dependencies, loaded means metadata is ready. With visible raster dependencies, all current view tiles must be ready. metadataLoaded only proves a usable metadata snapshot existed; hasData does not prove visible pixels. Events distinguish metadata and content using sourceDataType. Failed setUrl retains prior configuration and exposes loadError; setTiles can recover. getStyle returns current configuration, whereas getTileMetadata returns successfully resolved metadata.

Capabilities tiledSourceMetadata, tiledSourceRendering and rasterTileSourceRendering are true; vectorTileSourceStore is also true for the circle/line/fill/query subset. Vector supports shared circle/line/fill and queries; see shared MVT. Existing setStyle(URL) vector basemaps remain available. DEM,MLT,promoteId,volatile,remaining tiled types/feature state and the mobile host remain pending. GeoJSON/clustering methods do not apply to tiled sources. The existing C JSON/resource ABI remains unchanged.

The complete HTML example includes every button, event handler, credit and disposal action. The portable script runs in native, browser main-thread and strict Worker acceptance. The two-color example tiles are generated locally; replace the template and display provider-required attribution for real imagery.

MVT feature state is connected in07.9; see feature state.

Ordinary raster nearest-parent crop fallback is connected in07.13; fallbackTiles does not replace exact readyTiles/loaded. See parent fallback. DEM/promoteId/volatile and MVT feature state were connected in later stages; their dedicated guides supersede earlier scope notes above.

Shared tile URL templates extend quadkey, bbox, prefix, ratio and actual density changes. Earlier batch evidence remains historical; full source parameters remain separately pending.

Effective tile metadata documents current overrides, actual sizing/DEM decoding and accepted data during refresh waits/failures. Earlier evidence is not relabeled.