Actual map frames and idle

await map.sqs.lifecycleState() returns initialized, firstLoadCompleted, frameSequence, idle and work (pendingResources, pendingSources, animating, pendingRender, failed). await map.loaded() requires an actual frame, no pending work and no terminal source/style failure. Reads neither draw nor sample animations.

const next = map.once('idle');
map.setPaintProperty('trees', 'circle-color', '#00ff00');
await map.sqs.flush({render:true});
const event = await next;
console.log(event.lifecycle.frameSequence, event.cameraState);

Subscribe before changing content: an asynchronous host may already have drawn the new content before a later query. Render denotes a successful actual frame; repeated drawing of stationary content does not repeat idle. A terminal load failure may end busy work while loaded remains false. Frozen historical event state does not follow later camera/source changes.

Native libraries publish when the host explicitly draws or requests a render barrier. Ordinary desktop map presentation and autonomous browser drawing also produce render/idle; scripts do not need pixel readback. Desktop receipts originate from completion of an actually executed GUI GPU submission; discarded or unsubmitted passes are not frames. Receipts preserve the camera and content being drawn, and old frames cannot make newer changes idle. Actual frame/callback counts can differ; stationary redraws do not repeat idle. Full style lifecycle, the mobile host remain task04 work. Work state for legacy desktop 3D/terrain scenes still needs integration.

The standalone SDK also provides await map.lifecycleState(). The SDK supports standard load; scripts on an existing map inspect firstLoadCompleted. SDK remove fires once after destruction starts; use only its historical payload, as other methods and pending waits cancel. The SDK admits render/load/idle listener batches against its 32-promise budget. Pressure logs RESOURCE_LIMIT and preserves undelivered load/idle for a later actual frame; old render notifications are not replayed. Rejected foreign C pixel/receipt output does not advance the successful frame or consume idle; release output budget before retrying.

Standard load fires once after necessary resources and the first complete actual drawing. Animation may still run; idle also waits for animation to finish. firstLoadCompleted remembers the initial load and does not reset after camera or style changes. loaded() describes current work, so these states serve different purposes.

Attaching a script to an already loaded map does not replay load. Subscribe first, then read await map.sqs.lifecycleState(); proceed immediately if firstLoadCompleted is true. ready() only indicates the host connection. SDK destruction sends one remove snapshot even before successful drawing; stopping a script releases its session rather than destroying the map. Shared script remove is connected; complete style lifecycle remains pending.

The legacy C constructor load notification remains compatible. The standard first-frame notification is sqs.load in raw C events and maps to load in persistent native scripts, avoiding duplicate delivery. This follows the MapLibre event semantics; SqsMap implements its own engine.

Empty planar maps also support await map.sqs.flush({render:true}). The desktop host waits for an actual GUI GPU frame completed after the request and returns its historical camera. Having no exportable layer does not prevent rendering confirmation. Even a stationary map requires a new actual frame; unsubmitted drawing or an old frame cannot satisfy the request. The barrier still does not wait for every network resource or animation to finish.

When the host destroys the actual map, common scripts receive one remove with a frozen historical camera and lifecycle snapshot. New map/host operations from the callback return CANCELLED; old requests, subscriptions and waits are cleaned up. Final callbacks have a two-second execution budget: suspended callbacks time out with RESOURCE_LIMIT, and callback failures report INVALID_ARGUMENT while map release still completes. The browser also terminates a nonresponsive script worker after 2.5 seconds. Stopping a script or clearing a project does not emit remove because the map remains alive. Desktop exit, SDK destruction and native C map destruction share this contract; the mobile host remains pending.