@forgeax/engine-skinning 0.0.0-dev.8d955ade1c79

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+/** Install skeletal binding components in a World that consumes skinned scenes. */
+export declare function skinningPlugin(): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAcrD,mFAAmF;AACnF,wBAAgB,cAAc,IAAI,MAAM,CAQvC"}

package/dist/resolve-skin-joints.d.ts

@@ -0,0 +1,10 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { type SkinError } from './errors.js';
+export declare function resolveSkinJoints(jointPaths: readonly string[], names: ReadonlyMap<string, EntityHandle>, skinEntity: EntityHandle): {
+    ok: true;
+    value: Uint32Array;
+} | {
+    ok: false;
+    error: SkinError;
+};
+//# sourceMappingURL=resolve-skin-joints.d.ts.map

package/dist/resolve-skin-joints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-skin-joints.d.ts","sourceRoot":"","sources":["../src/resolve-skin-joints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,KAAK,SAAS,EAAgC,MAAM,aAAa,CAAC;AAE3E,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EACxC,UAAU,EAAE,YAAY,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAgBpE"}

package/dist/skin.d.ts

@@ -0,0 +1,5 @@
+export declare const Skin: import("@forgeax/engine-ecs").Component<"Skin", {
+    readonly skeleton: "shared<SkeletonAsset>";
+    readonly joints: "array<entity>";
+}>;
+//# sourceMappingURL=skin.d.ts.map

package/dist/skin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin.d.ts","sourceRoot":"","sources":["../src/skin.ts"],"names":[],"mappings":"AA8DA,eAAO,MAAM,IAAI;;;EAKf,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@forgeax/engine-skinning",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Optional skin and joint binding domain.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "headless binding package"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "binding is validated by unit tests"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package binary gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/binding.unit.test.ts

@@ -0,0 +1,33 @@
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { resolveSkinJoints, Skin, SkinJointPathUnresolvedError } from '@forgeax/engine-skinning';
+import { describe, expect, it } from 'vitest';
+
+describe('skinning binding contract', () => {
+  it('exposes Skin as the optional binding component', () => {
+    expect(Skin.name).toBe('Skin');
+    expect(componentSchema(Skin).skeleton).toBe('shared<SkeletonAsset>');
+    expect(componentSchema(Skin).joints).toBe('array<entity>');
+  });
+
+  it('returns the canonical error and retries with only the Name map repaired', () => {
+    const jointPaths = ['Root/Arm', 'Root/Missing', 'Root/Hand'];
+    const names = new Map([
+      ['Arm', 4 as never],
+      ['Root', 5 as never],
+    ]);
+    const result = resolveSkinJoints(jointPaths, names, 7 as never);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    const expected = new SkinJointPathUnresolvedError(7, ['Root', 'Missing'], 1);
+    expect(result.error).toBeInstanceOf(SkinJointPathUnresolvedError);
+    expect(result.error.code).toBe('skin-joint-path-unresolved');
+    expect(result.error.expected).toBe(expected.expected);
+    expect(result.error.hint).toBe(expected.hint);
+    expect(result.error.detail).toEqual(expected.detail);
+
+    names.set('Missing', 6 as never);
+    names.set('Hand', 8 as never);
+    const retry = resolveSkinJoints(jointPaths, names, 7 as never);
+    expect(retry).toEqual({ ok: true, value: new Uint32Array([4, 6, 8]) });
+  });
+});

package/src/__tests__/errors.unit.test.ts

@@ -0,0 +1,13 @@
+import { type SkinError, SkinJointPathUnresolvedError } from '@forgeax/engine-skinning';
+import { describe, expect, it } from 'vitest';
+
+describe('skinning error boundary', () => {
+  it('keeps binding errors structured and exhaustive', () => {
+    const error: SkinError = new SkinJointPathUnresolvedError(2, ['Root', 'Arm'], 1);
+    expect(error).toBeInstanceOf(SkinJointPathUnresolvedError);
+    expect(error.code).toBe('skin-joint-path-unresolved');
+    expect(error.expected).toBe('joint entity with Name="Arm" exists in the world');
+    expect(error.detail.failedAtIndex).toBe(1);
+    expect(error.hint.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/plugin.integration.test.ts

@@ -0,0 +1,23 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Skin, skinningPlugin } from '../index';
+
+describe('skinningPlugin', () => {
+  it('installs only the optional Skin component vocabulary', async () => {
+    const world = new World();
+    const context = await createWorldContext(world, [skinningPlugin()]);
+
+    expect([...world.components.entries()].map(([name]) => name)).toEqual(['Skin']);
+    const skeleton = world.allocSharedRef('SkeletonAsset', {
+      kind: 'skeleton',
+      jointCount: 0,
+      inverseBindMatrices: new Float32Array(),
+    });
+    const entity = world.spawn({ component: Skin, data: { skeleton, joints: [] } }).unwrap();
+    expect(world.get(entity, Skin).ok).toBe(true);
+
+    world.despawn(entity).unwrap();
+    await context.fiber.dispose();
+    expect(world.components.entries()).toHaveLength(0);
+  });
+});

package/src/__tests__/skin-error-code-owner.test-d.ts

@@ -0,0 +1,91 @@
+import type { resolveSkinJoints } from '@forgeax/engine-skinning';
+import type { SkinError, SkinErrorCode, SkinExtractErrorCode } from '../errors.js';
+
+type Equal<Left, Right> =
+  (<Type>() => Type extends Left ? 1 : 2) extends <Type>() => Type extends Right ? 1 : 2
+    ? true
+    : false;
+
+type Assert<Value extends true> = Value;
+
+type ExpectedSkinErrorCodes =
+  | 'skin-joint-count-exceeded'
+  | 'skin-joint-despawned'
+  | 'skin-joint-path-unresolved'
+  | 'skin-instances-coexist-forbidden'
+  | 'skeleton-resolve-failed'
+  | 'joint-count-mismatch'
+  | 'joint-entity-dangling';
+
+type _SkinErrorCodeDerivesFromSkinError = Assert<Equal<SkinErrorCode, SkinError['code']>>;
+
+type _SkinErrorCodeHasExactMembership = Assert<Equal<SkinErrorCode, ExpectedSkinErrorCodes>>;
+
+type _SkinExtractErrorCodeIsASkinErrorCode = Assert<
+  SkinExtractErrorCode extends SkinErrorCode ? true : false
+>;
+
+type ResolveSkinJointsError = Extract<ReturnType<typeof resolveSkinJoints>, { ok: false }>['error'];
+type _ResolveSkinJointsUsesSkinErrorAuthority = Assert<Equal<ResolveSkinJointsError, SkinError>>;
+
+declare const extractCode: SkinExtractErrorCode;
+const acceptsSkinErrorCode = (code: SkinErrorCode): SkinErrorCode => code;
+acceptsSkinErrorCode(extractCode);
+
+// @ts-expect-error invalid codes must not be accepted.
+acceptsSkinErrorCode('not-a-skin-error');
+
+function narrowSkinErrorDetail(error: SkinError): void {
+  switch (error.code) {
+    case 'skin-joint-path-unresolved': {
+      const path: readonly string[] = error.detail.path;
+      void path;
+      // @ts-expect-error code-driven narrowing excludes unrelated detail fields.
+      void error.detail.jointCount;
+      break;
+    }
+    case 'joint-count-mismatch': {
+      const actual: number = error.detail.actual;
+      void actual;
+      break;
+    }
+    case 'skeleton-resolve-failed': {
+      const skeletonHandle: number = error.detail.skeletonHandle;
+      void skeletonHandle;
+      break;
+    }
+    case 'skin-joint-count-exceeded': {
+      void error.detail.max;
+      break;
+    }
+    case 'skin-joint-despawned': {
+      void error.detail.meshEntity;
+      break;
+    }
+    case 'skin-instances-coexist-forbidden': {
+      void error.detail.entity;
+      break;
+    }
+    case 'joint-entity-dangling': {
+      void error.detail.jointIndex;
+      break;
+    }
+    default: {
+      const exhaustive: never = error;
+      void exhaustive;
+    }
+  }
+}
+
+export type _SkinErrorCodeOwnerChecks = {
+  /** @internal */
+  _derived: _SkinErrorCodeDerivesFromSkinError;
+  /** @internal */
+  _membership: _SkinErrorCodeHasExactMembership;
+  /** @internal */
+  _extractSubset: _SkinExtractErrorCodeIsASkinErrorCode;
+  /** @internal */
+  _resolveAuthority: _ResolveSkinJointsUsesSkinErrorAuthority;
+  /** @internal */
+  _narrowDetail: typeof narrowSkinErrorDetail;
+};

package/src/assets/skin-decoder.ts

@@ -0,0 +1,69 @@
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  err,
+  ok,
+  type SkeletonAsset,
+  type SkinAsset,
+} from '@forgeax/engine-types';
+
+function floatArray(value: unknown): Float32Array | undefined {
+  if (value instanceof Float32Array) return value;
+  if (Array.isArray(value) && value.every((item) => typeof item === 'number')) {
+    return Float32Array.from(value);
+  }
+  return undefined;
+}
+
+export const skinContribution: AssetDecoderContribution<SkinAsset, 'skin'> = {
+  kind: { kind: 'skin' } as AssetKind<SkinAsset, 'skin'>,
+  consumer: 'resolveSkinJoints',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      if (
+        payload.kind === 'skin' &&
+        payload.skeletonGuid.length > 0 &&
+        payload.jointPaths.length > 0
+      ) {
+        return ok(payload);
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a skin payload with a skeleton GUID and joint paths',
+        hint: 'recook the skin binding and publish its skeleton reference',
+        detail: { guid: envelope.guid, reason: 'skin owner validation failed' },
+      });
+    },
+  },
+};
+
+export const skeletonContribution: AssetDecoderContribution<SkeletonAsset, 'skeleton'> = {
+  kind: { kind: 'skeleton' } as AssetKind<SkeletonAsset, 'skeleton'>,
+  consumer: 'resolveSkinJoints',
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload as unknown;
+      if (payload !== null && typeof payload === 'object') {
+        const source = payload as Record<string, unknown>;
+        const inverseBindMatrices = floatArray(source.inverseBindMatrices);
+        const jointCount = source.jointCount;
+        if (
+          source.kind === 'skeleton' &&
+          inverseBindMatrices !== undefined &&
+          Number.isSafeInteger(jointCount) &&
+          (jointCount as number) >= 0 &&
+          inverseBindMatrices.length === (jointCount as number) * 16
+        ) {
+          return ok({ kind: 'skeleton', inverseBindMatrices, jointCount: jointCount as number });
+        }
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'a skeleton payload with one inverse-bind matrix per joint',
+        hint: 'recook the skeleton and publish its complete joint data',
+        detail: { guid: envelope.guid, reason: 'skeleton owner validation failed' },
+      });
+    },
+  },
+};

package/src/errors.ts

@@ -0,0 +1,356 @@
+// @forgeax/engine-runtime -- skin cluster error classes.
+//
+// feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): skin / skeleton
+// animation cluster -- joint count / despawn / path / coexistence and
+// extract-stage binding failures. Palette/material/GPU failures stay in the
+// render error union because render owns the emitting frame stages. Binding
+// class names, .code literals, and .detail shapes are preserved byte-for-byte
+// (OOS-4).
+//
+// SkinExtractErrorCode (the 3-member extract-stage subset union) is kept as a
+// named export and folded into SkinErrorCode, preserving the pre-existing
+// public symbol (OOS-4).
+
+// ── SkinExtractErrorCode subset union ───────────────────────────────────────
+
+/**
+ * feat-20260612-skin-palette-per-frame-upload M2 / m2-5 subset union.
+ *
+ * Covers the three new fail-fast extract-stage errors that fire from
+ * `render-system-extract.ts` `hasSkin` segment when the per-frame palette
+ * upload pipeline cannot resolve a slice for an entity. Single-entity
+ * `continue` semantics: the entity is skipped, sibling entities in the
+ * same frame keep extracting (plan-strategy D-5).
+ *
+ * | code | class | trigger |
+ * |:--|:--|:--|
+ * | `'skeleton-resolve-failed'` | `SkeletonResolveFailedError` | `assets.get<SkeletonAsset>(skin.skeleton)` returns null/undefined |
+ * | `'joint-count-mismatch'` | `JointCountMismatchError` | `Skin.joints.length !== SkeletonAsset.jointCount` |
+ * | `'joint-entity-dangling'` | `JointEntityDanglingError` | `Skin.joints[i]` Entity is despawned (Transform.world view undefined) |
+ *
+ * AI users discriminate via `switch (err.code)` over `RuntimeErrorCode`;
+ * each member narrows to its `*Error` class with structured `.detail`.
+ *
+ * NOTE: distinct from the pre-existing `'skin-joint-despawned'` /
+ * `'skin-joint-path-unresolved'` / `'skin-joint-count-exceeded'`
+ * (advanceAnimationPlayer + post-spawn jointPath resolution); plan-strategy
+ * D-4 forbids reusing those codes for the new extract-stage triggers.
+ */
+export type SkinExtractErrorCode =
+  | 'skeleton-resolve-failed'
+  | 'joint-count-mismatch'
+  | 'joint-entity-dangling';
+
+// ── SkinJointCountExceededError ────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'skin-joint-count-exceeded'`.
+ *
+ * Emitted when a glTF skin has more than MAX_JOINTS (256) joints.
+ */
+export interface SkinJointCountExceededDetail {
+  readonly jointCount: number;
+  readonly max: number;
+}
+
+/**
+ * Structured error for skin joint count exceeding the engine cap.
+ *
+ * Emitted during skin import/validation. Four-field surface:
+ *   - `.code = 'skin-joint-count-exceeded'`
+ *   - `.expected` — max allowed (256)
+ *   - `.hint` — reduce joint count in the source asset
+ *   - `.detail = { jointCount, max }` — actual vs limit
+ */
+export class SkinJointCountExceededError extends Error {
+  readonly code = 'skin-joint-count-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkinJointCountExceededDetail;
+
+  constructor(jointCount: number, max = 256) {
+    const expected = `jointCount <= ${max}`;
+    const hint = `skin has ${jointCount} joints (max ${max}); reduce joint count in the source glTF asset (OOS-skin-many-joints)`;
+    super(`skin joint count ${jointCount} exceeds max ${max}`);
+    this.name = 'SkinJointCountExceededError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { jointCount, max };
+  }
+}
+
+// ── SkinJointDespawnedError ─────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'skin-joint-despawned'`.
+ *
+ * Emitted at extract time when a Skin.joints[i] Entity has been despawned.
+ */
+export interface SkinJointDespawnedDetail {
+  readonly meshEntity: number;
+  readonly jointIndex: number;
+}
+
+/**
+ * Structured error for despawned skin joint Entity.
+ *
+ * Emitted at extract time; the mesh draw is fully skipped.
+ *   - `.code = 'skin-joint-despawned'`
+ *   - `.expected` — all Skin.joints alive
+ *   - `.hint` — remove the Skin component or re-spawn joints
+ *   - `.detail = { meshEntity, jointIndex }`
+ */
+export class SkinJointDespawnedError extends Error {
+  readonly code = 'skin-joint-despawned' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkinJointDespawnedDetail;
+
+  constructor(meshEntity: number, jointIndex: number) {
+    const expected = `Skin.joints[${jointIndex}] references a live entity`;
+    const hint = `joint[${jointIndex}] of entity ${meshEntity} has been despawned; remove Skin component or re-spawn the joint entity (OOS-skin-joint-respawn)`;
+    super(`skin joint[${jointIndex}] despawned for entity ${meshEntity}`);
+    this.name = 'SkinJointDespawnedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { meshEntity, jointIndex };
+  }
+}
+
+// ── SkinJointPathUnresolvedError ────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'skin-joint-path-unresolved'`.
+ *
+ * Emitted at post-spawn time when a jointPath leaf name cannot be found.
+ */
+export interface SkinJointPathUnresolvedDetail {
+  readonly skinEntity: number;
+  readonly path: readonly string[];
+  readonly failedAtIndex: number;
+}
+
+/**
+ * Structured error for unresolved jointPath post-spawn.
+ *
+ * Emitted by resolveSkinJoints when Name lookup fails.
+ *   - `.code = 'skin-joint-path-unresolved'`
+ *   - `.expected` — Name-bearing entity exists for each jointPath leaf
+ *   - `.hint` — verify glTF node Name preservation in the importer
+ *   - `.detail = { skinEntity, path, failedAtIndex }`
+ */
+export class SkinJointPathUnresolvedError extends Error {
+  readonly code = 'skin-joint-path-unresolved' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkinJointPathUnresolvedDetail;
+
+  constructor(skinEntity: number, path: readonly string[], failedAtIndex: number) {
+    const leafName = path[failedAtIndex] ?? '<unknown>';
+    const expected = `joint entity with Name="${leafName}" exists in the world`;
+    const hint = `joint path "${path.join('/')}" for skin entity ${skinEntity} could not be resolved; verify glTF node names are preserved`;
+    super(
+      `joint path "${path.join('/')}" unresolved at index ${failedAtIndex} for entity ${skinEntity}`,
+    );
+    this.name = 'SkinJointPathUnresolvedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { skinEntity, path, failedAtIndex };
+  }
+}
+
+// ── SkinInstancesCoexistForbiddenError ──────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'skin-instances-coexist-forbidden'`.
+ *
+ * Emitted at extract time when Skin + Instances coexist on the same entity.
+ */
+export interface SkinInstancesCoexistForbiddenDetail {
+  readonly entity: number;
+}
+
+/**
+ * Structured error for Skin + Instances coexistence on same entity.
+ *
+ * Emitted at extract time; the entity draw is skipped.
+ *   - `.code = 'skin-instances-coexist-forbidden'`
+ *   - `.expected` — Skin and Instances on separate entities
+ *   - `.hint` — split skinned meshes from instanced meshes into separate entities (OOS-skin-instances-coexist)
+ *   - `.detail = { entity }`
+ */
+export class SkinInstancesCoexistForbiddenError extends Error {
+  readonly code = 'skin-instances-coexist-forbidden' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkinInstancesCoexistForbiddenDetail;
+
+  constructor(entity: number) {
+    const expected = 'Skin and Instances must not coexist on the same entity';
+    const hint = `entity ${entity} has both Skin and Instances; split skinned meshes from instanced meshes into separate entities (OOS-skin-instances-coexist)`;
+    super(`Skin + Instances coexistence forbidden on entity ${entity}`);
+    this.name = 'SkinInstancesCoexistForbiddenError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity };
+  }
+}
+
+// ── SkeletonResolveFailedError ─────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'skeleton-resolve-failed'`.
+ *
+ * Emitted at extract time when `assets.get<SkeletonAsset>(skin.skeleton)`
+ * returns `null` / `undefined`. The skeleton handle is non-zero (the entity
+ * declared a Skin) but the asset is not registered (importer drift /
+ * AssetRegistry not warmed).
+ */
+export interface SkeletonResolveFailedDetail {
+  readonly entity: number;
+  readonly skeletonHandle: number;
+}
+
+/**
+ * Structured error for unresolved SkeletonAsset handle at extract time
+ * (feat-20260612-skin-palette-per-frame-upload M2 / m2-5).
+ *
+ * Emitted at extract time; the entity draw is skipped (continue), other
+ * entities in the same frame keep extracting.
+ *   - `.code = 'skeleton-resolve-failed'`
+ *   - `.expected` — Skin.skeleton handle resolves to a registered SkeletonAsset
+ *   - `.hint` — verify SkeletonAsset is imported into pack-index AND registered
+ *     via AssetRegistry.register(handle, asset) before extractFrame
+ *   - `.detail = { entity, skeletonHandle }`
+ */
+export class SkeletonResolveFailedError extends Error {
+  readonly code = 'skeleton-resolve-failed' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SkeletonResolveFailedDetail;
+
+  constructor(entity: number, skeletonHandle: number) {
+    const expected = `Skin.skeleton handle ${skeletonHandle} resolves to a registered SkeletonAsset`;
+    const hint = `entity ${entity} Skin.skeleton handle ${skeletonHandle} is not registered; check that the SkeletonAsset went through the gltf importer into pack-index AND that AssetRegistry.register was called for the handle before extractFrame runs`;
+    super(`Skin skeleton resolve failed on entity ${entity}: handle ${skeletonHandle}`);
+    this.name = 'SkeletonResolveFailedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, skeletonHandle };
+  }
+}
+
+// ── JointCountMismatchError ────────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'joint-count-mismatch'`.
+ *
+ * Emitted at extract time when `Skin.joints.length !== SkeletonAsset.jointCount`.
+ * `expected` is the SkeletonAsset's jointCount (the source of truth);
+ * `actual` is the entity's `Skin.joints.length` (the runtime entity reference
+ * list materialized at post-spawn time).
+ */
+export interface JointCountMismatchDetail {
+  readonly entity: number;
+  readonly expected: number;
+  readonly actual: number;
+}
+
+/**
+ * Structured error for SkinAsset.joints[] vs SkeletonAsset.jointCount disagreement
+ * (feat-20260612-skin-palette-per-frame-upload M2 / m2-5).
+ *
+ * Emitted at extract time; the entity draw is skipped (continue).
+ *   - `.code = 'joint-count-mismatch'`
+ *   - `.expected` — Skin.joints.length === SkeletonAsset.jointCount
+ *   - `.hint` — verify SkinAsset.joints[] and SkeletonAsset jointPaths[]
+ *     come from the same glTF skin node
+ *   - `.detail = { entity, expected, actual }`
+ */
+export class JointCountMismatchError extends Error {
+  readonly code = 'joint-count-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: JointCountMismatchDetail;
+
+  constructor(entity: number, expected: number, actual: number) {
+    const expectedStr = `Skin.joints.length === SkeletonAsset.jointCount (=${expected})`;
+    const hint = `entity ${entity}: Skin.joints.length=${actual} disagrees with SkeletonAsset.jointCount=${expected}; verify SkinAsset.joints[] and SkeletonAsset jointPaths[] come from the same glTF skin node`;
+    super(
+      `joint count mismatch on entity ${entity}: SkeletonAsset.jointCount=${expected}, Skin.joints.length=${actual}`,
+    );
+    this.name = 'JointCountMismatchError';
+    this.expected = expectedStr;
+    this.hint = hint;
+    this.detail = { entity, expected, actual };
+  }
+}
+
+// ── JointEntityDanglingError ──────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'joint-entity-dangling'`.
+ *
+ * Emitted at extract time when `Skin.joints[i]` points at an Entity that has
+ * been despawned (or lost its Transform component) so
+ * `worldInternal._getArrayView(jointEntity, Transform, 'world')` returns
+ * undefined. `jointIndex` is the position within `Skin.joints[]`.
+ */
+export interface JointEntityDanglingDetail {
+  readonly entity: number;
+  readonly jointIndex: number;
+}
+
+/**
+ * Structured error for despawned (or Transform-less) joint Entity at extract
+ * time (feat-20260612-skin-palette-per-frame-upload M2 / m2-5).
+ *
+ * Distinct from the pre-existing `SkinJointDespawnedError` which fires from
+ * advanceAnimationPlayer (animation-stage); this one fires from extractFrame
+ * (palette-upload stage) when the per-joint world mat4 view is missing.
+ *
+ * Emitted at extract time; the entity draw is skipped (continue).
+ *   - `.code = 'joint-entity-dangling'`
+ *   - `.expected` — Skin.joints[i] references a live Entity with Transform
+ *   - `.hint` — sync Skin.joints[] when joint entities are despawned, or
+ *     re-import the scene through the gltf importer to refresh Entity refs
+ *   - `.detail = { entity, jointIndex }`
+ */
+export class JointEntityDanglingError extends Error {
+  readonly code = 'joint-entity-dangling' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: JointEntityDanglingDetail;
+
+  constructor(entity: number, jointIndex: number) {
+    const expected = `Skin.joints[${jointIndex}] references a live Entity with Transform`;
+    const hint = `entity ${entity} Skin.joints[${jointIndex}] points at a despawned (or Transform-less) Entity; sync Skin.joints[] when joint entities are despawned, or re-import the scene through the gltf importer to refresh Entity references`;
+    super(`joint entity dangling on entity ${entity} at jointIndex ${jointIndex}`);
+    this.name = 'JointEntityDanglingError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, jointIndex };
+  }
+}
+
+// -- SkinErrorCode / SkinError closed unions ------------------------------------
+
+/**
+ * Closed union of skin-cluster error codes derived from the correlated error
+ * union. AI users perform exhaustive `switch (err.code)` without default; TS
+ * guards completeness.
+ */
+export type SkinErrorCode = SkinError['code'];
+
+/**
+ * Closed union of the skin-cluster structured error classes, each carrying a
+ * `SkinErrorCode` discriminant on `.code`.
+ */
+export type SkinError =
+  | SkinJointCountExceededError
+  | SkinJointDespawnedError
+  | SkinJointPathUnresolvedError
+  | SkinInstancesCoexistForbiddenError
+  | SkeletonResolveFailedError
+  | JointCountMismatchError
+  | JointEntityDanglingError;