reze-engine 0.19.0 → 0.21.0

package/src/graph/compile.ts

@@ -4,7 +4,7 @@
 // See docs/graph-compiler-spec.md.
 
 import { MAX_NODES, MAX_PARAMS } from "./schema"
-import type { Diagnostic, ExposedParam, GraphNode, SocketValue, StyleGraph } from "./schema"
+import type { Diagnostic, ExposedParam, GraphNode, SocketValue, ShaderGraph } from "./schema"
 import { NODE_REGISTRY, canConvert, convert, fmtValue, literalFits } from "./registry"
 import type { NodeSpec, SockT } from "./registry"
 import { assembleModule } from "./slots"
@@ -83,7 +83,7 @@ export function assignStyleSlots(params: ExposedParam[]): StyleSlot[] {
 
 // ─── Validation ─────────────────────────────────────────────────────
 
-export function validateGraph(graph: StyleGraph, opts: CompileOptions = {}): Diagnostic[] {
+export function validateGraph(graph: ShaderGraph, opts: CompileOptions = {}): Diagnostic[] {
   const d: Diagnostic[] = []
   const nodes = new Map<string, GraphNode>()
 
@@ -188,7 +188,7 @@ export function validateGraph(graph: StyleGraph, opts: CompileOptions = {}): Dia
 
 // ─── Compile ────────────────────────────────────────────────────────
 
-export function compileGraph(graph: StyleGraph, opts: CompileOptions = {}): CompileResult {
+export function compileGraph(graph: ShaderGraph, opts: CompileOptions = {}): CompileResult {
   const fail = (diagnostics: Diagnostic[]): CompileResult => ({
     ok: false,
     wgsl: "",

package/src/graph/presets/body.ts

@@ -1,11 +1,11 @@
-// M_Body as a StyleGraph — port of shaders/materials/body.ts (仿深空之眼 "M_Body").
+// M_Body as a ShaderGraph — port of shaders/materials/body.ts (仿深空之眼 "M_Body").
 // Toon + warm rim + rim1/rim2 stack mixed 50/50 against a Principled BSDF with
 // noise-bumped normal. The hand port's local ramp_ease is ramp_cardinal (identical
 // smoothstep form); the Mapping node's zero loc/rot folds to a scale multiply.
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const BODY_GRAPH: StyleGraph = {
+export const BODY_GRAPH: ShaderGraph = {
   version: 1,
   name: "Body",
   tags: ["body"],

package/src/graph/presets/cloth_rough.ts

@@ -1,11 +1,11 @@
-// M_Rough_Cloth as a StyleGraph — port of shaders/materials/cloth_rough.ts.
+// M_Rough_Cloth as a ShaderGraph — port of shaders/materials/cloth_rough.ts.
 // NPR graph identical to M_Smooth_Cloth, but the noise bump subtree IS live on
 // Principled.Normal (weave bump in rest space) and Roughness is raised to 0.8187.
 // The tex_noise node hits the detail=2 peephole → tex_noise_d2.
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const CLOTH_ROUGH_GRAPH: StyleGraph = {
+export const CLOTH_ROUGH_GRAPH: ShaderGraph = {
   version: 1,
   name: "Rough Cloth",
   tags: ["cloth_rough"],

package/src/graph/presets/cloth_smooth.ts

@@ -1,11 +1,11 @@
-// M_Smooth_Cloth as a StyleGraph — port of shaders/materials/cloth_smooth.ts.
+// M_Smooth_Cloth as a ShaderGraph — port of shaders/materials/cloth_smooth.ts.
 // NPR toon + bevel + overlay-boosted emission (18.2×) mixed 10/90 against a plain
 // Principled BSDF. The Blender graph's dead bump subtree is omitted (as in the hand
 // port). hue_sat nodes with hue=0.5 compile to the hue_sat_id specialization.
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const CLOTH_SMOOTH_GRAPH: StyleGraph = {
+export const CLOTH_SMOOTH_GRAPH: ShaderGraph = {
   version: 1,
   name: "Smooth Cloth",
   tags: ["cloth_smooth"],

package/src/graph/presets/default.ts

@@ -1,23 +1,30 @@
-// Default material as a StyleGraph — Blender's new-material template verbatim:
-// Image Texture → Principled BSDF (Metallic 0, Specular 0.5, Roughness 0.5) → Output.
-// This is both the port of shaders/materials/default.ts (must match it pixel-for-pixel;
-// see tests/graph.test.mjs) and the blank-canvas starter graph an editor offers when
-// the user creates a new style.
+// Default material — the neutral base used two ways: the ungrouped fallback (a material
+// in no style group renders this) and the blank-canvas starter the editor's "New graph"
+// begins from, so the two always agree. MMD-correct PBSDF base: diffuse texture × the
+// PMX material diffuse color → Principled BSDF (Metallic 0, Specular 0.5, Roughness 0.5).
+// The material-color multiply is what keeps untextured/solid-color materials from
+// rendering white (they carry their color in material.diffuse, not a texture).
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const DEFAULT_GRAPH: StyleGraph = {
+export const DEFAULT_GRAPH: ShaderGraph = {
   version: 1,
   name: "Principled BSDF",
   tags: ["default"],
   nodes: [
     { id: "tex", type: "texture" },
+    { id: "mat", type: "material_diffuse" },
+    { id: "base", type: "mix/multiply", inputs: { fac: 1.0 } }, // texture × material diffuse
     {
       id: "principled",
       type: "principled",
       inputs: { metallic: 0.0, specular: 0.5, roughness: 0.5, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
     },
   ],
-  links: [{ from: { node: "tex", socket: "color" }, to: { node: "principled", socket: "base" } }],
+  links: [
+    { from: { node: "tex", socket: "color" }, to: { node: "base", socket: "a" } },
+    { from: { node: "mat", socket: "color" }, to: { node: "base", socket: "b" } },
+    { from: { node: "base", socket: "color" }, to: { node: "principled", socket: "base" } },
+  ],
   output: { node: "principled", socket: "color" },
 }

package/src/graph/presets/eye.ts

@@ -1,4 +1,4 @@
-// Eye as a StyleGraph — port of shaders/materials/eye.ts. The published preset
+// Eye as a ShaderGraph — port of shaders/materials/eye.ts. The published preset
 // author's instruction: "keep eyes in the default nodegraph, add emission 1.5".
 // So it's the default Principled BSDF plus an Emission of the diffuse texture at
 // 1.5× (Blender's Principled Emission socket, decomposed as a separate Emission +
@@ -7,9 +7,9 @@
 // The rear-view gate and the see-through stencil stamp are slot-owned (built-in eye
 // behavior, see EYE_TEMPLATE in slots.ts + createSlotPipeline) — not in this graph.
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const EYE_GRAPH: StyleGraph = {
+export const EYE_GRAPH: ShaderGraph = {
   version: 1,
   name: "Eye",
   tags: ["eye"],

package/src/graph/presets/face.ts

@@ -1,4 +1,4 @@
-// M_Face as a StyleGraph — port of shaders/materials/face.ts (仿深空之眼 "M_Face").
+// M_Face as a ShaderGraph — port of shaders/materials/face.ts (仿深空之眼 "M_Face").
 // Toon + warm rim + dual fresnel rim + BT.601 bright-tex gate, mixed 50/50 against a
 // Principled BSDF with noise bump. Structurally close to body, but: the toon uses the
 // edge-AA ramp, hue tints are 0.46 (full hue_sat, not the 0.5 _id specialization),
@@ -6,9 +6,9 @@
 // near-white texture gate that emits (freckle/highlight paint). Plain material — no
 // built-in slot effect, so it uses the default prelude/epilogue.
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const FACE_GRAPH: StyleGraph = {
+export const FACE_GRAPH: ShaderGraph = {
   version: 1,
   name: "Face",
   tags: ["face"],

package/src/graph/presets/hair.ts

@@ -1,4 +1,4 @@
-// M_Hair — 仿深空之眼渲染预设v1.0_by_小绿毛猫, as a StyleGraph. Node ids mirror the
+// M_Hair — 仿深空之眼渲染预设v1.0_by_小绿毛猫, as a ShaderGraph. Node ids mirror the
 // Blender node names referenced in shaders/materials/hair.ts comments; compiled with
 // { inlineParams: true } this graph must reproduce HAIR_SHADER_WGSL's fragment body
 // (golden test #1 — see tests/graph.test.mjs).
@@ -10,9 +10,9 @@
 // The object is pure JSON (no functions/undefined) — JSON.stringify round-trips it,
 // which is how reze.design will ship additional presets.
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const HAIR_GRAPH: StyleGraph = {
+export const HAIR_GRAPH: ShaderGraph = {
   version: 1,
   name: "Hair",
   tags: ["hair"],

package/src/graph/presets/metal.ts

@@ -1,12 +1,12 @@
-// M_Metal as a StyleGraph — port of shaders/materials/metal.ts.
+// M_Metal as a ShaderGraph — port of shaders/materials/metal.ts.
 // Metallic Principled (Metallic=1, Specular=1, Roughness=0.3) with a
 // reflection-coord voronoi driving base color (metallic sparkle), plus an NPR
 // toon/overlay emission stack mixed at Fac=0.6967. The voronoi Color→ramp Fac
 // link goes through Blender's implicit BT.601 conversion (color_to_value).
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const METAL_GRAPH: StyleGraph = {
+export const METAL_GRAPH: ShaderGraph = {
   version: 1,
   name: "Metal",
   tags: ["metal"],

package/src/graph/presets/stockings.ts

@@ -1,4 +1,4 @@
-// M_Stockings as a StyleGraph — port of shaders/materials/stockings.ts.
+// M_Stockings as a ShaderGraph — port of shaders/materials/stockings.ts.
 // A bbox-gradient × facing-rim mask drives a Mix Shader between an HSV-boosted
 // emission (val 5×) and a sheen Principled. The hashed-alpha discard and the
 // alpha=1 output are slot-owned (see STOCKINGS_TEMPLATE in slots.ts) — the graph
@@ -6,9 +6,9 @@
 // as in the hand port. The grayscale mask feeds Mix Shader Fac through Blender's
 // implicit BT.601 color→float conversion (equal-component vector → same scalar).
 
-import type { StyleGraph } from "../schema"
+import type { ShaderGraph } from "../schema"
 
-export const STOCKINGS_GRAPH: StyleGraph = {
+export const STOCKINGS_GRAPH: ShaderGraph = {
   version: 1,
   name: "Stockings",
   tags: ["stockings"],

package/src/graph/registry.ts

@@ -137,6 +137,14 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
       reflection: "reflect(-v, n)",
     },
   },
+  // PMX material's diffuse color (the authored base tint). Multiply the diffuse texture
+  // by this for the MMD-correct base — untextured materials carry their color here, so a
+  // texture-only base would render them white.
+  material_diffuse: {
+    inputs: {},
+    outputs: { color: "color" },
+    contextOutputs: { color: "material.diffuseColor" },
+  },
 
   // ── Literals as nodes (for editor ergonomics; inlined literals work too) ──
   value: { inputs: { value: F(0) }, outputs: { value: "float" }, emit: (a) => a.value },

package/src/graph/render-class.ts

@@ -1,5 +1,5 @@
 // Render-class + alpha-mode: the small, closed, engine-owned vocabularies that carry
-// pass integration for a style group. A group's node graph is pure shading; these select
+// pass integration for a style group. A group's shader graph is pure shading; these select
 // how the engine wires that shading into the passes. Not user-extensible — this is where
 // rendering correctness lives (stencil, cull, draw order, alpha test). See
 // docs/style-groups-spec.md §5.

package/src/graph/schema.ts

@@ -1,4 +1,4 @@
-// Material style graph — JSON-serializable node graph compiled to WGSL by compile.ts.
+// ShaderGraph — a JSON-serializable graph of shading nodes, compiled to WGSL by compile.ts.
 // Engine-space (LH, Y-up): porting a Blender graph converts coordinates at authoring
 // time (Blender Normal Z → engine Y), the compiler never sees Blender conventions.
 // See docs/graph-compiler-spec.md.
@@ -34,7 +34,7 @@ export type ExposedParam = {
   default: SocketValue
 }
 
-export type StyleGraph = {
+export type ShaderGraph = {
   version: 1
   name: string
   nodes: GraphNode[]

package/src/graph/style-group.ts

@@ -1,10 +1,10 @@
 // Style groups — the user-facing unit of material styling. A group binds a set of
-// materials to a node graph (pure shading) plus the engine-owned pass-integration axes
+// materials to a shader graph (pure shading) plus the engine-owned pass-integration axes
 // (renderClass + alphaMode). Each material belongs to at most one group; grouped
 // materials render via the group's compiled-graph pipeline, ungrouped ones fall back to
 // the hand-written preset path. See docs/style-groups-spec.md.
 
-import type { Diagnostic, StyleGraph } from "./schema"
+import type { Diagnostic, ShaderGraph } from "./schema"
 import type { AlphaMode, RenderClass } from "./render-class"
 import type { StyleSlot } from "./compile"
 
@@ -16,8 +16,8 @@ export type StyleGroup = {
   label?: string
   /** Material names in this group; each material is in AT MOST one group. */
   materials: string[]
-  /** Pure shading (StyleGraph has no `slot` — integration lives here on the group). */
-  graph: StyleGraph
+  /** Pure shading (ShaderGraph has no `slot` — integration lives here on the group). */
+  graph: ShaderGraph
   /** Pass-integration class: stencil/cull/draw-order. Default "auto". */
   renderClass?: RenderClass
   /** Alpha-handling axis, orthogonal to renderClass. Default "opaque". */

package/src/index.ts

@@ -1,63 +1,63 @@
-export {
-  Engine,
-  DEFAULT_BLOOM_OPTIONS,
-  DEFAULT_VIEW_TRANSFORM,
-  type EngineStats,
-  type EngineOptions,
-  type BloomOptions,
-  type ViewTransformOptions,
-  type LoadModelFromFilesOptions,
-  type MaterialPreset,
-  type ResolvedMaterialPreset,
-  type MaterialPresetMap,
-  type GizmoDragEvent,
-  type GizmoDragCallback,
-  type GizmoDragKind,
-} from "./engine"
-export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload"
-export {
-  compileGraph,
-  validateGraph,
-  assignStyleSlots,
-  type CompileOptions,
-  type CompileResult,
-  type StyleSlot,
-} from "./graph/compile"
-export type {
-  StyleGraph,
-  GraphNode,
-  GraphLink,
-  ExposedParam,
-  SocketValue,
-  Diagnostic,
-} from "./graph/schema"
-export { NODE_REGISTRY, type NodeSpec, type SockT } from "./graph/registry"
-export { RENDER_CLASSES, type RenderClass, type AlphaMode, type RenderClassInfo } from "./graph/render-class"
-export type {
-  StyleGroup,
-  GroupDiagnostic,
-  ApplyStyleGroupsResult,
-  ApplyStyleGroupResult,
-} from "./graph/style-group"
-export { HAIR_GRAPH } from "./graph/presets/hair"
-export { DEFAULT_GRAPH } from "./graph/presets/default"
-export { CLOTH_SMOOTH_GRAPH } from "./graph/presets/cloth_smooth"
-export { CLOTH_ROUGH_GRAPH } from "./graph/presets/cloth_rough"
-export { METAL_GRAPH } from "./graph/presets/metal"
-export { BODY_GRAPH } from "./graph/presets/body"
-export { STOCKINGS_GRAPH } from "./graph/presets/stockings"
-export { EYE_GRAPH } from "./graph/presets/eye"
-export { FACE_GRAPH } from "./graph/presets/face"
-export { Model } from "./model"
-export { Vec3, Quat, Mat4 } from "./math"
-export type {
-  AnimationClip,
-  AnimationPlayOptions,
-  AnimationProgress,
-  BoneKeyframe,
-  MorphKeyframe,
-  BoneInterpolation,
-  ControlPoint,
-} from "./animation"
-export { FPS } from "./animation"
+export {
+  Engine,
+  DEFAULT_BLOOM_OPTIONS,
+  DEFAULT_VIEW_TRANSFORM,
+  type EngineStats,
+  type EngineOptions,
+  type BloomOptions,
+  type ViewTransformOptions,
+  type LoadModelFromFilesOptions,
+  type MaterialPreset,
+  type ResolvedMaterialPreset,
+  type MaterialPresetMap,
+  type GizmoDragEvent,
+  type GizmoDragCallback,
+  type GizmoDragKind,
+} from "./engine"
+export { parsePmxFolderInput, pmxFileAtRelativePath, type PmxFolderInputResult } from "./folder-upload"
+export {
+  compileGraph,
+  validateGraph,
+  assignStyleSlots,
+  type CompileOptions,
+  type CompileResult,
+  type StyleSlot,
+} from "./graph/compile"
+export type {
+  ShaderGraph,
+  GraphNode,
+  GraphLink,
+  ExposedParam,
+  SocketValue,
+  Diagnostic,
+} from "./graph/schema"
+export { NODE_REGISTRY, type NodeSpec, type SockT } from "./graph/registry"
+export { RENDER_CLASSES, type RenderClass, type AlphaMode, type RenderClassInfo } from "./graph/render-class"
+export type {
+  StyleGroup,
+  GroupDiagnostic,
+  ApplyStyleGroupsResult,
+  ApplyStyleGroupResult,
+} from "./graph/style-group"
+export { HAIR_GRAPH } from "./graph/presets/hair"
+export { DEFAULT_GRAPH } from "./graph/presets/default"
+export { CLOTH_SMOOTH_GRAPH } from "./graph/presets/cloth_smooth"
+export { CLOTH_ROUGH_GRAPH } from "./graph/presets/cloth_rough"
+export { METAL_GRAPH } from "./graph/presets/metal"
+export { BODY_GRAPH } from "./graph/presets/body"
+export { STOCKINGS_GRAPH } from "./graph/presets/stockings"
+export { EYE_GRAPH } from "./graph/presets/eye"
+export { FACE_GRAPH } from "./graph/presets/face"
+export { Model } from "./model"
+export { Vec3, Quat, Mat4 } from "./math"
+export type {
+  AnimationClip,
+  AnimationPlayOptions,
+  AnimationProgress,
+  BoneKeyframe,
+  MorphKeyframe,
+  BoneInterpolation,
+  ControlPoint,
+} from "./animation"
+export { FPS } from "./animation"
 export { RezePhysics } from "./physics"

package/src/tga-loader.ts

@@ -0,0 +1,154 @@
+// Minimal TGA decoder. TGA is not a web-native format (createImageBitmap can't decode
+// it), yet it's common in PMX assets — especially sphere maps (.spa/.sph) and eye/detail
+// textures — so without this those materials render untextured. Produces top-left-origin
+// RGBA8, ready for queue.writeTexture into an rgba8unorm(-srgb) texture.
+//
+// Handles the variants that actually appear in the wild: true-color (16/24/32), grayscale
+// (8), and color-mapped (8-bit index), each raw or RLE-compressed, with the image
+// descriptor's origin bits honored. Throws on malformed/unsupported input — the caller
+// catches, logs, and falls back to the white texture (never panics the render loop).
+
+export type DecodedImage = { width: number; height: number; rgba: Uint8Array }
+
+// Image type byte (header offset 2).
+const enum TgaType {
+  ColorMapped = 1,
+  TrueColor = 2,
+  Grayscale = 3,
+  RleColorMapped = 9,
+  RleTrueColor = 10,
+  RleGrayscale = 11,
+}
+
+export function decodeTga(buffer: ArrayBuffer): DecodedImage {
+  const bytes = new Uint8Array(buffer)
+  const view = new DataView(buffer)
+  if (bytes.length < 18) throw new Error("TGA too small for header")
+
+  const idLength = view.getUint8(0)
+  const colorMapType = view.getUint8(1)
+  const imageType = view.getUint8(2) as TgaType
+  const cmapLength = view.getUint16(5, true)
+  const cmapEntryBits = view.getUint8(7)
+  const width = view.getUint16(12, true)
+  const height = view.getUint16(14, true)
+  const pixelDepth = view.getUint8(16)
+  const descriptor = view.getUint8(17)
+
+  if (width <= 0 || height <= 0) throw new Error(`TGA bad dimensions ${width}x${height}`)
+
+  const rle =
+    imageType === TgaType.RleColorMapped ||
+    imageType === TgaType.RleTrueColor ||
+    imageType === TgaType.RleGrayscale
+  const colorMapped = imageType === TgaType.ColorMapped || imageType === TgaType.RleColorMapped
+  const grayscale = imageType === TgaType.Grayscale || imageType === TgaType.RleGrayscale
+  const trueColor = imageType === TgaType.TrueColor || imageType === TgaType.RleTrueColor
+  if (!colorMapped && !grayscale && !trueColor) throw new Error(`TGA unsupported image type ${imageType}`)
+
+  let offset = 18 + idLength
+
+  // Color map (BGR/BGRA entries) → precomputed RGBA lookup.
+  let colorMap: Uint8Array | null = null
+  if (colorMapType === 1) {
+    const entryBytes = Math.ceil(cmapEntryBits / 8)
+    colorMap = new Uint8Array(cmapLength * 4)
+    for (let i = 0; i < cmapLength; i++) {
+      const [r, g, b, a] = unpackColor(bytes, offset + i * entryBytes, cmapEntryBits)
+      colorMap.set([r, g, b, a], i * 4)
+    }
+    offset += cmapLength * entryBytes
+  } else if (colorMapped) {
+    throw new Error("TGA color-mapped image without a color map")
+  }
+
+  // Bytes per stored element (index byte for color-mapped, else pixel bytes).
+  const elemBits = colorMapped ? pixelDepth : pixelDepth
+  const elemBytes = Math.ceil(elemBits / 8)
+  const pixelCount = width * height
+
+  // Decode the (possibly RLE) element stream into one element per pixel, file order.
+  const elements = new Uint8Array(pixelCount * elemBytes)
+  if (rle) {
+    let out = 0
+    let src = offset
+    while (out < elements.length) {
+      if (src >= bytes.length) throw new Error("TGA RLE stream truncated")
+      const packet = bytes[src++]
+      const count = (packet & 0x7f) + 1
+      if (packet & 0x80) {
+        // RLE packet: one element repeated `count` times.
+        if (src + elemBytes > bytes.length) throw new Error("TGA RLE packet truncated")
+        for (let i = 0; i < count && out < elements.length; i++) {
+          elements.set(bytes.subarray(src, src + elemBytes), out)
+          out += elemBytes
+        }
+        src += elemBytes
+      } else {
+        // Raw packet: `count` elements follow.
+        const span = count * elemBytes
+        if (src + span > bytes.length) throw new Error("TGA raw packet truncated")
+        elements.set(bytes.subarray(src, src + span), out)
+        out += span
+        src += span
+      }
+    }
+  } else {
+    const span = pixelCount * elemBytes
+    if (offset + span > bytes.length) throw new Error("TGA pixel data truncated")
+    elements.set(bytes.subarray(offset, offset + span), 0)
+  }
+
+  // Convert elements → RGBA in file order.
+  const linear = new Uint8Array(pixelCount * 4)
+  for (let p = 0; p < pixelCount; p++) {
+    let rgba: [number, number, number, number]
+    if (colorMapped) {
+      const index = elements[p] // 8-bit index (pixelDepth 8)
+      const c = index * 4
+      rgba = colorMap ? [colorMap[c], colorMap[c + 1], colorMap[c + 2], colorMap[c + 3]] : [0, 0, 0, 255]
+    } else if (grayscale) {
+      const g = elements[p * elemBytes]
+      rgba = [g, g, g, 255]
+    } else {
+      rgba = unpackColor(elements, p * elemBytes, pixelDepth)
+    }
+    linear.set(rgba, p * 4)
+  }
+
+  // Honor origin bits: bit5 set → top-to-bottom (no flip); clear → bottom-to-top.
+  // bit4 set → right-to-left. Output is always top-left origin for GPU upload.
+  const flipY = (descriptor & 0x20) === 0
+  const flipX = (descriptor & 0x10) !== 0
+  if (!flipX && !flipY) return { width, height, rgba: linear }
+
+  const rgba = new Uint8Array(pixelCount * 4)
+  for (let y = 0; y < height; y++) {
+    const sy = flipY ? height - 1 - y : y
+    for (let x = 0; x < width; x++) {
+      const sx = flipX ? width - 1 - x : x
+      const src = (sy * width + sx) * 4
+      const dst = (y * width + x) * 4
+      rgba[dst] = linear[src]
+      rgba[dst + 1] = linear[src + 1]
+      rgba[dst + 2] = linear[src + 2]
+      rgba[dst + 3] = linear[src + 3]
+    }
+  }
+  return { width, height, rgba }
+}
+
+// Unpack one true-color element (16/24/32-bit, stored BGR[A]) to RGBA8.
+function unpackColor(src: Uint8Array, o: number, bits: number): [number, number, number, number] {
+  if (bits === 32) return [src[o + 2], src[o + 1], src[o], src[o + 3]]
+  if (bits === 24) return [src[o + 2], src[o + 1], src[o], 255]
+  if (bits === 16 || bits === 15) {
+    // 1-5-5-5: bit15 = attribute, then 5 red, 5 green, 5 blue (little-endian).
+    const val = src[o] | (src[o + 1] << 8)
+    const r = ((val >> 10) & 0x1f) * 255
+    const g = ((val >> 5) & 0x1f) * 255
+    const b = (val & 0x1f) * 255
+    return [Math.round(r / 31), Math.round(g / 31), Math.round(b / 31), 255]
+  }
+  throw new Error(`TGA unsupported pixel depth ${bits}`)
+}