type: reference title: "Sample basemap policy and inventory" description: "Shared free online basemaps, explicit overrides, sample exceptions, attribution, offline behavior and SDK/scaffold publication order." resource: "https://www.npmjs.com/package/@honua/sdk-js"

Basemap inventory

Source inventory at SDK commit 9f63b4c3b; 34 catalog entries. Each generated playground inherits its source sample policy.

Starters: vanilla-ts and react-ts keep local default fixture style; configured VITE_HONUA_ENDPOINT lane receives shared online default/override with attribution.

honua-samples: create-honua-app-react-ts/vanilla-ts consume the published scaffold. browser-featureserver-query renders a table, and geocode-single-line, hello-featureserver-rest, odata-query-rest, ogc-features-python, stac-search-rest and wms-getmap-check are request/response checks. No map basemap required.

Installed API design: /runtime explicit basemap style loader/binding, no network in core construction. Namespaced sources/layers inserted beneath operational overlays. Preserve TileJSON attribution and complete vector glyph/sprite resources. Surface style/tile/glyph/sprite failures with self-hosted override action while operational layers stay usable; no provider substitution.

Provider and offline evidence

The shared online defaults are OpenFreeMap Positron (thematic context), Liberty (street detail) and Dark (dark theme). Provider terms and quick start were checked 2026-10-10: no key or account is required, commercial use is allowed, and the public service has no SLA. Keep OpenMapTiles and OpenStreetMap attribution; do not strip source TileJSON attribution. Public style URLs are mutable. Use documented provider downloads/self-hosting for offline packs with recorded style/data versions and licenses; never scrape the public tile service as an implicit offline fallback.

@honua/sdk-js/runtime exports resolveHonuaOnlineBasemapStyle and HonuaOnlineBasemapBinding. Core client construction performs no basemap I/O. The browser binding explicitly fetches a style after the local initial map is ready. Custom/self-hosted styles take precedence over theme defaults. A custom glyph template must agree with any operational glyph template already on the map; otherwise the binding reports an actionable error and preserves the current base. Image, GeoJSON, video, glyph, sprite and tile URLs resolve relative to their style.

Custom sprite expressions preserve string/image coalesce fallback behavior and lexical let/var bindings. A case, match, step, or interpolate branch directly inside coalesce must use an explicit image expression; otherwise activation reports an unsupported expression without replacing the current basemap. Variable expansion is limited to 10,000 visited nodes and 64 levels to keep pathological styles bounded.

Online views keep operational source/layer objects, filters, feature state, selection, camera, imported bindings and popups during theme changes. Asset failures leave local operational rendering and controls available and show a status message; no other provider is silently substituted. Mobile layouts use MapLibre's compact attribution control, whose expanded credits remain accessible. Screenshots/exports must include that control or carry the exact visible source credits alongside the image. Canvas-only exports omit DOM attribution and must not be distributed without those credits.

Publication order

Publish the SDK containing the new /runtime exports and promote its certified release channel before publishing a create-honua-app release whose starter templates import them. Release-please owns both version bumps; do not move template pins ahead of registry availability. npm run create-app:verify:sdk-pair verifies packed scaffold projects beside a packed SDK under default npm peer resolution, then typechecks/builds both installed starters and imports the installed runtime default. The published scaffold consumer lane cannot exercise the new helper until the coordinated SDK and scaffold artifacts are available.

Map export inventory

The live map views covered here (First Map, React quickstart, service explorer, realtime incident dashboard, storytelling) and both starters have no user-facing map image export. Their browser evidence captures the page with expanded credits, including at mobile width, rather than exporting only the WebGL canvas. The imagery COG sample's image-server-export access path retrieves a server-authored raster; it is not a composite map screenshot and does not include an online basemap. Its purpose-specific imagery provenance/credits remain authoritative. Other fixture/scene/archive examples retain their own reviewed attribution; none exposes a canvas map PNG download. Future map image exports must include visible credits or an attached exact credit record before they can qualify.

Live style overrides

These are non-secret browser-visible style URLs. Set them when building the corresponding Vite app; a missing provider asset message names the exact key. Explicit overrides stay selected across light/dark changes. Fixture lanes retain their reviewed local style and do not implicitly fetch the online defaults.

Copied playground and starter adapters detect the runtime helper at activation, so older published SDKs still build and run their local fixture lane. A live map with an older SDK displays an explicit upgrade instruction. Source examples use direct imports so their normal bundle tree shaking is preserved. The compatibility adapter does not select an alternate provider.

After the deterministic packed-pair gate, opt in to the registry compatibility lane with HONUA_CREATE_APP_REGISTRY_COMPAT_ENABLED=true npm run create-app:verify:sdk-pair. This additionally builds both packed starters beside registry SDK 0.1.14 and executes their shipped adapter against those installed bytes, checking the actionable upgrade notice. The 0.1.14 version is a compatibility test target, not a release or generated dependency pin.

Bundle comparison is a separate opt-in review measurement: set HONUA_BASEMAP_BUNDLE_BASELINE_REF to an explicit existing Git ref or SHA while running the packed-pair gate. The receipt records its resolved commit and compares both live starter builds against that template source using the same installed packed SDK and dependencies, counting every emitted JavaScript chunk and its gzip size. The ordinary gate requires no Git remote or baseline history.