@driftengine/core 4.2.1 → 4.3.0

package/CHANGELOG.json

@@ -1,4 +1,15 @@
 [
+ {
+  "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",

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.1",
+  "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.1",
-    "@driftengine/physics": "4.2.1",
+    "@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.1",
-    "@driftengine/network": "4.2.1",
-    "@driftengine/texture": "4.2.1"
+    "@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);
   }