@forgeax/engine-image 0.1.2

package/src/reimport-reuse-meta.ts

@@ -0,0 +1,160 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { DecodedImage, ImageColorSpace } from '@forgeax/engine-types';
+
+import { deriveImageSourceKey } from './source-key.js';
+import type { SubAssetKey } from './sub-asset-key.js';
+import { subAssetKey, subAssetKeyEqual } from './sub-asset-key.js';
+
+/**
+ * Existing `*.meta.json` (importer: 'image') sub-asset record (free-form sub-shape; the
+ * meta.schema.json $defs/subAsset locks `guid` + `sourceIndex` + `kind` only).
+ * Image importer treats the open shape as a key-bearing tuple; the gltf-loader
+ * feat works on the same shape.
+ */
+export interface ExistingSubAsset {
+  readonly guid: string;
+  readonly sourceIndex: number;
+  readonly kind: string;
+  readonly name?: string;
+  readonly sourceKey?: string;
+}
+
+/**
+ * Existing `*.meta.json` (importer: 'image') package record. Mirrors the
+ * meta.schema.json $defs/ExternalAssetPackage shape (research F-9). Only
+ * the fields consumed by the reimport reuse algorithm are typed here;
+ * importSettings stays a free-form open shape.
+ */
+export interface ExistingExternalAssetPackage {
+  readonly schemaVersion: string;
+  readonly kind: 'external-asset-package';
+  readonly importer: 'image';
+  readonly source: string;
+  readonly importSettings: Readonly<Record<string, unknown>>;
+  readonly subAssets: readonly ExistingSubAsset[];
+}
+
+/**
+ * Sub-asset record emitted into the regenerated `*.meta.json` (importer: 'image')
+ * `subAssets[]` slot. Shape matches `ExistingSubAsset` so two consecutive
+ * reimports of byte-identical bytes produce byte-identical JSON
+ * (AC-16 byte-stable reimport guarantee).
+ */
+export interface EmittedSubAsset {
+  readonly guid: string;
+  readonly sourceIndex: number;
+  readonly kind: string;
+  readonly name?: string;
+  readonly sourceKey?: string;
+}
+
+/**
+ * Two-phase reimport reuse algorithm (plan-strategy section 2.2 D-4
+ * mirroring the in-flight gltf-loader algorithm).
+ *
+ * For each fresh sub-asset key the importer would emit, this function:
+ *  1. Searches the `existing.subAssets[]` for a `subAssetKeyEqual` hit.
+ *  2. On hit -- reuses the existing GUID byte-for-byte.
+ *  3. On miss -- mints a fresh UUIDv7 via `AssetGuid.random()`.
+ *
+ * Image disk schema currently emits a single `kind='texture'` sub-asset per
+ * source (cubemap face / array layer reserved for future feat); the
+ * algorithm scales to multi-sub-asset sources without modification (charter
+ * P5 consistent abstraction).
+ *
+ * Returns the regenerated `subAssets[]` array. The caller (toAssetPack /
+ * runAssetImport) splices it into the `*.meta.json` (importer: 'image') envelope.
+ */
+export function reimportReuseMeta(
+  decoded: DecodedImage,
+  existing: ExistingExternalAssetPackage | undefined,
+): readonly EmittedSubAsset[] {
+  // Image disk schema is single-sub-asset; the future multi-asset path
+  // iterates a producer-side list of sub-asset keys instead of a single one.
+  const freshKeys: readonly SubAssetKey[] = [subAssetKey({ kind: 'texture', sourceIndex: 0 })];
+
+  const out: EmittedSubAsset[] = [];
+  const sourceKey = deriveImageSourceKey('texture');
+
+  for (let i = 0; i < freshKeys.length; i++) {
+    const fresh = freshKeys[i];
+    if (fresh === undefined) continue;
+
+    let reuseGuid: string | undefined;
+    if (existing !== undefined) {
+      for (const candidate of existing.subAssets) {
+        if (sourceKey !== undefined && candidate.sourceKey === sourceKey) {
+          reuseGuid = candidate.guid;
+          break;
+        }
+        const candidateKey = subAssetKey({
+          kind: candidate.kind,
+          sourceIndex: candidate.sourceIndex,
+          ...(candidate.name !== undefined ? { name: candidate.name } : {}),
+        });
+        if (subAssetKeyEqual(fresh, candidateKey)) {
+          reuseGuid = candidate.guid;
+          break;
+        }
+      }
+    }
+
+    const guid = reuseGuid ?? AssetGuid.format(AssetGuid.random());
+    const emit: EmittedSubAsset =
+      fresh.name !== undefined
+        ? {
+            guid,
+            sourceIndex: i,
+            kind: fresh.kind,
+            name: fresh.name,
+            ...(sourceKey === undefined ? {} : { sourceKey }),
+          }
+        : {
+            guid,
+            sourceIndex: i,
+            kind: fresh.kind,
+            ...(sourceKey === undefined ? {} : { sourceKey }),
+          };
+    out.push(emit);
+  }
+
+  // Ensure decoded ref is consumed (decoded.bytes is the producer signal that
+  // a sub-asset exists; without bytes there is nothing to emit). The
+  // signature keeps `decoded` in the public surface so the future cubemap /
+  // array-layer feat can derive its multi-sub-asset list from `decoded`
+  // metadata without a breaking change (charter P5 consistent abstraction).
+  void decoded;
+
+  return out;
+}
+
+/**
+ * HDR colorSpace validator for *.image.meta.json sidecar importSettings
+ * (plan-strategy D-8 -- HDR files must use colorSpace=linear).
+ *
+ * Extension is matched case-insensitively against the HDR set
+ * (`.hdr`, `.exr`). When the extension belongs to the HDR set:
+ * - `colorSpace='linear'` -> ok, returns `'linear'`
+ * - any other colorSpace -> structured rejection with expected/actual
+ *
+ * Non-HDR extensions pass through the colorSpace unchanged. Downstream
+ * callers (decodeImageFromFile, parseImage) invoke this at the
+ * sidecar-read entry to fail-fast when an .hdr meta carries srgb.
+ */
+export function validateColorSpaceForHdr(
+  ext: string,
+  colorSpace: ImageColorSpace,
+): { ok: true; value: ImageColorSpace } | { ok: false; expected: string; actual: string } {
+  const lower = ext.toLowerCase();
+  if (lower === '.hdr' || lower === '.exr') {
+    if (colorSpace !== 'linear') {
+      return {
+        ok: false,
+        expected: 'colorSpace=linear for HDR source files',
+        actual: `colorSpace=${colorSpace}`,
+      };
+    }
+    return { ok: true, value: 'linear' };
+  }
+  return { ok: true, value: colorSpace };
+}

package/src/resize-image.ts

@@ -0,0 +1,39 @@
+/** Deterministically downscale tight-packed RGBA pixels with bilinear sampling. */
+export function downscaleRgba(
+  bytes: Uint8Array,
+  width: number,
+  height: number,
+  maxDimension: number,
+): { readonly bytes: Uint8Array; readonly width: number; readonly height: number } {
+  if (width <= maxDimension && height <= maxDimension) {
+    return { bytes, width, height };
+  }
+
+  const scale = maxDimension / Math.max(width, height);
+  const targetWidth = Math.max(1, Math.round(width * scale));
+  const targetHeight = Math.max(1, Math.round(height * scale));
+  const output = new Uint8Array(targetWidth * targetHeight * 4);
+  const source = (x: number, y: number, channel: number): number =>
+    bytes[(y * width + x) * 4 + channel] ?? 0;
+
+  for (let y = 0; y < targetHeight; y += 1) {
+    const sourceY = ((y + 0.5) * height) / targetHeight - 0.5;
+    const y0 = Math.max(0, Math.floor(sourceY));
+    const y1 = Math.min(height - 1, y0 + 1);
+    const yWeight = Math.max(0, Math.min(1, sourceY - y0));
+    for (let x = 0; x < targetWidth; x += 1) {
+      const sourceX = ((x + 0.5) * width) / targetWidth - 0.5;
+      const x0 = Math.max(0, Math.floor(sourceX));
+      const x1 = Math.min(width - 1, x0 + 1);
+      const xWeight = Math.max(0, Math.min(1, sourceX - x0));
+      const outputOffset = (y * targetWidth + x) * 4;
+      for (let channel = 0; channel < 4; channel += 1) {
+        const top = source(x0, y0, channel) * (1 - xWeight) + source(x1, y0, channel) * xWeight;
+        const bottom = source(x0, y1, channel) * (1 - xWeight) + source(x1, y1, channel) * xWeight;
+        output[outputOffset + channel] = Math.round(top * (1 - yWeight) + bottom * yWeight);
+      }
+    }
+  }
+
+  return { bytes: output, width: targetWidth, height: targetHeight };
+}

package/src/result.ts

@@ -0,0 +1,13 @@
+// Result<T, E> + ok / err live in `@forgeax/engine-types` (tweak-20260612-result-
+// into-types). They were duplicated here as a lite (plain-object, no `unwrap`)
+// variant; consolidated upstream into the same shape used by rhi / ecs / naga.
+// The barrel here re-exports them so existing
+// `import { err, ok, Result, ResultOk, ResultErr } from '@forgeax/engine-image'`
+// consumers (and intra-package `./result.js` imports) stay unchanged.
+export {
+  err,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from '@forgeax/engine-types';

package/src/runtime/__tests__/asset-decoders.unit.test.ts

@@ -0,0 +1,66 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('@forgeax/engine-codec', () => ({
+  parseKtx2: vi.fn(async () => ({ ok: true, value: {} })),
+  transcodeBasis: vi.fn(),
+  transcodeKtx2: vi.fn(async (_parsed: unknown, target: string) => ({
+    ok: true,
+    value: {
+      format: target,
+      width: 2,
+      height: 2,
+      mips: [{ level: 0, width: 2, height: 2, data: new Uint8Array(16) }],
+    },
+  })),
+}));
+
+import { textureContribution } from '../asset-decoders.js';
+
+describe('runtime image asset decoder', () => {
+  it('transcodes Basis KTX2 artifacts to the uncompressed TextureAsset baseline', async () => {
+    const result = await textureContribution.decoder.decode({
+      envelope: {
+        guid: '019e3969-1d47-760f-982e-7bad1ffd969c',
+        kind: 'texture',
+        payload: {
+          kind: 'texture',
+          width: 4,
+          height: 4,
+          format: 'rgba8unorm-srgb',
+          colorSpace: 'srgb',
+          mipmap: true,
+          data: new Uint8Array(64),
+        },
+        refs: [],
+        artifacts: {
+          body: {
+            path: 'body.bin',
+            mediaType: 'image/ktx2',
+            assetCodec: { name: 'basis', container: 'ktx2', profile: 'etc1s' },
+            contentEncoding: 'identity',
+            byteLength: 4,
+            integrity: { algorithm: 'sha256', digest: `sha256:${'0'.repeat(64)}` },
+          },
+        },
+      },
+      artifacts: {
+        read: async () => ok(new Uint8Array([1, 2, 3, 4])),
+      },
+      signal: new AbortController().signal,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      value: expect.objectContaining({
+        kind: 'texture',
+        width: 2,
+        height: 2,
+        format: 'rgba8unorm-srgb',
+        colorSpace: 'srgb',
+        mipmap: true,
+        data: expect.any(Uint8Array),
+      }),
+    });
+  });
+});

package/src/runtime/asset-decoders.ts

@@ -0,0 +1,152 @@
+import { parseKtx2, transcodeBasis, transcodeKtx2 } from '@forgeax/engine-codec';
+import {
+  type AssetDecoderContribution,
+  type AssetDecoderInput,
+  type AssetDecoderResult,
+  type AssetKind,
+  type AssetLoadError,
+  type EquirectAsset,
+  err,
+  ok,
+  type TextureAsset,
+} from '@forgeax/engine-types';
+
+function invalid(guid: string, expected: string, reason: string) {
+  return err<AssetLoadError>({
+    code: 'asset-package-invalid',
+    expected,
+    hint: 'recook the image asset and publish its complete device-neutral payload',
+    detail: { guid, reason },
+  });
+}
+
+function validDimensions(width: number, height: number): boolean {
+  return Number.isSafeInteger(width) && width > 0 && Number.isSafeInteger(height) && height > 0;
+}
+
+function imageBytes(value: unknown): Uint8Array | Uint8ClampedArray | undefined {
+  if (value instanceof Uint8Array || value instanceof Uint8ClampedArray) return value;
+  if (!Array.isArray(value)) return undefined;
+  if (!value.every((item) => Number.isInteger(item) && item >= 0 && item <= 255)) {
+    return undefined;
+  }
+  return Uint8Array.from(value);
+}
+
+function compressedImageTarget(colorSpace: TextureAsset['colorSpace']): TextureAsset['format'] {
+  return colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
+}
+
+function validImageSurface(
+  value: unknown,
+): value is Pick<TextureAsset, 'width' | 'height' | 'format' | 'data' | 'colorSpace'> {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<TextureAsset>;
+  return (
+    validDimensions(candidate.width ?? 0, candidate.height ?? 0) &&
+    typeof candidate.format === 'string' &&
+    imageBytes(candidate.data) !== undefined &&
+    (candidate.colorSpace === 'srgb' || candidate.colorSpace === 'linear')
+  );
+}
+
+async function readImageSurface<P extends TextureAsset | EquirectAsset>(
+  input: AssetDecoderInput<P>,
+  kind: P['kind'],
+  expected: string,
+): Promise<AssetDecoderResult<P>> {
+  const { envelope, artifacts } = input;
+  const payload = envelope.payload as unknown;
+  if (
+    payload === null ||
+    typeof payload !== 'object' ||
+    (payload as { kind?: unknown }).kind !== kind
+  ) {
+    return invalid(envelope.guid, expected, `${kind} owner validation failed`);
+  }
+
+  const body = envelope.artifacts.body ?? envelope.artifacts.atlas;
+  let data = imageBytes((payload as { data?: unknown }).data);
+  if (body !== undefined) {
+    const read = await artifacts.read(body);
+    if (!read.ok) return err(read.error);
+    const bytes = read.value;
+    data = bytes;
+
+    // Pack v2 keeps the authored TextureAsset format device-neutral while the
+    // artifact may carry a Basis KTX2/raw-Basis delivery codec. The new
+    // AssetDecoder seam has no device-capability input, so its safe baseline is
+    // an uncompressed RGBA target; the renderer can upload that POD on every
+    // backend without interpreting container bytes as pixels.
+    if (body.assetCodec?.name === 'basis' && body.assetCodec.container !== undefined) {
+      const candidate = payload as Partial<TextureAsset>;
+      if (candidate.colorSpace !== 'srgb' && candidate.colorSpace !== 'linear') {
+        return invalid(envelope.guid, expected, `${kind} color space is invalid`);
+      }
+      const target = compressedImageTarget(candidate.colorSpace);
+      const transcoded =
+        body.assetCodec.container === 'ktx2'
+          ? await parseKtx2(bytes).then((parsed) =>
+              parsed.ok ? transcodeKtx2(parsed.value, target) : parsed,
+            )
+          : await transcodeBasis(bytes, target);
+      if (!transcoded.ok) {
+        return invalid(envelope.guid, expected, `codec:${transcoded.error.code}`);
+      }
+      const mip = transcoded.value.mips[0];
+      if (mip === undefined) return invalid(envelope.guid, expected, 'codec:base-mip-missing');
+      data = mip.data;
+      return readDecodedSurface(envelope.guid, expected, {
+        ...payload,
+        width: mip.width,
+        height: mip.height,
+        format: target,
+        data,
+      });
+    }
+  }
+
+  return readDecodedSurface(envelope.guid, expected, {
+    ...payload,
+    ...(data === undefined ? {} : { data }),
+  });
+}
+
+function readDecodedSurface<P extends TextureAsset | EquirectAsset>(
+  guid: string,
+  expected: string,
+  candidate: unknown,
+): ReturnType<typeof ok<P>> | ReturnType<typeof err<AssetLoadError>> {
+  if (!validImageSurface(candidate)) {
+    return invalid(guid, expected, 'image owner validation failed');
+  }
+  return ok(candidate as P);
+}
+
+export const textureContribution: AssetDecoderContribution<TextureAsset, 'texture'> = {
+  kind: { kind: 'texture' } as AssetKind<TextureAsset, 'texture'>,
+  consumer: 'Image/Render DeviceScope',
+  decoder: {
+    async decode(input) {
+      return readImageSurface(
+        input,
+        'texture',
+        'a texture payload with dimensions, format, color space, and bytes',
+      );
+    },
+  },
+};
+
+export const equirectContribution: AssetDecoderContribution<EquirectAsset, 'equirect'> = {
+  kind: { kind: 'equirect' } as AssetKind<EquirectAsset, 'equirect'>,
+  consumer: 'Image/Render DeviceScope',
+  decoder: {
+    async decode(input) {
+      return readImageSurface(
+        input,
+        'equirect',
+        'an equirect payload with dimensions, format, color space, and bytes',
+      );
+    },
+  },
+};

package/src/runtime/decode-image-bytes.ts

@@ -0,0 +1,41 @@
+import type { ImageError, Result, TextureAsset } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import { decodeImageInBrowser } from '../image-decoder-browser';
+import { runtimeImageError } from './image-error';
+
+const SUPPORTED_MIMES = ['image/png', 'image/jpeg'] as const;
+type SupportedMime = (typeof SUPPORTED_MIMES)[number];
+
+function isSupportedMime(mime: string): mime is SupportedMime {
+  return SUPPORTED_MIMES.some((supportedMime) => supportedMime === mime);
+}
+
+function mipLevels(width: number, height: number): number {
+  return Math.floor(Math.log2(Math.max(width, height))) + 1;
+}
+
+/** Image-owned runtime boundary from encoded bytes to a TextureAsset POD. */
+export async function decodeImageBytes(
+  bytes: Uint8Array | ArrayBuffer,
+  mime: string,
+  opts: { readonly colorSpace?: 'srgb' | 'linear'; readonly mipmap?: boolean } = {},
+): Promise<Result<TextureAsset, ImageError>> {
+  if (!isSupportedMime(mime)) {
+    return err(runtimeImageError({ code: 'image-format-unsupported', actualMime: mime }));
+  }
+  const colorSpace = opts.colorSpace ?? 'srgb';
+  const mipmap = opts.mipmap ?? true;
+  const input = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const decoded = await decodeImageInBrowser(input, mime as SupportedMime, { colorSpace, mipmap });
+  if (!decoded.ok) return err(decoded.error);
+  return ok({
+    kind: 'texture',
+    width: decoded.value.width,
+    height: decoded.value.height,
+    format: colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm',
+    data: decoded.value.bytes,
+    colorSpace,
+    mipmap,
+    mipLevelCount: mipmap ? mipLevels(decoded.value.width, decoded.value.height) : 1,
+  });
+}

package/src/runtime/image-error.ts

@@ -0,0 +1,8 @@
+import type { ImageErrorCode, ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';
+import { imageError } from '../errors';
+
+export function runtimeImageError<C extends ImageErrorCode>(
+  detail: ImageErrorDetailFor<C>,
+): ImageErrorFor<C> {
+  return imageError(detail);
+}

package/src/source-key.ts

@@ -0,0 +1,41 @@
+/**
+ * Derive the semantic identity for an image producer output.
+ *
+ * The role is the producer-owned identity. Source path and sourceIndex are
+ * locators only and must not be folded into this key.
+ */
+export interface ImageSourceKeyLocator {
+  readonly sourcePath?: string;
+  readonly sourceIndex?: number;
+}
+
+export type ImageSourceKeyResult =
+  | { readonly ok: true; readonly keys: readonly string[] }
+  | {
+      readonly ok: false;
+      readonly code: 'missing-source-key' | 'duplicate-source-key';
+      readonly roles: readonly string[];
+    };
+
+export function deriveImageSourceKey(
+  role: string,
+  _locator?: ImageSourceKeyLocator,
+): string | undefined {
+  const normalizedRole = role.trim();
+  if (normalizedRole.length === 0) return undefined;
+  return `image:${normalizedRole}`;
+}
+
+export function deriveImageSourceKeys(roles: readonly string[]): ImageSourceKeyResult {
+  const keys = roles.map((role) => deriveImageSourceKey(role));
+  const missing = roles.filter((_role, index) => keys[index] === undefined);
+  if (missing.length > 0) return { ok: false, code: 'missing-source-key', roles: missing };
+
+  const seen = new Set<string>();
+  for (const key of keys) {
+    if (key === undefined) continue;
+    if (seen.has(key)) return { ok: false, code: 'duplicate-source-key', roles };
+    seen.add(key);
+  }
+  return { ok: true, keys: keys as string[] };
+}

package/src/sub-asset-key.ts

@@ -0,0 +1,67 @@
+/**
+ * Sub-asset-key shape mirroring the in-flight gltf-loader feat (plan-strategy
+ * section 2.2 D-4 same-shape). Each sub-asset emitted into a `*.meta.json`
+ * sidecar (uniformly `<source>.meta.json` across image / gltf arms,
+ * dispatched on top-level `importer` field per feat-20260521) carries a
+ * `{kind, name?, indexFallback}` triple so the importer can deterministically
+ * match an existing sub-asset across reimports (charter P5 producer/consumer
+ * split + AC-14 cross-feat alignment).
+ *
+ * The image disk schema is currently single-sub-asset; this file collapses
+ * to `kind='texture'` + `indexFallback='textures/0'` so the same matching
+ * algorithm is reusable when the future cubemap / array-layer feat lands
+ * (plan-strategy R5 free-form schema).
+ */
+
+export interface SubAssetKey {
+  /** Discriminator literal -- 'texture' for engine-image; 'mesh' / 'material' / 'scene' / 'image' for gltf-loader. */
+  readonly kind: string;
+  /** Optional human-readable name field; absent when the source has no symbolic identifier. */
+  readonly name?: string;
+  /** Path-style fallback identifier (e.g. 'images/0' / 'meshes/0'); always non-empty. */
+  readonly indexFallback: string;
+}
+
+export interface SubAssetKeyInput {
+  readonly kind: string;
+  readonly sourceIndex: number;
+  readonly name?: string;
+}
+
+/**
+ * Construct a sub-asset key from importer input. The `indexFallback` is
+ * synthesised from the kind literal + sourceIndex so two importers
+ * (image / gltf-loader) emit identical fallback strings for the same
+ * `(kind, sourceIndex)` pair (AC-14).
+ */
+export function subAssetKey(input: SubAssetKeyInput): SubAssetKey {
+  const indexFallback = `${input.kind}s/${input.sourceIndex}`;
+  if (input.name !== undefined) {
+    return { kind: input.kind, name: input.name, indexFallback };
+  }
+  return { kind: input.kind, indexFallback };
+}
+
+/**
+ * Two-phase equality predicate used by reimportReuseMeta for GUID
+ * preservation across reimports:
+ *
+ * Phase 1 -- (kind + name + idx) full match: identical in all three fields
+ * Phase 2 -- (kind + idx) match: same kind + indexFallback, name absent or
+ *            equal (collapses when both sides omit name)
+ * Phase 3 -- otherwise: false (importer mints fresh UUIDv7)
+ *
+ * The two phases are folded into a single boolean predicate here; the
+ * reimportReuseMeta caller iterates the existing subAssets list and picks
+ * the first hit (deterministic order; matches AC-16 byte-identical
+ * reimport).
+ */
+export function subAssetKeyEqual(a: SubAssetKey, b: SubAssetKey): boolean {
+  if (a.kind !== b.kind) return false;
+  if (a.indexFallback !== b.indexFallback) return false;
+  // name comparison: undefined === undefined is fine; if one side has a name
+  // and the other does not, the keys are NOT equal (charter P4 explicit
+  // failure -- name carries a meaningful identifier when present)
+  if (a.name !== b.name) return false;
+  return true;
+}

package/src/to-asset-pack.ts

@@ -0,0 +1,95 @@
+import type { AssetCompression, DecodedImage, ImageMeta } from '@forgeax/engine-types';
+
+/**
+ * External-asset-package envelope shape mirroring the
+ * `packages/pack/schema/meta.schema.json` $defs/ExternalAssetPackage.
+ * Consumed by `forgeax-engine-remote-asset import` (CLI entry, M3b) +
+ * the image importer in M2 build-time path. The internal-text-package
+ * variant ($defs/InternalTextPackage) is owned by the gltf-loader feat.
+ */
+export interface ExternalAssetPackage {
+  readonly schemaVersion: string;
+  readonly kind: 'external-asset-package';
+  readonly importer: 'image';
+  readonly source: string;
+  readonly importSettings: ImageImportSettings;
+  readonly subAssets: readonly ExternalSubAsset[];
+}
+
+/**
+ * Free-form image importer settings persisted into `*.meta.json` (importer: 'image')
+ * `importSettings`. Matches `ImageMeta` POD field-for-field (charter P5
+ * single SSOT) but the open Record shape allows future minor adds (cubemap
+ * face / array layer / custom colorSpace) without breaking existing meta
+ * files (plan-strategy R5).
+ */
+export interface ImageImportSettings extends Readonly<Record<string, unknown>> {
+  readonly colorSpace: ImageMeta['colorSpace'];
+  readonly mipmap: ImageMeta['mipmap'];
+  readonly addressMode: ImageMeta['addressMode'];
+  readonly filterMode: ImageMeta['filterMode'];
+  readonly downscaleMaxDimension?: number;
+  /**
+   * Explicit per-asset compression override (AC-01: importSettings carries
+   * compression intent). When omitted, the build-time compression strategy
+   * table decides by artifact kind (mesh -> zstd, texture -> none). When set,
+   * this value wins over the default table for this asset.
+   */
+  readonly compression?: AssetCompression;
+}
+
+export interface ExternalSubAsset {
+  readonly guid: string;
+  readonly sourceIndex: number;
+  readonly kind: string;
+  readonly name?: string;
+}
+
+/**
+ * Pure function that translates a DecodedImage POD + ImageMeta POD into
+ * an external-asset-package envelope ready to be JSON-stringified into a
+ * `*.meta.json` sidecar with importer: 'image' (plan-strategy section 3.2 sequence A; AC-13
+ * disk schema reuse).
+ *
+ * The single sub-asset emitted carries:
+ *  - `guid` -- copied verbatim from `meta.guid` (the producer guarantees
+ *    the GUID is freshly minted or reused via `reimportReuseMeta`)
+ *  - `sourceIndex: 0` (single-sub-asset shape; cubemap / array reserved
+ *    for future feat)
+ *  - `kind: 'texture'` (closed literal for image-importer emit)
+ *
+ * Two consecutive calls with identical inputs produce JSON.stringify
+ * byte-equal output (AC-16 idempotent reimport).
+ */
+export function toAssetPack(decoded: DecodedImage, meta: ImageMeta): ExternalAssetPackage {
+  // decoded.bytes are not embedded in the meta envelope -- the source bytes
+  // live next to the sidecar on disk (the runtime reads them via
+  // decodeImageFromFile at app load time). We keep the parameter so future
+  // cubemap / array-layer feats can derive multi-sub-asset emit from decoded
+  // dimensions without breaking the call surface (charter P5 consistent
+  // abstraction).
+  void decoded;
+
+  return {
+    schemaVersion: '1.0.0',
+    kind: 'external-asset-package',
+    importer: 'image',
+    source: '',
+    importSettings: {
+      colorSpace: meta.colorSpace,
+      mipmap: meta.mipmap,
+      addressMode: meta.addressMode,
+      filterMode: meta.filterMode,
+      ...(meta.downscaleMaxDimension !== undefined
+        ? { downscaleMaxDimension: meta.downscaleMaxDimension }
+        : {}),
+    },
+    subAssets: [
+      {
+        guid: meta.guid,
+        sourceIndex: 0,
+        kind: 'texture',
+      },
+    ],
+  };
+}