vgpu-render 0.1.0 → 0.2.0

package/dist/{frame-recorder.js → frame-draw-list.js}

@@ -1,14 +1,16 @@
 import { sampleCurve } from "./curve.js";
-import { FrameRecorder2D } from "./frame-recorder-2d.js";
+import { FrameDrawList2D } from "./frame-draw-list-2d.js";
 import { gridLines } from "./geometry-generators.js";
 import { DEFAULT_FONT_FAMILY } from "./text-font.js";
-import { resolveTextAnchor, DEFAULT_LINE_HEIGHT_SCALE } from "./text-layout.js";
+import { resolveTextAnchor, DEFAULT_LINE_HEIGHT_SCALE, DEFAULT_FONT_WEIGHT, MAX_FONT_WEIGHT, MIN_FONT_WEIGHT, TEXT_FONT_STYLES, TEXT_FONT_WIDTHS, } from "./text-layout.js";
 export const DEFAULT_COLOR = [1, 1, 1, 1];
 export const DEFAULT_LAYER = 1;
 /** Default block font size in pixels; the world spaces scale it by `DEFAULT_TEXT_PIXEL_SIZE`. */
 export const DEFAULT_TEXT_SIZE = 16;
 /** Default world units per font pixel, i.e. a 0.32 world-unit glyph at the default size. */
 export const DEFAULT_TEXT_PIXEL_SIZE = 0.02;
+/** `world-plane` blocks face +Z until a rotation lays them down, like a reference `Label3D`. */
+export const DEFAULT_TEXT_ROTATION = [0, 0, 0];
 /** reference `LineHeight` default is `RelativeToFont(1.2)`. */
 export const DEFAULT_LINE_HEIGHT_RATIO = DEFAULT_LINE_HEIGHT_SCALE;
 function finite(value, name) {
@@ -79,6 +81,24 @@ function textSpaceValue(value, name) {
     }
     return value;
 }
+function fontWeightValue(value, name) {
+    if (!Number.isFinite(value) || value < MIN_FONT_WEIGHT || value > MAX_FONT_WEIGHT) {
+        throw new RangeError(`${name} must be between ${MIN_FONT_WEIGHT} and ${MAX_FONT_WEIGHT}`);
+    }
+    return value;
+}
+function textFontStyleValue(value, name) {
+    if (!TEXT_FONT_STYLES.includes(value)) {
+        throw new RangeError(`${name} must be one of ${TEXT_FONT_STYLES.join(", ")}`);
+    }
+    return value;
+}
+function textFontWidthValue(value, name) {
+    if (!TEXT_FONT_WIDTHS.includes(value)) {
+        throw new RangeError(`${name} must be one of ${TEXT_FONT_WIDTHS.join(", ")}`);
+    }
+    return value;
+}
 function textBounds(value, name) {
     if (value.length !== 2)
         throw new RangeError(`${name} must contain two values`);
@@ -90,7 +110,7 @@ function textBounds(value, name) {
  * Folds the block defaults into every span so the renderer resolves a style once per span and
  * never has to guess what an omitted field meant.
  */
-function resolveTextSpans(text, options, defaults, baseFontSize, baseFontFamily) {
+function resolveTextSpans(text, options, defaults, baseFontSize, baseFontFamily, baseWeight, baseStyle, baseWidth) {
     const input = typeof text === "string" ? [{ text }] : text;
     const baseColor = color(options.color ?? defaults.color);
     return input.map((span) => {
@@ -102,11 +122,15 @@ function resolveTextSpans(text, options, defaults, baseFontSize, baseFontFamily)
             color: span.color === undefined ? baseColor : color(span.color),
             fontSize,
             fontFamily: span.fontFamily ?? baseFontFamily,
+            // A span overrides the block's face one axis at a time, like a nested `TextFont` component.
+            weight: span.weight === undefined ? baseWeight : fontWeightValue(span.weight, "span weight"),
+            style: span.style === undefined ? baseStyle : textFontStyleValue(span.style, "span style"),
+            width: span.width === undefined ? baseWidth : textFontWidthValue(span.width, "span width"),
         };
     });
 }
 /** Validates and resolves style defaults so invalid values fail at construction time. */
-export function resolveFrameRecorderDefaults(defaults = {}) {
+export function resolveFrameDrawListDefaults(defaults = {}) {
     const point = defaults.point ?? {};
     const line = defaults.line ?? {};
     const text = defaults.text ?? {};
@@ -168,6 +192,9 @@ export function resolveFrameRecorderDefaults(defaults = {}) {
             fontSize: textSize,
             pixelSize: textPixelSize,
             fontFamily: text.fontFamily,
+            weight: text.weight === undefined ? undefined : fontWeightValue(text.weight, "default text weight"),
+            style: text.style === undefined ? undefined : textFontStyleValue(text.style, "default text style"),
+            width: text.width === undefined ? undefined : textFontWidthValue(text.width, "default text width"),
             lineHeight: textLineHeight,
             lineHeightScale: textLineHeightScale,
             letterSpacing: text.letterSpacing === undefined ? undefined : finite(text.letterSpacing, "default text letterSpacing"),
@@ -175,13 +202,19 @@ export function resolveFrameRecorderDefaults(defaults = {}) {
             lineBreak: text.lineBreak === undefined ? undefined : textLineBreakValue(text.lineBreak, "default text lineBreak"),
             anchor: textAnchor,
             space: text.space === undefined ? undefined : textSpaceValue(text.space, "default text space"),
+            rotation: text.rotation === undefined ? undefined : vec3(text.rotation, "default text rotation"),
             source: text.source,
             depthTest: text.depthTest,
             layer: text.layer === undefined ? undefined : layerValue(text.layer, "default text layer"),
         },
     };
 }
-export class FrameRecorder {
+/**
+ * One frame's draw list: records primitives, then hands them to `GpuDebugDraw3D` as
+ * `FrameCommand[]`. This is the `ImDrawList` / `GizmoBuffer` layer; GPU command encoding
+ * happens later in the renderer.
+ */
+export class FrameDrawList {
     #points = [];
     #lines = [];
     #joints = [];
@@ -191,10 +224,10 @@ export class FrameRecorder {
     #d2;
     #sealed = false;
     constructor(defaults = {}) {
-        this.#defaults = resolveFrameRecorderDefaults(defaults);
-        // The 2D layer shares this recorder's resolved point/line styles, so a style set on
+        this.#defaults = resolveFrameDrawListDefaults(defaults);
+        // The 2D layer shares this drawList's resolved point/line styles, so a style set on
         // `DebugDraw3D` cannot apply to one layer and not the other.
-        this.#d2 = new FrameRecorder2D({ point: this.#defaults.point, line: this.#defaults.line }, () => this.assertOpen());
+        this.#d2 = new FrameDrawList2D({ point: this.#defaults.point, line: this.#defaults.line }, () => this.assertOpen());
     }
     /**
      * The 2D layer: `Vec2` primitives on the reference-style `Camera2d` spaces described in
@@ -431,10 +464,14 @@ export class FrameRecorder {
             throw new RangeError("lineHeight must be greater than zero");
         const letterSpacing = finite(options.letterSpacing ?? defaults.letterSpacing ?? 0, "letterSpacing");
         const fontFamily = options.fontFamily ?? defaults.fontFamily ?? DEFAULT_FONT_FAMILY;
+        const weight = fontWeightValue(options.weight ?? defaults.weight ?? DEFAULT_FONT_WEIGHT, "weight");
+        const style = textFontStyleValue(options.style ?? defaults.style ?? "normal", "style");
+        const width = textFontWidthValue(options.width ?? defaults.width ?? "normal", "width");
         const justify = options.justify ?? defaults.justify ?? "left";
         const lineBreak = options.lineBreak ?? defaults.lineBreak ?? "word";
         const anchor = options.anchor ?? defaults.anchor ?? "center";
         const space = options.space ?? defaults.space ?? "world-plane";
+        const rotation = vec3(options.rotation ?? defaults.rotation ?? DEFAULT_TEXT_ROTATION, "rotation");
         const source = options.source ?? defaults.source;
         const bounds = options.bounds;
         if (bounds !== undefined)
@@ -451,13 +488,16 @@ export class FrameRecorder {
         this.#texts.push({
             kind: "text",
             position: vec3(position, "position"),
-            spans: resolveTextSpans(text, options, defaults, fontSize, fontFamily),
+            spans: resolveTextSpans(text, options, defaults, fontSize, fontFamily, weight, style, width),
             color: color(options.color ?? defaults.color),
             outlineWidth,
             outlineColor,
             fontSize,
             pixelSize,
             fontFamily,
+            weight,
+            style,
+            width,
             lineHeight,
             ...(lineHeightScale === undefined ? {} : { lineHeightScale }),
             letterSpacing,
@@ -465,6 +505,7 @@ export class FrameRecorder {
             lineBreak,
             anchor,
             space,
+            rotation,
             ...(source === undefined ? {} : { source }),
             depthTest: options.depthTest ?? defaults.depthTest ?? true,
             layer: layer(options.layer ?? defaults.layer),
@@ -510,6 +551,6 @@ export class FrameRecorder {
     }
     assertOpen() {
         if (this.#sealed)
-            throw new Error("frame recorder is sealed");
+            throw new Error("frame drawList is sealed");
     }
 }

package/dist/geometry-generators.d.ts

@@ -1,5 +1,5 @@
-import type { Vec3 } from "./frame-recorder.js";
-import { type CircleBasis } from "./layout-3d.js";
+import type { Vec3 } from "./frame-draw-list.js";
+import { type CircleBasis } from "./vector-math.js";
 export type Triangle = readonly [Vec3, Vec3, Vec3];
 export type Segment = readonly [Vec3, Vec3];
 export type MeshData = {

package/dist/geometry-generators.js

@@ -1,4 +1,4 @@
-import { crossVector, normalizeVector, rotateAroundAxis } from "./layout-3d.js";
+import { crossVector, normalizeVector, rotateAroundAxis } from "./vector-math.js";
 const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
 const scale = (a, n) => [a[0] * n, a[1] * n, a[2] * n];
 const rotate = (p, rotation) => {

package/dist/gpu-debug-draw-2d.d.ts

@@ -14,7 +14,7 @@
  */
 import { type FrameComputePass, type FramePass, type Gpu } from "vgpu";
 import { type Camera2D } from "./camera-2d.js";
-import type { FrameCommand2D } from "./frame-recorder-2d.js";
+import type { FrameCommand2D } from "./frame-draw-list-2d.js";
 export type GpuDebugDraw2DOptions = {
     /**
      * WGSL for the shared primitives, generated by `GpuDebugDraw3D` so the two layers cannot drift

package/dist/gpu-debug-draw-3d.d.ts

@@ -1,6 +1,6 @@
 import { type Frame, type FramePass, type Gpu } from "vgpu";
 import type { Camera2D } from "./camera-2d.js";
-import type { FrameCommand } from "./frame-recorder.js";
+import type { FrameCommand } from "./frame-draw-list.js";
 import { type GpuText3DOptions } from "./gpu-text-3d.js";
 /**
  * Named glyph sources. A text command picks one by name through `TextOptions.source`; commands that

package/dist/gpu-debug-draw-3d.js

@@ -710,8 +710,10 @@ export class GpuDebugDraw3D {
         this.#viewProjection = camera.viewProjection;
         this.#view = camera.view;
         // Every renderer that exists is prepared, even with an empty list: that is what drops the
-        // previous frame's glyphs instead of leaving them on screen.
-        if (textCommands.length > 0 || this.#texts.size > 0) {
+        // previous frame's glyphs instead of leaving them on screen. A caller that never configured a
+        // text source asked for geometry only, so the example scenes' own labels are drawn by nobody
+        // rather than failing the frame — a named source that is missing still throws.
+        if (this.#textOptions !== undefined && (textCommands.length > 0 || this.#texts.size > 0)) {
             this.#prepareText(textCommands, camera);
         }
         // Always prepared, even with an empty list: that is what drops the previous frame's 2D

package/dist/gpu-text-3d.d.ts

@@ -32,7 +32,7 @@
  * glyph's translucent ink box from clipping the glyphs drawn after it.
  */
 import { type FrameComputePass, type FramePass, type Gpu } from "vgpu";
-import type { TextCommand } from "./frame-recorder.js";
+import type { TextCommand } from "./frame-draw-list.js";
 import { type TextMeasurer } from "./text-layout.js";
 import type { GlyphRasterizer } from "./text-font.js";
 /** Both halves of a font: metrics for layout and pixels for the atlas. */

package/dist/gpu-text-3d.js

@@ -205,7 +205,12 @@ struct Out { @builtin(position) clip: vec4f, @location(0) uv: vec2f, @location(1
       let up = vec3f(camera.view[0][1], camera.view[1][1], camera.view[2][1]);
       worldPosition = input.origin + right * local.x - up * local.y;
     } else {
-      worldPosition = input.origin + vec3f(local.x, -local.y, 0.0);
+      // The instance world matrix carries the block's own plane basis: column 0 is the reading
+      // direction, column 1 the layout's down. Label3D.rotation lands on that basis, so the default
+      // identity keeps the plane facing +Z.
+      let axisX = input.world0.xyz;
+      let axisY = input.world1.xyz;
+      worldPosition = input.origin + axisX * local.x - axisY * local.y;
     }
     clip = camera.viewProjection * vec4f(worldPosition, 1.0);
   }
@@ -233,6 +238,41 @@ fn atlasTexelsPerPixel(uv: vec2f) -> f32 {
 
 ${fragment}`;
 }
+/** `world-plane` blocks keep facing +Z until their own rotation lays them down. */
+const IDENTITY_WORLD = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+/**
+ * The instance world matrix of a `world-plane` block, from the reference `Label3D.rotation` Euler
+ * order (Y, then X, then Z). Column 0 is the reading direction and column 1 the layout's down, so a
+ * `[-PI/2, 0, 0]` block lies flat on the XZ plane and reads from above.
+ *
+ * The basis travels in the instance world matrix rather than in two extra instance attributes: the
+ * text pipeline already uses the device's full vertex attribute budget.
+ */
+function textPlaneWorld(rotation) {
+    const [pitch, yaw, roll] = rotation;
+    if (pitch === 0 && yaw === 0 && roll === 0)
+        return IDENTITY_WORLD;
+    const cosRoll = Math.cos(roll);
+    const sinRoll = Math.sin(roll);
+    const cosPitch = Math.cos(pitch);
+    const sinPitch = Math.sin(pitch);
+    const cosYaw = Math.cos(yaw);
+    const sinYaw = Math.sin(yaw);
+    // Rz, then Rx, then Ry: the vector order that matches reference YXZ Euler convention.
+    let x = [cosRoll, sinRoll, 0];
+    let y = [-sinRoll, cosRoll, 0];
+    x = [x[0], x[1] * cosPitch - x[2] * sinPitch, x[1] * sinPitch + x[2] * cosPitch];
+    y = [y[0], y[1] * cosPitch - y[2] * sinPitch, y[1] * sinPitch + y[2] * cosPitch];
+    x = [x[0] * cosYaw + x[2] * sinYaw, x[1], -x[0] * sinYaw + x[2] * cosYaw];
+    y = [y[0] * cosYaw + y[2] * sinYaw, y[1], -y[0] * sinYaw + y[2] * cosYaw];
+    const z = [x[1] * y[2] - x[2] * y[1], x[2] * y[0] - x[0] * y[2], x[0] * y[1] - x[1] * y[0]];
+    return new Float32Array([
+        x[0], x[1], x[2], 0,
+        y[0], y[1], y[2], 0,
+        z[0], z[1], z[2], 0,
+        0, 0, 0, 1,
+    ]);
+}
 export class GpuText3D {
     #gpu;
     #font;
@@ -349,6 +389,9 @@ export class GpuText3D {
                 color: command.color,
                 fontSize: command.fontSize,
                 fontFamily: command.fontFamily,
+                weight: command.weight,
+                style: command.style,
+                width: command.width,
                 // A relative line height stays relative all the way to layout, where each line resolves it
                 // against that line's own largest span; only an explicit one is absolute.
                 ...(command.lineHeightScale === undefined
@@ -361,6 +404,7 @@ export class GpuText3D {
                 anchor: resolveTextAnchor(command.anchor),
             }, this.#font);
             const space = command.space === "world-billboard" ? SPACE_WORLD_BILLBOARD : command.space === "screen" ? SPACE_SCREEN : SPACE_WORLD_PLANE;
+            const planeWorld = space === SPACE_WORLD_PLANE ? textPlaneWorld(command.rotation) : IDENTITY_WORLD;
             // Screen text never takes part in depth testing, whatever the command asked for.
             const flags = space | (command.depthTest && space !== SPACE_SCREEN ? 0 : FLAG_NO_DEPTH);
             // The quad's size comes from the layout, not from the atlas. A distance field can be drawn at
@@ -382,7 +426,7 @@ export class GpuText3D {
                 const rasterScale = dynamicRaster
                     ? rasterScaleFor(quantizeRasterPx(Math.max(glyph.fontSize * screenPxPerFontPx, glyph.fontSize * rasterFloor)), glyph.fontSize)
                     : undefined;
-                const entry = this.#atlas.glyph(glyph.character, glyph.fontFamily, glyph.fontSize, rasterScale);
+                const entry = this.#atlas.glyph(glyph.character, glyph.face, glyph.fontSize, rasterScale);
                 if (entry === undefined)
                     continue;
                 const id = this.#ids[index] ?? this.#addInstance(index);
@@ -398,6 +442,9 @@ export class GpuText3D {
                     outlineWidth: command.outlineWidth,
                     outlineColor: command.outlineColor,
                 });
+                // The matrix always reflects this block's own plane, because instances are reused across
+                // blocks and a stale basis would tilt a block that asked for none.
+                this.#glyphs.setWorld(id, planeWorld);
                 index++;
             }
         }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./debug-draw-3d.js";
 export * from "./camera-2d.js";
-export * from "./frame-recorder.js";
-export * from "./frame-recorder-2d.js";
+export * from "./frame-draw-list.js";
+export * from "./frame-draw-list-2d.js";
 export * from "./color-space.js";
 export * from "./curve.js";
 export * from "./geometry-generators.js";
@@ -11,7 +11,6 @@ export * from "./gpu-text-3d.js";
 export * from "./infinite-grid-3d.js";
 export * from "./infinite-grid-2d.js";
 export * from "./mesh-batch-3d.js";
-export * from "./scenes-3d.js";
 export * from "./text-atlas.js";
 export * from "./text-font.js";
 export * from "./text-layout.js";
@@ -19,3 +18,4 @@ export * from "./text-sdf.js";
 export * from "./text-msdf.js";
 export * from "./text-msdf-font.js";
 export * from "./text-msdf-baked.js";
+export type { CircleBasis } from "./vector-math.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export * from "./debug-draw-3d.js";
 export * from "./camera-2d.js";
-export * from "./frame-recorder.js";
-export * from "./frame-recorder-2d.js";
+export * from "./frame-draw-list.js";
+export * from "./frame-draw-list-2d.js";
 export * from "./color-space.js";
 export * from "./curve.js";
 export * from "./geometry-generators.js";
@@ -11,7 +11,6 @@ export * from "./gpu-text-3d.js";
 export * from "./infinite-grid-3d.js";
 export * from "./infinite-grid-2d.js";
 export * from "./mesh-batch-3d.js";
-export * from "./scenes-3d.js";
 export * from "./text-atlas.js";
 export * from "./text-font.js";
 export * from "./text-layout.js";

package/dist/mesh-batch-3d.d.ts

@@ -1,6 +1,6 @@
 import { type FramePass, type Gpu } from "vgpu";
 import type { MeshData } from "./geometry-generators.js";
-import type { Color } from "./frame-recorder.js";
+import type { Color } from "./frame-draw-list.js";
 export declare class MeshBatch3D {
     #private;
     constructor(gpu: Gpu, mesh: MeshData, color: Color, solid: boolean);

package/dist/shape2d-shader.js

@@ -213,8 +213,9 @@ fn shape_distance(shape: u32, p: vec2f, size: vec2f, vertexB: vec2f, vertexC: ve
     case SHAPE_ROUNDED_RECT: { return sd_rounded_box(p, size, cornerRadius); }
     case SHAPE_CIRCLE: { return sd_ellipse(p, size); }
     case SHAPE_ELLIPSE: { return sd_ellipse(p, size); }
-    // An arc has no interior: its distance is unsigned, so filling one yields a hairline.
-    case SHAPE_ARC: { return abs(length(p) - size.x); }
+    // An arc has no interior: the ring alone ignores the angles, so it is clipped to the swept
+    // wedge. Filling one still yields a hairline, because the distance stays unsigned.
+    case SHAPE_ARC: { return max(abs(length(p) - size.x), sd_sector(p, size.x, startAngle, sweep)); }
     case SHAPE_ANNULUS: { return sd_annulus(p, size.y, size.x); }
     case SHAPE_CAPSULE: { return sd_capsule(p, size.y, size.x); }
     case SHAPE_POLYGON: { return sd_regular_polygon(p, size.x, sides); }

package/dist/text-atlas.d.ts

@@ -9,14 +9,16 @@
  * 2 px of padding; both choices are kept here, since the padding is what keeps linear
  * sampling from bleeding between neighbours.
  *
- * Unlike reference the atlas is not keyed per font size: the cache key carries the family and size
- * instead, so one page set serves every size a frame happens to use. Glyphs are rasterised at
- * `rasterScale` times their font size, which decouples the atlas' detail from the logical layout
+ * Unlike reference the atlas is not keyed per font size: the cache key carries the face and size
+ * instead, so one page set serves every size a frame happens to use. The face part comes from
+ * `GlyphRasterizer.faceKey`, which is how a source states which of the axes it can actually vary.
+ * Glyphs are rasterised at `rasterScale` times their font size, which decouples the atlas' detail from the logical layout
  * size — the same separation as resampling a font at a higher point size before scaling it down.
  * Pages grow on demand until `maxPages` is reached — the GPU renderer pins that at one page so a
  * single draw call covers the whole atlas — and a `revision` counter tells the renderer which of
  * them changed since the last upload.
  */
+import { type FontFace } from "./text-layout.js";
 import type { GlyphEncoding, GlyphRasterizer } from "./text-font.js";
 /** Page size and inter-glyph padding, matching reference minimum atlas and `GLYPH_ATLAS_PADDING`. */
 export declare const DEFAULT_ATLAS_SIZE = 512;
@@ -111,7 +113,7 @@ export declare class GlyphAtlas {
      * exactly as it did. The renderer passes the size the block covers on screen instead, so the entry
      * that comes back is rasterised for the rung that face asked for.
      */
-    glyph(character: string, fontFamily: string, fontSize: number, rasterScale?: number): AtlasGlyph | undefined;
+    glyph(character: string, face: FontFace, fontSize: number, rasterScale?: number): AtlasGlyph | undefined;
     /** Drops every cached glyph. The next frame re-rasterises whatever it still draws. */
     clear(): void;
 }

package/dist/text-atlas.js

@@ -9,14 +9,16 @@
  * 2 px of padding; both choices are kept here, since the padding is what keeps linear
  * sampling from bleeding between neighbours.
  *
- * Unlike reference the atlas is not keyed per font size: the cache key carries the family and size
- * instead, so one page set serves every size a frame happens to use. Glyphs are rasterised at
- * `rasterScale` times their font size, which decouples the atlas' detail from the logical layout
+ * Unlike reference the atlas is not keyed per font size: the cache key carries the face and size
+ * instead, so one page set serves every size a frame happens to use. The face part comes from
+ * `GlyphRasterizer.faceKey`, which is how a source states which of the axes it can actually vary.
+ * Glyphs are rasterised at `rasterScale` times their font size, which decouples the atlas' detail from the logical layout
  * size — the same separation as resampling a font at a higher point size before scaling it down.
  * Pages grow on demand until `maxPages` is reached — the GPU renderer pins that at one page so a
  * single draw call covers the whole atlas — and a `revision` counter tells the renderer which of
  * them changed since the last upload.
  */
+import { fontFaceKey } from "./text-layout.js";
 /** Page size and inter-glyph padding, matching reference minimum atlas and `GLYPH_ATLAS_PADDING`. */
 export const DEFAULT_ATLAS_SIZE = 512;
 export const DEFAULT_ATLAS_PADDING = 2;
@@ -100,13 +102,14 @@ export class GlyphAtlas {
      * exactly as it did. The renderer passes the size the block covers on screen instead, so the entry
      * that comes back is rasterised for the rung that face asked for.
      */
-    glyph(character, fontFamily, fontSize, rasterScale) {
+    glyph(character, face, fontSize, rasterScale) {
         const scale = rasterScale !== undefined && rasterScale > 0 ? rasterScale : this.rasterScale;
         // The key carries the size the glyph was *rasterised* at rather than the layout font size: two
         // font sizes that land on the same rung share one rasterisation, which is what keeps a block
         // whose size changes every frame from rasterising the same character over and over.
         const rasterPx = Math.max(1, Math.round(fontSize * scale));
-        const key = `${fontFamily}|${rasterPx}|${character}`;
+        const faceKey = this.#rasterizer.faceKey?.(face) ?? fontFaceKey(face);
+        const key = `${faceKey}|${rasterPx}|${character}`;
         const cached = this.#glyphs.get(key);
         if (cached !== undefined) {
             cached.lastFrame = this.#frame;
@@ -114,7 +117,7 @@ export class GlyphAtlas {
         }
         if (this.#missing.has(key))
             return undefined;
-        const rasterized = this.#rasterizer.rasterize(character, fontFamily, rasterPx);
+        const rasterized = this.#rasterizer.rasterize(character, face, rasterPx);
         if (rasterized === undefined) {
             this.#missing.add(key);
             return undefined;

package/dist/text-font.d.ts

@@ -13,7 +13,7 @@
  * Everything here is browser-only. Layout depends on the `TextMeasurer` interface alone, so
  * unit tests keep running in plain Node, and the GPU tests inject their own rasteriser.
  */
-import type { GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
+import { type FontFace, type GlyphMetrics, type TextMeasurer, type VerticalMetrics } from "./text-layout.js";
 /**
  * How a glyph is stored in the atlas, and therefore how the shader has to decode it.
  *
@@ -36,6 +36,23 @@ export type GlyphEncoding = "bitmap" | "sdf" | "msdf";
 export declare const DEFAULT_FONT_FAMILY = "vgpu-render-fira-mono";
 /** Decodes a base64 payload into bytes. Shared by the inlined font and the prebaked atlas. */
 export declare function decodeBase64Bytes(base64: string): Uint8Array<ArrayBuffer>;
+/** One inlined face of a multi-weight family: the weight it was built at, plus its WOFF2 bytes. */
+export type EmbeddedFontFace = {
+    readonly weight: number;
+    /** Base64 WOFF2, so the payload stays plain text and every toolchain can read it. */
+    readonly woff2Base64: string;
+};
+/**
+ * Registers a family whose weights are separate faces, each carrying its own `weight` descriptor.
+ *
+ * This is the only way to get more than one drawn weight out of Canvas2D: the font shorthand carries a
+ * single synthesised bold step, and `font-variation-settings` does not exist there, but the browser
+ * does select a face by the weight it was registered with. Registering the same family once per
+ * weight therefore turns `weight: 700` into a real bold face instead of an emboldened regular one.
+ *
+ * Idempotent per family, like `loadDefaultFont`, and browser-only.
+ */
+export declare function loadFontFaces(family: string, faces: readonly EmbeddedFontFace[]): Promise<void>;
 /** Decodes the inlined WOFF2 bytes of the bundled font, which is what `FontFace` takes. */
 export declare function decodeEmbeddedFont(): Uint8Array<ArrayBuffer>;
 /**
@@ -102,6 +119,15 @@ export interface GlyphRasterizer {
      * were rasterised once at a fixed size, so the renderer leaves it on `rasterScale` instead.
      */
     readonly dynamicRaster?: boolean;
+    /**
+     * Cache-key part for one face. The atlas keys glyphs by this plus the raster size, so a source that
+     * cannot change a face' axes reports just the parts it honours.
+     *
+     * The default keys on every axis (`fontFaceKey`). A source holding one fixed face — a prebaked page
+     * or a single parsed `opentype.js` buffer — overrides it so a weight the source cannot rasterise
+     * does not multiply identical atlas entries.
+     */
+    readonly faceKey?: (face: FontFace) => string;
     /**
      * Returns `undefined` for characters with no ink, such as whitespace.
      *
@@ -109,10 +135,25 @@ export interface GlyphRasterizer {
      * size: the atlas asks for the size the glyph will cover on screen, so the same character stays
      * sharp at any font size while still being rasterised once per size rung.
      */
-    rasterize(character: string, fontFamily: string, rasterSize: number): RasterizedGlyph | undefined;
-    /** Vertical metrics for a `fontSize`-sized face of `fontFamily`. */
-    verticalMetrics(fontFamily: string, fontSize: number): VerticalMetrics;
+    rasterize(character: string, face: FontFace, rasterSize: number): RasterizedGlyph | undefined;
+    /** Vertical metrics for a `fontSize`-sized instance of `face`. */
+    verticalMetrics(face: FontFace, fontSize: number): VerticalMetrics;
 }
+/**
+ * The CSS font shorthand that selects `face` at `fontSize`.
+ *
+ * Order follows the shorthand's grammar — style, weight, stretch, size, family — because Canvas2D
+ * parses the value as one. Two of the axes are conditional:
+ *
+ * - `font-stretch` keywords are only kept by the parser when the face has a `wdth` axis. A static
+ *   face drops the keyword and draws every stop identically, which is why the bundled subset cannot
+ *   show a `FontWidth` difference at all.
+ * - `italic` is the only slant Canvas2D keeps; `oblique <angle>` reads back as plain `italic`.
+ *
+ * A weight the loaded face does not carry is synthesised by the browser (one emboldened step, which
+ * keeps the advance), so `weight` at least changes what is drawn for the bundled static face.
+ */
+export declare function canvasFontString(face: FontFace, fontSize: number): string;
 /** Encodings Canvas2D coverage can produce directly. `msdf` needs outlines, not a mask. */
 export type CoverageEncoding = Exclude<GlyphEncoding, "msdf">;
 /**
@@ -141,9 +182,9 @@ export declare class CanvasGlyphRasterizer implements GlyphRasterizer, TextMeasu
         rasterScale?: number;
         dynamicRaster?: boolean;
     });
-    verticalMetrics(fontFamily: string, fontSize: number): VerticalMetrics;
-    glyphMetrics(character: string, fontFamily: string, fontSize: number): GlyphMetrics;
-    rasterize(character: string, fontFamily: string, rasterSize: number): RasterizedGlyph | undefined;
+    verticalMetrics(face: FontFace, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, face: FontFace, fontSize: number): GlyphMetrics;
+    rasterize(character: string, face: FontFace, rasterSize: number): RasterizedGlyph | undefined;
 }
 /** Packs Canvas2D coverage into the RGBA layout the chosen encoding expects. */
 export declare function encodeCoverage(coverage: Uint8Array, width: number, height: number, encoding: CoverageEncoding, range: number): Uint8Array;