@forgeax-extension/character-3d 0.1.2

package/shared/catalog.ts

@@ -0,0 +1,307 @@
+// Provider capability catalog + ProviderResult contract.
+//
+// catalog = static, source-derived planning data (which provider/mode is safe
+// to expose). It is NOT a benchmark/scoring runtime — provider-comparison
+// conclusions live in docs only (ADR-0001). Pure data + pure functions; no
+// filesystem, no network. Persistence orchestration lives in server/.
+
+export type Exposure = 'planned' | 'mock-first' | 'experimental' | 'hidden' | 'blocked';
+
+import type {
+  FileFormat,
+  FileRole,
+  GenerationMode,
+  ProviderId,
+} from './manifest';
+
+export interface ProviderCapability {
+  providerId: ProviderId;
+  providerName: string;
+  capability: string;
+  sourceStatus: string;
+  exposure: Exposure;
+  notes: string;
+}
+
+export type PromptCategory = 'character' | 'prop' | 'scene';
+
+// ProviderResult — the pure output of a provider adapter. A provider knows
+// nothing about cache or asset-store (ADR-0001 decoupling). It returns the bytes
+// (already downloaded from any provider URL) plus role/format so the handler can
+// persist them. `sourceJobId` is audit-only, never a stored asset reference.
+export interface ProviderResultFile {
+  role: FileRole;
+  format: FileFormat;
+  data: Uint8Array;
+}
+
+export interface MeshyTaskRefs {
+  /** Text preview (white mesh) task id — only valid input to refine. */
+  previewTaskId: string | null;
+  /** Final usable mesh task id (refine after auto-texture, else the single submit). */
+  resultTaskId: string | null;
+}
+
+/** VISVISE COS URLs from generate/rig. Downstream tools must reuse these. */
+export interface VisviseRefs {
+  meshUrl: string | null;
+  rigUrl: string | null;
+}
+
+export interface ProviderResult {
+  provider: ProviderId;
+  mode: GenerationMode;
+  providerMode: 'mock' | 'real';
+  sourceJobId: string | null;
+  prompt: string | null;
+  files: ProviderResultFile[];
+  /** Meshy-only preview/result task pair (absent for other providers). */
+  meshyTaskRefs?: MeshyTaskRefs;
+  /** VISVISE-only generate/rig COS URLs (absent for other providers). */
+  visviseRefs?: VisviseRefs;
+}
+
+export interface MeshyTextMockArgs {
+  prompt: string;
+  promptCategory?: PromptCategory;
+  enablePbr?: boolean;
+  targetPolycount?: number;
+}
+
+export const QUALITY_RUBRIC = [
+  'geometry',
+  'topology',
+  'texture',
+  'pbr',
+  'prompt_fidelity',
+] as const;
+
+export const CAPABILITIES: readonly ProviderCapability[] = [
+  {
+    providerId: 'meshy',
+    providerName: 'Meshy',
+    capability: 'text / text-to-3D preview',
+    sourceStatus: 'Implemented in lab',
+    exposure: 'mock-first',
+    notes: 'Good M2/M3 candidate. Preserve cache-first behavior before enabling real calls.',
+  },
+  {
+    providerId: 'meshy',
+    providerName: 'Meshy',
+    capability: 'image / image-to-3D',
+    sourceStatus: 'Implemented in lab',
+    exposure: 'planned',
+    notes: 'Requires image input handling and artifact display.',
+  },
+  {
+    providerId: 'meshy',
+    providerName: 'Meshy',
+    capability: 'views / multi-image-to-3D',
+    sourceStatus: 'Implemented in lab',
+    exposure: 'planned',
+    notes: 'Meshy accepts image URL arrays rather than Hunyuan named view slots.',
+  },
+  {
+    providerId: 'meshy',
+    providerName: 'Meshy',
+    capability: 'refine',
+    sourceStatus: 'Implemented in lab',
+    exposure: 'planned',
+    notes: 'Meshy-only second stage; keep provider-specific.',
+  },
+  {
+    providerId: 'hunyuan_workflow',
+    providerName: 'Hunyuan workflow',
+    capability: 'text',
+    sourceStatus: 'Verified main mode',
+    exposure: 'planned',
+    notes: 'Use hunyuan-3d-v3.1-text2gen-wf with async submit and poll.',
+  },
+  {
+    providerId: 'hunyuan_workflow',
+    providerName: 'Hunyuan workflow',
+    capability: 'image',
+    sourceStatus: 'Verified main mode',
+    exposure: 'planned',
+    notes: 'Use hunyuan-3d-v3.1-image2gen-wf with async submit and poll.',
+  },
+  {
+    providerId: 'hunyuan_workflow',
+    providerName: 'Hunyuan workflow',
+    capability: 'views',
+    sourceStatus: 'Verified main mode',
+    exposure: 'planned',
+    notes: 'Use hunyuan-3d-v3.1-views2gen-wf and Hunyuan named view slots.',
+  },
+  {
+    providerId: 'hunyuan_workflow',
+    providerName: 'Hunyuan workflow',
+    capability: 'geometry and world workflow modes',
+    sourceStatus: 'Endpoint reachable, field sanity incomplete',
+    exposure: 'hidden',
+    notes: 'Keep out of UI and schemas until output shape is verified.',
+  },
+  {
+    providerId: 'hunyuan_rest',
+    providerName: 'Hunyuan REST',
+    capability: 'pose_standardization',
+    sourceStatus: 'Implemented + live-verified 2026-06-10',
+    exposure: 'mock-first',
+    notes:
+      'Tool gen3d:pose-standardization. Synchronous REST; image to A/T-pose standardization (upstream preprocessing, persists a blob, no manifest). Real call confirmed ~20s. Falls back to mock when GEN3D_ENABLE_REAL_PROVIDERS≠1.',
+  },
+  {
+    providerId: 'hunyuan_rest',
+    providerName: 'Hunyuan REST',
+    capability: 'low_poly',
+    sourceStatus: 'Contract from internal PDF; not live-tested in gen3d',
+    exposure: 'planned',
+    notes:
+      'M13-1 gen3d:retopo-lowpoly. Async submit/poll (hunyuan-3d-low-poly-v1.5). High-poly source retained by default (2026-06-12). Gate 0 verifies Hunyuan can fetch public COS model URLs.',
+  },
+  {
+    providerId: 'hunyuan_rest',
+    providerName: 'Hunyuan REST',
+    capability: 'motion_retarget v1',
+    sourceStatus: 'Verified end-to-end in lab',
+    exposure: 'planned',
+    notes:
+      'M13-3 gen3d:apply-motion. int motion types 9-16 (跨步/摔倒/跳跃/踢腿/挥击/步行/跑步/跳舞, decided 2026-06-12). Input = rigged humanoid FBX (role=rigged_model).',
+  },
+  {
+    providerId: 'hunyuan_rest',
+    providerName: 'Hunyuan REST',
+    capability: 'auto_rigging',
+    sourceStatus: 'Endpoint reachable, not fully verified',
+    exposure: 'experimental',
+    notes: 'M13-2 gen3d:auto-rig. Gate 1 verifies end-to-end output before default AI exposure.',
+  },
+  {
+    providerId: 'hunyuan_rest',
+    providerName: 'Hunyuan REST',
+    capability: 'motion_retarget_v2',
+    sourceStatus: 'Blocked by unknown literal list',
+    exposure: 'blocked',
+    notes: 'Endpoint may return 200 while falling back to default motion.',
+  },
+  {
+    providerId: 'rodin',
+    providerName: 'Rodin',
+    capability: 'text / text-to-3D',
+    sourceStatus: 'On LiteLLM as rodin-3d (2026-08-14 C1). getRodinEnv uses the shared 3D key. Old Hyper3D rodin.ts is unused.',
+    exposure: 'mock-first',
+    notes: 'Gateway POST /v1/3d/generations model=rodin-3d, body {prompt}. Do not read RODIN_API_KEY.',
+  },
+  {
+    providerId: 'rodin',
+    providerName: 'Rodin',
+    capability: 'image / image-to-3D',
+    sourceStatus: 'On LiteLLM as rodin-3d (2026-08-14 C1).',
+    exposure: 'mock-first',
+    notes: 'Gateway body {image_url} or {image_urls}. Static GLB only — no Rodin pose/rig.',
+  },
+  {
+    providerId: 'rodin',
+    providerName: 'Rodin',
+    capability: 'views / multi-image-to-3D',
+    sourceStatus: 'Same LiteLLM rodin-3d as image; body {image_urls} (2–5).',
+    exposure: 'mock-first',
+    notes: 'views-to-3d sends front/back/left/right as image_urls. First image is used for material. No separate views model.',
+  },
+  {
+    providerId: 'visvise',
+    providerName: 'VISVISE',
+    capability: 'text / image to 3D + pose + rig + text/video motion',
+    sourceStatus: 'On LiteLLM 2026-08-14 (visvise-3d / mid / low / image-pose / rigging / text-motion / video-motion).',
+    exposure: 'mock-first',
+    notes:
+      'Do not invent algorithm_model. visvise-3d-mid is image-only. input_model_url for pose/rig/motion. No views model. Skinning not chained unless live proves needed.',
+  },
+];
+
+export function clampTargetPolycount(value: number): number {
+  if (!Number.isFinite(value)) return 30000;
+  return Math.min(300000, Math.max(1000, Math.round(value)));
+}
+
+// Cache key = stable hash of (provider, mode, normalized inputs). Mirrors the
+// lab's "provider-mode + sorted non-empty payload" dedup (see ADR-0001 Cache).
+export function makeCacheKey(
+  provider: ProviderId,
+  mode: GenerationMode,
+  payload: Record<string, string | number | boolean>,
+): string {
+  const normalized = Object.keys(payload)
+    .filter((key) => payload[key] !== '' && payload[key] !== undefined)
+    .sort()
+    .map((key) => `${key}:${String(payload[key])}`)
+    .join('|');
+  return `${provider}-${mode}-${fnv1a(`${provider}|${mode}|${normalized}`)}`;
+}
+
+// Deterministic no-quota Meshy text mock. Produces a ProviderResult with a small
+// placeholder GLB byte buffer + a preview image so the handler can exercise the
+// full persistence path (blob → manifest) without any remote call.
+export function generateMeshyTextMockResult(args: MeshyTextMockArgs): {
+  cacheKey: string;
+  result: ProviderResult;
+} {
+  const prompt = args.prompt.trim();
+  if (!prompt) {
+    throw Object.assign(new Error('prompt is required'), { code: 'invalid_prompt' });
+  }
+  const promptCategory = args.promptCategory ?? 'prop';
+  const enablePbr = args.enablePbr ?? true;
+  const targetPolycount = clampTargetPolycount(args.targetPolycount ?? 30000);
+  const cacheKey = makeCacheKey('meshy', 'text', {
+    prompt,
+    promptCategory,
+    enablePbr,
+    targetPolycount,
+  });
+
+  return {
+    cacheKey,
+    result: {
+      provider: 'meshy',
+      mode: 'text',
+      providerMode: 'mock',
+      sourceJobId: `mock-${cacheKey}`,
+      prompt,
+      files: [
+        { role: 'source_mesh', format: 'glb', data: mockGlbBytes(cacheKey) },
+        { role: 'preview_image', format: 'png', data: MOCK_PNG_BYTES },
+      ],
+    },
+  };
+}
+
+// Minimal valid-ish GLB header (magic "glTF" + version 2) padded with a
+// deterministic tail. Not a renderable model — a stand-in byte payload so the
+// store/manifest path runs end-to-end without a provider call.
+function mockGlbBytes(seed: string): Uint8Array {
+  const header = new Uint8Array([0x67, 0x6c, 0x54, 0x46, 0x02, 0x00, 0x00, 0x00]);
+  const tail = new TextEncoder().encode(`mock-glb:${seed}`);
+  const out = new Uint8Array(header.length + tail.length);
+  out.set(header, 0);
+  out.set(tail, header.length);
+  return out;
+}
+
+// 1x1 transparent PNG.
+const MOCK_PNG_BYTES = Uint8Array.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+  0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4,
+  0x89, 0x00, 0x00, 0x00, 0x0a, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x00, 0x01, 0x00, 0x00,
+  0x05, 0x00, 0x01, 0x0d, 0x0a, 0x2d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae,
+  0x42, 0x60, 0x82,
+]);
+
+function fnv1a(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}

package/shared/manifest.ts

@@ -0,0 +1,378 @@
+// Gen3DAssetManifest — the durable handoff contract between gen3d and
+// downstream modules (wb-3d-pipeline, game generation). See docs/adr/0002 and
+// CONTEXT.md. M9: an Asset is a per-game file, keyed by its game-relative path
+// (`assetPath`, e.g. assets/3d/characters/hero.glb), NOT a random UUID. The main
+// GLB is the identity; same-basename sidefiles (preview PNG, external texture)
+// are dependencies. Downstream modules reference assets by assetPath, never by
+// provider URL.
+
+import type { CharacterMotionOverride, MotionMappingDraft } from './playable-profile';
+
+export type ProviderId = 'meshy' | 'hunyuan_workflow' | 'hunyuan_rest' | 'rodin' | 'visvise';
+
+export type GenerationMode = 'text' | 'image' | 'views' | 'refine';
+
+// Provider mode tag. `mock` marks no-quota deterministic fixtures so a manifest
+// produced without a real call is never mistaken for a real generation.
+export type ProviderMode = 'mock' | 'real';
+
+export type AssetKind = 'mesh' | 'animation';
+
+// Where the asset lands in the game's 3D asset tree. The value maps 1:1 to a
+// directory under assets/3d/ (see ADR-0002 / 03-WORKSPACE-LAYOUT.md).
+export type AssetSlot = 'characters' | 'meshes';
+
+export const ASSET_SLOT_DIRS: Record<AssetSlot, string> = {
+  characters: 'characters',
+  meshes: 'meshes',
+};
+
+// Durable file roles. source_mesh/preview_image/texture come from generation;
+// rigged_model/animation_clip/animated_model are appended by wb-3d-pipeline.
+export type FileRole =
+  | 'source_mesh'
+  | 'rigged_model'
+  | 'preview_image'
+  | 'texture'
+  | 'animation_clip'
+  | 'animated_model';
+
+export type FileFormat = 'glb' | 'fbx' | 'obj' | 'mtl' | 'usdz' | 'stl' | 'png' | 'jpg' | 'webp' | 'mp4';
+
+export type SkeletonProfile = 'humanoid' | 'unknown';
+
+// Motion type for animated_model files. Hunyuan motion_retarget v1 fixed motions
+// are ints 9–16 (跨步/摔倒/跳跃/踢腿/挥击/步行/跑步/跳舞; see ADR-0003 §③). Stored
+// structurally so idempotency / enumeration / downstream selection never parse
+// file names. Kept as the hunyuan_v1 subset of MotionRef + a legacy on-disk
+// field (older sidecars wrote a bare `motionType`; sidecarToManifest upgrades it).
+export type MotionType = 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16;
+
+// Which animation "system" produced a clip. Public beta uses Meshy; Hunyuan v1
+// (8 fixed motions) stays for internal/dev; hunyuan_v2 is reserved for the
+// 48-motion B-line once it unblocks (ADR-0006 §Decision 3 / PLAN §8-Q2,Q7).
+export type MotionSystem = 'hunyuan_v1' | 'hunyuan_v2' | 'meshy' | 'visvise';
+
+// Generalized, structural motion descriptor (ADR-0006, Q2 = option 1). One
+// discriminated union subsumes all three systems and is designed once so adding
+// hunyuan_v2 later does not touch the contract. Stored MINIMALLY as
+// {system,id,label}; rich metadata (category / preview gif / rigType / isFree)
+// is resolved on demand from the P2 motion catalog by (system,id), never
+// persisted (PLAN §3-1). The idempotency key is `${system}:${id}`.
+export type MotionRef =
+  | { system: 'hunyuan_v1'; id: MotionType; label: string }
+  | { system: 'hunyuan_v2'; id: string; label: string }
+  | { system: 'meshy'; id: number; label: string }
+  | { system: 'visvise'; id: string; label: string };
+
+// Stable dedup / idempotency key for a motion across systems.
+export function motionRefKey(ref: MotionRef): string {
+  return `${ref.system}:${ref.id}`;
+}
+
+// Canonical labels for the 8 Hunyuan v1 motions (跨步/摔倒/…). Kept here (not in
+// the UI) so the server can build a MotionRef label and upgrade legacy sidecars.
+export const HUNYUAN_V1_MOTION_LABELS: Record<MotionType, string> = {
+  9: '跨步',
+  10: '摔倒',
+  11: '跳跃',
+  12: '踢腿',
+  13: '挥击',
+  14: '步行',
+  15: '跑步',
+  16: '跳舞',
+};
+
+// Upgrade a legacy bare `motionType` (int 9–16) to a full MotionRef.
+export function motionRefFromLegacy(id: MotionType): MotionRef {
+  return { system: 'hunyuan_v1', id, label: HUNYUAN_V1_MOTION_LABELS[id] ?? `动作 ${id}` };
+}
+
+// Reserved Meshy ids for the free walk/run clips bundled in a /rigging result.
+// These are NOT real Meshy action_ids (those are positive), so reserving
+// negatives lets the bundled clips dedupe + render like any other motion
+// without colliding with a real action (PLAN §3-4 / §8-Q6).
+export const MESHY_FREE_WALK_ID = -1;
+export const MESHY_FREE_RUN_ID = -2;
+
+export interface ManifestFile {
+  fileId: string;
+  role: FileRole;
+  format: FileFormat;
+  // Game-relative path of the on-disk file (e.g. assets/3d/characters/hero.glb).
+  // The main source_mesh GLB path equals the manifest's assetPath identity.
+  storageKey: string;
+  bytes: number;
+  sha256: string;
+  // Same-origin Studio URL when the blob can be streamed locally. Preview/
+  // download only; not assumed reachable by external providers.
+  localUrl: string | null;
+  // Rigging readiness. Only meaningful for role=rigged_model FBX inputs that
+  // motion_retarget consumes. Plain mesh→fbx conversions stay hasSkeleton=false.
+  hasSkeleton: boolean;
+  skeletonProfile: SkeletonProfile;
+  animationInputReady: boolean;
+  // For role=animated_model files: which motion this clip is, structural (not
+  // parsed from the file name) so multiple motions coexist and apply-motion
+  // stays idempotent per motion. `motionRef` is the generalized descriptor
+  // (any system); `motionType` is the legacy hunyuan_v1-only field, still
+  // populated for that system so older readers keep working. Undefined for
+  // non-animated roles.
+  motionRef?: MotionRef;
+  motionType?: MotionType;
+}
+
+// Five-dimension quality rubric kept as null placeholders. Scoring is manual/
+// out-of-band background knowledge per ADR-0001; not produced at generation time.
+export interface QualityScore {
+  geometry: number | null;
+  topology: number | null;
+  texture: number | null;
+  pbr: number | null;
+  prompt_fidelity: number | null;
+  total: number | null;
+}
+
+export type QualityDimSource = 'auto' | 'ai' | 'manual';
+
+export interface QualityDim {
+  value: number | null;
+  source: QualityDimSource;
+}
+
+export interface QualityReport {
+  geometry: QualityDim;
+  topology: QualityDim;
+  texture: QualityDim;
+  pbr: QualityDim;
+  prompt_fidelity: QualityDim;
+  total: number | null;
+  method: 'auto' | 'auto+ai' | 'manual' | 'mixed';
+  rater: string;
+  notes: string;
+  scoredAt: string;
+}
+
+export function emptyQualityReport(): QualityReport {
+  const dim = (): QualityDim => ({ value: null, source: 'auto' });
+  return {
+    geometry: dim(),
+    topology: dim(),
+    texture: dim(),
+    pbr: dim(),
+    prompt_fidelity: dim(),
+    total: null,
+    method: 'auto',
+    rater: '',
+    notes: '',
+    scoredAt: '',
+  };
+}
+
+export function reportToScore(r: QualityReport): QualityScore {
+  return {
+    geometry: r.geometry.value,
+    topology: r.topology.value,
+    texture: r.texture.value,
+    pbr: r.pbr.value,
+    prompt_fidelity: r.prompt_fidelity.value,
+    total: r.total,
+  };
+}
+
+export interface Gen3DAssetManifest {
+  manifestVersion: 1;
+  // Canonical identity: the game-relative path of the main GLB (ADR-0002).
+  assetPath: string;
+  // The 3D asset slot this lives in (characters | meshes).
+  assetSlot: AssetSlot;
+  kind: AssetKind;
+  provider: ProviderId;
+  providerMode: ProviderMode;
+  mode: GenerationMode;
+  // Original provider job/task id, for audit. Not a stored-asset reference.
+  // For Meshy text after auto-refine this is the refine (result) task id.
+  sourceJobId: string | null;
+  // Meshy preview vs result task pair. Manual refine MUST use previewTaskId;
+  // auto-rig prefers resultTaskId (final textured mesh). Absent for non-Meshy.
+  meshyTaskRefs?: {
+    previewTaskId: string | null;
+    resultTaskId: string | null;
+  };
+  // VISVISE generate/rig COS URLs. auto-rig / apply-motion must send these as
+  // input_model_url (C1: do not re-host on ForgeaX COS first).
+  visviseRefs?: {
+    meshUrl: string | null;
+    rigUrl: string | null;
+  };
+  // Upstream asset paths consumed to produce this one (e.g. image→mesh).
+  sourceInputAssetPaths: string[];
+  prompt: string | null;
+  // Optional user-defined display name. Overrides the auto-generated caption
+  // (prompt first-line or mode name) everywhere the asset is shown.
+  userLabel?: string | null;
+  files: ManifestFile[];
+  // Readiness flags answer "what can downstream do with this asset".
+  readiness: {
+    hasSourceMesh: boolean;
+    rigged: boolean;
+    animated: boolean;
+  };
+  // Rig-chain identity once the asset is rigged (ADR-0006). apply-motion reads
+  // rig.rigTaskId (Meshy) and dispatches by rig.rigProvider. Undefined until rigged.
+  rig?: RigChain;
+  quality: QualityScore;
+  targetFaceCount?: number | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ─── v2 workspace-contract sidecar (03-WORKSPACE-LAYOUT.md) ──────────────────
+//
+// On disk every asset file gets a `<name>.glb.gen3d-meta.json` sidecar in the
+// v2 contract shape (NOT engine pack `*.meta.json`). gen3d-private fields
+// (provider/mode/job/cacheKey/readiness…) live under `custom`. Same-basename
+// sidefiles go in `dependencies[]`.
+
+export interface SidecarDependency {
+  // Path relative to the sidecar's directory (e.g. hero.png, hero.texture.png).
+  path: string;
+  // sha256:<hex>.
+  hash: string;
+  // Role of the dependency file (preview_image, texture, rigged_model, …).
+  kind: string;
+  // Rigging metadata for rigged_model / animated_model attached files, so
+  // sidecarToManifest can restore them instead of writing hasSkeleton:false. Only
+  // set by appendDerivedFiles (a verified rig step); generation never sets these.
+  hasSkeleton?: boolean;
+  skeletonProfile?: SkeletonProfile;
+  animationInputReady?: boolean;
+  // For animated_model deps: the generalized motion descriptor (any system).
+  motionRef?: MotionRef;
+  // Legacy hunyuan_v1-only field, still read for back-compat with sidecars
+  // written before motionRef existed (upgraded in sidecarToManifest).
+  motionType?: MotionType;
+}
+
+// Rig-chain identity persisted on a rigged asset (ADR-0006 §Decision 3). Meshy
+// animation MUST be driven by Meshy's own rig_task_id (it does not accept an
+// external FBX), so apply-motion dispatches strictly by the recorded system and
+// reads rigTaskId from here. Hunyuan REST only needs the local rigged FBX, so
+// rigTaskId is null there.
+export interface RigChain {
+  rigProvider: 'meshy' | 'hunyuan_rest' | 'visvise';
+  // Meshy rig task id (input to /animations). null for the Hunyuan path.
+  rigTaskId: string | null;
+  // Meshy rig skeleton type (e.g. style_01); used to filter compatible actions.
+  rigType: string | null;
+  // Meshy rig task expiry (epoch ms; ~3 days). Used to detect rig_expired.
+  rigExpiresAt: number | null;
+}
+
+export interface PlayableDeliverySnapshot {
+  modelPath: string;
+  playablePath: string;
+  profileId: string;
+  profileVersion: number;
+  clipSlotIds?: string[];
+  slotGuidRegistry: Record<string, string>;
+  mappingFingerprint: string;
+  exportedAt: string;
+}
+
+export interface AssetSidecar {
+  schemaVersion: 1;
+  producer: {
+    plugin: string;
+    pluginVersion: string;
+    pipelineId?: string;
+  };
+  createdAt: string;
+  // sha256:<hex> of the main asset file.
+  contentHash: string;
+  size: number;
+  // Asset type label (e.g. gen3d-character, gen3d-mesh).
+  type: string;
+  dependencies: SidecarDependency[];
+  // gen3d-private namespace. Not part of the cross-plugin contract.
+  custom: {
+    provider: ProviderId;
+    providerMode: ProviderMode;
+    mode: GenerationMode;
+    assetSlot: AssetSlot;
+    sourceJobId: string | null;
+    prompt: string | null;
+    userLabel?: string | null;
+    sourceInputAssetPaths: string[];
+    faceCount?: number;
+    readiness: Gen3DAssetManifest['readiness'];
+    // The cacheKey that produced this asset, for delete→tombstone reverse lookup.
+    cacheKey?: string;
+    quality?: QualityReport;
+    meshyTaskRefs?: Gen3DAssetManifest['meshyTaskRefs'];
+    visviseRefs?: Gen3DAssetManifest['visviseRefs'];
+    // Rig-chain identity (ADR-0006), set by a verified rig step. apply-motion
+    // dispatches by custom.rig.rigProvider and reads rig.rigTaskId (Meshy).
+    rig?: RigChain;
+    // Playable-character layer (PLAN-2026-07-13 §4.1, ADR-0008). Only ever set
+    // on characters slot assets. Absent = this character uses the game default
+    // profile unmodified with no motion mapping drafted yet.
+    playableOverride?: CharacterMotionOverride;
+    motionMapping?: MotionMappingDraft;
+    // Last successful playable delivery snapshot (PLAN §5.6 / UX1 one-click update).
+    playableDelivery?: PlayableDeliverySnapshot;
+  };
+}
+
+export const FILE_ROLES: readonly FileRole[] = [
+  'source_mesh',
+  'rigged_model',
+  'preview_image',
+  'texture',
+  'animation_clip',
+  'animated_model',
+];
+
+export function emptyQuality(): QualityScore {
+  return {
+    geometry: null,
+    topology: null,
+    texture: null,
+    pbr: null,
+    prompt_fidelity: null,
+    total: null,
+  };
+}
+
+export function computeReadiness(files: readonly ManifestFile[]): Gen3DAssetManifest['readiness'] {
+  return {
+    hasSourceMesh: files.some((file) => file.role === 'source_mesh'),
+    rigged: files.some((file) => file.role === 'rigged_model' && file.hasSkeleton),
+    animated: files.some(
+      (file) => file.role === 'animated_model' || file.role === 'animation_clip',
+    ),
+  };
+}
+
+// Resolve the single file a consumer wants by role (+ optional format), instead
+// of parsing file names or URLs. The main mesh is selectFile(files,
+// 'source_mesh', 'glb'); the preview is selectFile(files, 'preview_image').
+export function selectFile(
+  files: readonly ManifestFile[],
+  role: FileRole,
+  format?: FileFormat,
+): ManifestFile | null {
+  return (
+    files.find((file) => file.role === role && (format ? file.format === format : true)) ?? null
+  );
+}
+
+// All files of a role (e.g. every animated_model clip), for enumeration. The UI
+// lists existing motions from animated_model files' structural motionType.
+export function selectFiles(
+  files: readonly ManifestFile[],
+  role: FileRole,
+  format?: FileFormat,
+): ManifestFile[] {
+  return files.filter((file) => file.role === role && (format ? file.format === format : true));
+}