beckhoff-xts-viewer-3d 4.2.0 → 4.4.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { ColorRepresentation, Shape, Curve, Vector3, CurvePath, Matrix4 } from 'three';
+import { ColorRepresentation, Shape, Curve, Vector3, CurvePath, Matrix4, WebGLRenderer } from 'three';
 import { GLTF } from 'three-stdlib';
 
 /**
@@ -12,7 +12,7 @@ import { GLTF } from 'three-stdlib';
  * Run `npm run sync-version` (or any script that depends on it) to refresh
  * after bumping the package version.
  */
-declare const VERSION: "4.2.0";
+declare const VERSION: "4.4.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -1696,6 +1696,13 @@ interface XtsViewer3DProps {
          * Falls back to WebGL automatically. Default: false (experimental).
          */
         webgpu?: boolean;
+        /**
+         * Override the KTX2 (Basis) transcoder path used to decode compressed
+         * textures in the GLB assets. Defaults to a CDN copy pinned to the
+         * bundled three.js revision. Point this at a self-hosted
+         * `basis_transcoder.{js,wasm}` directory for offline / air-gapped use.
+         */
+        ktx2TranscoderUrl?: string;
     };
     /**
      * Live override of the per-asset origin-correction sidecars. Useful for
@@ -2245,6 +2252,39 @@ declare function resolveGuidingRailType(moduleType: ModuleType3D): RailType3D |
  */
 declare function resolveGuidingRailGlbUrl(railType: RailType3D, override?: AssetManifest['guidingRails']): string;
 
+/**
+ * configureGltfLoaders — wire compression decoders onto a GLTFLoader.
+ *
+ * The viewer ships Meshopt-compressed geometry (EXT_meshopt_compression)
+ * and KTX2/Basis-compressed textures (KHR_texture_basisu). Neither decodes
+ * unless the GLTFLoader has the matching decoder attached, so this module
+ * centralises that wiring for both load paths:
+ *
+ *   - the render hot-path via drei's `useGLTF` (see `useGltfClone.ts`), and
+ *   - the public preload API (`AssetLoader`).
+ *
+ * Design: pure, framework-free functions so the wiring is unit-testable with
+ * fake loader / renderer objects (node has no WebGL2, so KTX2 transcoding
+ * itself is exercised in the browser — see docs/performance-analysis.md).
+ *
+ * Meshopt geometry decodes headless (no GPU needed) and is therefore always
+ * attached. KTX2 transcoding needs the live `WebGLRenderer` to detect the
+ * GPU's supported compressed-texture formats, so it is only attached when a
+ * renderer is provided. A loader configured this way still loads plain,
+ * uncompressed GLBs unchanged — attaching decoders is backward-compatible.
+ */
+
+interface ConfigureLoaderOptions {
+    /**
+     * The live WebGLRenderer. Required for KTX2 textures — the loader must
+     * detect which GPU-compressed formats the device supports. When omitted
+     * (SSR / node tests), only Meshopt geometry decoding is wired up.
+     */
+    gl?: WebGLRenderer | null;
+    /** Override the KTX2 transcoder (basis) path for this call. */
+    transcoderUrl?: string;
+}
+
 /**
  * AssetLoader — promise-cached GLB loader for the viewer.
  *
@@ -2265,6 +2305,16 @@ declare function resolveGuidingRailGlbUrl(railType: RailType3D, override?: Asset
 declare class AssetLoader {
     private readonly cache;
     private readonly loader;
+    /**
+     * Wire compression decoders (Meshopt always; KTX2 when a renderer is
+     * supplied) onto the underlying GLTFLoader so Meshopt/KTX2-compressed GLBs
+     * parse. Safe to call repeatedly and before/after loads — it only attaches
+     * decoders and does not touch the cache. Without `gl`, only Meshopt
+     * geometry is wired (KTX2 needs the renderer for GPU-format detection).
+     */
+    configure(options?: ConfigureLoaderOptions & {
+        gl?: WebGLRenderer | null;
+    }): void;
     /**
      * Load a GLB. Repeated calls for the same URL return the cached Promise.
      * Returns the parsed GLTF object — the consumer is responsible for

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import React__default from 'react';
-import { ColorRepresentation, Shape, Curve, Vector3, CurvePath, Matrix4 } from 'three';
+import { ColorRepresentation, Shape, Curve, Vector3, CurvePath, Matrix4, WebGLRenderer } from 'three';
 import { GLTF } from 'three-stdlib';
 
 /**
@@ -12,7 +12,7 @@ import { GLTF } from 'three-stdlib';
  * Run `npm run sync-version` (or any script that depends on it) to refresh
  * after bumping the package version.
  */
-declare const VERSION: "4.2.0";
+declare const VERSION: "4.4.0";
 
 /**
  * Default CDN URL for the GLB asset bundle (`beckhoff-xts-viewer-3d-assets`).
@@ -1696,6 +1696,13 @@ interface XtsViewer3DProps {
          * Falls back to WebGL automatically. Default: false (experimental).
          */
         webgpu?: boolean;
+        /**
+         * Override the KTX2 (Basis) transcoder path used to decode compressed
+         * textures in the GLB assets. Defaults to a CDN copy pinned to the
+         * bundled three.js revision. Point this at a self-hosted
+         * `basis_transcoder.{js,wasm}` directory for offline / air-gapped use.
+         */
+        ktx2TranscoderUrl?: string;
     };
     /**
      * Live override of the per-asset origin-correction sidecars. Useful for
@@ -2245,6 +2252,39 @@ declare function resolveGuidingRailType(moduleType: ModuleType3D): RailType3D |
  */
 declare function resolveGuidingRailGlbUrl(railType: RailType3D, override?: AssetManifest['guidingRails']): string;
 
+/**
+ * configureGltfLoaders — wire compression decoders onto a GLTFLoader.
+ *
+ * The viewer ships Meshopt-compressed geometry (EXT_meshopt_compression)
+ * and KTX2/Basis-compressed textures (KHR_texture_basisu). Neither decodes
+ * unless the GLTFLoader has the matching decoder attached, so this module
+ * centralises that wiring for both load paths:
+ *
+ *   - the render hot-path via drei's `useGLTF` (see `useGltfClone.ts`), and
+ *   - the public preload API (`AssetLoader`).
+ *
+ * Design: pure, framework-free functions so the wiring is unit-testable with
+ * fake loader / renderer objects (node has no WebGL2, so KTX2 transcoding
+ * itself is exercised in the browser — see docs/performance-analysis.md).
+ *
+ * Meshopt geometry decodes headless (no GPU needed) and is therefore always
+ * attached. KTX2 transcoding needs the live `WebGLRenderer` to detect the
+ * GPU's supported compressed-texture formats, so it is only attached when a
+ * renderer is provided. A loader configured this way still loads plain,
+ * uncompressed GLBs unchanged — attaching decoders is backward-compatible.
+ */
+
+interface ConfigureLoaderOptions {
+    /**
+     * The live WebGLRenderer. Required for KTX2 textures — the loader must
+     * detect which GPU-compressed formats the device supports. When omitted
+     * (SSR / node tests), only Meshopt geometry decoding is wired up.
+     */
+    gl?: WebGLRenderer | null;
+    /** Override the KTX2 transcoder (basis) path for this call. */
+    transcoderUrl?: string;
+}
+
 /**
  * AssetLoader — promise-cached GLB loader for the viewer.
  *
@@ -2265,6 +2305,16 @@ declare function resolveGuidingRailGlbUrl(railType: RailType3D, override?: Asset
 declare class AssetLoader {
     private readonly cache;
     private readonly loader;
+    /**
+     * Wire compression decoders (Meshopt always; KTX2 when a renderer is
+     * supplied) onto the underlying GLTFLoader so Meshopt/KTX2-compressed GLBs
+     * parse. Safe to call repeatedly and before/after loads — it only attaches
+     * decoders and does not touch the cache. Without `gl`, only Meshopt
+     * geometry is wired (KTX2 needs the renderer for GPU-format detection).
+     */
+    configure(options?: ConfigureLoaderOptions & {
+        gl?: WebGLRenderer | null;
+    }): void;
     /**
      * Load a GLB. Repeated calls for the same URL return the cached Promise.
      * Returns the parsed GLTF object — the consumer is responsible for