@forgeax/engine-import 0.1.20 → 0.1.23

package/README.md

@@ -2,12 +2,28 @@
 
 ## Authoring and recovery index
 
+## 灯光资产 producer 入口
+
+三条最短入口：
+
+1. `RectAreaLight`、`SpotLight` 与 `LightProbe` 由 render 的 ECS schema 创作，scene producer 只外化 `shared<T>` GUID。
+2. `iesImporter` 只在 build-time 接受 LM-63 Type C `TILT=NONE`，输出固定 cooked `IesProfileAsset`；runtime 不解析 `.ies` 文本。
+3. `SpotLight.cookie` 走现有 `TextureAsset`/image producer；不要建立 Cookie registry 或第二条采样路径。
+
+producer 持有 authored/source authority，Pack 产出 published 记录，Catalog 是 admitted/current 的投影；失败只返回结构化 `import-failed` 并保留原 GUID，修复 producer 后按同 GUID 重试。`lastKnownGood` 只可预览，不能冒充 verified/current。
+
+Extended-lighting imports keep the same source key across Rect, Spot modifier,
+Probe, and recovery carriers. IES is a build-time Type C `TILT=NONE` producer;
+Cookie uses the existing texture producer; Probe and Sky are not new asset
+registries. A failed publish is a structured producer result, and runtime must
+not parse source text, invent a cooked payload, or promote LKG to current.
+
 ScriptablePack sources use the public `@forgeax/engine-import` producer bridge.
 The output is the same Pack v2 durable payload used by ordinary importers. The
-16 `SCRIPTABLE_PACK_ASSET_KINDS` are `mesh`, `material`, `scene`, `texture`,
+17 `SCRIPTABLE_PACK_ASSET_KINDS` are `mesh`, `material`, `scene`, `texture`,
 `equirect`, `sampler`, `font`, `render-pipeline`, `tileset`, `video`,
 `skeleton`, `skin`, `animation-clip`, `animation-graph`, `audio`, and
-`particle-effect`; all are loadable by GUID, while `refs`,
+`particle-effect`, and `ies-profile`; all are loadable by GUID, while `refs`,
 `artifacts`, `mediaType`, and `programFingerprint` remain producer facts.
 Producer or dependency failures return `code`, `expected`, `hint`, and
 `detail`; inspect the owning evidence, rebuild or cold-cook, and retry.
@@ -23,6 +39,28 @@ The import contract is [`asset-authority.schema.json`](../../asset-authority.sch
 
 The Importer owns neither DDC lifecycle nor Editor authoring writes. Editor writes go through its asset-authoring gateway, and runtime consumes the validated projection.
 
+### Parameterized Pack generation
+
+`buildParameterizedScriptablePack()` accepts a Pack v2 definition, resolves the
+default/inherited values, and executes `build()` once for the current subject
+identity. The result is a dynamic `sourceKey -> Asset` map; the bridge derives
+`AssetGuid` values from `(subjectPackageId, sourceKey)` and sends the resulting
+assets through the same registered output producers and Pack v2 finalizer used
+by ordinary imports.
+
+`buildParameterizedScriptablePackWorklist()` is the internal clean-generation
+fixed point. Subjects are evaluated in stable order, a forward `readByGuid()`
+content miss waits for the subject that can materialize that GUID, and a pass
+with no progress returns `pack-content-dependency-stalled`. Once all subjects
+settle, the bridge validates references and incoming-reference deletions before
+publication. A GUID written into a payload is only a reference dependency;
+only `readByGuid()` creates a content dependency.
+
+`produceParameterizedScriptablePackProducts()` and
+`materializePreparedParameterizedScriptablePack()` adapt that result to the
+existing DDC/Catalog/Pack v2 publication tuple. No parameter, parent, sourceKey,
+or TypeScript execution contract crosses into the runtime package.
+
 Build-time asset **import** runner + `ImporterRegistry` — the build-time half of
 the engine's import/load split.
 
@@ -103,7 +141,7 @@ flowchart LR
 
 Domain producers return structured `ImportError`; the generic bridge contains no per-kind switch. `createStandardAssetOutputProducerRegistry(sceneComponents)` composes the production Scene, Material, and Mesh owners with the definition-bound scene schema. Scene refs use the ECS externalization kernel shared with runtime save, Material refs cover parent/texture/sampler GUIDs, and Mesh emits the versioned binary artifact. The fingerprint covers canonical Meta, the definition-bound scene schema, the recursive source closure, observed external evidence, authoring contract version, and registered producer versions.
 
-`createScriptablePackStagedAssetSnapshotSource()` owns clean-build content reads. It resolves a GUID to its local source owner, lazily builds that owner inside one fixed generation, memoizes private clones and digests, and reports `pack-source-build-cycle` without consulting an older fallback generation. A fallback is only an explicit prebuilt authority for GUIDs with no local owner.
+`createScriptablePackStagedAssetSnapshotSource()` owns clean-build content reads. It resolves a GUID to its local source owner, lazily builds that owner inside one fixed generation, memoizes private clones and digests, and reports `pack-content-dependency-stalled` for a cycle without consulting an older fallback generation. A fallback is only an explicit prebuilt authority for GUIDs with no local owner.
 
 `createStandardAssetOutputProducerRegistry(sceneComponents)` registers the production
 Material, Mesh, and Scene producers. Material output derives
@@ -132,6 +170,13 @@ binary metadata.
 > so the importer cannot publish a partial mesh product. v2/v3 mesh binaries
 > are not compatibility inputs.
 
+For prebuilt ordinary Pack dependencies, use
+`createScriptablePackFileAssetSnapshotSource({ assetRoots })` from the same
+package. It recursively indexes validated `.pack.json` assets by GUID and
+returns private `ScriptablePackAssetSnapshot` clones with deterministic
+generation/digest evidence; missing, malformed, unreadable, and colliding
+inputs remain structured `Result` errors.
+
 At the low-level `buildScriptablePack` boundary, `assetSource` is optional only
 when `build` never calls `reader.readByGuid`. The first attempted content read
 without a source returns structured `asset-not-found`; no empty snapshot or
@@ -220,8 +265,51 @@ Result boundary. A digest-capability refusal during CookProduct finalization
 does not publish a partial product; repair that capability and retry the same
 Meta/GUID through the same `ImporterRegistry`.
 
+### Source-format LOD adapters
+
+Format adapters project producer facts into the same `MeshAsset.lods` and Pack
+closure. The adapter owns interpretation; the sidecar owns retained author
+facts and the importer only produces validated derived output.
+
+| Source fact | Normalized result | Required closure |
+|:--|:--|:--|
+| glTF `MSFT_lod` node relation | ordered root and lower mesh GUIDs | root `refs[]` contains every lower mesh |
+| FBX `FbxLODGroup` level relation | ordered root and lower mesh GUIDs | root `refs[]` contains every lower mesh |
+| sidecar `sourceOverrides.mesh.lods` | retained `screenCoverage` and source keys | every GUID resolves in the same package |
+
+On first import the helper derives lower-level coverage with
+
+$$c_i = round6(0.5 \times 0.4^{i-1})$$
+
+for `i = 1 .. n`, where `n` is the number of lower levels. This yields
+`0.5` for two total LODs, `0.5, 0.2` for three, and `0.5, 0.2, 0.08`
+for four. Existing legal sidecar values always win; only a newly appended
+suffix receives defaults. A changed middle source key or mesh GUID is rejected
+and the previous sidecar plus last-known-good product remains authoritative.
+
 The import package stops at build-time source conversion and product
 publication. It does not write authoring state, own Editor operations, or add
 runtime transport branches. A dev `ImportTransport` is an explicit host
 adapter; a shipped bundle must carry its build-time product and keeps
 `asset-not-imported` fail-fast semantics.
+
+## Mesh LOD normalization and recovery
+
+The shared helper in `src/mesh-lod.ts` owns validation, default coverage, and
+prefix-stable reimport. For `n` lower levels, first-import defaults are derived
+once with:
+
+$$c_i = round6(0.5 * 0.4^{i-1}), 1 <= i <= n$$
+
+Thus two levels produce `0.5`, three produce `0.5, 0.2`, and four produce
+`0.5, 0.2, 0.08`. Existing legal sidecar values win; newly appended suffix
+levels receive defaults. A middle sourceKey or GUID change is a structured
+topology/authority error, so the previous sidecar and LKG remain intact.
+
+```mermaid
+flowchart LR
+  A["source plus Meta"] --> B["validate LOD facts"]
+  B -->|"valid"| C["reconcile prefix and defaults"]
+  C --> D["publish Pack and Catalog"]
+  B -->|"invalid"| E["restore old sidecar and LKG"]
+```

package/dist/__tests__/ies-contract.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ies-contract.unit.test.d.ts.map

package/dist/__tests__/ies-contract.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ies-contract.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ies-contract.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ies-producer.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ies-producer.unit.test.d.ts.map

package/dist/__tests__/ies-producer.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ies-producer.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ies-producer.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/mesh-lod-contract.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mesh-lod-contract.unit.test.d.ts.map

package/dist/__tests__/mesh-lod-contract.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-lod-contract.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mesh-lod-contract.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/mesh-lod-reimport.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mesh-lod-reimport.integration.test.d.ts.map

package/dist/__tests__/mesh-lod-reimport.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-lod-reimport.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mesh-lod-reimport.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/parameterized-scriptable-pack.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parameterized-scriptable-pack.unit.test.d.ts.map

package/dist/__tests__/parameterized-scriptable-pack.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameterized-scriptable-pack.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/parameterized-scriptable-pack.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/scriptable-pack-file-snapshot.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scriptable-pack-file-snapshot.unit.test.d.ts.map

package/dist/__tests__/scriptable-pack-file-snapshot.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptable-pack-file-snapshot.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/scriptable-pack-file-snapshot.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/source-package-publication-lod.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-package-publication-lod.integration.test.d.ts.map

package/dist/__tests__/source-package-publication-lod.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-package-publication-lod.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/source-package-publication-lod.integration.test.ts"],"names":[],"mappings":""}

package/dist/browser.d.ts

@@ -2,4 +2,5 @@ export { IMPORT_ERROR_HINTS, ImportError } from '@forgeax/engine-types';
 export { type DdcPack, type ImportRunnerFs, normaliseForPack, type RunImportMeta, type RunImportOk, type RunImportProductResult, type RunImportResult, runImport, SHADER_RESERVED_IMPORTER_KEY, } from './import-runner.js';
 export { ImporterRegistry } from './importer-registry.js';
 export { packMeshBinV4 } from './mesh-bin.js';
+export { deriveDefaultLodScreenCoverages, reconcileMeshLodMeta, validateMeshLodContract, } from './mesh-lod.js';
 //# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,SAAS,EACT,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,SAAS,EACT,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,eAAe,CAAC"}

package/dist/browser.mjs

@@ -1,4 +1,4 @@
-import { validateSourceOverrideMap, ImportError, IMPORT_ERROR_HINTS, canonicalizeSourceOverrides, err, ok } from '@forgeax/engine-types';
+import { err, ok, validateSourceOverrideMap, ImportError, IMPORT_ERROR_HINTS, canonicalizeSourceOverrides } from '@forgeax/engine-types';
 export { IMPORT_ERROR_HINTS, ImportError } from '@forgeax/engine-types';
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
@@ -113,6 +113,171 @@ function finalizeImportProducts(product, inputFingerprint) {
     return products;
   })();
 }
+function deriveDefaultLodScreenCoverages(levelCount) {
+  if (!Number.isInteger(levelCount) || levelCount < 1 || levelCount > 8) {
+    throw new RangeError("levelCount must be an integer in [1, 8]");
+  }
+  return Array.from(
+    { length: levelCount - 1 },
+    (_, index) => Math.round(0.5 * 0.4 ** index * 1e6) / 1e6
+  );
+}
+function validateMeshLodContract(input) {
+  if (input.lods.length > 7) {
+    return err({
+      code: "mesh-lod-contract-invalid",
+      reason: "at most seven lower-detail levels are supported"
+    });
+  }
+  if (input.lodHysteresis !== void 0 && (!Number.isFinite(input.lodHysteresis) || input.lodHysteresis < 0 || input.lodHysteresis >= 1)) {
+    return err({
+      code: "mesh-lod-contract-invalid",
+      reason: "lodHysteresis must be finite and in [0, 1)"
+    });
+  }
+  if (input.generation !== void 0 && (!Number.isSafeInteger(input.generation) || input.generation < 0)) {
+    return err({
+      code: "mesh-lod-contract-invalid",
+      reason: "generation must be a non-negative safe integer"
+    });
+  }
+  const guids = /* @__PURE__ */ new Set();
+  let previous = 1;
+  for (const level of input.lods) {
+    if (level.meshGuid.trim() === "" || guids.has(level.meshGuid)) {
+      return err({
+        code: "mesh-lod-contract-invalid",
+        reason: "LOD mesh GUIDs must be unique and non-empty"
+      });
+    }
+    if (!Number.isFinite(level.screenCoverage) || level.screenCoverage <= 0 || level.screenCoverage > 1) {
+      return err({
+        code: "mesh-lod-contract-invalid",
+        reason: "screenCoverage must be finite and in (0, 1]"
+      });
+    }
+    if (level.screenCoverage >= previous) {
+      return err({
+        code: "mesh-lod-contract-invalid",
+        reason: "screenCoverage must strictly decrease by level"
+      });
+    }
+    guids.add(level.meshGuid);
+    previous = level.screenCoverage;
+  }
+  if (input.refs !== void 0) {
+    const refs = new Set(input.refs);
+    for (const level of input.lods) {
+      if (!refs.has(level.meshGuid)) {
+        return err({
+          code: "mesh-lod-contract-invalid",
+          reason: "every lower-detail mesh GUID must be enclosed by root refs"
+        });
+      }
+    }
+  }
+  if (input.rootMeshGuid !== void 0 && input.refs !== void 0 && !input.refs.includes(input.rootMeshGuid)) {
+    return err({
+      code: "mesh-lod-contract-invalid",
+      reason: "root mesh GUID must be included in refs"
+    });
+  }
+  if (input.rootBounds !== void 0) {
+    if (!validBounds(input.rootBounds)) {
+      return err({
+        code: "mesh-lod-contract-invalid",
+        reason: "root bounds must be finite and ordered"
+      });
+    }
+    for (const bounds of input.lodBounds ?? []) {
+      if (!validBounds(bounds) || !encloses(input.rootBounds, bounds)) {
+        return err({
+          code: "mesh-lod-contract-invalid",
+          reason: "root bounds must enclose every lower-detail bounds"
+        });
+      }
+    }
+  }
+  if (input.lodBounds !== void 0 && input.lodBounds.length !== input.lods.length) {
+    return err({
+      code: "mesh-lod-contract-invalid",
+      reason: "lod bounds must cover every lower level"
+    });
+  }
+  if (input.rootMaterialSlots !== void 0 || input.lodMaterialSlots !== void 0) {
+    const rootSlots = input.rootMaterialSlots ?? [];
+    const lowerSlots = input.lodMaterialSlots ?? [];
+    if (lowerSlots.length !== input.lods.length || lowerSlots.some((slots) => !sameSlots(rootSlots, slots))) {
+      return err({
+        code: "mesh-lod-contract-invalid",
+        reason: "lower-detail material slots must preserve root sourceKey order"
+      });
+    }
+  }
+  if (input.relations !== void 0 && hasCycle(input.relations)) {
+    return err({ code: "mesh-lod-contract-invalid", reason: "LOD relations must be acyclic" });
+  }
+  return ok({ lods: input.lods });
+}
+function validBounds(bounds) {
+  const [minX, minY, minZ] = bounds.min;
+  const [maxX, maxY, maxZ] = bounds.max;
+  return [minX, minY, minZ, maxX, maxY, maxZ].every(Number.isFinite) && minX <= maxX && minY <= maxY && minZ <= maxZ;
+}
+function encloses(root, child) {
+  return child.min[0] >= root.min[0] && child.min[1] >= root.min[1] && child.min[2] >= root.min[2] && child.max[0] <= root.max[0] && child.max[1] <= root.max[1] && child.max[2] <= root.max[2];
+}
+function sameSlots(root, child) {
+  return root.length === child.length && root.every((slot, index) => slot.sourceKey === child[index]?.sourceKey);
+}
+function hasCycle(relations) {
+  const edges = /* @__PURE__ */ new Map();
+  for (const relation of relations)
+    edges.set(relation.from, [...edges.get(relation.from) ?? [], relation.to]);
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (visiting.has(node)) return true;
+    if (visited.has(node)) return false;
+    visiting.add(node);
+    for (const next of edges.get(node) ?? []) if (visit(next)) return true;
+    visiting.delete(node);
+    visited.add(node);
+    return false;
+  };
+  return [...edges.keys()].some(visit);
+}
+function reconcileMeshLodMeta(previous, next) {
+  const overlap = Math.min(previous.length, next.length);
+  for (let index = 0; index < overlap; index++) {
+    const oldEntry = previous[index];
+    const nextEntry = next[index];
+    if (oldEntry?.sourceKey !== nextEntry?.sourceKey) {
+      return err({
+        code: "mesh-lod-topology-change",
+        reason: "existing LOD source keys must remain prefix-stable",
+        previousIndices: [index],
+        nextIndices: [index]
+      });
+    }
+    if (oldEntry?.meshGuid !== nextEntry?.meshGuid) {
+      return err({
+        code: "mesh-lod-authority-conflict",
+        reason: `sourceKey ${nextEntry?.sourceKey ?? "<missing>"} changed mesh GUID`
+      });
+    }
+  }
+  const defaults = deriveDefaultLodScreenCoverages(next.length + 1);
+  const lods = next.map((entry, index) => ({
+    ...entry,
+    screenCoverage: previous[index]?.screenCoverage ?? entry.screenCoverage ?? defaults[index] ?? 0
+  }));
+  const valid = validateMeshLodContract({
+    lods: lods.map(({ meshGuid, screenCoverage }) => ({ meshGuid, screenCoverage }))
+  });
+  if (!valid.ok) return valid;
+  return ok({ lods });
+}
 
 // src/import-runner.ts
 var SHADER_RESERVED_IMPORTER_KEY = "shader";
@@ -125,6 +290,9 @@ function isModuleLoadFailure(e) {
   const msg = e.message;
   return msg.includes("Cannot find module") || msg.includes("native addon") || msg.includes(".node");
 }
+function declarationsSourceKey(declarations, guid) {
+  return declarations.find((declaration) => declaration.guid === guid)?.sourceKey;
+}
 function normaliseForPack(value) {
   if (value === null || value === void 0) return value;
   if (value instanceof Float32Array || value instanceof Float64Array || value instanceof Uint8Array || value instanceof Uint16Array || value instanceof Uint32Array || value instanceof Int8Array || value instanceof Int16Array || value instanceof Int32Array) {
@@ -434,6 +602,37 @@ async function runImport(meta, registry, fs) {
     );
   }
   const produced = product.assets;
+  for (const asset of produced) {
+    if (asset.kind !== "mesh" || asset.payload === null || typeof asset.payload !== "object")
+      continue;
+    const payload = asset.payload;
+    if (payload.lods === void 0) continue;
+    const lods = payload.lods.map((level) => ({
+      meshGuid: typeof level.meshGuid === "string" ? level.meshGuid : typeof level.mesh === "string" ? level.mesh : JSON.stringify(level.mesh),
+      screenCoverage: level.screenCoverage
+    }));
+    const validated = validateMeshLodContract({
+      lods,
+      ...payload.lodHysteresis === void 0 ? {} : { lodHysteresis: payload.lodHysteresis }
+    });
+    if (!validated.ok) {
+      return errResult(
+        new ImportError({
+          code: validated.error.code,
+          expected: "MeshAsset LOD facts to satisfy the shared contract",
+          hint: IMPORT_ERROR_HINTS[validated.error.code],
+          detail: {
+            meshLodSourceKey: declarationsSourceKey(meta.subAssets, asset.guid),
+            reason: validated.error.reason,
+            ...validated.error.code === "mesh-lod-topology-change" ? {
+              previousIndices: validated.error.previousIndices,
+              nextIndices: validated.error.nextIndices
+            } : {}
+          }
+        })
+      );
+    }
+  }
   const declared = new Set(meta.subAssets.map((s) => s.guid));
   const producedGuids = new Set(produced.map((a) => a.guid));
   const unexpectedGuids = [...producedGuids].filter((g) => !declared.has(g));
@@ -651,12 +850,40 @@ function refsMeta(payload, refs) {
       };
     }
   );
+  if (payload.lods !== void 0 && payload.lods.length > 7) {
+    throw new Error("MeshAsset LOD chain supports at most seven lower-detail levels");
+  }
+  let previousCoverage = 1;
+  const seenLodGuids = /* @__PURE__ */ new Set();
+  const lods = payload.lods?.map((lod, lodIndex) => {
+    const guid = AssetGuid.format(lod.mesh).toLowerCase();
+    const meshRef = refs.findIndex((candidate) => candidate.toLowerCase() === guid);
+    if (meshRef < 0) {
+      throw new Error(`LOD ${lodIndex} mesh ${guid} is absent from refs`);
+    }
+    if (seenLodGuids.has(guid)) {
+      throw new Error(`LOD ${lodIndex} mesh ${guid} is duplicated`);
+    }
+    if (!Number.isFinite(lod.screenCoverage) || lod.screenCoverage <= 0 || lod.screenCoverage > 1 || lod.screenCoverage >= previousCoverage) {
+      throw new Error(
+        `LOD ${lodIndex} screenCoverage must be finite, in (0, 1], and strictly decreasing`
+      );
+    }
+    seenLodGuids.add(guid);
+    previousCoverage = lod.screenCoverage;
+    return { meshRef, screenCoverage: lod.screenCoverage };
+  });
+  if (payload.lodHysteresis !== void 0 && (!Number.isFinite(payload.lodHysteresis) || payload.lodHysteresis < 0 || payload.lodHysteresis >= 1)) {
+    throw new Error("lodHysteresis must be finite and in [0, 1)");
+  }
   return {
     submeshes: payload.submeshes === void 0 || payload.submeshes.length === 0 ? [{ indexOffset: 0, indexCount: payload.indices?.length ?? 0, materialSlot: 0 }] : payload.submeshes,
     materialSlots,
     ...payload.aabb === void 0 ? {} : { aabb: jsonValue(payload.aabb) },
     ...payload.morphTargets === void 0 ? {} : { morphTargets: jsonValue(payload.morphTargets) },
-    ...payload.morphWeights === void 0 ? {} : { morphWeights: jsonValue(payload.morphWeights) }
+    ...payload.morphWeights === void 0 ? {} : { morphWeights: jsonValue(payload.morphWeights) },
+    ...lods === void 0 ? {} : { lods },
+    ...payload.lodHysteresis === void 0 ? {} : { lodHysteresis: payload.lodHysteresis }
   };
 }
 function packMeshBinV4(payload, sourceKey, refs = []) {
@@ -780,6 +1007,6 @@ function packMeshBinV4(payload, sourceKey, refs = []) {
   }
 }
 
-export { ImporterRegistry, SHADER_RESERVED_IMPORTER_KEY, normaliseForPack, packMeshBinV4, runImport };
+export { ImporterRegistry, SHADER_RESERVED_IMPORTER_KEY, deriveDefaultLodScreenCoverages, normaliseForPack, packMeshBinV4, reconcileMeshLodMeta, runImport, validateMeshLodContract };
 //# sourceMappingURL=browser.mjs.map
 //# sourceMappingURL=browser.mjs.map