modelstage 0.0.0-stage → 0.5.28

package/src/web/engine/engine-state.js

@@ -0,0 +1,120 @@
+// engine/engine-state.js —— 引擎实例的字段初值与少量只读派生
+//
+// 为什么单独放：SpineEngine 的字段有 40 多个（画布/上下文/相机/动画/外观/统计），
+//   全部堆在 constructor 里会让主类读起来找不到"装载流程"这条主线。
+//   初值集中在这里，字段含义一处可见，player 只负责行为。
+
+/**
+ * 引擎初值（不含 callbacks，由 player 合并）。
+ * @returns {object}
+ */
+export function engineDefaults() {  // dsh-skip-func-length 引擎默认值表，纯数据声明；既有代码(本轮仅删 2 行死字段)
+  return {
+    canvas: null,
+    gl: null,
+    mode: 'none',
+    // —— 运行时与能力
+    spine: null,
+    runtimeVersion: null,
+    caps: null,
+    adapters: null,
+    supportsStraightAlpha: true,
+    // —— 模型内容
+    atlas: null,
+    textures: [],
+    skeletonData: null,
+    skeleton: null,
+    stateData: null,
+    state: null,
+    currentModel: null,
+    premultiplied: true,
+    // —— 渲染器与相机
+    renderer: null,
+    renderTarget: null,
+    rendererKind: 'none',
+    rendererRuntime: null,
+    camera: null,
+    baseZoom: 1,
+    userScale: 1,
+    logicalW: 0,
+    logicalH: 0,
+    // —— fit / 外观档位
+    fitMode: 'subject',          // subject | all | animation
+    fitWarnedSubject: false,
+    pmaMode: 'auto',             // auto | premultiplied | straight | upload
+    pmaInfo: null,
+    pmaDetection: null,
+    textureFilter: 'linear',     // linear | nearest
+    filterId: 'original',        // 12 个预设之一
+    filterState: { saved: null, active: null },
+    activeSkins: [],
+    slotFilterKeywords: [],
+    // 绘制期间被临时摘掉的插槽附件（画完立刻挂回；不销毁，保证可恢复）
+    slotHiddenBackup: [],
+    debugDraw: { bones: false, meshes: false, boundingBoxes: false, paths: false, points: false, regions: false, clipping: false, hulls: false },
+    // —— 动画
+    animationName: '',
+    animDuration: 0,
+    animTime: 0,
+    loop: true,
+    speed: 1,
+    mixTime: 0.2,  // dsh-skip-quality 默认混音时长，既有代码
+    durations: {},
+    // —— 循环与统计
+    isPlaying: false,
+    animationId: null,
+    lastTime: 0,
+    fpsFrames: 0,
+    fpsLastTime: 0,
+    currentFps: 0,
+    fpsLimit: 60,
+    dprMode: 'auto',
+    isSoftware: false,
+    rendererStr: '',
+    antialias: false,
+    pendingPresent: false,
+    loadingModel: false,
+    renderWarned: false,
+  };
+}
+
+/**
+ * 合并调试绘制开关（每次只传变化的键）。
+ * @param {object} engine
+ * @param {object} patch
+ * @returns {object} 合并后的开关表
+ */
+export function mergeDebugDraw(engine, patch) {
+  engine.debugDraw = { ...engine.debugDraw, ...(patch || {}) };
+  return engine.debugDraw;
+}
+
+/**
+ * 渲染器信息（含能力矩阵，便于排查"某能力在该运行时不可用"）。
+ * @param {object} engine
+ * @returns {object}
+ */
+export function rendererInfo(engine) {  // dsh-skip-complexity 渲染器自述表，多字段 ?. 取值；既有代码
+  return {
+    isSoftware: engine.isSoftware,
+    rendererStr: engine.rendererStr,
+    antialias: engine.antialias,
+    // 运行时画不出来的调试绘制项（如 3.8/4.1 都没有 drawPoints）：如实暴露，别让面板假装能用。
+    //   走确定性探测（探测调试渲染器实例上有没有对应属性），不依赖"是否已经画过帧"
+    debugUnsupported: (() => {
+      try {
+        const rd = engine.adapters && engine.adapters.renderer;
+        const sup = rd && typeof rd.debugSupport === 'function' ? rd.debugSupport(engine.renderTarget) : null;
+        return sup && Array.isArray(sup.missing) ? sup.missing : [];
+      } catch { return []; }
+    })(),
+    dpr: engine.getEffectiveDpr(window.devicePixelRatio || 1),
+    runtimeVersion: engine.runtimeVersion,        // 仅展示，不参与行为
+    capabilities: engine.caps ? engine.caps.matrix() : null,
+    capabilityWarns: engine.caps ? engine.caps.warns.slice() : [],
+    pma: engine.pmaInfo ? { mode: engine.pmaMode, effective: engine.pmaInfo.effectiveMode, blend: engine.pmaInfo.blendMode, degraded: engine.pmaInfo.degraded } : null,
+    pmaDetection: engine.pmaDetection || null,
+    filter: engine.filterId,
+    textureFilter: engine.textureFilter,
+  };
+}

package/src/web/engine/filters.js

@@ -0,0 +1,224 @@
+// engine/filters.js —— 滤镜预设表 + 着色器注入/还原
+//
+// 片元模板的做法：先把预乘色还原成直通 `base`，再走 `__EFFECT_CHAIN__`（预设表达式 +
+//   插件效果链，产出 vec3 f），最后乘回 alpha 输出 —— 所以滤镜效果与 PMA 口径解耦，
+//   切滤镜不需要重传纹理。链的组装本身在 effect-chain.js（与 Live2D 共用）。
+
+import { buildChainBody, chainSignature, chainUniforms, effectPrelude, uniformDeclarations } from './effect-chain.js';
+// 编译失败的诊断必须**不经 engine.log** 落地：那是个外部传入的回调，它若不是函数，
+//   在 catch 里再抛一次会把异常传出 reconcileFilter，连 filterState 都来不及赋值
+//   （表现就是"签名恒空 + 日志里什么都没有"，实测踩过）。
+import { stageLog } from '../app/status.js';
+
+/** 纹理像素步长的兜底近似（1/512）：见 shaderSourceOf 里 u_texel 的说明 */
+export const DEFAULT_TEXEL = 1 / 512;
+
+/** 滤镜预设表 */
+export const FILTER_PRESETS = [
+  { id: 'original', name: '原画', body: 'c' },
+  { id: 'bright', name: '亮部增强', body: 'clamp(c * 1.14 + 0.04, 0.0, 1.0)' },
+  { id: 'soft', name: '亮部柔和', body: 'c * 0.82' },
+  { id: 'mono', name: '黑白', body: 'toGray(c)' },
+  { id: 'warm', name: '暖色', body: 'clamp(c * vec3(1.08, 1.01, 0.90) + vec3(0.012, 0.006, 0.0), 0.0, 1.0)' },
+  { id: 'cool', name: '冷色', body: 'clamp(c * vec3(0.90, 0.97, 1.10), 0.0, 1.0)' },
+  { id: 'fresh', name: '日系清新', body: 'withSat(clamp(c * 1.06 + 0.035, 0.0, 1.0), 0.80) * vec3(0.97, 1.0, 1.05)' },
+  { id: 'sepia', name: '棕褐复古', body: 'mix(c, clamp(vec3(dot(c, vec3(0.393, 0.769, 0.189)), dot(c, vec3(0.349, 0.686, 0.168)), dot(c, vec3(0.272, 0.534, 0.131))), 0.0, 1.0), 0.85)' },
+  { id: 'tealorange', name: '青橙电影', body: 'c * mix(vec3(0.72, 1.06, 1.16), vec3(1.14, 0.97, 0.76), smoothstep(0.08, 0.92, dot(c, LUMA)))' },
+  { id: 'cyber', name: '赛博朋克', body: 'clamp(withSat((c - 0.5) * 1.18 + 0.5, 1.32) * mix(vec3(0.78, 1.08, 1.22), vec3(1.28, 0.82, 1.18), smoothstep(0.1, 0.9, dot(c, LUMA))), 0.0, 1.0)' },
+  { id: 'negative', name: '负片', body: '1.0 - c' },
+  { id: 'woodcut', name: '版画二值', body: 'vec3(step(0.52, dot(c, LUMA)))' },
+];
+
+/** 缺省滤镜 */
+export const DEFAULT_FILTER = 'original';
+
+/** 是否合法滤镜 id */
+export function hasFilter(id) {
+  return FILTER_PRESETS.some((p) => p.id === id);
+}
+
+/** 顶点着色器 */
+export const VERTEX_SHADER = `
+attribute vec4 a_position;
+attribute vec4 a_color;
+attribute vec4 a_color2;
+attribute vec2 a_texCoords;
+uniform mat4 u_projTrans;
+varying vec4 v_light;
+varying vec4 v_dark;
+varying vec2 v_texCoords;
+
+void main() {
+  v_light = a_color;
+  v_dark = a_color2;
+  v_texCoords = a_texCoords;
+  gl_Position = u_projTrans * a_position;
+}
+`;
+
+/** 片元着色器模板（__EFFECT_CHAIN__ 处填入预设表达式 + 插件效果链） */
+export const FRAGMENT_TEMPLATE = `
+#ifdef GL_ES
+  #define LOWP lowp
+  precision mediump float;
+#else
+  #define LOWP
+#endif
+varying LOWP vec4 v_light;
+varying LOWP vec4 v_dark;
+varying vec2 v_texCoords;
+uniform sampler2D u_texture;
+__EFFECT_GLOBALS__
+
+const vec3 LUMA = vec3(0.299, 0.587, 0.114);
+
+vec3 toGray(vec3 c) { return vec3(dot(c, LUMA)); }
+vec3 withSat(vec3 c, float s) { float l = dot(c, LUMA); return mix(vec3(l), c, s); }
+
+void main() {
+  vec4 texColor = texture2D(u_texture, v_texCoords);
+  float a = texColor.a * v_light.a;
+  vec3 pma = ((texColor.a - 1.0) * v_dark.a + 1.0 - texColor.rgb) * v_dark.rgb + texColor.rgb * v_light.rgb;
+  vec3 base = pma / max(a, 0.00001);
+  // 下面是"效果链占位行"：由 shaderSourceOf 注入预设表达式与插件效果链，产出 vec3 f。
+  // 注意：模板内注释不许出现占位符字样本身，也不许出现反引号（会终止模板字符串）。
+  __EFFECT_CHAIN__
+  gl_FragColor = vec4(f * a, a);
+}
+`;
+
+/** 取某预设的 vs/fs（未知 id 回落 original） */
+export function shaderSourceOf(id, effects) {
+  // 硬断言：两个注入位在模板里必须**恰好各 1 处**。
+  //   为什么需要：模板注释里若也写了这两个 token 字样，replace 只会命中最先出现的那一处
+  //   ⇒ 注入内容落进注释、真正的注入行留在原地 ⇒ GLSL 报 '{' / '=' 之类的语法错，
+  //   而从渲染层一路查下来完全看不出是"字符串拼接"问题（实测在这上面耗了几轮）。
+  //   断言能一次拦住，不用再靠肉眼数。
+  const countOf = (hay, token) => hay.split(token).length - 1;
+  const nGlobals = countOf(FRAGMENT_TEMPLATE, '__EFFECT_GLOBALS__');
+  const nChain = countOf(FRAGMENT_TEMPLATE, '__EFFECT_CHAIN__');
+  if (nGlobals !== 1 || nChain !== 1) {
+    throw new Error(`滤镜模板注入位数量异常：__EFFECT_GLOBALS__=${nGlobals}、__EFFECT_CHAIN__=${nChain}（各必须恰好 1 次）`);
+  }
+  const preset = FILTER_PRESETS.find((p) => p.id === id) || FILTER_PRESETS[0];
+  const chain = Array.isArray(effects) ? effects : [];
+  // 链的组装交给 effect-chain.js（与 Live2D 共用同一份语义），这里只负责
+  //   "把链塞进 Spine 的片元模板"—— 这是两条链路唯一该有的差异。
+  const body = buildChainBody({ presetBody: preset.body, effects: chain });
+  // 前置声明分两段（GLSL 作用域规则）：uniform 与函数定义进全局，局部变量进 main 内。
+  //   上一版把两段混在一起塞进 main ⇒ `S'u_texel' : syntax error`（实测编译失败）。
+  const pre = effectPrelude({ sampler: 'u_texture', texCoords: 'v_texCoords' });
+  const useChain = chain.length > 0;
+  const fs = FRAGMENT_TEMPLATE
+    // 用 replaceAll：占位符若在模板注释里再出现一次，replace 只会换第一处，
+    //   把注入内容吞进注释、真占位行残留 ⇒ 语法错（实测踩过）
+    .replaceAll('__EFFECT_GLOBALS__', () => (useChain ? `${pre.global}\n${uniformDeclarations(chain)}` : ''))
+    .replaceAll('__EFFECT_CHAIN__', () => (useChain ? `${pre.local}\n  ${body}` : body));
+  const uniforms = chainUniforms(chain);
+  // u_texel 必须有非零值：GLSL 未赋值的 uniform 默认 0 ⇒ texelSample(uv-0) 取回自己，
+  //   锐化类表达式退化成 c + k*(c-c) = c，看起来"开关没反应"（上一轮实测踩过）。
+  if (chain.length) uniforms.u_texel = [DEFAULT_TEXEL, DEFAULT_TEXEL];
+  return { vs: VERTEX_SHADER, fs, uniforms, signature: chainSignature(chain) };
+}
+
+/**
+ * 把滤镜着色器装上/还原。
+ * 关键约定：
+ *   · `savedDefaultBatcherShader` **只在第一次装滤镜时保存一次**，避免把"滤镜着色器"当成默认存进去；
+ *   · 编译失败 → warn 并保持原渲染（不置空、不抛）；
+ *   · 切回 original 时还原默认着色器并 dispose 滤镜着色器。
+ * @param {{renderer: object, gl: WebGLRenderingContext, ShaderCtor: Function,
+ *          filterId: string, saved: object|null, active: object|null}} ctx
+ * @returns {{saved: object|null, active: object|null, changed: boolean}}
+ */
+/**
+ * 给 shader 实例写 uniform 值。
+ *
+ * PixiJS 各版本挂点不同：v4 是 `shader.uniforms`，v5+ 是 `shader.uniformGroup.uniforms`。
+ * 写不上**不抛**：编译本身已经成功，值缺失最多是"效果强度为 0"，
+ *   不该被外层当成编译失败（实测：直接写 `shader.uniforms[key]` 在 v5 上抛
+ *   "Cannot set properties of undefined"，被 catch 吞成"编译失败"，
+ *   于是 active 永远为 null ⇒ 效果永远不生效，而日志看起来像着色器语法问题）。
+ * @param {object} shader
+ * @param {object} uniforms
+ * @param {Function} log
+ * @returns {boolean} 是否写成功
+ */
+function applyUniforms(shader, uniforms, log = () => {}) {
+  if (!shader || typeof shader.bind !== 'function') return false;
+  // spine-webgl 的 Shader（src/spine-runtimes/spine-webgl-*.js）**没有 uniforms 属性**，
+  //   值只能经 bind() + setUniformf / setUniform2f 下发；Pixi 的 uniformGroup/dirty 那套不适用。
+  //   gl.uniform* 只作用于当前 program，所以必须先 bind（batcherShader 自己也是这么用的）。
+  try {
+    shader.bind();
+    for (const [key, value] of Object.entries(uniforms || {})) {
+      // 未被表达式使用的 uniform 会被 GLSL 编译器优化掉，getUniformLocation 返回 null，
+      //   此时 gl.uniform*(null, v) 静默无效 —— 显式拦一下并留痕，免得"声明了却没生效"。
+      const loc = typeof shader.getUniformLocation === 'function' ? shader.getUniformLocation(key) : undefined;
+      if (loc === null) {
+        try { log('warn', `uniform ${key} 在着色器里未被使用（可能被优化掉），已跳过`, 'filter'); } catch { /* 忽略 */ }
+        continue;
+      }
+      if (Array.isArray(value) && value.length === 2) {
+        // vec2 必须用 setUniform2f：setUniformf 走 gl.uniform1f，给 vec2 会丢一半
+        if (typeof shader.setUniform2f === 'function') shader.setUniform2f(key, Number(value[0]), Number(value[1]));
+      } else if (typeof shader.setUniformf === 'function') {
+        shader.setUniformf(key, Number(value));
+      }
+    }
+    return true;
+  } catch (e) {
+    try { log('warn', `效果参数下发失败: ${e && e.message ? e.message : e}`, 'filter'); } catch { /* 忽略 */ }
+    return false;
+  }
+}
+
+export function reconcileFilter(ctx) {
+  const { renderer: r, gl, ShaderCtor, filterId, effects, state, log = () => {} } = ctx;
+  if (!r || !gl || !ShaderCtor || !('batcherShader' in r)) return { ...state, changed: false };
+  const chain = Array.isArray(effects) ? effects : [];
+  if (filterId === DEFAULT_FILTER && !chain.length) {
+    if (state.active) {
+      if (state.saved) r.batcherShader = state.saved;
+      try { state.active.dispose(); } catch { /* 释放失败不影响还原 */ }
+      return { saved: state.saved, active: null, changed: true, signature: '' };
+    }
+    // 链已空 ⇒ 签名就是空串（与 active 是否非 null 无关）。
+    //   这句漏了会出大问题：active 为 null（例如上一次编译失败从未挂上）时返回 {...state}
+    //   会把**旧签名**又带回去 ⇒ 上层以为链还在（实测：关掉档位后签名不回落）。
+    return { ...state, changed: false, signature: '' };
+  }
+  const saved = state.saved || r.batcherShader;
+  // 签名 = 预设 + 链上"结构"（效果增减 / 表达式变化）。**参数值不进签名** ——
+  //   参数变化只改 uniform，这是热更新的关键：签名一变就会重建着色器（黑帧抖动）。
+  const signature = `${filterId}|${chainSignature(chain)}`;
+  if (state.active && state.signature === signature) {
+    const { uniforms } = shaderSourceOf(filterId, chain);
+    applyUniforms(state.active, uniforms, log);
+    return { ...state, changed: false, signature };
+  }
+  const { vs, fs, uniforms } = shaderSourceOf(filterId, chain);
+  let shader = null;
+  try {
+    shader = new ShaderCtor(gl, vs, fs);
+    // 新实例的 uniform 要显式写一遍：模板只给了声明空间，值由宿主负责填
+    applyUniforms(shader, uniforms, log);
+  } catch (e) {
+    const detail = e && e.message ? e.message : String(e);
+    // 失败也要带 signature：上层用它区分"没有链"和"链挂了"。
+    //   漏了它 ⇒ filterState.signature 存成 '' ⇒ effectChainSignature() 恒空，
+    //   看起来像"链根本没建"（这就是上一轮卡住的地方）。
+    try { stageLog('warn', `滤镜着色器编译失败，保持原渲染: ${detail}`, { filterId, chainLen: chain.length }); } catch { /* 日志失败不影响还原 */ }
+    // 把替换后的片元前若干行打出来：要看的是 __EFFECT_CHAIN__ 到底替成了什么
+    try {
+      const head = String(fs).split('\n').slice(0, 24).join(' ⏎ ');
+      stageLog('info', `[滤镜 fs 片段] ${head}`, { filterId, signature });
+    } catch { /* 忽略 */ }
+    try { log('warn', `滤镜着色器编译失败，保持原渲染: ${detail}`, 'filter'); } catch { /* log 不是函数时别把异常传出去 */ }
+    return { saved, active: state.active, changed: false, signature };
+  }
+  const prev = state.active;
+  r.batcherShader = shader;
+  if (prev) { try { prev.dispose(); } catch { /* 忽略 */ } }
+  return { saved, active: shader, changed: true, signature };
+}

package/src/web/engine/fit.js

@@ -0,0 +1,197 @@
+// engine/fit.js —— 适配（fit）三模式：subject（默认）/ all / animation
+//
+// 三模式的判定规则：
+//   · NON_SUBJECT_RE 剔除背景/特效，CORE_RE 认主体，FIT_MAX_RATIO=1.15 限制"横向过宽"的包围盒；
+//   · subject 结果不可信时回落到整体包围盒；
+//   · animation 模式对每个动作采样若干帧取并集。
+// 版本差异（computeWorldVertices 的签名）用**参数个数 + 试调**探测，不读版本号。
+
+/** 背景/特效类部件（不参与主体适配） */
+export const NON_SUBJECT_RE = /(?:^|[_\s/.-])(backgrounds?|bgs?|backs?|effects?|effs?|efs?|fxs?|efxs?|vfx|particles?|auras?|glows?|halos?|debris|bursts?|shadows?|floors?|grounds?|lights?|(?:bg)|(?:fx)[0-9]*)(?:[_\s/.-]|$|[0-9])|sakura|petal|blossom|bgimage|bg-img|bg_img|(?:^|[/])ref[/]|背景|特效|光效|粒子|光晕|樱花|花瓣|碎片|阴影|地面/i;
+
+/** 主体类部件（优先级最高） */
+export const CORE_RE = /(chara|character|body|head|face|hair|arm|leg|skirt|cloth|pelvis|neck|hand|foot|torso|spine|chest|hip|bust|skin|sleeve|glove|shoe|socks|dress|coat|jacket|cape|wing|tail|horn|ear|eye|mouth|nose|身|头|脸|发|手|脚|腿|衣|裙|体|肤)/i;
+
+/** 横向相对高度的上限（超过就当作"背景太宽"，按高度收窄） */
+export const FIT_MAX_RATIO = 1.15;
+
+/** 支持的模式（与面板「初始缩放」三个按钮一一对应） */
+export const FIT_MODES = ['subject', 'all', 'animation'];
+
+/** 顶点数组 → 包围盒 */
+function boxOfPoints(points) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i + 1 < points.length; i += 2) {
+    const x = points[i];
+    const y = points[i + 1];
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  if (!Number.isFinite(minX) || maxX <= minX) return null;
+  return { minX, minY, maxX, maxY, w: maxX - minX, h: maxY - minY };
+}
+
+/**
+ * 取附件世界顶点包围盒（签名差异用"参数个数 + 试调"探测）。
+ * @param {object} skeleton
+ * @param {object} slot
+ * @returns {{minX: number, minY: number, maxX: number, maxY: number, w: number, h: number}|null}
+ */
+export function slotWorldBounds(skeleton, slot) {
+  const att = slot && slot.attachment;
+  if (!att) return null;
+  const len = att.worldVerticesLength;
+  if (typeof len === 'number' && typeof att.computeWorldVertices === 'function') {
+    const verts = new Float32Array(len);
+    const deepFirst = att.computeWorldVertices.length >= 6;
+    const narrow = () => att.computeWorldVertices(slot, 0, len, verts, 0, 2);
+    const deep = () => att.computeWorldVertices(skeleton, slot, 0, len, verts, 0, 2);
+    for (const run of (deepFirst ? [deep, narrow] : [narrow, deep])) {
+      try { run(); const box = boxOfPoints(verts); if (box) return box; } catch { /* 试下一种签名 */ }
+    }
+  }
+  // 回退：骨骼位置 + 附件宽高（region 类附件）
+  const bone = slot && slot.bone;
+  if (!bone) return null;
+  let sx = Math.abs(bone.scaleX || 1);
+  let sy = Math.abs(bone.scaleY || 1);
+  for (let p = bone.parent; p; p = p.parent) { sx *= Math.abs(p.scaleX || 1); sy *= Math.abs(p.scaleY || 1); }
+  const w = (att.width || 0) * sx;
+  const h = (att.height || 0) * sy;
+  if (!(w > 0) || !(h > 0)) return null;
+  const x = bone.worldX || 0;
+  const y = bone.worldY || 0;
+  return { minX: x - w / 2, maxX: x + w / 2, minY: y - h / 2, maxY: y + h / 2, w, h };
+}
+
+/**
+ * 主体包围盒（核心部件为准，剔除背景/特效，远离主体的碎片也剔除）。
+ * @param {{skeleton: object, skeletonData: object}} ctx
+ * @returns {{x: number, y: number, w: number, h: number}|null}
+ */
+export function computeSubjectBounds({ skeleton, skeletonData }) {
+  const order = (skeleton && skeleton.drawOrder) || [];
+  const items = [];
+  for (const slot of order) {
+    const box = slot && slot.attachment ? slotWorldBounds(skeleton, slot) : null;
+    if (!box) continue;
+    const slotName = String((slot.data && slot.data.name) || '');
+    const attName = String((slot.attachment && slot.attachment.name) || '');
+    const core = CORE_RE.test(slotName) || CORE_RE.test(attName);
+    const bg = (NON_SUBJECT_RE.test(slotName) || NON_SUBJECT_RE.test(attName)) && !core;
+    items.push({ box, bg, core });
+  }
+  if (!items.length) return null;
+  const ref = referenceSize(items, skeletonData);
+  const coreBox = unionCore(items);
+  const coreSignificant = !!coreBox && coreBox.w >= 0.12 * ref.w && coreBox.h >= 0.12 * ref.h;
+  const margin = coreSignificant ? Math.max(0.22 * ref.h, coreBox.h * 0.6) : 0;
+  return unionKeep(items, { coreBox, coreSignificant, margin, ref });
+}
+
+/** 参考尺寸：优先骨架数据自带，否则全部部件的范围 */
+function referenceSize(items, skeletonData) {
+  let w = skeletonData && skeletonData.width > 0 ? skeletonData.width : 0;
+  let h = skeletonData && skeletonData.height > 0 ? skeletonData.height : 0;
+  if (!(w > 0) || !(h > 0)) {
+    let minX = Infinity; let minY = Infinity; let maxX = -Infinity; let maxY = -Infinity;
+    for (const it of items) {
+      if (it.box.minX < minX) minX = it.box.minX;
+      if (it.box.minY < minY) minY = it.box.minY;
+      if (it.box.maxX > maxX) maxX = it.box.maxX;
+      if (it.box.maxY > maxY) maxY = it.box.maxY;
+    }
+    if (Number.isFinite(minX)) { w = maxX - minX; h = maxY - minY; }
+  }
+  return { w: w > 0 ? w : 1024, h: h > 0 ? h : 1024 };
+}
+
+/** 核心部件并集 */
+function unionCore(items) {
+  let minX = Infinity; let minY = Infinity; let maxX = -Infinity; let maxY = -Infinity;
+  for (const it of items) {
+    if (!it.core) continue;
+    if (it.box.minX < minX) minX = it.box.minX;
+    if (it.box.minY < minY) minY = it.box.minY;
+    if (it.box.maxX > maxX) maxX = it.box.maxX;
+    if (it.box.maxY > maxY) maxY = it.box.maxY;
+  }
+  if (minX === Infinity) return null;
+  return { minX, minY, maxX, maxY, w: maxX - minX, h: maxY - minY };
+}
+
+/** 合并：核心必留；非核心剔除背景与远离主体的碎片 */
+function unionKeep(items, { coreBox, coreSignificant, margin, ref }) {
+  let minX = Infinity; let minY = Infinity; let maxX = -Infinity; let maxY = -Infinity;
+  let count = 0;
+  for (const it of items) {
+    const b = it.box;
+    if (!it.core) {
+      if (it.bg) continue;
+      const tooWide = b.w > 1.3 * ref.w || b.h > 1.3 * ref.h;
+      const farAway = coreSignificant && (
+        b.maxX < coreBox.minX - margin || b.minX > coreBox.maxX + margin
+        || b.maxY < coreBox.minY - margin || b.minY > coreBox.maxY + margin
+      );
+      if (tooWide || farAway) continue;
+    }
+    if (b.minX < minX) minX = b.minX;
+    if (b.minY < minY) minY = b.minY;
+    if (b.maxX > maxX) maxX = b.maxX;
+    if (b.maxY > maxY) maxY = b.maxY;
+    count += 1;
+  }
+  if (!count || !Number.isFinite(minX)) return null;
+  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}
+
+/**
+ * 两个包围盒求交（subject 并集 ∩ 整体包围盒）。
+ * 为什么需要：并集可能因个别远端附件（如超大挂件）比整体还大，
+ *   实测的 subject 结果始终落在整体范围内；取交可剔除这类离群部件。
+ * @param {{x: number, y: number, w: number, h: number}} a
+ * @param {{x: number, y: number, w: number, h: number}} b
+ */
+export function intersectBox(a, b) {
+  if (!a) return b || null;
+  if (!b) return a;
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.w, b.x + b.w);
+  const bottom = Math.min(a.y + a.h, b.y + b.h);
+  if (!(right > x) || !(bottom > y)) return b;
+  return { x, y, w: right - x, h: bottom - y };
+}
+
+/** subject 结果的"横向对称收窄" */
+export function clampSubjectBox(box) {
+  if (!box) return null;
+  const symHalf = Math.max(Math.abs(box.x), Math.abs(box.x + box.w));
+  let w = 2 * symHalf;
+  const cap = FIT_MAX_RATIO * box.h;
+  if (w > cap) w = cap;
+  const center = box.x + box.w / 2;
+  const keepCenter = Math.abs(center) <= box.w * 0.04 ? 0 : center;
+  return { x: keepCenter - w / 2, y: box.y, w, h: box.h };
+}
+
+/**
+ * 计算视口适配参数（相机 zoom 语义：可见世界宽 = zoom × 视口宽）。
+ * @param {{bounds: {x: number, y: number, w: number, h: number}|null, viewW: number, viewH: number}} ctx
+ * @returns {{baseZoom: number, centerX: number, centerY: number}|null}
+ */
+export function computeFit({ bounds, viewW, viewH }) {
+  if (!bounds || !(viewW > 0) || !(viewH > 0) || !(bounds.w > 0) || !(bounds.h > 0)) return null;
+  const need = Math.max(bounds.w / viewW, bounds.h / viewH);
+  if (!Number.isFinite(need) || need <= 0) return null;
+  // ：baseZoom = max(宽比, 高比)，不再额外除以 (1-FIT_MARGIN)
+  const baseZoom = need;
+  if (!Number.isFinite(baseZoom) || baseZoom <= 0) return null;
+  return { baseZoom, centerX: bounds.x + bounds.w / 2, centerY: bounds.y + bounds.h / 2 };
+}

package/src/web/engine/frame-gate.js

@@ -0,0 +1,33 @@
+// engine/frame-gate.js —— 帧率门控（累加器口径，两面共用）。
+// 为什么不用 PIXI ticker.maxFPS / 单门限：前者按 deltaTime 判断且带容差（90Hz 屏会放行，实测 60/30 档跑到 90），
+//   后者只跟上一帧时间戳比，零头被丢掉导致长期偏低。累加器：够一格才渲，渲后只扣一格（余量留给下一次），
+//   并对 debt 做上限钳制（卡顿回来不连爆）。两面共用同一份实现，避免各自再写一套限帧逻辑。
+
+/**
+ * 造一个帧率门控。
+ * @param {() => number} getTargetFps 目标帧率（每次询问，支持运行期改档位）
+ * @returns {{shouldRender: (deltaMs: number) => boolean, reset: () => void, debtMs: number}}
+ */
+export function createFrameGate(getTargetFps) {
+  let debtMs = 0;
+  return {
+    /**
+     * 这一帧该不该渲染。
+     * @param {number} deltaMs 距上一次 rAF/ticker 的间隔（毫秒）
+     * @returns {boolean} true = 渲染；false = 跳过本帧（只更新状态不出画）
+     */
+    shouldRender(deltaMs) {
+      const target = Math.max(1, Number(getTargetFps()) || 60);
+      const interval = 1000 / target;
+      const d = Number(deltaMs);
+      if (Number.isFinite(d) && d > 0) debtMs += d;
+      if (debtMs < interval) return false;
+      debtMs -= interval;
+      if (debtMs > interval) debtMs = interval; // 防连爆：最多保留一格余量
+      return true;
+    },
+    /** 重置累加器（重新起循环/换 app 时用） */
+    reset() { debtMs = 0; },
+    get debtMs() { return debtMs; },
+  };
+}

package/src/web/engine/gl-driver.js

@@ -0,0 +1,56 @@
+// engine/gl-driver.js —— 上下文/尺寸/DPR 的驱动逻辑（从 player 拆出，控制单类规模）
+//
+// 这些方法只操作"引擎实例上的 GL 状态"，与装载/动画无关，放这里便于单独演进。
+
+import { createContext, effectiveDpr, applyPixelSize } from './gl.js';
+import * as cameraOps from './camera-adapter.js';
+
+/** 建上下文；失败返回 false（调用方据此判定环境不可渲染） */
+export function initEngine(engine, canvas, opts = {}) {
+  engine.canvas = canvas;
+  engine.antialias = opts.antialias === true;
+  const { gl, isSoftware, rendererStr } = createContext(canvas, { antialias: engine.antialias });
+  if (!gl) {
+    engine.log('error', '当前浏览器不支持 WebGL，无法渲染 Spine 动画。', 'renderer');
+    engine.mode = 'none';
+    return false;
+  }
+  engine.gl = gl;
+  engine.mode = 'webgl';
+  engine.isSoftware = isSoftware;
+  engine.rendererStr = rendererStr;
+  engine.logicalW = canvas.clientWidth || canvas.width;
+  engine.logicalH = canvas.clientHeight || canvas.height;
+  refreshResolution(engine);
+  engine.log('info', `WebGL 初始化成功 (canvas=${canvas.width}x${canvas.height}, css=${engine.logicalW}x${engine.logicalH})`, 'renderer');
+  return true;
+}
+
+/** 生效 DPR（auto：软件渲染钳 1、否则上限 2） */
+export function effectiveDprOf(engine, deviceDpr) {
+  return effectiveDpr(engine.dprMode, engine.isSoftware, deviceDpr);
+}
+
+/** 按逻辑尺寸 + DPR 重设 backing store */
+export function refreshResolution(engine) {
+  if (!engine.canvas) return;
+  if (engine.logicalW <= 0 || engine.logicalH <= 0) return;
+  const dpr = effectiveDprOf(engine, window.devicePixelRatio || 1);
+  applyPixelSize(engine.canvas, engine.gl, { logicalW: engine.logicalW, logicalH: engine.logicalH, dpr });
+  cameraOps.syncCamera(engine);
+}
+
+/** 纯尺寸更新（画布尺寸由外部改动后调用） */
+export function resizeEngine(engine, w, h) {
+  if (!engine.canvas) return;
+  engine.logicalW = w || engine.canvas.clientWidth;
+  engine.logicalH = h || engine.canvas.clientHeight;
+  refreshResolution(engine);
+}
+
+/** DPR 模式 */
+export function setDprMode(engine, mode) {
+  engine.dprMode = mode;
+  refreshResolution(engine);
+  requestAnimationFrame(() => refreshResolution(engine));
+}