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

package/dist/index.mjs

@@ -0,0 +1,1731 @@
+// ../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;
+}
+function toUnique(raw) {
+  return raw;
+}
+function unwrapHandle(h) {
+  return h;
+}
+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"
+]);
+var PACK_ERROR_HINTS = {
+  "pack-malformed-meta": "check guid is a valid RFC 4122 UUID; validate with: ajv validate -s schema/meta.schema.json -d <file>",
+  "pack-malformed-pack": "check all asset guid and refs[] fields are 36-char dash-form UUIDs; validate with pack.schema.json",
+  "pack-guid-malformed": "use AssetGuid.random() or a UUIDv7 generator; all GUID fields must be 36-char RFC 4122 dash-form",
+  "pack-orphan-meta": "remove the orphan .meta.json or add the missing source file next to it",
+  "pack-meta-missing": "run forgeax-engine-remote-asset scan --roots <dir> to list source files without .meta.json",
+  "pack-guid-collision": "run forgeax-engine-remote-asset verify to list all GUID collisions; each GUID must be globally unique",
+  "pack-cyclic-reference": "run forgeax-engine-remote-asset verify to print the cycle path; break the cycle by removing a refs[] entry",
+  "pack-subasset-index-out-of-range": "check subAssets[].sourceIndex does not exceed the actual sub-image count in the source file",
+  // === 1 new hint (feat-20260523-shader-template-instance-split M1-T02) ===
+  "payload-schema-mismatch": "material asset payload failed schema validation; check paramSchema entries all use valid types from MATERIAL_PARAM_TYPES and materialShader is a non-empty string",
+  // === 4 new hints (feat-20260608-scene-nesting-ecs-fication M1 / w8;
+  // plan-strategy D-8) ===
+  "pack-mount-localid-overlap": "check parent SceneAsset.mounts[].memberFirst windows do not overlap with each other or with entities[].localId; rebuild mount sidecar after the child SceneAsset reimport",
+  "pack-mount-count-mismatch": "mount.memberCount must equal the referenced child SceneAsset totalSlots (entities.length + sum(mounts[].memberCount) + mounts.length); rebuild mount sidecar via forgeax-engine-remote-asset verify <dir> after the child SceneAsset reimport",
+  "pack-mount-override-localid-out-of-range": "override.localId must be in [0, mount.memberCount); shrink the override or extend memberCount to match the child SceneAsset",
+  "pack-mount-override-unknown-field": "override.comp / override.field must match a defined component schema; check defineComponent registry or rebuild mount sidecar after the child SceneAsset reimport",
+  // === 2 new hints (feat-20260625-asset-meta-source-mount-prefix M1 / w1) ===
+  "pack-unknown-path": "the @name in source is not declared in package.json#forgeax.assets.paths; add it there or use a known name from the list in error.detail.knownNames",
+  "pack-malformed-path-ref": "source must be @<name>/<rest> where name is a key in package.json#forgeax.assets.paths; the resolved path must not escape the declared directory"
+};
+
+// src/assets/scene-decoder.ts
+var sceneAssetKind = {
+  kind: "scene"
+};
+function invalidScene(guid, reason) {
+  return err({
+    code: "asset-package-invalid",
+    expected: "a scene payload with an entities array",
+    hint: "recook the SceneAsset and publish its complete envelope",
+    detail: { guid, reason }
+  });
+}
+var sceneWireRefs = /* @__PURE__ */ new WeakMap();
+function resolveWireRef(refs, value, location) {
+  const guid = refs[value];
+  if (!Number.isInteger(value) || value < 0 || guid === void 0) {
+    return {
+      ok: false,
+      reason: `${location} references refs[${value}], but refs contains ${refs.length} entries`
+    };
+  }
+  return { ok: true, value: guid };
+}
+function resolveMounts(mounts, refs) {
+  if (mounts === void 0) return { ok: true, value: void 0 };
+  const resolved = [];
+  for (const mount of mounts) {
+    if (typeof mount.source !== "number" || !Number.isInteger(mount.source)) {
+      resolved.push(mount);
+      continue;
+    }
+    const ref = resolveWireRef(refs, mount.source, `mount ${mount.localId} source`);
+    if (!ref.ok) return ref;
+    resolved.push({ ...mount, source: ref.value });
+  }
+  return { ok: true, value: resolved };
+}
+function resolveSkinGuids(skinGuids, refs) {
+  if (skinGuids === void 0) return { ok: true, value: void 0 };
+  const resolved = [];
+  for (let index = 0; index < skinGuids.length; index += 1) {
+    const value = skinGuids[index];
+    if (typeof value === "string") {
+      resolved.push(value);
+      continue;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+      return { ok: false, reason: `skinGuids[${index}] is not a GUID or refs index` };
+    }
+    const ref = resolveWireRef(refs, value, `skinGuids[${index}]`);
+    if (!ref.ok) return ref;
+    resolved.push(ref.value);
+  }
+  return { ok: true, value: resolved };
+}
+function resolveSceneWireRefs(payload, refs) {
+  const entities = [];
+  for (const entity of payload.entities) {
+    const components = {};
+    for (const [componentName, rawFields] of Object.entries(entity.components)) {
+      components[componentName] = { ...rawFields };
+    }
+    entities.push({ localId: entity.localId, components });
+  }
+  const mounts = resolveMounts(payload.mounts, refs);
+  if (!mounts.ok) return mounts;
+  const skinGuids = resolveSkinGuids(
+    payload.skinGuids,
+    refs
+  );
+  if (!skinGuids.ok) return skinGuids;
+  return {
+    ok: true,
+    value: {
+      kind: "scene",
+      entities,
+      ...mounts.value === void 0 ? {} : { mounts: mounts.value },
+      ...skinGuids.value === void 0 ? {} : { skinGuids: skinGuids.value }
+    }
+  };
+}
+var sceneAssetDecoder = {
+  async decode({ envelope }) {
+    const payload = envelope.payload;
+    if (payload.kind !== "scene" || !Array.isArray(payload.entities)) {
+      return invalidScene(envelope.guid, "scene payload is missing entities");
+    }
+    const resolved = resolveSceneWireRefs(payload, envelope.refs);
+    if (!resolved.ok) return invalidScene(envelope.guid, resolved.reason);
+    sceneWireRefs.set(resolved.value, Object.freeze([...envelope.refs]));
+    return ok(resolved.value);
+  }
+};
+var sceneAssetContribution = {
+  kind: sceneAssetKind,
+  decoder: sceneAssetDecoder,
+  consumer: "Scene"
+};
+
+// src/components/children.ts
+import { defineRelationship } from "@forgeax/engine-ecs";
+var { source: ChildOf, target: Children } = defineRelationship({
+  sourceName: "ChildOf",
+  sourceField: "parent",
+  targetName: "Children",
+  targetField: "entities",
+  exclusive: true,
+  linkedSpawn: true
+});
+
+// src/collect-subtree.ts
+function collectSubtree(world, spawnRoot, visited) {
+  if (visited === void 0) visited = /* @__PURE__ */ new Set();
+  if (visited.has(spawnRoot)) return visited;
+  const queue = [spawnRoot];
+  visited.add(spawnRoot);
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const children = world.get(current, Children);
+    if (!children.ok) continue;
+    const entities = children.value.entities;
+    for (let index = 0; index < entities.length; index += 1) {
+      const child = entities[index];
+      if (visited.has(child)) continue;
+      visited.add(child);
+      queue.push(child);
+    }
+  }
+  return visited;
+}
+
+// src/components/morph-weights.ts
+import { defineComponent } from "@forgeax/engine-ecs";
+var MorphWeights = defineComponent("MorphWeights", {
+  weights: { type: "array<f32>" }
+});
+
+// src/components/name.ts
+import { defineComponent as defineComponent2 } from "@forgeax/engine-ecs";
+var Name = defineComponent2("Name", { value: { type: "string" } });
+
+// src/components/transform.ts
+import { defineComponent as defineComponent3 } from "@forgeax/engine-ecs";
+var IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+var Transform = defineComponent3("Transform", {
+  pos: { type: "array<f32, 3>", default: new Float32Array([0, 0, 0]) },
+  // Component order [x, y, z, w] end to end (glTF-aligned; E6).
+  quat: { type: "array<f32, 4>", default: new Float32Array([0, 0, 0, 1]) },
+  scale: { type: "array<f32, 3>", default: new Float32Array([1, 1, 1]) },
+  // `world` is field-level transient (D-5): scene collect skips it. The resolved
+  // world mat4 is derived by the propagate kernel from the persisted local TRS
+  // each frame, so serializing it would store reconstructable data (SSOT: local
+  // TRS). Round-trip re-derives an equivalent world on the first propagate pass.
+  world: { type: "array<f32, 16>", default: IDENTITY_MAT4, transient: true }
+});
+
+// src/errors.ts
+import { ComponentNotDefinedError } from "@forgeax/engine-ecs/projection";
+var SceneError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    super(`[SceneError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = "SceneError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+
+// src/instances/collect-profile.ts
+var SCENE_COLLECT_PROFILE = Object.freeze({
+  includeComponent: (_componentName, transient) => !transient,
+  includeField: (_componentName, _fieldName, transient) => !transient
+});
+
+// src/instances/externalization.ts
+function sharedKind(type) {
+  if (type?.startsWith("shared<")) return "one";
+  if (type?.startsWith("array<shared<")) return "many";
+  return void 0;
+}
+function overrideGuids(override, resolveSchema) {
+  const schema = resolveSchema(override.comp);
+  const values = override.field !== void 0 ? [[override.field, override.value]] : override.value !== null && typeof override.value === "object" && !Array.isArray(override.value) ? Object.entries(override.value) : [];
+  return values.flatMap(([field, value]) => {
+    const kind = sharedKind(schema?.[field]);
+    if (kind === "one" && typeof value === "string") return [{ field, guid: value }];
+    if (kind === "many" && Array.isArray(value)) {
+      return value.flatMap((item) => typeof item === "string" ? [{ field, guid: item }] : []);
+    }
+    return [];
+  });
+}
+function externalizeSceneAsset(scene, resolveSchema) {
+  const refs = [];
+  const indexByGuid = /* @__PURE__ */ new Map();
+  const addRef = (guid, sourceField, sceneEntityId) => {
+    const prior = indexByGuid.get(guid);
+    if (prior !== void 0) return prior;
+    const index = refs.length;
+    refs.push({ guid, sourceField, ...sceneEntityId === void 0 ? {} : { sceneEntityId } });
+    indexByGuid.set(guid, index);
+    return index;
+  };
+  const entities = scene.entities.map((entity) => {
+    const components = {};
+    for (const componentName of Object.keys(entity.components)) {
+      const schema = resolveSchema(componentName);
+      const source = entity.components[componentName];
+      if (source === void 0) continue;
+      const fields = {};
+      for (const fieldName of Object.keys(source)) {
+        const value = source[fieldName];
+        if (value === void 0) continue;
+        const kind = sharedKind(schema?.[fieldName]);
+        if (kind === "one" && typeof value === "string") {
+          fields[fieldName] = addRef(value, { componentName, fieldName }, entity.localId);
+        } else if (kind === "many" && Array.isArray(value)) {
+          fields[fieldName] = value.map(
+            (item, arrayIndex) => typeof item === "string" ? addRef(item, { componentName, fieldName, arrayIndex }, entity.localId) : item
+          );
+        } else {
+          fields[fieldName] = value;
+        }
+      }
+      if (Object.keys(fields).length > 0 || Object.keys(schema ?? {}).length === 0) {
+        components[componentName] = fields;
+      }
+    }
+    return { localId: entity.localId, components };
+  });
+  const mounts = scene.mounts?.map((mount) => {
+    const source = typeof mount.source === "string" ? addRef(
+      mount.source,
+      { componentName: "SceneInstance", fieldName: "source" },
+      mount.localId
+    ) : mount.source;
+    for (const { field, guid } of (mount.overrides ?? []).flatMap(
+      (override) => overrideGuids(override, resolveSchema)
+    )) {
+      addRef(guid, { componentName: "SceneInstance", fieldName: `overrides.${field}` });
+    }
+    return {
+      localId: mount.localId,
+      source,
+      memberFirst: mount.memberFirst,
+      memberCount: mount.memberCount,
+      ...mount.parent === void 0 ? {} : { parent: mount.parent },
+      ...mount.publicationFence === void 0 ? {} : { publicationFence: mount.publicationFence },
+      ...mount.overrides === void 0 ? {} : { overrides: mount.overrides.map((item) => ({ ...item })) }
+    };
+  });
+  for (const [arrayIndex, guid] of (scene.skinGuids ?? []).entries()) {
+    if (typeof guid !== "string") return err({ field: "skinGuids", value: guid });
+    addRef(guid, { componentName: "<scene>", fieldName: "skinGuids", arrayIndex });
+  }
+  return ok({
+    payload: {
+      entities,
+      ...mounts === void 0 || mounts.length === 0 ? {} : { mounts },
+      ...scene.skinGuids === void 0 ? {} : { skinGuids: scene.skinGuids.map((guid) => indexByGuid.get(guid)) }
+    },
+    refs
+  });
+}
+
+// src/instances/scene-instances.ts
+import {
+  ENTITY_NULL_RAW
+} from "@forgeax/engine-ecs";
+import { classifyEntityField, remapEntityFieldValue } from "@forgeax/engine-ecs/externalization";
+import { componentSchema } from "@forgeax/engine-ecs/internal";
+import { fillComponentDefaults, StaleEntityError } from "@forgeax/engine-ecs/projection";
+var entityIndex = (entity) => entity & 16777215;
+var entityGeneration = (entity) => entity >>> 24 & 255;
+var sceneWorldStates = /* @__PURE__ */ new WeakMap();
+function sceneWorldState(world) {
+  const current = sceneWorldStates.get(world);
+  if (current !== void 0) return current;
+  const created = { resolver: null, statePayloads: /* @__PURE__ */ new Map() };
+  sceneWorldStates.set(world, created);
+  return created;
+}
+function worldSetSceneAssetResolver(world, resolver) {
+  sceneWorldState(world).resolver = resolver;
+}
+function worldGetSceneAssetResolver(world) {
+  return sceneWorldState(world).resolver;
+}
+function worldInstantiateScene(world, handle, parent) {
+  const stack = /* @__PURE__ */ new Set();
+  const diagnostics = [];
+  const r = worldInstantiateSceneRec(world, handle, parent, stack, diagnostics);
+  if (!r.ok) return r;
+  return ok({ root: r.value, diagnostics });
+}
+function worldInstantiateScenePayload(world, asset, parent) {
+  const handle = world.allocSharedRef("SceneAsset", asset);
+  try {
+    return worldInstantiateScene(world, handle, parent);
+  } finally {
+    world.sharedRefs.release(handle);
+  }
+}
+function worldInstantiateSceneFlat(world, handle) {
+  const stack = /* @__PURE__ */ new Set();
+  const diagnostics = [];
+  const handleKey = unwrapHandle(handle);
+  const resolved = worldResolveSceneAsset(world, handle);
+  if (!resolved.ok) return resolved;
+  stack.add(handleKey);
+  let r;
+  try {
+    r = worldInstantiateSceneAssetFlat(world, handle, resolved.value, stack, diagnostics);
+  } finally {
+    stack.delete(handleKey);
+  }
+  if (!r.ok) return r;
+  return ok({ ...r.value, diagnostics });
+}
+function worldInstantiateSceneRec(world, handle, parent, stack, diagnostics) {
+  const handleKey = unwrapHandle(handle);
+  if (stack.has(handleKey)) {
+    const cycleArr = [];
+    for (const k of stack) cycleArr.push(String(k));
+    cycleArr.push(String(handleKey));
+    const detail = {
+      code: "pack-cyclic-reference",
+      kind: "mount-asset",
+      cycle: cycleArr
+    };
+    return err({
+      code: "pack-cyclic-reference",
+      expected: "acyclic SceneAsset mount graph",
+      hint: PACK_ERROR_HINTS["pack-cyclic-reference"],
+      detail
+    });
+  }
+  const resolved = worldResolveSceneAsset(world, handle);
+  if (!resolved.ok) return resolved;
+  const asset = resolved.value;
+  stack.add(handleKey);
+  try {
+    return worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics);
+  } finally {
+    stack.delete(handleKey);
+  }
+}
+function worldResolveSceneAsset(world, handle) {
+  const r = world.sharedRefs.resolve(handle);
+  if (!r.ok) {
+    return err(r.error);
+  }
+  return ok(r.value);
+}
+function worldSpawnSceneMembers(world, handle, asset, stack, diagnostics) {
+  const sceneInstanceToken = world.components.resolve("SceneInstance");
+  if (sceneInstanceToken === void 0) {
+    return err(new ComponentNotDefinedError("SceneInstance"));
+  }
+  const childOfToken = world.components.resolve("ChildOf");
+  const ownEntities = asset.entities;
+  const ownMounts = asset.mounts ?? [];
+  const memberSum = ownMounts.reduce((s, m) => s + m.memberCount, 0);
+  const countBaseline = ownEntities.length + ownMounts.length + memberSum;
+  let maxLocalId = ownEntities.reduce((m, e) => Math.max(m, e.localId), -1);
+  for (const mount of ownMounts) {
+    maxLocalId = Math.max(maxLocalId, mount.localId);
+    const last = mount.memberFirst + mount.memberCount - 1;
+    maxLocalId = Math.max(maxLocalId, last);
+  }
+  const totalSlots = Math.max(countBaseline, maxLocalId + 1);
+  {
+    const claims = /* @__PURE__ */ new Map();
+    const overlapLids = /* @__PURE__ */ new Set();
+    const overlapSources = [];
+    const claim = (lid, src) => {
+      const prior = claims.get(lid);
+      if (prior !== void 0) {
+        if (!overlapLids.has(lid)) {
+          overlapLids.add(lid);
+          overlapSources.push(prior);
+          overlapSources.push(src);
+        } else {
+          overlapSources.push(src);
+        }
+        return;
+      }
+      claims.set(lid, src);
+    };
+    for (const ent of ownEntities) {
+      claim(ent.localId, `entities[${ent.localId}]`);
+    }
+    for (const mount of ownMounts) {
+      const mLid = mount.localId;
+      claim(mLid, `mount[${mLid}]`);
+      const first = mount.memberFirst;
+      for (let k = 0; k < mount.memberCount; k += 1) {
+        claim(first + k, `mount[${mLid}].member[${k}]`);
+      }
+    }
+    if (overlapLids.size > 0) {
+      const overlapping = Array.from(overlapLids).sort((a, b) => a - b);
+      return err({
+        code: "pack-mount-localid-overlap",
+        expected: "each LocalEntityId claimed by exactly one entity or mount slot",
+        hint: PACK_ERROR_HINTS["pack-mount-localid-overlap"],
+        detail: {
+          code: "pack-mount-localid-overlap",
+          overlapping,
+          sources: overlapSources
+        }
+      });
+    }
+  }
+  const mapping = new Uint32Array(totalSlots).fill(ENTITY_NULL_RAW);
+  const entityToLocalId = /* @__PURE__ */ new Map();
+  const rootEntities = [];
+  const mountEntities = [];
+  const mountEntitiesNeedingRootParent = [];
+  const mountEntitiesNeedingDeferredParent = [];
+  const mountInstances = [];
+  for (const mount of ownMounts) {
+    const overrideValidationRes = worldValidateMountOverrides(world, mount);
+    if (!overrideValidationRes.ok) {
+      return overrideValidationRes;
+    }
+    const mountLid = mount.localId;
+    const mountSpawnRes = worldSpawnMountEntity(world, mount, mapping, diagnostics);
+    if (!mountSpawnRes.ok) return mountSpawnRes;
+    const mountEntity = mountSpawnRes.value;
+    mountEntities.push(mountEntity);
+    mapping[mountLid] = mountEntity;
+    const childHandleRes = worldResolveMountSource(world, mount.source, handle);
+    if (!childHandleRes.ok) return childHandleRes;
+    const childHandle = childHandleRes.value;
+    const childRes = worldInstantiateSceneRec(world, childHandle, mountEntity, stack, diagnostics);
+    if (!childRes.ok) return childRes;
+    const childInstRes = world.get(childRes.value, sceneInstanceToken);
+    if (!childInstRes.ok) return childInstRes;
+    const childMapping = childInstRes.value.mapping;
+    mountInstances.push({ mount, root: childRes.value, mapping: childMapping });
+    if (childMapping.length !== mount.memberCount) {
+      return err({
+        code: "pack-mount-count-mismatch",
+        expected: "mount.memberCount === child SceneAsset totalSlots",
+        hint: PACK_ERROR_HINTS["pack-mount-count-mismatch"],
+        detail: {
+          code: "pack-mount-count-mismatch",
+          mountLocalId: mountLid,
+          declared: mount.memberCount,
+          actual: childMapping.length
+        }
+      });
+    }
+    const window = mount.memberCount;
+    for (let k = 0; k < window; k += 1) {
+      mapping[mount.memberFirst + k] = childMapping[k] ?? ENTITY_NULL_RAW;
+    }
+    if (childOfToken !== void 0) {
+      if (mount.parent !== void 0) {
+        const parentSlot = mount.parent;
+        const parentEntity = mapping[parentSlot];
+        if (parentEntity !== void 0 && parentEntity !== ENTITY_NULL_RAW) {
+          const r = world.addComponent(mountEntity, {
+            component: childOfToken,
+            data: { parent: parentEntity }
+          });
+          if (!r.ok) {
+            const set = world.set(mountEntity, childOfToken, {
+              parent: parentEntity
+            });
+            if (!set.ok) return set;
+          }
+        } else {
+          mountEntitiesNeedingDeferredParent.push([mountEntity, parentSlot]);
+        }
+      } else {
+        mountEntitiesNeedingRootParent.push(mountEntity);
+      }
+    }
+  }
+  const order = sceneTopoSort(ownEntities);
+  for (const idx of order) {
+    const node = ownEntities[idx];
+    if (node === void 0) continue;
+    const lid = node.localId;
+    const compDataRes = worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics);
+    if (!compDataRes.ok) return compDataRes;
+    const sp = world.spawn(
+      ...compDataRes.value
+    );
+    if (!sp.ok) return sp;
+    const e = sp.value;
+    mapping[lid] = e;
+    entityToLocalId.set(e, lid);
+    if (node.components.ChildOf === void 0) {
+      rootEntities.push(e);
+    }
+  }
+  if (childOfToken !== void 0) {
+    for (const [mountEntity, parentSlot] of mountEntitiesNeedingDeferredParent) {
+      const parentEntity = mapping[parentSlot];
+      if (parentEntity === void 0 || parentEntity === ENTITY_NULL_RAW) continue;
+      const set = world.set(mountEntity, childOfToken, { parent: parentEntity });
+      if (!set.ok) {
+        const r = world.addComponent(mountEntity, {
+          component: childOfToken,
+          data: { parent: parentEntity }
+        });
+        if (!r.ok) return r;
+      }
+    }
+  }
+  return ok({
+    mapping,
+    entityToLocalId,
+    rootEntities,
+    mountEntitiesNeedingRootParent,
+    mountEntities,
+    mountInstances,
+    totalSlots
+  });
+}
+function worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics) {
+  const sceneInstanceToken = world.components.resolve("SceneInstance");
+  if (sceneInstanceToken === void 0) {
+    return err(new ComponentNotDefinedError("SceneInstance"));
+  }
+  const childOfToken = world.components.resolve("ChildOf");
+  const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
+  if (!membersRes.ok) return membersRes;
+  const { mapping, entityToLocalId, rootEntities, mountEntitiesNeedingRootParent, totalSlots } = membersRes.value;
+  const { mountInstances } = membersRes.value;
+  const ownMounts = asset.mounts ?? [];
+  let stateRef;
+  stateRef = world.allocUniqueRef("SceneInstanceState", null, () => {
+    sceneWorldState(world).statePayloads.delete(Number(stateRef));
+  });
+  const mappingPlain = Array.from(mapping);
+  const rootComponents = [
+    {
+      component: sceneInstanceToken,
+      data: {
+        source: handle,
+        mapping: mappingPlain,
+        state: stateRef
+      }
+    }
+  ];
+  const transformToken = world.components.resolve("Transform");
+  if (transformToken !== void 0) {
+    rootComponents.push({
+      component: transformToken,
+      data: {}
+    });
+  }
+  const rootSpawn = world.spawn(
+    ...rootComponents
+  );
+  if (!rootSpawn.ok) {
+    return rootSpawn;
+  }
+  const rootEntity = rootSpawn.value;
+  const overrides = /* @__PURE__ */ new Map();
+  for (const mount of ownMounts) {
+    for (const ov of mount.overrides ?? []) {
+      const lid = ov.localId;
+      let fieldMap = overrides.get(lid);
+      if (fieldMap === void 0) {
+        fieldMap = /* @__PURE__ */ new Map();
+        overrides.set(lid, fieldMap);
+      }
+      fieldMap.set(mountOverrideStateKey(ov), ov);
+      const memberEntityRaw = mapping[lid];
+      if (memberEntityRaw !== void 0 && memberEntityRaw !== ENTITY_NULL_RAW) {
+        const memberEntity = memberEntityRaw;
+        const applyRes = worldApplyMountOverride(world, memberEntity, ov);
+        if (!applyRes.ok) {
+          return applyRes;
+        }
+      }
+    }
+  }
+  const detached = /* @__PURE__ */ new Set();
+  const state = {
+    source: handle,
+    entityToLocalId,
+    detachedLocalIds: detached,
+    // Convert overrides Map<LocalEntityId, Map<string, MountOverride>>
+    // into Map<LocalEntityId, Map<string, SceneInstanceOverrideRecord>>
+    overrides: worldMountOverridesToStateMap(overrides),
+    rootEntities,
+    mountRoots: mountInstances.map(({ root }) => root),
+    totalSlots,
+    mountTimeOverrides: ownMounts.flatMap((m) => m.overrides ?? [])
+  };
+  worldSetUniqueRefPayload(world, stateRef, state);
+  if (childOfToken !== void 0) {
+    for (const rootE of rootEntities) {
+      const has = world.get(rootE, childOfToken);
+      if (!has.ok) {
+        const r = world.addComponent(rootE, {
+          component: childOfToken,
+          data: { parent: rootEntity }
+        });
+        if (!r.ok) return r;
+      }
+    }
+    for (const mountE of mountEntitiesNeedingRootParent) {
+      const set = world.set(mountE, childOfToken, { parent: rootEntity });
+      if (!set.ok) {
+        const r = world.addComponent(mountE, {
+          component: childOfToken,
+          data: { parent: rootEntity }
+        });
+        if (!r.ok) return r;
+      }
+    }
+    if (parent !== void 0) {
+      const r = world.addComponent(rootEntity, {
+        component: childOfToken,
+        data: { parent }
+      });
+      if (!r.ok) return r;
+    }
+  }
+  return ok(rootEntity);
+}
+function worldInstantiateSceneAssetFlat(world, handle, asset, stack, diagnostics) {
+  const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
+  if (!membersRes.ok) return membersRes;
+  const { rootEntities, mountEntitiesNeedingRootParent, mountEntities, mountInstances } = membersRes.value;
+  const childOfToken = world.components.resolve("ChildOf");
+  for (const { mount, root, mapping: childMapping } of mountInstances) {
+    const childStateRes = worldGetSceneInstanceState(world, root);
+    if (!childStateRes.ok) return childStateRes;
+    for (const ov of mount.overrides ?? []) {
+      const childLocalId = ov.localId - mount.memberFirst;
+      const memberEntityRaw = childMapping[childLocalId];
+      if (memberEntityRaw === void 0 || memberEntityRaw === ENTITY_NULL_RAW) continue;
+      const memberEntity = memberEntityRaw;
+      const applyRes = worldApplyMountOverride(world, memberEntity, ov);
+      if (!applyRes.ok) {
+        return applyRes;
+      }
+      let fieldMap = childStateRes.value.overrides.get(childLocalId);
+      if (fieldMap === void 0) {
+        fieldMap = /* @__PURE__ */ new Map();
+        childStateRes.value.overrides.set(childLocalId, fieldMap);
+      }
+      fieldMap.set(mountOverrideStateKey(ov), {
+        comp: ov.comp,
+        ...ov.field === void 0 ? {} : { field: ov.field },
+        value: ov.value
+      });
+    }
+  }
+  if (childOfToken !== void 0) {
+    for (const mountE of mountEntitiesNeedingRootParent) {
+      const co = world.get(mountE, childOfToken);
+      if (co.ok && co.value.parent === ENTITY_NULL_RAW) {
+        world.removeComponent(mountE, childOfToken);
+      }
+    }
+  }
+  return ok({ roots: [...rootEntities, ...mountEntitiesNeedingRootParent], mountEntities });
+}
+function worldBuildSceneEntityComponentDatas(world, node, mapping, diagnostics) {
+  const out = [];
+  const nodeLocalId = node.localId;
+  for (const compName of Object.keys(node.components)) {
+    const token = world.components.resolve(compName);
+    if (token === void 0) {
+      return err(new ComponentNotDefinedError(compName));
+    }
+    const raw = node.components[compName] ?? {};
+    const schema = componentSchema(token);
+    const remappedRaw = {};
+    for (const fieldName of Object.keys(raw)) {
+      const fieldType = schema[fieldName];
+      if (fieldType === void 0) {
+        diagnostics.push({ component: compName, field: fieldName, localId: nodeLocalId });
+        continue;
+      }
+      const value = raw[fieldName];
+      const kind = classifyEntityField(token, fieldName);
+      if (kind !== null) {
+        const sceneRemap = (localId) => {
+          if (localId < 0 || localId >= mapping.length) return ENTITY_NULL_RAW;
+          const live = mapping[localId];
+          return live === void 0 || live === ENTITY_NULL_RAW ? ENTITY_NULL_RAW : live;
+        };
+        remappedRaw[fieldName] = remapEntityFieldValue(value, kind, sceneRemap);
+      } else {
+        remappedRaw[fieldName] = value;
+      }
+    }
+    const filled = fillComponentDefaults(token, remappedRaw);
+    out.push({ component: token, data: filled });
+  }
+  return ok(out);
+}
+function worldApplyMountOverride(world, member, ov) {
+  const ovToken = world.components.resolve(ov.comp);
+  if (ovToken === void 0) return ok(void 0);
+  if (ov.field !== void 0) {
+    return world.set(member, ovToken, { [ov.field]: ov.value });
+  }
+  const rawValue = ov.value ?? {};
+  const filled = fillComponentDefaults(ovToken, rawValue);
+  const has = world.get(member, ovToken);
+  if (has.ok) {
+    return world.set(member, ovToken, filled);
+  }
+  return world.addComponent(member, { component: ovToken, data: filled });
+}
+function worldValidateMountOverrides(world, mount) {
+  const overrides = mount.overrides;
+  if (overrides === void 0) return ok(void 0);
+  const memberFirst = mount.memberFirst;
+  const memberCount = mount.memberCount;
+  const memberLast = memberFirst + memberCount;
+  const mountLid = mount.localId;
+  for (const ov of overrides) {
+    const ovLid = ov.localId;
+    if (ovLid < memberFirst || ovLid >= memberLast) {
+      return err({
+        code: "pack-mount-override-localid-out-of-range",
+        expected: `override.localId in [${memberFirst}, ${memberLast})`,
+        hint: PACK_ERROR_HINTS["pack-mount-override-localid-out-of-range"],
+        detail: {
+          code: "pack-mount-override-localid-out-of-range",
+          overrideLocalId: ovLid,
+          mountLocalId: mountLid,
+          memberCount
+        }
+      });
+    }
+    const ovToken = world.components.resolve(ov.comp);
+    if (ov.field !== void 0) {
+      if (ovToken !== void 0) {
+        const schema = componentSchema(ovToken);
+        if (!(ov.field in schema)) {
+          return err({
+            code: "pack-mount-override-unknown-field",
+            expected: `override.field defined on component '${ov.comp}'`,
+            hint: PACK_ERROR_HINTS["pack-mount-override-unknown-field"],
+            detail: {
+              code: "pack-mount-override-unknown-field",
+              comp: ov.comp,
+              field: ov.field,
+              mountLocalId: mountLid
+            }
+          });
+        }
+      }
+    } else {
+      if (ovToken === void 0) {
+        return err(new ComponentNotDefinedError(ov.comp));
+      }
+      const schema = componentSchema(ovToken);
+      const valueMap = ov.value ?? {};
+      for (const key of Object.keys(valueMap)) {
+        if (!(key in schema)) {
+          return err({
+            code: "pack-mount-override-unknown-field",
+            expected: `override.value keys defined on component '${ov.comp}'`,
+            hint: PACK_ERROR_HINTS["pack-mount-override-unknown-field"],
+            detail: {
+              code: "pack-mount-override-unknown-field",
+              comp: ov.comp,
+              field: key,
+              mountLocalId: mountLid
+            }
+          });
+        }
+      }
+    }
+  }
+  return ok(void 0);
+}
+function worldSpawnMountEntity(world, mount, mapping, diagnostics) {
+  const fakeNode = {
+    localId: mount.localId,
+    components: mount.components ?? {}
+  };
+  const cdRes = worldBuildSceneEntityComponentDatas(world, fakeNode, mapping, diagnostics);
+  if (!cdRes.ok) return cdRes;
+  const transformToken = world.components.resolve("Transform");
+  if (transformToken !== void 0) {
+    const hasTransform = cdRes.value.some((c) => c.component === transformToken);
+    if (!hasTransform) {
+      cdRes.value.push({ component: transformToken, data: {} });
+    }
+  }
+  if (cdRes.value.length === 0) {
+    const childOfToken = world.components.resolve("ChildOf");
+    if (childOfToken === void 0) {
+      return err(new ComponentNotDefinedError("ChildOf"));
+    }
+    cdRes.value.push({
+      component: childOfToken,
+      data: { parent: ENTITY_NULL_RAW }
+    });
+  }
+  return world.spawn(...cdRes.value);
+}
+function worldResolveMountSource(world, source, parentHandle) {
+  const resolver = worldGetSceneAssetResolver(world);
+  if (resolver === null) {
+    return err({
+      code: "stale-entity",
+      expected: "wired SceneAssetResolver (auto-wired by engine.assets.instantiate)",
+      hint: "engine.assets.instantiate sugar wires this for you; call worldSetSceneAssetResolver before nested scene expansion.",
+      detail: { entity: 0, slot: 0, generation: 0 }
+    });
+  }
+  const r = resolver(source, parentHandle);
+  if (!r.ok) {
+    return err(r.error);
+  }
+  return ok(r.value);
+}
+function worldMountOverridesToStateMap(src) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [lid, fields] of src) {
+    const m = /* @__PURE__ */ new Map();
+    for (const [k, v] of fields) {
+      m.set(k, {
+        comp: v.comp,
+        value: v.value,
+        ...v.field !== void 0 ? { field: v.field } : {}
+      });
+    }
+    out.set(lid, m);
+  }
+  return out;
+}
+function worldSetUniqueRefPayload(world, handle, payload) {
+  sceneWorldState(world).statePayloads.set(Number(handle), payload);
+}
+function worldResolveSceneInstanceStatePayload(world, root) {
+  const sceneInstanceToken = world.components.resolve("SceneInstance");
+  if (sceneInstanceToken === void 0) {
+    return err(new ComponentNotDefinedError("SceneInstance"));
+  }
+  const r = world.get(root, sceneInstanceToken);
+  if (!r.ok) return r;
+  const stateRefRaw = r.value.state;
+  const stateRefHandle = toUnique(stateRefRaw);
+  const payload = sceneWorldState(world).statePayloads.get(Number(stateRefHandle));
+  if (payload === void 0) {
+    return err(
+      new StaleEntityError(root, entityIndex(root), entityGeneration(root), {
+        operation: "resolveSceneInstanceState",
+        component: "SceneInstance",
+        expectedGeneration: entityGeneration(root),
+        actualGeneration: entityGeneration(root)
+      })
+    );
+  }
+  return ok(payload);
+}
+function worldGetSceneInstanceState(world, root) {
+  return worldResolveSceneInstanceStatePayload(world, root);
+}
+function worldDespawnScene(world, root, opts) {
+  const dRes = worldDespawnDescendants(world, root, opts);
+  if (!dRes.ok) return dRes;
+  const drop = world.despawn(root);
+  if (!drop.ok) return drop;
+  return ok(dRes.value + 1);
+}
+function worldDespawnDescendants(world, root, opts) {
+  let detached = null;
+  let entityToLocalId = null;
+  if (opts?.keepDetached === true) {
+    const stateRes = worldResolveSceneInstanceStatePayload(world, root);
+    if (stateRes.ok) {
+      detached = stateRes.value.detachedLocalIds;
+      entityToLocalId = stateRes.value.entityToLocalId;
+    }
+  }
+  let count = 0;
+  const list = [];
+  const seen = /* @__PURE__ */ new Set();
+  const collect = (anchor) => {
+    for (const e of world.iterDescendants(anchor)) {
+      const raw = e;
+      if (!seen.has(raw)) {
+        seen.add(raw);
+        list.push(e);
+      }
+    }
+    const stateRes = worldResolveSceneInstanceStatePayload(world, anchor);
+    if (!stateRes.ok) return;
+    for (const e of stateRes.value.entityToLocalId.keys()) {
+      const raw = e;
+      if (!seen.has(raw)) {
+        seen.add(raw);
+        list.push(e);
+      }
+    }
+    for (const nestedRoot of stateRes.value.mountRoots) {
+      const raw = nestedRoot;
+      if (seen.has(raw)) continue;
+      seen.add(raw);
+      list.push(nestedRoot);
+      collect(nestedRoot);
+    }
+  };
+  collect(root);
+  const childOfToken = world.components.resolve("ChildOf");
+  const owned = new Set(list.map((entity) => Number(entity)));
+  const ownedDepth = (entity) => {
+    if (childOfToken === void 0) return 0;
+    let current = entity;
+    let depth = 0;
+    const visited = /* @__PURE__ */ new Set();
+    while (!visited.has(Number(current))) {
+      visited.add(Number(current));
+      const parentRes = world.get(current, childOfToken);
+      if (!parentRes.ok) break;
+      const parent = parentRes.value.parent;
+      if (!owned.has(Number(parent))) break;
+      depth += 1;
+      current = parent;
+    }
+    return depth;
+  };
+  list.sort((a, b) => ownedDepth(b) - ownedDepth(a));
+  for (const e of list) {
+    if (detached !== null) {
+      const lid = entityToLocalId?.get(e);
+      if (lid !== void 0 && detached.has(lid)) {
+        if (childOfToken !== void 0) {
+          world.removeComponent(e, childOfToken);
+        }
+        continue;
+      }
+    }
+    const r = world.despawn(e);
+    if (!r.ok) {
+      if (r.error.code === "stale-entity") continue;
+      return r;
+    }
+    count += 1;
+  }
+  return ok(count);
+}
+function worldSetSceneOverride(world, root, member, component, field, value) {
+  const stateRes = worldResolveSceneInstanceStatePayload(world, root);
+  if (!stateRes.ok) return stateRes;
+  const state = stateRes.value;
+  const lid = state.entityToLocalId.get(member);
+  if (lid === void 0) {
+    return err(
+      new StaleEntityError(
+        member,
+        entityIndex(member),
+        entityGeneration(member),
+        {
+          operation: "setSceneOverride",
+          component: component.name,
+          expectedGeneration: entityGeneration(member),
+          actualGeneration: entityGeneration(member)
+        }
+      )
+    );
+  }
+  const schemaType = componentSchema(component)[field];
+  if (schemaType !== void 0 && isPrimitiveScalarFieldType(schemaType)) {
+    const expectJsType = primitiveJsType(schemaType);
+    const actualJsType = typeof value;
+    if (expectJsType !== actualJsType) {
+      return err({
+        code: "scene-override-type-mismatch",
+        expected: `value typeof === ${expectJsType}`,
+        hint: `setSceneOverride(${component.name}.${field}) expected ${expectJsType}, got ${actualJsType}; coerce or pick a different override path.`,
+        detail: {
+          code: "scene-override-type-mismatch",
+          comp: component.name,
+          field,
+          expectedType: schemaType,
+          actualType: actualJsType
+        }
+      });
+    }
+  }
+  const setRes = world.set(member, component, { [field]: value });
+  if (!setRes.ok) return setRes;
+  let fieldMap = state.overrides.get(lid);
+  if (fieldMap === void 0) {
+    fieldMap = /* @__PURE__ */ new Map();
+    state.overrides.set(lid, fieldMap);
+  }
+  fieldMap.set(`${component.name}:${field}`, {
+    comp: component.name,
+    field,
+    value
+  });
+  return ok(void 0);
+}
+function worldRemoveSceneOverride(world, root, member, component, field) {
+  const stateRes = worldResolveSceneInstanceStatePayload(world, root);
+  if (!stateRes.ok) return stateRes;
+  const state = stateRes.value;
+  const lid = state.entityToLocalId.get(member);
+  if (lid === void 0) return ok(void 0);
+  const fieldMap = state.overrides.get(lid);
+  if (fieldMap !== void 0) {
+    fieldMap.delete(`${component.name}:${field}`);
+    if (fieldMap.size === 0) state.overrides.delete(lid);
+  }
+  const assetRes = worldResolveSceneAsset(world, state.source);
+  if (!assetRes.ok) return assetRes;
+  const node = assetRes.value.entities.find(
+    (n) => n.localId === lid
+  );
+  const layer1 = node?.components[component.name];
+  if (layer1 !== void 0 && field in layer1) {
+    const r = world.set(member, component, { [field]: layer1[field] });
+    if (!r.ok) return r;
+  }
+  return ok(void 0);
+}
+function worldDetachSceneMember(world, root, member) {
+  const sceneInstanceToken = world.components.resolve("SceneInstance");
+  if (sceneInstanceToken === void 0) {
+    return err(new ComponentNotDefinedError("SceneInstance"));
+  }
+  const stateRes = worldResolveSceneInstanceStatePayload(world, root);
+  if (!stateRes.ok) return stateRes;
+  const state = stateRes.value;
+  const lid = state.entityToLocalId.get(member);
+  if (lid === void 0) return ok(void 0);
+  state.detachedLocalIds.add(lid);
+  return ok(void 0);
+}
+function worldReattachSceneMember(world, root, member) {
+  const stateRes = worldResolveSceneInstanceStatePayload(world, root);
+  if (!stateRes.ok) return stateRes;
+  const state = stateRes.value;
+  const lid = state.entityToLocalId.get(member);
+  if (lid === void 0) return ok(void 0);
+  state.detachedLocalIds.delete(lid);
+  return ok(void 0);
+}
+function worldGetSceneAssetForInstance(world, root) {
+  const stateRes = worldResolveSceneInstanceStatePayload(world, root);
+  if (!stateRes.ok) return stateRes;
+  return ok(stateRes.value.source);
+}
+function sceneTopoSort(nodes) {
+  const n = nodes.length;
+  const childrenOf = Array.from({ length: n }, () => []);
+  const indeg = new Uint32Array(n);
+  const localIdToIdx = /* @__PURE__ */ new Map();
+  for (let i = 0; i < n; i += 1) {
+    const node = nodes[i];
+    if (node === void 0) continue;
+    localIdToIdx.set(node.localId, i);
+  }
+  for (let i = 0; i < n; i += 1) {
+    const node = nodes[i];
+    if (node === void 0) continue;
+    const child = node.components.ChildOf;
+    if (child === void 0) continue;
+    const p = child.parent;
+    if (typeof p === "number") {
+      const parentIdx = localIdToIdx.get(p);
+      if (parentIdx !== void 0 && parentIdx !== i) {
+        childrenOf[parentIdx]?.push(i);
+        indeg[i] = (indeg[i] ?? 0) + 1;
+      }
+    }
+  }
+  const order = [];
+  const queue = [];
+  for (let i = 0; i < n; i += 1) if ((indeg[i] ?? 0) === 0) queue.push(i);
+  while (queue.length > 0) {
+    const head = queue.shift();
+    if (head === void 0) break;
+    order.push(head);
+    for (const c of childrenOf[head] ?? []) {
+      indeg[c] = (indeg[c] ?? 0) - 1;
+      if ((indeg[c] ?? 0) === 0) queue.push(c);
+    }
+  }
+  for (let i = 0; i < n; i += 1) {
+    if (!order.includes(i) && nodes[i] !== void 0) order.push(i);
+  }
+  return order;
+}
+function mountOverrideStateKey(ov) {
+  return ov.field !== void 0 ? `${ov.comp}:${ov.field}` : ov.comp;
+}
+function isPrimitiveScalarFieldType(fieldType) {
+  if (fieldType === "f32" || fieldType === "f64" || fieldType === "u32" || fieldType === "i32" || fieldType === "u8" || fieldType === "i8" || fieldType === "u16" || fieldType === "i16" || fieldType === "bool" || fieldType === "string") {
+    return true;
+  }
+  if (fieldType.startsWith("enum<")) return true;
+  return false;
+}
+function primitiveJsType(fieldType) {
+  if (fieldType === "bool") return "boolean";
+  if (fieldType === "string") return "string";
+  return "number";
+}
+
+// src/systems/propagate-transforms.ts
+import {
+  defineSystem,
+  defineSystemSet,
+  FixedUpdate,
+  Update
+} from "@forgeax/engine-ecs";
+import {
+  createWorldProjection as createWorldProjection2,
+  setDerivedComponent
+} from "@forgeax/engine-ecs/projection";
+import { mat4 } from "@forgeax/engine-math";
+
+// src/systems/hierarchy-projection.ts
+import { Entity } from "@forgeax/engine-ecs";
+import { createWorldProjection } from "@forgeax/engine-ecs/projection";
+var HIERARCHY_PROJECTION_CACHE = /* @__PURE__ */ new WeakMap();
+function diagnostic(code, entity, parent) {
+  if (code === "hierarchy-cycle") {
+    return {
+      code,
+      expected: "ChildOf parent edges form an acyclic live hierarchy",
+      hint: "remove one ChildOf edge from the reported cycle, then re-run the extract",
+      detail: { entity, parent }
+    };
+  }
+  return {
+    code,
+    expected: "ChildOf.parent references a live entity in the same World",
+    hint: "remove the stale ChildOf component or restore the referenced parent in this World",
+    detail: { entity, parent }
+  };
+}
+function projectHierarchy(world) {
+  const cached = HIERARCHY_PROJECTION_CACHE.get(world);
+  const changes = cached?.changes ?? createWorldProjection(world, { components: [ChildOf] });
+  if (cached !== void 0) {
+    const evidence = changes.poll();
+    if (evidence.status === "delta" && evidence.changes.length === 0) return cached.snapshot;
+  }
+  const liveEntities = /* @__PURE__ */ new Set();
+  const authoredParents = /* @__PURE__ */ new Map();
+  const query = world.query({ read: [Entity], optional: [ChildOf] });
+  if (query.ok) {
+    for (const row of query.value) {
+      liveEntities.add(row.entity);
+      const parent = row.get(ChildOf)?.parent;
+      if (parent !== void 0 && parent !== null) authoredParents.set(row.entity, parent);
+    }
+  }
+  const parentOf = /* @__PURE__ */ new Map();
+  const diagnostics = [];
+  for (const [entity, parent] of authoredParents) {
+    if (liveEntities.has(parent)) {
+      parentOf.set(entity, parent);
+    } else {
+      diagnostics.push(diagnostic("hierarchy-broken", entity, parent));
+    }
+  }
+  const state = /* @__PURE__ */ new Map();
+  const stack = [];
+  const cycleMembers = /* @__PURE__ */ new Set();
+  const visit = (entity) => {
+    const currentState = state.get(entity) ?? 0;
+    if (currentState === 2) return;
+    if (currentState === 1) {
+      const cycleStart = stack.indexOf(entity);
+      for (let index = cycleStart; index >= 0 && index < stack.length; index++) {
+        const member = stack[index];
+        if (member !== void 0) cycleMembers.add(member);
+      }
+      return;
+    }
+    state.set(entity, 1);
+    stack.push(entity);
+    const parent = parentOf.get(entity);
+    if (parent !== void 0) visit(parent);
+    stack.pop();
+    state.set(entity, 2);
+  };
+  for (const entity of liveEntities) visit(entity);
+  for (const entity of cycleMembers) {
+    const parent = authoredParents.get(entity);
+    if (parent !== void 0) diagnostics.push(diagnostic("hierarchy-cycle", entity, parent));
+    parentOf.delete(entity);
+  }
+  diagnostics.sort((left, right) => {
+    const entityDelta = left.detail.entity - right.detail.entity;
+    if (entityDelta !== 0) return entityDelta;
+    return left.code.localeCompare(right.code);
+  });
+  const stableParentOf = new Map(parentOf);
+  const stableDiagnostics = Object.freeze(diagnostics.slice());
+  const snapshot = {
+    parentOf: stableParentOf,
+    diagnostics: stableDiagnostics,
+    getParent(entity) {
+      return stableParentOf.get(entity);
+    }
+  };
+  HIERARCHY_PROJECTION_CACHE.set(world, {
+    changes,
+    snapshot
+  });
+  return snapshot;
+}
+
+// src/systems/propagate-transforms.ts
+var PROPAGATE_TRANSFORMS_SYSTEM = "propagateTransforms";
+var PROPAGATE_TRANSFORMS_FIXED_SYSTEM = "propagateTransformsFixed";
+var TransformSet = defineSystemSet({ name: "transform" });
+var TransformFixedSet = defineSystemSet({ name: "transform-fixed" });
+var CACHE = /* @__PURE__ */ new WeakMap();
+var REGISTRATION_LEASES = /* @__PURE__ */ new WeakMap();
+function copyState(value) {
+  return {
+    pos: new Float32Array(value.pos),
+    quat: new Float32Array(value.quat),
+    scale: new Float32Array(value.scale)
+  };
+}
+function sameArray(left, right) {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+function sameState(left, right) {
+  return left !== void 0 && sameArray(left.pos, right.pos) && sameArray(left.quat, right.quat) && sameArray(left.scale, right.scale);
+}
+function compose(state, out) {
+  mat4.compose(out, state.pos, state.quat, state.scale);
+}
+function indexChildren(hierarchy) {
+  const childrenOf = /* @__PURE__ */ new Map();
+  for (const [child, parent] of hierarchy.parentOf) {
+    const children = childrenOf.get(parent);
+    if (children === void 0) childrenOf.set(parent, [child]);
+    else children.push(child);
+  }
+  return childrenOf;
+}
+function descendants(childrenOf, roots) {
+  const affected = new Set(roots);
+  const pending = [...roots];
+  for (let index = 0; index < pending.length; index += 1) {
+    const parent = pending[index];
+    if (parent === void 0) continue;
+    for (const child of childrenOf.get(parent) ?? []) {
+      if (affected.has(child)) continue;
+      affected.add(child);
+      pending.push(child);
+    }
+  }
+  return affected;
+}
+function hierarchyError(hierarchy) {
+  const first = hierarchy.diagnostics[0];
+  if (first === void 0) return ok(void 0);
+  return err(
+    new SceneError({
+      code: first.code,
+      expected: first.expected,
+      hint: first.hint,
+      detail: first.detail
+    })
+  );
+}
+function buildCache(world, projection) {
+  const hierarchy = projectHierarchy(world);
+  const locals = /* @__PURE__ */ new Map();
+  const entities = /* @__PURE__ */ new Set();
+  const query = world.query({ read: [Transform], optional: [ChildOf] });
+  if (query.ok) {
+    for (const row of query.value) {
+      const transform = row.get(Transform);
+      if (transform === void 0) continue;
+      entities.add(row.entity);
+      locals.set(row.entity, copyState(transform));
+    }
+  }
+  return {
+    projection,
+    hierarchy,
+    parentOf: hierarchy.parentOf,
+    childrenOf: indexChildren(hierarchy),
+    entities,
+    locals,
+    derived: /* @__PURE__ */ new Map(),
+    result: ok(void 0)
+  };
+}
+function deriveEntity(world, entity, cache, affected, visiting, published) {
+  if (!affected.has(entity) || cache.derived.has(entity)) return ok(void 0);
+  if (visiting.has(entity)) return ok(void 0);
+  visiting.add(entity);
+  const local = cache.locals.get(entity);
+  if (local === void 0) {
+    visiting.delete(entity);
+    return ok(void 0);
+  }
+  const parent = cache.parentOf.get(entity);
+  if (parent !== void 0 && cache.entities.has(parent)) {
+    const parentResult = deriveEntity(world, parent, cache, affected, visiting, published);
+    if (!parentResult.ok) return parentResult;
+  }
+  const localWorld = mat4.create();
+  compose(local, localWorld);
+  const parentWorld = parent === void 0 ? void 0 : cache.derived.get(parent);
+  const resolved = mat4.create();
+  if (parentWorld === void 0) resolved.set(localWorld);
+  else mat4.multiply(resolved, parentWorld, localWorld);
+  const write = setDerivedComponent(world, entity, Transform, { world: resolved });
+  if (!write.ok) {
+    visiting.delete(entity);
+    return err(
+      new SceneError({
+        code: "hierarchy-broken",
+        expected: "the derived Transform.world write to succeed",
+        hint: "inspect the ECS mutation error before retrying transform propagation",
+        detail: { entity, parent: entity }
+      })
+    );
+  }
+  cache.derived.set(entity, resolved);
+  published.add(entity);
+  visiting.delete(entity);
+  return ok(void 0);
+}
+function drainPublishedChanges(cache, published) {
+  const drained = cache.projection.poll();
+  if (drained.status === "rebuild") return true;
+  return drained.changes.every(
+    (change) => change.kind === "derived-component-changed" && change.component === Transform && published.has(change.entity)
+  );
+}
+function propagateTransforms(world, _hierarchy) {
+  let cache = CACHE.get(world);
+  if (cache === void 0) {
+    cache = buildCache(world, createWorldProjection2(world, { components: [Transform, ChildOf] }));
+    CACHE.set(world, cache);
+    const initial = new Set(cache.entities);
+    const published2 = /* @__PURE__ */ new Set();
+    for (const entity of initial) {
+      const result = deriveEntity(world, entity, cache, initial, /* @__PURE__ */ new Set(), published2);
+      if (!result.ok) return result;
+    }
+    if (!drainPublishedChanges(cache, published2)) {
+      CACHE.delete(world);
+      return propagateTransforms(world);
+    }
+    cache.result = hierarchyError(cache.hierarchy);
+    return cache.result;
+  }
+  const evidence = cache.projection.poll();
+  if (evidence.status === "rebuild") {
+    cache = buildCache(world, cache.projection);
+    CACHE.set(world, cache);
+    const all = new Set(cache.entities);
+    const published2 = /* @__PURE__ */ new Set();
+    for (const entity of all) {
+      const result = deriveEntity(world, entity, cache, all, /* @__PURE__ */ new Set(), published2);
+      if (!result.ok) return result;
+    }
+    if (!drainPublishedChanges(cache, published2)) {
+      CACHE.delete(world);
+      return propagateTransforms(world);
+    }
+    cache.result = hierarchyError(cache.hierarchy);
+    return cache.result;
+  }
+  if (evidence.changes.length === 0) return cache.result;
+  const transformSeeds = /* @__PURE__ */ new Set();
+  let rebuild = false;
+  for (const change of evidence.changes) {
+    if (change.kind === "entity-removed" || change.kind === "component-added" || change.kind === "component-removed") {
+      rebuild = true;
+      break;
+    }
+    if (change.kind !== "component-changed") continue;
+    if (change.component === ChildOf) {
+      rebuild = true;
+      break;
+    }
+    if (change.component === Transform) transformSeeds.add(change.entity);
+  }
+  if (rebuild) {
+    CACHE.delete(world);
+    return propagateTransforms(world);
+  }
+  const changed = /* @__PURE__ */ new Set();
+  for (const entity of transformSeeds) {
+    const current = world.get(entity, Transform);
+    if (!current.ok) {
+      CACHE.delete(world);
+      return propagateTransforms(world);
+    }
+    const next = copyState(current.value);
+    if (!sameState(cache.locals.get(entity), next)) changed.add(entity);
+    cache.locals.set(entity, next);
+  }
+  if (changed.size === 0) return cache.result;
+  const affected = descendants(cache.childrenOf, changed);
+  const published = /* @__PURE__ */ new Set();
+  for (const entity of affected) cache.derived.delete(entity);
+  for (const entity of affected) {
+    const result = deriveEntity(world, entity, cache, affected, /* @__PURE__ */ new Set(), published);
+    if (!result.ok) return result;
+  }
+  if (!drainPublishedChanges(cache, published)) {
+    CACHE.delete(world);
+    return propagateTransforms(world);
+  }
+  cache.result = hierarchyError(cache.hierarchy);
+  return cache.result;
+}
+var PropagateTransforms = defineSystem({
+  name: PROPAGATE_TRANSFORMS_SYSTEM,
+  queries: [],
+  fn: (world) => {
+    const result = propagateTransforms(world);
+    if (!result.ok) throw result.error;
+  }
+});
+var PropagateTransformsFixed = defineSystem({
+  name: PROPAGATE_TRANSFORMS_FIXED_SYSTEM,
+  queries: [],
+  fn: PropagateTransforms.fn
+});
+function registerPropagateTransforms(world, options = {}) {
+  const existing = REGISTRATION_LEASES.get(world);
+  if (existing !== void 0) {
+    existing.refs += 1;
+    let active2 = true;
+    return () => {
+      if (!active2) return;
+      active2 = false;
+      existing.refs -= 1;
+      if (existing.refs === 0) {
+        world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
+        world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
+        REGISTRATION_LEASES.delete(world);
+        CACHE.delete(world);
+      }
+    };
+  }
+  if (options.beforeSystemName === void 0) {
+    world.addSystems(Update, TransformSet, [PropagateTransforms]).unwrap();
+  } else {
+    world.addSystems(Update, TransformSet, [
+      {
+        name: PROPAGATE_TRANSFORMS_SYSTEM,
+        queries: [],
+        fn: PropagateTransforms.fn,
+        before: [options.beforeSystemName]
+      }
+    ]).unwrap();
+  }
+  world.addSystems(FixedUpdate, TransformFixedSet, [PropagateTransformsFixed]).unwrap();
+  const lease = { refs: 1 };
+  REGISTRATION_LEASES.set(world, lease);
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    lease.refs -= 1;
+    if (lease.refs !== 0) return;
+    world.removeSystem(FixedUpdate, PROPAGATE_TRANSFORMS_FIXED_SYSTEM);
+    world.removeSystem(Update, PROPAGATE_TRANSFORMS_SYSTEM);
+    REGISTRATION_LEASES.delete(world);
+    CACHE.delete(world);
+  };
+}
+
+// src/plugin.ts
+var SCENE_COMPONENTS = [ChildOf, Children, MorphWeights, Name, Transform];
+function registerSceneComponents(world) {
+  const leases = SCENE_COMPONENTS.map((component) => world.components.register(component).unwrap());
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+function scenePlugin() {
+  return {
+    name: "scene",
+    inject: ["world"],
+    apply(ctx) {
+      ctx.effect(() => registerSceneComponents(ctx.world), "scene/components");
+      ctx.effect(() => registerPropagateTransforms(ctx.world), "scene/propagate-transforms");
+    }
+  };
+}
+export {
+  ChildOf,
+  Children,
+  ComponentNotDefinedError,
+  MorphWeights,
+  Name,
+  PROPAGATE_TRANSFORMS_SYSTEM,
+  SCENE_COLLECT_PROFILE,
+  SceneError,
+  Transform,
+  TransformSet,
+  collectSubtree,
+  externalizeSceneAsset,
+  projectHierarchy,
+  propagateTransforms,
+  registerPropagateTransforms,
+  sceneAssetContribution,
+  scenePlugin,
+  worldApplyMountOverride,
+  worldBuildSceneEntityComponentDatas,
+  worldDespawnDescendants,
+  worldDespawnScene,
+  worldDetachSceneMember,
+  worldGetSceneAssetForInstance,
+  worldGetSceneAssetResolver,
+  worldGetSceneInstanceState,
+  worldInstantiateScene,
+  worldInstantiateSceneAsset,
+  worldInstantiateSceneAssetFlat,
+  worldInstantiateSceneFlat,
+  worldInstantiateScenePayload,
+  worldInstantiateSceneRec,
+  worldMountOverridesToStateMap,
+  worldReattachSceneMember,
+  worldRemoveSceneOverride,
+  worldResolveMountSource,
+  worldResolveSceneAsset,
+  worldResolveSceneInstanceStatePayload,
+  worldSetSceneAssetResolver,
+  worldSetSceneOverride,
+  worldSpawnMountEntity,
+  worldSpawnSceneMembers,
+  worldValidateMountOverrides
+};
+//# sourceMappingURL=index.mjs.map