@downdraft/engine 0.0.0 → 0.1.1

package/core/src/assets/cache.ts

@@ -0,0 +1,186 @@
+export interface GPUCacheEntry {
+  resource: GPUTexture | GPUBuffer;
+  refCount: number;
+  lastUsed: number;
+  key: string;
+}
+
+export class GPUResourceCache {
+  private textures: Map<string, GPUCacheEntry> = new Map();
+  private buffers: Map<string, GPUCacheEntry> = new Map();
+  private device: GPUDevice | null = null;
+  private maxAge: number = 60000;
+  private cleanupInterval: number | null = null;
+
+  setDevice(device: GPUDevice): void {
+    this.device = device;
+  }
+
+  getTexture(key: string): GPUTexture | null {
+    const entry = this.textures.get(key);
+    if (entry) {
+      entry.refCount++;
+      entry.lastUsed = Date.now();
+      return entry.resource as GPUTexture;
+    }
+    return null;
+  }
+
+  cacheTexture(key: string, texture: GPUTexture): void {
+    this.textures.set(key, {
+      resource: texture,
+      refCount: 1,
+      lastUsed: Date.now(),
+      key,
+    });
+  }
+
+  releaseTexture(key: string): void {
+    const entry = this.textures.get(key);
+    if (entry) {
+      entry.refCount--;
+      if (entry.refCount <= 0) {
+        (entry.resource as GPUTexture).destroy();
+        this.textures.delete(key);
+      }
+    }
+  }
+
+  getBuffer(key: string): GPUBuffer | null {
+    const entry = this.buffers.get(key);
+    if (entry) {
+      entry.refCount++;
+      entry.lastUsed = Date.now();
+      return entry.resource as GPUBuffer;
+    }
+    return null;
+  }
+
+  cacheBuffer(key: string, buffer: GPUBuffer): void {
+    this.buffers.set(key, {
+      resource: buffer,
+      refCount: 1,
+      lastUsed: Date.now(),
+      key,
+    });
+  }
+
+  releaseBuffer(key: string): void {
+    const entry = this.buffers.get(key);
+    if (entry) {
+      entry.refCount--;
+      if (entry.refCount <= 0) {
+        (entry.resource as GPUBuffer).destroy();
+        this.buffers.delete(key);
+      }
+    }
+  }
+
+  private genericResources: Map<string, { resource: unknown; cleanup: (() => Promise<void> | void) | null; refCount: number; lastUsed: number }> = new Map();
+
+  register(key: string, resource: unknown, cleanup?: () => Promise<void> | void): void {
+    this.genericResources.set(key, {
+      resource,
+      cleanup: cleanup ?? null,
+      refCount: 1,
+      lastUsed: Date.now(),
+    });
+  }
+
+  getRegistered<T>(key: string): T | null {
+    const entry = this.genericResources.get(key);
+    if (entry) {
+      entry.refCount++;
+      entry.lastUsed = Date.now();
+      return entry.resource as T;
+    }
+    return null;
+  }
+
+  releaseRegistered(key: string): void {
+    const entry = this.genericResources.get(key);
+    if (entry) {
+      entry.refCount--;
+      if (entry.refCount <= 0) {
+        if (entry.cleanup) entry.cleanup();
+        this.genericResources.delete(key);
+      }
+    }
+  }
+
+  startAutoCleanup(intervalMs: number = 30000): void {
+    if (this.cleanupInterval !== null) return;
+    this.cleanupInterval = setInterval(() => this.cleanup(), intervalMs) as unknown as number;
+  }
+
+  stopAutoCleanup(): void {
+    if (this.cleanupInterval !== null) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.textures.entries()) {
+      if (entry.refCount <= 0 && now - entry.lastUsed > this.maxAge) {
+        (entry.resource as GPUTexture).destroy();
+        this.textures.delete(key);
+      }
+    }
+    for (const [key, entry] of this.buffers.entries()) {
+      if (entry.refCount <= 0 && now - entry.lastUsed > this.maxAge) {
+        (entry.resource as GPUBuffer).destroy();
+        this.buffers.delete(key);
+      }
+    }
+    // Evict stale generic resources (refCount <= 0 and past maxAge), then
+    // enforce an LRU cap of 64 entries by evicting least-recently-used items.
+    const GENERIC_LRU_MAX = 64;
+    for (const [key, entry] of this.genericResources.entries()) {
+      if (entry.refCount <= 0 && now - entry.lastUsed > this.maxAge) {
+        if (entry.cleanup) entry.cleanup();
+        this.genericResources.delete(key);
+      }
+    }
+    if (this.genericResources.size > GENERIC_LRU_MAX) {
+      // Map iterates in insertion order; sort by lastUsed ascending to evict LRU.
+      const sorted = [...this.genericResources.entries()].sort(
+        (a, b) => a[1].lastUsed - b[1].lastUsed,
+      );
+      const toEvict = sorted.length - GENERIC_LRU_MAX;
+      for (let i = 0; i < toEvict; i++) {
+        const [key, entry] = sorted[i];
+        if (entry.cleanup) entry.cleanup();
+        this.genericResources.delete(key);
+      }
+    }
+  }
+
+  getStats(): { textureCount: number; bufferCount: number; totalRefs: number } {
+    let totalRefs = 0;
+    for (const entry of this.textures.values()) totalRefs += entry.refCount;
+    for (const entry of this.buffers.values()) totalRefs += entry.refCount;
+    return {
+      textureCount: this.textures.size,
+      bufferCount: this.buffers.size,
+      totalRefs,
+    };
+  }
+
+  destroy(): void {
+    this.stopAutoCleanup();
+    for (const entry of this.textures.values()) {
+      (entry.resource as GPUTexture).destroy();
+    }
+    for (const entry of this.buffers.values()) {
+      (entry.resource as GPUBuffer).destroy();
+    }
+    for (const entry of this.genericResources.values()) {
+      if (entry.cleanup) entry.cleanup();
+    }
+    this.textures.clear();
+    this.buffers.clear();
+    this.genericResources.clear();
+  }
+}

package/core/src/assets/cubemap-converter.ts

@@ -0,0 +1,155 @@
+
+import { createValidatedShaderModule } from "../render/shader-validator";
+const EQUIRECT_TO_CUBEMAP_SHADER = /* wgsl */ `
+struct Uniforms {
+  faceSize: u32,
+  _pad: u32,
+  srcWidth: u32,
+  srcHeight: u32,
+};
+
+@group(0) @binding(0) var srcTex: texture_2d<f32>;
+@group(0) @binding(1) var dstTex: texture_storage_2d_array<rgba16float, write>;
+@group(0) @binding(2) var<uniform> uniforms: Uniforms;
+
+const PI: f32 = 3.141592653589793;
+
+fn faceDirToUV(face: u32, u: f32, v: f32) -> vec3<f32> {
+  let a = u * 2.0 - 1.0;
+  let b = v * 2.0 - 1.0;
+  switch face {
+    case 0u: { return vec3<f32>( 1.0, -b, -a); }  // +X
+    case 1u: { return vec3<f32>(-1.0, -b,  a); }  // -X
+    case 2u: { return vec3<f32>( a,  1.0,  b); }  // +Y
+    case 3u: { return vec3<f32>( a, -1.0, -b); }  // -Y
+    case 4u: { return vec3<f32>( a, -b,  1.0); }  // +Z
+    case 5u: { return vec3<f32>(-a, -b, -1.0); }  // -Z
+    default: { return vec3<f32>(0.0, 0.0, 0.0); }
+  }
+}
+
+fn dirToEquirect(dir: vec3<f32>, srcW: u32, srcH: u32) -> vec2<u32> {
+  let phi = atan2(dir.z, dir.x);
+  let theta = acos(clamp(dir.y, -1.0, 1.0));
+  let u = (phi / (2.0 * PI) + 0.5);
+  let v = theta / PI;
+  return vec2<u32>(u32(u * f32(srcW)), u32(v * f32(srcH)));
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let faceSize = uniforms.faceSize;
+  if (gid.x >= faceSize || gid.y >= faceSize) {
+    return;
+  }
+
+  let face = gid.z;
+  let u = (f32(gid.x) + 0.5) / f32(faceSize);
+  let v = (f32(gid.y) + 0.5) / f32(faceSize);
+
+  let dir = normalize(faceDirToUV(face, u, v));
+  let srcCoord = dirToEquirect(dir, uniforms.srcWidth, uniforms.srcHeight);
+
+  let color = textureLoad(srcTex, srcCoord, 0);
+  textureStore(dstTex, vec2<i32>(i32(gid.x), i32(gid.y)), i32(face), color);
+}
+`;
+
+export interface EquirectToCubemapOptions {
+  faceSize: number;
+  srcFormat?: GPUTextureFormat;
+  dstFormat?: GPUTextureFormat;
+}
+
+export class EquirectToCubemapConverter {
+  private device: GPUDevice;
+  private pipeline: GPUComputePipeline | null = null;
+  private bindGroupLayout: GPUBindGroupLayout | null = null;
+  private uniformBuffer: GPUBuffer | null = null;
+
+  constructor(device: GPUDevice) {
+    this.device = device;
+  }
+
+  private ensurePipeline(): void {
+    if (this.pipeline) return;
+
+    this.bindGroupLayout = this.device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.COMPUTE, texture: { sampleType: "float" } },
+        { binding: 1, visibility: GPUShaderStage.COMPUTE, storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d-array" } },
+        { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+      ],
+    });
+
+    const shaderModule = createValidatedShaderModule(this.device, { code: EQUIRECT_TO_CUBEMAP_SHADER, label: "CubemapConverter" });
+
+    const pipelineLayout = this.device.createPipelineLayout({
+      bindGroupLayouts: [this.bindGroupLayout],
+    });
+
+    this.pipeline = this.device.createComputePipeline({
+      layout: pipelineLayout,
+      compute: { module: shaderModule, entryPoint: "cs_main" },
+    });
+
+    this.uniformBuffer = this.device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+  }
+
+  convert(
+    srcTexture: GPUTexture,
+    options: EquirectToCubemapOptions,
+  ): GPUTexture {
+    this.ensurePipeline();
+
+    const faceSize = options.faceSize;
+    const dstFormat = options.dstFormat ?? "rgba16float";
+
+    const dstTexture = this.device.createTexture({
+      size: [faceSize, faceSize, 6],
+      format: dstFormat,
+      usage: GPUTextureUsage.STORAGE_BINDING |
+             GPUTextureUsage.TEXTURE_BINDING |
+             GPUTextureUsage.COPY_SRC,
+    });
+
+    const srcView = srcTexture.createView({
+      dimension: "2d",
+    });
+
+    const dstView = dstTexture.createView({
+      dimension: "2d-array",
+    });
+
+    const uniformData = new Uint32Array(4);
+    uniformData[0] = faceSize;
+    uniformData[1] = 0;
+    uniformData[2] = srcTexture.width;
+    uniformData[3] = srcTexture.height;
+    this.device!.queue.writeBuffer(this.uniformBuffer!, 0, uniformData);
+
+    const bindGroup = this.device.createBindGroup({
+      layout: this.bindGroupLayout!,
+      entries: [
+        { binding: 0, resource: srcView },
+        { binding: 1, resource: dstView },
+        { binding: 2, resource: { buffer: this.uniformBuffer! } },
+      ],
+    });
+
+    const encoder = this.device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(this.pipeline!);
+    pass.setBindGroup(0, bindGroup);
+    const workgroupsX = Math.ceil(faceSize / 8);
+    const workgroupsY = Math.ceil(faceSize / 8);
+    pass.dispatchWorkgroups(workgroupsX, workgroupsY, 6);
+    pass.end();
+    this.device.queue.submit([encoder.finish()]);
+
+    return dstTexture;
+  }
+}

package/core/src/assets/environment-manager.ts

@@ -0,0 +1,121 @@
+import { EquirectToCubemapConverter } from "./cubemap-converter";
+import { IrradianceGenerator } from "./irradiance-generator";
+import { createEquirectangularGPUTexture, createGPUCubemap, loadCubemapFromFiles } from "./loader-cubemap";
+import { loadHDRFile } from "./loader-hdr";
+import type { TextureData } from "./loader-texture";
+import { PrefilteredSpecularGenerator } from "./prefilter-generator";
+
+export interface EnvironmentMap {
+  cubemap: GPUTexture;
+  irradiance: GPUTexture;
+  prefilteredSpecular: GPUTexture[];
+  prefilteredMaxMip: number;
+  brdfLUT: GPUTexture | null;
+  faceSize: number;
+}
+
+export interface EnvironmentManagerOptions {
+  device: GPUDevice;
+  faceSize?: number;
+  prefilterLevels?: number;
+  prefilterSamples?: number;
+}
+
+export class EnvironmentManager {
+  private device: GPUDevice;
+  private equirectConverter: EquirectToCubemapConverter;
+  private irradianceGen: IrradianceGenerator;
+  private prefilterGen: PrefilteredSpecularGenerator;
+  private faceSize: number;
+  private prefilterLevels: number;
+  private prefilterSamples: number;
+  private currentEnv: EnvironmentMap | null = null;
+
+  constructor(options: EnvironmentManagerOptions) {
+    this.device = options.device;
+    this.equirectConverter = new EquirectToCubemapConverter(this.device);
+    this.irradianceGen = new IrradianceGenerator(this.device);
+    this.prefilterGen = new PrefilteredSpecularGenerator(this.device);
+    this.faceSize = options.faceSize ?? 256;
+    this.prefilterLevels = options.prefilterLevels ?? 5;
+    this.prefilterSamples = options.prefilterSamples ?? 512;
+  }
+
+  async loadFromEquirectangular(uri: string): Promise<EnvironmentMap> {
+    const texData = await loadHDRFile(uri);
+    if (!texData) throw new Error(`Failed to load HDR file: ${uri}`);
+    const equirectTex = createEquirectangularGPUTexture(this.device, texData, "rgba16float");
+
+    const cubemap = this.equirectConverter.convert(equirectTex, {
+      faceSize: this.faceSize,
+    });
+
+    equirectTex.destroy();
+
+    return this.generateIBLMaps(cubemap);
+  }
+
+  async loadFromCubemapFiles(
+    faceUris: [string, string, string, string, string, string],
+  ): Promise<EnvironmentMap> {
+    const cubemapData = await loadCubemapFromFiles(faceUris);
+    const cubemap = createGPUCubemap(this.device, cubemapData, "rgba16float");
+    return this.generateIBLMaps(cubemap);
+  }
+
+  async loadFromHDRData(texData: TextureData): Promise<EnvironmentMap> {
+    const equirectTex = createEquirectangularGPUTexture(this.device, texData, "rgba16float");
+    const cubemap = this.equirectConverter.convert(equirectTex, {
+      faceSize: this.faceSize,
+    });
+    equirectTex.destroy();
+    return this.generateIBLMaps(cubemap);
+  }
+
+  private generateIBLMaps(cubemap: GPUTexture): EnvironmentMap {
+    const irradiance = this.irradianceGen.generate(cubemap, {
+      faceSize: 32,
+    });
+
+    const prefilteredSpecular = this.prefilterGen.generateMipmapChain(
+      cubemap,
+      this.faceSize,
+      this.prefilterLevels,
+      this.prefilterSamples,
+    );
+
+    const envMap: EnvironmentMap = {
+      cubemap,
+      irradiance,
+      prefilteredSpecular,
+      prefilteredMaxMip: this.prefilterLevels - 1,
+      brdfLUT: null,
+      faceSize: this.faceSize,
+    };
+
+    this.currentEnv = envMap;
+    return envMap;
+  }
+
+  getCurrentEnvironment(): EnvironmentMap | null {
+    return this.currentEnv;
+  }
+
+  setBRDFLUT(lut: GPUTexture): void {
+    if (this.currentEnv) {
+      // Destroy the previous BRDF LUT texture before overwriting to avoid a leak.
+      this.currentEnv.brdfLUT?.destroy();
+      this.currentEnv.brdfLUT = lut;
+    }
+  }
+
+  destroy(): void {
+    if (!this.currentEnv) return;
+    this.currentEnv.cubemap.destroy();
+    this.currentEnv.irradiance.destroy();
+    this.currentEnv.prefilteredSpecular.forEach((tex) => {
+      tex.destroy();
+    });
+    this.currentEnv = null;
+  }
+}

package/core/src/assets/import-cache.ts

@@ -0,0 +1,65 @@
+// ============================================================================
+// Import Cache — caches resolved ImportSettings keyed by model path
+// ============================================================================
+// The cache eliminates repeated sidecar resolution + HTTP requests on
+// subsequent loads of the same model. Two implementations:
+//   - MemoryImportCache: in-process Map, used in browser-only mode
+//   - SQLiteImportCache: persistent, used on the native host
+//
+// The cache is keyed by model file path. Entries are invalidated when the
+// source file or sidecar mtime changes.
+//
+
+import type { ImportSettings } from "./import-settings";
+
+export interface CacheEntry {
+  settings: ImportSettings;
+  /** mtime (ms) of the model file when this entry was created. */
+  sourceMtime: number;
+  /** mtime (ms) of the sidecar file (0 if no sidecar). */
+  sidecarMtime: number;
+  /** When this entry was last updated (ms epoch). */
+  updatedAt: number;
+}
+
+export interface ImportCache {
+  get(modelPath: string): CacheEntry | null;
+  set(modelPath: string, entry: CacheEntry): void;
+  invalidate(modelPath: string): void;
+  close(): void;
+}
+
+/**
+ * In-memory import cache. Used when no host cache store is available or as
+ * a fallback when SQLite is unavailable. Does not persist across restarts.
+ */
+export class MemoryImportCache implements ImportCache {
+  private cache = new Map<string, CacheEntry>();
+
+  get(modelPath: string): CacheEntry | null {
+    return this.cache.get(modelPath) ?? null;
+  }
+
+  set(modelPath: string, entry: CacheEntry): void {
+    this.cache.set(modelPath, entry);
+  }
+
+  invalidate(modelPath: string): void {
+    this.cache.delete(modelPath);
+  }
+
+  close(): void {
+    this.cache.clear();
+  }
+}
+
+/**
+ * Check if a cache entry is still valid given current file mtimes.
+ */
+export function isCacheEntryValid(
+  entry: CacheEntry,
+  sourceMtime: number,
+  sidecarMtime: number,
+): boolean {
+  return entry.sourceMtime === sourceMtime && entry.sidecarMtime === sidecarMtime;
+}

package/core/src/assets/import-settings.ts

@@ -0,0 +1,72 @@
+// ============================================================================
+// Import Settings — per-model normalization configuration (core types)
+// ============================================================================
+// These settings control how a model is normalized at import time:
+// up-axis conversion, unit scaling, node-transform baking, centering, auto-fit.
+//
+// Defined in core (not plugin-models) so the ImportCache can store them
+// without a cross-package dependency. Module-models re-exports these.
+//
+
+export type UpAxis = "y" | "z";
+
+export type UnitSystem = "meters" | "centimeters" | "inches" | "millimeters" | "units";
+
+export type SettingsSource = "ddmeta" | "unity" | "godot" | "blender" | "parser" | "default";
+
+export interface ImportSettings {
+  /** Source up-axis. The engine is Y-up. If the source is Z-up, vertices and
+   * normals are rotated -90° around X: (x, y, z) → (x, z, -y). */
+  upAxis: UpAxis;
+  /** Source unit system. Positions are scaled to meters: cm→0.01, inch→0.0254,
+   * mm→0.001, units→1.0 (unknown, no conversion). */
+  units: UnitSystem;
+  /** Additional user scale multiplier, applied after unit conversion. Default: 1.0 */
+  scale: number;
+  /** Optional quaternion pre-rotation [x, y, z, w] applied to the root. Default: [0,0,0,1] */
+  rotation: [number, number, number, number];
+  /** Subtract bounding-box center to place the model at the origin. Default: false */
+  centerToOrigin: boolean;
+  /** Auto-fit: null = off, or target max-dimension in meters. When set, the model
+   * is uniformly scaled so its largest dimension equals this value. */
+  autoFit: number | null;
+  /** Node transform handling: "apply" = bake the node hierarchy transforms into
+   * mesh vertices, "ignore" = use raw mesh data only. Default: "apply" */
+  nodeTransforms: "apply" | "ignore";
+  /** Where these settings came from (for debugging / UI display). */
+  source: SettingsSource;
+}
+
+export function createDefaultImportSettings(
+  parserUpAxis?: UpAxis,
+  parserUnits?: UnitSystem,
+): ImportSettings {
+  return {
+    upAxis: parserUpAxis ?? "y",
+    units: parserUnits ?? "meters",
+    scale: 1.0,
+    rotation: [0, 0, 0, 1],
+    centerToOrigin: false,
+    autoFit: null,
+    nodeTransforms: "apply",
+    source: "default",
+  };
+}
+
+/** Merge two ImportSettings, with `override` taking priority on non-undefined fields. */
+export function mergeImportSettings(
+  base: ImportSettings,
+  override: Partial<ImportSettings>,
+  source: SettingsSource,
+): ImportSettings {
+  return {
+    upAxis: override.upAxis ?? base.upAxis,
+    units: override.units ?? base.units,
+    scale: override.scale ?? base.scale,
+    rotation: override.rotation ?? base.rotation,
+    centerToOrigin: override.centerToOrigin ?? base.centerToOrigin,
+    autoFit: override.autoFit ?? base.autoFit,
+    nodeTransforms: override.nodeTransforms ?? base.nodeTransforms,
+    source,
+  };
+}

package/core/src/assets/importer.ts

@@ -0,0 +1,108 @@
+import type { GLBLoader, GLTFDocument } from "./loader-mesh";
+
+export interface ImportOptions {
+  format: "gltf" | "glb";
+  generateNormals?: boolean;
+  generateTangents?: boolean;
+  flipY?: boolean;
+  scale?: number;
+}
+
+export interface ImportResult {
+  document: GLTFDocument;
+  /** Parsed model data (plugin ModelData shape) with meshes, materials, etc. */
+  model?: unknown;
+  binaryBuffer: Uint8Array | null;
+  warnings: string[];
+}
+
+export class AssetImporter {
+  private loader: GLBLoader;
+
+  constructor(loader: GLBLoader) {
+    this.loader = loader;
+  }
+
+  async importGLB(data: ArrayBuffer, options?: ImportOptions): Promise<ImportResult> {
+    const warnings: string[] = [];
+    const { meshes, nodes } = await this.loader.parseGLB(data);
+
+    // Apply scale: bake into vertex positions (uniform scale).
+    let processedMeshes = meshes;
+    if (options?.scale && options.scale !== 1) {
+      const s = options.scale;
+      processedMeshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        // Engine MeshData vertices are interleaved; position is at offset 0
+        // per vertex. The stride depends on the layout. We use the layout
+        // stride to find position offsets.
+        const stride = mesh.layout.stride / 4; // floats per vertex
+        for (let i = 0; i < mesh.vertexCount; i++) {
+          const base = i * stride;
+          verts[base + 0] *= s;
+          verts[base + 1] *= s;
+          verts[base + 2] *= s;
+        }
+      });
+    }
+
+    // Apply flipY: when flipY === false, flip UV V coordinate (1 - v).
+    // Default (flipY true/undefined) leaves UVs as-is (glTF convention).
+    if (options?.flipY === false) {
+      // UVs are not stored separately in engine MeshData; they're interleaved
+      // at offset 6-7 per vertex. Flip the V component.
+      processedMeshes.forEach((mesh) => {
+        const verts = mesh.vertices;
+        const stride = mesh.layout.stride / 4;
+        for (let i = 0; i < mesh.vertexCount; i++) {
+          const base = i * stride;
+          verts[base + 7] = 1 - verts[base + 7];
+        }
+      });
+    }
+
+    // Build a GLTFDocument-shaped object that retains mesh/node counts.
+    const document = {
+      asset: { version: "2.0" },
+      meshes: processedMeshes.map((m, i) => ({
+        name: `mesh_${i}`,
+        primitives: [{ attributes: {}, mode: 4 }],
+      })),
+      nodes,
+    } as unknown as GLTFDocument;
+
+    return {
+      document,
+      model: { meshes: processedMeshes, nodes, name: "imported", format: "glb" },
+      binaryBuffer: null,
+      warnings,
+    };
+  }
+
+  async importGLTF(json: object, binaryData?: ArrayBuffer): Promise<ImportResult> {
+    const warnings: string[] = [];
+    const doc = json as unknown as GLTFDocument;
+
+    if (!doc.asset || !doc.asset.version) {
+      warnings.push("Missing asset.version in GLTF document.");
+    }
+
+    if (doc.asset?.version && !doc.asset.version.startsWith("2.")) {
+      warnings.push(`GLTF version ${doc.asset.version} — only 2.x is fully supported.`);
+    }
+
+    const { meshes, nodes } = await this.loader.parseGLTFJSON(doc);
+
+    return {
+      document: doc,
+      model: { meshes, nodes, name: "imported", format: "gltf" },
+      binaryBuffer: binaryData ? new Uint8Array(binaryData) : null,
+      warnings,
+    };
+  }
+
+  supportsFormat(extension: string): boolean {
+    const ext = extension.toLowerCase().replace(".", "");
+    return ext === "glb" || ext === "gltf";
+  }
+}