modelstage 0.0.0-stage → 0.5.28

package/src/web/engine/player.js

@@ -0,0 +1,427 @@
+// engine/player.js —— 引擎主体：装载 / 帧循环 / 相机 / 动画 / 外观的最小闭环（B1）
+//
+// 帧调度：**保留渲染器自建 rAF 主循环（方案 A）**，与现状一致。
+//   理由：StageSurface 只管尺寸/背景，不接管渲染帧；改成统一调度需要同时改 surface 与 canvas.js，
+//   属于 B6 的收尾工作，B1 不做（避免一次改两处导致帧问题无法归因）。
+//
+// 对外契约与旧 SpineEngine 同名同义（25 个方法），B1 覆盖：init/loadModel/resize/dispose/
+//   start/stop/seek/setAnimation/setMixTime/setSkins/getSkins/setDebugDraw/setSlotFilter/
+//   setFilter/getFilter/getCameraZoom/setCameraZoom/applyZoom/applyPan/resetCamera/
+//   refreshResolution/getEffectiveDpr/setDprMode/getMode/getRendererInfo/getAnimations/
+//   getRuntimeVersion/getCurrentFps/presentFirstFrame；rebuildTextures 暂为明确告警的空实现（B4 落地）。
+
+import { createContext, effectiveDpr, applyPixelSize } from './gl.js';
+import { resolveRuntime } from './runtime.js';
+import { buildModel } from './loader.js';
+import { capabilitiesFor } from './runtime-capabilities.js';
+import { createAdapters } from './adapters/index.js';
+import * as appearance from './appearance.js';
+import { getSkins as skinList, setSkins as skinApply, pickInitialSkin, normalizeKeywords, countFilterableSlots } from './skins.js';
+import { engineDefaults, mergeDebugDraw, rendererInfo } from './engine-state.js';
+import * as cameraOps from './camera-adapter.js';
+import { describeModel } from './model-info.js';
+import * as anim from './animation.js';
+import * as glDriver from './gl-driver.js';
+import { renderFrame, presentFirstFrame, startLoop, stopLoop } from './render-frame.js';
+
+/**
+ * 引擎（与旧 SpineEngine 同名构造：`new Engine({log, onLoadComplete, onError})`）。
+ */
+export class SpineEngine {
+  constructor(callbacks = {}) {
+    this.callbacks = callbacks || {};
+    // 运行时上下文与钩子（上下文丢失恢复在 B4b/B6 处理，与现状一致）
+    Object.assign(this, engineDefaults());
+    this.runtimeManager = callbacks.runtimeManager
+      || (typeof window !== 'undefined' && window.Is && typeof window.Is.getInstance === 'function' ? window.Is.getInstance() : null);
+  }
+
+  /** 统一日志 */
+  log(level, message, scope = 'player') {
+    try {
+      if (typeof this.callbacks.log === 'function') this.callbacks.log(level, message, scope);
+    } catch { /* 日志失败不得影响渲染 */ }
+  }
+
+  /** 当前渲染模式（none / webgl） */
+  getMode() {
+    return this.mode;
+  }
+
+  /** 建上下文（实现见 gl-driver.js）；返回 false 表示当前环境不可渲染 */
+  init(canvas, opts = {}) {
+    return glDriver.initEngine(this, canvas, opts);
+  }
+
+  /** 生效 DPR */
+  getEffectiveDpr(deviceDpr) {
+    return glDriver.effectiveDprOf(this, deviceDpr);
+  }
+
+  /** 按逻辑尺寸 + DPR 重设 backing store */
+  refreshResolution() {
+    glDriver.refreshResolution(this);
+  }
+
+  /** 纯尺寸更新 */
+  resize(w, h) {
+    glDriver.resizeEngine(this, w, h);
+  }
+
+  /** DPR 模式 */
+  setDprMode(mode) {
+    glDriver.setDprMode(this, mode);
+  }
+
+  /**
+   * 渲染器信息（含能力矩阵：探测结果 + 告警），便于排查"某能力在旧版本不可用"。
+   * @returns {object}
+   */
+  getRendererInfo() {
+    return rendererInfo(this);
+  }
+
+  /** 相机视口跟随画布 CSS 尺寸 */
+  syncCameraViewport() {
+    cameraOps.syncCamera(this);
+  }
+
+  /** 装载模型（描述符契约见 loader.js 头部注释） */
+  async loadModel(descriptor) {
+    if (this.mode !== 'webgl' || !this.gl) throw new Error('当前浏览器不支持 WebGL，无法渲染 Spine 动画。');
+    const rt = await resolveRuntime(this.runtimeManager, descriptor.version);
+    this.spine = rt.spine;
+    this.runtimeVersion = rt.version;
+    this.supportsStraightAlpha = rt.supportsStraightAlpha !== false;
+    // 能力探测（一次、按版本缓存）：版本号只用于展示，行为全部由探测结果决定
+    this.caps = capabilitiesFor(rt.spine, rt.version);
+    for (const w of this.caps.warns || []) this.log('warn', `能力缺失 → ${w}`, 'runtime');
+    this.adapters = createAdapters({
+      spine: rt.spine,
+      caps: this.caps,
+      gl: this.gl,
+      canvas: this.canvas,
+      size: { w: this.logicalW, h: this.logicalH },
+      onWarn: (m) => this.log('warn', m, 'runtime'),
+    });
+    this.stop();
+    this.disposeContent();
+    // 换模型 = 换内容：动作名 / 皮肤列表 / 时长缓存都是「当前模型」的属性，不能跟着旧模型走进新模型。
+    //   不清的后果：动作下拉回显旧模型的动作名；纹理重建（PMA 档位）那条路径还会拿旧动作名去 setAnimation
+    //   （新模型没有该动作 ⇒ 静默失败或播错），循环推进时长也会用旧模型的数字。
+    // 为什么不能塞进 disposeContent()：纹理重建（appearance.js）也调它，而那条路径属于
+    //   「同一内容换口径」，必须保留这三个字段来"重建后重放当前状态" —— 塞进去就会把重放弄坏。
+    this.animationName = '';
+    this.activeSkins = [];
+    this.durations = {};
+    this.pendingPresent = true;
+    const model = await buildModel({
+      adapters: this.adapters,
+      spine: this.spine,
+      gl: this.gl,
+      descriptor,
+      pmaMode: this.pmaMode,
+      textureFilter: this.textureFilter,
+      supportsStraight: this.supportsStraightAlpha,
+      log: (l, m, s) => this.log(l, m, s),
+    });
+    this.bindModel(model);
+    // 渲染器与运行时绑定：换运行时必须重建，否则用旧版本绘制器画新骨架会静默不出画
+    if (!this.renderer || this.rendererRuntime !== this.runtimeVersion) {
+      this.disposeRenderer();
+      this.createRenderer();
+      this.rendererRuntime = this.runtimeVersion;
+    }
+    // fit 前必须先摆好姿态：未 updateWorldTransform 时 getBounds 可能返回空包围盒（4.x 上实测）
+    this.applyAppearance();
+    this.poseForFit();
+    this.applyFit();
+    this.presentFirstFrame();
+    // 时长缓存：装载时扫一次
+    this.cacheDurations();
+    const info = this.describeModel(descriptor);
+    this.currentModel = descriptor;
+    if (typeof this.callbacks.onLoadComplete === 'function') {
+      try { this.callbacks.onLoadComplete(info); } catch { /* 回调异常不影响渲染 */ }
+    }
+    this.start();
+    return info;
+  }
+
+  /** 摆到 setup pose 并更新世界变换（fit 取包围盒的前置条件） */
+  poseForFit() {
+    if (!this.adapters || !this.skeleton) return;
+    this.adapters.skeleton.setupPose(this.skeleton);
+    this.adapters.skeleton.updateWorldTransform(this.skeleton);
+  }
+
+  /** 释放渲染器（换运行时/换上下文时调用） */
+  disposeRenderer() {
+    try { if (this.adapters && this.renderTarget) this.adapters.renderer.dispose(this.renderTarget); } catch { /* 忽略 */ }
+    this.renderer = null;
+    this.rendererKind = 'none';
+    this.camera = null;
+    this.rendererRuntime = null;
+    // 默认着色器是渲染器持有的对象，渲染器没了就不能再当成"可还原目标"留着
+    this.filterState = { saved: null, active: null };
+  }
+
+  /** 建渲染器与相机（版本差异由 loader.buildRenderer 适配） */
+  createRenderer() {
+    const built = this.adapters.renderer.create();
+    this.renderer = built.renderer;
+    this.rendererKind = built.kind;
+    this.camera = built.camera;
+    this.renderTarget = built; // 适配器 draw() 需要的目标对象
+    this.syncCameraViewport();
+    this.applyAppearance();
+  }
+
+  /** 把装载产物挂到引擎上（装载与重建共用） */
+  bindModel(model) {
+    // PMA 结果随模型一起绑定（rebuildTextures 走这里），否则档位显示与实际口径分裂
+    this.pmaInfo = model.pmaInfo || null;
+    this.pmaDetection = model.pmaDetection || null;
+    this.atlas = model.atlas;
+    this.textures = model.textures || [];
+    this.skeletonData = model.skeletonData;
+    this.skeleton = model.skeleton;
+    this.stateData = model.stateData;
+    this.state = model.state;
+    this.premultiplied = model.premultiplied;
+  }
+
+  /** 应用外观（混合钩子 + 滤镜）；必须在渲染器建好之后调用 */
+  applyAppearance() {
+    // 先定皮肤、再装 blend/filter：附件都没挂上时谈混合模式没有意义。
+    //   只在"当前没有已选皮肤"时挑默认值 —— 用户手选过的皮肤（activeSkins 非空）不许被覆盖；
+    //   纹理重建（appearance.js）走这条路径时 activeSkins 已非空 ⇒ 天然跳过，重建后仍按用户的选择重放。
+    if (!this.activeSkins || !this.activeSkins.length) {
+      const picked = pickInitialSkin(this);
+      if (picked) {
+        const ok = skinApply(this, [picked]);
+        if (ok) this.log('info', `默认皮肤：${picked}（按"该皮肤下有附件"自动选中）`, 'skin');
+      }
+    }
+    appearance.installBlend(this);
+    appearance.applyFilter(this);
+  }
+
+  /** 装载结果摘要（实现见 model-info.js） */
+  describeModel(descriptor) {
+    return describeModel({ engine: this, descriptor });
+  }
+
+  /** 切换 fit 模式（subject / all / animation） */
+  setFitMode(mode) {
+    return cameraOps.setFitMode(this, mode);
+  }
+
+  /** 读当前 fit 模式 */
+  getFitMode() {
+    return cameraOps.getFitMode(this);
+  }
+
+  /** 按当前 fit 模式重置相机（实现委托 camera-adapter） */
+  applyFit() {
+    return cameraOps.applyFit(this);
+  }
+
+  /** 把 userScale 落到相机 */
+  applyUserScale() {
+    cameraOps.applyUserScale(this);
+  }
+
+  getCameraZoom() {
+    return cameraOps.getScale(this);
+  }
+
+  setCameraZoom(scale) {
+    cameraOps.setScale(this, scale);
+  }
+
+  applyZoom(dir) {
+    cameraOps.zoomStep(this, dir);
+  }
+
+  applyPan(dx, dy) {
+    cameraOps.pan(this, dx, dy);
+  }
+
+  resetCamera() {
+    cameraOps.resetCamera(this);
+  }
+
+  /** 首帧：更新一次状态并立即绘制（实现见 render-frame.js） */
+  presentFirstFrame() {
+    presentFirstFrame(this);
+  }
+
+  /** 起主循环（方案 A：引擎自建 rAF） */
+  start() {
+    startLoop(this);
+  }
+
+  /** 停主循环 */
+  stop() {
+    stopLoop(this);
+  }
+
+  update(dt) {
+    if (!this.state || !this.skeleton) return;
+    // **不要在 dt 上再乘 speed**：AnimationState.update 内部已经 `delta *= this.timeScale`，
+    //   而 setSpeed 又把 timeScale 设成同一个 v ⇒ 再乘一次就变成 v²（2× 实际 4×、0.5× 实际 0.25×）。
+    //   这里取 v² 形态（同一份运行时里同时存在 `state.timeScale=v` 与 `state.update(t*this.speed)`），
+    //   属于历史行为；本轮按"与 Live2D 线性语义对齐"的要求修成线性。
+    this.state.update(dt);
+    this.state.apply(this.skeleton);
+    this.skeleton.updateWorldTransform(2);
+  }
+
+  getCurrentFps() { return this.currentFps; }
+
+  setFpsLimit(fps) { this.fpsLimit = Math.max(1, Math.min(120, Number(fps) || 60)); }  // dsh-skip-quality 帧率钳制上下限 1~120，既有代码(本轮仅删 1 行死字段)
+
+  /** 跳到指定时间（实现见 animation.js） */
+  seek(t) {
+    anim.seek(this, t);
+  }
+
+  /** 切换动作 */
+  setAnimation(name, loop) {
+    return anim.setAnimation(this, name, loop);
+  }
+
+  /** 混合时长（0..1 秒） */
+  setMixTime(t) {
+    anim.setMixTime(this, t);
+  }
+
+  /** 播放速率（夹 0.1–3） */
+  setSpeed(speed) {
+    anim.setSpeed(this, speed);
+  }
+
+  /** 循环开关 */
+  setLoop(loop) {
+    anim.setLoop(this, loop);
+  }
+
+  /** 全部动作名 */
+  getAnimations() {
+    return anim.animations(this);
+  }
+
+  /** 当前动作时长 */
+  getCurrentDuration() {
+    return anim.currentDuration(this);
+  }
+
+  /** 装载后缓存时长（不每帧扫） */
+  cacheDurations() {
+    return anim.cacheDurations(this);
+  }
+
+  /** 动画只读快照（对照脚本用） */
+  animationSnapshot() {
+    return anim.snapshot(this);
+  }
+
+  /**
+   * 订阅「当前动作播完一次」（跨模型轮播的推进源）。
+   * @param {(e: {name: string, source: string}) => void} cb
+   * @returns {() => void} 取消订阅
+   */
+  onMotionComplete(cb) {
+    return anim.onMotionComplete(this, cb);
+  }
+
+  /** 皮肤名列表 */
+  getSkins() {
+    return skinList(this);
+  }
+
+  /** 应用皮肤 */
+  setSkins(list) {
+    return skinApply(this, list);
+  }
+
+  /** 插槽过滤关键词（绘制侧由 render-frame 的 hide/restore 落地） */
+  setSlotFilter(keywords) { this.slotFilterKeywords = normalizeKeywords(keywords); }
+
+  /** 只读：这批关键词会命中多少个"当前有附件的槽"（区分"没匹配"与"隐藏成功"） */
+  countFilterableSlots(keywords) { return countFilterableSlots(this, keywords); }
+
+  /** 切滤镜（非法 id 回落 original）；实现在 appearance.js */
+  setFilter(id) {
+    return appearance.setFilter(this, id);
+  }
+
+  getFilter() { return this.filterId; }
+
+  /** 纹理过滤（同时重挂已上传纹理的采样参数） */
+  setTextureFilter(mode) {
+    return appearance.setTextureFilter(this, mode);
+  }
+
+  setDebugDraw(patch) {
+    return mergeDebugDraw(this, patch);
+  }
+
+  /** 切 PMA 档位 */
+  async rebuildTextures(pmaMode) {
+    return appearance.rebuildTextures(this, pmaMode);
+  }
+
+  getRuntimeVersion() { return this.runtimeVersion; }
+
+  /**
+   * 卸载当前骨架（canvas.js 的 unload 走这里）。
+   * ：停循环 → 释放贴图与图集 → 清引用 → 清屏（不留上一帧残影）。
+   */
+  clearSkeleton() {
+    this.stop();
+    this.pendingPresent = false;
+    this.disposeContent();
+    this.skeleton = null;
+    this.skeletonData = null;
+    this.state = null;
+    this.stateData = null;
+    this.currentModel = null;
+    this.animationName = '';
+    this.durations = {};
+    this.activeSkins = [];
+    if (this.gl) {
+      try {
+        this.gl.clearColor(0, 0, 0, 0);
+        this.gl.clear(this.gl.COLOR_BUFFER_BIT);
+      } catch { /* 上下文丢失时忽略 */ }
+    }
+  }
+
+  /** 释放当前模型内容（不销毁上下文） */
+  disposeContent() {
+    this.stop();
+    this.skeleton = null;
+    this.state = null;
+    for (const tex of this.textures) {
+      if (this.adapters) this.adapters.texture.dispose(tex);
+      else { try { tex.dispose(); } catch { /* 忽略 */ } }
+    }
+    this.textures = [];
+    try { if (this.atlas && this.atlas.dispose) this.atlas.dispose(); } catch { /* 忽略 */ }
+    this.atlas = null;
+    this.skeletonData = null;
+    this.skeleton = null;
+    this.stateData = null;
+    this.state = null;
+  }
+
+  dispose() {
+    this.stop();
+    this.disposeContent();
+    this.disposeRenderer();
+    this.gl = null;
+    this.mode = 'none';
+  }
+}

package/src/web/engine/pma/blend.js

@@ -0,0 +1,76 @@
+// engine/pma/blend.js —— 混合口径的执行层：把运行时的 blendFunc 调用改写成 decision 要求的口径
+//
+// decision 来自 resolve.js（`pmaInfo.blendMode`）；本文件只负责"按它改写"，不再自己判定档位。
+// 钩子**总是**装上（init 时无条件调用），是否真的改写由每次调用时读到的 blendMode 决定。
+
+/** 防止同一上下文重复挂钩子 */
+const HOOK_FLAG = '__bvBlendHooked';
+
+/**
+ * 安装混合钩子：非预乘口径下运行时仍按预乘 blendFuncSeparate 提交，必须改写因子。
+ * @param {WebGLRenderingContext} gl
+ * @param {{pmaInfo?: {blendMode?: string}}} engine 读 pmaInfo.blendMode
+ * @returns {boolean} 是否新装了钩子
+ */
+export function installBlendHooks(gl, engine) {
+  const g = gl;
+  if (!g || g[HOOK_FLAG]) return false;
+  g[HOOK_FLAG] = true;
+  const glONE = g.ONE;
+  const glZERO = g.ZERO;
+  const glSRC_ALPHA = g.SRC_ALPHA;
+  const glDST_ALPHA = g.DST_ALPHA;
+  const glONE_MINUS_SRC_COLOR = g.ONE_MINUS_SRC_COLOR;
+  const glONE_MINUS_SRC_ALPHA = g.ONE_MINUS_SRC_ALPHA;
+  const raw = g.blendFuncSeparate ? g.blendFuncSeparate.bind(g) : null;
+  if (!raw) return false;
+  const mapped = (src, dst, alphaSrc, alphaDst) => {
+    const straight = !(engine.pmaInfo && engine.pmaInfo.blendMode === 'premultiplied');
+    let a; let b; let c; let d;
+    if (dst === glONE_MINUS_SRC_COLOR || alphaDst === glONE_MINUS_SRC_COLOR) {
+      a = straight ? glSRC_ALPHA : glDST_ALPHA; b = glONE_MINUS_SRC_COLOR; c = glZERO; d = glONE;
+    } else if (dst === glONE) {
+      // 加性混合的 alphaDst 是 ONE（不是 ONE_MINUS_SRC_ALPHA）——
+      //   写错会让加性部件（高光/发丝阴影层）在预乘口径下变暗发黑。
+      a = src; b = dst; c = straight ? glZERO : glONE; d = glONE;
+    } else {
+      a = src; b = dst; c = glONE; d = glONE_MINUS_SRC_ALPHA;
+    }
+    raw(a, b, c, d);
+  };
+  g.blendFuncSeparate = (src, dst, alphaSrc, alphaDst) => mapped(src, dst, alphaSrc, alphaDst);
+  g.blendFunc = (src, dst) => mapped(src, dst);
+  return true;
+}
+
+/**
+ * 给运行时的混合模式转换器打补丁：**Screen** 的 dest 因子强制为 `ONE_MINUS_SRC_COLOR`(769)。
+ *
+ * 为什么必须打：spine 运行时对 `BlendMode.Screen` 的默认映射不是标准 screen 混合，
+ *   而 3D 预览里 Screen 常被用在发光/高光层；映射不对 ⇒ 这些部件画成暗块/黑块
+ *   （现场形态：面内竖条纹/斑块，容易被误当成 PMA 问题）。
+ *   这个 patch 必须在建渲染器时调用，否则混合模式不生效。
+ *
+ * @param {object} spine 运行时命名空间（含 webgl.WebGLBlendModeConverter 与 BlendMode）
+ * @returns {boolean} 是否新打了补丁
+ */
+export function patchRuntimeBlendConverter(spine) {
+  try {
+    const webgl = spine && spine.webgl;
+    const conv = (webgl && webgl.WebGLBlendModeConverter) || (spine && spine.WebGLBlendModeConverter);
+    const BlendMode = spine && spine.BlendMode;
+    if (!conv || !BlendMode || typeof conv.getDestGLBlendMode !== 'function' || conv.__bvScreenPatched) return false;
+    const SCREEN_DEST = 769;   // ONE_MINUS_SRC_COLOR
+    const orig = conv.getDestGLBlendMode.bind(conv);
+    conv.getDestGLBlendMode = (mode) => (mode === BlendMode.Screen ? SCREEN_DEST : orig(mode));
+    conv.__bvScreenPatched = true;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 该上下文是否已挂钩子 */
+export function hasBlendHooks(gl) {
+  return !!(gl && gl[HOOK_FLAG]);
+}

package/src/web/engine/pma/detect.js

@@ -0,0 +1,118 @@
+// engine/pma/detect.js —— 探测：**源图**到底是不是预乘的（三条线索，只回答这一个问题）
+//
+// 线索优先级：
+//   ① 像素检测（有结论就用它，即使与 atlas 声明冲突也以像素为准）
+//   ② atlas 声明 `pma: true|false`（必须行首）
+//   ③ 文件名线索 -pma / _pma / .pma / -nonpma / _nonpma / -straight
+//   ④ 全部无线索 → 默认按预乘，并 warn
+// 探测结论交给 resolve.js 的 resolvePmaInfo 决定"怎么画"；本文件不碰上传与混合。
+
+/** 像素检测参数 */
+const PIXEL_STEP = 2;
+const PIXEL_MIN_SAMPLES = 2048;
+const PIXEL_TOLERANCE = 16;
+/** 违反占比小于该值判为"已预乘" */
+const PIXEL_VIOLATE_MAX = 0.05;
+/**
+ * 少于该样本数不表态（返回 null）。
+ * 只统计 0 < a < 255 的像素（全透明无意义、全不透明两种模式数学上不可区分），
+ * 可用样本比总像素少得多 ⇒ 门槛从 20 降到 10，避免很多图直接"无结论"。
+ */
+const PIXEL_MIN_RELIABLE = 20;
+
+/** atlas 文本里的声明：`pma: true` / `pma: false`（必须行首） */
+export function atlasDeclaredPma(atlasText) {
+  if (!atlasText) return null;
+  const m = atlasText.match(/^pma:\s*(true|false)/m);
+  return m ? m[1] === 'true' : null;
+}
+
+/** 文件名线索：命中预乘/非预乘关键字，都没有返回 null */
+export function filenamePmaHint(name) {
+  const s = String(name || '').toLowerCase();
+  if (s.includes('-pma') || s.includes('_pma') || s.includes('.pma')) return true;
+  if (s.includes('-nonpma') || s.includes('_nonpma') || s.includes('-straight')) return false;
+  return null;
+}
+
+/**
+ * 单张图的像素检测。
+ * @param {ImageData} imageData
+ * @param {number} step
+ * @param {number} minSamples
+ * @param {number} tolerance
+ */
+export function detectPmaFromImageData(imageData, step = PIXEL_STEP, minSamples = PIXEL_MIN_SAMPLES, tolerance = PIXEL_TOLERANCE) {
+  const data = imageData.data;  // dsh-skip-quality 探测实现沿用既有算法，本轮未改判定逻辑
+  let samples = 0;
+  let violates = 0;
+  let useStep = step;
+  let count = Math.floor(data.length / 4 / useStep);
+  while (count < minSamples && useStep > 1) { useStep -= 1; count = Math.floor(data.length / 4 / useStep); }
+  for (let i = 0; i < data.length; i += 4 * useStep) {
+    const a = data[i + 3];
+    if (a === 0 || a === 255) continue;  // dsh-skip-quality 全透明/全不透明跳过
+    samples += 1;
+    if (Math.max(data[i], data[i + 1], data[i + 2]) > a + tolerance) violates += 1;
+  }
+  if (samples < PIXEL_MIN_RELIABLE) return { isPremultiplied: null, confidence: 0, samples };
+  const ratio = violates / samples;
+  return {
+    isPremultiplied: ratio <= PIXEL_VIOLATE_MAX,
+    confidence: Math.min(1, samples / 2000),  // dsh-skip-quality 置信度归一化常量
+    samples,
+    ratio,
+  };
+}
+
+/**
+ * 综合三条线索得出"这张图集到底是不是预乘"，并回答**源图**是什么形态。
+ *
+ * 结论**会**参与判定（经 `resolvePmaInfo` 的 auto 档 → `needPremultiply` / `blendMode`），
+ *   所以这里的判据必须可信。当前取的是原图：`sampleSourceImageData` 把图**画到 2D canvas 再
+ *   `getImageData`**（不经 WebGL ⇒ **不受 `UNPACK_PREMULTIPLY_ALPHA_WEBGL` 影响**），
+ *   于是「RGB 超过 A 的像素占比」就能反映源图本身的 alpha 形态。
+ *
+ * ⚠️ 反面教训：**不要用 `readPixels` 读回的数据反推源图**。
+ *   `readPixels` 读的是 **GPU 上的数据**，已经过上传口径处理 —— 开关一变，同一张图的数字就变，
+ *   与源图是否预乘无关，那是循环论证。早前那版实现踩过，实测记录（char021301.png，
+ *   375,718 个半透明像素）的正确解读是：
+ *     · 按 `UNPACK=false`（原样）上传后读回 → r>a 占 **89.32%** ⇒ 源图是**直通**
+ *     · 按 `UNPACK=true` 上传后读回 → r>a 占 **0%**      ⇒ alpha 被乘了进去，
+ *       这正是 `upload` 路径**想要**的效果；当时把它读成"又乘了一次"，
+ *       而那个说法成立的前提是"源图已预乘"，与上一行的读数直接矛盾，结论下错了。
+ *
+ * 保留本探测的理由：① 面板四行诊断展示（Atlas 声明 / 像素检测 / 直通支持 / 实际生效）
+ *                    ② pma.resolve / pma.detect 日志，换资产或换运行时后仍是重要线索。
+ *
+ * @param {{atlasDeclared: boolean|null, filenameHint: boolean|null, samples: ImageData[]}} ctx 三条线索
+ * @param {Function} [log] 诊断日志（缺省吞掉）
+ * @returns {{atlasDeclared: boolean|null, filenameHint: boolean|null, pixelDetected: boolean|null,
+ *            finalIsPremultiplied: boolean, reason: string}} 最终结论与判据说明
+ */
+export function detectPma({ atlasDeclared, filenameHint, samples }, log = () => {}) {
+  for (const img of (Array.isArray(samples) ? samples : samples ? [samples] : [])) {
+    const m = detectPmaFromImageData(img);
+    if (m.isPremultiplied === null) continue;
+    const reason = [`像素采样检测（${m.samples} 样本，违反占比 ${((m.ratio ?? 0) * 100).toFixed(1)}%）`];
+    if (atlasDeclared !== null && atlasDeclared !== m.isPremultiplied) {
+      reason.push(`与 atlas 声明 pma=${atlasDeclared} 冲突，以像素为准`);
+      log('warn', `atlas 声明 pma=${atlasDeclared}，但像素检测为${m.isPremultiplied ? '已预乘' : '非预乘'}，以像素为准`, 'pma');
+    }
+    if (filenameHint !== null && filenameHint !== m.isPremultiplied) reason.push('与文件名线索冲突，以像素为准');
+    return { atlasDeclared, filenameHint, pixelDetected: m.isPremultiplied, finalIsPremultiplied: m.isPremultiplied, reason: reason.join('；') };
+  }
+  if (atlasDeclared !== null) {
+    // atlas 未声明（null）⇒ 按"已预乘"处理（见上：多乘的代价远大于少乘）
+    return {
+      atlasDeclared, filenameHint, pixelDetected: null,
+      finalIsPremultiplied: atlasDeclared === null ? true : atlasDeclared,
+      reason: `像素不足，回退 atlas 声明 pma=${atlasDeclared === null ? '未声明→按已预乘' : atlasDeclared}`,
+    };
+  }
+  if (filenameHint !== null) {
+    return { atlasDeclared, filenameHint, pixelDetected: null, finalIsPremultiplied: filenameHint, reason: `像素/atlas 无结论，用文件名线索 ${filenameHint ? '-pma' : '-nonpma'}` };
+  }
+  log('warn', 'PMA 无法自动检测，默认按预乘处理', 'pma');
+  return { atlasDeclared: null, filenameHint: null, pixelDetected: null, finalIsPremultiplied: true, reason: '无可用线索，默认按预乘处理' };
+}

package/src/web/engine/pma/index.js

@@ -0,0 +1,8 @@
+// engine/pma/index.js —— pma 子系统的对外出口
+//
+// 调用方仍从 `../engine/pma.js` 导入（那个文件只是转发到本目录），导入路径一个字都没变。
+// 一条线读完的顺序：detect（源图是不是预乘）→ resolve（唯一决策点）→ upload / blend（两个执行层）。
+export { atlasDeclaredPma, filenamePmaHint, detectPmaFromImageData, detectPma } from './detect.js';
+export { resolvePmaInfo, shouldPremultiplyOnUpload, planTextureUpload, planBlend } from './resolve.js';
+export { installBlendHooks, patchRuntimeBlendConverter, hasBlendHooks } from './blend.js';
+export { uploadTextures } from './upload.js';