@womp/spark-agent 4.4.0 → 5.0.0

package/dist/server/scene-access.js

@@ -0,0 +1,40 @@
+/** One queue per native renderer, shared by every standalone run in this process. */
+const renderers = new Map();
+export function standaloneSceneAccess(url) {
+    const key = new URL(url).href;
+    let access = renderers.get(key);
+    if (!access) {
+        access = createSceneAccess();
+        renderers.set(key, access);
+    }
+    return access;
+}
+function createSceneAccess() {
+    let tail = Promise.resolve();
+    let uncertain = false;
+    return {
+        release(synchronized) {
+            if (!synchronized)
+                uncertain = true;
+        },
+        run(signal, action) {
+            const result = tail.then(async () => {
+                signal.throwIfAborted();
+                if (uncertain)
+                    throw new Error("The renderer has an uncertain scene commit. Inspect it before restarting standalone scene access; do not repeat the edit.");
+                const active = new AbortController();
+                const abort = () => active.abort(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+                const beginSettlement = () => signal.removeEventListener("abort", abort);
+                try {
+                    return await action(active.signal, beginSettlement);
+                }
+                finally {
+                    beginSettlement();
+                }
+            });
+            tail = result.then(() => { }, () => { });
+            return result;
+        },
+    };
+}

package/dist/server/standalone.js

@@ -3,7 +3,7 @@ import { createOpenAI } from "@ai-sdk/openai";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import express from "express";
 import { getSparkModel, SPARK_MODELS } from "../models.js";
-import { KakapoAPI, KakapoRpcError } from "@womp/kakapo-sdk";
+import { KakapoAPI, KakapoRpcError, KakapoSceneCommitError } from "@womp/kakapo-sdk";
 import { captureSdkSceneScreenshot } from "../sdk-scene-screenshot.js";
 import { composeCapabilities, createAccountCapability, createGeometryCapability, createOpenScadCapability, createSceneCapability, } from "../capabilities.js";
 import { loadDemoSceneMaterials } from "./demo-scene-materials.js";
@@ -13,7 +13,7 @@ import { createSdkGeometryHost } from "../sdk-geometry-host.js";
 import { createSdkOpenScadHost } from "../sdk-openscad-host.js";
 import { createSdkSceneHealthHost } from "../sdk-scene-health-host.js";
 import { geometryReference } from "../geometry.js";
-import { getSdkSceneAreaIds, hasSceneResourcePressure, readStableSdkSceneHealth, } from "../scene-health.js";
+import { hasSceneResourcePressure, } from "../scene-health.js";
 import { QuickJSJavaScriptExecutor } from "../quickjs-executor.js";
 import { sparkModelOptions } from "../model-options.js";
 import { createSparkRunExecutor } from "./executor.js";
@@ -21,7 +21,7 @@ import { createSparkAgentRouter } from "./express.js";
 import { SparkAgentService } from "./service.js";
 import { SqliteSparkStore } from "./sqlite-store.js";
 import { clearSceneContents } from "./scene-actions.js";
-import { initializeStandaloneScene } from "./scene-initialization.js";
+import { standaloneSceneAccess } from "./scene-access.js";
 export async function checkStandaloneServices(api) {
     const [fonts, openScad] = await Promise.allSettled([
         api.listFonts(),
@@ -57,6 +57,7 @@ export async function createStandaloneSparkAgentApp(options) {
         throw error;
     }
     const artifactStore = store;
+    const sceneAccess = standaloneSceneAccess(options.kakapoUrl);
     const executeRun = createSparkRunExecutor({
         createHost: async (context) => {
             const api = new KakapoAPI({
@@ -65,9 +66,7 @@ export async function createStandaloneSparkAgentApp(options) {
             });
             try {
                 context.signal.throwIfAborted();
-                await api.connect();
-                context.signal.throwIfAborted();
-                await initializeStandaloneScene(api, context.signal);
+                await api.connect({ refreshScene: false });
                 context.signal.throwIfAborted();
                 const support = await checkStandaloneServices(api);
                 const services = {
@@ -81,12 +80,12 @@ export async function createStandaloneSparkAgentApp(options) {
                     targetKey,
                     operations: store,
                     saveToRenderer: true,
-                    withConnection: async (invocation, action) => {
-                        invocation.signal.throwIfAborted();
+                    withConnection: (invocation, action) => sceneAccess.run(invocation.signal, async (signal, beginSettlement) => {
                         if (!api.isConnected)
                             throw new Error("The Kakapo connection was interrupted; reconnect before continuing");
-                        return action(api, () => { }, invocation);
-                    },
+                        return action(api, beginSettlement, { ...invocation, signal });
+                    }),
+                    acquireAccess: async () => sceneAccess.release,
                     assertEditable: () => {
                         if (!api.isConnected)
                             throw new Error("The Kakapo connection is unavailable");
@@ -103,16 +102,11 @@ export async function createStandaloneSparkAgentApp(options) {
                 const sceneHost = createSdkSceneHost({
                     ...editorOptions,
                     editor,
-                    health: createSdkSceneHealthHost(editor, onHealth),
-                    onSceneCommitted: async (_operation, api) => {
-                        const sceneHealth = await readStableSdkSceneHealth(api, getSdkSceneAreaIds(api), context.signal);
-                        onHealth(sceneHealth);
-                        return { sceneHealth };
-                    },
+                    health: createSdkSceneHealthHost(editor, onHealth, repairs),
                     services: async () => services,
                     screenshot: async (settings, invocation) => {
                         invocation.signal.throwIfAborted();
-                        const image = await captureSdkSceneScreenshot(api, settings);
+                        const image = await editor.withConnection(invocation, activeApi => captureSdkSceneScreenshot(activeApi, settings));
                         options.onScreenshot?.(context.runId);
                         invocation.signal.throwIfAborted();
                         return artifactStore.write(context.ownerId, image);
@@ -254,8 +248,19 @@ export async function createStandaloneSparkAgentApp(options) {
         clearingScene = true;
         const api = new KakapoAPI({ url: options.kakapoUrl, requestTimeoutMs: 30_000 });
         try {
-            await api.connect();
-            const { save } = await api.editSceneAndSave(clearSceneContents);
+            await api.connect({ refreshScene: false });
+            const { save } = await sceneAccess.run(new AbortController().signal, async () => {
+                try {
+                    const result = await api.accessScene(clearSceneContents, { save: true });
+                    sceneAccess.release(result.save.status !== "unknown");
+                    return result;
+                }
+                catch (error) {
+                    if (error instanceof KakapoSceneCommitError && error.outcome === "unknown")
+                        sceneAccess.release(false);
+                    throw error;
+                }
+            });
             const warning = save.status === "failed" || save.status === "unknown"
                 ? `Scene cleared, but saving ${save.status === "failed" ? "failed" : "could not be confirmed"}: ${save.error} Do not repeat the clear operation.`
                 : undefined;

package/dist/simple-bench-prompts.d.ts

@@ -1,28 +1,5 @@
-export declare const BENCH_PROMPTS: readonly [{
-    readonly id: "armchair";
-    readonly prompt: "Make a mustard-yellow upholstered armchair, 85 cm wide, 90 cm deep, and 85 cm tall. Give it a thick square seat cushion, a slightly reclined backrest, rounded armrests, and four short tapered wooden legs.";
-}, {
-    readonly id: "desk-lamp";
-    readonly prompt: "Make a matte-black desk lamp, 45 cm tall, with a circular base 18 cm in diameter, two slender articulated arms, and a conical shade 15 cm wide. Give the shade a white interior and a warm-white bulb.";
-}, {
-    readonly id: "coffee-mug";
-    readonly prompt: "Make a teal ceramic mug, 10 cm tall and 9 cm in diameter, with a gently rounded base, an open top, a thick rim, and a large C-shaped handle. Give it a cream-colored interior.";
-}, {
-    readonly id: "bookshelf";
-    readonly prompt: "Make a light-oak bookshelf, 180 cm tall, 90 cm wide, and 30 cm deep. Give it five evenly spaced open compartments, thick rectangular side panels, a solid back panel, and a recessed base.";
-}, {
-    readonly id: "backpack";
-    readonly prompt: "Make a navy-blue backpack, 45 cm tall, 30 cm wide, and 18 cm deep. Give it a rounded rectangular body, a large front zipper pocket, two padded shoulder straps, a top carry handle, and light-gray zipper pulls.";
-}, {
-    readonly id: "toaster";
-    readonly prompt: "Make a cream-colored two-slot toaster, 28 cm wide, 18 cm deep, and 20 cm tall. Give it rounded corners, a brushed-metal top, two long bread slots, a silver side lever, and a circular browning dial.";
-}, {
-    readonly id: "plant-pot";
-    readonly prompt: "Make a terracotta plant pot, 25 cm tall, tapering from a 30 cm opening to a 20 cm base. Give it a thick rolled rim and dark soil containing a small plant with six broad green leaves on short stems.";
-}, {
-    readonly id: "suitcase";
-    readonly prompt: "Make a burgundy hard-shell suitcase, 65 cm tall, 42 cm wide, and 26 cm deep. Give it rounded corners, five vertical ribs on each broad face, four black spinner wheels, a silver telescoping handle, and a black side carry handle.";
-}, {
-    readonly id: "dining-table";
-    readonly prompt: "Make a rectangular walnut dining table, 160 cm long, 90 cm wide, and 75 cm tall. Give it a 4 cm thick tabletop with softly rounded corners, four square tapered legs, and a recessed wooden apron beneath the top.";
-}];
+export declare const BENCH_ORIENTATION = "Orient the object upright (+Y), with its front facing +Z and its base centered at the origin.";
+export declare const BENCH_PROMPTS: {
+    prompt: string;
+    id: string;
+}[];

package/dist/simple-bench-prompts.js

@@ -1,3 +1,4 @@
+export const BENCH_ORIENTATION = "Orient the object upright (+Y), with its front facing +Z and its base centered at the origin.";
 export const BENCH_PROMPTS = [
     { id: "armchair", prompt: "Make a mustard-yellow upholstered armchair, 85 cm wide, 90 cm deep, and 85 cm tall. Give it a thick square seat cushion, a slightly reclined backrest, rounded armrests, and four short tapered wooden legs." },
     { id: "desk-lamp", prompt: "Make a matte-black desk lamp, 45 cm tall, with a circular base 18 cm in diameter, two slender articulated arms, and a conical shade 15 cm wide. Give the shade a white interior and a warm-white bulb." },
@@ -8,4 +9,4 @@ export const BENCH_PROMPTS = [
     { id: "plant-pot", prompt: "Make a terracotta plant pot, 25 cm tall, tapering from a 30 cm opening to a 20 cm base. Give it a thick rolled rim and dark soil containing a small plant with six broad green leaves on short stems." },
     { id: "suitcase", prompt: "Make a burgundy hard-shell suitcase, 65 cm tall, 42 cm wide, and 26 cm deep. Give it rounded corners, five vertical ribs on each broad face, four black spinner wheels, a silver telescoping handle, and a black side carry handle." },
     { id: "dining-table", prompt: "Make a rectangular walnut dining table, 160 cm long, 90 cm wide, and 75 cm tall. Give it a 4 cm thick tabletop with softly rounded corners, four square tapered legs, and a recessed wooden apron beneath the top." },
-];
+].map(item => ({ ...item, prompt: `${item.prompt} ${BENCH_ORIENTATION}` }));

package/dist/simple-bench.js

@@ -2,7 +2,7 @@ import { once } from "node:events";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { KakapoAPI } from "@womp/kakapo-sdk";
-import { z } from "zod";
+import { benchCamera, benchGeometryIds } from "./bench-camera.js";
 import { SparkChatTransport } from "./client.js";
 import { createStandaloneSparkAgentApp } from "./server/standalone.js";
 import { BENCH_PROMPTS } from "./simple-bench-prompts.js";
@@ -40,7 +40,7 @@ export async function runSimpleBench(options) {
     const report = async () => {
         await writeFile(path.join(options.output, "results.json"), JSON.stringify({
             version: 1, startedAt, nodeVersion: process.version, settings: options.settings,
-            timeoutMs: options.timeoutMs, camera: "fitted-perspective-preserving-direction", plannedPrompts: prompts.map((item) => item.id),
+            timeoutMs: options.timeoutMs, camera: "fixed-three-quarter-v3", plannedPrompts: prompts.map((item) => item.id),
             totalCost: totalBenchCost(results), results,
         }, null, 2));
         const columns = ["id", "status", "steps", "readSkill", "executeJavaScript", "screenshots", "durationMs", "costUsd", "costStatus", "image", "error"];
@@ -100,30 +100,18 @@ export async function runSimpleBench(options) {
                 const api = new KakapoAPI({ url: options.kakapoUrl, requestTimeoutMs: 30_000 });
                 try {
                     await api.connect();
-                    const ids = api.listNodes({ parentId: 0 })
-                        .filter((node) => node.kind !== "light" && (!("hidden" in node) || !node.hidden))
-                        .map((node) => node.id);
+                    const snapshot = await api.rpc("scene_state_get");
+                    await writeFile(path.join(options.output, `${item.id}.scene.json`), typeof snapshot === "string" ? snapshot : JSON.stringify(snapshot));
+                    const ids = benchGeometryIds(api);
                     const bounds = await api.getNodesBoundingBox(ids);
                     const viewport = await api.captureScreenshot({});
-                    const { camera } = await api.refreshScene();
-                    const direction = z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).parse(camera.dir);
-                    const directionLength = Math.hypot(direction.x, direction.y, direction.z);
-                    if (directionLength === 0)
-                        throw new Error("Cannot frame a scene with a zero camera direction.");
-                    const target = {
-                        x: (bounds.min.x + bounds.max.x) / 2,
-                        y: (bounds.min.y + bounds.max.y) / 2,
-                        z: (bounds.min.z + bounds.max.z) / 2,
-                    };
-                    const radius = Math.hypot(bounds.max.x - bounds.min.x, bounds.max.y - bounds.min.y, bounds.max.z - bounds.min.z) / 2;
-                    const halfAngle = Math.atan(Math.tan(Math.PI / 6) * Math.min(1, viewport.height / viewport.width));
-                    const offset = Math.max(0.1, radius * 1.1 / Math.sin(halfAngle)) / directionLength;
-                    const image = await api.captureScreenshot({ camera: {
-                            position: { x: target.x - direction.x * offset, y: target.y - direction.y * offset, z: target.z - direction.z * offset },
-                            target, projection: "perspective", horizontalFovDegrees: 60,
-                        }, timeoutMs: 30_000 });
+                    const camera = benchCamera(bounds, viewport.width / viewport.height);
+                    await writeFile(path.join(options.output, `${item.id}.framing.json`), JSON.stringify({ ids, bounds, width: viewport.width, height: viewport.height, cameras: { "three-quarter": camera } }, null, 2));
+                    const image = await api.captureScreenshot({ camera, timeoutMs: 30_000 });
+                    if (image.width !== viewport.width || image.height !== viewport.height)
+                        throw new Error("Viewport changed during benchmark capture.");
+                    await writeFile(path.join(options.output, `${item.id}.jpg`), image.data);
                     result.image = `${item.id}.jpg`;
-                    await writeFile(path.join(options.output, result.image), image.data);
                 }
                 finally {
                     api.disconnect();

package/dist/womp-scene-api.d.ts

@@ -164,8 +164,20 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     nodeGetLightType: (id: number) => number;
     nodeSetLightType: (id: number, lightType: number) => void;
     nodeGetPower: (id: number) => number;
+    /** Linear emitted intensity before collimation; not a percentage or physical unit. */
     nodeSetPower: (id: number, power: number) => void;
     nodeGetText: (id: number) => string;
+    /** Aim light emission or the readable text/decal face using target minus node position in parent-local coordinates. Use instead of generic lookAt for these faces. Y-up, Z-up when vertical. */
+    nodeSetFacing: (id: number, direction: Vec3) => void;
+    /** Font em size and extrusion depth in project units, not text bounding-box dimensions. */
+    nodeSetTextSize: (id: number, size: {
+        fontSize: number;
+        depth: number;
+    }) => void;
+    nodeGetTextSize: (id: number) => {
+        fontSize: number;
+        depth: number;
+    };
     nodeSetText: (id: number, text: string) => void;
     nodeGetFont: (id: number) => string;
     nodeSetFont: (id: number, font: string) => void;
@@ -177,8 +189,10 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     nodeSetAlign: (id: number, align: number) => void;
     nodeGetWrap: (id: number) => number;
     nodeSetWrap: (id: number, wrap: number) => void;
+    /** Text layout width in project units, including owning Area scale. */
     nodeGetWidth: (id: number) => number;
     nodeSetWidth: (id: number, width: number) => void;
+    /** Additional letter spacing in project units, including owning Area scale. */
     nodeGetSpacing: (id: number) => number;
     nodeSetSpacing: (id: number, spacing: number) => void;
     nodeGetLineHeight: (id: number) => number;
@@ -272,6 +286,7 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
     nodeResize: (id: number, dimensions: Partial<Vec3>) => Promise<void>;
     aabbCenter: (box: AABB) => Vec3;
     aabbRadius: (box: AABB) => number;
+    /** Align local +Z from origin toward target, not a light's emission or a text/decal face; use nodeSetFacing for those. */
     lookAt: typeof lookAt;
     alignAxis: typeof alignAxis;
     scenePropertiesRead: () => {
@@ -291,5 +306,20 @@ export declare function createWompSceneApi(context: WompSceneApiContext): {
         g: number;
         b: number;
     }) => void;
+    unitMultiplier: number;
+    /** Current draft summaries. Filters precede pagination; defaults to 100 results, maximum 1000. */
+    nodes(options?: {
+        ids?: number[];
+        type?: number;
+        parentId?: number;
+        name?: string;
+        offset?: number;
+        limit?: number;
+    }): {
+        id: number;
+        name: string;
+        type: number;
+        parentId: number;
+    }[];
 };
 export {};

package/dist/womp-scene-api.js

@@ -1,8 +1,8 @@
-import { xyzRotationFromMatrix, MAX_BLEND_RADIUS_MM, MAX_MIRROR_BLEND_RADIUS_MM } from "@womp/kakapo-sdk";
+import { xyzRotationFromMatrix, MAX_BLEND_RADIUS_MM, MAX_MIRROR_BLEND_RADIUS_MM, maxLightIntensity } from "@womp/kakapo-sdk";
 import { metadataObject, readMaterialMetadata, removeMaterialMetadata, shiftCurvePointMetadata, writeMaterialMetadata, } from "./scene-metadata.js";
 import { createSceneEnvironment } from "./scene-environment.js";
 import { assertColor255 } from "./color.js";
-import { convertRotationBasis, sceneUnitMultiplier, fromEngineDimensions, fromEngineMirrorRotation, fromEnginePosition, toEngineDimensions, toEngineMirrorRotation, toEnginePosition, } from "./coordinates.js";
+import { INTERNAL_UNITS_PER_MM, convertRotationBasis, sceneUnitMultiplier, fromEngineDimensions, fromEngineMirrorRotation, fromEnginePosition, toEngineDimensions, toEngineMirrorRotation, toEnginePosition, } from "./coordinates.js";
 export const NodeType = {
     Primitive: 0,
     Union: 1,
@@ -395,6 +395,8 @@ export function createWompSceneApi(context) {
             const y = finite(sizeValue?.y, "size.y");
             if (x <= 0 || y <= 0)
                 throw new Error("Light size.x and size.y must be positive");
+            if ("z" in sizeValue)
+                finite(sizeValue.z, "size.z");
             const converted = toEngineDimensions({ x, y, z: 1 }, unitMultiplier);
             update(id, { size: { x: converted.z, y: converted.y } });
             return;
@@ -434,6 +436,23 @@ export function createWompSceneApi(context) {
         return converted;
     };
     const api = {
+        get unitMultiplier() {
+            return sceneUnitMultiplier(scene.getSceneProperties().unit_multiplier);
+        },
+        /** Current draft summaries. Filters precede pagination; defaults to 100 results, maximum 1000. */
+        nodes(options = {}) {
+            const { offset = 0, limit = 100 } = options;
+            if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 1000)
+                throw new Error("nodes() requires a nonnegative integer offset and a limit from 1 to 1000");
+            const ids = options.ids === undefined ? undefined : new Set(options.ids);
+            const query = options.name?.toLowerCase();
+            return scene.listNodeSummaries().filter(({ id, name, kind, parentId }) => (ids === undefined || ids.has(id)) &&
+                (options.type === undefined || sceneNodeType(kind) === options.type) &&
+                (options.parentId === undefined || (parentId ?? 0) === options.parentId) &&
+                (query === undefined || name.toLowerCase().includes(query))).slice(offset, offset + limit).map(({ id, name, kind, parentId }) => ({
+                id, name, type: sceneNodeType(kind), parentId: parentId ?? 0,
+            }));
+        },
         ...createSceneEnvironment(scene, context.hdrs, context.print),
         listSuperMaterials: () => {
             if (!context.superMaterialNames)
@@ -609,7 +628,7 @@ export function createWompSceneApi(context) {
         nodeSetLock: (id, locked) => {
             requireNode(id);
             const current = metadataObject(scene.getSceneExt([String(id)])[String(id)]);
-            scene.patchSceneExt([{ op: "add", path: `/${id}`, value: { ...current, locked: Boolean(locked) } }]);
+            scene.patchSceneExt([{ op: "add", path: `/${id}`, value: { ...current, locked: Boolean(locked) } }], { returnScene: false });
         },
         nodeSetPos: (id, position) => {
             requireEditableTransform(id);
@@ -643,7 +662,7 @@ export function createWompSceneApi(context) {
             return "operation" in node ? OPERATIONS.indexOf(node.operation) : OperationType.Union;
         },
         nodeSetOp: (id, operation) => {
-            const value = OPERATIONS[Math.round(finite(operation, "operation"))];
+            const value = OPERATIONS[finite(operation, "operation")];
             if (!value)
                 throw new Error("Operation must be from 0 to 3");
             const node = requireNode(id);
@@ -701,51 +720,113 @@ export function createWompSceneApi(context) {
         },
         nodeGetLightType: (id) => LIGHT_TYPES.indexOf(requireLight(id).lightType),
         nodeSetLightType: (id, lightType) => {
-            const value = LIGHT_TYPES[Math.round(finite(lightType, "lightType"))];
+            requireLight(id);
+            const value = LIGHT_TYPES[finite(lightType, "lightType")];
             if (!value)
-                throw new Error("LightType must be from 0 to 2");
+                throw new Error("LightType must be an integer from 0 to 2");
             update(id, { lightType: value });
         },
         nodeGetPower: (id) => requireLight(id).power,
+        /** Linear emitted intensity before collimation; not a percentage or physical unit. */
         nodeSetPower: (id, power) => {
-            requireLight(id);
-            if (!Number.isFinite(power) || power < 0 || power > 100)
-                throw new Error(`Light ${id}: power must be a finite number from 0 through 100`);
+            const light = requireLight(id);
+            const max = maxLightIntensity(light.lightType);
+            if (!Number.isFinite(power) || power < 0 || power > max)
+                throw new Error(`Light ${id} (${light.lightType}): linear intensity must be a finite number from 0 through ${max}`);
             update(id, { power });
         },
         nodeGetText: (id) => requireText(id).text,
-        nodeSetText: (id, text) => update(id, { text: String(text) }),
+        /** Aim light emission or the readable text/decal face using target minus node position in parent-local coordinates. Use instead of generic lookAt for these faces. Y-up, Z-up when vertical. */
+        nodeSetFacing: (id, direction) => {
+            requireNode(id);
+            const value = vector(direction, "direction");
+            const nativeDirection = { x: -value.z, y: value.y, z: -value.x };
+            const up = Math.abs(value.y) / Math.hypot(value.x, value.y, value.z) > 1 - 1e-8
+                ? { x: -1, y: 0, z: 0 } : { x: 0, y: 1, z: 0 };
+            context.call("setNodeFacing", [id, nativeDirection, up], () => scene.setNodeFacing(id, nativeDirection, up));
+        },
+        /** Font em size and extrusion depth in project units, not text bounding-box dimensions. */
+        nodeSetTextSize: (id, size) => {
+            requireText(id);
+            const fontSize = finite(size?.fontSize, "fontSize");
+            const depth = finite(size?.depth, "depth");
+            if (fontSize <= 0 || depth <= 0)
+                throw new Error("Text fontSize and depth must be positive");
+            const factor = INTERNAL_UNITS_PER_MM / ancestorScale(id);
+            const nativeSize = {
+                fontSize: clamp(fontSize / unitMultiplier, 0.01, 1000) * factor,
+                depth: clamp(depth / unitMultiplier, 0.01, 1000) * factor,
+            };
+            context.call("setTextSize", [id, nativeSize], () => scene.setTextSize(id, nativeSize));
+        },
+        nodeGetTextSize: (id) => {
+            const node = requireText(id);
+            const factor = ancestorScale(id) * unitMultiplier / INTERNAL_UNITS_PER_MM;
+            return { fontSize: node.transform.scale.x * factor, depth: node.transform.scale.z * factor };
+        },
+        nodeSetText: (id, text) => {
+            requireText(id);
+            if (typeof text !== "string")
+                throw new Error("text must be a string; use an empty string to clear it");
+            update(id, { text });
+        },
         nodeGetFont: (id) => requireText(id).fontFamily,
         nodeSetFont: (id, font) => {
+            requireText(id);
+            if (typeof font !== "string" || !font.trim())
+                throw new Error("font must be a non-empty font family name");
+            if (!context.fonts.length)
+                throw new Error("Font catalog is unavailable; this host cannot validate a new font selection");
             const match = context.fonts.find((family) => family.name.toLowerCase() === font.toLowerCase());
-            if (!match && context.fonts.length)
-                throw new Error(`Unknown font "${font}"`);
+            if (!match)
+                throw new Error(`Unknown font "${font}"; choose a family from the font catalog`);
             update(id, { fontFamily: match?.name ?? font });
         },
         nodeGetWeight: (id) => requireText(id).weight,
-        nodeSetWeight: (id, weight) => update(id, { weight: clamp(finite(weight, "weight"), 100, 900) }),
+        nodeSetWeight: (id, weight) => {
+            requireText(id);
+            update(id, { weight: clamp(finite(weight, "weight"), 100, 900) });
+        },
         nodeGetItalic: (id) => requireText(id).italic,
-        nodeSetItalic: (id, italic) => update(id, { italic: Boolean(italic) }),
+        nodeSetItalic: (id, italic) => {
+            requireText(id);
+            if (typeof italic !== "boolean")
+                throw new Error("italic must be a boolean");
+            update(id, { italic });
+        },
         nodeGetAlign: (id) => ALIGNS.indexOf(requireText(id).align),
         nodeSetAlign: (id, align) => {
-            const value = ALIGNS[Math.round(finite(align, "align"))];
+            requireText(id);
+            const value = ALIGNS[finite(align, "align")];
             if (!value)
-                throw new Error("Align must be from 0 to 2");
+                throw new Error("Align must be an integer from 0 to 2");
             update(id, { align: value });
         },
         nodeGetWrap: (id) => WRAPS.indexOf(requireText(id).wrap),
         nodeSetWrap: (id, wrap) => {
-            const value = WRAPS[Math.round(finite(wrap, "wrap"))];
+            requireText(id);
+            const value = WRAPS[finite(wrap, "wrap")];
             if (!value)
-                throw new Error("Wrap must be from 0 to 2");
+                throw new Error("Wrap must be an integer from 0 to 2");
             update(id, { wrap: value });
         },
-        nodeGetWidth: (id) => requireText(id).width,
-        nodeSetWidth: (id, width) => update(id, { width: finite(width, "width") }),
-        nodeGetSpacing: (id) => requireText(id).spacing,
-        nodeSetSpacing: (id, spacing) => update(id, { spacing: clamp(finite(spacing, "spacing"), -1, 1) }),
+        /** Text layout width in project units, including owning Area scale. */
+        nodeGetWidth: (id) => requireText(id).width * ancestorScale(id) * unitMultiplier / INTERNAL_UNITS_PER_MM,
+        nodeSetWidth: (id, width) => {
+            requireText(id);
+            update(id, { width: finite(width, "width") * INTERNAL_UNITS_PER_MM / unitMultiplier / ancestorScale(id) });
+        },
+        /** Additional letter spacing in project units, including owning Area scale. */
+        nodeGetSpacing: (id) => requireText(id).spacing * ancestorScale(id) * unitMultiplier / INTERNAL_UNITS_PER_MM,
+        nodeSetSpacing: (id, spacing) => {
+            requireText(id);
+            update(id, { spacing: clamp(finite(spacing, "spacing") / unitMultiplier, -25, 25) * INTERNAL_UNITS_PER_MM / ancestorScale(id) });
+        },
         nodeGetLineHeight: (id) => requireText(id).lineHeight,
-        nodeSetLineHeight: (id, lineHeight) => update(id, { lineHeight: clamp(finite(lineHeight, "lineHeight"), 0.5, 3) }),
+        nodeSetLineHeight: (id, lineHeight) => {
+            requireText(id);
+            update(id, { lineHeight: clamp(finite(lineHeight, "lineHeight"), 0.5, 3) });
+        },
         nodeGetDensity: (id) => requireCurve(id).density,
         nodeSetDensity: (id, density) => update(id, { density: clamp(Math.round(finite(density, "density")), 0, 250) }),
         nodeGetRoundness: (id) => requireCurve(id).roundness,
@@ -762,7 +843,7 @@ export function createWompSceneApi(context) {
             return value;
         },
         nodeSetPrimType: (id, primitive) => {
-            const value = PUBLIC_PRIMITIVES.get(Math.round(finite(primitive, "primitive")));
+            const value = PUBLIC_PRIMITIVES.get(finite(primitive, "primitive"));
             if (!value)
                 throw new Error("PrimitiveType must be Sphere, Cylinder, Cube, Cone, Torus, or Pyramid");
             const node = requireNode(id);
@@ -991,6 +1072,7 @@ export function createWompSceneApi(context) {
             z: (box.min.z + box.max.z) / 2,
         }),
         aabbRadius: (box) => Math.hypot(box.max.x - box.min.x, box.max.y - box.min.y, box.max.z - box.min.z) / 2,
+        /** Align local +Z from origin toward target, not a light's emission or a text/decal face; use nodeSetFacing for those. */
         lookAt,
         alignAxis,
     };