three-base 2.0.137 → 2.0.145

package/SpriteText3.ts

@@ -0,0 +1,599 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2026-09-02（从旧 9-slice + Canvas 画箭头 重构为 11-slice 源图切片）
+ * @Description: 带源图气泡背景的精灵文字组件。
+ *
+ * ============================================================================
+ * 【11-slice 气泡背景切片方案】(2026-09-02 用户硬性要求，硬性写进注释防遗忘)
+ * ============================================================================
+ *
+ * 原始需求（防止改着改着就忘记原始需求）：
+ *   把气泡背景源图 spriteTextBg.png 切分成 11 个部分，绘制到 canvas：
+ *     [1]  左上角      — 不可变形（保持原始宽高比，等比缩放）
+ *     [2]  上边        — 横向拉伸
+ *     [3]  右上角      — 不可变形
+ *     [4]  左边        — 纵向拉伸
+ *     [5]  中间        — 双向拉伸
+ *     [6]  右边        — 纵向拉伸
+ *     [7]  左下角      — 不可变形
+ *     [8]  左中连接边   — 横向拉伸
+ *     [9]  下中尖角    — 不可变形（含气泡底边 + 箭头）
+ *     [10] 中右连接边  — 横向拉伸
+ *     [11] 右下角      — 不可变形
+ *
+ *   不可变形块 = 5 个：左上、右上、左下、下中尖角、右下。
+ *   拉伸块     = 6 个：上边、左边、中间、右边、左中连接边、中右连接边。
+ *
+ * 源图坐标（2026-09-06 皇上指定：原始设计稿 922×400；硬编码常量，如换源图必须同步改）：
+ *   - 切片范围 = 整图（含外辉光）：alpha>0 区域 x[0,922) y[0,392)
+ *   - 不透明本体（深蓝圆角矩形 + 蓝霓虹描边，alpha==255）：x[42,880] y[44,344]（描边底 y=345）
+ *   - 圆角半径 38；边框带 SRC_CORNER = 辉光 42 + 圆角 38 = 82（角块必须含完整辉光外角 + 圆角）
+ *   - 底部箭头：青色倒三角，顶边 y=346 宽 49（x 447..495），尖点 (471, 386)，高 41
+ *   - 外辉光：蓝色 (64,86,255)、alpha 1~62，分布在本体四周 → 由 11-slice 边框带承载（拉伸）
+ *   - ⚠️ 演变史：最初误用 [5,918]×[7,382]（alpha>0 外沿）切片→辉光错位混入→发灰+透明度二次合成；
+ *     随后改 alpha==255 本体切片修掉发灰，但把辉光全裁掉了（皇上：「图片没有用完，
+ *     裁掉了很大一部分边缘的图片纹理」）；最终方案 = 整图切片 + 边框带 82（9-patch 标准）。
+ *
+ * 11-slice 网格（以源图坐标定义）：
+ *
+ *   列（x 方向，5 列）：
+ *     C0 左角列      [SRC_BODY_LEFT,             SRC_BODY_LEFT  + SRC_CORNER)              宽 c
+ *     C1 左连接列    [SRC_BODY_LEFT + SRC_CORNER, 画布水平中心对应的源列)                       (横向拉伸源段)
+ *     C2 尖角列      [TIP_SRC_X,                  TIP_SRC_X + TIP_SRC_W)                    宽 TIP_SRC_W=60          (固定列，以箭头为中心)
+ *     C3 右连接列    [画布水平中心对应的源列,       SRC_BODY_RIGHT - SRC_CORNER)              (横向拉伸源段)
+ *     C4 右角列      [SRC_BODY_RIGHT - SRC_CORNER, SRC_BODY_RIGHT)                          宽 c
+ *
+ *   行（y 方向，4 行）：
+ *     R0 上角行      [SRC_BODY_TOP,             SRC_BODY_TOP    + SRC_CORNER)             高 c
+ *     R1 中间行      [SRC_BODY_TOP + SRC_CORNER, SRC_BODY_BOTTOM - SRC_CORNER)             高 (双向拉伸)
+ *     R2 下角行      [SRC_BODY_BOTTOM - SRC_CORNER, SRC_BODY_BOTTOM)                        高 c   ← 含气泡底边
+ *     R3 箭头行      [SOLID_BOTTOM,              SOLID_BOTTOM + ARROW_SRC_H)               高 ARROW_SRC_H = 41  ← 源图箭头凸出（被辉光尾包住）
+ *
+ *   部件 → 网格映射（绘制顺序即下述顺序，尖角块最后叠加）：
+ *     [1]  左上角       = (R0, C0)        不可变形，cornerSize × cornerSize
+ *     [2]  上边         = (R0, C1+C2+C3)  横向拉伸（高 cornerSize）
+ *     [3]  右上角       = (R0, C4)        不可变形
+ *     [4]  左边         = (R1, C0)        纵向拉伸（宽 cornerSize）
+ *     [5]  中间         = (R1, C1+C2+C3)  双向拉伸
+ *     [6]  右边         = (R1, C4)        纵向拉伸
+ *     [7]  左下角       = (R2, C0)        不可变形
+ *     [8]  左中连接边   = (R2, C1+C2+C3 左半)  横向拉伸，从左下角右缘画到 canvas 水平中心
+ *     [10] 中右连接边   = (R2, C1+C2+C3 右半)  横向拉伸，从 canvas 水平中心画到右下角左缘
+ *     [11] 右下角       = (R2, C4)        不可变形
+ *     [9]  下中尖角     = (R2 下沿粘合段 + R3, C2)  不可变形，等比缩放，最后叠加在底边带中央之上
+ *
+ * 关键设计点：
+ *   1) 尖角块源区域 = C2 列，且【纵向只取箭头本身】，不取任何底边描边行：
+ *        y ∈ [SOLID_BOTTOM + 1, SOLID_BOTTOM + 1 + TIP_SRC_H) = [346, 389)
+ *        高度 = TIP_SRC_H = ARROW_SRC_H(41) + ARROW_TIP_FADE(2) = 43 源像素。
+ *        ⚠️ 起点必须是描边底 SOLID_BOTTOM(345) 的【下一行】346：cell 若向上多含 345 一行，
+ *        就会用箭头的亮边把下边框描边的【最后一行】覆盖 → 皇上反馈的
+ *        「箭头和下边框有 1px 的重叠」（2026-09-14 真实 Chrome 逐行实测确认）。
+ *        ⚠️ 不能把 R2 行整个包进尖角块：尖角块整体等比缩放（不可变形），
+ *        若向上多包描边行，放大后尖角块会跑出 canvas 被裁剪 → 底边带中间留洞（2026-09-02 踩坑）。
+ *   2) 尖角块在画布上等比缩放（不变形），缩放比由 arrowTargetH 决定：
+ *        tipScale = arrowTargetH / ARROW_SRC_H（默认 41/41 = 1:1 最锐利）
+ *      尖角块画布尺寸 = (TIP_SRC_W * tipScale) × (TIP_SRC_H * tipScale)。
+ *      arrowTargetH ≤ 41（ARROW_SRC_H）时均为缩小/1:1，不会糊；调大超过 41 才开始放大。
+ *   3) 尖角块定位：
+ *        solidBottomDst = bodyHc - cornerSize*(GLOW_TAIL/SRC_CORNER)   // 描边底在画布上的 y
+ *        dstX = bodyWc/2 - tipDstW/2 + arrowOffsetX                    // 以箭头为中心水平居中 + 视觉微调
+ *        dstY = solidBottomDst + 1                                     // 箭头紧贴描边底的下一行（不与描边重叠）
+ *      canvasH = max(bodyHc, 箭头尖 y)：默认箭头尖埋在底部辉光带内（与原图一致），
+ *      arrowTargetH 调大超出辉光带时画布自动加高。
+ *   4) 左中连接边[8] / 中右连接边[10] 【横跨整个底边带】（到 canvas 水平中心为止），
+ *      尖角块[9]【最后 clearRect + source-over 绘制】在底边带中央之上：cell 与连接边同源、同 1:1 比例，
+ *      故两侧视觉连续。⚠️ 用 clearRect（"替换"）而非叠加 → 不存在透明度二次合成，也不需要粘合段；
+ *      箭头两侧源像素即底边辉光，与连接边同色 → 底边带完整无缝，中间不会留洞。
+ *   5) canvas 总高 = max(bodyHc, 箭头尖 y)（bodyHc 之上是气泡主体，之下是箭头 + 辉光尾）。
+ *   6) 文字居中于 bodyHc/2（气泡主体几何中心，不在 canvas 中心，因为下方有箭头凸出）。
+ *   7) 源图箭头中心 x=471 相对气泡中心 461 偏右约 10px；尖角块以【箭头】为中心取块，
+ *      画布上块居中 → 箭头相对气泡居中（偏置被自然消除），如需偏移用 arrowOffsetX 微调。
+ *   8) 颜色空间（2026-09-06 修）：canvas 纹理必须 texture.colorSpace = SRGBColorSpace（采样时
+ *      硬件解码 sRGB→linear），片元着色器输出前 #include <colorspace_fragment>（按渲染目标
+ *      自动编码）。缺任一环 → 主场景后处理链二次编码 → 整体发白偏亮。
+ *
+ * 旧实现对照（已废弃，2026-09-02 之前）：
+ *   - 用 Canvas2D 单独绘制等腰三角作为箭头（避开源图箭头非对称问题）
+ *   - 新方案按用户要求改为"源图箭头作为尖角块不可变形"，源图非对称特征自然保留为视觉特色
+ *   - 旧 bubbleAlpha / bgColor / borderFrac / borderTopScale+BottomScale+LeftScale+RightScale
+ *     4 个 scale 属性一并移除（源图自带颜色不可调，圆角半径单一控制更简洁）
+ *
+ * 边界处理 / 已知细节：
+ *   - 源图箭头尖在 (471, 386)；尖角块以箭头为中心取块，画布上自动相对气泡居中
+ *   - 拉伸源段（[2][4][5][6][8][10]）取【从一角块边界到另一角块边界的完整连续区段】
+ *     （9-patch 标准做法）：使相邻块在拼接处的源像素相邻/镜像对称 → 无接缝。
+ *     ⚠️ 2026-09-14 修正（皇上：「左上角圆角很正常，但其他 3 个圆角的拼接不对；三角形区域
+ *     左右 2 边的像素点都没拼接上，可以看到明显的接缝」）：
+ *       原实现误把拉伸源段当成「左上角内侧固定 82px 的小段」来拉伸，导致除左上角外的每条
+ *       拼接边两侧源像素相隔上百像素——中间行底端源 y163 ↔ 底边带顶源 y310（跨 147px），
+ *       上边带右端源 x163 ↔ 右上角块源 x840；而源图本体底部 y≈300 起有明显内发光
+ *       ((9,27,58) → (12,32,74) → y330 (23,51,114))，于是画布 y=bodyHc-cornerSize 处出现横向
+ *       台阶（左下/右下角接缝）、x=bodyWc-cornerSize 处出现纵向台阶（右上角接缝）、底边带中心
+ *       源 x163↔x758 与尖角块源 x441/501 不连续（箭头两侧接缝）。
+ *       改为整段取源后，所有相邻边界源像素连续（y309↔y310、x839↔x840、x440↔x441、x500↔x501）。
+ *   - 辉光带在边框带内被拉伸（辉光是垂直于边缘的渐变、沿边缘方向均匀 → 拉伸不失真）
+ *   - 文字居中于 bodyHc/2 ≈ 不透明本体中心（辉光带上下近似对称，偏差 <2% 可忽略）
+ *   - 尖角块粘合段取自不透明底边描边 → 与连接边叠加处双方 alpha=255，无透明度二次合成
+ *   - canvas resize 时浏览器会清空画布，每次 _genText 都从 clearRect 0,0,canvasW,canvasH 开始
+ *
+ * 后续修改警告（再改此文件前必读本注释）：
+ *   - 改源图 spriteTextBg.png 尺寸/箭头位置/圆角半径 → 同步更新 SRC_* 常量
+ *   - 改 11 个部件的命名或数量 → 先确认用户是否同意（用户明确说"防止改着改着就忘记原始需求"）
+ *   - 尖角块若改成"可拉伸"（如 9-slice 底边中段一样）→ 需重新讨论，原始需求是"不可变形"
+ * ============================================================================
+ */
+import {
+    DoubleSide,
+    LinearFilter,
+    SRGBColorSpace,
+    Mesh,
+    PlaneGeometry,
+    ShaderMaterial,
+    Texture,
+} from "three";
+import { defaultBg } from "./spriteTextBg";
+import type { ColorString } from "./types";
+
+/** 顶点着色器：Mesh billboard，plane 永远正对相机，尺寸由 mesh.scale 驱动 */
+const VERTEX_SHADER = /* glsl */ `
+#include <common>
+#include <logdepthbuf_pars_vertex>
+varying vec2 vUv;
+void main() {
+    vUv = uv;
+    vec2 scale = vec2(length(modelMatrix[0].xyz), length(modelMatrix[1].xyz));
+    vec4 mvPosition = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+    mvPosition.xy += position.xy * scale;
+    gl_Position = projectionMatrix * mvPosition;
+    #include <logdepthbuf_vertex>
+}
+`;
+
+/** 片元着色器：直接输出 canvas 纹理（气泡 + 文字已合好） */
+const FRAGMENT_SHADER = /* glsl */ `
+#include <common>
+#include <logdepthbuf_pars_fragment>
+uniform sampler2D uTextTexture;
+varying vec2 vUv;
+void main() {
+    gl_FragColor = texture2D(uTextTexture, vUv);
+    // 纹理标记 SRGBColorSpace（采样时硬件解码 sRGB→linear），
+    // 此处按渲染目标自动编码输出：主场景线性 RT 下 passthrough，直接出屏时编码 sRGB。
+    // ⚠️ 不加会导致主场景后处理链终处理二次编码 → 整体发白偏亮（2026-09-06 修）。
+    #include <colorspace_fragment>
+    #include <logdepthbuf_fragment>
+}
+`;
+
+/** 1x1 透明占位纹理，纹理生成完成前使用 */
+function createPlaceholderTexture(): Texture {
+    const canvas = document.createElement("canvas");
+    canvas.width = 1;
+    canvas.height = 1;
+    const texture = new Texture(canvas);
+    texture.colorSpace = SRGBColorSpace;
+    texture.needsUpdate = true;
+    return texture;
+}
+
+/**
+ * 源图硬编码常量（详见文件头注释）。
+ *
+ * ⚠️ 2026-09-06 皇上旨：源图 = 原始设计稿 spriteTextBg.png（922×400），"不要动图片了"
+ *   —— 图片禁止任何加工（不缩放/不重绘/不调色），只调切片常量。
+ * ⚠️ 2026-09-06 二次反馈「图片没有用完，裁掉了很大一部分边缘」：
+ *   曾按 alpha==255 本体（x[42,880] y[44,345]）切片，把外圈辉光全裁掉了。
+ *   现改为 9-patch 标准做法：**整图（含辉光）纳入切片**，边框带 = 辉光 + 圆角 + 描边。
+ *   本常量为原图实测值（PIL 逐像素量测）：
+ *     alpha>0 区域 x[0,922) y[0,392)；圆角 38（圆心 80,82）；描边底（不透明本体底）y=345；
+ *     辉光尾 345..392；箭头顶边 y=346 宽 49（x 447..495）、尖点 (471,386)。
+ *   如换源图必须同步改本常量。
+ */
+const SRC_W = 922;
+const SRC_H = 400;
+/** 切片范围 = 整图（含外辉光）：alpha>0 区域 x[0,922) y[0,392)（exclusive 右/下沿） */
+const SRC_BODY_LEFT = 0;
+const SRC_BODY_RIGHT = 922;
+const SRC_BODY_TOP = 0;
+const SRC_BODY_BOTTOM = 392;
+/**
+ * 边框带厚度（4 角方块的源边长）= 外辉光 42 + 圆角 38 = 82。
+ * 角块必须包含完整辉光外角 + 完整圆角，二者缺一会被拉伸变形（9-patch 标准）。
+ */
+const SRC_CORNER = 82;
+/** 不透明本体（描边）底 y=345；描边底到辉光底的"辉光尾"高 47（底边带内源像素） */
+const SOLID_BOTTOM = 345;
+const GLOW_TAIL = SRC_BODY_BOTTOM - SOLID_BOTTOM;
+/** 底部箭头源像素尺寸（顶边宽 49 的青色倒三角，顶边 y=346 贴气泡底边、尖点 (471,386)） */
+const ARROW_SRC_W = 49;
+const ARROW_SRC_H = 41;
+/** 箭头源中心 x（源图特征：相对气泡中心 461 偏右约 10px；尖角块以箭头为中心取块，画布上自动居中） */
+const ARROW_SRC_CX = 471;
+/** 尖角块源宽度（以箭头为中心，向两侧各取 30 像素 = 60 像素宽，覆盖箭头顶边 49 + 余量） */
+const TIP_SRC_W = 60;
+/** 尖角块源 x 起点 = 471 - 30 = 441 */
+const TIP_SRC_X = ARROW_SRC_CX - TIP_SRC_W / 2;
+/**
+ * 尖角块源 y 起点 = 描边底 SOLID_BOTTOM(345) 的【下一行】346（箭头顶边）。
+ * ⚠️ 必须从 346 起取，不可向上多含 345 一行：345 是下边框描边的【最后一行】，
+ *    cell 若含它，就用箭头的亮边把该行覆盖 → 皇上反馈的「箭头和下边框有 1px 的重叠」
+ *    （2026-09-14 真实 Chrome 逐行实测：该行在无箭头时全宽 (47,118,215)，
+ *      含箭头后被覆盖为 (72,186,248)）。
+ * 说明：本块用 clearRect + source-over 绘制（"替换"而非"叠加"），不会发生透明度二次合成，
+ *      故不需要"粘合段"；旧的 TIP_SRC_OVERLAP=4 及其粘合段已删除（2026-09-14）。
+ */
+const TIP_SRC_Y = SOLID_BOTTOM + 1;
+/**
+ * 箭头源区额外多取的"尖点渐隐"行数：源 y387(α188) / y388(α21) 仍是箭头色
+ * （y389 起才是底色辉光 (64,86,255,α≤3)），属尖点抗锯齿。少取则尖点末尾出现 1px 硬切。
+ */
+const ARROW_TIP_FADE = 2;
+/** 尖角块源高度 = 41（箭头主体 346..386） + 2（尖点渐隐 387..388） = 43 */
+const TIP_SRC_H = ARROW_SRC_H + ARROW_TIP_FADE;
+
+/**
+ * 箭头（2026-09-14 皇上旨"箭头看不清楚了"，前一轮"接缝"已由 11-slice 连续取源修好）：
+ * 源图箭头 cell（TIP_SRC_X=441…）左右边界 x441/500 与左右带子 [8]/[10] 逐行 RGBA 完全一致(均带子蓝)，
+ * 且 cell 是整块青蓝渐变：边缘=带子蓝低透明(α≈32~43)、箭身/尖点=亮青(≈47,168,225)高透明(α≈248)。
+ * [9] 用 **「先 clearRect 局部清空 + source-over 画原始 cell」**（等价"局部 copy"）：
+ *   · 清空：先清掉 [9] 矩形内的带子 → 箭头边距不会与带子 α 相加 → 无缝；
+ *   · 绘制：source-over 画原始 cell，箭身=亮青 α≈248 → 清晰可见。
+ * ⚠️ 三个已验证的坑（2026-09-14 各踩一次，真实 Chrome 无头实测）：
+ *   · source-over：边距 α 与带子 α 相加(32+33≈60) → 又现台阶(皇上反馈的"接缝")；
+ *   · source-atop：箭头 α 被压到带子的≈43 → 整块与带子同透明 → 箭头糊没(皇上反馈"看不清楚")；
+ *   · **copy：canvas 的 copy 是"清空整个画布、只保留本次绘制"**（不是只替换目标矩形！）→
+ *     前面 11-slice 画的边框全被清掉、只剩箭头(皇上反馈"其他边框全没了"；实测整块只剩 2700 像素)。
+ */
+
+export default class SpriteText3 extends Mesh {
+    constructor(
+        text: string = "",
+        textHeight: number = 10,
+        color: ColorString = "#ffffff",
+    ) {
+        const shader = new ShaderMaterial({
+            transparent: true,
+            depthWrite: false,
+            side: DoubleSide,
+            uniforms: {
+                uTextTexture: { value: createPlaceholderTexture() },
+            },
+            vertexShader: VERTEX_SHADER,
+            fragmentShader: FRAGMENT_SHADER,
+        });
+        // 几何底部落在模型原点，箭头尖即 billboard 锚点
+        super(new PlaneGeometry(1, 1).translate(0, 0.5, 0), shader);
+
+        this._shader = shader;
+        this._text = `${text}`;
+        this._textHeight = textHeight;
+        this._color = color;
+
+        this._loadBg();
+        this._genText();
+    }
+
+    /** 自定义着色器材质（类型收窄用） */
+    private _shader: ShaderMaterial;
+    /** 气泡+文字纹理（_genText 重建） */
+    private _textTexture: Texture | null = null;
+    /** 绘制用离屏 canvas */
+    private _textCanvas: HTMLCanvasElement = document.createElement("canvas");
+    /** 气泡背景图源图（加载完成后在 canvas 上做 11-slice） */
+    private _bgImage: HTMLImageElement | null = null;
+    // 箭头直接用源图原始 cell 绘制（见下方 [9] 段），无需离屏预生成。
+
+    // ========== 用户可调属性 ==========
+    _text: string = "";
+    _textHeight: number = 10;
+    _color: ColorString = "#ffffff";
+    _fontFace: string = "Arial";
+    _fontSize: number = 90;
+    _fontWeight: string = "normal";
+    _padding: number = 8;
+    /**
+     * 边框带边长（画布像素，4 角 + R0/R2 行高 + C0/C4 列宽 共享）
+     * 源边框带 = 外辉光 42 + 圆角 38 = 82；默认 82 = 1:1 复刻原图（辉光完整保留）
+     */
+    _cornerSize: number = 82;
+    /**
+     * 箭头目标凸出高度（画布像素，尖角块[9]的箭头段在画布上的最终高度）
+     * 源图箭头 ARROW_SRC_H=41 像素，此属性控制缩放后的视觉大小（不可变形等比缩放）
+     * 默认 41 = 1:1 最锐利（原图箭头比例）；调大超过 41 才开始放大变糊
+     */
+    _arrowTargetH: number = 41;
+    /**
+     * 箭头水平视觉微调偏移（像素，相对 canvas 中心；负值左移、正值右移）
+     * 源图箭头中心 x=471 相对气泡中心 461 偏右约 10px；尖角块以【箭头】为中心取块，
+     * 画布上块居中 → 该偏置被自然消除，默认 0；此属性供按视觉需求再做微调
+     */
+    _arrowOffsetX: number = 0;
+    /** 是否显示 11-slice 分割线（默认开启） */
+    _showGrid: boolean = false;
+    /** 是否显示调试描边（默认关闭，画整个 canvas 红色边框） */
+    _showOutline: boolean = false;
+
+    get text(): string { return this._text; }
+    set text(value: string) { this._text = value; this._genText(); }
+
+    get textHeight(): number { return this._textHeight; }
+    set textHeight(value: number) { this._textHeight = value; this._genText(); }
+
+    get color(): ColorString { return this._color; }
+    set color(value: ColorString) { this._color = value; this._genText(); }
+
+    get fontFace(): string { return this._fontFace; }
+    set fontFace(value: string) { this._fontFace = value; this._genText(); }
+
+    get fontSize(): number { return this._fontSize; }
+    set fontSize(value: number) { this._fontSize = value; this._genText(); }
+
+    get fontWeight(): string { return this._fontWeight; }
+    set fontWeight(value: string) { this._fontWeight = value; this._genText(); }
+
+    get padding(): number { return this._padding; }
+    set padding(value: number) { this._padding = value; this._genText(); }
+
+    get cornerSize(): number { return this._cornerSize; }
+    set cornerSize(value: number) { this._cornerSize = Math.max(0, value); this._genText(); }
+
+    get arrowTargetH(): number { return this._arrowTargetH; }
+    set arrowTargetH(value: number) { this._arrowTargetH = Math.max(0, value); this._genText(); }
+
+    get arrowOffsetX(): number { return this._arrowOffsetX; }
+    set arrowOffsetX(value: number) { this._arrowOffsetX = value; this._genText(); }
+
+    get showOutline(): boolean { return this._showOutline; }
+    set showOutline(value: boolean) { this._showOutline = value; this._genText(); }
+
+    get showGrid(): boolean { return this._showGrid; }
+    set showGrid(value: boolean) { this._showGrid = value; this._genText(); }
+
+    /** 异步载入背景图源图（base64 data URL），加载完成后触发 11-slice 重绘 */
+    private _loadBg(): void {
+        const img = new Image();
+        img.onload = () => {
+            this._bgImage = img;
+            this._genText();
+        };
+        img.src = defaultBg;
+    }
+
+    /**
+     * 重新生成 canvas 纹理并同步 sprite 世界尺寸。
+     * 主体流程：计算文字/气泡尺寸 → 计算 11 切片的目标位置/大小 → 依次 drawImage 11 个部件
+     *         → 画 showGrid 分割线 → 画 showOutline 边框 → 画文字 → 更新 Texture。
+     */
+    private _genText(): void {
+        const lines = this._text.split("\n");
+        const ctx = this._textCanvas.getContext("2d");
+        if (!ctx) return;
+
+        const font = `${this._fontWeight} ${this._fontSize}px ${this._fontFace}`;
+        ctx.font = font;
+
+        // 逐行度量真实墨迹尺寸
+        const metrics = lines.map((line) => {
+            const m = ctx.measureText(line);
+            const ascent = m.actualBoundingBoxAscent ?? this._fontSize * 0.8;
+            const descent = m.actualBoundingBoxDescent ?? this._fontSize * 0.2;
+            return { width: m.width, ascent, descent };
+        });
+        const textWpx = Math.max(...metrics.map((m) => m.width), 1);
+        const lineH = this._fontSize;
+        const blockHpx =
+            lines.length <= 1
+                ? metrics[0].ascent + metrics[0].descent
+                : metrics[0].ascent + metrics[metrics.length - 1].descent + (lines.length - 1) * lineH;
+        // 文本高度下限：单行不低于字号高度，多行不低于「行数×字号」，
+        // 避免扁字形（如"一"）真实墨迹高度过小、把气泡压扁而包不住文字。
+        const textHpx = Math.max(blockHpx, this._fontSize * lines.length, 1);
+
+        // 世界/像素换算
+        const pxToWorld = this._textHeight / this._fontSize;
+        const padX = this._padding;
+        const padY = this._padding;
+        // 文字区在画布上的尺寸（像素，不含 4 角 + 上下/左右连接带）
+        const textAreaW = textWpx + 2 * padX;
+        const textAreaH = textHpx + 2 * padY;
+
+        // 气泡主体尺寸：文字区 + 上下/左右各 cornerSize 像素的边框
+        const cornerSize = this._cornerSize;
+        const bodyWc = Math.max(Math.round(textAreaW) + 2 * cornerSize, 2 * cornerSize + 2);
+        const bodyHc = Math.max(Math.round(textAreaH) + 2 * cornerSize, 2 * cornerSize + 2);
+
+        // 尖角块参数（[9] 下中尖角）
+        // 尖角块在画布上等比缩放（不可变形），缩放比由 arrowTargetH 决定
+        const tipScale = this._arrowTargetH / ARROW_SRC_H;
+        const tipDstW = TIP_SRC_W * tipScale;
+        const tipDstH = TIP_SRC_H * tipScale;
+        // 尖角块位置：以箭头为中心水平居中 + 视觉微调
+        const tipDstX = bodyWc / 2 - tipDstW / 2 + this._arrowOffsetX;
+        // 不透明本体（描边）底在画布上的 y：底边带（含辉光尾）内，辉光尾占 GLOW_TAIL/SRC_CORNER 比例
+        const solidBottomDst = bodyHc - cornerSize * (GLOW_TAIL / SRC_CORNER);
+        // 尖角块顶 = 描边底的【下一行】（箭头紧贴下边框下方，绝不与下边框重叠哪怕 1px）
+        const tipDstY = solidBottomDst + 1;
+        const arrowTipDst = tipDstY + tipDstH;
+        // 画布总高：默认箭头尖埋在底部辉光带内（与原图一致）；arrowTargetH 调大超出辉光带时加高
+        const canvasW = bodyWc;
+        const canvasH = Math.max(bodyHc, Math.ceil(arrowTipDst));
+
+        this._textCanvas.width = canvasW;
+        this._textCanvas.height = canvasH;
+
+        // resize 会清空画布，重设状态
+        ctx.font = font;
+        ctx.clearRect(0, 0, canvasW, canvasH);
+
+        // ===== 11-slice 背景绘制（顺序：底边带 → 中间行 → 上边带 → 顶角 → 尖角叠加）=====
+        if (this._bgImage && this._bgImage.naturalWidth > 0) {
+            const img = this._bgImage;
+            // 箭头 [9] 直接用原始源图 cell 绘制（见下方 [9] 段），不再预生成离屏 canvas、不再染同色。
+            // 拉伸块的源区段（标准 9-patch：一律取「从一角块边界到另一角块边界」的完整连续区段，
+            // 使相邻块在拼接处的源像素相邻/对称 → 无接缝）。
+            // ⚠️ 2026-09-14 修（皇上反馈「左上圆角正常、其他 3 个圆角拼接不对 + 箭头两侧可见接缝」）：
+            //    原实现所有拉伸块都只取源图【左上角内侧】固定 82px 的一小段来拉伸，导致除「左上角」外的
+            //    各拼接边两侧源像素不相邻：中间行底端源 y163 紧邻底边带顶源 y310（跨 147px，而源图本体
+            //    底部 y≈300 起有明显内发光变亮 (9,27,58)→(12,32,74)）→ 画布 y=bodyHc-cornerSize 处
+            //    横向台阶；上边带右端源 x163 紧邻右上角块源 x840 → 画布 x=bodyWc-cornerSize 处纵向台阶；
+            //    底边带中心源 x163↔x758 与尖角块源 x441/501 亦不连续 → 箭头两侧接缝。
+            //    改为整段取源后，所有相邻边界源像素连续（y309↔y310、x839↔x840、x440↔x441、x500↔x501）。
+            const srcMidW = SRC_BODY_RIGHT - SRC_BODY_LEFT - 2 * SRC_CORNER;   // 上/中带源宽 = 922-164 = 758
+            const srcMidH = SRC_BODY_BOTTOM - SRC_BODY_TOP - 2 * SRC_CORNER;   // 左/中/右带源高 = 392-164 = 228
+            const srcBottomLeftW = TIP_SRC_X - (SRC_BODY_LEFT + SRC_CORNER);   // 左中连接边源宽 = 441-82 = 359
+            const srcBottomRightW =
+                SRC_BODY_RIGHT - SRC_CORNER - (TIP_SRC_X + TIP_SRC_W);         // 中右连接边源宽 = 840-501 = 339
+
+            const draw = (
+                sx: number, sy: number, sw: number, sh: number,
+                dx: number, dy: number, dw: number, dh: number,
+            ): void => {
+                if (sw <= 0 || sh <= 0 || dw <= 0 || dh <= 0) return;
+                ctx.drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh);
+            };
+
+            // ----- 底边带（R2 行：Y = bodyHc - cornerSize ~ bodyHc）-----
+            // ⚠️ 两条连接边【横跨整个底边带】（画到 canvas 水平中心），尖角块[9]最后叠加在中央之上，
+            //    底边带中间不留空隙（2026-09-02 踩坑：若连接边止步尖角块边缘，尖角块一旦异常
+            //    中间就会露出透明洞）。
+            //    ⚠️ 但取样源端点必须【对齐尖角块左右缘】（441 / 501）：这样连接边在箭头两侧与尖角块
+            //    的源像素连续（箭头两侧底边辉光镜像对称，x441=x501），消除「箭头两侧接缝」。
+            // [7] 左下角：源 (SRC_BODY_LEFT, SRC_BODY_BOTTOM - SRC_CORNER, SRC_CORNER, SRC_CORNER)
+            draw(
+                SRC_BODY_LEFT, SRC_BODY_BOTTOM - SRC_CORNER, SRC_CORNER, SRC_CORNER,
+                0, bodyHc - cornerSize, cornerSize, cornerSize,
+            );
+            // [8] 左中连接边：源 x[82, 441)（右端紧贴尖角块左缘）→ 目标 (cornerSize ~ canvas 水平中心)
+            draw(
+                SRC_BODY_LEFT + SRC_CORNER, SRC_BODY_BOTTOM - SRC_CORNER, srcBottomLeftW, SRC_CORNER,
+                cornerSize, bodyHc - cornerSize, bodyWc / 2 - cornerSize, cornerSize,
+            );
+            // [10] 中右连接边：源 x[501, 840)（左端紧贴尖角块右缘）→ 目标 (canvas 水平中心 ~ bodyWc-cornerSize)
+            draw(
+                TIP_SRC_X + TIP_SRC_W, SRC_BODY_BOTTOM - SRC_CORNER, srcBottomRightW, SRC_CORNER,
+                bodyWc / 2, bodyHc - cornerSize, bodyWc / 2 - cornerSize, cornerSize,
+            );
+            // [11] 右下角：源 (SRC_BODY_RIGHT - SRC_CORNER, SRC_BODY_BOTTOM - SRC_CORNER, ...)
+            draw(
+                SRC_BODY_RIGHT - SRC_CORNER, SRC_BODY_BOTTOM - SRC_CORNER, SRC_CORNER, SRC_CORNER,
+                bodyWc - cornerSize, bodyHc - cornerSize, cornerSize, cornerSize,
+            );
+
+            // ----- 中间行（R1 行：Y = cornerSize ~ bodyHc - cornerSize）-----
+            // 源一律取 y[82, 310)（整段中间高）：底端 y309 与底边带顶端 y310 连续 → 无横向台阶。
+            // [4] 左边：纵向拉伸
+            draw(
+                SRC_BODY_LEFT, SRC_BODY_TOP + SRC_CORNER, SRC_CORNER, srcMidH,
+                0, cornerSize, cornerSize, bodyHc - 2 * cornerSize,
+            );
+            // [5] 中间：双向拉伸
+            draw(
+                SRC_BODY_LEFT + SRC_CORNER, SRC_BODY_TOP + SRC_CORNER, srcMidW, srcMidH,
+                cornerSize, cornerSize, bodyWc - 2 * cornerSize, bodyHc - 2 * cornerSize,
+            );
+            // [6] 右边：纵向拉伸
+            draw(
+                SRC_BODY_RIGHT - SRC_CORNER, SRC_BODY_TOP + SRC_CORNER, SRC_CORNER, srcMidH,
+                bodyWc - cornerSize, cornerSize, cornerSize, bodyHc - 2 * cornerSize,
+            );
+
+            // ----- 顶边带（R0 行：Y = 0 ~ cornerSize）-----
+            // [1] 左上角
+            draw(
+                SRC_BODY_LEFT, SRC_BODY_TOP, SRC_CORNER, SRC_CORNER,
+                0, 0, cornerSize, cornerSize,
+            );
+            // [2] 上边：横向拉伸，源取 x[82, 840)（整段中间宽）：右端 x839 与右上角块 x840 连续 → 无纵向台阶
+            draw(
+                SRC_BODY_LEFT + SRC_CORNER, SRC_BODY_TOP, srcMidW, SRC_CORNER,
+                cornerSize, 0, bodyWc - 2 * cornerSize, cornerSize,
+            );
+            // [3] 右上角
+            draw(
+                SRC_BODY_RIGHT - SRC_CORNER, SRC_BODY_TOP, SRC_CORNER, SRC_CORNER,
+                bodyWc - cornerSize, 0, cornerSize, cornerSize,
+            );
+
+            // ----- 尖角块 [9]（最后画，叠加在底边带中央）-----
+            // 方案 = 「先 clearRect 局部清空 + source-over 画原始 cell」（等价"局部 copy"），一次解决三个约束：
+            //  · 无缝：先清掉 [9] 矩形内的带子，箭头边距 α 就不会与带子 α 相加 → 与左右带子逐像素一致。
+            //    ⚠️ 若直接 source-over，边距 α 与带子 α 相加(32+33≈60) → 又现台阶(皇上反馈的"接缝")。
+            //  · 清晰：箭身/尖点=亮青高透明(α≈248) → 可见。
+            //    ⚠️ 若用 source-atop 会把箭头 α 压到带子的≈43 → 整块与带子同透明 → 看不见(皇上反馈"看不清楚")。
+            //  · 不破坏其它块：clearRect 只清 [9] 矩形(实测仅 1144 像素差异、全落在该矩形内)，
+            //    绝不动 11-slice 已画好的边框。
+            //    ⚠️ 绝不可用 copy：canvas 的 copy 会【清空整个画布、只保留本次绘制】→ 边框全没(皇上反馈"其他边框全没了")。
+            ctx.clearRect(tipDstX, tipDstY, tipDstW, tipDstH);
+            draw(TIP_SRC_X, TIP_SRC_Y, TIP_SRC_W, TIP_SRC_H, tipDstX, tipDstY, tipDstW, tipDstH);
+        }
+
+        // ===== 调试分割线（11 块边界 + 文字区边界）=====
+        if (this._showGrid) {
+            ctx.save();
+            ctx.strokeStyle = "rgba(255,0,0,0.85)";
+            ctx.lineWidth = 1;
+            ctx.beginPath();
+            // 4 角方框（不可变形区域可视化）
+            ctx.strokeRect(0, 0, cornerSize, cornerSize);
+            ctx.strokeRect(bodyWc - cornerSize, 0, cornerSize, cornerSize);
+            ctx.strokeRect(0, bodyHc - cornerSize, cornerSize, cornerSize);
+            ctx.strokeRect(bodyWc - cornerSize, bodyHc - cornerSize, cornerSize, cornerSize);
+            // 上/下/左/右可拉伸带边界
+            ctx.moveTo(cornerSize, 0); ctx.lineTo(cornerSize, cornerSize);
+            ctx.moveTo(bodyWc - cornerSize, 0); ctx.lineTo(bodyWc - cornerSize, cornerSize);
+            ctx.moveTo(0, cornerSize); ctx.lineTo(cornerSize, cornerSize);
+            ctx.moveTo(0, bodyHc - cornerSize); ctx.lineTo(cornerSize, bodyHc - cornerSize);
+            // 中间行上下边界
+            ctx.moveTo(cornerSize, cornerSize); ctx.lineTo(bodyWc - cornerSize, cornerSize);
+            ctx.moveTo(cornerSize, bodyHc - cornerSize); ctx.lineTo(bodyWc - cornerSize, bodyHc - cornerSize);
+            // 左右可拉伸带与中间区分界
+            ctx.moveTo(cornerSize, cornerSize); ctx.lineTo(cornerSize, bodyHc - cornerSize);
+            ctx.moveTo(bodyWc - cornerSize, cornerSize); ctx.lineTo(bodyWc - cornerSize, bodyHc - cornerSize);
+            // 尖角块轮廓（叠加在底边带中央，含下方凸出的箭头段）
+            ctx.strokeRect(tipDstX, tipDstY, tipDstW, tipDstH);
+            ctx.stroke();
+            ctx.restore();
+        }
+
+        // 调试描边：整个 canvas 红色边框
+        if (this._showOutline) {
+            ctx.save();
+            ctx.strokeStyle = "rgba(255,0,0,0.85)";
+            ctx.lineWidth = 2;
+            ctx.strokeRect(1, 1, canvasW - 2, canvasH - 2);
+            ctx.restore();
+        }
+
+        // ===== 绘制文字 =====
+        // 文字块居中在 body 主体内（文字区中心 = (bodyWc/2, cornerSize + textAreaH/2)）
+        ctx.save();
+        ctx.fillStyle = this._color;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "alphabetic";
+        const cx = bodyWc / 2;
+        const textCenterY = cornerSize + (bodyHc - 2 * cornerSize) / 2;
+        const firstAscent = metrics[0].ascent;
+        const lastDescent = metrics[metrics.length - 1].descent;
+        const y0 = textCenterY - (lines.length - 1) * lineH / 2 + (firstAscent - lastDescent) / 2;
+        lines.forEach((line, index) => {
+            const y = y0 + index * lineH;
+            ctx.fillText(line, cx, y);
+        });
+        ctx.restore();
+
+        // 更新纹理
+        this._textTexture?.dispose();
+        const texture = new Texture(this._textCanvas);
+        texture.colorSpace = SRGBColorSpace;
+        texture.minFilter = LinearFilter;
+        texture.magFilter = LinearFilter;
+        texture.needsUpdate = true;
+        this._textTexture = texture;
+        this._shader.uniforms.uTextTexture.value = texture;
+
+        // 同步 sprite 世界尺寸
+        // 世界宽 = 画布宽 × pxToWorld；世界高 = 画布高 × pxToWorld（箭头凸出随之缩放）
+        this.scale.set(canvasW * pxToWorld, canvasH * pxToWorld, 1);
+    }
+}

package/SpriteWithHtml.d.ts

@@ -1,7 +1,9 @@
 import { Sprite } from "three";
+type HexColorString = `#${string}`;
 export default class SpriteWithHtml extends Sprite {
-    constructor(html?: string, backgroundColor?: `#${string}`);
+    constructor(html?: string, backgroundColor?: HexColorString);
     visible: boolean;
     div: HTMLDivElement;
-    setHtml(html?: string, backgroundColor?: `#${string}`): Promise<void>;
+    setHtml(html?: string, backgroundColor?: HexColorString): Promise<void>;
 }
+export {};

package/SpriteWithHtml.ts

@@ -0,0 +1,50 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2023-04-15 11:26:32
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2023-04-15 12:38:09
+ */
+import { snapdom } from "@zumer/snapdom";
+import { Texture, Sprite } from "three";
+import threeLoader from "./threeLoader";
+import type { SpriteWithHtmlEventMap } from "./EventMap";
+
+type HexColorString = `#${string}`;
+
+// html 文本面板
+export default class SpriteWithHtml extends Sprite {
+    constructor(html: string = "", backgroundColor: HexColorString = "#00000000") {
+        super();
+        this.setHtml(html, backgroundColor);
+    }
+
+    visible: boolean = false;
+    div: HTMLDivElement = (() => {
+        const div = document.createElement("div");
+        div.style.position = "fixed";
+        div.style.top = "100%";
+        div.style.left = "100%";
+        div.style.pointerEvents = "none";
+        div.style.userSelect = "none";
+        div.style.lineHeight = "1";
+        div.style.whiteSpace = "nowrap";
+        return div;
+    })();
+
+    async setHtml(html: string = "", backgroundColor: HexColorString = "#00000000"): Promise<void> {
+        this.div.innerHTML = html;
+        document.body.appendChild(this.div);
+        const img = await snapdom.toPng(this.div, { backgroundColor });
+        this.scale.set(img.naturalWidth, img.naturalHeight, 1);
+        const texture = new Texture(img);
+        texture.needsUpdate = true;
+        this.material.map = texture;
+        this.material.map.anisotropy = threeLoader.anisotropy;
+        this.material.alphaTest = 0.1;
+        this.material.needsUpdate = true;
+        await new Promise(resolve => requestAnimationFrame(resolve));
+        this.visible = true;
+        this.div.remove();
+        this.dispatchEvent({ type: "loaded" } as never);
+    }
+}