@caoguo/maplibre 0.0.1

package/dist/offline/index.d.cts

@@ -0,0 +1,300 @@
+import { AddProtocolAction } from 'maplibre-gl';
+
+/**
+ * 离线瓦片存储抽象层（F-1.4）。
+ *
+ * 设计：存储后端可插拔。浏览器用 IndexedDB（idb），Node/测试用内存实现。
+ * 瓦片 key 统一为 `${sourceId}:${z}:${x}:${y}`，value 为原始字节 + 过期时间。
+ */
+type TileFormat = 'pbf' | 'geojson' | 'png' | 'mvt' | 'json';
+interface StoredTile {
+    data: ArrayBuffer | Uint8Array;
+    format: TileFormat;
+    /** 过期时间戳（ms）；0 表示永不过期 */
+    expires: number;
+}
+interface TileStoreBackend {
+    get(key: string): Promise<StoredTile | undefined>;
+    put(key: string, tile: StoredTile): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): Promise<void>;
+    size(): Promise<number>;
+}
+/** 内存实现（测试 / 无 IndexedDB 环境） */
+declare class MemoryTileStore implements TileStoreBackend {
+    private map;
+    get(key: string): Promise<StoredTile | undefined>;
+    put(key: string, tile: StoredTile): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): Promise<void>;
+    size(): Promise<number>;
+}
+declare function tileKey(sourceId: string, z: number, x: number, y: number): string;
+/** 离线协议名（caoguo-offline://...）。集中定义，供 protocol 与 serviceWorker 共用。 */
+declare const OFFLINE_PROTOCOL = "caoguo-offline";
+/**
+ * 解析离线协议 URL：`caoguo-offline://{sourceId}/{z}/{x}/{y}`
+ * 返回 sourceId 与瓦片坐标，便于 ProtocolHandler 取瓦片。
+ */
+declare function parseOfflineUrl(url: string): {
+    sourceId: string;
+    z: number;
+    x: number;
+    y: number;
+} | null;
+
+/**
+ * 离线协议加载器（F-1.4）。
+ *
+ * 通过 MapLibre `addProtocol('caoguo-offline', loader)` 注册自定义协议，
+ * 瓦片源可声明 `tiles: ['caoguo-offline://{sourceId}/{z}/{x}/{y}']`，
+ * 引擎即从离线存储读取瓦片，实现「空气隔离」离线底图。
+ *
+ * MapLibre v4 的 protocol handler 签名：
+ *   (requestParameters, abortController) => Promise<{ data: ArrayBuffer }>
+ */
+
+interface OfflineProtocolContext {
+    store: TileStoreBackend;
+}
+/** 构造离线协议 URL（供 source.tiles 使用） */
+declare function offlineTileUrl(sourceId: string, z: number, x: number, y: number): string;
+/** 生成离线栅格/矢量源的 tiles 数组 */
+declare function offlineSourceTiles(sourceId: string): string[];
+/**
+ * 创建离线协议 loader（返回可直接传给 addProtocol 的异步函数）。
+ * 未命中瓦片时 reject，由 MapLibre 回退到线上源（若配置）。
+ */
+declare function createOfflineLoader(ctx: OfflineProtocolContext): AddProtocolAction;
+/** 在指定地图实例上注册离线协议 */
+declare function registerOfflineProtocol(maplibregl: {
+    addProtocol: (name: string, action: AddProtocolAction) => void;
+}, ctx: OfflineProtocolContext): void;
+
+/**
+ * 离线瓦片打包器（F-1.4）。
+ *
+ * 把本地瓦片导入离线存储：
+ *  - 原始 {z}/{x}/{y}.pbf|png 目录结构
+ *  - 单张 GeoJSON（按 z/x/y 网格切片为矢量瓦片缓冲，供 `caoguo-offline` 协议读取）
+ *
+ * 这里的「切片」为简化实现：GeoJSON 按瓦片网格空间包含关系分桶，
+ * 仅把要素写入对应瓦片（不做 MVT 编码），存储为 UTF-8 JSON，
+ * 由 protocol loader 以 `geojson` 格式返回，source type 用 geojson。
+ * 生产级 MVT 编码（tippecanoe / @mapbox/vector-tile）可后续接入。
+ */
+
+interface PackGeoJSONOptions {
+    sourceId: string;
+    geojson: {
+        type: 'FeatureCollection';
+        features: Array<{
+            geometry: {
+                type: string;
+                coordinates: unknown;
+            };
+            properties: Record<string, unknown>;
+        }>;
+    };
+    maxZoom?: number;
+    /** 过期时间（ms 时间戳），0=永不过期 */
+    expires?: number;
+    onProgress?: (done: number, total: number) => void;
+}
+/**
+ * 将 GeoJSON 按瓦片网格分桶写入离线存储。
+ * 返回写入的瓦片数量。
+ */
+declare function packGeoJSONToStore(store: TileStoreBackend, opts: PackGeoJSONOptions): Promise<number>;
+/**
+ * 由离线存储构造一个 geojson 源（用于 MapLibre source.tiles）。
+ * 注意：geojson 协议瓦片由 protocol loader 直接返回 FeatureCollection。
+ */
+declare function offlineGeoJSONSource(sourceId: string): {
+    type: 'geojson';
+    data: never;
+} & {
+    tiles: string[];
+    _caoguoOffline: true;
+    _sourceId: string;
+};
+
+/**
+ * Service Worker 离线拦截（T5 / F-1.6）。
+ *
+ * 目标：在 T4 离线瓦片（IndexedDB + caoguo-offline 协议）之上，增加一层
+ * **网络级二级缓存**——用 Cache API 缓存线上请求的瓦片（天地图等），并在
+ * 「空气隔离（air-gap）」模式下拦截所有请求、用 Cache/离线存储兜底，
+ * 实现断网后地图仍可平移缩放。
+ *
+ * 设计：
+ * - `resolveCacheKey` / `shouldCache` / `resolveResponse` 是**纯函数 core**，
+ *   不依赖真实 ServiceWorker 全局，可在 Node/vitest 中直接测试。
+ * - `createFetchHandler` 把 core 包装成标准 `fetch` 事件处理器（注入 cache 与 store）。
+ * - 浏览器侧用 `registerServiceWorker` 注册脚本，并通过 postMessage 切换空气隔离模式。
+ *
+ * 与 T4 的边界：T4 负责「业务离线瓦片 → IndexedDB → maplibre 协议」，
+ * 本模块负责「线上瓦片请求 → Cache API 二级缓存 + 空气隔离拦截」，
+ * 二者互补：T4 命中时根本不发网络请求（协议层短路），未命中时才走到 SW 缓存。
+ */
+
+/** 需要二级缓存的瓦片来源（host 白名单，避免缓存无关资源） */
+declare const CACHEABLE_HOSTS: string[];
+/** 缓存名称（版本化，便于失效升级） */
+declare const CACHE_NAME = "caoguo-offline-tiles-v1";
+/** 空气隔离模式消息协议 */
+declare const MSG_AIRGAP: "caoguo:airgap";
+interface AirgapMessage {
+    type: typeof MSG_AIRGAP;
+    /** true=开启空气隔离（断网模式），false=恢复在线优先 */
+    enabled: boolean;
+}
+/**
+ * 判断请求是否应进入离线二级缓存。
+ * 只缓存 GET 请求 & 白名单 host & 图片/瓦片类型（保守策略）。
+ */
+declare function shouldCache(request: {
+    method: string;
+    url: string;
+}): boolean;
+/**
+ * 计算 Cache Storage 的 key。优先用 URL（含 query，token 不同视为不同资源），
+ * 否则回退到 request 对象本身。
+ */
+declare function resolveCacheKey(request: {
+    url: string;
+}): string;
+/**
+ * 从存储（IndexedDB/T4 离线）尝试取得瓦片兜底。
+ * 用于空气隔离模式下网络不可达时返回上次离线打包的瓦片。
+ */
+declare function resolveFromStore(store: TileStoreBackend | undefined, request: {
+    url: string;
+}): Promise<{
+    data: ArrayBuffer;
+    contentType: string;
+} | undefined>;
+interface ResolveResponseDeps {
+    /** 实际的 fetch 实现（浏览器为全局 fetch，测试可注入） */
+    fetchImpl: (input: string) => Promise<{
+        ok: boolean;
+        status: number;
+        arrayBuffer: () => Promise<ArrayBuffer>;
+        headers: {
+            get: (k: string) => string | null;
+        };
+    }>;
+    /** Cache 接口（浏览器为全局 caches，测试可注入内存实现） */
+    cache: {
+        match: (key: string) => Promise<CacheEntry | undefined>;
+        put: (key: string, resp: unknown) => Promise<void>;
+    };
+    /** 空气隔离开关（闭包状态，由消息控制） */
+    airgap: {
+        enabled: boolean;
+    };
+    /** T4 离线存储（可选，空气隔离兜底） */
+    store?: TileStoreBackend;
+}
+interface CacheEntry {
+    ok: boolean;
+    status: number;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    headers: {
+        get: (k: string) => string | null;
+    };
+}
+interface ResolvedResponse {
+    /** 最终响应主体 */
+    data: ArrayBuffer;
+    /** 内容类型 */
+    contentType: string;
+    /** 来源：cache=命中缓存 / network=线上最新 / store=离线存储兜底 */
+    source: 'cache' | 'network' | 'store';
+    /** 该响应是否应写回缓存 */
+    cacheable: boolean;
+}
+/**
+ * 核心解析逻辑（纯函数，可测试）。
+ * 两种模式：
+ * - 在线优先（airgap=false）：cache → network(写回 cache) → store 兜底
+ * - 空气隔离（airgap=true）：cache → store 兜底（不发网络请求）
+ */
+declare function resolveResponse(request: {
+    method: string;
+    url: string;
+}, deps: ResolveResponseDeps): Promise<ResolvedResponse | null>;
+/**
+ * 包装为 Service Worker 的 fetch 事件处理器。
+ * 注入真实的 caches / fetch / store。在浏览器 SW 全局中调用：
+ *   self.addEventListener('fetch', createFetchHandler({ store }));
+ */
+declare function createFetchHandler(opts: {
+    store?: TileStoreBackend;
+    airgap?: {
+        enabled: boolean;
+    };
+}): (event: {
+    request: {
+        method: string;
+        url: string;
+    };
+    respondWith: (r: Promise<Response> | Response) => void;
+}) => void;
+/**
+ * 在 Service Worker 全局上安装离线拦截逻辑（浏览器 SW 脚本入口）。
+ * 处理 install/activate 生命周期、airgap 消息、fetch 拦截。
+ */
+declare function installServiceWorker(sw: {
+    addEventListener: (type: string, handler: (ev: unknown) => void) => void;
+    caches: unknown;
+    store?: TileStoreBackend;
+}): {
+    airgap: {
+        enabled: boolean;
+    };
+};
+/**
+ * 浏览器端注册离线 Service Worker（主线程调用）。
+ * 需要项目提供 SW 脚本文件（见 `sw-template` 注释），并部署到与地图同域根路径。
+ *
+ * @param scriptUrl SW 脚本 URL（如 '/caoguo-sw.js'），需调用方自行构建/放置
+ * @returns 注册成功的 ServiceWorker 实例；不支持时返回 null
+ */
+declare function registerOfflineServiceWorker(scriptUrl: string): Promise<ServiceWorkerRegistration | null>;
+/**
+ * 向已注册的 Service Worker 发送消息，切换「空气隔离」模式。
+ * enabled=true 时地图进入断网可用状态（仅用 Cache + T4 离线存储）。
+ */
+declare function setAirgap(registration: ServiceWorkerRegistration, enabled: boolean): void;
+/**
+ * SW 脚本模板（供调用方写入部署文件，如 public/caoguo-sw.js）。
+ * 该脚本通过 importScripts 复用本包编译产物，或直接内联 installServiceWorker。
+ *
+ * ```js
+ * // caoguo-sw.js
+ * importScripts('/caoguo-offline-sw.bundle.js'); // 含 installServiceWorker
+ * installServiceWorker(self);
+ * ```
+ */
+declare const SW_TEMPLATE_HINT = "importScripts('caoguo-offline-sw.bundle.js'); installServiceWorker(self);";
+
+/**
+ * IndexedDB 离线瓦片后端（浏览器环境，F-1.4）。
+ * 延迟依赖 idb；仅当运行在浏览器时加载，避免 Node/测试环境报错。
+ */
+
+declare class IdbTileStore implements TileStoreBackend {
+    get(key: string): Promise<StoredTile | undefined>;
+    put(key: string, tile: StoredTile): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): Promise<void>;
+    size(): Promise<number>;
+}
+/** 浏览器环境默认用 IndexedDB，否则回退内存 */
+declare function createDefaultStore(): TileStoreBackend;
+
+export { type AirgapMessage, CACHEABLE_HOSTS, CACHE_NAME, IdbTileStore, MSG_AIRGAP, MemoryTileStore, OFFLINE_PROTOCOL, type OfflineProtocolContext, type PackGeoJSONOptions, type ResolveResponseDeps, type ResolvedResponse, SW_TEMPLATE_HINT, type StoredTile, type TileFormat, type TileStoreBackend, createDefaultStore, createFetchHandler, createOfflineLoader, installServiceWorker, offlineGeoJSONSource, offlineSourceTiles, offlineTileUrl, packGeoJSONToStore, parseOfflineUrl, registerOfflineProtocol, registerOfflineServiceWorker, resolveCacheKey, resolveFromStore, resolveResponse, setAirgap, shouldCache, tileKey };

package/dist/offline/index.d.ts

@@ -0,0 +1,300 @@
+import { AddProtocolAction } from 'maplibre-gl';
+
+/**
+ * 离线瓦片存储抽象层（F-1.4）。
+ *
+ * 设计：存储后端可插拔。浏览器用 IndexedDB（idb），Node/测试用内存实现。
+ * 瓦片 key 统一为 `${sourceId}:${z}:${x}:${y}`，value 为原始字节 + 过期时间。
+ */
+type TileFormat = 'pbf' | 'geojson' | 'png' | 'mvt' | 'json';
+interface StoredTile {
+    data: ArrayBuffer | Uint8Array;
+    format: TileFormat;
+    /** 过期时间戳（ms）；0 表示永不过期 */
+    expires: number;
+}
+interface TileStoreBackend {
+    get(key: string): Promise<StoredTile | undefined>;
+    put(key: string, tile: StoredTile): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): Promise<void>;
+    size(): Promise<number>;
+}
+/** 内存实现（测试 / 无 IndexedDB 环境） */
+declare class MemoryTileStore implements TileStoreBackend {
+    private map;
+    get(key: string): Promise<StoredTile | undefined>;
+    put(key: string, tile: StoredTile): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): Promise<void>;
+    size(): Promise<number>;
+}
+declare function tileKey(sourceId: string, z: number, x: number, y: number): string;
+/** 离线协议名（caoguo-offline://...）。集中定义，供 protocol 与 serviceWorker 共用。 */
+declare const OFFLINE_PROTOCOL = "caoguo-offline";
+/**
+ * 解析离线协议 URL：`caoguo-offline://{sourceId}/{z}/{x}/{y}`
+ * 返回 sourceId 与瓦片坐标，便于 ProtocolHandler 取瓦片。
+ */
+declare function parseOfflineUrl(url: string): {
+    sourceId: string;
+    z: number;
+    x: number;
+    y: number;
+} | null;
+
+/**
+ * 离线协议加载器（F-1.4）。
+ *
+ * 通过 MapLibre `addProtocol('caoguo-offline', loader)` 注册自定义协议，
+ * 瓦片源可声明 `tiles: ['caoguo-offline://{sourceId}/{z}/{x}/{y}']`，
+ * 引擎即从离线存储读取瓦片，实现「空气隔离」离线底图。
+ *
+ * MapLibre v4 的 protocol handler 签名：
+ *   (requestParameters, abortController) => Promise<{ data: ArrayBuffer }>
+ */
+
+interface OfflineProtocolContext {
+    store: TileStoreBackend;
+}
+/** 构造离线协议 URL（供 source.tiles 使用） */
+declare function offlineTileUrl(sourceId: string, z: number, x: number, y: number): string;
+/** 生成离线栅格/矢量源的 tiles 数组 */
+declare function offlineSourceTiles(sourceId: string): string[];
+/**
+ * 创建离线协议 loader（返回可直接传给 addProtocol 的异步函数）。
+ * 未命中瓦片时 reject，由 MapLibre 回退到线上源（若配置）。
+ */
+declare function createOfflineLoader(ctx: OfflineProtocolContext): AddProtocolAction;
+/** 在指定地图实例上注册离线协议 */
+declare function registerOfflineProtocol(maplibregl: {
+    addProtocol: (name: string, action: AddProtocolAction) => void;
+}, ctx: OfflineProtocolContext): void;
+
+/**
+ * 离线瓦片打包器（F-1.4）。
+ *
+ * 把本地瓦片导入离线存储：
+ *  - 原始 {z}/{x}/{y}.pbf|png 目录结构
+ *  - 单张 GeoJSON（按 z/x/y 网格切片为矢量瓦片缓冲，供 `caoguo-offline` 协议读取）
+ *
+ * 这里的「切片」为简化实现：GeoJSON 按瓦片网格空间包含关系分桶，
+ * 仅把要素写入对应瓦片（不做 MVT 编码），存储为 UTF-8 JSON，
+ * 由 protocol loader 以 `geojson` 格式返回，source type 用 geojson。
+ * 生产级 MVT 编码（tippecanoe / @mapbox/vector-tile）可后续接入。
+ */
+
+interface PackGeoJSONOptions {
+    sourceId: string;
+    geojson: {
+        type: 'FeatureCollection';
+        features: Array<{
+            geometry: {
+                type: string;
+                coordinates: unknown;
+            };
+            properties: Record<string, unknown>;
+        }>;
+    };
+    maxZoom?: number;
+    /** 过期时间（ms 时间戳），0=永不过期 */
+    expires?: number;
+    onProgress?: (done: number, total: number) => void;
+}
+/**
+ * 将 GeoJSON 按瓦片网格分桶写入离线存储。
+ * 返回写入的瓦片数量。
+ */
+declare function packGeoJSONToStore(store: TileStoreBackend, opts: PackGeoJSONOptions): Promise<number>;
+/**
+ * 由离线存储构造一个 geojson 源（用于 MapLibre source.tiles）。
+ * 注意：geojson 协议瓦片由 protocol loader 直接返回 FeatureCollection。
+ */
+declare function offlineGeoJSONSource(sourceId: string): {
+    type: 'geojson';
+    data: never;
+} & {
+    tiles: string[];
+    _caoguoOffline: true;
+    _sourceId: string;
+};
+
+/**
+ * Service Worker 离线拦截（T5 / F-1.6）。
+ *
+ * 目标：在 T4 离线瓦片（IndexedDB + caoguo-offline 协议）之上，增加一层
+ * **网络级二级缓存**——用 Cache API 缓存线上请求的瓦片（天地图等），并在
+ * 「空气隔离（air-gap）」模式下拦截所有请求、用 Cache/离线存储兜底，
+ * 实现断网后地图仍可平移缩放。
+ *
+ * 设计：
+ * - `resolveCacheKey` / `shouldCache` / `resolveResponse` 是**纯函数 core**，
+ *   不依赖真实 ServiceWorker 全局，可在 Node/vitest 中直接测试。
+ * - `createFetchHandler` 把 core 包装成标准 `fetch` 事件处理器（注入 cache 与 store）。
+ * - 浏览器侧用 `registerServiceWorker` 注册脚本，并通过 postMessage 切换空气隔离模式。
+ *
+ * 与 T4 的边界：T4 负责「业务离线瓦片 → IndexedDB → maplibre 协议」，
+ * 本模块负责「线上瓦片请求 → Cache API 二级缓存 + 空气隔离拦截」，
+ * 二者互补：T4 命中时根本不发网络请求（协议层短路），未命中时才走到 SW 缓存。
+ */
+
+/** 需要二级缓存的瓦片来源（host 白名单，避免缓存无关资源） */
+declare const CACHEABLE_HOSTS: string[];
+/** 缓存名称（版本化，便于失效升级） */
+declare const CACHE_NAME = "caoguo-offline-tiles-v1";
+/** 空气隔离模式消息协议 */
+declare const MSG_AIRGAP: "caoguo:airgap";
+interface AirgapMessage {
+    type: typeof MSG_AIRGAP;
+    /** true=开启空气隔离（断网模式），false=恢复在线优先 */
+    enabled: boolean;
+}
+/**
+ * 判断请求是否应进入离线二级缓存。
+ * 只缓存 GET 请求 & 白名单 host & 图片/瓦片类型（保守策略）。
+ */
+declare function shouldCache(request: {
+    method: string;
+    url: string;
+}): boolean;
+/**
+ * 计算 Cache Storage 的 key。优先用 URL（含 query，token 不同视为不同资源），
+ * 否则回退到 request 对象本身。
+ */
+declare function resolveCacheKey(request: {
+    url: string;
+}): string;
+/**
+ * 从存储（IndexedDB/T4 离线）尝试取得瓦片兜底。
+ * 用于空气隔离模式下网络不可达时返回上次离线打包的瓦片。
+ */
+declare function resolveFromStore(store: TileStoreBackend | undefined, request: {
+    url: string;
+}): Promise<{
+    data: ArrayBuffer;
+    contentType: string;
+} | undefined>;
+interface ResolveResponseDeps {
+    /** 实际的 fetch 实现（浏览器为全局 fetch，测试可注入） */
+    fetchImpl: (input: string) => Promise<{
+        ok: boolean;
+        status: number;
+        arrayBuffer: () => Promise<ArrayBuffer>;
+        headers: {
+            get: (k: string) => string | null;
+        };
+    }>;
+    /** Cache 接口（浏览器为全局 caches，测试可注入内存实现） */
+    cache: {
+        match: (key: string) => Promise<CacheEntry | undefined>;
+        put: (key: string, resp: unknown) => Promise<void>;
+    };
+    /** 空气隔离开关（闭包状态，由消息控制） */
+    airgap: {
+        enabled: boolean;
+    };
+    /** T4 离线存储（可选，空气隔离兜底） */
+    store?: TileStoreBackend;
+}
+interface CacheEntry {
+    ok: boolean;
+    status: number;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    headers: {
+        get: (k: string) => string | null;
+    };
+}
+interface ResolvedResponse {
+    /** 最终响应主体 */
+    data: ArrayBuffer;
+    /** 内容类型 */
+    contentType: string;
+    /** 来源：cache=命中缓存 / network=线上最新 / store=离线存储兜底 */
+    source: 'cache' | 'network' | 'store';
+    /** 该响应是否应写回缓存 */
+    cacheable: boolean;
+}
+/**
+ * 核心解析逻辑（纯函数，可测试）。
+ * 两种模式：
+ * - 在线优先（airgap=false）：cache → network(写回 cache) → store 兜底
+ * - 空气隔离（airgap=true）：cache → store 兜底（不发网络请求）
+ */
+declare function resolveResponse(request: {
+    method: string;
+    url: string;
+}, deps: ResolveResponseDeps): Promise<ResolvedResponse | null>;
+/**
+ * 包装为 Service Worker 的 fetch 事件处理器。
+ * 注入真实的 caches / fetch / store。在浏览器 SW 全局中调用：
+ *   self.addEventListener('fetch', createFetchHandler({ store }));
+ */
+declare function createFetchHandler(opts: {
+    store?: TileStoreBackend;
+    airgap?: {
+        enabled: boolean;
+    };
+}): (event: {
+    request: {
+        method: string;
+        url: string;
+    };
+    respondWith: (r: Promise<Response> | Response) => void;
+}) => void;
+/**
+ * 在 Service Worker 全局上安装离线拦截逻辑（浏览器 SW 脚本入口）。
+ * 处理 install/activate 生命周期、airgap 消息、fetch 拦截。
+ */
+declare function installServiceWorker(sw: {
+    addEventListener: (type: string, handler: (ev: unknown) => void) => void;
+    caches: unknown;
+    store?: TileStoreBackend;
+}): {
+    airgap: {
+        enabled: boolean;
+    };
+};
+/**
+ * 浏览器端注册离线 Service Worker（主线程调用）。
+ * 需要项目提供 SW 脚本文件（见 `sw-template` 注释），并部署到与地图同域根路径。
+ *
+ * @param scriptUrl SW 脚本 URL（如 '/caoguo-sw.js'），需调用方自行构建/放置
+ * @returns 注册成功的 ServiceWorker 实例；不支持时返回 null
+ */
+declare function registerOfflineServiceWorker(scriptUrl: string): Promise<ServiceWorkerRegistration | null>;
+/**
+ * 向已注册的 Service Worker 发送消息，切换「空气隔离」模式。
+ * enabled=true 时地图进入断网可用状态（仅用 Cache + T4 离线存储）。
+ */
+declare function setAirgap(registration: ServiceWorkerRegistration, enabled: boolean): void;
+/**
+ * SW 脚本模板（供调用方写入部署文件，如 public/caoguo-sw.js）。
+ * 该脚本通过 importScripts 复用本包编译产物，或直接内联 installServiceWorker。
+ *
+ * ```js
+ * // caoguo-sw.js
+ * importScripts('/caoguo-offline-sw.bundle.js'); // 含 installServiceWorker
+ * installServiceWorker(self);
+ * ```
+ */
+declare const SW_TEMPLATE_HINT = "importScripts('caoguo-offline-sw.bundle.js'); installServiceWorker(self);";
+
+/**
+ * IndexedDB 离线瓦片后端（浏览器环境，F-1.4）。
+ * 延迟依赖 idb；仅当运行在浏览器时加载，避免 Node/测试环境报错。
+ */
+
+declare class IdbTileStore implements TileStoreBackend {
+    get(key: string): Promise<StoredTile | undefined>;
+    put(key: string, tile: StoredTile): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): Promise<void>;
+    size(): Promise<number>;
+}
+/** 浏览器环境默认用 IndexedDB，否则回退内存 */
+declare function createDefaultStore(): TileStoreBackend;
+
+export { type AirgapMessage, CACHEABLE_HOSTS, CACHE_NAME, IdbTileStore, MSG_AIRGAP, MemoryTileStore, OFFLINE_PROTOCOL, type OfflineProtocolContext, type PackGeoJSONOptions, type ResolveResponseDeps, type ResolvedResponse, SW_TEMPLATE_HINT, type StoredTile, type TileFormat, type TileStoreBackend, createDefaultStore, createFetchHandler, createOfflineLoader, installServiceWorker, offlineGeoJSONSource, offlineSourceTiles, offlineTileUrl, packGeoJSONToStore, parseOfflineUrl, registerOfflineProtocol, registerOfflineServiceWorker, resolveCacheKey, resolveFromStore, resolveResponse, setAirgap, shouldCache, tileKey };

package/dist/offline/index.js

@@ -0,0 +1,3 @@
+export { CACHEABLE_HOSTS, CACHE_NAME, IdbTileStore, MSG_AIRGAP, MemoryTileStore, OFFLINE_PROTOCOL, SW_TEMPLATE_HINT, createDefaultStore, createFetchHandler, createOfflineLoader, installServiceWorker, offlineGeoJSONSource, offlineSourceTiles, offlineTileUrl, packGeoJSONToStore, parseOfflineUrl, registerOfflineProtocol, registerOfflineServiceWorker, resolveCacheKey, resolveFromStore, resolveResponse, setAirgap, shouldCache, tileKey } from '../chunk-MNUQZUQA.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/offline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}