@honua/app-platform 0.1.12 → 0.1.13

package/offline/store-conformance.js

@@ -0,0 +1,233 @@
+import { sha256 } from "./digest.js";
+import { createOfflineRegionManifest, downloadOfflineRegion, planOfflineRegionAdmission } from "./region.js";
+import { HonuaOfflineRegionError, } from "./types.js";
+/**
+ * One conformance suite every offline region store must pass.
+ *
+ * The IndexedDB adapter can only run in a browser and the in-memory adapter can
+ * run anywhere, so the suite is written as plain async functions rather than
+ * against a test framework: vitest runs it over the memory store, and the browser
+ * evidence runs the identical cases over real IndexedDB. A store that passes here
+ * is substitutable in the download coordinator and the read path.
+ *
+ * @experimental
+ */
+export const HONUA_OFFLINE_REGION_STORE_CONFORMANCE_KIND = "honua.offline-region-store-conformance";
+export const HONUA_OFFLINE_REGION_STORE_CONFORMANCE_VERSION = "1.0";
+const encoder = new TextEncoder();
+const QUOTA = 1024 * 1024;
+/** Names of every case in the suite, in execution order. */
+export const OFFLINE_REGION_STORE_CONFORMANCE_CASES = [
+    "empty-store-reports-no-regions",
+    "commit-publishes-region-and-resources",
+    "read-returns-caller-owned-bytes",
+    "absent-resource-reads-undefined",
+    "commit-advances-inventory-revision",
+    "stale-inventory-commit-is-refused",
+    "rollback-discards-uncommitted-writes",
+    "admission-evicts-to-fit-quota",
+    "credential-bearing-identity-is-refused",
+    "byte-length-mismatch-is-refused",
+];
+const CASES = {
+    "empty-store-reports-no-regions": async (store) => {
+        const inventory = await store.inventory();
+        assert(typeof inventory.revision === "string" && inventory.revision.length > 0, "revision must be a non-empty string");
+        assert(inventory.regions.length === 0, "a fresh store must report no regions");
+        assert((await store.readResource("missing-region", "missing-resource")) === undefined, "absent region must read undefined");
+    },
+    "commit-publishes-region-and-resources": async (store) => {
+        const fixture = await downloadFixture(store, "alpha");
+        const inventory = await store.inventory();
+        assert(inventory.regions.length === 1, "one committed region must appear in the inventory");
+        assert(inventory.regions[0]?.id === fixture.manifest.id, "the inventory must key the region by its manifest id");
+        assert(inventory.regions[0]?.logicalByteLength === fixture.manifest.totalLogicalBytes, "the inventory must charge the manifest's logical bytes");
+        const read = await store.readResource(fixture.manifest.id, fixture.resourceId);
+        assert(read !== undefined, "a committed resource must be readable");
+        assert(decode(read.bytes) === fixture.payload, "a committed resource must read back its exact bytes");
+        assert(read.manifest.id === fixture.manifest.id, "a read must carry the region's manifest");
+        assert(read.resource.id === fixture.resourceId, "a read must carry the resource descriptor");
+    },
+    "read-returns-caller-owned-bytes": async (store) => {
+        const fixture = await downloadFixture(store, "alpha");
+        const first = await store.readResource(fixture.manifest.id, fixture.resourceId);
+        assert(first !== undefined, "a committed resource must be readable");
+        first.bytes[0] = 0;
+        const second = await store.readResource(fixture.manifest.id, fixture.resourceId);
+        assert(second !== undefined, "a committed resource must stay readable");
+        assert(decode(second.bytes) === fixture.payload, "mutating returned bytes must not mutate the store");
+    },
+    "absent-resource-reads-undefined": async (store) => {
+        const fixture = await downloadFixture(store, "alpha");
+        assert((await store.readResource(fixture.manifest.id, "features/absent")) === undefined, "an unknown resource id must read undefined");
+        assert((await store.readResource("sha256:0", fixture.resourceId)) === undefined, "an unknown region must read undefined");
+    },
+    "commit-advances-inventory-revision": async (store) => {
+        const before = (await store.inventory()).revision;
+        await downloadFixture(store, "alpha");
+        const after = (await store.inventory()).revision;
+        assert(before !== after, "a committed mutation must advance the inventory revision");
+    },
+    "stale-inventory-commit-is-refused": async (store) => {
+        const stale = await store.inventory();
+        const first = await downloadFixture(store, "alpha");
+        const second = await fixtureManifest("beta");
+        const transaction = await store.beginWrite(second.manifest.id);
+        await transaction.write(second.manifest.resources[0], encoder.encode(second.payload));
+        const outcome = await transaction.commit(second.manifest, receiptFor(second.manifest), {
+            expectedInventoryRevision: stale.revision,
+            logicalQuotaBytes: QUOTA,
+            admission: planOfflineRegionAdmission(second.manifest, stale, { logicalQuotaBytes: QUOTA }),
+        });
+        assert(outcome === "inventory-changed", "a commit against a stale inventory revision must be refused");
+        await transaction.rollback();
+        const inventory = await store.inventory();
+        assert(inventory.regions.length === 1, "a refused commit must not publish a region");
+        assert(inventory.regions[0]?.id === first.manifest.id, "a refused commit must leave the prior region intact");
+    },
+    "rollback-discards-uncommitted-writes": async (store) => {
+        const fixture = await fixtureManifest("alpha");
+        const transaction = await store.beginWrite(fixture.manifest.id);
+        await transaction.write(fixture.manifest.resources[0], encoder.encode(fixture.payload));
+        await transaction.rollback();
+        const inventory = await store.inventory();
+        assert(inventory.regions.length === 0, "a rolled back transaction must publish nothing");
+        assert((await store.readResource(fixture.manifest.id, fixture.resourceId)) === undefined, "a rolled back resource must not be readable");
+    },
+    "admission-evicts-to-fit-quota": async (store) => {
+        const first = await downloadFixture(store, "alpha");
+        const second = await fixtureManifest("beta");
+        // A quota that fits exactly one region forces the older one out.
+        await downloadOfflineRegion(second.manifest, {
+            store,
+            load: async () => encoder.encode(second.payload),
+            logicalQuotaBytes: second.manifest.totalLogicalBytes,
+        });
+        const inventory = await store.inventory();
+        assert(inventory.regions.length === 1, "eviction must leave exactly the admitted region");
+        assert(inventory.regions[0]?.id === second.manifest.id, "eviction must retain the newly admitted region");
+        assert((await store.readResource(first.manifest.id, first.resourceId)) === undefined, "eviction must remove the evicted region's resources");
+    },
+    "credential-bearing-identity-is-refused": async (store) => {
+        await expectRejection(() => store.beginWrite("https://user:secret@example.test/region?token=abc"), "a credential-bearing region id must be refused");
+    },
+    "byte-length-mismatch-is-refused": async (store) => {
+        const fixture = await fixtureManifest("alpha");
+        const transaction = await store.beginWrite(fixture.manifest.id);
+        await expectRejection(() => transaction.write(fixture.manifest.resources[0], encoder.encode(`${fixture.payload}-extra`)), "a byte length that disagrees with the descriptor must be refused");
+        await transaction.rollback();
+    },
+};
+/**
+ * Run the suite and report per-case outcomes.
+ *
+ * Cases never share a store: each one is handed a fresh store from
+ * `createStore`, so a failure cannot cascade into a false failure downstream.
+ */
+export async function runOfflineRegionStoreConformance(options) {
+    const selected = options.only ?? OFFLINE_REGION_STORE_CONFORMANCE_CASES;
+    const cases = [];
+    for (const name of selected) {
+        const body = CASES[name];
+        if (!body) {
+            cases.push({ name, status: "failed", detail: "unknown conformance case" });
+            continue;
+        }
+        let store;
+        try {
+            store = await options.createStore();
+            await body(store);
+            cases.push({ name, status: "passed" });
+        }
+        catch (error) {
+            cases.push({ name, status: "failed", detail: describe(error) });
+        }
+        finally {
+            if (store && options.disposeStore) {
+                try {
+                    await options.disposeStore(store);
+                }
+                catch {
+                    // Teardown failures must not rewrite a case's own verdict.
+                }
+            }
+        }
+    }
+    const failed = cases.filter((entry) => entry.status === "failed").length;
+    return {
+        kind: HONUA_OFFLINE_REGION_STORE_CONFORMANCE_KIND,
+        version: HONUA_OFFLINE_REGION_STORE_CONFORMANCE_VERSION,
+        ...(options.label ? { label: options.label } : {}),
+        total: cases.length,
+        passed: cases.length - failed,
+        failed,
+        cases,
+    };
+}
+async function fixtureManifest(name) {
+    const payload = `{"region":"${name}"}`;
+    const resourceId = `features/${name}`;
+    const resource = {
+        id: resourceId,
+        kind: "features",
+        byteLength: encoder.encode(payload).byteLength,
+        integrity: await sha256(encoder.encode(payload)),
+        contentType: "application/json",
+    };
+    const manifest = await createOfflineRegionManifest({
+        name: `Conformance region ${name}`,
+        sourceId: "conformance-source",
+        endpoint: "https://example.test/FeatureServer/0",
+        authorizationScopeFingerprint: `conformance-scope-${name}`,
+        bounds: { minX: -1, minY: -1, maxX: 1, maxY: 1, crs: "EPSG:4326" },
+        sourceVersion: "source-v1",
+        schemaVersion: "schema-v1",
+        planVersion: "plan-v1",
+        observation: { state: "live", observedAt: "2026-01-01T00:00:00.000Z" },
+        attribution: { fixture: "Honua conformance fixture" },
+        resources: [resource],
+    });
+    return { manifest, resourceId, payload };
+}
+async function downloadFixture(store, name) {
+    const fixture = await fixtureManifest(name);
+    await downloadOfflineRegion(fixture.manifest, {
+        store,
+        load: async () => encoder.encode(fixture.payload),
+        logicalQuotaBytes: QUOTA,
+    });
+    return fixture;
+}
+function receiptFor(manifest) {
+    return {
+        regionId: manifest.id,
+        resourceCount: manifest.resources.length,
+        logicalByteLength: manifest.totalLogicalBytes,
+        evictedRegionIds: [],
+        integrity: "verified",
+        quotaAccounting: "logical-payload-bytes",
+        completedAt: "2026-01-01T00:00:00.000Z",
+    };
+}
+async function expectRejection(body, message) {
+    try {
+        await body();
+    }
+    catch (error) {
+        assert(error instanceof Error, `${message} (a typed error is required)`);
+        return;
+    }
+    throw new Error(message);
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function decode(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function describe(error) {
+    if (error instanceof HonuaOfflineRegionError)
+        return `${error.code}: ${error.message}`;
+    return error instanceof Error ? error.message : String(error);
+}

package/offline/tile-protocol.d.ts

@@ -0,0 +1,81 @@
+import { type OfflineRegionTileReadV1, type ReadOfflineRegionTileOptions } from "./read-resource.js";
+import { type OfflineRegionManifestV1 } from "./types.js";
+/**
+ * Binding persisted tiles to the map runtime's existing protocol seam.
+ *
+ * The SDK already registers custom URL protocols with MapLibre through a
+ * `addProtocol(scheme, handler)` registrar (`src/runtime/pmtiles-protocol.ts`),
+ * so offline tiles reuse that seam rather than introducing a second tile
+ * pipeline: a style names `offline-region://…/{z}/{x}/{y}` tiles, and the handler
+ * answers each one from the persisted region under the full read discipline. A
+ * tile the region does not hold rejects with its typed reason — nothing falls
+ * back to the network, and nothing renders bytes the region never stored.
+ *
+ * Registration stays application-owned. The runtime does not yet auto-register
+ * this protocol or rewrite a style's tile URLs onto it.
+ *
+ * @experimental
+ */
+/** URL scheme a style uses to address tiles inside a persisted region. */
+export declare const OFFLINE_REGION_TILE_SCHEME: "offline-region";
+/** One parsed `offline-region://` tile address. */
+export interface OfflineRegionTileAddressV1 {
+    readonly tileMatrixSetId: string;
+    readonly z: number;
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Request shape MapLibre hands a protocol handler.
+ *
+ * Declared structurally so `@honua/sdk-js/offline` never imports the map runtime
+ * or the `maplibre-gl` peer; it is the same shape the runtime's own registrar
+ * already passes.
+ */
+export interface OfflineRegionProtocolRequest {
+    readonly url: string;
+}
+export interface OfflineRegionProtocolResponse {
+    readonly data: ArrayBuffer;
+    readonly cacheControl?: string;
+    readonly expires?: string;
+}
+export type OfflineRegionProtocolHandler = (request: OfflineRegionProtocolRequest, abortController?: AbortController) => Promise<OfflineRegionProtocolResponse>;
+/** The `addProtocol`/`removeProtocol` pair the map runtime already speaks. */
+export interface OfflineRegionProtocolRegistrar {
+    addProtocol(scheme: string, handler: OfflineRegionProtocolHandler): void;
+    removeProtocol?(scheme: string): void;
+}
+export interface CreateOfflineRegionTileProtocolOptions extends Omit<ReadOfflineRegionTileOptions, "tile" | "scheme" | "tileMatrixSetId" | "signal"> {
+    readonly manifest: OfflineRegionManifestV1;
+    /** Observe every tile served, for diagnostics. Exceptions are ignored. */
+    readonly onTile?: (read: OfflineRegionTileReadV1) => void;
+}
+/** Build the tile-URL template a MapLibre source uses to address a region. */
+export declare function buildOfflineRegionTileUrlTemplate(options?: {
+    readonly tileMatrixSetId?: string;
+}): string;
+/**
+ * Parse an `offline-region://` tile URL.
+ *
+ * Parsing is a bounded segment split with no regular expression, and a URL
+ * carrying a query or fragment is refused outright: a tile address is an
+ * identity, and anything that could smuggle a token into one is not a tile
+ * address.
+ */
+export declare function parseOfflineRegionTileUrl(url: string): OfflineRegionTileAddressV1;
+/**
+ * Create a MapLibre protocol handler that serves tiles from a persisted region.
+ *
+ * Register it with the same registrar the runtime uses for other custom schemes:
+ * `registrar.addProtocol(OFFLINE_REGION_TILE_SCHEME, handler)`.
+ */
+export declare function createOfflineRegionTileProtocol(options: CreateOfflineRegionTileProtocolOptions): OfflineRegionProtocolHandler;
+/**
+ * Register the offline tile protocol and return its disposer.
+ *
+ * The registrar is the application's — usually `maplibre-gl` itself — so the SDK
+ * neither imports the peer nor decides when a map should read from a region.
+ */
+export declare function registerOfflineRegionTileProtocol(registrar: OfflineRegionProtocolRegistrar, options: CreateOfflineRegionTileProtocolOptions): () => void;
+//# sourceMappingURL=tile-protocol.d.ts.map

package/offline/tile-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tile-protocol.d.ts","sourceRoot":"","sources":["../../../src/offline/tile-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EAElC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAA2B,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,kBAA0B,CAAC;AAIlE,mDAAmD;AACnD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,4BAA4B,GAAG,CACzC,OAAO,EAAE,4BAA4B,EACrC,eAAe,CAAC,EAAE,eAAe,KAC9B,OAAO,CAAC,6BAA6B,CAAC,CAAC;AAE5C,8EAA8E;AAC9E,MAAM,WAAW,8BAA8B;IAC7C,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAAC;IACzE,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,sCACf,SAAQ,IAAI,CAAC,4BAA4B,EAAE,MAAM,GAAG,QAAQ,GAAG,iBAAiB,GAAG,QAAQ,CAAC;IAC5F,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAC;CAC3D;AAED,8EAA8E;AAC9E,wBAAgB,iCAAiC,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAQ7G;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,0BAA0B,CAejF;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sCAAsC,GAC9C,4BAA4B,CAwB9B;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,8BAA8B,EACzC,OAAO,EAAE,sCAAsC,GAC9C,MAAM,IAAI,CAMZ"}

package/offline/tile-protocol.js

@@ -0,0 +1,119 @@
+import { readOfflineRegionTile, } from "./read-resource.js";
+import { OFFLINE_REGION_DEFAULT_TILE_MATRIX_SET, OFFLINE_REGION_PROTOCOL } from "./selection.js";
+import { HonuaOfflineRegionError } from "./types.js";
+/**
+ * Binding persisted tiles to the map runtime's existing protocol seam.
+ *
+ * The SDK already registers custom URL protocols with MapLibre through a
+ * `addProtocol(scheme, handler)` registrar (`src/runtime/pmtiles-protocol.ts`),
+ * so offline tiles reuse that seam rather than introducing a second tile
+ * pipeline: a style names `offline-region://…/{z}/{x}/{y}` tiles, and the handler
+ * answers each one from the persisted region under the full read discipline. A
+ * tile the region does not hold rejects with its typed reason — nothing falls
+ * back to the network, and nothing renders bytes the region never stored.
+ *
+ * Registration stays application-owned. The runtime does not yet auto-register
+ * this protocol or rewrite a style's tile URLs onto it.
+ *
+ * @experimental
+ */
+/** URL scheme a style uses to address tiles inside a persisted region. */
+export const OFFLINE_REGION_TILE_SCHEME = OFFLINE_REGION_PROTOCOL;
+const SCHEME_PREFIX = `${OFFLINE_REGION_TILE_SCHEME}://`;
+/** Build the tile-URL template a MapLibre source uses to address a region. */
+export function buildOfflineRegionTileUrlTemplate(options = {}) {
+    const set = options.tileMatrixSetId ?? OFFLINE_REGION_DEFAULT_TILE_MATRIX_SET;
+    if (typeof set !== "string" || set.length === 0 || set.includes("/")) {
+        throw new HonuaOfflineRegionError("invalid-manifest", "tileMatrixSetId must be a non-empty path segment.", {
+            path: "tileMatrixSetId",
+        });
+    }
+    return `${SCHEME_PREFIX}${set}/{z}/{x}/{y}`;
+}
+/**
+ * Parse an `offline-region://` tile URL.
+ *
+ * Parsing is a bounded segment split with no regular expression, and a URL
+ * carrying a query or fragment is refused outright: a tile address is an
+ * identity, and anything that could smuggle a token into one is not a tile
+ * address.
+ */
+export function parseOfflineRegionTileUrl(url) {
+    if (typeof url !== "string" || !url.startsWith(SCHEME_PREFIX)) {
+        throw invalid(`Tile URL must start with "${SCHEME_PREFIX}".`);
+    }
+    const rest = url.slice(SCHEME_PREFIX.length);
+    if (rest.includes("?") || rest.includes("#") || rest.includes("@")) {
+        throw invalid("Tile URL must not carry a query, fragment, or user information.");
+    }
+    const segments = rest.split("/");
+    if (segments.length !== 4)
+        throw invalid("Tile URL must be <tileMatrixSetId>/<z>/<x>/<y>.");
+    const [set, z, x, rawY] = segments;
+    if (set.length === 0)
+        throw invalid("Tile URL must name a tile matrix set.");
+    const dot = rawY.lastIndexOf(".");
+    const y = dot > 0 ? rawY.slice(0, dot) : rawY;
+    return { tileMatrixSetId: set, z: segment(z, "z"), x: segment(x, "x"), y: segment(y, "y") };
+}
+/**
+ * Create a MapLibre protocol handler that serves tiles from a persisted region.
+ *
+ * Register it with the same registrar the runtime uses for other custom schemes:
+ * `registrar.addProtocol(OFFLINE_REGION_TILE_SCHEME, handler)`.
+ */
+export function createOfflineRegionTileProtocol(options) {
+    if (!options?.manifest)
+        throw new TypeError("An offline region manifest is required.");
+    if (!options.store)
+        throw new TypeError("An offline region store is required.");
+    const { manifest, onTile, ...read } = options;
+    return async (request, abortController) => {
+        if (typeof request?.url !== "string")
+            throw new TypeError("request.url must be a string.");
+        const address = parseOfflineRegionTileUrl(request.url);
+        const tileRead = await readOfflineRegionTile(manifest, {
+            ...read,
+            tile: { z: address.z, x: address.x, y: address.y },
+            tileMatrixSetId: address.tileMatrixSetId,
+            ...(abortController ? { signal: abortController.signal } : {}),
+        });
+        try {
+            onTile?.(tileRead);
+        }
+        catch {
+            // Diagnostics are observational and never change what the map renders.
+        }
+        const bytes = tileRead.bytes;
+        const data = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        // The region is the cache. Declining a second layer of renderer caching keeps
+        // eviction, freshness, and provenance answerable from one place.
+        return { data, cacheControl: "no-store" };
+    };
+}
+/**
+ * Register the offline tile protocol and return its disposer.
+ *
+ * The registrar is the application's — usually `maplibre-gl` itself — so the SDK
+ * neither imports the peer nor decides when a map should read from a region.
+ */
+export function registerOfflineRegionTileProtocol(registrar, options) {
+    if (typeof registrar?.addProtocol !== "function") {
+        throw new TypeError("A MapLibre-style protocol registrar with addProtocol is required.");
+    }
+    registrar.addProtocol(OFFLINE_REGION_TILE_SCHEME, createOfflineRegionTileProtocol(options));
+    return () => registrar.removeProtocol?.(OFFLINE_REGION_TILE_SCHEME);
+}
+function segment(value, path) {
+    if (value.length === 0 || value.length > 12)
+        throw invalid(`Tile URL ${path} is not an integer.`);
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 48 || code > 57)
+            throw invalid(`Tile URL ${path} is not an integer.`);
+    }
+    return Number(value);
+}
+function invalid(message) {
+    return new HonuaOfflineRegionError("invalid-manifest", message, { path: "url" });
+}