@honua/react 0.1.2-beta.0 → 0.1.4-beta.0

package/runtime/offline-region-protocol.js

@@ -0,0 +1,63 @@
+/**
+ * Auto-registration of the MapLibre `offline-region://` protocol.
+ *
+ * A style whose tile sources address a persisted offline region renders through
+ * a protocol handler built by `@honua/sdk-js/offline`
+ * (`createOfflineRegionTileProtocol`). This module registers that handler on
+ * MapLibre once, through the same shared registry `pmtiles://` uses.
+ *
+ * The runtime deliberately does **not** import `@honua/sdk-js/offline` and does
+ * not build the handler itself. A handler is bound to one region manifest, one
+ * store, and one authorization scope, none of which the runtime can invent —
+ * so the caller supplies the handler and the runtime decides only *when* it must
+ * be registered. That also keeps the offline module graph out of every map that
+ * never reads from a region.
+ *
+ * Registration is triggered by evidence, never by import: `loadMapPackage`
+ * registers when the composed style actually references the scheme, and fails
+ * closed when it does but no handler was supplied — because a missing handler
+ * renders blank tiles rather than an error.
+ *
+ * @module
+ */
+import { ensureMaplibreProtocol, isMaplibreProtocolRegistered, resetMaplibreProtocol, styleUsesProtocolScheme, } from "./protocol-registry.js";
+/** The MapLibre protocol scheme persisted offline regions are addressed under. */
+export const OFFLINE_REGION_PROTOCOL_SCHEME = "offline-region";
+/**
+ * Register the `offline-region://` protocol on MapLibre if it is not registered
+ * already. Idempotent per scheme, exactly like the PMTiles registration: several
+ * maps loading the same region concurrently share one registration.
+ *
+ * Because MapLibre's protocol table is process-global, the *first* handler wins
+ * for a given scheme. A host that needs to serve a different region on the same
+ * scheme must {@link resetOfflineRegionProtocol} first, or register the second
+ * region under its own scheme.
+ */
+export async function ensureOfflineRegionProtocol(deps) {
+    if (typeof deps?.tileHandler !== "function") {
+        throw new TypeError("An offline-region tile handler is required; build one with createOfflineRegionTileProtocol() from @honua/sdk-js/offline.");
+    }
+    await ensureMaplibreProtocol({
+        scheme: deps.scheme ?? OFFLINE_REGION_PROTOCOL_SCHEME,
+        ...(deps.maplibre ? { maplibre: deps.maplibre } : {}),
+        createHandler: () => deps.tileHandler,
+    });
+}
+/** Whether the `offline-region://` protocol (or `scheme`) is currently registered. */
+export function isOfflineRegionProtocolRegistered(scheme = OFFLINE_REGION_PROTOCOL_SCHEME) {
+    return isMaplibreProtocolRegistered(scheme);
+}
+/**
+ * Release a prior {@link ensureOfflineRegionProtocol} registration, so a later
+ * call can bind a different region's handler to the same scheme.
+ */
+export function resetOfflineRegionProtocol(scheme = OFFLINE_REGION_PROTOCOL_SCHEME) {
+    resetMaplibreProtocol(scheme);
+}
+/**
+ * Whether a composed MapLibre style references at least one `offline-region://`
+ * source. This is the evidence `loadMapPackage` registers on.
+ */
+export function styleUsesOfflineRegion(style, scheme = OFFLINE_REGION_PROTOCOL_SCHEME) {
+    return styleUsesProtocolScheme(style, scheme);
+}

package/runtime/offline-region-style.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Rewriting a style's tile templates onto the `offline-region://` scheme.
+ *
+ * A persisted region can only answer what it was addressed for, so pointing a
+ * style at one is a narrow, mechanical edit: replace a source's single XYZ tile
+ * template with `offline-region://<tileMatrixSetId>/{z}/{x}/{y}`. Everything
+ * else — TileJSON `url` members, GeoJSON `data`, sprites, glyphs, layer paint —
+ * is left exactly as authored.
+ *
+ * The rewrite is lossless and reversible: it returns a new style plus a record of
+ * every replacement, and {@link revertOfflineRegionStyleRewrite} restores the
+ * original byte-for-byte. Anything it cannot rewrite *exactly* is refused with a
+ * reason rather than guessed at, because a style that silently kept its network
+ * template would render live tiles while the application believed it was reading
+ * from a region.
+ *
+ * @module
+ */
+export type OfflineRegionStyleRefusalReason = 
+/** No source with this id exists in the style. */
+"unknown-source"
+/** The source is not a tile source (`geojson`, `image`, `video`, …). */
+ | "not-a-tile-source"
+/** The source addresses tiles only through a TileJSON `url`, which a region does not serve. */
+ | "tilejson-url-only"
+/** The source carries both `url` and `tiles`; which one MapLibre uses is not ours to decide. */
+ | "ambiguous-tile-source"
+/** The source has no single tile template to replace. */
+ | "multiple-tile-templates"
+/** The template is not a plain `{z}/{x}/{y}` address. */
+ | "unsupported-tile-template"
+/** The template already addresses the offline scheme. */
+ | "already-rewritten";
+export interface OfflineRegionStyleRefusalV1 {
+    readonly sourceId: string;
+    readonly reason: OfflineRegionStyleRefusalReason;
+    readonly detail: string;
+}
+/** One replacement, carrying exactly what is needed to undo it. */
+export interface OfflineRegionStyleRewriteEntryV1 {
+    readonly sourceId: string;
+    readonly member: "tiles";
+    readonly index: number;
+    readonly from: string;
+    readonly to: string;
+}
+export interface OfflineRegionStyleRewriteV1<TStyle = unknown> {
+    /** A new style. The input is never mutated. */
+    readonly style: TStyle;
+    readonly rewrites: readonly OfflineRegionStyleRewriteEntryV1[];
+    readonly refusals: readonly OfflineRegionStyleRefusalV1[];
+}
+export interface RewriteStyleTilesForOfflineRegionOptions {
+    /** Style source ids to serve from the region. Only these are considered. */
+    readonly sourceIds: readonly string[];
+    /** Tile-matrix-set segment of the rewritten URL. Defaults to `"default"`. */
+    readonly tileMatrixSetId?: string;
+    /** Protocol scheme. Defaults to `"offline-region"`. */
+    readonly scheme?: string;
+}
+/**
+ * Point the named tile sources at a persisted offline region.
+ *
+ * Rewrites only `sources[id].tiles[0]`, and only when that source is a
+ * `vector`, `raster`, or `raster-dem` source whose single template is a plain
+ * `{z}`/`{x}`/`{y}` address. Every other shape is refused; the caller decides
+ * whether a refusal is fatal.
+ */
+export declare function rewriteStyleTilesForOfflineRegion<TStyle>(style: TStyle, options: RewriteStyleTilesForOfflineRegionOptions): OfflineRegionStyleRewriteV1<TStyle>;
+/**
+ * Undo a rewrite, restoring every original template exactly.
+ *
+ * Applying this to the style a rewrite produced yields a style deep-equal to the
+ * one that went in, which is what makes the offline binding safe to apply to a
+ * package a host still owns.
+ */
+export declare function revertOfflineRegionStyleRewrite<TStyle>(style: TStyle, rewrite: Pick<OfflineRegionStyleRewriteV1, "rewrites">): TStyle;
+//# sourceMappingURL=offline-region-style.d.ts.map

package/runtime/offline-region-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-region-style.d.ts","sourceRoot":"","sources":["../../../src/runtime/offline-region-style.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,MAAM,+BAA+B;AACzC,kDAAkD;AAChD,gBAAgB;AAClB,wEAAwE;GACtE,mBAAmB;AACrB,+FAA+F;GAC7F,mBAAmB;AACrB,gGAAgG;GAC9F,uBAAuB;AACzB,yDAAyD;GACvD,yBAAyB;AAC3B,yDAAyD;GACvD,2BAA2B;AAC7B,yDAAyD;GACvD,mBAAmB,CAAC;AAExB,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B,CAAC,MAAM,GAAG,OAAO;IAC3D,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,gCAAgC,EAAE,CAAC;IAC/D,QAAQ,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,CAAC;CAC3D;AAED,MAAM,WAAW,wCAAwC;IACvD,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAOD;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EACtD,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,wCAAwC,GAChD,2BAA2B,CAAC,MAAM,CAAC,CAmCrC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EACpD,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,IAAI,CAAC,2BAA2B,EAAE,UAAU,CAAC,GACrD,MAAM,CAqBR"}

package/runtime/offline-region-style.js

@@ -0,0 +1,147 @@
+/**
+ * Rewriting a style's tile templates onto the `offline-region://` scheme.
+ *
+ * A persisted region can only answer what it was addressed for, so pointing a
+ * style at one is a narrow, mechanical edit: replace a source's single XYZ tile
+ * template with `offline-region://<tileMatrixSetId>/{z}/{x}/{y}`. Everything
+ * else — TileJSON `url` members, GeoJSON `data`, sprites, glyphs, layer paint —
+ * is left exactly as authored.
+ *
+ * The rewrite is lossless and reversible: it returns a new style plus a record of
+ * every replacement, and {@link revertOfflineRegionStyleRewrite} restores the
+ * original byte-for-byte. Anything it cannot rewrite *exactly* is refused with a
+ * reason rather than guessed at, because a style that silently kept its network
+ * template would render live tiles while the application believed it was reading
+ * from a region.
+ *
+ * @module
+ */
+import { OFFLINE_REGION_PROTOCOL_SCHEME } from "./offline-region-protocol.js";
+/** Source types whose `tiles` templates address XYZ tiles. */
+const TILE_SOURCE_TYPES = new Set(["vector", "raster", "raster-dem"]);
+/** Placeholders the offline tile handler can answer. Anything else is refused. */
+const SUPPORTED_PLACEHOLDERS = new Set(["z", "x", "y"]);
+/**
+ * Point the named tile sources at a persisted offline region.
+ *
+ * Rewrites only `sources[id].tiles[0]`, and only when that source is a
+ * `vector`, `raster`, or `raster-dem` source whose single template is a plain
+ * `{z}`/`{x}`/`{y}` address. Every other shape is refused; the caller decides
+ * whether a refusal is fatal.
+ */
+export function rewriteStyleTilesForOfflineRegion(style, options) {
+    const sourceIds = options?.sourceIds;
+    if (!Array.isArray(sourceIds) || sourceIds.length === 0) {
+        throw new TypeError("rewriteStyleTilesForOfflineRegion requires at least one style source id.");
+    }
+    const scheme = options.scheme ?? OFFLINE_REGION_PROTOCOL_SCHEME;
+    const tileMatrixSetId = options.tileMatrixSetId ?? "default";
+    if (tileMatrixSetId.length === 0 || tileMatrixSetId.includes("/")) {
+        throw new TypeError("tileMatrixSetId must be a non-empty path segment.");
+    }
+    const target = `${scheme}://${tileMatrixSetId}/{z}/{x}/{y}`;
+    const sources = style?.sources;
+    const rewrites = [];
+    const refusals = [];
+    const replacements = new Map();
+    for (const sourceId of sourceIds) {
+        const source = sources && typeof sources === "object" ? sources[sourceId] : undefined;
+        const refusal = classify(sourceId, source, scheme);
+        if (refusal) {
+            refusals.push(refusal);
+            continue;
+        }
+        const record = source;
+        rewrites.push({ sourceId, member: "tiles", index: 0, from: record.tiles[0], to: target });
+        replacements.set(sourceId, { ...record, tiles: [target] });
+    }
+    if (replacements.size === 0) {
+        return { style, rewrites, refusals };
+    }
+    const nextSources = { ...sources };
+    for (const [sourceId, source] of replacements)
+        nextSources[sourceId] = source;
+    return { style: { ...style, sources: nextSources }, rewrites, refusals };
+}
+/**
+ * Undo a rewrite, restoring every original template exactly.
+ *
+ * Applying this to the style a rewrite produced yields a style deep-equal to the
+ * one that went in, which is what makes the offline binding safe to apply to a
+ * package a host still owns.
+ */
+export function revertOfflineRegionStyleRewrite(style, rewrite) {
+    const entries = rewrite?.rewrites ?? [];
+    if (entries.length === 0)
+        return style;
+    const sources = style?.sources;
+    if (!sources || typeof sources !== "object") {
+        throw new TypeError("Cannot revert an offline-region rewrite against a style without sources.");
+    }
+    const nextSources = { ...sources };
+    for (const entry of entries) {
+        const source = nextSources[entry.sourceId];
+        const current = source?.tiles?.[entry.index];
+        if (current !== entry.to) {
+            throw new TypeError(`Style source "${entry.sourceId}" no longer carries the rewritten tile template; refusing a partial revert.`);
+        }
+        const tiles = [...(source?.tiles ?? [])];
+        tiles[entry.index] = entry.from;
+        nextSources[entry.sourceId] = { ...source, tiles };
+    }
+    return { ...style, sources: nextSources };
+}
+function classify(sourceId, source, scheme) {
+    if (!source || typeof source !== "object") {
+        return refuse(sourceId, "unknown-source", "The style declares no source with this id.");
+    }
+    const record = source;
+    if (typeof record.type !== "string" || !TILE_SOURCE_TYPES.has(record.type)) {
+        return refuse(sourceId, "not-a-tile-source", `Only vector, raster, and raster-dem sources address tiles; this source is "${String(record.type)}".`);
+    }
+    const hasTiles = Array.isArray(record.tiles);
+    if (record.url !== undefined && hasTiles) {
+        return refuse(sourceId, "ambiguous-tile-source", "The source carries both a TileJSON url and a tiles array; remove one before binding it to a region.");
+    }
+    if (!hasTiles) {
+        return refuse(sourceId, "tilejson-url-only", "The source addresses tiles through a TileJSON url, which a persisted region does not serve.");
+    }
+    const tiles = record.tiles;
+    if (tiles.length !== 1 || typeof tiles[0] !== "string") {
+        return refuse(sourceId, "multiple-tile-templates", `Exactly one string tile template can be bound to a region; this source declares ${tiles.length}.`);
+    }
+    const template = tiles[0];
+    if (template.startsWith(`${scheme}://`)) {
+        return refuse(sourceId, "already-rewritten", "The source already addresses the offline-region scheme.");
+    }
+    const placeholders = collectPlaceholders(template);
+    const missing = ["z", "x", "y"].filter((name) => !placeholders.has(name));
+    if (missing.length > 0) {
+        return refuse(sourceId, "unsupported-tile-template", `The template is missing the ${missing.join(", ")} placeholder(s) a region addresses tiles by.`);
+    }
+    for (const placeholder of placeholders) {
+        if (!SUPPORTED_PLACEHOLDERS.has(placeholder)) {
+            return refuse(sourceId, "unsupported-tile-template", `The template uses the {${placeholder}} placeholder, which a persisted region cannot address.`);
+        }
+    }
+    return undefined;
+}
+/** Bounded linear scan for `{name}` placeholders; deliberately not a regex. */
+function collectPlaceholders(template) {
+    const found = new Set();
+    let index = 0;
+    while (index < template.length) {
+        const open = template.indexOf("{", index);
+        if (open < 0)
+            break;
+        const close = template.indexOf("}", open + 1);
+        if (close < 0)
+            break;
+        found.add(template.slice(open + 1, close));
+        index = close + 1;
+    }
+    return found;
+}
+function refuse(sourceId, reason, detail) {
+    return { sourceId, reason, detail };
+}

package/runtime/pmtiles-protocol.d.ts

@@ -16,16 +16,15 @@
  * PMTiles source to a live map through `runtime.addSource` is synchronous — call
  * {@link ensurePmtilesProtocol} yourself beforehand in that case.
  *
- * The `maplibre-gl` / `pmtiles` slices are injectable so the wiring is
- * unit-testable without either real package.
+ * The registration bookkeeping itself lives in `protocol-registry.ts`, shared
+ * with every other scheme the runtime registers; this module owns only the
+ * PMTiles policy. The `maplibre-gl` / `pmtiles` slices are injectable so the
+ * wiring is unit-testable without either real package.
  *
  * @module
  */
-/** The MapLibre `addProtocol` / `removeProtocol` surface this module drives. */
-export interface MaplibreProtocolRegistrar {
-    addProtocol(scheme: string, handler: unknown): void;
-    removeProtocol?(scheme: string): void;
-}
+import { type MaplibreProtocolRegistrar } from "./protocol-registry.js";
+export type { MaplibreProtocolRegistrar };
 /** The `pmtiles.Protocol` surface this module drives. */
 export interface PmtilesProtocolLike {
     readonly tile: unknown;
@@ -65,7 +64,7 @@ export declare function isPmtilesProtocolRegistered(scheme?: string): boolean;
  * useful if a host wants to fully release the protocol. Best-effort — a
  * registrar without `removeProtocol` just clears the local record.
  */
-export declare function resetPmtilesProtocol(): void;
+export declare function resetPmtilesProtocol(scheme?: string): void;
 /**
  * Whether a composed MapLibre style references at least one `pmtiles://` source.
  * Used by `loadMapPackage` to decide whether the protocol must be registered

package/runtime/pmtiles-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pmtiles-protocol.d.ts","sourceRoot":"","sources":["../../../src/runtime/pmtiles-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,KAAK,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,mBAAmB,CAAC;CACvG;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IAC9C,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAmCjD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,GAAE,yBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/F;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,MAAM,GAAE,MAAgC,GAAG,OAAO,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,MAAM,GAAE,MAAgC,GACvC,OAAO,CAOT"}
+{"version":3,"file":"pmtiles-protocol.d.ts","sourceRoot":"","sources":["../../../src/runtime/pmtiles-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,KAAK,yBAAyB,EAK/B,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,yBAAyB,EAAE,CAAC;AAE1C,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,KAAK,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,mBAAmB,CAAC;CACvG;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IAC9C,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAMjD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,GAAE,yBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAY/F;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,MAAM,GAAE,MAAgC,GAAG,OAAO,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,MAAgC,GAAG,IAAI,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,MAAM,GAAE,MAAgC,GACvC,OAAO,CAET"}

package/runtime/pmtiles-protocol.js

@@ -16,30 +16,16 @@
  * PMTiles source to a live map through `runtime.addSource` is synchronous — call
  * {@link ensurePmtilesProtocol} yourself beforehand in that case.
  *
- * The `maplibre-gl` / `pmtiles` slices are injectable so the wiring is
- * unit-testable without either real package.
+ * The registration bookkeeping itself lives in `protocol-registry.ts`, shared
+ * with every other scheme the runtime registers; this module owns only the
+ * PMTiles policy. The `maplibre-gl` / `pmtiles` slices are injectable so the
+ * wiring is unit-testable without either real package.
  *
  * @module
  */
+import { ensureMaplibreProtocol, isMaplibreProtocolRegistered, resetMaplibreProtocol, styleUsesProtocolScheme, } from "./protocol-registry.js";
 /** The default MapLibre protocol scheme PMTiles archives are addressed under. */
 export const PMTILES_PROTOCOL_SCHEME = "pmtiles";
-let registration;
-let inFlight;
-/**
- * Resolve the MapLibre `addProtocol` registrar from the lazily-imported module.
- * MapLibre exposes it both as a named ESM export and off the default namespace;
- * accept either so this works against any v5 packaging.
- */
-async function loadMaplibreRegistrar() {
-    const mod = (await import("maplibre-gl"));
-    if (typeof mod.addProtocol === "function") {
-        return { addProtocol: mod.addProtocol, removeProtocol: mod.removeProtocol };
-    }
-    if (mod.default && typeof mod.default.addProtocol === "function") {
-        return mod.default;
-    }
-    throw new Error("maplibre-gl does not expose addProtocol(); ensure maplibre-gl >= 2 is installed.");
-}
 async function loadPmtilesModule() {
     return (await import("pmtiles"));
 }
@@ -53,29 +39,20 @@ async function loadPmtilesModule() {
  */
 export async function ensurePmtilesProtocol(deps = {}) {
     const scheme = deps.scheme ?? PMTILES_PROTOCOL_SCHEME;
-    if (registration && registration.scheme === scheme)
-        return;
-    if (inFlight)
-        return inFlight;
-    inFlight = (async () => {
-        const registrar = deps.maplibre ?? (await loadMaplibreRegistrar());
-        const pmtilesModule = deps.pmtilesModule ?? (await loadPmtilesModule());
-        // `metadata: true` lets MapLibre auto-populate source attribution and the
-        // inspect surface from the archive header without a second wiring step.
-        const protocol = new pmtilesModule.Protocol({ metadata: true });
-        registrar.addProtocol(scheme, protocol.tile);
-        registration = { scheme, registrar, protocol };
-    })();
-    try {
-        await inFlight;
-    }
-    finally {
-        inFlight = undefined;
-    }
+    await ensureMaplibreProtocol({
+        scheme,
+        ...(deps.maplibre ? { maplibre: deps.maplibre } : {}),
+        createHandler: async () => {
+            const pmtilesModule = deps.pmtilesModule ?? (await loadPmtilesModule());
+            // `metadata: true` lets MapLibre auto-populate source attribution and the
+            // inspect surface from the archive header without a second wiring step.
+            return new pmtilesModule.Protocol({ metadata: true }).tile;
+        },
+    });
 }
 /** Whether the `pmtiles://` protocol (or `scheme`) is currently registered. */
 export function isPmtilesProtocolRegistered(scheme = PMTILES_PROTOCOL_SCHEME) {
-    return registration?.scheme === scheme;
+    return isMaplibreProtocolRegistered(scheme);
 }
 /**
  * Tear down a prior {@link ensurePmtilesProtocol} registration. Primarily a test
@@ -83,25 +60,8 @@ export function isPmtilesProtocolRegistered(scheme = PMTILES_PROTOCOL_SCHEME) {
  * useful if a host wants to fully release the protocol. Best-effort — a
  * registrar without `removeProtocol` just clears the local record.
  */
-export function resetPmtilesProtocol() {
-    if (registration) {
-        registration.registrar.removeProtocol?.(registration.scheme);
-        registration = undefined;
-    }
-    inFlight = undefined;
-}
-function sourceReferencesPmtiles(source, scheme) {
-    if (!source || typeof source !== "object")
-        return false;
-    const prefix = `${scheme}://`;
-    const url = source.url;
-    if (typeof url === "string" && url.startsWith(prefix))
-        return true;
-    const tiles = source.tiles;
-    if (Array.isArray(tiles) && tiles.some((tile) => typeof tile === "string" && tile.startsWith(prefix))) {
-        return true;
-    }
-    return false;
+export function resetPmtilesProtocol(scheme = PMTILES_PROTOCOL_SCHEME) {
+    resetMaplibreProtocol(scheme);
 }
 /**
  * Whether a composed MapLibre style references at least one `pmtiles://` source.
@@ -109,12 +69,5 @@ function sourceReferencesPmtiles(source, scheme) {
  * before `map.setStyle`.
  */
 export function styleUsesPmtiles(style, scheme = PMTILES_PROTOCOL_SCHEME) {
-    const sources = style?.sources;
-    if (!sources)
-        return false;
-    for (const source of Object.values(sources)) {
-        if (sourceReferencesPmtiles(source, scheme))
-            return true;
-    }
-    return false;
+    return styleUsesProtocolScheme(style, scheme);
 }

package/runtime/protocol-registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * One idempotent MapLibre protocol registry, shared by every scheme the runtime
+ * auto-registers.
+ *
+ * MapLibre's protocol table is process-global, so registration has to be
+ * idempotent, deduplicated across concurrently loading maps, and keyed by scheme
+ * rather than by whichever protocol happened to register last. This module owns
+ * that bookkeeping once; `pmtiles-protocol.ts` and `offline-region-protocol.ts`
+ * are thin policies over it that decide *what* handler a scheme gets and *when* a
+ * style needs it.
+ *
+ * The `maplibre-gl` slice stays injectable so every wiring path is unit-testable
+ * without the real peer.
+ *
+ * @module
+ */
+/** The MapLibre `addProtocol` / `removeProtocol` surface this module drives. */
+export interface MaplibreProtocolRegistrar {
+    addProtocol(scheme: string, handler: unknown): void;
+    removeProtocol?(scheme: string): void;
+}
+/**
+ * Resolve the MapLibre `addProtocol` registrar from the lazily-imported module.
+ * MapLibre 6 is ESM-only and exposes it as a named export; MapLibre 5 may also
+ * surface it off the default namespace depending on how the host bundles the
+ * UMD build. Accept either so this works across the `^5 || ^6` peer range.
+ */
+export declare function loadMaplibreRegistrar(): Promise<MaplibreProtocolRegistrar>;
+/**
+ * Register `scheme` once, building its handler only when it is actually needed.
+ *
+ * Repeated calls — including from several maps loading at the same time — share
+ * one registration and one in-flight build per scheme. A failed build is not
+ * remembered, so a later call can retry.
+ */
+export declare function ensureMaplibreProtocol(options: {
+    readonly scheme: string;
+    /** Built at most once per scheme, and only when the scheme is not registered. */
+    readonly createHandler: () => unknown | Promise<unknown>;
+    readonly maplibre?: MaplibreProtocolRegistrar;
+}): Promise<void>;
+/** Whether `scheme` is currently registered through this registry. */
+export declare function isMaplibreProtocolRegistered(scheme: string): boolean;
+/**
+ * Tear down a prior registration. Primarily a test seam so a module-global
+ * registration does not leak between cases; also useful if a host wants to fully
+ * release a protocol. Best-effort — a registrar without `removeProtocol` just
+ * clears the local record.
+ */
+export declare function resetMaplibreProtocol(scheme: string): void;
+/** Whether a composed MapLibre style references at least one `<scheme>://` source. */
+export declare function styleUsesProtocolScheme(style: {
+    sources?: Record<string, unknown>;
+} | null | undefined, scheme: string): boolean;
+//# sourceMappingURL=protocol-registry.d.ts.map

package/runtime/protocol-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/protocol-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpD,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAUD;;;;;GAKG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,yBAAyB,CAAC,CAehF;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBhB;AAED,sEAAsE;AACtE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAO1D;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CACrC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,MAAM,EAAE,MAAM,GACb,OAAO,CAQT"}

package/runtime/protocol-registry.js

@@ -0,0 +1,103 @@
+/**
+ * One idempotent MapLibre protocol registry, shared by every scheme the runtime
+ * auto-registers.
+ *
+ * MapLibre's protocol table is process-global, so registration has to be
+ * idempotent, deduplicated across concurrently loading maps, and keyed by scheme
+ * rather than by whichever protocol happened to register last. This module owns
+ * that bookkeeping once; `pmtiles-protocol.ts` and `offline-region-protocol.ts`
+ * are thin policies over it that decide *what* handler a scheme gets and *when* a
+ * style needs it.
+ *
+ * The `maplibre-gl` slice stays injectable so every wiring path is unit-testable
+ * without the real peer.
+ *
+ * @module
+ */
+const registrations = new Map();
+const inFlight = new Map();
+/**
+ * Resolve the MapLibre `addProtocol` registrar from the lazily-imported module.
+ * MapLibre 6 is ESM-only and exposes it as a named export; MapLibre 5 may also
+ * surface it off the default namespace depending on how the host bundles the
+ * UMD build. Accept either so this works across the `^5 || ^6` peer range.
+ */
+export async function loadMaplibreRegistrar() {
+    const mod = (await import("maplibre-gl"));
+    if (typeof mod.addProtocol === "function") {
+        return { addProtocol: mod.addProtocol, removeProtocol: mod.removeProtocol };
+    }
+    if (mod.default && typeof mod.default.addProtocol === "function") {
+        return mod.default;
+    }
+    throw new Error("maplibre-gl does not expose addProtocol(); install maplibre-gl 5.x or 6.x (the SDK peer range is ^5.0.0 || ^6.0.0).");
+}
+/**
+ * Register `scheme` once, building its handler only when it is actually needed.
+ *
+ * Repeated calls — including from several maps loading at the same time — share
+ * one registration and one in-flight build per scheme. A failed build is not
+ * remembered, so a later call can retry.
+ */
+export async function ensureMaplibreProtocol(options) {
+    const scheme = options.scheme;
+    if (typeof scheme !== "string" || scheme.length === 0)
+        throw new TypeError("A protocol scheme is required.");
+    if (registrations.has(scheme))
+        return;
+    const pending = inFlight.get(scheme);
+    if (pending)
+        return pending;
+    const run = (async () => {
+        const registrar = options.maplibre ?? (await loadMaplibreRegistrar());
+        const handler = await options.createHandler();
+        registrar.addProtocol(scheme, handler);
+        registrations.set(scheme, { registrar, handler });
+    })();
+    inFlight.set(scheme, run);
+    try {
+        await run;
+    }
+    finally {
+        inFlight.delete(scheme);
+    }
+}
+/** Whether `scheme` is currently registered through this registry. */
+export function isMaplibreProtocolRegistered(scheme) {
+    return registrations.has(scheme);
+}
+/**
+ * Tear down a prior registration. Primarily a test seam so a module-global
+ * registration does not leak between cases; also useful if a host wants to fully
+ * release a protocol. Best-effort — a registrar without `removeProtocol` just
+ * clears the local record.
+ */
+export function resetMaplibreProtocol(scheme) {
+    const registration = registrations.get(scheme);
+    if (registration) {
+        registration.registrar.removeProtocol?.(scheme);
+        registrations.delete(scheme);
+    }
+    inFlight.delete(scheme);
+}
+/** Whether a composed MapLibre style references at least one `<scheme>://` source. */
+export function styleUsesProtocolScheme(style, scheme) {
+    const sources = style?.sources;
+    if (!sources)
+        return false;
+    const prefix = `${scheme}://`;
+    for (const source of Object.values(sources)) {
+        if (sourceReferencesScheme(source, prefix))
+            return true;
+    }
+    return false;
+}
+function sourceReferencesScheme(source, prefix) {
+    if (!source || typeof source !== "object")
+        return false;
+    const url = source.url;
+    if (typeof url === "string" && url.startsWith(prefix))
+        return true;
+    const tiles = source.tiles;
+    return Array.isArray(tiles) && tiles.some((tile) => typeof tile === "string" && tile.startsWith(prefix));
+}

package/runtime/runtime.d.ts

@@ -48,6 +48,7 @@ export interface MaplibreMap extends FeatureStateMap, MapEventTarget {
         lat: number;
     } | readonly [number, number];
     fitBounds?(bounds: [[number, number], [number, number]] | [number, number, number, number], options?: Record<string, unknown>): void;
+    getContainer?(): HTMLElement;
     jumpTo?(options: {
         center?: [number, number];
         zoom?: number;
@@ -209,6 +210,7 @@ export declare class HonuaMapRuntime {
         remove(): void;
     };
     setViewState(view: SetViewStateInput): void;
+    private prefersReducedMotion;
     /**
      * Diff the current package against `next`. Applies the change
      * incrementally when safe; falls back to `map.setStyle` for structural