vgpu-render 0.1.0 → 0.3.0

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

@@ -1,6 +1,6 @@
 import { type Curve3D, type CurveTransform } from "./curve.js";
-import { FrameRecorder2D, type FrameCommand2D } from "./frame-recorder-2d.js";
-import { type TextAnchor, type TextJustify, type TextLineBreak } from "./text-layout.js";
+import { FrameDrawList2D, type FrameCommand2D } from "./frame-draw-list-2d.js";
+import { type TextAnchor, type TextFontStyle, type TextFontWidth, type TextJustify, type TextLineBreak } from "./text-layout.js";
 export type Vec3 = readonly [number, number, number];
 export type Color = readonly [number, number, number, number];
 export type LayerMask = number;
@@ -114,6 +114,12 @@ export type TextSpanOptions = {
     readonly color?: Color;
     readonly fontSize?: number;
     readonly fontFamily?: string;
+    /** reference `TextFont::weight`, 1 to 1000. Defaults to the block's, then to 400. */
+    readonly weight?: number;
+    /** reference `TextFont::style`, minus `Oblique`: Canvas2D drops the slant angle. */
+    readonly style?: TextFontStyle;
+    /** reference `TextFont::width`, as a `font-stretch` keyword. Inert unless the face has a `wdth` axis. */
+    readonly width?: TextFontWidth;
 };
 export type TextOptions = {
     color?: Color;
@@ -143,6 +149,21 @@ export type TextOptions = {
      */
     pixelSize?: number;
     fontFamily?: string;
+    /**
+     * reference `TextFont::weight`, 1 to 1000, default `400`. A face that does not carry the weight is
+     * emboldened by the browser in one synthesised step, so the advance does not change.
+     */
+    weight?: number;
+    /**
+     * reference `TextFont::style`. `italic` is the only slant Canvas2D honours: its shorthand drops the
+     * angle of `Oblique(a)`, so a synthesised slant is all an oblique could mean here.
+     */
+    style?: TextFontStyle;
+    /**
+     * reference `TextFont::width`, spelled as a `font-stretch` keyword. Canvas2D keeps the keyword only when
+     * the face has a `wdth` axis; the bundled static subset has none, so every stop draws identically.
+     */
+    width?: TextFontWidth;
     /**
      * Absolute line height in pixels, reference `LineHeight::Px`. Exclusive with `lineHeightScale`;
      * omitting both leaves the line height at reference default, `RelativeToFont(1.2)`.
@@ -164,6 +185,12 @@ export type TextOptions = {
     bounds?: readonly [number, number];
     anchor?: TextAnchor;
     space?: TextSpace;
+    /**
+     * Local rotation of a `world-plane` block, in radians, as reference `Label3D.rotation` Euler angles
+     * (applied Y, then X, then Z). The reference `Label3D` labels use `[-PI/2, 0, 0]` to lay the block
+     * flat on the XZ plane, readable from above; the two camera-relative spaces ignore it.
+     */
+    rotation?: readonly [number, number, number];
     /**
      * Which registered glyph source draws this block: its encoding and raster scale. Blocks that name
      * nothing use the first source, so a frame can mix a sharp pass and a cheap pass.
@@ -179,6 +206,9 @@ export type ResolvedTextSpan = {
     readonly color: Color;
     readonly fontSize: number;
     readonly fontFamily: string;
+    readonly weight: number;
+    readonly style: TextFontStyle;
+    readonly width: TextFontWidth;
 };
 export type TextCommand = {
     readonly kind: "text";
@@ -190,6 +220,9 @@ export type TextCommand = {
     readonly fontSize: number;
     readonly pixelSize: number;
     readonly fontFamily: string;
+    readonly weight: number;
+    readonly style: TextFontStyle;
+    readonly width: TextFontWidth;
     /**
      * Resolved line height in pixels: the value a `LineHeight::Px` block asked for, or
      * `1.2 × fontSize` for the default, which `lineHeightScale` then marks as resolved per line.
@@ -207,6 +240,7 @@ export type TextCommand = {
     readonly bounds?: readonly [number, number];
     readonly anchor: TextAnchor;
     readonly space: TextSpace;
+    readonly rotation: readonly [number, number, number];
     readonly source?: string;
     readonly depthTest: boolean;
     readonly layer: LayerMask;
@@ -248,6 +282,12 @@ export type TextDefaults = {
     fontSize?: number;
     pixelSize?: number;
     fontFamily?: string;
+    /** Default reference `TextFont::weight`, 1 to 1000. */
+    weight?: number;
+    /** Default reference `TextFont::style`. */
+    style?: TextFontStyle;
+    /** Default reference `TextFont::width`, as a `font-stretch` keyword. */
+    width?: TextFontWidth;
     /**
      * Absolute line height in pixels, reference `LineHeight::Px`. Omitted means reference default,
      * `RelativeToFont(1.2)`: every line is 1.2 times its own largest span, so a line holding a
@@ -261,11 +301,12 @@ export type TextDefaults = {
     lineBreak?: TextLineBreak;
     anchor?: TextAnchor;
     space?: TextSpace;
+    rotation?: readonly [number, number, number];
     source?: string;
     depthTest?: boolean;
     layer?: LayerMask;
 };
-export type FrameRecorderDefaults = {
+export type FrameDrawListDefaults = {
     point?: PointDefaults;
     line?: LineDefaults;
     text?: TextDefaults;
@@ -276,6 +317,8 @@ export declare const DEFAULT_LAYER = 1;
 export declare const DEFAULT_TEXT_SIZE = 16;
 /** Default world units per font pixel, i.e. a 0.32 world-unit glyph at the default size. */
 export declare const DEFAULT_TEXT_PIXEL_SIZE = 0.02;
+/** `world-plane` blocks face +Z until a rotation lays them down, like a reference `Label3D`. */
+export declare const DEFAULT_TEXT_ROTATION: readonly [number, number, number];
 /** reference `LineHeight` default is `RelativeToFont(1.2)`. */
 export declare const DEFAULT_LINE_HEIGHT_RATIO = 1.2;
 export type ResolvedPointDefaults = {
@@ -301,6 +344,9 @@ export type ResolvedTextDefaults = {
     fontSize: number | undefined;
     pixelSize: number | undefined;
     fontFamily: string | undefined;
+    weight: number | undefined;
+    style: TextFontStyle | undefined;
+    width: TextFontWidth | undefined;
     lineHeight: number | undefined;
     lineHeightScale: number | undefined;
     letterSpacing: number | undefined;
@@ -308,25 +354,31 @@ export type ResolvedTextDefaults = {
     lineBreak: TextLineBreak | undefined;
     anchor: TextAnchor | undefined;
     space: TextSpace | undefined;
+    rotation: readonly [number, number, number] | undefined;
     source: string | undefined;
     depthTest: boolean | undefined;
     layer: LayerMask | undefined;
 };
-export type ResolvedFrameRecorderDefaults = {
+export type ResolvedFrameDrawListDefaults = {
     point: ResolvedPointDefaults;
     line: ResolvedLineDefaults;
     text: ResolvedTextDefaults;
 };
 /** Validates and resolves style defaults so invalid values fail at construction time. */
-export declare function resolveFrameRecorderDefaults(defaults?: FrameRecorderDefaults): ResolvedFrameRecorderDefaults;
-export declare class FrameRecorder {
+export declare function resolveFrameDrawListDefaults(defaults?: FrameDrawListDefaults): ResolvedFrameDrawListDefaults;
+/**
+ * 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 declare class FrameDrawList {
     #private;
-    constructor(defaults?: FrameRecorderDefaults);
+    constructor(defaults?: FrameDrawListDefaults);
     /**
      * The 2D layer: `Vec2` primitives on the reference-style `Camera2d` spaces described in
      * `camera-2d.ts`. Drawing here records into the same frame and layer mask as the 3D methods.
      */
-    get d2(): FrameRecorder2D;
+    get d2(): FrameDrawList2D;
     point(position: Vec3, options?: PointOptions): this;
     line(start: Vec3, end: Vec3, options?: LineOptions): this;
     ray(origin: Vec3, direction: Vec3, options?: LineOptions): this;

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,7 +1,9 @@
-import type { Vec3 } from "./frame-recorder.js";
-import { type CircleBasis } from "./layout-3d.js";
+import type { Vec2 } from "./camera-2d.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 Segment2D = readonly [Vec2, Vec2];
 export type MeshData = {
     readonly triangles: readonly Triangle[];
     readonly segments: readonly Segment[];
@@ -99,3 +101,10 @@ export declare function coneWire(radius: number, height: number, segments: numbe
  */
 export declare function cylinderWire(radius: number, halfHeight: number, segments: number, sideSegmentCount: number, center: Vec3, basis: CircleBasis): ShapeWire;
 export declare function gridLines(cells: readonly [number, number], spacing: readonly [number, number], center?: Vec3, rotation?: readonly [number, number, number], skew?: readonly [number, number], outer?: "none" | "x" | "z" | "xz"): Segment[];
+/**
+ * 2D counterpart of `gridLines`: the same cell/skew/outer contract in the XY plane.
+ *
+ * `rotation` is one anticlockwise angle around the grid centre. `outer` keeps the x-axis
+ * boundary lines (`"x"`), the y-axis ones (`"y"`), or both (`"xy"`).
+ */
+export declare function gridLines2D(cells: readonly [number, number], spacing: readonly [number, number], center?: Vec2, rotation?: number, skew?: readonly [number, number], outer?: "none" | "x" | "y" | "xy"): Segment2D[];

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) => {
@@ -479,3 +479,39 @@ export function gridLines(cells, spacing, center = [0, 0, 0], rotation = [0, 0,
     }
     return segments;
 }
+/**
+ * 2D counterpart of `gridLines`: the same cell/skew/outer contract in the XY plane.
+ *
+ * `rotation` is one anticlockwise angle around the grid centre. `outer` keeps the x-axis
+ * boundary lines (`"x"`), the y-axis ones (`"y"`), or both (`"xy"`).
+ */
+export function gridLines2D(cells, spacing, center = [0, 0], rotation = 0, skew = [0, 0], outer = "none") {
+    const [cellX, cellY] = cells;
+    const [spacingX, spacingY] = spacing;
+    if (cellX <= 0 || cellY <= 0 || spacingX <= 0 || spacingY <= 0)
+        return [];
+    const skewTan = [Math.tan(skew[0]), Math.tan(skew[1])];
+    const dx = [spacingX, spacingX * skewTan[1]];
+    const dy = [spacingY * skewTan[0], spacingY];
+    const start = [-dx[0] * cellX * 0.5 - dy[0] * cellY * 0.5, -dx[1] * cellX * 0.5 - dy[1] * cellY * 0.5];
+    const cos = Math.cos(rotation);
+    const sin = Math.sin(rotation);
+    const place = (p) => [
+        center[0] + p[0] * cos - p[1] * sin,
+        center[1] + p[0] * sin + p[1] * cos,
+    ];
+    const plus = (a, b) => [a[0] + b[0], a[1] + b[1]];
+    const scale = (v, n) => [v[0] * n, v[1] * n];
+    const keepX = outer === "x" || outer === "xy";
+    const keepY = outer === "y" || outer === "xy";
+    const segments = [];
+    for (let yIndex = keepX ? 0 : 1; yIndex < (keepX ? cellY + 1 : cellY); yIndex++) {
+        const from = plus(start, scale(dy, yIndex));
+        segments.push([place(from), place(plus(from, scale(dx, cellX)))]);
+    }
+    for (let xIndex = keepY ? 0 : 1; xIndex < (keepY ? cellX + 1 : cellX); xIndex++) {
+        const from = plus(start, scale(dx, xIndex));
+        segments.push([place(from), place(plus(from, scale(dy, cellY)))]);
+    }
+    return segments;
+}

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-2d.js

@@ -43,6 +43,12 @@ function sameVec2(a, b) {
 function sameColor(a, b) {
     return a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];
 }
+/** Dash patterns are optional, so both sides being absent is also a match. */
+function sameDash(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
 function samePoint2D(a, b) {
     return sameVec2(a.position, b.position) && sameColor(a.color, b.color) && a.size === b.size && a.sizeMode === b.sizeMode && a.round === b.round;
 }
@@ -83,6 +89,7 @@ function sameShape2D(a, b) {
         a.startAngle === b.startAngle &&
         a.sweep === b.sweep &&
         a.sides === b.sides &&
+        sameDash(a.dash, b.dash) &&
         sameColor(a.color, b.color));
 }
 /** Two-dimensional point lifted onto the near plane the projection matrix maps to. */
@@ -163,7 +170,7 @@ class SpaceBucket2D {
         this.#points = instances({ capacity: capacities.points, attributes: { point: "float32x3", color: "float32x4", size: "float32", flags: "uint32" } });
         this.#lines = instances({ capacity: capacities.lines, attributes: { start: "float32x3", end: "float32x3", color: "float32x4", colorEnd: "float32x4", width: "float32", flags: "uint32", dash: "float32x3", normal: "float32x3", joint: "uint32" } });
         this.#joints = instances({ capacity: capacities.joints, attributes: { previous: "float32x3", center: "float32x3", next: "float32x3", color: "float32x4", width: "float32", flags: "uint32", dash: "float32x3", joint: "uint32", previousNormal: "float32x3", nextNormal: "float32x3" } });
-        this.#shapes = instances({ capacity: capacities.shapes, attributes: { shape: "uint32", center: "float32x3", size: "float32x2", vertexB: "float32x2", vertexC: "float32x2", params: "float32x4", rotationRadius: "float32x2", color: "float32x4", flags: "uint32" } });
+        this.#shapes = instances({ capacity: capacities.shapes, attributes: { shape: "uint32", center: "float32x3", size: "float32x2", vertexB: "float32x2", vertexC: "float32x2", params: "float32x4", rotationRadius: "float32x2", color: "float32x4", flags: "uint32", dash: "float32x3" } });
         this.#pointBridge = instanceGeometry(gpu, this.#points, { mesh: zeroGeometry(gpu) });
         this.#lineBridge = instanceGeometry(gpu, this.#lines, { mesh: zeroGeometry(gpu) });
         this.#jointBridge = instanceGeometry(gpu, this.#joints, { mesh: jointGeometry(gpu, options.jointVertexCount) });
@@ -380,10 +387,11 @@ class SpaceBucket2D {
             rotationRadius: [command.rotation, boundingRadius(command)],
             color: command.color,
             flags: (command.filled ? 1 : 0) | (command.sides << 8),
+            dash: command.dash ?? [0, 0, 0],
         });
     }
     #addShapeId(index) {
-        const id = this.#shapes.add({ shape: 0, center: [0, 0, 0], size: [0, 0], vertexB: [0, 0], vertexC: [0, 0], params: [0, 0, 0, 0], rotationRadius: [0, 0], color: [0, 0, 0, 0], flags: 0 });
+        const id = this.#shapes.add({ shape: 0, center: [0, 0, 0], size: [0, 0], vertexB: [0, 0], vertexC: [0, 0], params: [0, 0, 0, 0], rotationRadius: [0, 0], color: [0, 0, 0, 0], flags: 0, dash: [0, 0, 0] });
         world(this.#shapes, id);
         this.#shapeIds[index] = id;
         return id;

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);