@forgeax/engine-image 0.1.19 → 0.1.21

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

@@ -9,20 +9,21 @@ import type {
 } from '@forgeax/engine-types';
 import { describe, expectTypeOf, it } from 'vitest';
 
-// Type-only tests. Verify the 8-member ImageErrorCode closed union compiles
+// Type-only tests. Verify the 9-member ImageErrorCode closed union compiles
 // an exhaustive switch without a default arm (charter P4 explicit failure).
 // Verifies the discriminated ImageErrorDetail narrowing per .code (charter
 // P3 machine-readable union > prose; AGENTS.md Error model row pattern).
 //
 // feat-20260521-sprite-atlas-animation M1 T-03 update: union grew from 5 to
 // 8 with the atlas-* triplet (atlas-empty-input / atlas-size-exceeded /
-// atlas-region-mismatch). The exact-member assertion + exhaustive switch
+// atlas-region-mismatch); the 9th arm is the image-owned PixelSurface
+// authoring error. The exact-member assertion + exhaustive switch
 // arms below mirror the SSOT in @forgeax/engine-types ImageErrorCode +
 // ImageErrorDetail so a future minor add still fails this file at compile
 // time until the new arm + .expected + .hint rows are supplied.
 
 describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () => {
-  it('ImageErrorCode is the exact 8-member union literal set', () => {
+  it('ImageErrorCode is the exact 9-member union literal set', () => {
     expectTypeOf<ImageErrorCode>().toEqualTypeOf<
       | 'image-decode-failed'
       | 'image-format-unsupported'
@@ -32,6 +33,7 @@ describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () =
       | 'atlas-empty-input'
       | 'atlas-size-exceeded'
       | 'atlas-region-mismatch'
+      | 'image-surface-invalid'
     >();
   });
 
@@ -54,6 +56,8 @@ describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () =
           return 'downscale source or split atlas under maxAtlasSize cap';
         case 'atlas-region-mismatch':
           return 'shelfPack regions exceed atlas footprint -- packer safety net';
+        case 'image-surface-invalid':
+          return 'repair PixelSurface authoring input';
       }
     }
     expectTypeOf(recover).toBeFunction();
@@ -78,6 +82,8 @@ describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () =
           return `atlas-size:${detail.name}:${detail.width}x${detail.height}>${detail.maxAtlasSize}`;
         case 'atlas-region-mismatch':
           return `atlas-region:${detail.name}:${detail.regionsTotalPixels}>${detail.atlasPixels}`;
+        case 'image-surface-invalid':
+          return `surface:${detail.operation}:${detail.field}`;
       }
     }
     expectTypeOf(describe_).toBeFunction();
@@ -102,6 +108,8 @@ describe('ImageErrorCode + ImageErrorDetail closed union compile contract', () =
           return `${error.detail.name}:${error.detail.maxAtlasSize}`;
         case 'atlas-region-mismatch':
           return `${error.detail.name}:${error.detail.atlasPixels}`;
+        case 'image-surface-invalid':
+          return `${error.detail.operation}:${error.detail.field}`;
       }
     }
 

package/src/__tests__/image-importer-conversion-failure.unit.test.ts

@@ -61,6 +61,8 @@ function expectConversionFailure(
         code: diagnosticCode,
         rule: expect.stringMatching(/^image-conversion-/),
         severity: 'error',
+        expected: expect.any(String),
+        hint: expect.any(String),
       }),
     ],
   });
@@ -206,6 +208,25 @@ describe('image importer conversion failure through the public runner', () => {
     expect(state.reads).toBe(6);
   });
 
+  it.each([
+    { colorSpace: 'srgb' as const, format: 'rgba8unorm-srgb' },
+    { colorSpace: 'linear' as const, format: 'rgba8unorm' },
+  ])('publishes a format matching the authored $colorSpace color space', async (input) => {
+    const result = await runImport(
+      meta('valid.png', { colorSpace: input.colorSpace, mipmap: 'none' }),
+      registry(),
+      { readSource: source({ bytes: makePng(1, 1, [1, 2, 3, 255]), reads: 0 }) },
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value) return;
+    expect(result.value.pack.assets[0]?.payload).toMatchObject({
+      colorSpace: input.colorSpace,
+      format: input.format,
+      mips: { kind: 'none' },
+    });
+  });
+
   it.skipIf(!pkgBuilt)('repairs raw Basis color-space settings in the same registry', async () => {
     const state = { bytes: await makeRawBasis(), reads: 0 };
     const importerRegistry = registry();
@@ -226,7 +247,11 @@ describe('image importer conversion failure through the public runner', () => {
     if (!repaired.ok || 'skipped' in repaired.value) return;
     expect(repaired.value.pack.assets[0]).toMatchObject({
       guid: GUID,
-      payload: { colorSpace: 'linear', width: 4, height: 4 },
+      payload: {
+        colorSpace: 'linear',
+        shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
+        mips: { kind: 'none' },
+      },
       artifacts: {
         body: {
           mediaType: 'application/x-forgeax-basis',
@@ -270,7 +295,11 @@ describe('image importer conversion failure through the public runner', () => {
     if (!repaired.ok || 'skipped' in repaired.value) return;
     expect(repaired.value.pack.assets[0]).toMatchObject({
       guid: GUID,
-      payload: { colorSpace: 'linear', width: 4, height: 4, mipmap: false },
+      payload: {
+        colorSpace: 'linear',
+        shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
+        mips: { kind: 'none' },
+      },
       artifacts: {
         body: {
           mediaType: 'image/ktx2',

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

@@ -172,10 +172,10 @@ describe('image importer required output topology', () => {
       sourceIndex: 0,
       payload: {
         kind: 'texture',
-        width: 1,
-        height: 1,
+        shape: { viewDimension: '2d', extent: { width: 1, height: 1 } },
         format: 'rgba8unorm-srgb',
         colorSpace: 'srgb',
+        mips: { kind: 'none' },
       },
       artifacts: {
         body: {

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

@@ -601,8 +601,7 @@ import { makeCorruptPng, makeJpg, makePng } from './make-fixture.js';
 
         const payload = asset?.payload as unknown as Record<string, unknown>;
         expect(payload.kind).toBe('texture');
-        expect(payload.width).toBe(8);
-        expect(payload.height).toBe(4);
+        expect(payload.shape).toEqual({ viewDimension: '2d', extent: { width: 8, height: 4 } });
         expect(payload.format).toBe('rgba8unorm-srgb');
         expect(payload.colorSpace).toBe('srgb');
         expect(payload.data).toBeInstanceOf(Uint8Array);
@@ -859,8 +858,7 @@ import { makeCorruptPng, makeJpg, makePng } from './make-fixture.js';
 
         const payload = asset?.payload as TextureAsset;
         expect(payload.kind).toBe('texture');
-        expect(payload.width).toBe(8);
-        expect(payload.height).toBe(4);
+        expect(payload.shape).toEqual({ viewDimension: '2d', extent: { width: 8, height: 4 } });
         expect(payload.format).toBe('rgba8unorm-srgb');
         expect(payload.colorSpace).toBe('srgb');
         expect(payload.data.length).toBe(8 * 4 * 4);

package/src/__tests__/ktx2-basis-importer.unit.test.ts

@@ -97,11 +97,10 @@ describe.skipIf(!pkgBuilt)('KTX2/Basis source importer', () => {
     if (!result.ok) return;
     expect(result.value.assets[0]?.payload).toMatchObject({
       kind: 'texture',
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm',
       colorSpace: 'linear',
-      mipmap: false,
+      mips: { kind: 'none' },
     });
     expect(result.value.assets[0]?.artifacts.body?.assetCodec).toMatchObject({
       name: 'basis',

package/src/__tests__/pixel-surface.unit.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { createPixelSurface, toAssetPack } from '../index.js';
+
+const META = {
+  guid: '01928000-7c00-7000-8000-000000000099',
+  colorSpace: 'srgb' as const,
+  mipmap: 'none' as const,
+  addressMode: 'repeat' as const,
+  filterMode: 'nearest' as const,
+};
+
+function surface(width = 4, height = 3) {
+  const result = createPixelSurface({ width, height, colorSpace: 'srgb', mipmap: false });
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('PixelSurface', () => {
+  it('rejects malformed dimensions and channel/seed values through ImageError', () => {
+    const badDimension = createPixelSurface({ width: 0, height: 2 });
+    expect(badDimension.ok).toBe(false);
+    if (!badDimension.ok) {
+      expect(badDimension.error.code).toBe('image-surface-invalid');
+      if (badDimension.error.code === 'image-surface-invalid') {
+        expect(badDimension.error.detail.expected).toContain('positive integer');
+        expect(badDimension.error.detail.code).toBe('image-surface-invalid');
+      }
+    }
+
+    const candidate = surface();
+    const badColor = candidate.setPixel(0, 0, [0, 0, 256, 255]);
+    expect(badColor.ok).toBe(false);
+    if (!badColor.ok && badColor.error.code === 'image-surface-invalid') {
+      expect(badColor.error.detail.operation).toBe('set-pixel');
+    }
+
+    const badSeed = candidate.fillNoise(Number.NaN);
+    expect(badSeed.ok).toBe(false);
+    if (!badSeed.ok && badSeed.error.code === 'image-surface-invalid') {
+      expect(badSeed.error.detail.operation).toBe('noise');
+    }
+  });
+
+  it('rounds coordinates, clips writes, and keeps exact RGBA8 channel order', () => {
+    const candidate = surface();
+    expect(candidate.setPixel(1.4, 1.6, [10, 20, 30, 40]).ok).toBe(true);
+    expect(candidate.data.slice((2 * 4 + 1) * 4, (2 * 4 + 2) * 4)).toEqual(
+      Uint8Array.of(10, 20, 30, 40),
+    );
+    expect(candidate.fillRect(-1.2, -1.2, 3.1, 3.1, [1, 2, 3, 4]).ok).toBe(true);
+    expect(candidate.data.slice(0, 4)).toEqual(Uint8Array.of(1, 2, 3, 4));
+    expect(candidate.fillCircle(3, 2, 1, { r: 9, g: 8, b: 7, a: 6 }).ok).toBe(true);
+    expect(candidate.data.slice((2 * 4 + 3) * 4, (2 * 4 + 4) * 4)).toEqual(
+      Uint8Array.of(9, 8, 7, 6),
+    );
+  });
+
+  it('snapshots overlapping blits before writing', () => {
+    const candidate = surface(4, 1);
+    for (let x = 0; x < 4; x += 1) {
+      expect(candidate.setPixel(x, 0, [x + 1, 0, 0, 255]).ok).toBe(true);
+    }
+    expect(candidate.blit(candidate, 1, 0, { x: 0, y: 0, width: 3, height: 1 }).ok).toBe(true);
+    expect(Array.from(candidate.data.filter((_value, index) => index % 4 === 0))).toEqual([
+      1, 1, 2, 3,
+    ]);
+  });
+
+  it('produces byte-identical seeded noise and a regular TextureAsset/Pack carrier', () => {
+    const first = surface();
+    const second = surface();
+    expect(first.fillNoise(42, { min: 10, max: 200, alpha: 123 }).ok).toBe(true);
+    expect(second.noise(42, { min: 10, max: 200, alpha: 123 }).ok).toBe(true);
+    expect(first.data).toEqual(second.data);
+    expect(first.toTextureAsset()).toMatchObject({
+      kind: 'texture',
+      shape: {
+        viewDimension: '2d',
+        extent: { width: 4, height: 3 },
+      },
+      format: 'rgba8unorm-srgb',
+      colorSpace: 'srgb',
+      mips: { kind: 'none' },
+    });
+    const decoded = first.toDecodedImage();
+    const pack = toAssetPack(decoded, META);
+    expect(pack.subAssets).toEqual([{ guid: META.guid, sourceIndex: 0, kind: 'texture' }]);
+    expect(pack.importSettings.mipmap).toBe('none');
+    const changed = decoded.bytes.slice();
+    changed[0] = (changed[0] ?? 0) ^ 1;
+    expect(changed).not.toEqual(decoded.bytes);
+  });
+});

package/src/__tests__/texture-source-descriptor.integration.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { produceTextureSource } from '../texture/importer.js';
+import type { TextureSourceDescriptor } from '../texture/source-descriptor.js';
+import { parseTextureSourceDescriptor } from '../texture/source-descriptor.js';
+
+const GUID = '019ffa97-3000-7000-8000-000000000101';
+const SOURCE_KEY = 'density/volume';
+const BODY_BYTES = 64 * 64 * 64;
+
+function densityDescriptor(): TextureSourceDescriptor {
+  return {
+    schemaVersion: '1',
+    shape: {
+      viewDimension: '3d',
+      extent: { width: 64, height: 64, depth: 64 },
+    },
+    format: 'r8unorm',
+    colorSpace: 'linear',
+    mips: { kind: 'none' },
+    rawSibling: 'density.raw',
+  };
+}
+
+function arrayDescriptor(): TextureSourceDescriptor {
+  return {
+    schemaVersion: '1',
+    shape: {
+      viewDimension: '2d-array',
+      extent: { width: 8, height: 4, layers: 3 },
+    },
+    format: 'r8unorm',
+    colorSpace: 'linear',
+    mips: { kind: 'none' },
+    rawSibling: 'array.raw',
+  };
+}
+
+describe('texture source descriptor producer contract', () => {
+  it('produces one 64^3 density asset from its raw sibling', async () => {
+    const descriptor = densityDescriptor();
+    const raw = new Uint8Array(BODY_BYTES);
+    raw[0] = 17;
+    raw[raw.length - 1] = 231;
+    const readSibling = async (uri: string) => {
+      expect(uri).toBe(descriptor.rawSibling);
+      return { ok: true as const, value: raw };
+    };
+
+    const result = await produceTextureSource({
+      descriptor,
+      guid: GUID,
+      sourceKey: SOURCE_KEY,
+      readSibling,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.guid).toBe(GUID);
+    expect(result.value.kind).toBe('texture');
+    expect(result.value.payload).toEqual({
+      kind: 'texture',
+      shape: descriptor.shape,
+      format: descriptor.format,
+      colorSpace: 'linear',
+      mips: { kind: 'none' },
+      data: raw,
+    });
+    expect(result.value.artifacts.body?.bytes).toEqual(raw);
+    expect(result.value.artifacts.body?.mediaType).toBe('application/x-forgeax-r8');
+  });
+
+  it('keeps array and 3d payloads equivalent without minting slice identities', async () => {
+    const descriptors = [arrayDescriptor(), densityDescriptor()];
+    for (const descriptor of descriptors) {
+      const layoutBytes = descriptor.shape.viewDimension === '3d' ? BODY_BYTES : 8 * 4 * 3;
+      const raw = new Uint8Array(layoutBytes);
+      const result = await produceTextureSource({
+        descriptor,
+        guid: GUID,
+        sourceKey: SOURCE_KEY,
+        readSibling: async () => ({ ok: true as const, value: raw }),
+      });
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) continue;
+      expect(result.value.guid).toBe(GUID);
+      expect(result.value.payload.shape).toEqual(descriptor.shape);
+      expect(result.value.artifacts.body?.bytes).toEqual(raw);
+    }
+  });
+
+  it('rejects missing sibling and invalid descriptor facts structurally', async () => {
+    const missing = await produceTextureSource({
+      descriptor: densityDescriptor(),
+      guid: GUID,
+      sourceKey: SOURCE_KEY,
+      readSibling: async () => ({ ok: false as const, error: new Error('missing raw sibling') }),
+    });
+    expect(missing.ok).toBe(false);
+    if (!missing.ok) {
+      expect(missing.error.code).toBe('source-read-failed');
+      expect(missing.error.detail).toMatchObject({ sourceKey: SOURCE_KEY, sibling: 'density.raw' });
+    }
+
+    const invalid = parseTextureSourceDescriptor({
+      ...densityDescriptor(),
+      shape: { viewDimension: '3d', extent: { width: 64, height: 64, depth: 64 } },
+      format: 'bc7-rgba-unorm',
+      mips: { kind: 'none' },
+    });
+    expect(invalid.ok).toBe(false);
+    if (!invalid.ok) {
+      expect(invalid.error.code).toBe('texture-format-dimension-unsupported');
+      expect(invalid.error.detail).toMatchObject({ format: 'bc7-rgba-unorm', viewDimension: '3d' });
+    }
+  });
+});

package/src/errors.ts

@@ -25,6 +25,8 @@ const IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {
   'atlas-size-exceeded':
     'image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint',
   'atlas-region-mismatch': 'sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight',
+  'image-surface-invalid':
+    'PixelSurface dimensions and authoring inputs satisfy the RGBA8 contract',
 };
 
 /** Runtime implementation of the correlated `ImageErrorFor<C>` envelope. */

package/src/image-importer.ts

@@ -46,6 +46,7 @@ import { IMPORT_ERROR_HINTS, ImportError } from '@forgeax/engine-types';
 import type { CompressionMode } from './ktx2-encode.js';
 import { encodeTextureToKtx2, resolveEncodeMode } from './ktx2-encode.js';
 import { parseImage } from './parse-image.js';
+import { importTextureSource } from './texture/importer.js';
 
 /** Map a source path / mime hint to the parseImage mime literal. */
 function mimeFromSource(source: string): 'image/png' | 'image/jpeg' | undefined {
@@ -319,13 +320,17 @@ async function importKtx2Source(ctx: ImportContext, bytes: Uint8Array): Promise<
       kind: 'texture',
       payload: {
         kind: 'texture',
-        width: inspection.width,
-        height: inspection.height,
+        shape: {
+          viewDimension: '2d',
+          extent: { width: inspection.width, height: inspection.height },
+        },
         format: colorSpaceToFormat(inspection.colorSpace),
         data: bytes,
         colorSpace: inspection.colorSpace,
-        mipmap: inspection.levelCount > 1,
-        mipLevelCount: inspection.levelCount,
+        mips:
+          inspection.levelCount > 1
+            ? { kind: 'packed', levelCount: inspection.levelCount }
+            : { kind: 'none' },
       },
       refs: [],
       artifacts: {
@@ -481,13 +486,17 @@ async function importBasisSource(ctx: ImportContext, bytes: Uint8Array): Promise
       kind: 'texture',
       payload: {
         kind: 'texture',
-        width: inspection.width,
-        height: inspection.height,
+        shape: {
+          viewDimension: '2d',
+          extent: { width: inspection.width, height: inspection.height },
+        },
         format: colorSpaceToFormat(colorSpace),
         data: bytes,
         colorSpace,
-        mipmap: inspection.levelCount > 1,
-        mipLevelCount: inspection.levelCount,
+        mips:
+          inspection.levelCount > 1
+            ? { kind: 'packed', levelCount: inspection.levelCount }
+            : { kind: 'none' },
       },
       refs: [],
       artifacts: {
@@ -574,6 +583,9 @@ async function maybeEncodeTextureBytes(
 }
 
 async function importImage(ctx: ImportContext): Promise<ImportResult> {
+  if (ctx.source.toLowerCase().endsWith('.texture.json')) {
+    return importTextureSource(ctx);
+  }
   const requiredKind = requiredImageOutputKind(ctx.source);
   if (requiredKind !== undefined) {
     const topologyError = validateImageOutputTopology(ctx, requiredKind);
@@ -730,12 +742,11 @@ async function importImage(ctx: ImportContext): Promise<ImportResult> {
     if (sub.kind !== 'texture') continue;
     const payload: TextureAsset = {
       kind: 'texture',
-      width: dec.width,
-      height: dec.height,
+      shape: { viewDimension: '2d', extent: { width: dec.width, height: dec.height } },
       format: colorSpaceToFormat(colorSpace),
       data: encodedBytes ?? dec.bytes,
       colorSpace,
-      mipmap,
+      mips: mipmap ? { kind: 'generate' } : { kind: 'none' },
     };
     out.push({
       guid: sub.guid,
@@ -825,11 +836,10 @@ export const decodeImageForImport: ImportContext['decodeImage'] = async (
       texture: {
         kind: 'texture' as const,
         data: cookedBytes,
-        width: tex.width,
-        height: tex.height,
+        shape: { viewDimension: '2d', extent: { width: tex.width, height: tex.height } },
         format: colorSpaceToFormat(colorSpace),
         colorSpace,
-        mipmap,
+        mips: mipmap ? { kind: 'generate' as const } : { kind: 'none' as const },
       },
       bytes: cookedBytes,
       mediaType,

package/src/index.ts

@@ -23,6 +23,14 @@ export { decodeHdr } from './hdr-decoder.js';
 export { decodeImageInBrowser } from './image-decoder-browser.js';
 export type { JpegModule, UpngModule } from './image-decoder-node.js';
 export { loadJpeg, loadUpng } from './image-decoder-node.js';
+export {
+  createPixelSurface,
+  type PixelColor,
+  type PixelSurface,
+  type PixelSurfaceNoiseOptions,
+  type PixelSurfaceOptions,
+  type PixelSurfaceRect,
+} from './pixel-surface.js';
 export type {
   EmittedSubAsset,
   ExistingExternalAssetPackage,