Atomic incremental style updates

Compare live state while preserving compatible sources, caches and pending resources

The shared style diff in development SDK 0.3.0-dev.bc743baa passes the same public script with 35 checks and 14 phases on Linux, browser main thread and Worker. Probe (await map.sqs.getCapabilities()).commonStyleDiff at runtime.

The common map.setStyle(style, options) attempts incremental updates when diff is omitted or true. Use diff:false for full replacement; null clears. The default changes from the earlier full replacement behavior. Pass false explicitly to retain that behavior.

const style = await map.getStyle();
style.layers.find(layer => layer.id === 'roads').paint['line-color'] = '#ff5500';
map.setStyle(style, {diff: true});
await map.sqs.flush();

Replace roads with your actual layer ID. Applications provide their own layer panels and theme buttons; the core provides APIs and events.

Candidates compare the current live registry, including previous data, filter, material and order edits. A transaction can add/remove sources and layers, change compatible data or tile templates, reorder layers and edit supported style properties. Unknown parameters and unsupported rendering combinations still fail. Invalid candidates preserve the existing frame, identities, state and resources.

Compatible sources retain sourceInstanceId, cache, pending requests and raster fade time; compatible layers retain layerInstanceId. GeoJSON compatibility requires identical non-data options. Data changes follow existing setData state rules: stable explicit IDs and promoteId retain state; generated positional IDs clear it. Type, clustering, identity or other structural changes replace sources and invalidate previous handles. Tiled sources require identical declarations except tiles/url. Media declarations must match to retain frames and playback.

Changing glyphs or sprite roots falls back to full replacement. This does not imply every resource supports diffing. URL replies compare live state at arrival and retain requests belonging to unchanged sources. Late replies cannot revive removed or replaced sources.

New global defaults retain explicit runtime overrides, including an override equal to the previous default. Null removes an override and restores the current default. Candidates retain the 4 MiB input document, 128 source/layer and existing image, glyph, geometry, tile cache and resident budgets. Existing large live data is not reparsed as an input style document.

Flush confirms submission, not resource or fade completion. Inspect source and map loading state. This stage does not represent complete MapLibre style support, mobile GIS, iOS, external device acceptance or formal publication.

Complete acceptance script uses synthetic data and private protocols. Localhost3304 is an actual screenshot barrier. External drivers capture fades over real time and compare clock continuity across a diff; no fake clock or production timing API is introduced.