@driftengine/assets 4.8.6 → 4.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Model readers for nine formats — `.blend` among them, read from the file's own DNA — and the streaming loader that uploads them.
 
-**Cost: 26.3 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 25.9 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/bcLoad.d.ts

@@ -23,4 +23,9 @@ export interface BcDecoder {
     readonly reason: string;
     dispose(): void;
 }
+/**
+ * A decoder over a worker `spawn` starts, or on the main thread where it is null — the default, since
+ * the worker's factory lives behind its own specifier (`@driftengine/assets/bcWorkers`) and a caller
+ * names it.
+ */
 export declare function createBcDecoder(spawn?: (() => BcWorker) | null): BcDecoder;

package/dist/bcLoad.js

@@ -8,10 +8,11 @@
  * otherwise**, which on a phone is every BC texture: in a worker, because a 2048² BC7 image is
  * 262,144 blocks and a phone's main thread spends the better part of a second on them.
  *
- * **Never silently slower.** Where there is no `Worker`, or the one this module starts fails to
- * load — a bundler that does not understand `new Worker(new URL(…))` — the decode moves to the main
- * thread and `reason` says so, and the loader prints it once. A request in flight when the worker
- * fails is decoded again there rather than left waiting.
+ * **Never silently slower.** Where no worker is named (`spawnBcWorker`, behind a specifier of its
+ * own so the barrel names none), where there is no `Worker`, or where the one started fails to load —
+ * a bundler that does not understand `new Worker(new URL(…))` — the decode moves to the main thread
+ * and `reason` says so, and the loader prints it once. A request in flight when the worker fails is
+ * decoded again there rather than left waiting.
  */
 import { uploadsCompressed } from '@driftengine/core';
 import { answerBcRequest } from './bcAnswer.js';
@@ -36,19 +37,11 @@ function settle(reply, pending) {
         pending.reject(new Error(reply.error ?? 'bc: the decode answered nothing'));
 }
 /**
- * The worker this package ships, built the way a bundler understands, or null where there is no
- * `Worker` at all. `createBcDecoder`'s `spawn` is the way past either.
+ * A decoder over a worker `spawn` starts, or on the main thread where it is null — the default, since
+ * the worker's factory lives behind its own specifier (`@driftengine/assets/bcWorkers`) and a caller
+ * names it.
  */
-const defaultSpawn = 
-// platform: feature probe — no `Worker` means BC decodes on the main thread, with a reason
-typeof Worker === 'undefined'
-    ? null
-    : () => 
-    // platform: browser default — `createBcDecoder(spawn)` is the seam a host supplies
-    new Worker(new URL('./bcWorker.js', import.meta.url), {
-        type: 'module',
-    });
-export function createBcDecoder(spawn = defaultSpawn) {
+export function createBcDecoder(spawn = null) {
     let worker = null;
     let reason = '';
     const pending = new Map();
@@ -62,7 +55,9 @@ export function createBcDecoder(spawn = defaultSpawn) {
         pending.clear();
     };
     if (spawn === null) {
-        reason = 'BC textures decode on the main thread: this runtime has no Worker';
+        reason =
+            'BC textures decode on the main thread: no worker was named. Pass `bcWorker: spawnBcWorker`, ' +
+                "exported by '@driftengine/assets/bcWorkers', to decode them off it";
     }
     else {
         try {

package/dist/bcWorkers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The BC decode worker, behind its own specifier, for the reason `physics/src/workers.ts` gives.
+ *
+ * **A bundler emits a worker before it decides the code reaching it is unreachable.** The loader's
+ * decoder built its worker with `new Worker(new URL('./bcWorker.ts', import.meta.url))` inside the
+ * barrel's graph, and Vite rewrites that at transform time, before tree-shaking, so every consumer
+ * importing anything from `@driftengine/assets` had the BC decoder's chunk written into its build,
+ * whether or not it ever loaded a BC texture. It did so from 4.8.4 to 4.8.6;
+ * `scripts/worker-entry.test.mjs` asserts that no barrel names a worker, and it skipped this barrel
+ * whenever the packages were not built, which is how the chunk shipped past it.
+ *
+ * So a loader that should decode BC off the main thread names the factory:
+ *
+ * ```ts
+ * import { DrftLoader } from '@driftengine/assets';
+ * import { spawnBcWorker } from '@driftengine/assets/bcWorkers';
+ *
+ * const loader = new DrftLoader(renderer, { bcWorker: spawnBcWorker });
+ * ```
+ *
+ * **A declared subpath, so it resolves the way the barrel does**: to the build by default and to
+ * this file under `drift-source`. The path into `src/` that 4.8.7 documented still resolves, through
+ * the manifest's `./*` passthrough, and hands every consumer TypeScript inside `node_modules`, which
+ * is the default the 2026-09-13 flip took away from the barrels; a resolver that maps a package's
+ * subpaths into `src/` also doubled it, to `src/src/bcWorkers.ts`.
+ *
+ * Without it BC textures decode on the main thread, and the loader says so once. **What that costs**
+ * is the decode of a texture the device cannot take as blocks, which on a phone is every BC texture:
+ * a 2048² BC7 image is 262,144 blocks.
+ */
+import type { BcWorker } from './bcLoad.ts';
+/** A BC decode worker, as a bundler understands one. Throws where the runtime has no `Worker`. */
+export declare function spawnBcWorker(): BcWorker;

package/dist/bcWorkers.js

@@ -0,0 +1,7 @@
+/** A BC decode worker, as a bundler understands one. Throws where the runtime has no `Worker`. */
+export function spawnBcWorker() {
+    // platform: browser default — `DrftLoaderOptions.bcWorker` is the seam a host supplies
+    return new Worker(new URL('./bcWorker.js', import.meta.url), {
+        type: 'module',
+    });
+}

package/dist/drftLoader.d.ts

@@ -5,6 +5,7 @@ import type { SurfaceTextureHandle } from '@driftengine/core';
 import type { DrftMaterial } from '@driftengine/drft';
 import type { DrftFieldPlacement } from './fieldPlacement.ts';
 import { TextureSet } from './drftTextures.ts';
+import type { BcWorker } from './bcLoad.ts';
 import type { DrawSurfaceOverride } from './drawKey.ts';
 import type { AnimationClip, DrftLight, DrftMorph, DrftNode, DrftSkin } from '@driftengine/drft';
 import type { DrftLightVolume, EntsScene, NavPolyMesh } from '@driftengine/drft';
@@ -48,6 +49,13 @@ export interface DrftLoaderOptions {
      * the default.
      */
     readonly fetchImpl?: FetchLike;
+    /**
+     * What starts the worker a BC texture the device cannot take as blocks is decoded in:
+     * `spawnBcWorker`, from `@driftengine/assets/bcWorkers`. Absent, they decode on the main
+     * thread and the loader says so once — the factory is behind its own specifier so a consumer that
+     * never names it has no worker in its build. See `bcWorkers.ts`.
+     */
+    readonly bcWorker?: () => BcWorker;
     /**
      * The most parts one `update` may take, however cheap they turn out to be.
      *

package/dist/drftLoader.js

@@ -1251,7 +1251,7 @@ export class DrftLoader {
             return;
         }
         if (this.bcDecoder === null)
-            this.bcDecoder = createBcDecoder();
+            this.bcDecoder = createBcDecoder(this.options.bcWorker ?? null);
         const decoder = this.bcDecoder;
         decoder
             .decode(image, asImage)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/assets",
-  "version": "4.8.6",
+  "version": "4.9.0",
   "description": "Model readers and the streaming loader for the .drft container",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,6 +12,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./bcWorkers": {
+      "drift-source": "./src/bcWorkers.ts",
+      "types": "./dist/bcWorkers.d.ts",
+      "default": "./dist/bcWorkers.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -27,11 +32,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.8.6",
-    "@driftengine/texture": "4.8.6"
+    "@driftengine/drft": "4.9.0",
+    "@driftengine/texture": "4.9.0"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.8.6"
+    "@driftengine/core": "4.9.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/bcLoad.ts

@@ -8,10 +8,11 @@
  * otherwise**, which on a phone is every BC texture: in a worker, because a 2048² BC7 image is
  * 262,144 blocks and a phone's main thread spends the better part of a second on them.
  *
- * **Never silently slower.** Where there is no `Worker`, or the one this module starts fails to
- * load — a bundler that does not understand `new Worker(new URL(…))` — the decode moves to the main
- * thread and `reason` says so, and the loader prints it once. A request in flight when the worker
- * fails is decoded again there rather than left waiting.
+ * **Never silently slower.** Where no worker is named (`spawnBcWorker`, behind a specifier of its
+ * own so the barrel names none), where there is no `Worker`, or where the one started fails to load —
+ * a bundler that does not understand `new Worker(new URL(…))` — the decode moves to the main thread
+ * and `reason` says so, and the loader prints it once. A request in flight when the worker fails is
+ * decoded again there rather than left waiting.
  */
 import { uploadsCompressed } from '@driftengine/core';
 import type { CompressedTextureFormat } from '@driftengine/core';
@@ -74,20 +75,11 @@ function settle(reply: BcReply, pending: Pending): void {
 }
 
 /**
- * The worker this package ships, built the way a bundler understands, or null where there is no
- * `Worker` at all. `createBcDecoder`'s `spawn` is the way past either.
+ * A decoder over a worker `spawn` starts, or on the main thread where it is null — the default, since
+ * the worker's factory lives behind its own specifier (`@driftengine/assets/bcWorkers`) and a caller
+ * names it.
  */
-const defaultSpawn: (() => BcWorker) | null =
-  // platform: feature probe — no `Worker` means BC decodes on the main thread, with a reason
-  typeof Worker === 'undefined'
-    ? null
-    : (): BcWorker =>
-        // platform: browser default — `createBcDecoder(spawn)` is the seam a host supplies
-        new Worker(new URL('./bcWorker.ts', import.meta.url), {
-          type: 'module',
-        }) as unknown as BcWorker;
-
-export function createBcDecoder(spawn: (() => BcWorker) | null = defaultSpawn): BcDecoder {
+export function createBcDecoder(spawn: (() => BcWorker) | null = null): BcDecoder {
   let worker: BcWorker | null = null;
   let reason = '';
   const pending = new Map<number, Pending>();
@@ -103,7 +95,9 @@ export function createBcDecoder(spawn: (() => BcWorker) | null = defaultSpawn):
   };
 
   if (spawn === null) {
-    reason = 'BC textures decode on the main thread: this runtime has no Worker';
+    reason =
+      'BC textures decode on the main thread: no worker was named. Pass `bcWorker: spawnBcWorker`, ' +
+      "exported by '@driftengine/assets/bcWorkers', to decode them off it";
   } else {
     try {
       worker = spawn();

package/src/bcWorkers.ts

@@ -0,0 +1,39 @@
+/**
+ * The BC decode worker, behind its own specifier, for the reason `physics/src/workers.ts` gives.
+ *
+ * **A bundler emits a worker before it decides the code reaching it is unreachable.** The loader's
+ * decoder built its worker with `new Worker(new URL('./bcWorker.ts', import.meta.url))` inside the
+ * barrel's graph, and Vite rewrites that at transform time, before tree-shaking, so every consumer
+ * importing anything from `@driftengine/assets` had the BC decoder's chunk written into its build,
+ * whether or not it ever loaded a BC texture. It did so from 4.8.4 to 4.8.6;
+ * `scripts/worker-entry.test.mjs` asserts that no barrel names a worker, and it skipped this barrel
+ * whenever the packages were not built, which is how the chunk shipped past it.
+ *
+ * So a loader that should decode BC off the main thread names the factory:
+ *
+ * ```ts
+ * import { DrftLoader } from '@driftengine/assets';
+ * import { spawnBcWorker } from '@driftengine/assets/bcWorkers';
+ *
+ * const loader = new DrftLoader(renderer, { bcWorker: spawnBcWorker });
+ * ```
+ *
+ * **A declared subpath, so it resolves the way the barrel does**: to the build by default and to
+ * this file under `drift-source`. The path into `src/` that 4.8.7 documented still resolves, through
+ * the manifest's `./*` passthrough, and hands every consumer TypeScript inside `node_modules`, which
+ * is the default the 2026-09-13 flip took away from the barrels; a resolver that maps a package's
+ * subpaths into `src/` also doubled it, to `src/src/bcWorkers.ts`.
+ *
+ * Without it BC textures decode on the main thread, and the loader says so once. **What that costs**
+ * is the decode of a texture the device cannot take as blocks, which on a phone is every BC texture:
+ * a 2048² BC7 image is 262,144 blocks.
+ */
+import type { BcWorker } from './bcLoad.ts';
+
+/** A BC decode worker, as a bundler understands one. Throws where the runtime has no `Worker`. */
+export function spawnBcWorker(): BcWorker {
+  // platform: browser default — `DrftLoaderOptions.bcWorker` is the seam a host supplies
+  return new Worker(new URL('./bcWorker.ts', import.meta.url), {
+    type: 'module',
+  }) as unknown as BcWorker;
+}

package/src/drftLoader.ts

@@ -11,7 +11,7 @@ import type { DrftFieldPlacement } from './fieldPlacement.ts';
 import type { DrftTexture } from '@driftengine/drft';
 import { TextureSet, textureColorSpaces } from './drftTextures.ts';
 import { bcPlan, createBcDecoder } from './bcLoad.ts';
-import type { BcDecoder } from './bcLoad.ts';
+import type { BcDecoder, BcWorker } from './bcLoad.ts';
 import { decodeBc } from './bcDecode.ts';
 import { isCompressedSource, uploadsCompressed } from '@driftengine/core';
 import { CODEC_BC, codecName, readBcPayload } from '@driftengine/drft';
@@ -82,6 +82,13 @@ export interface DrftLoaderOptions {
    * the default.
    */
   readonly fetchImpl?: FetchLike;
+  /**
+   * What starts the worker a BC texture the device cannot take as blocks is decoded in:
+   * `spawnBcWorker`, from `@driftengine/assets/bcWorkers`. Absent, they decode on the main
+   * thread and the loader says so once — the factory is behind its own specifier so a consumer that
+   * never names it has no worker in its build. See `bcWorkers.ts`.
+   */
+  readonly bcWorker?: () => BcWorker;
   /**
    * The most parts one `update` may take, however cheap they turn out to be.
    *
@@ -1523,7 +1530,7 @@ export class DrftLoader {
       done(image);
       return;
     }
-    if (this.bcDecoder === null) this.bcDecoder = createBcDecoder();
+    if (this.bcDecoder === null) this.bcDecoder = createBcDecoder(this.options.bcWorker ?? null);
     const decoder = this.bcDecoder;
     decoder
       .decode(image, asImage)