@forgeax/engine-image 0.1.27 → 0.1.29

package/src/__tests__/cube-parser.unit.test.ts

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { type CubeLut, cubeLutBytes, parseCubeLut } from '../lut/cube-parser.js';
+
+function cubeSource(
+  size: number,
+  options: { readonly extra?: string; readonly rows?: string[] } = {},
+) {
+  const rows =
+    options.rows ??
+    Array.from({ length: size ** 3 }, (_, index) => {
+      const value = index / Math.max(1, size ** 3 - 1);
+      return `${value.toFixed(8)} ${value.toFixed(8)} ${value.toFixed(8)}`;
+    });
+  return [
+    '# canonical test source',
+    `LUT_3D_SIZE ${size}`,
+    'DOMAIN_MIN 0.0 0.0 0.0',
+    'DOMAIN_MAX 1.0 1.0 1.0',
+    options.extra ?? '',
+    ...rows,
+  ].join('\n');
+}
+
+describe('parseCubeLut', () => {
+  it.each([16, 32, 64])('accepts canonical %s^3 data with R-fastest ordering', (size) => {
+    const parsed = parseCubeLut(cubeSource(size), `fixture/canonical-${size}.cube`);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.value).toMatchObject({
+      size,
+      domainMin: [0, 0, 0],
+      domainMax: [1, 1, 1],
+    });
+    expect(parsed.value.values).toHaveLength(size ** 3 * 3);
+    expect(parsed.value.values.slice(0, 3)).toEqual(new Float32Array([0, 0, 0]));
+    expect(parsed.value.values.slice(-3)).toEqual(new Float32Array([1, 1, 1]));
+  });
+
+  it('emits deterministic linear rgba16float bytes with alpha one', () => {
+    const parsed = parseCubeLut(cubeSource(16), 'fixture/deterministic.cube');
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const first = cubeLutBytes(parsed.value);
+    const second = cubeLutBytes(parsed.value);
+    expect(first).toEqual(second);
+    expect(first.byteLength).toBe(16 ** 3 * 4 * 2);
+    expect(createHash('sha256').update(first).digest('hex')).toBe(
+      '38344bf4db2170fd88c41f0acda182470777eed00688bcf214f2127ce62896e9',
+    );
+  });
+
+  it.each([
+    ['missing size', '# no size\n0 0 0'],
+    ['non-cubic size', cubeSource(16, { extra: 'LUT_3D_SIZE 32' })],
+    ['short data', cubeSource(16, { rows: ['0 0 0'] })],
+    [
+      'extra data',
+      cubeSource(16, { rows: [...Array.from({ length: 16 ** 3 }, () => '0 0 0'), '0 0 0'] }),
+    ],
+    [
+      'non-finite data',
+      cubeSource(16, { rows: ['nan 0 0', ...Array.from({ length: 16 ** 3 - 1 }, () => '0 0 0')] }),
+    ],
+    [
+      'out of domain',
+      cubeSource(16, { rows: ['2 0 0', ...Array.from({ length: 16 ** 3 - 1 }, () => '0 0 0')] }),
+    ],
+  ])('rejects %s with structured source diagnostics', (_name, source) => {
+    const parsed = parseCubeLut(source, 'fixture/invalid.cube');
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.error.code).toMatch(/^cube-/);
+    expect(parsed.error.expected).toContain('LUT_3D_SIZE');
+    expect(parsed.error.hint).toContain('sourceKey');
+    expect(parsed.error.detail).toMatchObject({ sourceKey: 'fixture/invalid.cube' });
+  });
+
+  it('keeps the parser type independent from TextureAsset runtime loading', () => {
+    const parsed = parseCubeLut(cubeSource(16), 'fixture/runtime-boundary.cube');
+    expect(parsed.ok).toBe(true);
+    expect(typeof ({} as CubeLut)).toBe('object');
+  });
+});

package/src/__tests__/cube-producer.integration.test.ts

@@ -0,0 +1,94 @@
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import {
+  finalizeImportProducts,
+  projectImportProductForBuild,
+  textureAssetOutputProducer,
+} from '@forgeax/engine-import';
+import { describe, expect, it } from 'vitest';
+import { produceCubeTexture } from '../lut/cube-producer.js';
+
+const GUID = '019ffa97-3000-7000-8000-000000000901';
+const SOURCE_KEY = 'color-grading/neutral';
+
+function cubeSource(size = 16): string {
+  const rows = Array.from({ length: size ** 3 }, () => '0 0.5 1');
+  return [
+    'TITLE "ForgeaX neutral LUT"',
+    `LUT_3D_SIZE ${size}`,
+    'DOMAIN_MIN 0 0 0',
+    'DOMAIN_MAX 1 1 1',
+    ...rows,
+    '',
+  ].join('\n');
+}
+
+function digest(bytes: Uint8Array): string {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+describe('cube texture producer identity', () => {
+  it('keeps ordinary texture shape, bytes, and Pack artifact identity closed', async () => {
+    const produced = produceCubeTexture(
+      { guid: GUID, source: 'assets/neutral.cube', sourceKey: SOURCE_KEY },
+      cubeSource(),
+    );
+    expect(produced.ok).toBe(true);
+    if (!produced.ok) return;
+
+    const asset = produced.value;
+    expect(asset).toMatchObject({ guid: GUID, kind: 'texture' });
+    expect(asset.payload.kind).toBe('texture');
+    expect(asset.payload.shape).toEqual({
+      viewDimension: '3d',
+      extent: { width: 16, height: 16, depth: 16 },
+    });
+    expect(asset.payload.format).toBe('rgba16float');
+    expect(asset.payload.colorSpace).toBe('linear');
+    expect(asset.payload.mips).toEqual({ kind: 'none' });
+
+    const standard = await textureAssetOutputProducer.produce({
+      guid: GUID,
+      sourceKey: SOURCE_KEY,
+      asset: asset.payload,
+    });
+    expect(standard.ok).toBe(true);
+    if (!standard.ok) return;
+    const producedBody = asset.artifacts.body;
+    const standardBody = standard.value.artifacts.body;
+    expect(producedBody).toBeDefined();
+    expect(standardBody).toBeDefined();
+    if (producedBody === undefined || standardBody === undefined) return;
+    expect(standardBody.mediaType).toBe(producedBody.mediaType);
+    expect(standardBody.assetCodec).toEqual(producedBody.assetCodec);
+    expect(Buffer.from(standardBody.bytes).equals(Buffer.from(producedBody.bytes))).toBe(true);
+
+    const pack = projectImportProductForBuild({
+      assets: [{ ...asset, artifacts: standard.value.artifacts }],
+    });
+    expect(pack.assets).toHaveLength(1);
+    expect(pack.assets[0]).toMatchObject({ guid: GUID, kind: 'texture' });
+    expect(pack.assets[0]?.payload.kind).toBe('texture');
+    expect(pack.assets[0]?.payload.shape).toEqual({
+      viewDimension: '3d',
+      extent: { width: 16, height: 16, depth: 16 },
+    });
+    expect(pack.assets[0]?.payload.format).toBe('rgba16float');
+    const products = await finalizeImportProducts(
+      {
+        assets: [{ ...asset, artifacts: standard.value.artifacts }],
+        sourceDependencies: ['assets/neutral.cube'],
+      },
+      'sha256:source-neutral',
+    );
+    expect(products[0]).toMatchObject({
+      guid: GUID,
+      digest: expect.stringMatching(/^sha256:/),
+      receipt: { guid: GUID, inputFingerprint: 'sha256:source-neutral', status: 'succeeded' },
+    });
+    expect(products[0]?.artifacts.body?.integrity).toEqual({
+      algorithm: 'sha256',
+      digest: digest(asset.artifacts.body?.bytes ?? new Uint8Array()),
+    });
+  });
+});

package/src/__tests__/cube-recovery.integration.test.ts

@@ -0,0 +1,52 @@
+import type { ImportContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { importCubeSource } from '../lut/cube-producer.js';
+
+const GUID = '019ffa97-3000-7000-8000-000000000902';
+const SOURCE_KEY = 'color-grading/recovery';
+
+function context(source: string, bytes: Uint8Array): ImportContext {
+  return {
+    source,
+    subAssets: [{ guid: GUID, sourceIndex: 0, kind: 'texture' as const, sourceKey: SOURCE_KEY }],
+    importSettings: {},
+    readSource: async () => ({ ok: true as const, value: bytes }),
+    readSibling: async () => {
+      throw new Error('not used');
+    },
+    decodeImage: async () => {
+      throw new Error('not used');
+    },
+  };
+}
+
+function cubeSource(): string {
+  const rows = Array.from({ length: 16 ** 3 }, () => '0.5 0.5 0.5');
+  return ['LUT_3D_SIZE 16', 'DOMAIN_MIN 0 0 0', 'DOMAIN_MAX 1 1 1', ...rows, ''].join('\n');
+}
+
+describe('cube source recovery', () => {
+  it('rejects invalid source before Pack and retries the same identity after repair', async () => {
+    const source = 'assets/recovery.cube';
+    const invalid = await importCubeSource(
+      context(source, new TextEncoder().encode('LUT_3D_SIZE 16')),
+    );
+    expect(invalid.ok).toBe(false);
+    if (invalid.ok) return;
+    expect(invalid.error.code).toBe('source-validation-failed');
+    expect(JSON.stringify(invalid.error.detail)).toContain(`${source}#DOMAIN_MIN/MAX`);
+    expect(JSON.stringify(invalid.error.detail)).toContain('cube-source-parser');
+
+    const repaired = await importCubeSource(
+      context(source, new TextEncoder().encode(cubeSource())),
+    );
+    expect(repaired.ok).toBe(true);
+    if (!repaired.ok) return;
+    expect(repaired.value.sourceDependencies).toEqual([source]);
+    expect(repaired.value.assets[0]).toMatchObject({ guid: GUID, kind: 'texture' });
+    expect(repaired.value.assets[0]?.payload).toMatchObject({
+      shape: { viewDimension: '3d', extent: { width: 16, height: 16, depth: 16 } },
+      format: 'rgba16float',
+    });
+  });
+});

package/src/__tests__/errors.test-d.ts

@@ -47,11 +47,11 @@ describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () =
         case 'image-dimension-out-of-bounds':
           return 'downscale source under device caps maxDimension';
         case 'image-meta-missing':
-          return 'run forgeax-engine-remote-asset import <path>';
+          return 'run forgeax asset import <path> --root <project>';
         case 'image-hdr-decode-failed':
           return 'verify Radiance RGBE header and FORMAT=32-bit_rle_rgbe field';
         case 'atlas-empty-input':
-          return 'verify forgeax-engine-remote-asset atlas --input glob matches at least 1 PNG';
+          return 'verify forgeax asset atlas --input glob matches at least 1 PNG';
         case 'atlas-size-exceeded':
           return 'downscale source or split atlas under maxAtlasSize cap';
         case 'atlas-region-mismatch':

package/src/__tests__/image-importer-topology.unit.test.ts

@@ -26,6 +26,24 @@ function readSourceFor(bytes: Uint8Array): ImportContext['readSource'] {
 }
 
 describe('image importer required output topology', () => {
+  it('reserves .cube sources for the ordinary texture producer topology', async () => {
+    const registry = imageRegistry();
+    const result = await runImport(
+      imageMeta('grading.cube', [
+        { guid: PNG_GUID, sourceIndex: 0, sourceKey: 'grading/lut', kind: 'texture' },
+      ]),
+      registry,
+      { readSource: readSourceFor(new TextEncoder().encode(cubeFixture(16))) },
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value) return;
+    expect(result.value.product.assets[0]).toMatchObject({
+      guid: PNG_GUID,
+      kind: 'texture',
+      payload: { kind: 'texture', shape: { viewDimension: '3d' } },
+    });
+  });
+
   it.each([
     { source: 'texture.png', label: 'PNG' },
     { source: 'texture.jpeg', label: 'JPEG' },
@@ -207,3 +225,12 @@ describe('image importer required output topology', () => {
     );
   });
 });
+
+function cubeFixture(size: number): string {
+  return [
+    `LUT_3D_SIZE ${size}`,
+    'DOMAIN_MIN 0 0 0',
+    'DOMAIN_MAX 1 1 1',
+    ...Array.from({ length: size ** 3 }, () => '0 0 0'),
+  ].join('\n');
+}

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

@@ -89,7 +89,7 @@ import { makeCorruptPng, makeJpg, makePng } from './make-fixture.js';
           if (r.error.detail.code !== 'image-meta-missing') return;
           expect(r.error.detail.sourcePath).toBe(sourcePath);
           expect(r.error.detail.expectedSidecarPath).toBe(join(dir, 'wood.png.meta.json'));
-          expect(r.error.hint).toContain('forgeax-engine-remote-asset');
+          expect(r.error.hint).toContain('forgeax asset');
         } finally {
           rmSync(dir, { recursive: true, force: true });
         }

package/src/decode-image-from-file.ts

@@ -82,7 +82,7 @@ function deriveSidecarPath(sourcePath: string): string {
  *
  * AC-17 path (a) lock: when the sidecar is absent, the returned error
  * carries `detail.sourcePath` + `detail.expectedSidecarPath` so AI users
- * read .hint and run `forgeax-engine-remote-asset import <path>` to
+ * read .hint and run `forgeax asset import <path> --root <project>` to
  * self-recover (charter P3 explicit failure + IDE jump-to-source).
  */
 export async function decodeImageFromFile(

package/src/errors.ts

@@ -60,3 +60,38 @@ export function imageError<C extends ImageErrorCode>(
 }
 
 export { IMAGE_ERROR_EXPECTED };
+
+export type CubeParserErrorCode =
+  | 'cube-header-invalid'
+  | 'cube-size-invalid'
+  | 'cube-domain-invalid'
+  | 'cube-row-invalid'
+  | 'cube-data-count-invalid';
+
+export interface CubeParserError {
+  readonly code: CubeParserErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly sourceKey: string;
+    readonly line?: number;
+    readonly field: string;
+    readonly actual: unknown;
+  };
+}
+
+export function cubeParserError(
+  code: CubeParserErrorCode,
+  sourceKey: string,
+  field: string,
+  actual: unknown,
+  line?: number,
+): CubeParserError {
+  const lineDetail = line === undefined ? '' : ` at line ${line}`;
+  return {
+    code,
+    expected: `valid .cube source with LUT_3D_SIZE, DOMAIN_MIN/MAX, and exactly N^3 RGB rows${lineDetail}`,
+    hint: `repair field ${field} in sourceKey ${sourceKey} and re-run the Node image producer`,
+    detail: { sourceKey, field, actual, ...(line === undefined ? {} : { line }) },
+  };
+}

package/src/image-importer.ts

@@ -51,6 +51,7 @@ import type {
 import { IMPORT_ERROR_HINTS, ImportError } from '@forgeax/engine-types';
 import type { CompressionMode } from './ktx2-encode.js';
 import { encodeTextureToKtx2, resolveEncodeMode } from './ktx2-encode.js';
+import { importCubeSource } from './lut/cube-producer.js';
 import { parseImage } from './parse-image.js';
 import { importTextureSource } from './texture/importer.js';
 
@@ -67,7 +68,12 @@ type RequiredImageOutputKind = 'texture' | 'equirect';
 function requiredImageOutputKind(source: string): RequiredImageOutputKind | undefined {
   const lower = source.toLowerCase();
   if (lower.endsWith('.hdr')) return 'equirect';
-  if (mimeFromSource(source) !== undefined || lower.endsWith('.basis') || lower.endsWith('.ktx2')) {
+  if (
+    mimeFromSource(source) !== undefined ||
+    lower.endsWith('.basis') ||
+    lower.endsWith('.ktx2') ||
+    lower.endsWith('.cube')
+  ) {
     return 'texture';
   }
   return undefined;
@@ -590,6 +596,9 @@ async function importImage(ctx: ImportContext): Promise<ImportResult> {
   if (ctx.source.toLowerCase().endsWith('.texture.json')) {
     return importTextureSource(ctx);
   }
+  if (ctx.source.toLowerCase().endsWith('.cube')) {
+    return importCubeSource(ctx);
+  }
   const requiredKind = requiredImageOutputKind(ctx.source);
   if (requiredKind !== undefined) {
     const topologyError = validateImageOutputTopology(ctx, requiredKind);
@@ -870,3 +879,6 @@ export const imageImporter: Importer = {
   import: importImage,
   capabilities: { decodeImage: decodeImageForImport },
 };
+
+export { cubeLutBytes, parseCubeLut } from './lut/cube-parser.js';
+export { importCubeSource, produceCubeTexture } from './lut/cube-producer.js';

package/src/lut/cube-parser.ts

@@ -0,0 +1,185 @@
+import type { CubeParserError } from '../errors.js';
+import { cubeParserError } from '../errors.js';
+
+export interface CubeLut {
+  readonly size: 16 | 32 | 64;
+  readonly domainMin: readonly [number, number, number];
+  readonly domainMax: readonly [number, number, number];
+  readonly values: Float32Array;
+  readonly sourceKey: string;
+}
+
+export type CubeLutResult =
+  | { readonly ok: true; readonly value: CubeLut }
+  | { readonly ok: false; readonly error: CubeParserError };
+
+const ALLOWED_SIZES = new Set([16, 32, 64]);
+
+function finite(value: number): boolean {
+  return Number.isFinite(value);
+}
+
+function parseTriple(tokens: readonly string[]): readonly [number, number, number] | undefined {
+  if (tokens.length !== 3) return undefined;
+  const values = tokens.map(Number);
+  if (!values.every(finite)) return undefined;
+  const [red, green, blue] = values;
+  if (red === undefined || green === undefined || blue === undefined) return undefined;
+  return [red, green, blue];
+}
+
+function float32ToFloat16(value: number): number {
+  const input = new Float32Array([value]);
+  const bits = new Uint32Array(input.buffer).at(0) ?? 0;
+  const sign = (bits >>> 16) & 0x8000;
+  const exponent = (bits >>> 23) & 0xff;
+  const fraction = bits & 0x7fffff;
+  if (exponent === 0xff) return sign | (fraction === 0 ? 0x7c00 : 0x7e00);
+  const halfExponent = exponent - 127 + 15;
+  if (halfExponent >= 0x1f) return sign | 0x7c00;
+  if (halfExponent <= 0) {
+    if (halfExponent < -10) return sign;
+    const mantissa = (fraction | 0x800000) >>> (1 - halfExponent);
+    return sign | ((mantissa + 0x1000) >>> 13);
+  }
+  return sign | (halfExponent << 10) | ((fraction + 0x1000) >>> 13);
+}
+
+export function parseCubeLut(source: string, sourceKey = '<inline .cube>'): CubeLutResult {
+  let size: number | undefined;
+  let domainMin: readonly [number, number, number] | undefined;
+  let domainMax: readonly [number, number, number] | undefined;
+  const values: number[] = [];
+  const lines = source.split(/\r?\n/);
+
+  for (const [index, rawLine] of lines.entries()) {
+    const line = rawLine.replace(/#.*/, '').trim();
+    const lineNumber = index + 1;
+    if (line.length === 0) continue;
+    const tokens = line.split(/\s+/);
+    const directive = tokens.shift();
+    if (directive === undefined) continue;
+    if (directive === 'TITLE') continue;
+    if (directive === 'LUT_3D_SIZE') {
+      const sizeToken = tokens[0];
+      if (
+        size !== undefined ||
+        tokens.length !== 1 ||
+        sizeToken === undefined ||
+        !/^\d+$/.test(sizeToken)
+      ) {
+        return {
+          ok: false,
+          error: cubeParserError('cube-size-invalid', sourceKey, 'LUT_3D_SIZE', line, lineNumber),
+        };
+      }
+      size = Number(sizeToken);
+      if (!ALLOWED_SIZES.has(size)) {
+        return {
+          ok: false,
+          error: cubeParserError('cube-size-invalid', sourceKey, 'LUT_3D_SIZE', size, lineNumber),
+        };
+      }
+      continue;
+    }
+    if (directive === 'DOMAIN_MIN' || directive === 'DOMAIN_MAX') {
+      const triple = parseTriple(tokens);
+      if (triple === undefined) {
+        return {
+          ok: false,
+          error: cubeParserError('cube-domain-invalid', sourceKey, directive, line, lineNumber),
+        };
+      }
+      if (directive === 'DOMAIN_MIN') {
+        if (domainMin !== undefined)
+          return {
+            ok: false,
+            error: cubeParserError('cube-domain-invalid', sourceKey, directive, line, lineNumber),
+          };
+        domainMin = triple;
+      } else {
+        if (domainMax !== undefined)
+          return {
+            ok: false,
+            error: cubeParserError('cube-domain-invalid', sourceKey, directive, line, lineNumber),
+          };
+        domainMax = triple;
+      }
+      continue;
+    }
+    if (directive === 'LUT_1D_SIZE') {
+      return {
+        ok: false,
+        error: cubeParserError('cube-header-invalid', sourceKey, directive, line, lineNumber),
+      };
+    }
+    const row = parseTriple([directive, ...tokens]);
+    if (row === undefined || row.some((value) => value < 0 || value > 1)) {
+      return {
+        ok: false,
+        error: cubeParserError('cube-row-invalid', sourceKey, 'RGB row', line, lineNumber),
+      };
+    }
+    values.push(...row);
+  }
+
+  if (size === undefined)
+    return {
+      ok: false,
+      error: cubeParserError('cube-header-invalid', sourceKey, 'LUT_3D_SIZE', 'missing'),
+    };
+  if (domainMin === undefined || domainMax === undefined) {
+    return {
+      ok: false,
+      error: cubeParserError('cube-domain-invalid', sourceKey, 'DOMAIN_MIN/MAX', 'missing'),
+    };
+  }
+  if (
+    domainMin.some((value, index) => {
+      const maxValue = domainMax[index];
+      return maxValue !== undefined && value >= maxValue;
+    })
+  ) {
+    return {
+      ok: false,
+      error: cubeParserError('cube-domain-invalid', sourceKey, 'DOMAIN_MIN/MAX', {
+        domainMin,
+        domainMax,
+      }),
+    };
+  }
+  const expectedValues = size ** 3 * 3;
+  if (values.length !== expectedValues) {
+    return {
+      ok: false,
+      error: cubeParserError('cube-data-count-invalid', sourceKey, 'RGB rows', {
+        expected: expectedValues / 3,
+        actual: values.length / 3,
+      }),
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      size: size as 16 | 32 | 64,
+      domainMin,
+      domainMax,
+      values: new Float32Array(values),
+      sourceKey,
+    },
+  };
+}
+
+export function cubeLutBytes(lut: CubeLut): Uint8Array {
+  const bytes = new Uint8Array(lut.size ** 3 * 4 * 2);
+  const view = new DataView(bytes.buffer);
+  for (let index = 0; index < lut.size ** 3; index += 1) {
+    const valueOffset = index * 3;
+    const byteOffset = index * 8;
+    view.setUint16(byteOffset, float32ToFloat16(lut.values[valueOffset] ?? 0), true);
+    view.setUint16(byteOffset + 2, float32ToFloat16(lut.values[valueOffset + 1] ?? 0), true);
+    view.setUint16(byteOffset + 4, float32ToFloat16(lut.values[valueOffset + 2] ?? 0), true);
+    view.setUint16(byteOffset + 6, 0x3c00, true);
+  }
+  return bytes;
+}