@driftengine/core 4.1.5 → 4.2.1

package/CHANGELOG.json

@@ -1,4 +1,31 @@
 [
+ {
+  "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",
+  "entries": [
+   {
+    "kind": "fixed",
+    "short": "Text is drawn at the cell size it was asked for, so a centred line is centred again. 4.1.4 snapped the cell down without telling the caller that measured it.",
+    "text": "**Reported as text that \"is not centered anymore and maybe tinier\", in every consumer at once**, correct in a full-size landscape browser and wrong in mobile portrait.\n\n4.1.4 made the draw path snap the cell down to whole device pixels, so a 5x7 face could not draw strokes of two different widths. That defect is real and the snap is the right cure for it, but imposing it was wrong. `textWidthPx` is the only measurement a consumer has, it takes no viewport and therefore cannot know the device ratio, so every consumer went on laying out against the cell it asked for while the engine drew a smaller one.\n\n**Everything done with a measured width broke together**: a centred line, a right-aligned column, a line fitted to a box. Measured on a 23-character string, a cell of 4.68 at ratio 1 draws 46.6 px narrower than measured; a whole cell of 3 on a 1.25 display draws 41.1 px narrower and 20% smaller than asked. The release note that shipped it called this \"at most half a device pixel per cell off centre\", which was wrong by two orders of magnitude.\n\n**It looked fine on a desktop because the snap is a no-op there.** A whole cell at a whole device ratio is returned untouched, which is exactly the case a full-size landscape browser produces. A consumer that divides an available width by a cell count, which is what a responsive layout does, gets a fraction and pays the whole gap. That is why it was reported as a mobile-portrait fault rather than a text fault.\n\nBoth backends now draw the cell they are handed. The origin snap stays: it rounds to the nearest device pixel, shifts a line by at most half of one and breaks no layout.\n\n**What this gives up** is that a fractional cell draws strokes of two widths again for a caller that does not opt in, which is the defect 4.1.4 was written to fix. It is available rather than imposed now, and the entry below is how."
+   },
+   {
+    "kind": "added",
+    "short": "deviceSnappedCellSize is exported, so a caller can ask for whole-pixel glyph strokes and measure the size it will actually get.",
+    "text": "The cell size to draw at so that every cell of a bitmap glyph covers whole device pixels, which the engine used to apply on the caller's behalf and no longer does.\n\n**It was not exported at all before**, which is why no consumer could have compensated for the snap being imposed: the decision was reachable only from inside the renderer. Snap once, at the point the cell is computed, then use that one number to measure, to lay out and to draw. The measurement and the picture then agree by construction, which is the property the imposed version could not have.\n\n```js\nconst cell = deviceSnappedCellSize(available / cells, viewportWidth, canvas.width);\nconst width = textWidthPx(label, cell);\nrenderer.drawText(text, viewportWidth, viewportHeight, (boxWidth - width) / 2, y, { ...style, cellSize: cell }, now);\n```\n\nThe cell drawn is the largest whole number of device pixels not larger than the one asked for. Down rather than to nearest, because a caller that fitted a line to a box measured it first and rounding up would draw a line wider than the box; rounding down can only leave a gap. A cell already whole is returned untouched, so nothing moves where there was nothing to fix."
+   }
+  ]
+ },
  {
   "version": "4.1.5",
   "date": "2026-09-21",

package/dist/index.d.ts

@@ -331,7 +331,7 @@ export { BoltBatch } from './render/boltBatch.ts';
 export { createLineSegments, setPolyline } from './render/linePoints.ts';
 export type { LineSegments } from './render/linePoints.ts';
 export { FlockRenderer } from './render/flockRenderer.ts';
-export { DEFAULT_TEXT_STYLE, textHeightPx, textWidthPx } from './render/textLayout.ts';
+export { DEFAULT_TEXT_STYLE, deviceSnappedCellSize, textHeightPx, textWidthPx, } from './render/textLayout.ts';
 export type { TextStyle } from './render/textLayout.ts';
 export { GLYPH_HEIGHT, GLYPH_SPACING, GLYPH_WIDTH, countCells, forEachCell, forEachRun, glyphRows, hasGlyph, measureText, } from './geometry/pixelFont.ts';
 export { parseSdfFont } from './render/sdfFont.ts';

package/dist/index.js

@@ -433,7 +433,13 @@ export { FlockRenderer } from './render/flockRenderer.js';
  * the same shape scatter, plumes, particles, flocks and bolts already have. The measuring
  * helpers were statics on the class and are free functions now, because neither needs a device.
  */
-export { DEFAULT_TEXT_STYLE, textHeightPx, textWidthPx } from './render/textLayout.js';
+export { DEFAULT_TEXT_STYLE, 
+/*
+ * Exported so a caller can ask for whole-pixel strokes, which the engine used to impose. See
+ * the note at the cell upload in `render/textRenderer.ts`: snap once, then measure, lay out
+ * and draw with that one number.
+ */
+deviceSnappedCellSize, textHeightPx, textWidthPx, } from './render/textLayout.js';
 export { GLYPH_HEIGHT, GLYPH_SPACING, GLYPH_WIDTH, countCells, forEachCell, forEachRun, glyphRows, hasGlyph, measureText, } from './geometry/pixelFont.js';
 /*
  * SDF text, reached the same way pixel text is: the verbs are on the renderer and the

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 { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.js';
+import { 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';
@@ -2492,9 +2492,9 @@ export class WebGPURenderer {
             deviceSnappedOrigin(originX, viewportWidth, this.surface.canvas.width),
             deviceSnappedOrigin(originY, viewportHeight, this.surface.canvas.height),
         ]);
-        /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
-           decision is shared with WebGL2; only this binding is per-backend. See `textLayout.ts`. */
-        v.writeFloat(vertexSlot, at('uCellSize'), deviceSnappedCellSize(style.cellSize, viewportWidth, this.surface.canvas.width));
+        /* The cell the caller asked for, drawn faithfully. See `textRenderer.ts` for why the snap
+           this used to impose is the caller's to ask for. */
+        v.writeFloat(vertexSlot, at('uCellSize'), style.cellSize);
         /* Far enough that a whole line barely converges, near enough that a turn reads as a turn. */
         v.writeFloat(vertexSlot, at('uDepth'), Math.max(viewportWidth, 600) * 1.4);
         v.writeFloat(vertexSlot, at('uReveal'), style.reveal);

package/dist/render/textRenderer.js

@@ -1,4 +1,4 @@
-import { MAX_CELLS, TEXT_CUBE, TextLayout, deviceSnappedCellSize, deviceSnappedOrigin, } from './textLayout.js';
+import { MAX_CELLS, TEXT_CUBE, TextLayout, deviceSnappedOrigin } from './textLayout.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { TEXT_FRAG, TEXT_VERT } from './shaders/text.js';
 /**
@@ -103,9 +103,28 @@ export class TextRenderer {
         /* Snapped with the cell below: a whole pitch on a fractional origin still splits a stroke.
            See `deviceSnappedOrigin`. */
         setVec2(gl, this.uniforms['uOrigin'], deviceSnappedOrigin(originX, viewportWidth, gl.drawingBufferWidth), deviceSnappedOrigin(originY, viewportHeight, gl.drawingBufferHeight));
-        /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
-           decision is shared with WebGPU; only this binding is per-backend. See `textLayout.ts`. */
-        setFloat(gl, this.uniforms['uCellSize'], deviceSnappedCellSize(style.cellSize, viewportWidth, gl.drawingBufferWidth));
+        /*
+         * **The cell the caller asked for, drawn faithfully.**
+         *
+         * 4.1.4 snapped this down to whole device pixels here, so a 5x7 face could not draw strokes
+         * of two different widths. That defect is real and the snap is the right cure for it, but
+         * imposing it was wrong: `textWidthPx` is the only measurement a consumer has, it takes no
+         * viewport and so cannot know the device ratio, and every consumer went on laying out against
+         * the cell it asked for while this drew a smaller one. A centred line, a right-aligned column
+         * and a line fitted to a box all broke at once, silently, and only where the snap was not a
+         * no-op: a whole cell at a whole ratio is untouched, which is why it looked right in a
+         * full-size landscape browser and wrong in mobile portrait, where a consumer divides an
+         * available width by a cell count and gets a fraction.
+         *
+         * So the snap is the caller's to ask for. `deviceSnappedCellSize` is exported; a caller that
+         * wants whole-pixel strokes snaps once and uses that one number to measure, to lay out and to
+         * draw, where the measurement and the picture agree by construction.
+         *
+         * **What this gives up** is that a fractional cell draws strokes of two widths again for a
+         * caller that does not opt in. **What would make it wrong** is a measurement that could snap
+         * on the caller's behalf, which would need the viewport `textWidthPx` is not handed.
+         */
+        setFloat(gl, this.uniforms['uCellSize'], style.cellSize);
         // Far enough that a whole line barely converges, near enough that a rotating character
         // reads as turning rather than shearing.
         setFloat(gl, this.uniforms['uDepth'], Math.max(viewportWidth, 600) * 1.4);

package/package.json

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

package/src/index.ts

@@ -933,7 +933,17 @@ export { FlockRenderer } from './render/flockRenderer.ts';
  * the same shape scatter, plumes, particles, flocks and bolts already have. The measuring
  * helpers were statics on the class and are free functions now, because neither needs a device.
  */
-export { DEFAULT_TEXT_STYLE, textHeightPx, textWidthPx } from './render/textLayout.ts';
+export {
+  DEFAULT_TEXT_STYLE,
+  /*
+   * Exported so a caller can ask for whole-pixel strokes, which the engine used to impose. See
+   * the note at the cell upload in `render/textRenderer.ts`: snap once, then measure, lay out
+   * and draw with that one number.
+   */
+  deviceSnappedCellSize,
+  textHeightPx,
+  textWidthPx,
+} from './render/textLayout.ts';
 export type { TextStyle } from './render/textLayout.ts';
 export {
   GLYPH_HEIGHT,

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

@@ -150,7 +150,7 @@ import {
   type GpuTextCube,
 } from './textPass.ts';
 import type { TextStyle } from '../../textLayout.ts';
-import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.ts';
+import { deviceSnappedOrigin } from '../../textLayout.ts';
 import { GpuSurfaceTexture } from './surfaceTexturePass.ts';
 import {
   createSdfTextBindGroup,
@@ -3185,13 +3185,9 @@ export class WebGPURenderer implements RendererApi {
       deviceSnappedOrigin(originX, viewportWidth, this.surface.canvas.width),
       deviceSnappedOrigin(originY, viewportHeight, this.surface.canvas.height),
     ]);
-    /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
-       decision is shared with WebGL2; only this binding is per-backend. See `textLayout.ts`. */
-    v.writeFloat(
-      vertexSlot,
-      at('uCellSize'),
-      deviceSnappedCellSize(style.cellSize, viewportWidth, this.surface.canvas.width),
-    );
+    /* The cell the caller asked for, drawn faithfully. See `textRenderer.ts` for why the snap
+       this used to impose is the caller's to ask for. */
+    v.writeFloat(vertexSlot, at('uCellSize'), style.cellSize);
     /* Far enough that a whole line barely converges, near enough that a turn reads as a turn. */
     v.writeFloat(vertexSlot, at('uDepth'), Math.max(viewportWidth, 600) * 1.4);
     v.writeFloat(vertexSlot, at('uReveal'), style.reveal);

package/src/render/textRenderer.ts

@@ -1,11 +1,5 @@
 import type { TextStyle } from './textLayout.ts';
-import {
-  MAX_CELLS,
-  TEXT_CUBE,
-  TextLayout,
-  deviceSnappedCellSize,
-  deviceSnappedOrigin,
-} from './textLayout.ts';
+import { MAX_CELLS, TEXT_CUBE, TextLayout, deviceSnappedOrigin } from './textLayout.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
 import { TEXT_FRAG, TEXT_VERT } from './shaders/text.ts';
 
@@ -129,13 +123,28 @@ export class TextRenderer {
       deviceSnappedOrigin(originX, viewportWidth, gl.drawingBufferWidth),
       deviceSnappedOrigin(originY, viewportHeight, gl.drawingBufferHeight),
     );
-    /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
-       decision is shared with WebGPU; only this binding is per-backend. See `textLayout.ts`. */
-    setFloat(
-      gl,
-      this.uniforms['uCellSize'],
-      deviceSnappedCellSize(style.cellSize, viewportWidth, gl.drawingBufferWidth),
-    );
+    /*
+     * **The cell the caller asked for, drawn faithfully.**
+     *
+     * 4.1.4 snapped this down to whole device pixels here, so a 5x7 face could not draw strokes
+     * of two different widths. That defect is real and the snap is the right cure for it, but
+     * imposing it was wrong: `textWidthPx` is the only measurement a consumer has, it takes no
+     * viewport and so cannot know the device ratio, and every consumer went on laying out against
+     * the cell it asked for while this drew a smaller one. A centred line, a right-aligned column
+     * and a line fitted to a box all broke at once, silently, and only where the snap was not a
+     * no-op: a whole cell at a whole ratio is untouched, which is why it looked right in a
+     * full-size landscape browser and wrong in mobile portrait, where a consumer divides an
+     * available width by a cell count and gets a fraction.
+     *
+     * So the snap is the caller's to ask for. `deviceSnappedCellSize` is exported; a caller that
+     * wants whole-pixel strokes snaps once and uses that one number to measure, to lay out and to
+     * draw, where the measurement and the picture agree by construction.
+     *
+     * **What this gives up** is that a fractional cell draws strokes of two widths again for a
+     * caller that does not opt in. **What would make it wrong** is a measurement that could snap
+     * on the caller's behalf, which would need the viewport `textWidthPx` is not handed.
+     */
+    setFloat(gl, this.uniforms['uCellSize'], style.cellSize);
     // Far enough that a whole line barely converges, near enough that a rotating character
     // reads as turning rather than shearing.
     setFloat(gl, this.uniforms['uDepth'], Math.max(viewportWidth, 600) * 1.4);