@driftengine/core 4.2.0 → 4.3.0

package/CHANGELOG.json

@@ -1,4 +1,26 @@
 [
+ {
+  "version": "4.3.0",
+  "date": "2026-09-21",
+  "entries": [
+   {
+    "kind": "added",
+    "short": "RendererApi.snapTextCellSize, so a caller can draw a bitmap glyph on whole device pixels and measure the size it will actually get.",
+    "text": "**The snap 4.1.4 imposed and 4.2.0 made opt-in, now reachable from where text is actually laid out.**\n\n`deviceSnappedCellSize` has been exported since 4.2.0, but it takes the ratio as two widths and the second of them is the renderer's own drawing buffer. `RendererApi` carries `cssWidth` and `cssHeight` and nothing about device pixels, and a game's text layout is a pure function over CSS pixels — so a consumer that wanted whole-pixel strokes had to thread a canvas down through its whole interface layer to reach a number the renderer was already holding. Every consumer on this engine sizes text that way, so the export alone was not adoptable.\n\n```js\nconst cell = renderer.snapTextCellSize(available / cells, viewportWidth);\nconst width = textWidthPx(label, cell);\nconst x = (boxWidth - width) / 2;\nrenderer.drawText(text, viewportWidth, viewportHeight, x, y, { ...style, cellSize: cell }, now);\n```\n\n`viewportWidth` is the caller's own and it already passes it to `drawText`. Snap once on the line the cell is computed, and the width, the centring, the right edge and the row pitch all follow from the one number — the measurement and the picture cannot disagree, which is the property the imposed version could never have.\n\nThe decision stays in `textLayout.ts` with only the binding per backend: the cell drawn is the largest whole number of device pixels not larger than the one asked for, downward so a line fitted to a box can only leave a gap rather than overflow it, and a cell already whole comes back untouched. **What it gives up** is that a caller who does not ask still gets strokes of two widths on a fractional cell, which is the trade 4.2.0 chose deliberately.\n\nPinned on the shared surface by a test rather than left to the `Omit` derivation, for the reason `api.test.ts` records about the resolution governor: a public member is otherwise on the surface by accident of not being in the omit list, which is a poor way to make a promise."
+   }
+  ]
+ },
+ {
+  "version": "4.2.1",
+  "date": "2026-09-21",
+  "entries": [
+   {
+    "kind": "fixed",
+    "short": "A physics worker pool survives a slow start. Its first adoption was racing the time its own workers take to load, and losing on small or cold machines.",
+    "text": "**Reported from continuous integration, intermittently, as \"the workers did not take the shared buffer, so island solving stayed on this thread.\"** The world stays correct when that happens, because the pool falls back to a serial solve, so what it costs is the capability rather than the picture. That is why it survived: nothing looked wrong, physics was just quietly single-threaded.\n\n`createIslandPool` spawns its workers and returns with no readiness handshake, so the *first* `reload` of a pool is also paying for the worker entry to load: a module graph, resolved and type-stripped, once per worker. It was measured against the deadline meant for a running worker that has stopped answering, and those are different questions.\n\n**Measured** on an idle twenty-four core machine with a warm module cache: the first adoption of each pool takes **45 to 77 ms** and every later one **0.3 to 0.8 ms**. So the 250 ms was already spending up to a third of itself on startup under the best conditions available, and a cold two-core machine goes over it.\n\nThe first adoption now has its own five second budget, because a boot that slow is still a working pool while the alternative is serial physics for the life of the world. The deadline that means \"a running worker stopped answering\" is untouched. The wait also parks on the acknowledgement rather than spinning for it, which a budget that long makes load-bearing rather than tidy: burning a core for five seconds would slow the very startup being waited for, and the worker has always answered with `Atomics.notify` on that slot.\n\n**Two earlier attempts blamed core contention and are recorded in the test file beside this one**, because neither reproduced anything: a hot spin does not starve a worker on a preemptive scheduler, which is what made a startup cost look like a scheduling one twice running. This one is proven by reproduction: forcing the start deadline below the measured boot reproduces both failing cases and the identical message, and restoring it turns them green.\n\nA consumer on a phone or a modest laptop is the one this was costing, which is where a worker pool is worth the most."
+   }
+  ]
+ },
  {
   "version": "4.2.0",
   "date": "2026-09-21",

package/dist/render/backend/webgl2/renderer.d.ts

@@ -1839,6 +1839,25 @@ export declare class WebGL2Renderer implements RendererApi {
      * whatever box the caller lays out in, and the game's own card is not always the canvas.
      */
     drawText(text: TextRenderer, viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number): void;
+    /**
+     * The cell size to draw a bitmap glyph at so every cell covers whole device pixels.
+     *
+     * **The caller snaps, and then measures and draws with the one number.** 4.1.4 applied this
+     * inside `drawText` instead, where `textWidthPx` could not see it — it takes no viewport and so
+     * cannot know the ratio — and every consumer went on laying out against the cell it asked for
+     * while the engine drew a smaller one. A centred line, a right-aligned column and a line fitted
+     * to a box broke together. Snapped here, the arithmetic and the picture cannot disagree.
+     *
+     * **It is on the renderer because only the renderer knows the second number.** `viewportWidth`
+     * is the caller's, and it already passes it to `drawText`; the drawing buffer is not on the
+     * shared surface and a game's text layout is a pure function over CSS pixels, so reaching it
+     * meant threading a canvas through an interface layer to a value the renderer was holding.
+     *
+     * The decision itself stays in `textLayout.ts` and only this binding is per backend, which is
+     * the 2026-08-13 rule: a cell already whole comes back untouched, and the snap is downward so a
+     * line fitted to a box can only leave a gap rather than overflow it.
+     */
+    snapTextCellSize(cellSize: number, viewportWidth: number): number;
     /** Width of the string this handle currently holds, in pixels at a given cell size. */
     textWidth(text: TextRenderer, cellSize: number): number;
     disposeText(text: TextRenderer): void;

package/dist/render/backend/webgl2/renderer.js

@@ -75,6 +75,7 @@ import { TextRenderer } from '../../textRenderer.js';
 import { SdfTextRenderer } from '../../sdfTextRenderer.js';
 import { MOTION_BLUR_MAX_UV, RUSH_REACH_UV } from '../../vertexDefaults.js';
 import { OUTPUT_TRANSFORM_CODE } from '../../vertexDefaults.js';
+import { deviceSnappedCellSize } from '../../textLayout.js';
 import { WindStreakRenderer } from '../../windStreakRenderer.js';
 import { InstancedBatch } from './instanced.js';
 /**
@@ -2777,6 +2778,27 @@ export class WebGL2Renderer {
             this.textBudget.ask();
         }
     }
+    /**
+     * The cell size to draw a bitmap glyph at so every cell covers whole device pixels.
+     *
+     * **The caller snaps, and then measures and draws with the one number.** 4.1.4 applied this
+     * inside `drawText` instead, where `textWidthPx` could not see it — it takes no viewport and so
+     * cannot know the ratio — and every consumer went on laying out against the cell it asked for
+     * while the engine drew a smaller one. A centred line, a right-aligned column and a line fitted
+     * to a box broke together. Snapped here, the arithmetic and the picture cannot disagree.
+     *
+     * **It is on the renderer because only the renderer knows the second number.** `viewportWidth`
+     * is the caller's, and it already passes it to `drawText`; the drawing buffer is not on the
+     * shared surface and a game's text layout is a pure function over CSS pixels, so reaching it
+     * meant threading a canvas through an interface layer to a value the renderer was holding.
+     *
+     * The decision itself stays in `textLayout.ts` and only this binding is per backend, which is
+     * the 2026-08-13 rule: a cell already whole comes back untouched, and the snap is downward so a
+     * line fitted to a box can only leave a gap rather than overflow it.
+     */
+    snapTextCellSize(cellSize, viewportWidth) {
+        return deviceSnappedCellSize(cellSize, viewportWidth, this.gl.drawingBufferWidth);
+    }
     /** Width of the string this handle currently holds, in pixels at a given cell size. */
     textWidth(text, cellSize) {
         return text.widthPx(cellSize);

package/dist/render/backend/webgpu/renderer.d.ts

@@ -1126,6 +1126,8 @@ export declare class WebGPURenderer implements RendererApi {
     createText(): GpuText;
     setText(text: GpuText, content: string): void;
     setPlate(text: GpuText, widthCells: number, heightCells: number, bottomCell: number): void;
+    /** See `Renderer.snapTextCellSize`; only the drawing buffer differs. */
+    snapTextCellSize(cellSize: number, viewportWidth: number): number;
     textWidth(text: GpuText, cellSize: number): number;
     disposeText(text: GpuText): void;
     /** A text label from an SDF font. See `sdfTextPass.ts`; the layout it holds is shared with WebGL2. */

package/dist/render/backend/webgpu/renderer.js

@@ -38,7 +38,7 @@ import { POINT_SHADOW_SAMPLER, PointShadowSystem, } from '../../pointShadowSyste
 import { GpuPointShadowArray, GpuPointShadowMap } from './pointShadowPass.js';
 import { createPanelBindGroup, createPanelBindGroupLayout, createPanelCorners, panelPipeline, PANEL_FRAG_FIELDS, PANEL_FRAG_SIZE, PANEL_VERTEX_COUNT, PANEL_VERT_FIELDS, PANEL_VERT_SIZE, } from './panelPass.js';
 import { createGpuTextCube, createTextBindGroup, createTextBindGroupLayout, GpuText, textPipeline, TEXT_FRAG_FIELDS, TEXT_FRAG_SIZE, TEXT_VERT_FIELDS, TEXT_VERT_SIZE, } from './textPass.js';
-import { deviceSnappedOrigin } from '../../textLayout.js';
+import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.js';
 import { GpuSurfaceTexture } from './surfaceTexturePass.js';
 import { createSdfTextBindGroup, createSdfTextBindGroupLayout, GpuSdfText, sdfTextPipeline, SDF_TEXT_FRAG_FIELDS, SDF_TEXT_FRAG_SIZE, SDF_TEXT_VERT_FIELDS, SDF_TEXT_VERT_SIZE, } from './sdfTextPass.js';
 import { createFilmBindGroup, createFilmBindGroupLayout, filmPipeline, FILM_FRAG_FIELDS, FILM_FRAG_SIZE, FILM_VERT_FIELDS, FILM_VERT_SIZE, } from './filmPass.js';
@@ -2342,6 +2342,10 @@ export class WebGPURenderer {
     setPlate(text, widthCells, heightCells, bottomCell) {
         text.setPlate(widthCells, heightCells, bottomCell);
     }
+    /** See `Renderer.snapTextCellSize`; only the drawing buffer differs. */
+    snapTextCellSize(cellSize, viewportWidth) {
+        return deviceSnappedCellSize(cellSize, viewportWidth, this.surface.canvas.width);
+    }
     textWidth(text, cellSize) {
         return text.layout.widthPx(cellSize);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.2.0",
-    "@driftengine/physics": "4.2.0",
+    "@driftengine/drft": "4.3.0",
+    "@driftengine/physics": "4.3.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -63,8 +63,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.2.0",
-    "@driftengine/network": "4.2.0",
-    "@driftengine/texture": "4.2.0"
+    "@driftengine/nav": "4.3.0",
+    "@driftengine/network": "4.3.0",
+    "@driftengine/texture": "4.3.0"
   }
 }

package/src/render/backend/webgl2/renderer.ts

@@ -218,6 +218,7 @@ import type { SdfTextStyle } from '../../sdfTextLayout.ts';
 import { MOTION_BLUR_MAX_UV, RUSH_REACH_UV } from '../../vertexDefaults.ts';
 import { OUTPUT_TRANSFORM_CODE } from '../../vertexDefaults.ts';
 import type { RenderBackend } from '../api.ts';
+import { deviceSnappedCellSize } from '../../textLayout.ts';
 import type { TextStyle } from '../../textLayout.ts';
 import { WindStreakRenderer } from '../../windStreakRenderer.ts';
 import type { WindStreakOptions } from '../../windStreakRenderer.ts';
@@ -3657,6 +3658,28 @@ export class WebGL2Renderer implements RendererApi {
     }
   }
 
+  /**
+   * The cell size to draw a bitmap glyph at so every cell covers whole device pixels.
+   *
+   * **The caller snaps, and then measures and draws with the one number.** 4.1.4 applied this
+   * inside `drawText` instead, where `textWidthPx` could not see it — it takes no viewport and so
+   * cannot know the ratio — and every consumer went on laying out against the cell it asked for
+   * while the engine drew a smaller one. A centred line, a right-aligned column and a line fitted
+   * to a box broke together. Snapped here, the arithmetic and the picture cannot disagree.
+   *
+   * **It is on the renderer because only the renderer knows the second number.** `viewportWidth`
+   * is the caller's, and it already passes it to `drawText`; the drawing buffer is not on the
+   * shared surface and a game's text layout is a pure function over CSS pixels, so reaching it
+   * meant threading a canvas through an interface layer to a value the renderer was holding.
+   *
+   * The decision itself stays in `textLayout.ts` and only this binding is per backend, which is
+   * the 2026-08-13 rule: a cell already whole comes back untouched, and the snap is downward so a
+   * line fitted to a box can only leave a gap rather than overflow it.
+   */
+  snapTextCellSize(cellSize: number, viewportWidth: number): number {
+    return deviceSnappedCellSize(cellSize, viewportWidth, this.gl.drawingBufferWidth);
+  }
+
   /** Width of the string this handle currently holds, in pixels at a given cell size. */
   textWidth(text: TextRenderer, cellSize: number): number {
     return text.widthPx(cellSize);

package/src/render/backend/webgpu/renderer.ts

@@ -150,7 +150,7 @@ import {
   type GpuTextCube,
 } from './textPass.ts';
 import type { TextStyle } from '../../textLayout.ts';
-import { deviceSnappedOrigin } from '../../textLayout.ts';
+import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.ts';
 import { GpuSurfaceTexture } from './surfaceTexturePass.ts';
 import {
   createSdfTextBindGroup,
@@ -3000,6 +3000,11 @@ export class WebGPURenderer implements RendererApi {
     text.setPlate(widthCells, heightCells, bottomCell);
   }
 
+  /** See `Renderer.snapTextCellSize`; only the drawing buffer differs. */
+  snapTextCellSize(cellSize: number, viewportWidth: number): number {
+    return deviceSnappedCellSize(cellSize, viewportWidth, this.surface.canvas.width);
+  }
+
   textWidth(text: GpuText, cellSize: number): number {
     return text.layout.widthPx(cellSize);
   }