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

package/dist/errors.d.ts

@@ -0,0 +1,232 @@
+/**
+ * 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';
+/**
+ * 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 declare class SkinJointCountExceededError extends Error {
+    readonly code: "skin-joint-count-exceeded";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkinJointCountExceededDetail;
+    constructor(jointCount: number, max?: number);
+}
+/**
+ * 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 declare class SkinJointDespawnedError extends Error {
+    readonly code: "skin-joint-despawned";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkinJointDespawnedDetail;
+    constructor(meshEntity: number, jointIndex: number);
+}
+/**
+ * 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 declare class SkinJointPathUnresolvedError extends Error {
+    readonly code: "skin-joint-path-unresolved";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkinJointPathUnresolvedDetail;
+    constructor(skinEntity: number, path: readonly string[], failedAtIndex: number);
+}
+/**
+ * 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 declare class SkinInstancesCoexistForbiddenError extends Error {
+    readonly code: "skin-instances-coexist-forbidden";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkinInstancesCoexistForbiddenDetail;
+    constructor(entity: number);
+}
+/**
+ * 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 declare class SkeletonResolveFailedError extends Error {
+    readonly code: "skeleton-resolve-failed";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: SkeletonResolveFailedDetail;
+    constructor(entity: number, skeletonHandle: number);
+}
+/**
+ * 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 declare class JointCountMismatchError extends Error {
+    readonly code: "joint-count-mismatch";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: JointCountMismatchDetail;
+    constructor(entity: number, expected: number, actual: number);
+}
+/**
+ * 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 declare class JointEntityDanglingError extends Error {
+    readonly code: "joint-entity-dangling";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: JointEntityDanglingDetail;
+    constructor(entity: number, jointIndex: number);
+}
+/**
+ * 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;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { skeletonContribution, skinContribution } from './assets/skin-decoder';
+export { JointCountMismatchError, JointEntityDanglingError, SkeletonResolveFailedError, type SkinError, type SkinErrorCode, SkinInstancesCoexistForbiddenError, SkinJointCountExceededError, SkinJointDespawnedError, SkinJointPathUnresolvedError, } from './errors';
+export { skinningPlugin } from './plugin';
+export { resolveSkinJoints } from './resolve-skin-joints';
+export { Skin } from './skin';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,kCAAkC,EAClC,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,375 @@
+// ../types/dist/index.mjs
+var OK_PROTO = {
+  unwrap() {
+    return this.value;
+  },
+  unwrapOr(_defaultValue) {
+    return this.value;
+  }
+};
+var ERR_PROTO = {
+  unwrap() {
+    throw this.error;
+  },
+  unwrapOr(defaultValue) {
+    return defaultValue;
+  }
+};
+function ok(value) {
+  const r = Object.create(OK_PROTO);
+  r.ok = true;
+  r.value = value;
+  return r;
+}
+function err(error) {
+  const r = Object.create(ERR_PROTO);
+  r.ok = false;
+  r.error = error;
+  return r;
+}
+var MAX_SLOT = (1 << 24) - 1;
+var MATERIAL_ERROR_CODES = [
+  "material-parent-not-found",
+  "material-circular-inheritance",
+  "material-no-effective-pass",
+  "material-value-unknown",
+  "material-value-type-mismatch",
+  "material-contract-program-mismatch",
+  "shader-module-id-missing",
+  "shader-module-id-duplicate",
+  "shader-module-not-found",
+  "shader-module-namespace-reserved",
+  "material-reflection-binding-mismatch",
+  "material-specialization-not-cooked",
+  "material-specialization-stale-generation",
+  "gltf-material-uv-set-missing",
+  "material-derived-interface-mismatch",
+  "material-texture-coordinate-invalid",
+  "material-payload-bounds"
+];
+var MATERIAL_ERROR_POLICY = {
+  "material-parent-not-found": {
+    expected: "every parent GUID resolves to a MaterialAsset",
+    hint: "fix the parent GUID and resolve the material again"
+  },
+  "material-circular-inheritance": {
+    expected: "the parent chain is acyclic",
+    hint: "remove the repeated GUID from the parent chain"
+  },
+  "material-no-effective-pass": {
+    expected: "the resolved material has at least one pass",
+    hint: "add a pass to the root material or an inherited parent"
+  },
+  "material-value-unknown": {
+    expected: "every value name is declared by the effective contract",
+    hint: "remove the value or declare the parameter in the root contract"
+  },
+  "material-value-type-mismatch": {
+    expected: "each value matches its declared parameter type",
+    hint: "change the value to the declared parameter type"
+  },
+  "material-contract-program-mismatch": {
+    expected: "the program satisfies the material contract",
+    hint: "align the program entries with the root contract"
+  },
+  "shader-module-id-missing": {
+    expected: "each WGSL source declares a module ID",
+    hint: "add a compiler-native module ID declaration to the WGSL source"
+  },
+  "shader-module-id-duplicate": {
+    expected: "each module ID has one source provenance",
+    hint: "rename one module or remove the duplicate source"
+  },
+  "shader-module-not-found": {
+    expected: "every referenced module exists in the source catalog",
+    hint: "add the module to the source catalog or fix the reference"
+  },
+  "shader-module-namespace-reserved": {
+    expected: "user modules use a non-reserved namespace",
+    hint: "choose a module ID outside the reserved namespace"
+  },
+  "material-reflection-binding-mismatch": {
+    expected: "reflection matches the material contract bindings",
+    hint: "update the contract or WGSL binding and cook again"
+  },
+  "material-specialization-not-cooked": {
+    expected: "the requested specialization has a cooked artifact",
+    hint: "run the build or development cook path for this selection"
+  },
+  "material-specialization-stale-generation": {
+    expected: "all specialization dependencies share one generation",
+    hint: "retry after dependent assets and sources settle"
+  },
+  "gltf-material-uv-set-missing": {
+    expected: "each texture slot references an available primitive UV set",
+    hint: "add the requested UV set to the primitive and re-import it"
+  },
+  "material-derived-interface-mismatch": {
+    expected: "the generated material interface matches the derived schema interface",
+    hint: "repair the schema or WGSL producer and recook the material"
+  },
+  "material-texture-coordinate-invalid": {
+    expected: "every texture coordinate record is finite and complete",
+    hint: "repair the texture metadata or coordinates and recook the material"
+  },
+  "material-payload-bounds": {
+    expected: "every material payload write stays within the derived payload",
+    hint: "repair the derived payload owner before submitting the draw"
+  }
+};
+var MATERIAL_ERROR_EXPECTED = Object.fromEntries(
+  MATERIAL_ERROR_CODES.map((code) => [code, MATERIAL_ERROR_POLICY[code].expected])
+);
+var MATERIAL_ERROR_HINTS = Object.fromEntries(
+  MATERIAL_ERROR_CODES.map((code) => [code, MATERIAL_ERROR_POLICY[code].hint])
+);
+var NUMERIC_TYPES = /* @__PURE__ */ new Set([
+  "f32",
+  "i32",
+  "u32",
+  "vec2",
+  "vec3",
+  "vec4",
+  "color"
+]);
+var TEXTURE_VIEW_TYPES = /* @__PURE__ */ new Set([
+  "texture2d",
+  "texture_cube",
+  "texture_depth_2d",
+  "texture_cube_array"
+]);
+var SAMPLER_TYPES = /* @__PURE__ */ new Set([
+  "sampler",
+  "sampler_comparison"
+]);
+var ALL_TYPES = /* @__PURE__ */ new Set([
+  ...NUMERIC_TYPES,
+  ...TEXTURE_VIEW_TYPES,
+  ...SAMPLER_TYPES,
+  "storage_buffer"
+]);
+
+// src/assets/skin-decoder.ts
+function floatArray(value) {
+  if (value instanceof Float32Array) return value;
+  if (Array.isArray(value) && value.every((item) => typeof item === "number")) {
+    return Float32Array.from(value);
+  }
+  return void 0;
+}
+var skinContribution = {
+  kind: { kind: "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" }
+      });
+    }
+  }
+};
+var skeletonContribution = {
+  kind: { kind: "skeleton" },
+  consumer: "resolveSkinJoints",
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      if (payload !== null && typeof payload === "object") {
+        const source = payload;
+        const inverseBindMatrices = floatArray(source.inverseBindMatrices);
+        const jointCount = source.jointCount;
+        if (source.kind === "skeleton" && inverseBindMatrices !== void 0 && Number.isSafeInteger(jointCount) && jointCount >= 0 && inverseBindMatrices.length === jointCount * 16) {
+          return ok({ kind: "skeleton", inverseBindMatrices, jointCount });
+        }
+      }
+      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" }
+      });
+    }
+  }
+};
+
+// src/errors.ts
+var SkinJointCountExceededError = class extends Error {
+  code = "skin-joint-count-exceeded";
+  expected;
+  hint;
+  detail;
+  constructor(jointCount, 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 };
+  }
+};
+var SkinJointDespawnedError = class extends Error {
+  code = "skin-joint-despawned";
+  expected;
+  hint;
+  detail;
+  constructor(meshEntity, jointIndex) {
+    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 };
+  }
+};
+var SkinJointPathUnresolvedError = class extends Error {
+  code = "skin-joint-path-unresolved";
+  expected;
+  hint;
+  detail;
+  constructor(skinEntity, path, failedAtIndex) {
+    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 };
+  }
+};
+var SkinInstancesCoexistForbiddenError = class extends Error {
+  code = "skin-instances-coexist-forbidden";
+  expected;
+  hint;
+  detail;
+  constructor(entity) {
+    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 };
+  }
+};
+var SkeletonResolveFailedError = class extends Error {
+  code = "skeleton-resolve-failed";
+  expected;
+  hint;
+  detail;
+  constructor(entity, skeletonHandle) {
+    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 };
+  }
+};
+var JointCountMismatchError = class extends Error {
+  code = "joint-count-mismatch";
+  expected;
+  hint;
+  detail;
+  constructor(entity, expected, actual) {
+    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 };
+  }
+};
+var JointEntityDanglingError = class extends Error {
+  code = "joint-entity-dangling";
+  expected;
+  hint;
+  detail;
+  constructor(entity, jointIndex) {
+    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 };
+  }
+};
+
+// src/skin.ts
+import { defineComponent } from "@forgeax/engine-ecs";
+var Skin = defineComponent("Skin", {
+  // The renderer owns the live skeleton asset/palette binding; joint entity
+  // relationships remain the portable simulation-side pose contract.
+  skeleton: { type: "shared<SkeletonAsset>" },
+  joints: { type: "array<entity>" }
+});
+
+// src/plugin.ts
+var SKINNING_COMPONENTS = [Skin];
+function registerSkinningComponents(world) {
+  const leases = SKINNING_COMPONENTS.map(
+    (component) => world.components.register(component).unwrap()
+  );
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+function skinningPlugin() {
+  return {
+    name: "skinning",
+    inject: ["world"],
+    apply(ctx) {
+      ctx.effect(() => registerSkinningComponents(ctx.world), "skinning/components");
+    }
+  };
+}
+
+// src/resolve-skin-joints.ts
+function resolveSkinJoints(jointPaths, names, skinEntity) {
+  const joints = [];
+  for (const path of jointPaths) {
+    const segments = path.split("/").filter(Boolean);
+    if (segments.length === 0) continue;
+    const failedAtIndex = segments.length - 1;
+    const entity = names.get(segments[failedAtIndex] ?? "");
+    if (entity === void 0) {
+      return {
+        ok: false,
+        error: new SkinJointPathUnresolvedError(skinEntity, segments, failedAtIndex)
+      };
+    }
+    joints.push(entity);
+  }
+  return { ok: true, value: new Uint32Array(joints) };
+}
+export {
+  JointCountMismatchError,
+  JointEntityDanglingError,
+  SkeletonResolveFailedError,
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+  resolveSkinJoints,
+  skeletonContribution,
+  skinContribution,
+  skinningPlugin
+};
+//# sourceMappingURL=index.mjs.map