s3m-three 0.4.16 → 0.4.18

package/docs/API.md

@@ -13,7 +13,7 @@
 - [样式（S3MStyle）](#样式s3mstyle)
 - [拾取与属性](#拾取与属性)
 - [投影](#投影)
-- [按业务字段着色](#按业务字段着色)
+- [业务字段：锚点在库内，对应关系在外部](#业务字段锚点在库内对应关系在外部)
 - [动画与过渡](#动画与过渡)
 - [纯 three.js 使用](#纯-threejs-使用)
 - [底层 API](#底层-api)
@@ -176,7 +176,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `maxImageCache` | `number` | `128` | 纹理缓存条数上限。一条 = 一张已解码的瓦片纹理，1024² RGBA 约 4MB，128 条即约 512MB 显存；低端设备 32~48。LRU，降下来下次淘汰时释放 |
 | `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。模块级全局，只影响之后创建的材质 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
-| `attributes` | `AttributeQueryOptions` | — | 业务属性查询配置，配了才能 `colorByField()`，见[按业务字段着色](#按业务字段着色) |
+| `attributes` | `AttributeQueryOptions` | — | 可选的 iServer 数据服务配置，配了才能用 `colorByField()` 等便利方法；不配就自己取数 + `setFeaturesStyle()`，见[业务字段](#业务字段锚点在库内对应关系在外部) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
 | `getBearing` | `() => number` | — | 地图朝向（弧度），让灯光跟着视角走；不传则灯光方向固定 |
 | `onStats` | `(s: Stats) => void` | — | 统计更新 |
@@ -334,7 +334,7 @@ getFilter(): S3MFilter | null
 clearFilter(): void
 ```
 
-详见[按业务字段着色](#按业务字段着色)。
+详见[业务字段](#业务字段锚点在库内对应关系在外部)。
 
 ### 3D 物理地表与基坑
 
@@ -536,7 +536,7 @@ interface PickResult {
 }
 ```
 
-> **注意**：`height` / `floors` / `bboxArea` 这些是**从几何算出来的**，不是业务属性表。OSGB 转 S3M 的数据通常不带属性表，`smid` 是与 iServer 侧数据对齐的唯一标识，业务字段需要你自己按 `smid` 去外部关联。
+> **注意**：`height` / `floors` / `bboxArea` 这些是**从几何算出来的**，不是业务属性表。OSGB 转 S3M 的数据通常不带属性表，`smid` 是与 iServer 侧数据对齐的唯一标识，业务字段需要你自己按 `smid` 去外部关联 —— 库不内置这个对应关系，见[业务字段](#业务字段锚点在库内对应关系在外部)。
 
 需要接业务属性时，用 `onPick` 拿到 `smid` 后自行查询：
 
@@ -572,9 +572,31 @@ V = P⁻¹ × MVP
 
 ---
 
-## 按业务字段着色
+## 业务字段：锚点在库内，对应关系在外部
 
-S3M 瓦片里**只有单体 ID**（SMID）和顶点区间，没有任何业务字段；业务属性在 iServer 的**数据服务**里（`data-xxx/rest/data`），和三维服务（`3D-xxx/rest/realspace`）是两个服务。所以按字段着色是「三维 + 数据」的跨服务查询，需要单独配一个数据源。
+S3M 瓦片里**只有单体 ID（SMID）和顶点区间，没有任何业务字段**。所以"哪个字段代表这栋楼、这栋楼在业务系统里是谁"这件事，库不替你做——鉴权、主子表、多数据源、字段命名每家都不一样，一旦内置就得跟着业务改。
+
+库只提供三个锚点：
+
+| 能力 | API |
+|---|---|
+| 拿到单体 ID | `onPick` 回调里的 `feature.smid` |
+| 单个 / 批量落样式 | `setFeatureStyle(smid, style)` / `setFeaturesStyle(smids, style)` |
+| 批量上色 | `setThematicColors(Map<smid, color>)` |
+
+推荐写法是**外部取数 → 自己算 → 落样式**：
+
+```ts
+const smids = viewer.getLoadedSmids();                       // 当前加载进来的单体
+const rows = await myOwnApi(smids);                          // 你自己的后端、自己的鉴权
+const colors = new Map<number, string>();
+for (const [smid, row] of rows) colors.set(smid, pickColor(row.用途));
+viewer.setThematicColors(colors);                            // 一次写纹理，不重建几何
+```
+
+### 内置的 iServer 便利版（可选）
+
+如果业务属性**刚好**发布在同一个 iServer 的**数据服务**里（`data-xxx/rest/data`，和三维服务 `3D-xxx/rest/realspace` 是两个服务），且单体 ID 列就是 `SmID`、没有额外鉴权，可以直接用内置的三个方法，省掉自己写查询：
 
 ```ts
 const viewer = new S3MViewer({
@@ -586,29 +608,25 @@ const viewer = new S3MViewer({
   },
 });
 
-// 分类字段：同一取值同色
-const result = await viewer.colorByField({ field: 'KEYID', type: 'category' });
-
-// 数值字段：连续色带 / 按阈值分级
-await viewer.colorByField({ field: 'SmMaxZ', type: 'ramp' });
-await viewer.colorByField({ field: 'SmMaxZ', type: 'breaks', breaks: [10, 30, 60] });
-
-result.legend;    // [{ label, color, count }]  直接拿去画图例
-result.matched;   // 真正上了色的单体数
+await viewer.colorByField({ field: 'SmMaxZ', type: 'ramp' });   // 数值列：连续色带
+await viewer.colorByField({ field: 'KEYID', type: 'category' }); // 字符串列：同值同色
+await viewer.filterByField({ field: '用途', values: ['住宅'] });  // 只显示命中
+await viewer.elevateByField({ field: 'SmMaxZ', scale: 0.5 });    // 按字段抬高
 ```
 
-几个要点：
+它的能力边界很明确，超出就别硬套，自己写：
 
-- **默认范围是「当前已加载的单体」**（`getLoadedSmids()`），不是整个数据集。实测每条要素的响应约 5KB（模型数据集每条都挂着 `geometry.model`，见下面的「为什么这么重」），全量几千栋会变成几十 MB，所以只查加载进来的那部分，按 200 个一批分片；
-- 查询结果按 SMID 缓存**整行**（`AttributeQuery`），换字段只是重算颜色、重写一张一维纹理，不重建几何、不重编译着色器，也不再发一次请求；
+- **只认 iServer 数据服务**，换后端没有口子；
+- **键固定是 `SmID`**（可用 `idField` 改名，但语义仍是"属性表里有一列等于 smid"）；
+- 三个方法**各自查各自的**，共享的只是 `AttributeQuery` 内部那份整行缓存；
+- 默认范围是**当前已加载的单体**（`getLoadedSmids()`），不是整个数据集。实测每条要素约 5KB（模型数据集每条都挂着 `geometry.model`），全量几千栋会变成几十 MB，所以按 200 个一批分片；
+- 查询结果按 SMID 缓存**整行**，换字段只重算颜色、重写一维纹理，不重建几何、不重编译着色器，也不再发请求；
 - 手动 `setFeatureStyle()` 的颜色优先级高于专题色；
-- `transform` 用来归并取值：`KEYID` / `ENTITYID` 这种基本一栋一个值的字段直接上分类色，着出来就是「随机色」，要么改用 `ramp` / `breaks`，要么用 `transform` 把编码截到能分组的层级，比如 `(v) => v.slice(0, 6)`;
-- `breaks` 不给就用色带档数等分；`colors` 不给就用内置 12 色板。
+- `transform` 用来归并取值：`KEYID` / `ENTITYID` 这种基本一栋一个值的字段直接上分类色会变成"随机色"，要么改用 `ramp` / `breaks`，要么用 `transform` 把编码截到能分组的层级。
 
-不想接数据服务时，也可以：
+不接数据服务也能自己算颜色（比如按几何派生量：高度 / 面积 / 楼层）：
 
 ```ts
-// 自己算好颜色（比如按几何派生量：高度 / 面积 / 楼层）
 viewer.setThematicColors(new Map([[423, '#ef4444'], [424, '#22c55e']]));
 viewer.clearThematic();
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {

package/src/core/AttributeQuery.ts

@@ -23,6 +23,8 @@
  * 这样换专题字段时全部命中缓存，不再发请求。
  */
 
+import { resolveAuthRequest, type AuthenticateFn } from './AuthFetch.js';
+
 const DEFAULT_ID_FIELD = 'SmID';
 const DEFAULT_CHUNK_SIZE = 200;
 /** 几何/索引字段取回来没用，还特别占带宽 */
@@ -44,6 +46,11 @@ export interface AttributeQueryOptions {
   format?: 'auto' | 'fastjson' | 'json';
   /** 便于测试时替换，默认用全局 fetch */
   fetchImpl?: typeof fetch;
+  /**
+   * 鉴权适配函数（不填则用图层级的 `authenticate`）。请求发出前过一遍，
+   * 可改写 URL（加 `?token=`）或附加请求头。见 `AuthenticateFn`。
+   */
+  authenticate?: AuthenticateFn;
 }
 
 export interface AttributeField {
@@ -93,6 +100,7 @@ export class AttributeQuery {
   private readonly _chunkSize: number;
   private readonly _formatOption: 'auto' | 'fastjson' | 'json';
   private readonly _fetch: typeof fetch;
+  private readonly _authenticate: AuthenticateFn | undefined;
   private readonly _cache = new Map<number, AttributeRow>();
   private _schema: AttributeField[] | null = null;
   private _resolvedFields: string[] | null = null;
@@ -113,6 +121,7 @@ export class AttributeQuery {
     this._chunkSize = Math.max(1, options.chunkSize ?? DEFAULT_CHUNK_SIZE);
     this._formatOption = options.format ?? 'auto';
     this._fetch = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this._authenticate = options.authenticate;
   }
 
   /** 数据集的 REST 路径：.../datasources/name/{ds}/datasets/name/{name} */
@@ -120,6 +129,20 @@ export class AttributeQuery {
     return `${this.dataServiceUrl}/datasources/name/${encodeURIComponent(this.datasourceName)}/datasets/name/${encodeURIComponent(this.datasetName)}`;
   }
 
+  /**
+   * 带鉴权的请求：先过 `authenticate` 钩子改写 URL / 追加 header，再走本查询的
+   * 传输层（`fetchImpl` 或全局 fetch，自定义传输不被绕过）。未配置鉴权时与旧版
+   * 行为逐字一致（参数原样透传）。
+   */
+  private async _request(url: string, init?: RequestInit): Promise<Response> {
+    const resolved = await resolveAuthRequest(url, this._authenticate, 'attributes');
+    const hookHeaders = resolved.headers && Object.keys(resolved.headers).length > 0 ? resolved.headers : null;
+    if (!hookHeaders) return init === undefined ? this._fetch(resolved.url) : this._fetch(resolved.url, init);
+    // 钩子头在前，init 头在后：调用方显式给的头（如 Content-Type）不被覆盖
+    const headers = { ...hookHeaders, ...init?.headers } as Record<string, string>;
+    return this._fetch(resolved.url, { ...init, headers });
+  }
+
   /** 累计的请求代价（不清零，用来观察整体开销） */
   get stats(): AttributeQueryStats {
     return { ...this._stats };
@@ -128,7 +151,7 @@ export class AttributeQuery {
   /** 字段表（顺手也用来判断「这个数据集到底有没有属性表」） */
   async loadSchema(): Promise<AttributeField[]> {
     if (this._schema) return this._schema;
-    const res = await this._fetch(`${this.datasetPath}/fields.json`);
+    const res = await this._request(`${this.datasetPath}/fields.json`);
     this._stats.requests++;
     if (!res.ok) throw new Error(`[s3m] 读取字段表失败 ${res.status}：${this.datasetPath}/fields.json`);
     const json = (await res.json()) as { fieldNames?: string[] };
@@ -197,7 +220,7 @@ export class AttributeQuery {
     if (this._format) return this._format;
     if (this._formatOption !== 'auto') return (this._format = this._formatOption);
     try {
-      const res = await this._fetch(`${this.datasetPath}/features.json?fromIndex=0&toIndex=1`);
+      const res = await this._request(`${this.datasetPath}/features.json?fromIndex=0&toIndex=1`);
       this._stats.requests++;
       const json = (await res.json()) as { geometryType?: string };
       const isModel = String(json.geometryType ?? '').toUpperCase().includes('MODEL');
@@ -249,7 +272,7 @@ export class AttributeQuery {
 
   private async _post(body: unknown, format: 'fastjson' | 'json'): Promise<string> {
     const t0 = performance.now();
-    const res = await this._fetch(`${this.dataServiceUrl}/featureResults.${format}?returnContent=true`, {
+    const res = await this._request(`${this.dataServiceUrl}/featureResults.${format}?returnContent=true`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(body),

package/src/core/AuthFetch.ts

@@ -0,0 +1,82 @@
+/**
+ * 鉴权适配（Authenticate Hook）
+ *
+ * S3M 服务经常挂在带鉴权的网关后面：有的要求 URL 带 `?token=...`，有的要求
+ * 请求头带 `Authorization` / `X-Token`，还有的 token 会过期需要定期换。内核在
+ * 主线程发出的全部请求（数据集配置 scp、瓦片 .s3mb/.s3mblock、子图集 .texblock、
+ * 棱线缓存、iServer 属性查询）都从这一个钩子过一遍，由使用方统一改写。
+ *
+ * 设计约束（对应 AGENTS.md 不变式①）：不传 `authenticate` 时，请求路径与旧版
+ * 逐字一致——`authFetch` 直接短路到裸 `fetch(url)` / `fetch(url, init)`，连 init
+ * 对象都不新建。
+ *
+ * 注意：鉴权只作用于**发到网络上的请求**，不参与内核的缓存键（瓦片 URL 带 `#N`
+ * 片段与 nodes/pending 等内部 Map 的键都是改写前的原 URL），token 轮换不会导致
+ * 重复加载同一块瓦片。重试时每次重新过钩子，token 刷新后重试天然带上新值。
+ */
+
+/** 请求类别，钩子按类别区分处理（比如属性查询走另一个网关） */
+export type AuthRequestKind = 'config' | 'tile' | 'texblock' | 'creases' | 'attributes';
+
+/** 改写后的请求：实际请求的 URL + 需要附加的请求头 */
+export interface AuthResolvedRequest {
+  /** 实际发到网络上的 URL（可追加 `?token=...` 等鉴权参数） */
+  url: string;
+  /** 需要附加的请求头（如 `Authorization` / `X-Token`） */
+  headers?: Record<string, string>;
+}
+
+/**
+ * 鉴权适配函数。每个请求发出前调用一次：
+ *
+ * - 返回 `string`：只改写 URL（最简形式，如追加 `?token=`）；
+ * - 返回 `{ url, headers }`：改写 URL 并附加请求头；
+ * - 返回 `Promise`：支持异步（如先向认证服务换 token）。
+ *
+ * ```js
+ * new S3MLayer({
+ *   configUrl: 'https://gw.example.com/data/a.scp',
+ *   authenticate: (url, kind) => ({
+ *     url: `${url}${url.includes('?') ? '&' : '?'}token=${getToken()}`,
+ *     headers: { 'X-Client': 's3m' },
+ *   }),
+ * });
+ * ```
+ */
+export type AuthenticateFn = (
+  url: string,
+  kind: AuthRequestKind
+) => string | AuthResolvedRequest | Promise<string | AuthResolvedRequest>;
+
+/** 把钩子返回值归一成 `{ url, headers }`；返回值异常时兜底用原 URL */
+export async function resolveAuthRequest(
+  url: string,
+  auth: AuthenticateFn | undefined,
+  kind: AuthRequestKind
+): Promise<AuthResolvedRequest> {
+  if (!auth) return { url };
+  const out = await auth(url, kind);
+  if (typeof out === 'string') return { url: out || url };
+  if (!out || typeof out !== 'object') return { url };
+  return { url: out.url || url, headers: out.headers };
+}
+
+/**
+ * 带鉴权的 fetch：先过钩子改写 URL / 追加 header，再发请求。
+ * `init.headers`（调用方自带的头）优先级高于钩子返回的 headers。
+ * `auth` 未配置时与裸 `fetch` 完全等价（参数原样透传，不新建 init）。
+ */
+export async function authFetch(
+  url: string,
+  auth: AuthenticateFn | undefined,
+  kind: AuthRequestKind,
+  init?: RequestInit
+): Promise<Response> {
+  if (!auth) return init === undefined ? fetch(url) : fetch(url, init);
+  const resolved = await resolveAuthRequest(url, auth, kind);
+  const hookHeaders = resolved.headers && Object.keys(resolved.headers).length > 0 ? resolved.headers : null;
+  if (!hookHeaders) return init === undefined ? fetch(resolved.url) : fetch(resolved.url, init);
+  // 钩子头在前，init 头在后：调用方显式给的头不被覆盖
+  const headers = { ...hookHeaders, ...init?.headers } as Record<string, string>;
+  return fetch(resolved.url, { ...init, headers });
+}

package/src/core/types.ts

@@ -222,6 +222,14 @@ export interface Stats {
   vertices: number;
   triangles: number;
   datasets: number;
+  /** 上一帧 draw call 数（renderer.info.render.calls，无渲染器时为 0） */
+  drawCalls: number;
+  /** 已编译着色程序数（renderer.info.programs.length） */
+  programs: number;
+  /** 显存里驻留的纹理数（renderer.info.memory.textures） */
+  textures: number;
+  /** 显存里驻留的几何数（renderer.info.memory.geometries） */
+  geometries: number;
 }
 
 /* ------------------------------------------------------------------ 单体属性 */

package/src/index.ts

@@ -21,6 +21,8 @@ export type {
   AttributeField,
   AttributeRow,
 } from './core/AttributeQuery.js';
+export type { AuthRequestKind, AuthResolvedRequest, AuthenticateFn } from './core/AuthFetch.js';
+export { resolveAuthRequest, authFetch } from './core/AuthFetch.js';
 
 // —— 公共类型
 export type {
@@ -65,6 +67,8 @@ export type {
   S3MViewerOptions,
   PickResult,
 } from './render/S3MViewer.js';
+export { HostRenderer } from './render/HostRenderer.js';
+export type { HostRendererOptions, HostFrame } from './render/HostRenderer.js';
 export {
   DEFAULT_STYLE,
   STYLE,

package/src/render/DatasetManager.ts

@@ -9,6 +9,7 @@
  */
 import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
+import type { AuthenticateFn } from '../core/AuthFetch.js';
 import type { Anchor } from '../core/types.js';
 import { worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
 
@@ -43,6 +44,11 @@ export interface S3MDatasetOptions {
    * - true / false：强制开 / 关（例如地形、绿地、道路只显示材质、不描边）
    */
   enableEdges?: boolean;
+  /**
+   * 本数据集专属的鉴权适配函数（不填则用图层级的 `authenticate`）。
+   * 适合多数据集走不同网关 / 不同 token 的场景。见 `AuthenticateFn`。
+   */
+  authenticate?: AuthenticateFn;
 }
 
 export interface S3MDatasetEntry {
@@ -170,7 +176,8 @@ export class DatasetManager {
     maxConcurrent: number,
     callbacks: DatasetManagerCallbacks,
     maxTriangles: number = Infinity,
-    maxImageCache: number = 128
+    maxImageCache: number = 128,
+    authenticate?: AuthenticateFn
   ): Promise<S3MDatasetEntry> {
     const existing = this.datasets.get(ds.id);
     if (existing) return existing;
@@ -205,6 +212,7 @@ export class DatasetManager {
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
       buildTile: buildTile ?? null,
       useWorker: ds.useWorker,
+      authenticate: ds.authenticate ?? authenticate,
       uniforms: uniforms,
       onTile: (node) => {
         callbacks.onTile(node, entry);

package/src/render/HostRenderer.ts

@@ -0,0 +1,222 @@
+/**
+ * 宿主无关渲染底座（HostRenderer）
+ *
+ * 把「宿主协议 ↔ s3m-three 渲染内核」的**宿主无关**部分抽出来，作为所有地图适配层
+ * （MapLibre / Mapbox / 未来的 ArcGIS / Cesium）的共同基类。它只做三件事：
+ *
+ *   1. 持有并构造 `S3MViewer`（渲染内核，宿主无关）；
+ *   2. 提供每帧驱动（把宿主给的 world→clip 矩阵喂给内核，并按需请求下一帧）、
+ *      生命周期（mount / restore / unmount）、投影模式状态与近平面缩放状态；
+ *   3. 把「宿主能力」做成两个抽象钩子 `requestRepaint()` / `getBearing()`，
+ *      由具体适配器实现（maplibre → `triggerRepaint()`，arcgis → `requestRender()`）。
+ *
+ * 凡是依赖具体地图 API 的东西（CustomLayerInterface 形态、从宿主 render 参数里抽矩阵、
+ * 事件绑定、上下文恢复重加图层、经纬度→墨卡托的 WorldCoordinateHelper 提取）都**不在这里**——
+ * 那是各适配层自己的事。这样「绕开墨卡托」也成为可能：非墨卡托宿主（ECEF / 局部米制）只要
+ * 实现 `requestRepaint` 并提供返回自己坐标系的 GeoAdapter，内核就完全不碰墨卡托。
+ *
+ * 设计约束（对应 AGENTS.md 不变式①）：本类不引入任何默认行为变更；maplibre 适配器继承它后，
+ * 默认路径与改动前逐字一致。
+ */
+import { S3MViewer } from './S3MViewer.js';
+import type { S3MViewerOptions, PickResult } from './S3MViewer.js';
+import type { ProjectionMode } from './OrthoProjection.js';
+import type { TransitionOptions } from '../anim/Animator.js';
+import type { Stats } from '../core/types.js';
+import type { S3MDatasetEntry } from './DatasetManager.js';
+
+/** HostRenderer 构造选项：渲染内核选项 + 三个适配器层专属开关 */
+export interface HostRendererOptions extends S3MViewerOptions {
+  /** 图层 / 适配器 id，默认 's3m' */
+  id?: string;
+  /** 投影模式，默认 'perspective'（跟随宿主） */
+  projection?: ProjectionMode;
+  /** 近裁剪面缩放系数（0 < scale < 1，默认 1 = 不改） */
+  nearPlaneScale?: number;
+}
+
+/** 每帧喂给内核的矩阵输入（宿主无关；适配器负责从宿主 render 参数里抽出来） */
+export interface HostFrame {
+  /** world→clip 矩阵（宿主坐标系下） */
+  mvp: ArrayLike<number>;
+  /** 相机在场景 ENU 中的位置（米，相对场景锚点） */
+  cameraEnu: [number, number, number];
+  /** 垂直视场角（弧度），用于 LOD 屏幕误差 */
+  fovRad: number;
+  /** 绘图缓冲高度（像素），LOD 判定用 */
+  canvasHeight: number;
+}
+
+/**
+ * 宿主无关渲染底座。具体地图适配器（如 S3MLayer）继承它，只补宿主专属胶水。
+ */
+export abstract class HostRenderer {
+  readonly id: string;
+  readonly options: HostRendererOptions;
+  readonly pickable: boolean;
+
+  /** 公开回调，可被使用方运行时重新赋值 */
+  onStats: (stats: Stats) => void;
+  onReady: (entry: S3MDatasetEntry) => void;
+  onPick: (result: PickResult | null) => void;
+  onError: (error: unknown) => void;
+
+  /** 渲染内核（宿主无关） */
+  readonly viewer: S3MViewer;
+
+  /** 当前投影模式 */
+  protected _projection: ProjectionMode = 'perspective';
+  /** 正交插值比例（0 = 纯透视，1 = 纯正交）；过渡期间由 animator 平滑推进 */
+  protected _projectionT = 0;
+  /** 正交不可用只告警一次 */
+  protected _orthoWarned = false;
+  /** 近裁剪面缩放系数，1 = 不改（默认） */
+  protected _nearPlaneScale = 1;
+
+  constructor(options: HostRendererOptions = {}) {
+    this.id = options.id ?? 's3m';
+    this.options = options;
+    this.pickable = options.pickable !== false;
+    this._projection = options.projection === 'orthographic' ? 'orthographic' : 'perspective';
+    this._nearPlaneScale = HostRenderer.normalizeNearPlaneScale(options.nearPlaneScale);
+    this._projectionT = this._projection === 'orthographic' ? 1 : 0;
+
+    this.onStats = options.onStats ?? (() => {});
+    this.onReady = options.onReady ?? (() => {});
+    this.onPick = options.onPick ?? (() => {});
+    this.onError = options.onError ?? ((e) => console.warn('[s3m]', e));
+
+    // 把宿主能力做成钩子，内核不碰任何地图 API
+    const { id: _id, projection: _projection, nearPlaneScale: _nearPlaneScale, ...viewerOptions } = options;
+    this.viewer = new S3MViewer({
+      ...viewerOptions,
+      onRequestRepaint: () => this.requestRepaint(),
+      getBearing: () => this.getBearing(),
+      onStats: (s) => this.onStats(s),
+      onReady: (e) => this.onReady(e),
+      onPick: (r) => this.onPick(r),
+      onError: (e) => this.onError(e),
+    });
+  }
+
+  /**
+   * 宿主能力的钩子：请求下一帧重绘。
+   * maplibre → `map.triggerRepaint()`；arcgis → `externalRenderers.requestRender(view)`。
+   */
+  protected abstract requestRepaint(): void;
+
+  /** 宿主方位角（度）；宿主无关默认 0（灯光不跟随视角） */
+  protected getBearing(): number {
+    return 0;
+  }
+
+  /* ----------------------------------------------------------------- 生命周期 */
+
+  /** 挂载渲染内核到宿主的 canvas + 共享 GL 上下文（上下文恢复时原地换新 renderer） */
+  protected mountViewer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    if (this.viewer.renderer) {
+      // 上下文恢复路径：onAdd 被再次触发（map.addLayer），原地换新 renderer，
+      // 保留已加载的场景与瓦片，不重建、不重拉。
+      this.viewer.restoreContext(gl);
+    } else {
+      this.viewer.mount(canvas, gl);
+    }
+  }
+
+  /** 卸载渲染内核（保留已加载的瓦片，下次 mount 可复用） */
+  protected unmountViewer(): void {
+    this.viewer.unmount();
+  }
+
+  /* ----------------------------------------------------------------- 每帧驱动 */
+
+  /**
+   * 把宿主抽好的矩阵喂给内核，并按需请求下一帧。
+   * 返回内核是否需要继续驱动（动态着色 / 瓦片加载中 / LOD 变化）。
+   */
+  protected driveFrame(frame: HostFrame): boolean {
+    const needsNext = this.viewer.renderFrame(frame);
+    if (needsNext) this.requestRepaint();
+    return needsNext;
+  }
+
+  /* ----------------------------------------------------------------- 投影模式 */
+
+  /**
+   * 切换投影模式，可带平滑过渡。
+   * 正交只影响本层：底图瓦片、地形、DOM Marker / 弹窗仍走宿主的透视投影。
+   * 拾取、选中描边、按单体着色/隐藏/抬高不受影响。
+   */
+  setProjection(mode: ProjectionMode, transition?: TransitionOptions): void {
+    const next = mode === 'orthographic' ? 'orthographic' : 'perspective';
+    const targetT = next === 'orthographic' ? 1 : 0;
+    const duration = transition?.duration ?? 0;
+    const wantAnim = duration > 0 || !!transition?.spring;
+
+    this._projection = next;
+    this._orthoWarned = false;
+
+    if (!wantAnim) {
+      if (this.viewer.animator.has('projection.t')) this.viewer.animator.cancel('projection.t');
+      this._projectionT = targetT;
+      this.requestRepaint();
+      return;
+    }
+
+    this._ensureProjectionChannel();
+    this.viewer.animator.to('projection.t', targetT, {
+      ...transition,
+      duration,
+      easing: transition?.easing ?? 'easeInOutCubic',
+      onComplete: () => {
+        this._projectionT = targetT;
+        this.requestRepaint();
+      },
+    });
+    this.requestRepaint();
+  }
+
+  /** 当前投影模式 */
+  get projection(): ProjectionMode {
+    return this._projection;
+  }
+
+  /** 当前正交插值比例（0 = 纯透视，1 = 纯正交） */
+  get projectionT(): number {
+    return this._projectionT;
+  }
+
+  /** 正交插值参数通道：由 animator 平滑推进，写回时请求重绘 */
+  protected _ensureProjectionChannel(): void {
+    if (this.viewer.animator.has('projection.t')) return;
+    this.viewer.animator.register('projection.t', {
+      dim: 1,
+      read: (out) => {
+        out[0] = this._projectionT;
+      },
+      write: (v) => {
+        this._projectionT = v[0];
+        this.requestRepaint();
+      },
+    });
+  }
+
+  /* ----------------------------------------------------------------- 近平面缩放 */
+
+  /** 动态调整近裁剪面缩放（0 < scale < 1）。传 1 / 0 / 非法值 = 恢复宿主原始 near */
+  setNearPlaneScale(scale: number): void {
+    this._nearPlaneScale = HostRenderer.normalizeNearPlaneScale(scale);
+    this.requestRepaint();
+  }
+
+  /** 当前近裁剪面缩放系数（1 = 不改，用宿主的默认值） */
+  get nearPlaneScale(): number {
+    return this._nearPlaneScale;
+  }
+
+  /** 近裁剪缩放系数的合法化：非数字 / <=0 / >=1 一律视为「不改」 */
+  static normalizeNearPlaneScale(v: number | undefined): number {
+    if (typeof v !== 'number' || !Number.isFinite(v)) return 1;
+    return v > 0 && v < 1 ? v : 1;
+  }
+}