Standalone web script host

MapScriptHost and ScriptRunner provide a reusable browser script console without Nuxt or desktop application sources. The caller supplies the editor, buttons, confirmation UI and map attribution. WebScriptHost remains a compatibility alias.

This private development snapshot is 0.1.0-dev.08.15a, matching core 65d76a28 and script contract 0.5-session. It is not a formal standalone npm release. The distribution manifest and host input snapshot identify the actual files and checksums. Use the local preview origin for local builds; public attachments require deployment.

Open the complete HTML example. Serve the manifest's dist, wasm, script, host and HTML from one directory over HTTP. Preserve relative dependencies and both Worker/WASM bundles. The blue point example requires no online basemap; supply the provider's source and copyright notices when adding a basemap.

import {MapView} from './dist/index.js';
import {MapScriptHost} from './host/dist/index.js';
import {ScriptRunner} from './script/dist/index.js';
const view = await MapView.create(container, {worker:false, locale:'auto'});
const host = new MapScriptHost(view, async preview =>
  confirm(preview.title + '\n' + preview.summary));
const runner = new ScriptRunner(host);
const value = await runner.run(source);

Include the following import map. The complete example includes CSS, editable source and every Run/Stop handler.

<script type="importmap">{"imports":{"@sqsmap/script":"./script/dist/index.js"}}</script>

Declare script metadata, such as // @gis-api 0.5-session and // @permissions ["project.read", "map.write"]. Scripts import map from sqsmap; the embedding application's MapView is a separate interface. Shared writes can be chained; authoritative queries and map.sqs.flush require await. Use map.setProjection({type:"globe"}) for the shared globe without switching to the gis module. See Globe API for spherical layer and camera scope. The old gis extension remains compatible.

Sessions and cleanup

runner.run resolves after initialization; a persistent script remains active. Export sessionMode = 'persistent' for retained event sessions. runner.closed reports actual closure, including CANCELLED on Stop, without an unhandled rejection.

Before rerunning or switching examples, call runner.stop(); await runner.closed; await host.reset();. Reset removes sources/layers confirmed as created by the host and restores planar projection. Normal script completion preserves the displayed map. Reset during an active session rejects with CONFLICT before cleanup; cleanup failures remain explicit. Destroy the map with view.destroy().

Successful reset starts a new host command/event identity domain. Never reuse old receipts or event sequences in it. SDK identity and history remain intact; SDK and script-host watermarks are separate. To continue after a caught write failure, acknowledge the observed error using its submittedSequence; the acceptance example covers this path.

Execution engines and current support

Browser code executes in a native JavaScript Worker, with contract WASM handling syntax and interface protocol. The optional native library script module embeds QuickJS. Browser scripts are not QuickJS and cannot access the embedding page DOM. Map rendering may use another Worker: worker:true permits fallback; supply createWorker and inspect view.offscreen for strict Worker rendering.

Seven identical source, layer, event, query and feature-state inputs passed real browser and Linux native-library checks. The native one-shot entry currently rejects source/layer event subscriptions explicitly; run those scripts through a retained session. Browser one-shot execution supports these short event scripts. Mobile hosting and external-device acceptance remain pending.

Runner declarations · Host declarations · Script types · Script WASM third-party notices · SDK license. Preserve relative declaration dependencies. Formal standalone package licensing and releases follow the release records.

Shared constant lighting, solar extensions and historical events use the same script shape; query capabilities for actual per-platform 3D layer support.

Legacy gis.map.setProjection confirms from the host’s acknowledged renderer watermark. Previously handled SDK failures are not replayed during a later globe switch; new projection failures still reject.