SDK and common-script event names
Standalone web SDK users and import {map} from 'sqsmap' scripts can both use sqs.layerschange and sqs.sourceschange. Callers own their layer/source UI: initialize it from actual state, then subscribe to changes.
const changed = event => console.log(event.layerCount, event.method, event.id);
const subscription = map.on('sqs.layerschange', changed);
const next = map.once('sqs.layerschange');
map.setPaintProperty('trees', 'circle-radius', 12);
await map.sqs.flush(); // standalone SDK: await map.flush()
await next;
subscription.unsubscribe();
// alternatively: map.off('sqs.layerschange', changed)
The SDK retains styleLayers / sources aliases and onStyleLayersChange / onSourcesChange convenience methods. These address one canonical subscription record. Mixing aliases with the same callback does not duplicate delivery; off can use the other name, and once shares single-use behavior and the 32-listener budget. Prefer canonical names in new code.
| Situation | Result |
|---|---|
| Empty, oversized or non-string event names | INVALID_ARGUMENT |
| Other valid names | Local custom events; no synthetic host lifecycle |
| Known but unconnected sqs.taskprogress and similar events | CAPABILITY_UNAVAILABLE |
| An event that cannot use a layer selector | CAPABILITY_UNAVAILABLE |
| Subscribing after map destruction or a still-pending once wait | CANCELLED |
SDK source/layer callbacks receive immutable historical count/change data. These remain SDK data snapshots; they do not add the common script's target, sequence or mapInstanceId envelope. Script hosts supply their own session envelope. SDK and script confirmation counters are also separate domains.
Synchronous throws and rejected Promises from non-pointer SDK observers are logged with console.error. They do not interrupt other observers or roll back applied commands; async once callbacks are covered too. At most 32 non-pointer observer promises may remain pending. Pressure logs RESOURCE_LIMIT and stops the remaining delivery for that notification, without later replaying skipped callbacks. Delivery recovers after promises settle. Avoid holding callbacks indefinitely and resynchronize from historical counts/current state when every notification matters. Destruction clears listeners, waits and budget bookkeeping, but cannot forcibly cancel caller-owned Promises.
Common-script callback errors retain their task-failure/cleanup policy; standalone SDK observers log failures. This is a host difference, not a claim of identical execution environments. Pointer callbacks retain their own bounded input/delegation contract.
This stage runs 32 checks in each real main-thread/strict Worker backend, covering alias deduplication, cross-name off/once, immutable counts, invalid names, rejected observers, pressure recovery and destruction. The complete SDK acceptance page is runnable. First load and render/idle are connected; shared-script remove is connected; complete style lifecycle and the mobile host remain task04 work.
Layer hover events are now connected.
Actual render/idle and state queries are connected; complete lifecycle remains in progress.
See Evented for custom events, fire and parent chains.
Internal SDK forwarding observers count toward the relevant event budget, so fewer than 32 public slots may be available. Aliases and canonical names share the actual remaining slots without a separate allowance.