@forgeax/engine-import 0.1.20 → 0.1.23

package/src/ies/ies-importer.ts

@@ -0,0 +1,126 @@
+import type {
+  IesProfileAsset,
+  ImportContext,
+  Importer,
+  ImportResult,
+  Result,
+} from '@forgeax/engine-types';
+import {
+  err,
+  IES_PROFILE_BYTE_LENGTH,
+  IES_PROFILE_HEIGHT,
+  IES_PROFILE_WIDTH,
+  IMPORT_ERROR_HINTS,
+  ImportError,
+  ok,
+} from '@forgeax/engine-types';
+import { parseLm63TypeC } from './parse-lm63.js';
+import { resampleTypeC } from './resample-type-c.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function decodeFloat16(bytes: Uint8Array, offset: number): number {
+  const bits = (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8);
+  const sign = (bits & 0x8000) === 0 ? 1 : -1;
+  const exponent = (bits >>> 10) & 0x1f;
+  const fraction = bits & 0x03ff;
+  if (exponent === 0) return sign * 2 ** -14 * (fraction / 2 ** 10);
+  if (exponent === 0x1f) return fraction === 0 ? sign * Infinity : Number.NaN;
+  return sign * 2 ** (exponent - 15) * (1 + fraction / 2 ** 10);
+}
+
+export function validateIesProfilePayload(value: unknown): Result<IesProfileAsset, Error> {
+  if (!isRecord(value) || value.kind !== 'ies-profile') {
+    return err(new Error('IES payload kind must be ies-profile'));
+  }
+  const data = value.data;
+  if (!(data instanceof Uint8Array) || data.byteLength !== IES_PROFILE_BYTE_LENGTH) {
+    return err(
+      new Error(
+        `IES payload must contain ${IES_PROFILE_WIDTH}x${IES_PROFILE_HEIGHT} little-endian f16 samples`,
+      ),
+    );
+  }
+  for (let offset = 0; offset < data.byteLength; offset += 2) {
+    if (!Number.isFinite(decodeFloat16(data, offset))) {
+      return err(new Error('IES payload contains a non-finite f16 sample'));
+    }
+  }
+  return ok(value as unknown as IesProfileAsset);
+}
+
+function sourceValidationError(ctx: ImportContext, reason: string): ImportError {
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: 'LM-63 Type C source with TILT=NONE',
+    hint: IMPORT_ERROR_HINTS['source-validation-failed'],
+    detail: {
+      diagnostics: [
+        {
+          code: 'ies-source-invalid',
+          severity: 'error',
+          sourcePath: ctx.source,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: 'LM-63 Type C TILT=NONE',
+          expected: 'LM-63 Type C source with TILT=NONE',
+          actual: reason,
+          hint: 'repair the IES source and rerun the build-time importer',
+        },
+      ],
+    },
+  });
+}
+
+async function importIes(ctx: ImportContext): Promise<ImportResult> {
+  const source = await ctx.readSource();
+  if (!source.ok) {
+    return {
+      ok: false,
+      error: new ImportError({
+        code: 'source-read-failed',
+        expected: `readable IES source at ${ctx.source}`,
+        hint: IMPORT_ERROR_HINTS['source-read-failed'],
+        detail: { source: ctx.source, reason: String(source.error) },
+      }),
+    };
+  }
+  const parsed = parseLm63TypeC(new TextDecoder().decode(source.value));
+  if (!parsed.ok) return { ok: false, error: sourceValidationError(ctx, parsed.error.reason) };
+  const declaration = ctx.subAssets.find((asset) => asset.kind === 'ies-profile');
+  if (declaration === undefined) {
+    return {
+      ok: false,
+      error: sourceValidationError(ctx, 'missing ies-profile sub-asset declaration'),
+    };
+  }
+  const data = resampleTypeC(parsed.value);
+  const payload: IesProfileAsset = { kind: 'ies-profile', data };
+  return {
+    ok: true,
+    value: {
+      assets: [
+        {
+          guid: declaration.guid,
+          kind: 'ies-profile',
+          payload,
+          refs: [],
+          artifacts: {
+            body: {
+              mediaType: 'application/octet-stream',
+              assetCodec: { name: 'forgeax-ies-profile', version: '1' },
+              bytes: data,
+            },
+          },
+        },
+      ],
+      sourceDependencies: [ctx.source],
+    },
+  };
+}
+
+export const iesImporter: Importer = {
+  key: 'ies',
+  import: importIes,
+};

package/src/ies/parse-lm63.ts

@@ -0,0 +1,98 @@
+import type { Result } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+export interface Lm63TypeC {
+  readonly tilt: 'NONE';
+  readonly verticalAnglesDeg: readonly number[];
+  readonly horizontalAnglesDeg: readonly number[];
+  readonly candela: readonly number[];
+}
+
+export interface Lm63ParseError {
+  readonly code: 'invalid-ies' | 'unsupported-tilt' | 'unsupported-photometric-type';
+  readonly reason: string;
+}
+
+function numericTokens(source: string, startLine: number): number[] {
+  return source
+    .split(/\r?\n/)
+    .slice(startLine)
+    .join(' ')
+    .replaceAll(',', ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 0)
+    .map(Number);
+}
+
+function allFinite(values: readonly number[]): boolean {
+  return values.every(Number.isFinite);
+}
+
+export function parseLm63TypeC(source: string): Result<Lm63TypeC, Lm63ParseError> {
+  const lines = source.split(/\r?\n/);
+  const tiltLine = lines.findIndex((line) => /^\s*TILT\s*=/i.test(line));
+  if (tiltLine < 0) return err({ code: 'invalid-ies', reason: 'missing TILT declaration' });
+  const tiltSource = lines[tiltLine];
+  if (tiltSource === undefined)
+    return err({ code: 'invalid-ies', reason: 'missing TILT declaration' });
+  const tilt = tiltSource
+    .slice(tiltSource.indexOf('=') + 1)
+    .trim()
+    .toUpperCase();
+  if (tilt !== 'NONE') return err({ code: 'unsupported-tilt', reason: `TILT=${tilt}` });
+
+  const values = numericTokens(source, tiltLine + 1);
+  if (values.length < 12 || !allFinite(values.slice(0, 12))) {
+    return err({ code: 'invalid-ies', reason: 'numeric header is incomplete or non-finite' });
+  }
+  const verticalCount = values[3];
+  const horizontalCount = values[4];
+  const photometricType = values[5];
+  if (
+    verticalCount === undefined ||
+    horizontalCount === undefined ||
+    photometricType === undefined
+  ) {
+    return err({ code: 'invalid-ies', reason: 'numeric header is incomplete or non-finite' });
+  }
+  if (photometricType !== 1) {
+    return err({
+      code: 'unsupported-photometric-type',
+      reason: `photometric type ${photometricType} is not Type C`,
+    });
+  }
+  if (
+    !Number.isInteger(verticalCount) ||
+    !Number.isInteger(horizontalCount) ||
+    verticalCount < 2 ||
+    horizontalCount < 1
+  ) {
+    return err({ code: 'invalid-ies', reason: 'angle counts are invalid' });
+  }
+
+  const angleOffset = 12;
+  const verticalEnd = angleOffset + verticalCount;
+  const horizontalEnd = verticalEnd + horizontalCount;
+  const candelaEnd = horizontalEnd + verticalCount * horizontalCount;
+  if (values.length < candelaEnd) {
+    return err({ code: 'invalid-ies', reason: 'angle or candela table is incomplete' });
+  }
+  const verticalAnglesDeg = values.slice(angleOffset, verticalEnd);
+  const horizontalAnglesDeg = values.slice(verticalEnd, horizontalEnd);
+  const candelaMultiplier = values[2];
+  if (candelaMultiplier === undefined) {
+    return err({ code: 'invalid-ies', reason: 'numeric header is incomplete or non-finite' });
+  }
+  const candela = values.slice(horizontalEnd, candelaEnd).map((value) => value * candelaMultiplier);
+  if (
+    !allFinite(verticalAnglesDeg) ||
+    !allFinite(horizontalAnglesDeg) ||
+    !allFinite(candela) ||
+    verticalAnglesDeg[0] !== 0 ||
+    verticalAnglesDeg[verticalAnglesDeg.length - 1] !== 180 ||
+    horizontalAnglesDeg[0] !== 0
+  ) {
+    return err({ code: 'invalid-ies', reason: 'Type C angles or candela values are invalid' });
+  }
+  return ok({ tilt: 'NONE', verticalAnglesDeg, horizontalAnglesDeg, candela });
+}

package/src/ies/resample-type-c.ts

@@ -0,0 +1,108 @@
+import { IES_PROFILE_HEIGHT, IES_PROFILE_WIDTH, type IesProfileAsset } from '@forgeax/engine-types';
+import type { Lm63TypeC } from './parse-lm63.js';
+
+function horizontalTable(source: Lm63TypeC): { angles: number[]; values: number[] } {
+  const angles = [...source.horizontalAnglesDeg];
+  const values = [...source.candela];
+  const verticalCount = source.verticalAnglesDeg.length;
+  const lastAngle = angles.at(-1);
+  if (lastAngle === undefined) return { angles, values };
+  if (lastAngle < 360) {
+    for (let index = angles.length - 2; index > 0; index--) {
+      const angle = angles[index];
+      if (angle === undefined) continue;
+      angles.push(360 - angle);
+      const row = source.horizontalAnglesDeg.length - 1 - index;
+      values.push(
+        ...source.candela.slice(row * verticalCount, row * verticalCount + verticalCount),
+      );
+    }
+  }
+  return { angles, values };
+}
+
+function interpolate(
+  values: readonly number[],
+  angles: readonly number[],
+  angle: number,
+  verticalIndex: number,
+  verticalCount: number,
+): number {
+  const wrapped = ((angle % 360) + 360) % 360;
+  const last = angles.length - 1;
+  const finalAngle = angles[last];
+  const firstAngle = angles[0];
+  if (finalAngle === undefined || firstAngle === undefined) return Number.NaN;
+  for (let index = 0; index < last; index++) {
+    const left = angles[index];
+    const right = angles[index + 1];
+    if (left === undefined || right === undefined) continue;
+    if (wrapped < left || wrapped > right) continue;
+    const span = right - left;
+    const factor = span === 0 ? 0 : (wrapped - left) / span;
+    const a = values[index * verticalCount + verticalIndex] ?? 0;
+    const b = values[(index + 1) * verticalCount + verticalIndex] ?? 0;
+    return a + (b - a) * factor;
+  }
+  const first = values[verticalIndex] ?? 0;
+  const finalRow = (angles.length - 1) * verticalCount + verticalIndex;
+  const final = values[finalRow] ?? 0;
+  const span = 360 - finalAngle + firstAngle;
+  const factor = span === 0 ? 0 : (wrapped - finalAngle + 360) / span;
+  return final + (first - final) * factor;
+}
+
+function toFloat16(value: number): number {
+  if (value === 0) return 0;
+  const sign = value < 0 ? 0x8000 : 0;
+  const absolute = Math.abs(value);
+  if (!Number.isFinite(absolute)) return sign | 0x7c00;
+  const exponent = Math.floor(Math.log2(absolute));
+  if (exponent < -14) return sign | Math.round(absolute / 2 ** -24);
+  if (exponent > 15) return sign | 0x7c00;
+  const mantissa = Math.round((absolute / 2 ** exponent - 1) * 1024);
+  return sign | ((exponent + 15) << 10) | Math.min(mantissa, 1023);
+}
+
+export function readFloat16LE(bytes: Uint8Array, offset: number): number {
+  const bits = (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8);
+  const sign = (bits & 0x8000) === 0 ? 1 : -1;
+  const exponent = (bits >>> 10) & 0x1f;
+  const fraction = bits & 0x03ff;
+  if (exponent === 0) return sign * 2 ** -14 * (fraction / 2 ** 10);
+  if (exponent === 0x1f) return fraction === 0 ? sign * Infinity : Number.NaN;
+  return sign * 2 ** (exponent - 15) * (1 + fraction / 2 ** 10);
+}
+
+export function resampleTypeC(source: Lm63TypeC): Uint8Array {
+  const table = horizontalTable(source);
+  const verticalCount = source.verticalAnglesDeg.length;
+  const output = new Uint8Array(IES_PROFILE_WIDTH * IES_PROFILE_HEIGHT * 2);
+  let peak = 0;
+  const samples: number[] = [];
+  for (let y = 0; y < IES_PROFILE_HEIGHT; y++) {
+    const vertical = (y / (IES_PROFILE_HEIGHT - 1)) * 180;
+    let lower = 0;
+    while (lower + 1 < verticalCount && (source.verticalAnglesDeg[lower + 1] ?? 0) < vertical)
+      lower++;
+    const upper = Math.min(lower + 1, verticalCount - 1);
+    const left = source.verticalAnglesDeg[lower] ?? 0;
+    const right = source.verticalAnglesDeg[upper] ?? 0;
+    const factor = right === left ? 0 : (vertical - left) / (right - left);
+    for (let x = 0; x < IES_PROFILE_WIDTH; x++) {
+      const horizontal = (x / IES_PROFILE_WIDTH) * 360;
+      const low = interpolate(table.values, table.angles, horizontal, lower, verticalCount);
+      const high = interpolate(table.values, table.angles, horizontal, upper, verticalCount);
+      const value = low + (high - low) * factor;
+      samples.push(Math.max(0, value));
+      peak = Math.max(peak, value);
+    }
+  }
+  const divisor = peak > 0 ? peak : 1;
+  for (let index = 0; index < samples.length; index++) {
+    const bits = toFloat16((samples[index] ?? 0) / divisor);
+    output[index * 2] = bits & 0xff;
+    output[index * 2 + 1] = bits >>> 8;
+  }
+  return output satisfies IesProfileAsset['data'];
+}

package/src/import-runner.ts

@@ -46,6 +46,7 @@ import {
   type TerminalImportProduct,
 } from './import-product.js';
 import type { ImporterRegistry } from './importer-registry.js';
+import { validateMeshLodContract } from './mesh-lod.js';
 
 /** Reserved `meta.importer` key consumed by vite-plugin-shader, not the import runner. */
 export const SHADER_RESERVED_IMPORTER_KEY = 'shader';
@@ -79,6 +80,13 @@ function isModuleLoadFailure(e: unknown): boolean {
   );
 }
 
+function declarationsSourceKey(
+  declarations: readonly { readonly guid: string; readonly sourceKey?: string }[],
+  guid: string,
+): string | undefined {
+  return declarations.find((declaration) => declaration.guid === guid)?.sourceKey;
+}
+
 /**
  * bug-20260610-pack-typed-array-roundtrip: normalise a value tree so every
  * typed-array becomes a plain `number[]`. The DDC pack is serialised via
@@ -634,6 +642,56 @@ export async function runImport(
 
   const produced = product.assets;
 
+  // LOD is a producer-authored MeshAsset fact. Validate it once at the
+  // import boundary so malformed coverage never reaches DDC or runtime.
+  for (const asset of produced) {
+    if (asset.kind !== 'mesh' || asset.payload === null || typeof asset.payload !== 'object')
+      continue;
+    const payload = asset.payload as {
+      readonly lods?: readonly {
+        readonly mesh?: unknown;
+        readonly meshGuid?: unknown;
+        readonly screenCoverage?: unknown;
+      }[];
+      readonly lodHysteresis?: unknown;
+    };
+    if (payload.lods === undefined) 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: lods as readonly { meshGuid: string; screenCoverage: number }[],
+      ...(payload.lodHysteresis === undefined
+        ? {}
+        : { lodHysteresis: payload.lodHysteresis as number }),
+    });
+    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,
+                }
+              : {}),
+          },
+        }),
+      );
+    }
+  }
+
   // GUID import-stable iron law: the produced GUID set must be a superset of
   // the declared set, and must not contain any GUID the meta never declared.
   const declared = new Set(meta.subAssets.map((s) => s.guid));

package/src/index.ts

@@ -21,6 +21,7 @@ export type {
   AudioClipAsset,
   EquirectAsset,
   FontAsset,
+  IesProfileAsset,
   MaterialAsset,
   MeshAsset,
   ParticleEffectAsset,
@@ -51,7 +52,6 @@ export {
   type BuildProductionOptions,
   type BuildProductionSink,
   produceBuildAssets,
-  type ScriptableBuildPackage,
 } from './build-production.js';
 export {
   type CatalogImporterDisposition,
@@ -60,6 +60,16 @@ export {
   DEFAULT_CATALOG_IMPORTER_KEYS,
 } from './catalog-importer-policy.js';
 export { buildCatalogResult } from './catalog-inventory.js';
+export {
+  iesImporter,
+  validateIesProfilePayload,
+} from './ies/ies-importer.js';
+export {
+  type Lm63ParseError,
+  type Lm63TypeC,
+  parseLm63TypeC,
+} from './ies/parse-lm63.js';
+export { readFloat16LE, resampleTypeC } from './ies/resample-type-c.js';
 export {
   createImportProduct,
   finalizeImportProducts,
@@ -83,18 +93,37 @@ export {
   type MeshBinEncodeError,
   packMeshBinV4,
 } from './mesh-bin.js';
+export {
+  deriveDefaultLodScreenCoverages,
+  type MeshLodBounds,
+  type MeshLodContractError,
+  type MeshLodContractInput,
+  type MeshLodMaterialSlot,
+  type MeshLodMetaEntry,
+  type MeshLodRelation,
+  type ReconciledMeshLodMeta,
+  reconcileMeshLodMeta,
+  validateMeshLodContract,
+} from './mesh-lod.js';
 export { projectImportProductForBuild } from './pack-projection.js';
+export {
+  buildParameterizedScriptablePack,
+  buildParameterizedScriptablePackWorklist,
+  type ParameterizedScriptablePackBuildOptions,
+  type ParameterizedScriptablePackBuildProduct,
+  type ParameterizedScriptablePackBuildResult,
+  type ParameterizedScriptablePackWorkItem,
+  type ParameterizedScriptablePackWorklistOptions,
+  type ParameterizedScriptablePackWorklistProduct,
+} from './parameterized-scriptable-pack.js';
 export {
   type AssetOutputInput,
   type AssetOutputPayload,
   type AssetOutputProducer,
   AssetOutputProducerRegistry,
   type AssetOutputProduct,
-  type BuildScriptablePackOptions,
-  buildScriptablePack,
   type ScriptablePackAssetSnapshot,
   type ScriptablePackAssetSnapshotSource,
-  type ScriptablePackBuildBridgeResult,
   type ScriptablePackBuildProduct,
   type ScriptablePackDomainError,
   type ScriptablePackExternalEvidence,
@@ -103,25 +132,31 @@ export {
   type ScriptablePackStagedOutput,
 } from './scriptable-pack.js';
 export {
-  type AuthoredPackTransport,
-  type CookedAuthoredPack,
+  createScriptablePackFileAssetSnapshotSource,
+  type ScriptablePackFileAssetSnapshotError,
+  type ScriptablePackFileAssetSnapshotSourceOptions,
+} from './scriptable-pack-file-snapshot.js';
+export {
   canonicalScriptableSourcePath,
+  type DirectPackTransport,
+  type DirectPackTransportInput,
   declaredPackExternalOutputs,
-  materializePreparedScriptablePack,
-  type PreparedScriptablePack,
-  prepareAuthoredPackTransport,
-  produceScriptablePackProducts,
-  projectScriptablePackPublication,
+  type LegacyPackTransport,
+  materializePreparedParameterizedScriptablePack,
+  type ParameterizedScriptablePackInput,
+  type ParameterizedScriptablePackProductionOptions,
+  type PreparedParameterizedScriptablePack,
+  prepareDirectPackTransport,
+  prepareLegacyPackTransport,
+  produceParameterizedScriptablePackProducts,
   readCookedAuthoredPack,
   type ScriptablePackExternalImportOptions,
-  type ScriptablePackInput,
   type ScriptablePackPublicationFacts,
   type ScriptablePackTransportPaths,
-  type ScriptablePackTransportPolicy,
   type ScriptablePackTransportSink,
-  scriptablePackInputs,
 } from './scriptable-pack-host.js';
 export {
+  createPreExternalizedSceneAssetOutputProducer,
   createSceneAssetOutputProducer,
   createStandardAssetOutputProducerRegistry,
   materialAssetOutputProducer,
@@ -134,11 +169,6 @@ export {
   type ScriptablePackStagedOwner,
   type ScriptablePackStagedSnapshotOptions,
 } from './scriptable-pack-staged-snapshot.js';
-export {
-  produceScriptableSourcePackage,
-  type ScriptableSourcePackageProduct,
-  type ScriptableSourcePackageResult,
-} from './scriptable-source-package.js';
 export {
   finalizeSourcePackage,
   type ProducerReadiness,

package/src/mesh-bin.ts

@@ -76,6 +76,42 @@ function refsMeta(payload: MeshPayloadIn, refs: readonly string[]): Record<strin
       };
     },
   );
+  if (payload.lods !== undefined && payload.lods.length > 7) {
+    throw new Error('MeshAsset LOD chain supports at most seven lower-detail levels');
+  }
+  let previousCoverage = 1;
+  const seenLodGuids = new Set<string>();
+  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 !== undefined &&
+    (!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 === undefined || payload.submeshes.length === 0
@@ -89,6 +125,8 @@ function refsMeta(payload: MeshPayloadIn, refs: readonly string[]): Record<strin
     ...(payload.morphWeights === undefined
       ? {}
       : { morphWeights: jsonValue(payload.morphWeights) }),
+    ...(lods === undefined ? {} : { lods }),
+    ...(payload.lodHysteresis === undefined ? {} : { lodHysteresis: payload.lodHysteresis }),
   };
 }