@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/assetLibrary/seedPosesQbx.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=seedPosesQbx.test.d.ts.map

package/dist/assetLibrary/seedPosesQbx.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seedPosesQbx.test.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/seedPosesQbx.test.ts"],"names":[],"mappings":""}

package/dist/assetLibrary/seedPosesQbx.test.js

@@ -0,0 +1,181 @@
+// packages/camera-studio/src/assetLibrary/seedPosesQbx.test.ts
+/**
+ * QBX 手势种子数据的不变量(2026-10-05 拇指偏差根治):
+ * 手势方向必须是「手腕相对」的——源包(QBX)的模型手臂下垂,若按世界方向
+ * 提取,会把手臂姿态烤进手势,应用到 T 姿势骨架上时手指相对手腕错位
+ * (拇指最显眼)。本测试把 seedPosesQbx 应用到 Y Bot rest,量每根手指骨
+ * 方向(用手腕世界四元数换算回手腕系),与管线 JSON 逐骨比对。
+ * JSON 必须是 v2(space='wrist');v1(世界方向)数据会在这里红。
+ */
+import fs from 'fs';
+import path from 'path';
+import { FBXLoader } from 'three-stdlib';
+import { Quaternion, Vector3 } from 'three';
+import { seedPosesQbx } from './seedPosesQbx';
+const pkgRoot = path.resolve(__dirname, '../..');
+const DOC_PATH = path.join(pkgRoot, 'scripts/pose-pipeline/poses_directions_qbx.json');
+const FBX_PATH = path.join(pkgRoot, 'scripts/pose-pipeline/models/Y Bot.fbx');
+function loadRest() {
+    const buf = fs.readFileSync(FBX_PATH);
+    const root = new FBXLoader().parse(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength), '');
+    const rest = new Map();
+    root.traverse((o) => {
+        const bone = o;
+        if (!bone.isBone || rest.has(bone.name))
+            return;
+        const p = bone.parent;
+        rest.set(bone.name, {
+            parent: p && p.isBone && p.name && rest.has(p.name) ? p.name : null,
+            localQuat: [
+                o.quaternion.x,
+                o.quaternion.y,
+                o.quaternion.z,
+                o.quaternion.w,
+            ],
+        });
+    });
+    return rest;
+}
+const doc = JSON.parse(fs.readFileSync(DOC_PATH, 'utf-8'));
+test('管线 JSON 是 v2 手腕相对格式(v1 世界方向会把手臂姿态烤进手势)', () => {
+    expect(doc.format).toBe('pose-directions-v2');
+    expect(doc.space).toBe('wrist');
+});
+test('条目按侧裁骨:名字带侧的只含本侧骨(挂错侧「没效果」的回归)', () => {
+    // 2026-10-05 用户报告:右手选择框里有两个「反手 V」,一个没效果。
+    // 根因:源包 Peace Flipped 的 action 名没带侧(实际是左手姿势),提取
+    // 时双手骨都收,运行时「无侧后缀=双手手势」两侧都列,挂到右手只写
+    // 了 rest 骨。修复=提取按侧裁骨+补侧名。这里兜底:名单侧 ⇔ 骨单侧
+    for (const e of seedPosesQbx) {
+        const sides = new Set(Object.keys(e.bones).map((b) => b.startsWith('mixamorigLeft') ? 'left' : 'right'));
+        if (e.name.endsWith('· 左手')) {
+            expect([...sides]).toEqual(['left']);
+        }
+        else if (e.name.endsWith('· 右手')) {
+            expect([...sides]).toEqual(['right']);
+        }
+    }
+    // 当事条目:裸 key 的反手 V 实为左手,名字与骨都必须标左
+    const bare = seedPosesQbx.find((e) => e.key === 'qbx-hands-03-signs-peace-flipped');
+    expect(bare.name).toContain('左手');
+    expect(Object.keys(bare.bones).every((b) => b.startsWith('mixamorigLeft'))).toBe(true);
+    // 侧标在名字中间的 Gun 03 也要各归各侧
+    for (const [key, side] of [
+        ['qbx-hands-04-weapons-gun-03-l-cock-the-hammer', '左手'],
+        ['qbx-hands-04-weapons-gun-03-r-cock-the-hammer', '右手'],
+    ]) {
+        expect(seedPosesQbx.find((e) => e.key === key).name).toContain(side);
+    }
+});
+test('左右成对手势的手指弯曲度互为镜像(源包漏帧/左右搞混的回归)', () => {
+    // 2026-10-05 三轮:FU R / Peace Flipped R 源 action 的右小指三节没 key
+    // (恒等于 rest),提取时已按左手镜像补齐。判镜像用「骨节链夹角」
+    // (相邻两节方向的夹角):标量、镜像不变,不受手腕朝向/滚转影响。
+    // 成对姿势若同源,各指链夹角必须相等;index 对有 8.4° 自然手绘误差,
+    // 阈值放 15°
+    const chain = (dirs, side, f, seg) => {
+        const a = dirs[`mixamorig${side}Hand${f}${seg}`];
+        const b = dirs[`mixamorig${side}Hand${f}${seg + 1}`];
+        const dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+        return (Math.acos(Math.min(1, Math.max(-1, dot))) * 180) / Math.PI;
+    };
+    const pairBase = (key) => key === 'qbx-hands-03-signs-peace-flipped'
+        ? key
+        : key.replace(/-[lr]$/, '').replace(/-[lr]-/, '-?-');
+    const lefts = new Map();
+    const rights = new Map();
+    for (const p of doc.poses) {
+        const isLeft = Object.keys(p.dirs)[0]?.startsWith('mixamorigLeft');
+        (isLeft ? lefts : rights).set(pairBase(p.key), p);
+    }
+    let pairs = 0;
+    for (const [base, l] of lefts) {
+        const r = rights.get(base);
+        if (!r)
+            throw new Error(`${l.key} 没有右手对子`);
+        pairs++;
+        for (const f of ['Thumb', 'Index', 'Middle', 'Ring', 'Pinky']) {
+            for (const seg of [1, 2]) {
+                const d = Math.abs(chain(l.dirs, 'Left', f, seg) - chain(r.dirs, 'Right', f, seg));
+                if (d > 15)
+                    throw new Error(`${base} ${f}${seg}↔${seg + 1} 左右弯曲度差 ${d.toFixed(1)}°`);
+            }
+        }
+    }
+    expect(pairs).toBe(55);
+});
+test('手势应用后与源姿势解剖关系一致(平掌≈T 手,握拳蜷曲)', () => {
+    const rest = loadRest();
+    // rest 世界四元数(插入序即先序,父先于子)
+    const restWorldQ = new Map();
+    for (const [name, info] of rest) {
+        const local = new Quaternion(...info.localQuat);
+        const parentQ = info.parent
+            ? restWorldQ.get(info.parent)
+            : new Quaternion();
+        restWorldQ.set(name, parentQ.clone().multiply(local));
+    }
+    const restDir = (bone) => new Vector3(0, 1, 0).applyQuaternion(restWorldQ.get(bone)).normalize();
+    const angleOf = (key, bone) => {
+        const entry = seedPosesQbx.find((e) => e.key === key);
+        if (!entry)
+            throw new Error(`种子缺 ${key}`);
+        const worldQ = new Map();
+        for (const [name, info] of rest) {
+            const local = new Quaternion(...(entry.bones[name]?.rotation ?? info.localQuat));
+            const parentQ = info.parent ? worldQ.get(info.parent) : new Quaternion();
+            worldQ.set(name, parentQ.clone().multiply(local));
+        }
+        const applied = new Vector3(0, 1, 0)
+            .applyQuaternion(worldQ.get(bone))
+            .normalize();
+        return ((Math.acos(Math.min(1, Math.max(-1, applied.dot(restDir(bone))))) * 180) /
+            Math.PI);
+    };
+    const FINGERS = ['Thumb', 'Index', 'Middle', 'Ring', 'Pinky'].flatMap((f) => [1, 2, 3].map((i) => `${f}${i}`));
+    // 平掌(stop):四指全伸 ≈ T 姿势,应与 rest 方向齐平(v1 世界方向数据
+    // 这里偏 50°+,naive 手腕系差 90°);拇指在 stop 里是侧向伸出的,与
+    // T 姿势放松拇指本就不同(源预览图可见),不应对齐——断言外展 >40°
+    for (const [side, s] of [
+        ['Left', 'l'],
+        ['Right', 'r'],
+    ]) {
+        for (const f of FINGERS) {
+            if (f.startsWith('Thumb'))
+                continue;
+            const a = angleOf(`qbx-hands-03-signs-stop-${s}`, `mixamorig${side}Hand${f}`);
+            if (a > 12)
+                throw new Error(`stop ${side} ${f} 与 rest 差 ${a.toFixed(1)}°`);
+        }
+        const thumb = angleOf(`qbx-hands-03-signs-stop-${s}`, `mixamorig${side}HandThumb1`);
+        if (thumb < 40)
+            throw new Error(`stop ${side} Thumb1 应外展,实测仅 ${thumb.toFixed(1)}°`);
+    }
+    // 放松(base):四指自然微蜷,相对 rest 小角度;绝不是 50° 级错位
+    for (const [side, s] of [
+        ['Left', 'l'],
+        ['Right', 'r'],
+    ]) {
+        for (const f of FINGERS) {
+            if (f.startsWith('Thumb'))
+                continue;
+            const a = angleOf(`qbx-hands-01-base-base-${s}`, `mixamorig${side}Hand${f}`);
+            if (a > 25)
+                throw new Error(`base ${side} ${f} 与 rest 差 ${a.toFixed(1)}°`);
+        }
+    }
+    // 握拳(fist):四指近节蜷 ≥40°、中末节 ≥100°
+    for (const [side, s] of [
+        ['Left', 'l'],
+        ['Right', 'r'],
+    ]) {
+        for (const f of ['Index', 'Middle', 'Ring', 'Pinky']) {
+            const a1 = angleOf(`qbx-hands-02-other-fist-${s}`, `mixamorig${side}Hand${f}1`);
+            if (a1 < 40)
+                throw new Error(`fist ${side} ${f}1 只蜷了 ${a1.toFixed(1)}°`);
+            const a2 = angleOf(`qbx-hands-02-other-fist-${s}`, `mixamorig${side}Hand${f}2`);
+            if (a2 < 100)
+                throw new Error(`fist ${side} ${f}2 只蜷了 ${a2.toFixed(1)}°`);
+        }
+    }
+});

package/dist/assetLibrary/source.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 统一数据源(2026-10-10 spec §5):模型/姿势/动画数据完全由应用提供的
+ * 存储承担;模块附带的基础资产也走同一接口——一个接口、三种实现
+ * (内置目录 / 宿主生产存储 / 本地 IndexedDB 演示),零特判。
+ */
+import type { EntryKind, LibraryEntry, RigAlias } from './types';
+export type LibraryErrorCode = 'auth' | 'quota' | 'network' | 'conflict' | 'not-found' | 'unknown';
+export declare class LibraryError extends Error {
+    readonly code: LibraryErrorCode;
+    readonly cause?: unknown;
+    constructor(code: LibraryErrorCode, message: string, cause?: unknown);
+}
+/** 源能力自描述(供 capabilities 查询;可写判别以 putEntry 存在性为准) */
+export type LibrarySourceCapabilities = {
+    writable?: boolean;
+    permanentUrls?: boolean;
+    maxUploadBytes?: number;
+};
+/** 统一数据源(读) */
+export interface LibrarySource {
+    readonly id: string;
+    listEntries(kind?: EntryKind): Promise<LibraryEntry[]>;
+    getEntry(id: string): Promise<LibraryEntry | undefined>;
+    /** 每个源自己解析自己的 blob:静态源→CDN 地址,HTTP 源→预签名,IDB→blob: */
+    getBlobUrl(blobId: string): Promise<string>;
+    capabilities?: LibrarySourceCapabilities;
+    /** 远端变更推送(可选,v1 不强制) */
+    subscribe?(fn: () => void): () => void;
+}
+/** 可写源 = 用户库(宿主生产存储 / 内置 IDB) */
+export interface WritableLibrarySource extends LibrarySource {
+    putEntry(entry: LibraryEntry): Promise<void>;
+    deleteEntry(id: string): Promise<void>;
+    putBlob(data: Blob, opts?: {
+        onProgress?: (ratio: number) => void;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    deleteBlob(blobId: string): Promise<void>;
+    getRigAliases(): Promise<RigAlias[]>;
+    putRigAlias(alias: RigAlias): Promise<void>;
+    /** 孤儿清扫用;HTTP 源不实现则跳过清扫 */
+    listBlobIds?(): Promise<string[]>;
+}
+export declare function isWritableSource(s: LibrarySource): s is WritableLibrarySource;
+//# sourceMappingURL=source.d.ts.map

package/dist/assetLibrary/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAC,MAAM,SAAS,CAAA;AAE9D,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,OAAO,GACP,SAAS,GACT,UAAU,GACV,WAAW,GACX,SAAS,CAAA;AAEb,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB;IAE/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,gBAAgB,EAC/B,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO;CAK3B;AAED,qDAAqD;AACrD,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAe;AACf,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAA;IACvD,sDAAsD;IACtD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3C,YAAY,CAAC,EAAE,yBAAyB,CAAA;IACxC,wBAAwB;IACxB,SAAS,CAAC,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CACvC;AAED,iCAAiC;AACjC,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,OAAO,CACL,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE;QAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAC,GAClE,OAAO,CAAC,MAAM,CAAC,CAAA;IAClB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,aAAa,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpC,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,2BAA2B;IAC3B,WAAW,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAClC;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,IAAI,qBAAqB,CAE7E"}

package/dist/assetLibrary/source.js

@@ -0,0 +1,11 @@
+export class LibraryError extends Error {
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'LibraryError';
+    }
+}
+export function isWritableSource(s) {
+    return typeof s.putEntry === 'function';
+}

package/dist/assetLibrary/source.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source.test.d.ts.map

package/dist/assetLibrary/source.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.test.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/source.test.ts"],"names":[],"mappings":""}

package/dist/assetLibrary/source.test.js

@@ -0,0 +1,28 @@
+import { LibraryError, isWritableSource } from './source';
+test('LibraryError 携带 code 与 cause', () => {
+    const cause = new Error('boom');
+    const err = new LibraryError('quota', '配额已满', cause);
+    expect(err.code).toBe('quota');
+    expect(err.cause).toBe(cause);
+    expect(err instanceof Error).toBe(true);
+});
+test('isWritableSource:有 putEntry 才判定可写', () => {
+    const ro = {
+        id: 'ro',
+        listEntries: async () => [],
+        getEntry: async () => undefined,
+        getBlobUrl: async () => '',
+    };
+    const rw = {
+        ...ro,
+        id: 'rw',
+        putEntry: async () => { },
+        deleteEntry: async () => { },
+        putBlob: async () => 'x',
+        deleteBlob: async () => { },
+        getRigAliases: async () => [],
+        putRigAlias: async () => { },
+    };
+    expect(isWritableSource(ro)).toBe(false);
+    expect(isWritableSource(rw)).toBe(true);
+});

package/dist/assetLibrary/staticCatalogSource.d.ts

@@ -0,0 +1,48 @@
+import type { LibrarySource } from './source';
+import type { SeedAssetsManifest } from './seedAssetsManifest';
+import type { EntryKind, LibraryEntry, ModelEntry, PoseEntry } from './types';
+/** 运行时缩略图渲染器:返回可用 URL(blob:/data:),渲染不了返回 undefined */
+export type CatalogThumbRenderer<E extends LibraryEntry> = (entry: E) => Promise<string | undefined>;
+export type StaticCatalogSourceOpts = {
+    /** 资产文件根(以 / 结尾);缺省惰性取包内 assets/ */
+    baseUrl?: string;
+    /** 缺省 = 入库的 seedAssetsManifest(测试可注入缩窄版) */
+    manifest?: SeedAssetsManifest;
+    /**
+     * 预留:宿主自定义取数(代理/鉴权 CDN)时用。源自身不发起网络——
+     * 静态文件纯拼 URL 交给 <img>/GLTFLoader 直接取,运行时缩略图由
+     * 注入的渲染器自行取数;当前实现不读取此字段。
+     */
+    fetcher?: typeof fetch;
+    renderPoseThumb?: CatalogThumbRenderer<PoseEntry>;
+    renderModelThumb?: CatalogThumbRenderer<ModelEntry>;
+};
+export declare class StaticCatalogSource implements LibrarySource {
+    readonly id = "catalog";
+    readonly capabilities: {
+        readonly writable: false;
+        readonly permanentUrls: true;
+    };
+    private readonly manifest;
+    private readonly renderPoseThumb?;
+    private readonly renderModelThumb?;
+    private readonly optsBaseUrl?;
+    private resolvedBaseUrl?;
+    private entriesById?;
+    /** 运行时缩略图 URL 缓存:渲染是 WebGL 离屏,同一 blobId 只渲染一次 */
+    private runtimeUrlCache;
+    constructor(opts?: StaticCatalogSourceOpts);
+    private baseUrl;
+    private buildEntries;
+    private entries;
+    listEntries(kind?: EntryKind): Promise<LibraryEntry[]>;
+    getEntry(id: string): Promise<LibraryEntry | undefined>;
+    /**
+     * blob 路由:静态文件纯拼 baseUrl(不探测可达性——配错由加载方
+     * 包 LibraryError('network') 上告,见 PlacementManager);运行时
+     * 缩略图调注入渲染器,结果按 blobId 内存缓存(不落地)。
+     */
+    getBlobUrl(blobId: string): Promise<string>;
+    private cachedRuntime;
+}
+//# sourceMappingURL=staticCatalogSource.d.ts.map

package/dist/assetLibrary/staticCatalogSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticCatalogSource.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/staticCatalogSource.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAG3C,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAC,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAC,MAAM,SAAS,CAAA;AAE3E,uDAAuD;AACvD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,YAAY,IAAI,CACzD,KAAK,EAAE,CAAC,KACL,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAEhC,MAAM,MAAM,uBAAuB,GAAG;IACpC,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;IACtB,eAAe,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAA;IACjD,gBAAgB,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAA;CACpD,CAAA;AAaD,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,EAAE,aAAY;IACvB,QAAQ,CAAC,YAAY;;;MAAkD;IAEvE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAiC;IAClE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAkC;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAQ;IACrC,OAAO,CAAC,eAAe,CAAC,CAAQ;IAChC,OAAO,CAAC,WAAW,CAAC,CAA2B;IAC/C,iDAAiD;IACjD,OAAO,CAAC,eAAe,CAAqC;gBAEhD,IAAI,GAAE,uBAA4B;IAO9C,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,OAAO;IAIT,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAKtD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAI7D;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0CjD,OAAO,CAAC,aAAa;CAoBtB"}

package/dist/assetLibrary/staticCatalogSource.js

@@ -0,0 +1,140 @@
+// packages/camera-studio/src/assetLibrary/staticCatalogSource.ts
+/**
+ * 内置资产目录源(2026-10-10 内置资产目录化):随包发布的模型 GLB 与
+ * 姿势预览图,以只读 LibrarySource 形式并入聚合器——与宿主生产存储、
+ * 本地 IndexedDB 同一接口,零特判。
+ *
+ * - 条目来自入库清单(seedAssetsManifest,脚本生成)+ 姿势数据模块;
+ *   内置模型 id = seed-model-<contentHash>,姿势 id 保持 seed-pose-* 不变。
+ * - blobId 全部带 `catalog:` 前缀,聚合器按前缀路由回本源:
+ *     catalog:models/<file>        → baseUrl 静态文件(纯拼接,不探测)
+ *     catalog:poseThumbs/<file>    → 同上(QBX 手势源包预览图)
+ *     catalog:runtime/model/<key>  → 注入的 renderModelThumb(内存缓存)
+ *     catalog:runtime/pose/<id>    → 注入的 renderPoseThumb(内存缓存)
+ * - baseUrl 缺省惰性解析到包内 assets/(jest 不碰:测试一律显式注入)。
+ */
+import { LibraryError } from './source';
+import { buildBuiltinPoseEntries, builtinPoseRig } from './seedBuiltinPoses';
+import { seedAssetsManifest } from './seedAssetsManifest';
+const PREFIX = 'catalog:';
+/**
+ * 包内 assets/ 的缺省根:src/assetLibrary/ 与 dist/assetLibrary/ 同层深,
+ * 两种形态都指到包根 assets/。必须惰性调用——import.meta.url 在 jest
+ * (CJS 变换)下不可用,模块加载期求值会让整条 import 链崩掉。
+ */
+function defaultBaseUrl() {
+    return new URL('../../assets/', import.meta.url).href;
+}
+export class StaticCatalogSource {
+    constructor(opts = {}) {
+        this.id = 'catalog';
+        this.capabilities = { writable: false, permanentUrls: true };
+        /** 运行时缩略图 URL 缓存:渲染是 WebGL 离屏,同一 blobId 只渲染一次 */
+        this.runtimeUrlCache = new Map();
+        this.manifest = opts.manifest ?? seedAssetsManifest;
+        this.renderPoseThumb = opts.renderPoseThumb;
+        this.renderModelThumb = opts.renderModelThumb;
+        this.optsBaseUrl = opts.baseUrl;
+    }
+    baseUrl() {
+        if (!this.resolvedBaseUrl) {
+            const raw = this.optsBaseUrl ?? defaultBaseUrl();
+            this.resolvedBaseUrl = raw.endsWith('/') ? raw : raw + '/';
+        }
+        return this.resolvedBaseUrl;
+    }
+    buildEntries() {
+        const byId = new Map();
+        const thumbFileByKey = new Map(this.manifest.poseThumbs.map((t) => [t.key, t.file]));
+        for (const m of this.manifest.models) {
+            const entry = {
+                id: `seed-model-${m.contentHash}`,
+                kind: 'model',
+                name: m.name,
+                rig: m.rig,
+                blobId: `${PREFIX}models/${m.file}`,
+                contentHash: m.contentHash,
+                thumbnailId: `${PREFIX}runtime/model/${m.key}`,
+                boneCount: m.boneCount,
+                vertexCount: m.vertexCount,
+                // 内置条目 createdAt 恒 0:目录内容静态,固定值保证 id/排序稳定
+                createdAt: 0,
+            };
+            byId.set(entry.id, entry);
+        }
+        for (const p of buildBuiltinPoseEntries(builtinPoseRig(this.manifest))) {
+            const key = p.id.slice('seed-pose-'.length);
+            const thumbFile = thumbFileByKey.get(key);
+            byId.set(p.id, {
+                ...p,
+                thumbnailId: thumbFile
+                    ? `${PREFIX}poseThumbs/${thumbFile}`
+                    : `${PREFIX}runtime/pose/${p.id}`,
+            });
+        }
+        return byId;
+    }
+    entries() {
+        return (this.entriesById ?? (this.entriesById = this.buildEntries()));
+    }
+    async listEntries(kind) {
+        const all = [...this.entries().values()];
+        return kind ? all.filter((e) => e.kind === kind) : all;
+    }
+    async getEntry(id) {
+        return this.entries().get(id);
+    }
+    /**
+     * blob 路由:静态文件纯拼 baseUrl(不探测可达性——配错由加载方
+     * 包 LibraryError('network') 上告,见 PlacementManager);运行时
+     * 缩略图调注入渲染器,结果按 blobId 内存缓存(不落地)。
+     */
+    async getBlobUrl(blobId) {
+        if (!blobId.startsWith(PREFIX)) {
+            throw new LibraryError('not-found', `非内置目录 blob:${blobId}`);
+        }
+        const rest = blobId.slice(PREFIX.length);
+        if (rest.startsWith('models/') || rest.startsWith('poseThumbs/')) {
+            // 逐段编码:文件名可含空格('Y Bot.glb'),目录段不动
+            return this.baseUrl() + rest.split('/').map(encodeURIComponent).join('/');
+        }
+        if (rest.startsWith('runtime/model/')) {
+            const key = rest.slice('runtime/model/'.length);
+            // key 对上清单条目才认(渲染器按条目渲染,不认裸 key)
+            const asset = this.manifest.models.find((m) => m.key === key);
+            const entry = asset
+                ? this.entries().get(`seed-model-${asset.contentHash}`)
+                : undefined;
+            if (!this.renderModelThumb || !entry || entry.kind !== 'model') {
+                throw new LibraryError('not-found', `模型缩略图不可用(缺渲染器或未知条目):${blobId}`);
+            }
+            return this.cachedRuntime(blobId, () => this.renderModelThumb(entry));
+        }
+        if (rest.startsWith('runtime/pose/')) {
+            const id = rest.slice('runtime/pose/'.length);
+            const entry = this.entries().get(id);
+            if (!this.renderPoseThumb || !entry || entry.kind !== 'pose') {
+                throw new LibraryError('not-found', `姿势缩略图不可用(缺渲染器或未知条目):${blobId}`);
+            }
+            return this.cachedRuntime(blobId, () => this.renderPoseThumb(entry));
+        }
+        throw new LibraryError('not-found', `未知内置目录 blob:${blobId}`);
+    }
+    cachedRuntime(blobId, render) {
+        let cached = this.runtimeUrlCache.get(blobId);
+        if (!cached) {
+            cached = render().then((url) => {
+                if (!url) {
+                    // 渲染不可用(GL 缺失等):不缓存,下次重试;按 not-found 降级
+                    this.runtimeUrlCache.delete(blobId);
+                    throw new LibraryError('not-found', `缩略图渲染不可用:${blobId}`);
+                }
+                return url;
+            });
+            this.runtimeUrlCache.set(blobId, cached);
+            // 注入渲染器自身抛错也不缓存(瞬时故障可重试)
+            cached.catch(() => this.runtimeUrlCache.delete(blobId));
+        }
+        return cached;
+    }
+}

package/dist/assetLibrary/staticCatalogSource.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=staticCatalogSource.test.d.ts.map

package/dist/assetLibrary/staticCatalogSource.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticCatalogSource.test.d.ts","sourceRoot":"","sources":["../../src/assetLibrary/staticCatalogSource.test.ts"],"names":[],"mappings":""}

package/dist/assetLibrary/staticCatalogSource.test.js

@@ -0,0 +1,154 @@
+/**
+ * StaticCatalogSource(内置资产目录源)契约:
+ * - 条目来自入库清单 + 姿势数据模块,数量一律数据驱动(不写死);
+ * - 内置模型 id = seed-model-<contentHash>,姿势 id 保持 seed-pose-*;
+ * - blobId 全部带 catalog: 前缀,聚合器按前缀路由回本源;
+ * - 静态文件(models/poseThumbs)纯拼接 baseUrl 不探测;
+ * - 运行时缩略图(模型/身体姿势)走注入渲染器,内存缓存,缺注入抛 not-found;
+ * - 清单 rig 与运行时 FBX 解析同一判定(parity 兜底)。
+ */
+import fs from 'fs';
+import path from 'path';
+import { FBXLoader } from 'three-stdlib';
+import { WebIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import draco3dgltf from 'draco3dgltf';
+import { LibraryError } from './source';
+import { StaticCatalogSource } from './staticCatalogSource';
+import { buildBuiltinPoseEntries } from './seedBuiltinPoses';
+import { seedAssetsManifest } from './seedAssetsManifest';
+import { seedPoses } from './seedPoses';
+import { seedPosesDpl } from './seedPosesDpl';
+import { seedPosesQbx } from './seedPosesQbx';
+import { collectBoneNames, rigIdOf } from './rig';
+import { Library } from './library';
+import { loadLibraryModel } from '../PlacementManager';
+const BASE = 'https://cdn.example.com/a/';
+describe('StaticCatalogSource', () => {
+    test('目录源:条目齐全,id 前缀与 blobId 路由正确', async () => {
+        const src = new StaticCatalogSource({ baseUrl: BASE });
+        const models = (await src.listEntries('model'));
+        const poses = (await src.listEntries('pose'));
+        // 数据驱动计数:清单与姿势数据模块是唯一事实源
+        expect(models).toHaveLength(seedAssetsManifest.models.length);
+        expect(poses).toHaveLength(buildBuiltinPoseEntries().length);
+        expect(poses).toHaveLength(seedPoses.length + seedPosesDpl.length + seedPosesQbx.length);
+        expect(models.every((m) => m.id.startsWith('seed-model-'))).toBe(true);
+        expect(poses.every((p) => p.id.startsWith('seed-pose-'))).toBe(true);
+        // 模型 blobId 带 catalog: 前缀,聚合器按前缀路由;URL 纯拼接
+        expect(models.every((m) => m.blobId.startsWith('catalog:models/'))).toBe(true);
+        const url = await src.getBlobUrl(models[0].blobId);
+        expect(url.startsWith(`${BASE}models/`)).toBe(true);
+        // getEntry 按 id 直查
+        expect(await src.getEntry(models[0].id)).toMatchObject({ id: models[0].id });
+        expect(await src.getEntry('seed-pose-nope')).toBeUndefined();
+        // 不分 kind 时全量返回
+        expect(await src.listEntries()).toHaveLength(models.length + poses.length);
+        // 只读目录:不可写,URL 长效可跨挂载缓存
+        expect(src.capabilities).toMatchObject({
+            writable: false,
+            permanentUrls: true,
+        });
+    });
+    test('QBX 预览图走静态文件;身体姿势缩略图走注入渲染器(内存缓存,不落地)', async () => {
+        const renderPoseThumb = jest.fn(async () => 'data:image/png;base64,x');
+        const src = new StaticCatalogSource({
+            baseUrl: BASE,
+            renderPoseThumb,
+        });
+        const poses = (await src.listEntries('pose'));
+        // QBX 子集 = 手势数据模块全量,且每个 key 都命中清单预览图
+        const qbx = poses.filter((p) => p.id.startsWith('seed-pose-qbx-'));
+        expect(qbx).toHaveLength(seedPosesQbx.length);
+        expect(qbx.every((p) => p.thumbnailId?.startsWith('catalog:poseThumbs/'))).toBe(true);
+        const qbx0 = poses.find((p) => p.id === 'seed-pose-qbx-hands-01-base-base-l');
+        expect(await src.getBlobUrl(qbx0.thumbnailId)).toContain(`${BASE}poseThumbs/`);
+        // 非 QBX(身体姿势):thumbnailId 走运行时渲染,渲染结果内存缓存
+        const dpl = poses.find((p) => !p.id.startsWith('seed-pose-qbx-'));
+        expect(dpl.thumbnailId).toBe(`catalog:runtime/pose/${dpl.id}`);
+        const t1 = await src.getBlobUrl(dpl.thumbnailId);
+        const t2 = await src.getBlobUrl(dpl.thumbnailId);
+        expect(t1).toBe('data:image/png;base64,x');
+        expect(renderPoseThumb).toHaveBeenCalledTimes(1); // 内存缓存
+        expect(t2).toBe(t1);
+    });
+    test('模型缩略图走 renderModelThumb 注入;缺注入抛 LibraryError(not-found)', async () => {
+        const renderModelThumb = jest.fn(async () => 'blob:model-thumb');
+        const src = new StaticCatalogSource({ baseUrl: BASE, renderModelThumb });
+        const [model] = (await src.listEntries('model'));
+        // thumbnailId = catalog:runtime/model/<key>,key 来自清单
+        const key = seedAssetsManifest.models[0].key;
+        expect(model.thumbnailId).toBe(`catalog:runtime/model/${key}`);
+        expect(await src.getBlobUrl(model.thumbnailId)).toBe('blob:model-thumb');
+        expect(renderModelThumb).toHaveBeenCalledTimes(1);
+        const bare = new StaticCatalogSource({ baseUrl: BASE });
+        await expect(bare.getBlobUrl(model.thumbnailId)).rejects.toThrow(LibraryError);
+        await expect(bare.getBlobUrl(model.thumbnailId)).rejects.toMatchObject({
+            code: 'not-found',
+        });
+        // 未知 blobId / 非本目录前缀同样 not-found
+        await expect(bare.getBlobUrl('catalog:bogus/x')).rejects.toMatchObject({
+            code: 'not-found',
+        });
+    });
+    test('清单 rig 与运行时解析一致(FBXLoader + rigIdOf 同一函数)', async () => {
+        // 清单 rig 来自生成脚本对 FBX 的 rigIdOf;这里独立重算一遍兜底
+        const fbxPath = path.resolve(__dirname, '../../scripts/pose-pipeline/models/Y Bot.fbx');
+        const buf = fs.readFileSync(fbxPath);
+        const root = new FBXLoader().parse(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength), '');
+        const manifestModel = seedAssetsManifest.models.find((m) => m.name === 'Y Bot');
+        expect(manifestModel.rig).toBe(rigIdOf(root));
+        expect(manifestModel.boneCount).toBe(collectBoneNames(root).length);
+        // GLB 产物完整性:skins joints 名是 FBX 骨名子集(转换丢骨/改名回归)。
+        // WebIO.readBinary 在 jest 可用(draco.test.ts 先例);NodeIO 的
+        // 动态 import fs 会被 jest 拦,不用
+        const glb = fs.readFileSync(path.resolve(__dirname, '../../assets/models', manifestModel.file));
+        const io = new WebIO()
+            .registerExtensions(ALL_EXTENSIONS)
+            .registerDependencies({
+            'draco3d.decoder': await draco3dgltf.createDecoderModule(),
+        });
+        const doc = await io.readBinary(new Uint8Array(glb));
+        const fbxNames = new Set(collectBoneNames(root));
+        const joints = new Set();
+        for (const skin of doc.getRoot().listSkins()) {
+            for (const j of skin.listJoints())
+                joints.add(j.getName());
+        }
+        expect(joints.size).toBeGreaterThan(0);
+        expect([...joints].every((n) => fbxNames.has(n))).toBe(true);
+    });
+    test('姿势条目 rig 与清单族代表模型一致(用户导入同款模型才能匹配)', async () => {
+        const src = new StaticCatalogSource({ baseUrl: BASE });
+        const rig = seedAssetsManifest.models.find((m) => m.name === 'Y Bot').rig;
+        const poses = await src.listEntries('pose');
+        expect(poses.every((p) => p.rig === rig)).toBe(true);
+    });
+    test('baseUrl 配错:GLB 加载失败走 LibraryError(network),选择框数据照常', async () => {
+        const src = new StaticCatalogSource({ baseUrl: 'https://bad.example/' });
+        // getBlobUrl 纯拼接不探测:
+        expect(await src.getBlobUrl('catalog:models/x.glb')).toContain('bad.example');
+        // 选择框数据照常:条目列表与 baseUrl 可达性无关
+        const errors = [];
+        const lib = new Library({
+            sources: [src],
+            onError: (e) => errors.push(e),
+        });
+        const models = await lib.listEntries('model');
+        expect(models).toHaveLength(seedAssetsManifest.models.length);
+        // PlacementManager 加载失败 → LibraryError network(fetcher stub 驱动)
+        const origFetch = globalThis.fetch;
+        globalThis.fetch = (async () => {
+            throw new Error('ENOTFOUND bad.example');
+        });
+        try {
+            await expect(loadLibraryModel(models[0].id, lib)).rejects.toMatchObject({
+                code: 'network',
+            });
+        }
+        finally {
+            globalThis.fetch = origFetch;
+        }
+        expect(errors.some((e) => e.code === 'network')).toBe(true);
+    });
+});