@honua/app-platform 0.1.2-beta.0 → 0.1.7-beta.0

package/runtime/load-package.js

@@ -11,6 +11,8 @@ import { createDataset } from "../contract/index.js";
 import { HonuaMap } from "../map/honua-map.js";
 import { HonuaMapPackageError } from "./errors.js";
 import { HONUA_MAP_PACKAGE_FORMAT_V1 } from "./map-package.js";
+import { OFFLINE_REGION_PROTOCOL_SCHEME, ensureOfflineRegionProtocol, styleUsesOfflineRegion, } from "./offline-region-protocol.js";
+import { rewriteStyleTilesForOfflineRegion } from "./offline-region-style.js";
 import { createOgcStyleRefResolver } from "./ogc-styles.js";
 import { ensurePmtilesProtocol, styleUsesPmtiles } from "./pmtiles-protocol.js";
 import { HonuaMapRuntime, } from "./runtime.js";
@@ -18,6 +20,29 @@ import { projectSourceBindings, toHonuaSourceSpec } from "./source-bridge.js";
 import { composeStyle } from "./style-compose.js";
 import { throwRuntimeDiagnostics } from "./style-interactions.js";
 import { prepareRuntimeStyleSpecValidation } from "./style-spec-validation.js";
+/**
+ * Point the named sources at the region, or fail the load.
+ *
+ * A refusal is fatal here on purpose: the caller named these sources precisely
+ * because they must come from storage, so leaving one on its network template
+ * would render live tiles while the application believed it was offline-backed.
+ */
+function bindOfflineRegionStyle(style, packageId, region) {
+    if (!region?.sourceIds || region.sourceIds.length === 0)
+        return style;
+    const rewrite = rewriteStyleTilesForOfflineRegion(style, {
+        sourceIds: region.sourceIds,
+        ...(region.tileMatrixSetId !== undefined ? { tileMatrixSetId: region.tileMatrixSetId } : {}),
+    });
+    if (rewrite.refusals.length > 0) {
+        throw new HonuaMapPackageError("offline-region style binding refused a source it cannot rewrite exactly", {
+            ...(packageId === undefined ? {} : { packageId }),
+            stage: "style-compose",
+            detail: { refusals: rewrite.refusals },
+        });
+    }
+    return rewrite.style;
+}
 /**
  * Load a `MapPackage` onto a caller-provided `MaplibreMap`. Returns a
  * runtime handle that exposes the operational API. Throws
@@ -121,10 +146,11 @@ export async function loadMapPackage(pkg, map, options) {
             if (!honuaMap.hasLayer(layer.id))
                 honuaMap.addLayer(layer);
         }
-        const composed = await composeStyle(target, preComposed, {
+        const styled = await composeStyle(target, preComposed, {
             resolveStyleRef: styleRefResolver,
             resolveTheme: options.resolveTheme,
         });
+        const composed = bindOfflineRegionStyle(styled, target.mapPackageId, options.offlineRegion);
         // Auto-register the MapLibre `pmtiles://` protocol before the caller (or
         // `runtime.reload`) hands this style to `map.setStyle`, so PMTiles-backed
         // sources render with no manual `addProtocol` wiring. Idempotent across
@@ -132,6 +158,24 @@ export async function loadMapPackage(pkg, map, options) {
         if (styleUsesPmtiles(composed)) {
             await ensurePmtilesProtocol();
         }
+        // Same contract for a persisted offline region: register on the evidence of
+        // the composed style, and refuse to hand MapLibre a style that addresses a
+        // region without the handler that can answer it — a missing handler renders
+        // blank tiles instead of failing.
+        if (styleUsesOfflineRegion(composed)) {
+            const region = options.offlineRegion;
+            if (!region) {
+                throw new HonuaMapPackageError("the composed style addresses an offline region but no offlineRegion tile handler was supplied", {
+                    packageId: target.mapPackageId,
+                    stage: "style-compose",
+                    detail: { scheme: OFFLINE_REGION_PROTOCOL_SCHEME },
+                });
+            }
+            await ensureOfflineRegionProtocol({
+                tileHandler: region.tileHandler,
+                ...(region.maplibre ? { maplibre: region.maplibre } : {}),
+            });
+        }
         return { composed, dataset, honuaMap, failedSources };
     };
     try {

package/runtime/maplibre-renderer.d.ts

@@ -1,5 +1,6 @@
 import type { RendererAdapter } from "../kernel/renderer.js";
 import { type ExplainAutomaticMapLibreOptions, type SourceToMapLibreMap } from "../map/index.js";
+import { type OfflineRegionTileHandler } from "./offline-region-protocol.js";
 import type { PmtilesProtocolModuleLike } from "./pmtiles-protocol.js";
 /** MapLibre module slice consumed from the caller-injected optional peer. */
 export interface MapLibreRendererPeer {
@@ -30,6 +31,16 @@ export interface MapLibreRendererOptions extends Omit<ExplainAutomaticMapLibreOp
     readonly mapOptions?: Readonly<Record<string, unknown>>;
     /** Defaults to `render`, the first frame that can contain the mounted layer. */
     readonly firstFrameEvent?: "render" | "idle";
+    /**
+     * Tile handler for a style that addresses a persisted offline region.
+     *
+     * Registered before an owned map is constructed, but only when the style
+     * actually references the `offline-region://` scheme. A style that references
+     * it without a handler fails construction instead of rendering blank tiles.
+     */
+    readonly offlineRegion?: {
+        readonly tileHandler: OfflineRegionTileHandler;
+    };
 }
 /**
  * Create an executable MapLibre adapter without importing `maplibre-gl`.

package/runtime/maplibre-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maplibre-renderer.d.ts","sourceRoot":"","sources":["../../../src/runtime/maplibre-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,+BAA+B,EAEpC,KAAK,mBAAmB,EAGzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGvE,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAQD,yFAAyF;AACzF,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,IAAI,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACpD,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,8BAA8B;IAC7C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,+BAA+B,EAAE,WAAW,CAAC;IACjG,sGAAsG;IACtG,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC9C;AAQD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,8BAAmC,GAC3C,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,uBAAuB,CAAC,CA6G3E"}
+{"version":3,"file":"maplibre-renderer.d.ts","sourceRoot":"","sources":["../../../src/runtime/maplibre-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,+BAA+B,EAEpC,KAAK,mBAAmB,EAGzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAA6B,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGlG,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAQD,yFAAyF;AACzF,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,IAAI,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACpD,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,cAAc,CAAC,IAAI,IAAI,CAAC;IACxB,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,8BAA8B;IAC7C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,+BAA+B,EAAE,WAAW,CAAC;IACjG,sGAAsG;IACtG,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAA;KAAE,CAAC;CAC7E;AAQD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,8BAAmC,GAC3C,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,uBAAuB,CAAC,CAwH3E"}

package/runtime/maplibre-renderer.js

@@ -1,5 +1,6 @@
 import { HonuaAbortError } from "../core/errors.js";
 import { HonuaAutomaticMapLibreStrategyError, explainAutomaticSourceToMapLibre, mountAutomaticSourceToMapLibre, } from "../map/index.js";
+import { ensureOfflineRegionProtocol, styleUsesOfflineRegion, } from "./offline-region-protocol.js";
 import { ensurePmtilesProtocol } from "./pmtiles-protocol.js";
 const EMPTY_STYLE = Object.freeze({
     version: 8,
@@ -24,6 +25,20 @@ export function maplibreRenderer(peer, options = {}) {
         },
         async mount(target, request) {
             const rendererOptions = request.rendererOptions ?? {};
+            // A style that addresses a persisted region needs its protocol before the
+            // map is constructed with it; registration is driven by the style's own
+            // evidence, and a style that names the scheme without a handler fails here
+            // rather than rendering blank tiles.
+            if (styleUsesOfflineRegion(request.style)) {
+                const registrar = protocolRegistrar(maplibre);
+                if (rendererOptions.offlineRegion === undefined || registrar === undefined) {
+                    throw new TypeError("Rendering an offline-region style requires caller-injected MapLibre and a rendererOptions.offlineRegion tile handler.");
+                }
+                await ensureOfflineRegionProtocol({
+                    tileHandler: rendererOptions.offlineRegion.tileHandler,
+                    maplibre: registrar,
+                });
+            }
             const host = resolveMapHost(maplibre, target, request, rendererOptions);
             const map = host.map;
             try {
@@ -50,15 +65,10 @@ export function maplibreRenderer(peer, options = {}) {
                     });
                 }
                 if (plan.selected?.strategy.startsWith("pmtiles")) {
-                    if (pmtiles === undefined || typeof maplibre.addProtocol !== "function") {
+                    const registrar = protocolRegistrar(maplibre);
+                    if (pmtiles === undefined || registrar === undefined) {
                         throw new HonuaAutomaticMapLibreStrategyError("no-eligible-strategy", "PMTiles mounting requires caller-injected MapLibre and PMTiles protocol peers.");
                     }
-                    const registrar = {
-                        addProtocol: (scheme, handler) => maplibre.addProtocol(scheme, handler),
-                        ...(typeof maplibre.removeProtocol === "function"
-                            ? { removeProtocol: (scheme) => maplibre.removeProtocol(scheme) }
-                            : {}),
-                    };
                     await ensurePmtilesProtocol({ maplibre: registrar, pmtilesModule: pmtiles });
                 }
                 const mounted = await mountAutomaticSourceToMapLibre(map, request.source, plan, {
@@ -131,6 +141,21 @@ function maplibrePeer(value) {
             : {}),
     });
 }
+/**
+ * Adapt the injected peer to the shared protocol registrar, or report that it
+ * cannot register protocols. This adapter never imports `maplibre-gl` itself, so
+ * an absent `addProtocol` is a caller-visible failure rather than a lazy import.
+ */
+function protocolRegistrar(peer) {
+    const addProtocol = peer.addProtocol;
+    if (typeof addProtocol !== "function")
+        return undefined;
+    const removeProtocol = peer.removeProtocol;
+    return {
+        addProtocol: (scheme, handler) => addProtocol(scheme, handler),
+        ...(typeof removeProtocol === "function" ? { removeProtocol: (scheme) => removeProtocol(scheme) } : {}),
+    };
+}
 function resolveMapHost(peer, target, request, options) {
     if (isMapHost(target)) {
         if (request.style !== undefined) {

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

@@ -0,0 +1,73 @@
+/**
+ * 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 { type MaplibreProtocolRegistrar } from "./protocol-registry.js";
+/** The MapLibre protocol scheme persisted offline regions are addressed under. */
+export declare const OFFLINE_REGION_PROTOCOL_SCHEME = "offline-region";
+/**
+ * The handler shape `createOfflineRegionTileProtocol()` returns.
+ *
+ * Declared structurally so the runtime never imports the offline entrypoint; it
+ * is the same shape MapLibre itself expects from `addProtocol`.
+ */
+export type OfflineRegionTileHandler = (request: {
+    readonly url: string;
+}, abortController?: AbortController) => Promise<{
+    readonly data: ArrayBuffer;
+    readonly cacheControl?: string;
+    readonly expires?: string;
+}>;
+/** Injectable dependencies for {@link ensureOfflineRegionProtocol}. */
+export interface EnsureOfflineRegionProtocolDeps {
+    /** Handler from `@honua/sdk-js/offline`'s `createOfflineRegionTileProtocol()`. */
+    readonly tileHandler: OfflineRegionTileHandler;
+    /** Override the lazily-imported MapLibre `addProtocol` registrar. */
+    readonly maplibre?: MaplibreProtocolRegistrar;
+    /** Protocol scheme to register. Defaults to `"offline-region"`. */
+    readonly scheme?: string;
+}
+/**
+ * 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 declare function ensureOfflineRegionProtocol(deps: EnsureOfflineRegionProtocolDeps): Promise<void>;
+/** Whether the `offline-region://` protocol (or `scheme`) is currently registered. */
+export declare function isOfflineRegionProtocolRegistered(scheme?: string): boolean;
+/**
+ * Release a prior {@link ensureOfflineRegionProtocol} registration, so a later
+ * call can bind a different region's handler to the same scheme.
+ */
+export declare function resetOfflineRegionProtocol(scheme?: string): void;
+/**
+ * Whether a composed MapLibre style references at least one `offline-region://`
+ * source. This is the evidence `loadMapPackage` registers on.
+ */
+export declare function styleUsesOfflineRegion(style: {
+    sources?: Record<string, unknown>;
+} | null | undefined, scheme?: string): boolean;
+//# sourceMappingURL=offline-region-protocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"offline-region-protocol.d.ts","sourceRoot":"","sources":["../../../src/runtime/offline-region-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,KAAK,yBAAyB,EAK/B,MAAM,wBAAwB,CAAC;AAEhC,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACjC,eAAe,CAAC,EAAE,eAAe,KAC9B,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAExG,uEAAuE;AACvE,MAAM,WAAW,+BAA+B;IAC9C,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAC;IAC/C,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,+BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtG;AAED,sFAAsF;AACtF,wBAAgB,iCAAiC,CAAC,MAAM,GAAE,MAAuC,GAAG,OAAO,CAE1G;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,GAAE,MAAuC,GAAG,IAAI,CAEhG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC/D,MAAM,GAAE,MAAuC,GAC9C,OAAO,CAET"}

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"}