@forgeax-extension/character-3d 0.1.2

package/marketplace-card.json

@@ -0,0 +1,56 @@
+{
+  "summary": {
+    "zh": "3D 角色生成工作台,接 Hunyuan3D、Meshy 等 provider 的一站式 3D 资产生成入口。支持文本生成 3D、图片生成 3D、多视图生成 3D,再做网格精修与 retopo 低模、自动绑骨与套用动作、质量评分,最后产出可持久化、游戏可直接用的 3D 资产 manifest。选 provider、给输入,剩下的从生成到绑骨一条龙。",
+    "en": "The 3D character generation editor — a one-stop entry to providers like Hunyuan3D and Meshy. It supports text-to-3D, image-to-3D and multi-view-to-3D, then mesh refine + lowpoly retopo, auto-rig + motion application, and quality scoring, finally producing durable, game-ready 3D asset manifests. Pick a provider, give input, and it carries through from generation to rigging."
+  },
+  "sections": [
+    {
+      "title": {
+        "zh": "生成管线",
+        "en": "Generation pipeline"
+      },
+      "body": {
+        "zh": "文本 / 图片 / 多视图 → 3D\n网格精修 + retopo 低模\n自动绑骨 + 套用动作 + 质量评分",
+        "en": "text / image / multi-view → 3D\nmesh refine + lowpoly retopo\nauto-rig + motion + quality scoring"
+      }
+    },
+    {
+      "title": {
+        "zh": "产出",
+        "en": "Outputs"
+      },
+      "body": {
+        "zh": "可持久化、游戏可用的 3D 资产 manifest",
+        "en": "Durable, game-ready 3D asset manifests"
+      }
+    },
+    {
+      "title": {
+        "zh": "怎么用",
+        "en": "How to use"
+      },
+      "body": {
+        "zh": "面板管理启用 → 选 provider + 输入开始生成",
+        "en": "Enable in Admin → pick a provider + input to generate"
+      }
+    }
+  ],
+  "history": [
+    {
+      "version": "0.1.0",
+      "date": "2026-06-10",
+      "notes": {
+        "zh": "首版:3D 角色生成入口",
+        "en": "First release: 3D character generation entry"
+      }
+    },
+    {
+      "version": null,
+      "date": "2026-06-24",
+      "notes": {
+        "zh": "3D turnaround 与流程完善",
+        "en": "3D turnaround + pipeline improvements"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "packageManager": "bun@1.3.14",
+  "name": "@forgeax-extension/character-3d",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "description": "ForgeaX extension for 3D character generation, rigging, motion, quality inspection, and playable export.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ForgeaXGame/forgeax-ex-character-3d.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "forgeax-extension.json",
+    "marketplace-card.json",
+    "schemas",
+    "server",
+    "shared",
+    "packages/external-asset-meta/src",
+    "packages/external-asset-meta/package.json",
+    "README.md",
+    "SOURCE_PROVENANCE.md",
+    "!server/**/*.test.ts"
+  ],
+  "scripts": {
+    "dev": "vite --host",
+    "build": "tsc && vite build && node scripts/release-scan-compat.mjs",
+    "typecheck": "tsc --noEmit",
+    "preview": "vite preview --port 15176",
+    "test": "bun test src server shared",
+    "smoke:real-gateway": "bun scripts/real-gateway-smoke.ts",
+    "check:release": "node scripts/check-release.mjs"
+  },
+  "dependencies": {
+    "cos-nodejs-sdk-v5": "^2.15.4",
+    "lucide-react": "^0.460.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": "^0.184.0",
+    "@forgeax-extension/external-asset-meta": "file:packages/external-asset-meta",
+    "@gltf-transform/core": "^4.4.0",
+    "@gltf-transform/extensions": "^4.4.0",
+    "@gltf-transform/functions": "^4.4.0",
+    "draco3dgltf": "^1.5.7"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/three": "^0.184.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "puppeteer-core": "24.9.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}

package/packages/external-asset-meta/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@forgeax-extension/external-asset-meta",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@gltf-transform/core": "^4.4.1",
+    "@gltf-transform/extensions": "^4.4.1",
+    "@gltf-transform/functions": "^4.4.1",
+    "draco3dgltf": "^1.5.7"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2"
+  }
+}

package/packages/external-asset-meta/src/cook.test.ts

@@ -0,0 +1,211 @@
+import { expect, test } from 'bun:test';
+import { createHash } from 'node:crypto';
+import { crc32, deflateSync } from 'node:zlib';
+import { Document, WebIO } from '@gltf-transform/core';
+import { cookExternalAssetFields, cookExternalAssetMeta } from './cook.ts';
+import type { ExternalAssetMeta } from './types.ts';
+
+async function buildGlb(meshCount: number): Promise<Uint8Array> {
+  const doc = new Document();
+  const buffer = doc.createBuffer();
+  const scene = doc.createScene();
+  for (let i = 0; i < meshCount; i += 1) {
+    const position = doc
+      .createAccessor()
+      .setType('VEC3')
+      .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+      .setBuffer(buffer);
+    const prim = doc.createPrimitive().setAttribute('POSITION', position);
+    const mesh = doc.createMesh(`mesh-${i}`).addPrimitive(prim);
+    scene.addChild(doc.createNode(`node-${i}`).setMesh(mesh));
+  }
+  return new WebIO().writeBinary(doc);
+}
+
+function oneByOnePng(): Uint8Array {
+  const chunk = (type: string, data: Buffer): Buffer => {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const typeBuf = Buffer.from(type, 'ascii');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])) >>> 0, 0);
+    return Buffer.concat([len, typeBuf, data, crc]);
+  };
+  const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const ihdr = chunk('IHDR', Buffer.from([0, 0, 0, 1, 0, 0, 0, 1, 8, 6, 0, 0, 0]));
+  const idat = chunk('IDAT', deflateSync(Buffer.from([0, 255, 0, 0, 255])));
+  const iend = chunk('IEND', Buffer.alloc(0));
+  return Buffer.concat([sig, ihdr, idat, iend]);
+}
+
+async function buildTexturedGlb(): Promise<Uint8Array> {
+  const doc = new Document();
+  const buffer = doc.createBuffer();
+  const scene = doc.createScene();
+  const position = doc
+    .createAccessor()
+    .setType('VEC3')
+    .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+    .setBuffer(buffer);
+  const tex = doc.createTexture('base-color').setImage(oneByOnePng()).setMimeType('image/png');
+  const material = doc.createMaterial('mat-0').setBaseColorTexture(tex);
+  const prim = doc.createPrimitive().setAttribute('POSITION', position).setMaterial(material);
+  const mesh = doc.createMesh('mesh-0').addPrimitive(prim);
+  scene.addChild(doc.createNode('node-0').setMesh(mesh));
+  return new WebIO().writeBinary(doc);
+}
+
+async function buildSkinnedAnimatedGlb(): Promise<Uint8Array> {
+  const doc = new Document();
+  const buffer = doc.createBuffer();
+  const scene = doc.createScene();
+  const position = doc
+    .createAccessor()
+    .setType('VEC3')
+    .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+    .setBuffer(buffer);
+  const joints = doc
+    .createAccessor()
+    .setType('VEC4')
+    .setArray(new Uint8Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]))
+    .setBuffer(buffer);
+  const weights = doc
+    .createAccessor()
+    .setType('VEC4')
+    .setArray(new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]))
+    .setBuffer(buffer);
+  const ibm = doc
+    .createAccessor()
+    .setType('MAT4')
+    .setArray(new Float32Array(16).map((_, i) => (i % 5 === 0 ? 1 : 0)))
+    .setBuffer(buffer);
+  const prim = doc
+    .createPrimitive()
+    .setAttribute('POSITION', position)
+    .setAttribute('JOINTS_0', joints)
+    .setAttribute('WEIGHTS_0', weights);
+  const mesh = doc.createMesh('skinned-mesh').addPrimitive(prim);
+  const joint = doc.createNode('Hips');
+  const skin = doc.createSkin('skin-0').addJoint(joint).setInverseBindMatrices(ibm);
+  const node = doc.createNode('skinned').setMesh(mesh).setSkin(skin);
+  scene.addChild(joint);
+  scene.addChild(node);
+
+  const input = doc
+    .createAccessor()
+    .setType('SCALAR')
+    .setArray(new Float32Array([0, 1]))
+    .setBuffer(buffer);
+  const output = doc
+    .createAccessor()
+    .setType('VEC3')
+    .setArray(new Float32Array([0, 0, 0, 0, 1, 0]))
+    .setBuffer(buffer);
+  const sampler = doc.createAnimationSampler().setInput(input).setOutput(output).setInterpolation('LINEAR');
+  const channel = doc.createAnimationChannel().setTargetNode(joint).setTargetPath('translation').setSampler(sampler);
+  doc.createAnimation('idle').addSampler(sampler).addChannel(channel);
+  const input2 = doc
+    .createAccessor()
+    .setType('SCALAR')
+    .setArray(new Float32Array([0, 1]))
+    .setBuffer(buffer);
+  const output2 = doc
+    .createAccessor()
+    .setType('VEC3')
+    .setArray(new Float32Array([0, 0, 0, 1, 0, 0]))
+    .setBuffer(buffer);
+  const sampler2 = doc.createAnimationSampler().setInput(input2).setOutput(output2).setInterpolation('LINEAR');
+  const channel2 = doc.createAnimationChannel().setTargetNode(joint).setTargetPath('translation').setSampler(sampler2);
+  doc.createAnimation('move').addSampler(sampler2).addChannel(channel2);
+
+  return new WebIO().writeBinary(doc);
+}
+
+function sha256Hex(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+test('single-mesh GLB → mesh + scene subAssets', async () => {
+  const glb = await buildGlb(1);
+  const contentHash = `sha256:${sha256Hex(glb)}`;
+  const meta = await cookExternalAssetFields(glb, contentHash, 'prop-test.glb');
+  expect(meta).not.toBeNull();
+  expect(meta!.kind).toBe('external-asset-package');
+  const byKind = Object.fromEntries(meta!.subAssets.map((s) => [s.kind, s]));
+  expect(Object.keys(byKind).sort()).toEqual(['mesh', 'scene']);
+});
+
+test('textured GLB → mesh + material + scene + texture', async () => {
+  const glb = await buildTexturedGlb();
+  const meta = await cookExternalAssetFields(glb, `sha256:${sha256Hex(glb)}`, 'prop-tex.glb');
+  const kinds = new Set(meta!.subAssets.map((s) => s.kind));
+  expect([...kinds].sort()).toEqual(['material', 'mesh', 'scene', 'texture']);
+});
+
+test('skinned+animated GLB → skeleton/skin/animation-clip', async () => {
+  const glb = await buildSkinnedAnimatedGlb();
+  const result = await cookExternalAssetMeta(glb, `sha256:${sha256Hex(glb)}`, 'hero.glb', {
+    animationSlotKeys: ['idle', 'move'],
+    slotGuidRegistry: { idle: '11111111-1111-1111-1111-111111111111' },
+  });
+  expect(result.ok).toBe(true);
+  if (!result.ok) return;
+  const kinds = result.meta.subAssets.map((s) => s.kind);
+  expect(kinds).toContain('skeleton');
+  expect(kinds).toContain('skin');
+  const clips = result.meta.subAssets.filter((s) => s.kind === 'animation-clip');
+  expect(clips.length).toBe(2);
+  expect(clips[0]!.guid).toBe('11111111-1111-1111-1111-111111111111');
+});
+
+test('existingMeta reuses GUID by (kind, sourceIndex)', async () => {
+  const glb = await buildGlb(1);
+  const hash = `sha256:${sha256Hex(glb)}`;
+  const first = await cookExternalAssetFields(glb, hash, 'prop.glb');
+  const existing: ExternalAssetMeta = {
+    ...first!,
+    subAssets: first!.subAssets.map((s) =>
+      s.kind === 'mesh' ? { ...s, guid: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } : s,
+    ),
+  };
+  const second = await cookExternalAssetMeta(glb, hash, 'prop.glb', { existingMeta: existing });
+  expect(second.ok).toBe(true);
+  if (!second.ok) return;
+  const mesh = second.meta.subAssets.find((s) => s.kind === 'mesh')!;
+  expect(mesh.guid).toBe('aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');
+});
+
+test('required Draco → engine_unsupported_extension', async () => {
+  const glb = await buildGlb(1);
+  // Patch JSON chunk to claim required Draco (without real compression).
+  const view = new DataView(glb.buffer, glb.byteOffset, glb.byteLength);
+  const jsonLen = view.getUint32(12, true);
+  const json = JSON.parse(new TextDecoder().decode(glb.subarray(20, 20 + jsonLen))) as Record<string, unknown>;
+  json.extensionsRequired = ['KHR_draco_mesh_compression'];
+  const jsonBytes = new TextEncoder().encode(JSON.stringify(json));
+  // Rebuild a minimal invalid-but-parseable GLB for extension check (cook fails before WebIO if required).
+  const out = new Uint8Array(20 + jsonBytes.length + 4);
+  out.set(glb.subarray(0, 12), 0);
+  new DataView(out.buffer).setUint32(12, jsonBytes.length, true);
+  new DataView(out.buffer).setUint32(16, 0x4e4f534a, true); // JSON
+  out.set(jsonBytes, 20);
+  const result = await cookExternalAssetMeta(out, 'sha256:dead', 'draco.glb');
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  expect(result.code).toBe('engine_unsupported_extension');
+});
+
+test('bad bytes → null via compat wrapper', async () => {
+  const meta = await cookExternalAssetFields(new Uint8Array([1, 2, 3]), 'sha256:bad', 'bad.glb');
+  expect(meta).toBeNull();
+});
+
+test('mesh GUID stays sha256(hash:sourceIndex)', async () => {
+  const glb = await buildGlb(1);
+  const bareHash = sha256Hex(glb);
+  const meta = await cookExternalAssetFields(glb, `sha256:${bareHash}`, 'prop-test.glb');
+  const mesh = meta!.subAssets.find((s) => s.kind === 'mesh')!;
+  const hex = createHash('sha256').update(`${bareHash}:0`).digest('hex');
+  const expected = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+  expect(mesh.guid).toBe(expected);
+});

package/packages/external-asset-meta/src/cook.ts

@@ -0,0 +1,188 @@
+// Shared engine external-asset-package cook (PLAN S1 / §5.1).
+// Mirrors forgeax-engine toAssetPack sub-asset kinds without depending on
+// @forgeax/engine-gltf (marketplace is outside the npm workspace).
+
+import { WebIO } from '@gltf-transform/core';
+import { createHash } from 'node:crypto';
+import {
+  ENGINE_REQUIRED_EXTENSION_ALLOWLIST,
+  type CookOptions,
+  type CookResult,
+  type ExternalAssetMeta,
+  type ExternalAssetSubAsset,
+} from './types.ts';
+
+function hexToUuid(hex: string): string {
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+function meshGuid(contentHash: string, sourceIndex: number): string {
+  const h = createHash('sha256').update(`${contentHash}:${sourceIndex}`).digest('hex');
+  return hexToUuid(h);
+}
+
+function subGuid(contentHash: string, kind: string, sourceIndex: number): string {
+  const h = createHash('sha256').update(`${contentHash}:${kind}:${sourceIndex}`).digest('hex');
+  return hexToUuid(h);
+}
+
+interface GlTFJson {
+  readonly meshes?: ReadonlyArray<{ readonly name?: string }>;
+  readonly materials?: ReadonlyArray<{ readonly name?: string }>;
+  readonly scenes?: ReadonlyArray<{ readonly name?: string }>;
+  readonly images?: ReadonlyArray<{ readonly name?: string }>;
+  readonly skins?: ReadonlyArray<{ readonly name?: string }>;
+  readonly animations?: ReadonlyArray<{ readonly name?: string }>;
+  readonly scene?: number;
+  readonly extensionsRequired?: ReadonlyArray<string>;
+  readonly extensionsUsed?: ReadonlyArray<string>;
+}
+
+function parseGlbJson(glbBytes: Uint8Array): GlTFJson | null {
+  if (glbBytes.length < 20) return null;
+  const view = new DataView(glbBytes.buffer, glbBytes.byteOffset, glbBytes.byteLength);
+  if (view.getUint32(0, true) !== 0x46546c67) return null;
+  const jsonLen = view.getUint32(12, true);
+  if (jsonLen <= 0 || 20 + jsonLen > glbBytes.length) return null;
+  const jsonText = new TextDecoder().decode(glbBytes.subarray(20, 20 + jsonLen));
+  try {
+    return JSON.parse(jsonText) as GlTFJson;
+  } catch {
+    return null;
+  }
+}
+
+function existingGuidMap(
+  existingMeta: ExternalAssetMeta | null | undefined,
+): Map<string, string> {
+  const map = new Map<string, string>();
+  if (!existingMeta || existingMeta.kind !== 'external-asset-package') return map;
+  for (const entry of existingMeta.subAssets) {
+    map.set(`${entry.kind}\0${entry.sourceIndex}`, entry.guid);
+  }
+  return map;
+}
+
+function resolveGuid(args: {
+  kind: string;
+  sourceIndex: number;
+  bareHash: string;
+  reuse: Map<string, string>;
+  slotKey?: string;
+  slotGuidRegistry?: Readonly<Record<string, string>>;
+}): string {
+  if (args.kind === 'animation-clip' && args.slotKey) {
+    const fromRegistry = args.slotGuidRegistry?.[args.slotKey];
+    if (fromRegistry) return fromRegistry;
+  }
+  const reused = args.reuse.get(`${args.kind}\0${args.sourceIndex}`);
+  if (reused) return reused;
+  if (args.kind === 'mesh') return meshGuid(args.bareHash, args.sourceIndex);
+  return subGuid(args.bareHash, args.kind, args.sourceIndex);
+}
+
+/**
+ * Cook a clean engine `external-asset-package` meta from GLB bytes.
+ * Returns structured success/failure (never throws on bad input).
+ */
+export async function cookExternalAssetMeta(
+  glbBytes: Uint8Array,
+  contentHash: string,
+  source: string,
+  options: CookOptions = {},
+): Promise<CookResult> {
+  const json = parseGlbJson(glbBytes);
+  if (json === null) {
+    return { ok: false, code: 'corrupt_glb', message: 'GLB header/JSON chunk is corrupt or not a GLB.' };
+  }
+
+  const required = json.extensionsRequired ?? [];
+  const allow = new Set<string>(ENGINE_REQUIRED_EXTENSION_ALLOWLIST);
+  const unsupported = required.filter((ext) => !allow.has(ext));
+  if (unsupported.length > 0) {
+    return {
+      ok: false,
+      code: 'engine_unsupported_extension',
+      message: `GLB requires unsupported extensions: ${unsupported.join(', ')}. Normalize/decode before cooking.`,
+      unsupportedExtensions: unsupported,
+    };
+  }
+
+  // Decode guard: structurally broken GLBs (and any remaining undecodable
+  // accessors) must not emit a fake-success meta.
+  try {
+    await new WebIO().readBinary(glbBytes);
+  } catch (err) {
+    return {
+      ok: false,
+      code: 'read_failed',
+      message: err instanceof Error ? err.message : 'WebIO.readBinary failed',
+    };
+  }
+
+  const meshes = json.meshes ?? [];
+  if (meshes.length === 0) {
+    return { ok: false, code: 'no_meshes', message: 'GLB has no meshes; engine external packages require ≥1 mesh.' };
+  }
+
+  const bareHash = contentHash.replace(/^sha256:/, '');
+  const reuse = existingGuidMap(options.existingMeta);
+  const subAssets: ExternalAssetSubAsset[] = [];
+
+  const push = (kind: string, sourceIndex: number, name: string | undefined, slotKey?: string) => {
+    subAssets.push({
+      guid: resolveGuid({
+        kind,
+        sourceIndex,
+        bareHash,
+        reuse,
+        slotKey,
+        slotGuidRegistry: options.slotGuidRegistry,
+      }),
+      sourceIndex,
+      kind,
+      ...(name ? { name } : {}),
+    });
+  };
+
+  meshes.forEach((mesh, i) => push('mesh', i, mesh.name));
+  (json.materials ?? []).forEach((m, i) => push('material', i, m.name));
+  (json.scenes ?? []).forEach((s, i) => push('scene', i, s.name));
+  // TEX1: textures only from images[], never sidecar PNG/JPG.
+  (json.images ?? []).forEach((img, i) => push('texture', i, img.name));
+  // Engine emits skeleton + skin 1:1 from each glTF skin (parse-gltf.ts).
+  (json.skins ?? []).forEach((skin, i) => {
+    push('skeleton', i, skin.name);
+    push('skin', i, skin.name);
+  });
+  (json.animations ?? []).forEach((anim, i) => {
+    const slotKey = options.animationSlotKeys?.[i];
+    push('animation-clip', i, anim.name ?? slotKey, slotKey);
+  });
+
+  return {
+    ok: true,
+    meta: {
+      schemaVersion: 1,
+      kind: 'external-asset-package',
+      importer: 'gltf',
+      source,
+      importSettings: { defaultSceneIndex: json.scene ?? 0 },
+      subAssets,
+    },
+  };
+}
+
+/**
+ * Backward-compatible wrapper used by existing ai-asset call sites.
+ * Maps structured failure → null (callers skip writing engine meta).
+ */
+export async function cookExternalAssetFields(
+  glbBytes: Uint8Array,
+  contentHash: string,
+  source: string,
+  options: CookOptions = {},
+): Promise<ExternalAssetMeta | null> {
+  const result = await cookExternalAssetMeta(glbBytes, contentHash, source, options);
+  return result.ok ? result.meta : null;
+}

package/packages/external-asset-meta/src/draco3dgltf.d.ts

@@ -0,0 +1,11 @@
+declare module 'draco3dgltf' {
+  interface DracoModule {
+    // Opaque WASM module handle consumed by @gltf-transform/extensions.
+  }
+  interface Draco3dGltf {
+    createDecoderModule(): Promise<DracoModule>;
+    createEncoderModule(): Promise<DracoModule>;
+  }
+  const draco3d: Draco3dGltf;
+  export default draco3d;
+}

package/packages/external-asset-meta/src/index.ts

@@ -0,0 +1,18 @@
+/// <reference path="./draco3dgltf.d.ts" />
+export {
+  ENGINE_REQUIRED_EXTENSION_ALLOWLIST,
+  type CookErrorCode,
+  type CookFailure,
+  type CookOptions,
+  type CookResult,
+  type CookSuccess,
+  type ExternalAssetMeta,
+  type ExternalAssetSubAsset,
+  type NormalizeErrorCode,
+  type NormalizeFailure,
+  type NormalizeResult,
+  type NormalizeSuccess,
+} from './types.ts';
+
+export { cookExternalAssetFields, cookExternalAssetMeta } from './cook.ts';
+export { normalizeGlbForEngine } from './normalize.ts';

package/packages/external-asset-meta/src/normalize.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'bun:test';
+import { Document, WebIO } from '@gltf-transform/core';
+import { normalizeGlbForEngine } from './normalize.ts';
+import { cookExternalAssetMeta } from './cook.ts';
+import { createHash } from 'node:crypto';
+
+async function buildPlainGlb(): Promise<Uint8Array> {
+  const doc = new Document();
+  const buffer = doc.createBuffer();
+  const scene = doc.createScene();
+  const position = doc
+    .createAccessor()
+    .setType('VEC3')
+    .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))
+    .setBuffer(buffer);
+  const prim = doc.createPrimitive().setAttribute('POSITION', position);
+  scene.addChild(doc.createNode('n').setMesh(doc.createMesh('m').addPrimitive(prim)));
+  return new WebIO().writeBinary(doc);
+}
+
+test('normalize plain GLB succeeds and remains cookable', async () => {
+  const glb = await buildPlainGlb();
+  const result = await normalizeGlbForEngine(glb);
+  expect(result.ok).toBe(true);
+  if (!result.ok) return;
+  const hash = `sha256:${createHash('sha256').update(result.bytes).digest('hex')}`;
+  const cooked = await cookExternalAssetMeta(result.bytes, hash, 'plain.glb');
+  expect(cooked.ok).toBe(true);
+});
+
+test('normalize corrupt bytes fails structured', async () => {
+  const result = await normalizeGlbForEngine(new Uint8Array([0, 1, 2, 3]));
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  expect(result.code).toBe('corrupt_glb');
+});