vgpu-render 0.1.0 → 0.2.0

package/README.md

@@ -30,23 +30,23 @@ dependencies of this package.
 
 ## Usage
 
-The public API uses an explicit frame recorder:
+The public API uses an explicit frame draw list:
 
 ```ts
-const recorder = debug.beginFrame();
-recorder.point([0, 0, 0], { color: [1, 0, 0, 1], size: 8 });
-recorder.line([0, 0, 0], [1, 0, 0], { color: [0, 1, 0, 1], width: 2 });
-recorder.arrow([0, 0, 0], [1, 1, 0], { color: [0, 0.5, 1, 1] });
-recorder.lineStrip([[0, 0, 0], [1, 0, 1], [2, 0, 0]], { width: 4, joint: "round" }, false);
+const drawList = debug.beginFrame();
+drawList.point([0, 0, 0], { color: [1, 0, 0, 1], size: 8 });
+drawList.line([0, 0, 0], [1, 0, 0], { color: [0, 1, 0, 1], width: 2 });
+drawList.arrow([0, 0, 0], [1, 1, 0], { color: [0, 0.5, 1, 1] });
+drawList.lineStrip([[0, 0, 0], [1, 0, 1], [2, 0, 0]], { width: 4, joint: "round" }, false);
 // Per-vertex normals select the reference `*_n` shading: each segment uses its start
 // vertex's normal and the joints between them blend the two normals.
-recorder.lineStrip([[0, 0, 0], [1, 0, 0], [1, 1, 0]], { width: 4, joint: "round", normals: [[0, 1, 0], [0, 1, 0], [0, 1, 0]] }, false);
-recorder.grid([0, 0, 0], [4, 4], [0.5, 0.5], { color: [0.4, 0.4, 0.5, 1] });
-recorder.curve(cubicBezier, { color: [1, 1, 1, 1], tolerance: 0.08 });
-recorder.mesh(sphere(0.5), { solid: true, color: [0.2, 0.6, 1, 0.8] });
-recorder.text([0, 1, 0], "world label", { fontSize: 32, pixelSize: 0.01, color: [1, 0.8, 0.2, 1] });
-recorder.text([24, 24, 0], "screen HUD", { space: "screen", anchor: "top-left", fontSize: 16 });
-const commands = debug.finishFrame(recorder);
+drawList.lineStrip([[0, 0, 0], [1, 0, 0], [1, 1, 0]], { width: 4, joint: "round", normals: [[0, 1, 0], [0, 1, 0], [0, 1, 0]] }, false);
+drawList.grid([0, 0, 0], [4, 4], [0.5, 0.5], { color: [0.4, 0.4, 0.5, 1] });
+drawList.curve(cubicBezier, { color: [1, 1, 1, 1], tolerance: 0.08 });
+drawList.mesh(sphere(0.5), { solid: true, color: [0.2, 0.6, 1, 0.8] });
+drawList.text([0, 1, 0], "world label", { fontSize: 32, pixelSize: 0.01, color: [1, 0.8, 0.2, 1] });
+drawList.text([24, 24, 0], "screen HUD", { space: "screen", anchor: "top-left", fontSize: 16 });
+const commands = debug.finishFrame(drawList);
 
 // `view` is the world-to-view matrix; normal-aware strokes read it like the reference view matrix.
 renderer.prepare(commands, { viewProjection, view });
@@ -108,7 +108,7 @@ alphas, which the addon does not expose.
 ## Pipeline
 
 ```text
-FrameRecorder -> FrameCommand[] -> GpuDebugDraw3D
+FrameDrawList -> FrameCommand[] -> GpuDebugDraw3D
   points    -> instanced billboards
   lines     -> screen-space or world-space quads, dash + normal aware
   triangles -> transient solid meshes
@@ -146,7 +146,9 @@ Two coordinate spaces share one pixel-based pipeline:
 | `screen` | top-left corner | down | one canvas pixel | no |
 
 `world2d` mirrors the reference 2D camera: the origin is the centre of the target, `+y` points up and
-`zoom` is canvas pixels per world unit. `2d_shapes`' `X_EXTENT = 1000` is a pixel-scale world
+`zoom` is canvas pixels per world unit. Both spaces are in **target pixels**, like the text `screen`
+space, so a HiDPI caller scales `screen` content itself (`gallery/screen-scale.ts` does that for the
+gallery); `world2d` needs no such step because its projection already reads the target size. `2d_shapes`' `X_EXTENT = 1000` is a pixel-scale world
 coordinate in that sense, not a top-left one — the top-left, +y-down space is the reference UI space,
 and here it is `screen`, the same one `TextSpace "screen"` already uses.
 
@@ -156,7 +158,7 @@ dashes with the same phase accumulation as the 3D paths, and round/bevel/miter j
 `triangle`, `rhombus`, `sector`, `segment`. Each is one instanced quad evaluated as a signed
 distance field in the fragment stage, so nothing is triangulated on the CPU and an outline
 width stays a pixel count at any zoom. `fill: false` plus `strokeWidth` turns any of them into
-an outline.
+an outline; an `arc`'s outline is clipped to its `startAngle`/`sweep` wedge.
 - The layer is an overlay: it draws after every 3D primitive, pins itself to the near plane and
 does not write depth. Screen-space text remains the last thing drawn.
 - `InfiniteGrid2D` renders the reference's 2D grid as a full-viewport shader quad: decimal LOD levels,
@@ -164,11 +166,15 @@ does not write depth. Screen-space text remains the last thing drawn.
   `cellSize`, `lineWidthPixels`, `minPixelsBetweenCells`, the LOD range and both line colors from
   the gallery's grid panel, and draws as the 2D layer's background.
 - The 2D camera is independent of the 3D one (`mode: "3d" | "2d"` in the gallery config); the
-`2d-*` pages fit their declared `view2d` extent, drag to pan and scroll to zoom.
+`2d-*` pages fit their declared `view2d` extent, drag or hold WASD to pan, and scroll to zoom. The gallery
+classifies the 2D layer like the 3D scenes: `2d-gizmos` and `2d-shapes` are overviews, while
+`2d-lines`, `2d-curves`, `2d-markers`, `2d-outlines`, `2d-fill`, `2d-spaces` and `2d-grid` are
+column-by-row matrices whose column titles and sample labels are `world2d` text, so they pan
+and zoom with the geometry they annotate.
 
 ## Text
 
-`recorder.text(position, text, options)` draws one block per call. `text` is a string or a list
+`drawList.text(position, text, options)` draws one block per call. `text` is a string or a list
 of spans, the equivalent of a text root entity plus its child span entities.
 
 Three placement spaces share one pipeline and are selected per block:
@@ -179,6 +185,13 @@ Three placement spaces share one pipeline and are selected per block:
 | `world-billboard` | world units, block rebuilt from the camera's axes | `fontSize × pixelSize` |
 | `screen` | **top-left origin pixels** (`position.z` ignored) | `fontSize` pixels |
 
+The `screen` space is in **target pixels** — the same units as the pass's viewport — because the
+library has no DOM access and must not guess a display density. A caller on a HiDPI display owns the
+conversion: the gallery authors its pages in CSS pixels and multiplies every screen-space command by
+`devicePixelRatio` before handing the frame over (`gallery/screen-scale.ts`). A block placed at
+`[24, 24]` with `fontSize: 18` in CSS pixels then draws at `[48, 48]` and 36 target pixels on a 2×
+display, which is what keeps a label the same physical size on every screen.
+
 `fontSize` is in **font pixels** and is the layout unit; `pixelSize` is world units per font pixel.
 That pair is the reference `font_size` / `pixel_size`, and it lets a block keep a fixed world
 size while its glyphs are rasterised at any resolution. Which resolution that is belongs to the glyph
@@ -187,6 +200,12 @@ source: one that can rasterise on demand is asked for the size the block covers
 `fontSize × rasterScale`. Layout options follow the reference layout model: `justify`, `lineBreak`,
 `bounds` (`TextBounds`, in font pixels), `anchor`, `lineHeight` and `letterSpacing`.
 
+`rotation` turns a `world-plane` block away from the XY plane, with the reference `Label3D.rotation`
+Euler order (Y, then X, then Z) in radians. `[-Math.PI / 2, 0, 0]` lays a block flat on the XZ plane
+so it reads from above, which is what the reference example labels do; the two camera-relative
+spaces ignore it. The basis travels in the instance world matrix, so the text pipeline stays inside
+the device's vertex attribute budget.
+
 `lineHeight` is the absolute pixel form when you pass one, and the default is a `1.2` multiple of the
 font size otherwise — which means a line's box is that multiple of **the line's own
 largest span**, so a line holding a bigger span is taller. `lineHeightScale` names that multiple
@@ -198,6 +217,34 @@ shaping pass adds it to each cluster's advance.
 World text is depth-tested but never depth-written, so geometry in front of it
 occludes it; `screen` text pins itself to the near plane and always wins.
 
+### Font face
+
+`weight` (1–1000, default `400`), `style` (`normal` or `italic`) and `width` (the nine
+`font-stretch` keywords) select the face a block is rasterised in, mirroring bevy's `TextFont`.
+They are block defaults, and a span overrides one axis of them at a time rather than replacing the
+whole face. The glyph atlas keys on all three, so two weights of one character cannot share texels.
+
+How much of that a browser can honour depends on the loaded face, and the limits are real:
+
+| option | what Canvas2D does |
+| --- | --- |
+| `weight` | A weight the loaded family does not carry is **synthesised** in one step (the threshold sits between 500 and 600), so `700` and `900` then look identical and the advance never changes. A variable font's real `wght` axis is not reachable — Canvas2D has no `font-variation-settings` — but the browser **does** pick a face by the weight it was registered with, so registering the same family once per weight gives real weights. |
+| `style` | `italic` is the only slant the font shorthand keeps; `oblique <angle>` reads back as plain `italic`, which is why bevy's `FontStyle::Oblique(a)` is not exposed. A face without an italic is slanted by the browser. |
+| `width` | The keyword only reaches the font when the face has a `wdth` axis. The bundled static subset has none, so every stop draws at normal width there. A percentage is rejected by the shorthand, so only the nine named stops exist here. |
+
+The bundled Fira Mono subset is a static Medium face, so out of the box `weight` only ever produces
+one synthesised step. `loadFontFaces(family, faces)` is the way out: it registers each entry as a face
+of `family` with its own `weight` descriptor, so `weight: 200` through `900` select genuinely different
+faces. The gallery does exactly that for the `text-font-query` page, which draws with eight instances
+of a variable font built by `bun scripts/build-font-faces.ts` (see
+`gallery/assets/`). That is gallery-only payload: the library's own entry point does not
+carry it.
+
+A custom glyph source receives the resolved face — `{ family, weight, style, width }` — instead of a
+family string, because those are the fields the atlas keys on. A source that holds one fixed face (a
+prebaked page, one parsed font buffer) sets `faceKey` to the part it can honour, so a weight it cannot
+rasterise does not multiply identical atlas entries.
+
 ### Outline
 
 `outlineWidth` (in font pixels) rings every glyph in the block in `outlineColor`, which defaults to
@@ -381,8 +428,8 @@ const renderer = new GpuDebugDraw3D(gpu, {
   },
 });
 
-recorder.text([0, 0, 0], "read me", { source: "sharp" });
-recorder.text([0, -1, 0], "and me", { source: "cheap" });
+drawList.text([0, 0, 0], "read me", { source: "sharp" });
+drawList.text([0, -1, 0], "and me", { source: "cheap" });
 ```
 
 Blocks that name nothing use the first source registered, and `defaultTextStyle` can set one for the
@@ -391,7 +438,10 @@ actually names it, so registering sources you never draw costs nothing.
 
 Seven scenes exercise text end to end, and none of them is a port — the reference addon has no text
 API; the layout they run follows the reference layout model, and `docs/text-reference.md` records how
-that was verified.
+that was verified. The geometry examples also draw their own labels, because the reference scenes
+own `Label3D` captions for every column and row; those go through the same pipeline, lying flat on
+the ground with `rotation: [-Math.PI / 2, 0, 0]`. A `GpuDebugDraw3D` built without a `text` option
+skips those blocks instead of failing, so geometry-only callers keep working.
 
 `text-compare` is the parity matrix, in the shape of the line/circle examples: rows are glyph sources,
 columns are font sizes, transposed relative to those because text grows sideways. The six
@@ -457,7 +507,7 @@ gallery to a single glyph source (`auto`, `bitmap`, `bitmap4x`, `sdf`, `sdf4x`,
 - `InfiniteGrid3D` shader-driven ground grid ported from the reference grid addon
   (decimal LOD layers, screen-space width, edge/grazing/center/far fades).
 - Orbit/pan/zoom camera controls in the gallery, tuned to the reference
-  `entities/free_camera.gd` and layered on a velocity model (`src/demo-camera.ts`): a drag is
+  `entities/free_camera.gd` and layered on a velocity model (`gallery/demo-camera.ts`): a drag is
   an angular velocity (0.25°/px) or a linear velocity (`distance`/FOV in perspective,
   `orthographicHeight` in orthographic), a wheel notch is a scalar velocity in log₂ space
   (1.08× per notch), and a released drag keeps its velocity and glides — the exact integral of
@@ -488,7 +538,7 @@ const debug = new DebugDraw3D({
 });
 ```
 
-`src/demo-config.ts` contains independently validated camera/view configuration
+`gallery/demo-config.ts` contains independently validated camera/view configuration
 and injected storage helpers. Gallery controls support grid, opacity, animation,
 width multiplier, projection, background, camera preset and reset; camera
 interaction is persisted. The sidebar groups them into three collapsible
@@ -507,11 +557,11 @@ deterministic preset without localStorage: `/?compare=1&scene=circle`. Orthograp
 changes the orthographic extent.
 
 The gallery UI is built with **Base UI + shadcn (base-lyra preset) + Tailwind v4**
-in `src/components/`, and the imperative WebGPU side lives in `src/demo-engine.ts`.
+in `gallery/components/`, and the imperative WebGPU side lives in `gallery/demo-engine.ts`.
 React only renders chrome; the render loop, camera, and persistence stay outside
 React and are read through `useSyncExternalStore`
-(`src/demo-hooks.ts`). `src/demo.tsx` mounts the shell, `src/index.css` holds the base-lyra
-theme tokens, and `src/demo.css` keeps the three-column layout, compare mode
+(`gallery/demo-hooks.ts`). `gallery/demo.tsx` mounts the shell, `gallery/index.css` holds the base-lyra
+theme tokens, and `gallery/demo.css` keeps the three-column layout, compare mode
 and code highlighting.
 
 Runtime comparison viewers (see `docs/visual-comparison.md` and `docs/text-reference.md`):

package/dist/curve.d.ts

@@ -1,4 +1,4 @@
-import type { Vec3 } from "./frame-recorder.js";
+import type { Vec3 } from "./frame-draw-list.js";
 export type CurvePoint = {
     readonly position: Vec3;
     readonly in?: Vec3;

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

@@ -1,4 +1,4 @@
-import { FrameRecorder, type FrameCommand, type LayerMask, type LineDefaults, type PointDefaults } from "./frame-recorder.js";
+import { FrameDrawList, type FrameCommand, type LayerMask, type LineDefaults, type PointDefaults } from "./frame-draw-list.js";
 export type DebugDrawOptions = {
     defaultVisibleLayers?: LayerMask;
     /** Style applied to every point that does not override it. */
@@ -9,6 +9,6 @@ export type DebugDrawOptions = {
 export declare class DebugDraw3D {
     #private;
     constructor(options?: DebugDrawOptions);
-    beginFrame(): FrameRecorder;
-    finishFrame(recorder: FrameRecorder): readonly FrameCommand[];
+    beginFrame(): FrameDrawList;
+    finishFrame(drawList: FrameDrawList): readonly FrameCommand[];
 }

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

@@ -1,4 +1,4 @@
-import { FrameRecorder, resolveFrameRecorderDefaults, } from "./frame-recorder.js";
+import { FrameDrawList, resolveFrameDrawListDefaults, } from "./frame-draw-list.js";
 export class DebugDraw3D {
     #visibleLayers;
     #defaults;
@@ -14,22 +14,22 @@ export class DebugDraw3D {
             ...(options.defaultLineStyle === undefined ? {} : { line: { ...options.defaultLineStyle } }),
         };
         // Validate eagerly so invalid defaults fail at construction, not on the first frame.
-        resolveFrameRecorderDefaults(this.#defaults);
+        resolveFrameDrawListDefaults(this.#defaults);
     }
     beginFrame() {
         if (this.#active !== undefined) {
             throw new Error("a debug draw frame is already active");
         }
-        const recorder = new FrameRecorder(this.#defaults);
-        this.#active = recorder;
-        return recorder;
+        const drawList = new FrameDrawList(this.#defaults);
+        this.#active = drawList;
+        return drawList;
     }
-    finishFrame(recorder) {
-        if (this.#active !== recorder) {
-            throw new Error("recorder does not belong to this debug draw instance");
+    finishFrame(drawList) {
+        if (this.#active !== drawList) {
+            throw new Error("drawList does not belong to this debug draw instance");
         }
-        const commands = recorder.commands(this.#visibleLayers);
-        recorder.seal();
+        const commands = drawList.commands(this.#visibleLayers);
+        drawList.seal();
         this.#active = undefined;
         return commands;
     }

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

@@ -1,7 +1,7 @@
 /**
- * 2D debug-draw commands and their recorder.
+ * 2D debug-draw commands and their drawList.
  *
- * The 2D layer is the same data flow as the 3D one — `FrameRecorder -> FrameCommand[] -> GPU` —
+ * The 2D layer is the same data flow as the 3D one — `FrameDrawList -> FrameCommand[] -> GPU` —
  * reached through `frame.d2` instead of a second entry point, so a frame has one lifecycle, one
  * layer mask and one set of defaults. The commands are separate types rather than 3D commands
  * with a `space` flag because a 2D point is a `Vec2` and 2D strokes carry no surface normal;
@@ -10,7 +10,7 @@
  * See `camera-2d.ts` for what `world2d` and `screen` mean.
  */
 import type { Space2D, Vec2 } from "./camera-2d.js";
-import type { Color, LayerMask, LineJoint, RenderedJoint, ResolvedLineDefaults, ResolvedPointDefaults } from "./frame-recorder.js";
+import type { Color, LayerMask, LineJoint, RenderedJoint, ResolvedLineDefaults, ResolvedPointDefaults } from "./frame-draw-list.js";
 export type Line2DOptions = {
     color?: Color;
     colorEnd?: Color;
@@ -115,31 +115,31 @@ export type Joint2DCommand = {
     readonly space: Space2D;
     readonly layer: LayerMask;
 };
-/** Everything a `FrameRecorder2D` can emit. */
+/** Everything a `FrameDrawList2D` can emit. */
 export type FrameCommand2D = Point2DCommand | Line2DCommand | Joint2DCommand | Shape2DCommand;
-/** The 3D recorder's resolved point/line styles, reused so 2D and 3D defaults cannot drift. */
-export type FrameRecorder2DStyleDefaults = {
+/** The 3D drawList's resolved point/line styles, reused so 2D and 3D defaults cannot drift. */
+export type FrameDrawList2DStyleDefaults = {
     readonly point: ResolvedPointDefaults;
     readonly line: ResolvedLineDefaults;
 };
 /**
- * Records 2D primitives for one frame. Obtained through `FrameRecorder.d2`; it seals with its
+ * Records 2D primitives for one frame. Obtained through `FrameDrawList.d2`; it seals with its
  * parent, so a caller cannot keep drawing into a finished frame.
  */
-export declare class FrameRecorder2D {
+export declare class FrameDrawList2D {
     #private;
-    constructor(defaults: FrameRecorder2DStyleDefaults, assertOpen: () => void);
+    constructor(defaults: FrameDrawList2DStyleDefaults, assertOpen: () => void);
     point(position: Vec2, options?: Point2DOptions): this;
     line(start: Vec2, end: Vec2, options?: Line2DOptions): this;
     ray(origin: Vec2, direction: Vec2, options?: Line2DOptions): this;
     /**
-     * Path of segments, the 2D twin of `FrameRecorder.lineStrip`. Dash distance accumulates over
+     * Path of segments, the 2D twin of `FrameDrawList.lineStrip`. Dash distance accumulates over
      * the whole path and an open strip joins only its interior vertices, matching the 3D layer.
      */
     lineStrip(points: readonly Vec2[], options?: Line2DOptions, closed?: boolean): this;
     polyline(points: readonly Vec2[], options?: Line2DOptions, closed?: boolean): this;
     /**
-     * Axis-aligned grid of lines, the 2D twin of `FrameRecorder.grid` and reference `grid_2d`: `cells`
+     * Axis-aligned grid of lines, the 2D twin of `FrameDrawList.grid` and reference `grid_2d`: `cells`
      * are the cells per axis, so the drawn line count is one more on each side.
      */
     grid(center: Vec2, cells: readonly [number, number], spacing: Vec2, options?: Line2DOptions): this;

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

@@ -1,7 +1,7 @@
 /**
- * 2D debug-draw commands and their recorder.
+ * 2D debug-draw commands and their drawList.
  *
- * The 2D layer is the same data flow as the 3D one — `FrameRecorder -> FrameCommand[] -> GPU` —
+ * The 2D layer is the same data flow as the 3D one — `FrameDrawList -> FrameCommand[] -> GPU` —
  * reached through `frame.d2` instead of a second entry point, so a frame has one lifecycle, one
  * layer mask and one set of defaults. The commands are separate types rather than 3D commands
  * with a `space` flag because a 2D point is a `Vec2` and 2D strokes carry no surface normal;
@@ -96,10 +96,10 @@ function spaceValue(value) {
     return value;
 }
 /**
- * Records 2D primitives for one frame. Obtained through `FrameRecorder.d2`; it seals with its
+ * Records 2D primitives for one frame. Obtained through `FrameDrawList.d2`; it seals with its
  * parent, so a caller cannot keep drawing into a finished frame.
  */
-export class FrameRecorder2D {
+export class FrameDrawList2D {
     #points = [];
     #lines = [];
     #joints = [];
@@ -158,7 +158,7 @@ export class FrameRecorder2D {
         return this.line(origin, [origin[0] + direction[0], origin[1] + direction[1]], options);
     }
     /**
-     * Path of segments, the 2D twin of `FrameRecorder.lineStrip`. Dash distance accumulates over
+     * Path of segments, the 2D twin of `FrameDrawList.lineStrip`. Dash distance accumulates over
      * the whole path and an open strip joins only its interior vertices, matching the 3D layer.
      */
     lineStrip(points, options = {}, closed = false) {
@@ -193,7 +193,7 @@ export class FrameRecorder2D {
         return this.lineStrip(points, options, closed);
     }
     /**
-     * Axis-aligned grid of lines, the 2D twin of `FrameRecorder.grid` and reference `grid_2d`: `cells`
+     * Axis-aligned grid of lines, the 2D twin of `FrameDrawList.grid` and reference `grid_2d`: `cells`
      * are the cells per axis, so the drawn line count is one more on each side.
      */
     grid(center, cells, spacing, options = {}) {

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;