vgpu-render 0.0.0-stage → 0.2.0

package/dist/frame-draw-list.js

@@ -0,0 +1,556 @@
+import { sampleCurve } from "./curve.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, 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) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`${name} must be finite`);
+    }
+    return value;
+}
+function vec3(value, name) {
+    if (value.length !== 3) {
+        throw new RangeError(`${name} must contain three values`);
+    }
+    return [finite(value[0], `${name}[0]`), finite(value[1], `${name}[1]`), finite(value[2], `${name}[2]`)];
+}
+function colorValue(value, name) {
+    if (value.length !== 4) {
+        throw new RangeError(`${name} must contain four values`);
+    }
+    return [
+        finite(value[0], `${name}[0]`),
+        finite(value[1], `${name}[1]`),
+        finite(value[2], `${name}[2]`),
+        finite(value[3], `${name}[3]`),
+    ];
+}
+function color(value) {
+    return value === undefined ? DEFAULT_COLOR : colorValue(value, "color");
+}
+function layerValue(value, name) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative integer bitmask`);
+    }
+    return value;
+}
+function layer(value) {
+    return value === undefined ? DEFAULT_LAYER : layerValue(value, "layer");
+}
+function sizeModeValue(value, name) {
+    if (value !== "screen" && value !== "world") {
+        throw new RangeError(`${name} must be "screen" or "world"`);
+    }
+    return value;
+}
+function jointValue(value, name) {
+    if (value !== "none" && value !== "round" && value !== "bevel" && value !== "miter") {
+        throw new RangeError(`${name} must be "none", "round", "bevel", or "miter"`);
+    }
+    return value;
+}
+const TEXT_JUSTIFY = ["left", "center", "right", "justified", "start", "end"];
+const TEXT_LINE_BREAK = ["word", "character", "word-or-character", "none"];
+const TEXT_SPACES = ["world-plane", "world-billboard", "screen"];
+function textJustifyValue(value, name) {
+    if (!TEXT_JUSTIFY.includes(value)) {
+        throw new RangeError(`${name} must be one of ${TEXT_JUSTIFY.join(", ")}`);
+    }
+    return value;
+}
+function textLineBreakValue(value, name) {
+    if (!TEXT_LINE_BREAK.includes(value)) {
+        throw new RangeError(`${name} must be one of ${TEXT_LINE_BREAK.join(", ")}`);
+    }
+    return value;
+}
+function textSpaceValue(value, name) {
+    if (!TEXT_SPACES.includes(value)) {
+        throw new RangeError(`${name} must be one of ${TEXT_SPACES.join(", ")}`);
+    }
+    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`);
+    if (!(value[0] > 0) || !(value[1] > 0))
+        throw new RangeError(`${name} values must be greater than zero`);
+    return value;
+}
+/**
+ * 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, baseWeight, baseStyle, baseWidth) {
+    const input = typeof text === "string" ? [{ text }] : text;
+    const baseColor = color(options.color ?? defaults.color);
+    return input.map((span) => {
+        const fontSize = span.fontSize ?? baseFontSize;
+        if (!Number.isFinite(fontSize) || fontSize <= 0)
+            throw new RangeError("span fontSize must be greater than zero");
+        return {
+            text: span.text,
+            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 resolveFrameDrawListDefaults(defaults = {}) {
+    const point = defaults.point ?? {};
+    const line = defaults.line ?? {};
+    const text = defaults.text ?? {};
+    const pointSize = point.size === undefined ? undefined : finite(point.size, "default point size");
+    if (pointSize !== undefined && pointSize <= 0) {
+        throw new RangeError("default point size must be greater than zero");
+    }
+    const lineWidth = line.width === undefined ? undefined : finite(line.width, "default line width");
+    if (lineWidth !== undefined && lineWidth <= 0) {
+        throw new RangeError("default line width must be greater than zero");
+    }
+    const textSize = text.fontSize === undefined ? undefined : finite(text.fontSize, "default text fontSize");
+    if (textSize !== undefined && textSize <= 0) {
+        throw new RangeError("default text fontSize must be greater than zero");
+    }
+    const textPixelSize = text.pixelSize === undefined ? undefined : finite(text.pixelSize, "default text pixelSize");
+    if (textPixelSize !== undefined && textPixelSize <= 0) {
+        throw new RangeError("default text pixelSize must be greater than zero");
+    }
+    const textLineHeight = text.lineHeight === undefined ? undefined : finite(text.lineHeight, "default text lineHeight");
+    if (textLineHeight !== undefined && textLineHeight <= 0) {
+        throw new RangeError("default text lineHeight must be greater than zero");
+    }
+    const textLineHeightScale = text.lineHeightScale === undefined ? undefined : finite(text.lineHeightScale, "default text lineHeightScale");
+    if (textLineHeightScale !== undefined && textLineHeightScale <= 0) {
+        throw new RangeError("default text lineHeightScale must be greater than zero");
+    }
+    if (textLineHeight !== undefined && textLineHeightScale !== undefined) {
+        throw new RangeError("default text lineHeight and lineHeightScale are exclusive; pass one or the other");
+    }
+    const textAnchor = text.anchor;
+    if (textAnchor !== undefined)
+        resolveTextAnchor(textAnchor);
+    const textOutlineWidth = text.outlineWidth === undefined ? undefined : finite(text.outlineWidth, "default text outlineWidth");
+    if (textOutlineWidth !== undefined && textOutlineWidth < 0) {
+        throw new RangeError("default text outlineWidth must not be negative");
+    }
+    return {
+        point: {
+            color: point.color === undefined ? undefined : colorValue(point.color, "default point color"),
+            size: pointSize,
+            sizeMode: point.sizeMode === undefined ? undefined : sizeModeValue(point.sizeMode, "default point sizeMode"),
+            layer: point.layer === undefined ? undefined : layerValue(point.layer, "default point layer"),
+        },
+        line: {
+            color: line.color === undefined ? undefined : colorValue(line.color, "default line color"),
+            colorEnd: line.colorEnd === undefined ? undefined : colorValue(line.colorEnd, "default line colorEnd"),
+            width: lineWidth,
+            widthMode: line.widthMode === undefined ? undefined : sizeModeValue(line.widthMode, "default line widthMode"),
+            dash: line.dash,
+            normal: line.normal === undefined ? undefined : vec3(line.normal, "default line normal"),
+            joint: line.joint === undefined ? undefined : jointValue(line.joint, "default line joint"),
+            layer: line.layer === undefined ? undefined : layerValue(line.layer, "default line layer"),
+        },
+        text: {
+            color: text.color === undefined ? undefined : colorValue(text.color, "default text color"),
+            outlineWidth: textOutlineWidth,
+            outlineColor: text.outlineColor === undefined ? undefined : colorValue(text.outlineColor, "default text outlineColor"),
+            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"),
+            justify: text.justify === undefined ? undefined : textJustifyValue(text.justify, "default text justify"),
+            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"),
+        },
+    };
+}
+/**
+ * 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 = [];
+    #triangles = [];
+    #texts = [];
+    #defaults;
+    #d2;
+    #sealed = false;
+    constructor(defaults = {}) {
+        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 FrameDrawList2D({ point: this.#defaults.point, line: this.#defaults.line }, () => this.assertOpen());
+    }
+    /**
+     * 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() {
+        this.assertOpen();
+        return this.#d2;
+    }
+    point(position, options = {}) {
+        this.assertOpen();
+        const size = finite(options.size ?? this.#defaults.point.size ?? 1, "size");
+        if (size <= 0)
+            throw new RangeError("size must be greater than zero");
+        this.#points.push({
+            kind: "point",
+            position: vec3(position, "position"),
+            color: color(options.color ?? this.#defaults.point.color),
+            size,
+            sizeMode: options.sizeMode ?? this.#defaults.point.sizeMode ?? "screen",
+            layer: layer(options.layer ?? this.#defaults.point.layer),
+            ...(options.round === undefined ? {} : { round: options.round }),
+        });
+        return this;
+    }
+    line(start, end, options = {}) {
+        this.assertOpen();
+        const resolvedStart = vec3(start, "start");
+        const resolvedEnd = vec3(end, "end");
+        if (resolvedStart.every((value, index) => value === resolvedEnd[index])) {
+            return this;
+        }
+        const width = finite(options.width ?? this.#defaults.line.width ?? 1, "width");
+        if (width <= 0)
+            throw new RangeError("width must be greater than zero");
+        const dash = options.dash ?? this.#defaults.line.dash;
+        const normal = options.normal ?? this.#defaults.line.normal;
+        const joint = options.joint ?? this.#defaults.line.joint;
+        const command = {
+            kind: "line",
+            start: resolvedStart,
+            end: resolvedEnd,
+            color: color(options.color ?? this.#defaults.line.color),
+            colorEnd: color(options.colorEnd ?? options.color ?? this.#defaults.line.colorEnd ?? this.#defaults.line.color),
+            width,
+            widthMode: options.widthMode ?? this.#defaults.line.widthMode ?? "screen",
+            layer: layer(options.layer ?? this.#defaults.line.layer),
+            ...(dash === undefined ? {} : { dash }),
+            ...(normal === undefined ? {} : { normal: vec3(normal, "normal") }),
+            ...(joint === undefined ? {} : { joint }),
+        };
+        this.#lines.push(command);
+        return this;
+    }
+    ray(origin, direction, options = {}) {
+        return this.line(origin, [origin[0] + direction[0], origin[1] + direction[1], origin[2] + direction[2]], options);
+    }
+    arrow(origin, direction, options = {}) {
+        const end = [origin[0] + direction[0], origin[1] + direction[1], origin[2] + direction[2]];
+        this.line(origin, end, options);
+        const length = Math.hypot(direction[0], direction[1], direction[2]) || 1;
+        const headLength = options.headLength ?? Math.min(0.18, length * 0.25);
+        const headAngle = options.headAngle ?? Math.PI / 6;
+        const forward = [direction[0] / length, direction[1] / length, direction[2] / length];
+        const reference = Math.abs(forward[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+        const side = [forward[1] * reference[2] - forward[2] * reference[1], forward[2] * reference[0] - forward[0] * reference[2], forward[0] * reference[1] - forward[1] * reference[0]];
+        const sideLength = Math.hypot(side[0], side[1], side[2]) || 1;
+        const unitSide = [side[0] / sideLength, side[1] / sideLength, side[2] / sideLength];
+        const back = Math.cos(headAngle) * headLength;
+        const spread = Math.sin(headAngle) * headLength;
+        const left = [end[0] - forward[0] * back + unitSide[0] * spread, end[1] - forward[1] * back + unitSide[1] * spread, end[2] - forward[2] * back + unitSide[2] * spread];
+        const right = [end[0] - forward[0] * back - unitSide[0] * spread, end[1] - forward[1] * back - unitSide[1] * spread, end[2] - forward[2] * back - unitSide[2] * spread];
+        this.line(end, left, options);
+        this.line(end, right, options);
+        return this;
+    }
+    axes(origin, length = 1, width = 2) {
+        // Reference `draw_axes` emits three unadorned axis lines (no arrowheads).
+        this.line(origin, [origin[0] + length, origin[1], origin[2]], { color: [1, 0, 0, 1], width });
+        this.line(origin, [origin[0], origin[1] + length, origin[2]], { color: [0, 1, 0, 1], width });
+        this.line(origin, [origin[0], origin[1], origin[2] + length], { color: [0, 0, 1, 1], width });
+        return this;
+    }
+    lineStrip(points, options = {}, closed = false) {
+        this.assertOpen();
+        // Dash distance must accumulate across the whole path, otherwise each segment
+        // restarts the pattern and closed shapes render as a nearly continuous line.
+        const dash = options.dash ?? this.#defaults.line.dash;
+        // Per-vertex normals mirror the reference `*_n` entry points: each segment is emitted
+        // with its start vertex's normal instead of one normal for the whole path.
+        const normals = options.normals;
+        if (normals !== undefined) {
+            // Reference `draw_line_strip_n` accepts one normal per segment, `draw_line_loop_n` one
+            // per vertex; the loop's closing segment reuses the last vertex's normal.
+            const required = closed ? points.length : Math.max(0, points.length - 1);
+            if (normals.length < required) {
+                throw new RangeError(`normals must have at least ${required} entries for this path`);
+            }
+        }
+        const { normals: _normals, ...sharedOptions } = options;
+        void _normals;
+        const vertexDistances = [0];
+        let traveled = 0;
+        const segment = (a, b, index) => {
+            const normal = normals === undefined ? undefined : normals[index];
+            const segmentOptions = {
+                ...sharedOptions,
+                ...(dash === undefined ? {} : { dash: [dash[0], dash[1], dash[2] + traveled] }),
+                ...(normal === undefined ? {} : { normal }),
+            };
+            this.line(a, b, segmentOptions);
+            traveled += Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+            vertexDistances.push(traveled);
+        };
+        for (let i = 0; i + 1 < points.length; i++)
+            segment(points[i], points[i + 1], i);
+        if (closed && points.length > 1)
+            segment(points[points.length - 1], points[0], points.length - 1);
+        const joint = options.joint ?? this.#defaults.line.joint;
+        // Reference `_emit_line_strip` / `_emit_line_loop`: an open strip only joins its
+        // interior vertices, while a loop also joins the two wrap-around seam vertices.
+        if (joint === "round" || joint === "bevel" || joint === "miter") {
+            const count = points.length;
+            const first = closed ? 0 : 1;
+            const last = closed ? (count > 2 ? count : 0) : count - 1;
+            for (let i = first; i < last; i++) {
+                const previousIndex = (i - 1 + count) % count;
+                this.#jointCommand(points[previousIndex], points[i], points[(i + 1) % count], joint, sharedOptions, dash, vertexDistances[i], normals === undefined ? undefined : [normals[previousIndex], normals[i]]);
+            }
+        }
+        return this;
+    }
+    /**
+     * Emits one joint instance for a path vertex. The reference skips degenerate wedges
+     * where the center coincides with a neighbour (`emit_joint`), and reuses the resolved
+     * line width/color/layer so segment and joint strokes cannot drift apart.
+     */
+    #jointCommand(previous, center, next, joint, options, dash, distance, normals) {
+        const resolvedPrevious = vec3(previous, "previous");
+        const resolvedCenter = vec3(center, "center");
+        const resolvedNext = vec3(next, "next");
+        const same = (a, b) => a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+        if (same(resolvedPrevious, resolvedCenter) || same(resolvedCenter, resolvedNext))
+            return;
+        const width = finite(options.width ?? this.#defaults.line.width ?? 1, "width");
+        if (width <= 0)
+            throw new RangeError("width must be greater than zero");
+        this.#joints.push({
+            kind: "joint",
+            previous: resolvedPrevious,
+            center: resolvedCenter,
+            next: resolvedNext,
+            color: color(options.color ?? this.#defaults.line.color),
+            width,
+            widthMode: options.widthMode ?? this.#defaults.line.widthMode ?? "screen",
+            joint,
+            layer: layer(options.layer ?? this.#defaults.line.layer),
+            ...(dash === undefined ? {} : { dash: [dash[0], dash[1], dash[2] + distance] }),
+            ...(normals === undefined ? {} : { previousNormal: vec3(normals[0], "previousNormal"), nextNormal: vec3(normals[1], "nextNormal") }),
+        });
+    }
+    polyline(points, options = {}, closed = false) {
+        return this.lineStrip(points, options, closed);
+    }
+    triangle(a, b, c, options = {}) {
+        this.assertOpen();
+        this.#triangles.push({
+            kind: "triangle",
+            a: vec3(a, "a"),
+            b: vec3(b, "b"),
+            c: vec3(c, "c"),
+            color: color(options.color),
+            layer: layer(options.layer),
+        });
+        return this;
+    }
+    mesh(mesh, options = {}) {
+        const shared = {
+            ...(options.color === undefined ? {} : { color: options.color }),
+            ...(options.layer === undefined ? {} : { layer: options.layer }),
+        };
+        if (options.solid) {
+            for (const [a, b, c] of mesh.triangles)
+                this.triangle(a, b, c, shared);
+        }
+        else {
+            for (const [a, b] of mesh.segments)
+                this.line(a, b, shared);
+        }
+        return this;
+    }
+    curve(curve, options = {}) {
+        const points = sampleCurve(curve, options.tolerance, options.transform);
+        const { tolerance: _tolerance, transform: _transform, ...lineOptions } = options;
+        void _tolerance;
+        void _transform;
+        return this.lineStrip(points, lineOptions, curve.closed ?? false);
+    }
+    grid(center, cells, spacing, options = {}) {
+        const { rotation, skew, outer, ...lineOptions } = options;
+        for (const [a, b] of gridLines(cells, spacing, center, rotation, skew, outer))
+            this.line(a, b, lineOptions);
+        return this;
+    }
+    /**
+     * Records one text block. `text` is either the block's string or a list of spans, mirroring
+     * reference `Text2d`/`Text` root plus its child `TextSpan`s; a span's own style overrides the
+     * block default. Layout happens at draw time, because only the renderer knows where the
+     * glyph atlas placed each character.
+     */
+    text(position, text, options = {}) {
+        this.assertOpen();
+        const defaults = this.#defaults.text;
+        const fontSize = finite(options.fontSize ?? defaults.fontSize ?? DEFAULT_TEXT_SIZE, "fontSize");
+        if (fontSize <= 0)
+            throw new RangeError("fontSize must be greater than zero");
+        const pixelSize = finite(options.pixelSize ?? defaults.pixelSize ?? DEFAULT_TEXT_PIXEL_SIZE, "pixelSize");
+        if (pixelSize <= 0)
+            throw new RangeError("pixelSize must be greater than zero");
+        const lineHeightOption = options.lineHeight ?? defaults.lineHeight;
+        const lineHeightScaleOption = options.lineHeightScale ?? defaults.lineHeightScale;
+        if (lineHeightOption !== undefined && lineHeightScaleOption !== undefined) {
+            throw new RangeError("lineHeight and lineHeightScale are exclusive; pass one or the other");
+        }
+        // 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.
+        const lineHeightScale = lineHeightOption === undefined
+            ? finite(lineHeightScaleOption ?? DEFAULT_LINE_HEIGHT_RATIO, "lineHeightScale")
+            : undefined;
+        if (lineHeightScale !== undefined && lineHeightScale <= 0)
+            throw new RangeError("lineHeightScale must be greater than zero");
+        const lineHeight = lineHeightScale === undefined ? finite(lineHeightOption, "lineHeight") : fontSize * lineHeightScale;
+        if (lineHeight <= 0)
+            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)
+            textBounds(bounds, "bounds");
+        const outlineWidth = finite(options.outlineWidth ?? defaults.outlineWidth ?? 0, "outlineWidth");
+        if (outlineWidth < 0)
+            throw new RangeError("outlineWidth must not be negative");
+        const outlineColor = color(options.outlineColor ?? defaults.outlineColor ?? options.color ?? defaults.color);
+        // Validates the anchor name and the enumerated fields with the same messages defaults use.
+        resolveTextAnchor(anchor);
+        textJustifyValue(justify, "justify");
+        textLineBreakValue(lineBreak, "lineBreak");
+        textSpaceValue(space, "space");
+        this.#texts.push({
+            kind: "text",
+            position: vec3(position, "position"),
+            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,
+            justify,
+            lineBreak,
+            anchor,
+            space,
+            rotation,
+            ...(source === undefined ? {} : { source }),
+            depthTest: options.depthTest ?? defaults.depthTest ?? true,
+            layer: layer(options.layer ?? defaults.layer),
+            ...(bounds === undefined ? {} : { bounds }),
+        });
+        return this;
+    }
+    get points() {
+        return this.#points;
+    }
+    get lines() {
+        return this.#lines;
+    }
+    get joints() {
+        return this.#joints;
+    }
+    get texts() {
+        return this.#texts;
+    }
+    commands(visibleLayers = 0xffff_ffff) {
+        this.assertOpen();
+        if (!Number.isInteger(visibleLayers) || visibleLayers < 0) {
+            throw new RangeError("visibleLayers must be a non-negative integer bitmask");
+        }
+        // Text draws last: it is the only alpha-blended primitive that is not depth-sorted against
+        // its own kind, so keeping it at the end preserves the reference's reading order. The 2D
+        // commands follow the 3D ones because the renderer draws them as an overlay.
+        return [
+            ...this.#points,
+            ...this.#lines,
+            ...this.#joints,
+            ...this.#triangles,
+            ...this.#texts,
+            ...this.#d2.points,
+            ...this.#d2.lines,
+            ...this.#d2.joints,
+            ...this.#d2.shapes,
+        ].filter((command) => (command.layer & visibleLayers) !== 0);
+    }
+    seal() {
+        this.assertOpen();
+        this.#sealed = true;
+    }
+    assertOpen() {
+        if (this.#sealed)
+            throw new Error("frame drawList is sealed");
+    }
+}

package/dist/geometry-generators.d.ts

@@ -0,0 +1,101 @@
+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 = {
+    readonly triangles: readonly Triangle[];
+    readonly segments: readonly Segment[];
+};
+export declare function rect(size: readonly [number, number], center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function box(size: Vec3, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function disc(radius: number, segments?: number, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function arc(radius: number, angle: number, segments?: number, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function cylinder(radius: number, halfHeight: number, segments?: number, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function cone(radius: number, height: number, segments?: number, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function sphere(radius: number, segments?: number, rings?: number, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+export declare function capsule(radius: number, halfHeight: number, segments?: number, rings?: number, center?: Vec3, rotation?: readonly [number, number, number]): MeshData;
+/**
+ * Grid line segments, ported from `_emit_grid_lines` in `debug_draw_3d.gd`.
+ *
+ * Alignment contract, which the previous implementation got backwards:
+ * - `outer` selects which boundary lines are **kept**: without `x`, the outermost line
+ *   along X is dropped (`start = 1`, `end = cellCount`); with `x` the full range
+ *   (`0 .. cellCount + 1`) is emitted. So `"none"` keeps only interior lines, and `"xz"`
+ *   keeps every line including both boundaries.
+ * - `skew` slants the lines themselves (`dx.z = sx * tan(skew.y)`,
+ *   `dz.x = sz * tan(skew.x)`), not just an offset.
+ */
+/** Closed paths the reference draws with `draw_line_loop`, plus `draw_line_list` segments. */
+export type ShapeWire = {
+    readonly loops: readonly (readonly Vec3[])[];
+    readonly lines: readonly Segment[];
+};
+/** `_get_cone_base_rotation`: `Basis(width_axis, axis.cross(width_axis), axis)`. */
+export declare function coneBaseBasis(basis: CircleBasis): CircleBasis;
+/** `_get_circle_points`: `center + (basis.x * cos + basis.y * sin) * radius`. */
+export declare function circlePoints(center: Vec3, radius: number, segments: number, basis: CircleBasis): Vec3[];
+/**
+ * `_get_circle_normals`: outward normals of a circle, sampled half a segment ahead of each
+ * point so every segment gets the radial direction at its own midpoint.
+ */
+export declare function circleNormals(segments: number, basis: CircleBasis): Vec3[];
+/** `_get_sphere_ring_normals`: each normal points from the sphere centre through the midpoint. */
+export declare function sphereRingNormals(sphereCenter: Vec3, points: readonly Vec3[]): Vec3[];
+/**
+ * `_get_capsule_side_outline_normals`: project each segment midpoint onto the capsule axis
+ * and use the direction from that axis point as the normal.
+ *
+ * Applied to a cap ring this reproduces `_get_circle_normals` exactly, because the ring
+ * midpoints project onto the cap centre and the resulting directions are the ring radials.
+ */
+export declare function capsuleOutlineNormals(bottomCenter: Vec3, topCenter: Vec3, axis: Vec3, points: readonly Vec3[]): Vec3[];
+/**
+ * `_get_arc_normals`: radial normals at each segment midpoint of an arc sweep. An arc is a
+ * strip, so it takes one normal per segment rather than per vertex.
+ */
+export declare function arcNormals(angle: number, segments: number, basis: CircleBasis): Vec3[];
+/**
+ * `_get_rect_normals`: one normal per corner, in the `_get_rect_points` order `rectLoop` uses
+ * (`-w-h`, `+w-h`, `+w+h`, `-w+h`).
+ */
+export declare function rectNormals(basis: CircleBasis): Vec3[];
+/**
+ * `_get_box_line_normals`, derived from the edges themselves rather than from a fixed table.
+ *
+ * A box edge runs along one basis axis and joins the two faces whose normals are the other two
+ * axes, so its normal is the sum of those two unit axes with the signs of the edge's position.
+ * Deriving it keeps the normals aligned with whatever order the mesh generator emits edges in,
+ * instead of depending on the reference's own point order.
+ */
+export declare function boxEdgeNormals(segments: readonly Segment[], center: Vec3, basis: CircleBasis): Vec3[];
+/** `_get_cone_side_line_normals`: one normal per side line, tilted along the cone slope. */
+export declare function coneSideLineNormals(radius: number, height: number, sideSegmentCount: number, basis: CircleBasis): Vec3[];
+/** `_get_cylinder_side_line_normals`: one radial normal per wall line. */
+export declare function cylinderSideLineNormals(radius: number, halfHeight: number, sideSegmentCount: number, basis: CircleBasis): Vec3[];
+/**
+ * `_emit_sphere_axis_rings`: `y_axis_segment_count` latitude rings plus
+ * `z_axis_segment_count` meridian great circles, de-duplicated by ring key.
+ *
+ * - Latitude rings sit at `radius * (-1 + 2i/n)` for `i in 1..n-1` with ring radius
+ *   `sqrt(r^2 - offset^2)`, so `n < 2` draws none and `n = 2` draws the equator only.
+ * - Great circles all have radius `radius` and advance by `PI / z` around `basis.y`, so
+ *   `z < 1` draws none. A count of `z` yields `ceil(z / 2)` distinct circles, because the
+ *   ring key folds opposite normals together.
+ */
+export declare function sphereWire(radius: number, segments: number, yAxisSegmentCount: number, zAxisSegmentCount: number, center: Vec3, basis: CircleBasis): ShapeWire;
+/**
+ * `_emit_capsule`: bottom/top cylinder rings plus `side_segment_count` closed side
+ * outlines. The reference has no solid capsule variant, so this is the whole wireframe.
+ */
+export declare function capsuleWire(radius: number, halfHeight: number, segments: number, sideSegmentCount: number, center: Vec3, basis: CircleBasis): ShapeWire;
+/**
+ * `_get_cone_base_points` + `_get_cone_side_line_points`: the base ring is a loop and
+ * the side lines are `apex -> base point` pairs emitted as a line list.
+ */
+export declare function coneWire(radius: number, height: number, segments: number, sideSegmentCount: number, center: Vec3, basis: CircleBasis): ShapeWire;
+/**
+ * `_get_cylinder_ring_points` + `_get_cylinder_side_line_points`: two rings and
+ * `side_segment_count` vertical wall segments.
+ */
+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[];