@womp/spark-agent 4.4.1 → 5.0.0

package/dist/sdk-openscad-host.js

@@ -1,8 +1,7 @@
 import { z } from "zod";
-import { getOpenScadGroundedPosition, MAX_PRINTABILITY_REPAIR_ATTEMPTS, requestStableOpenScadPrintability, toOpenScadCompileResponse, } from "./openscad.js";
-import { waitForOpenScadRenderer } from "./sdk-openscad-renderer.js";
+import { getOpenScadGroundedPosition, MAX_PRINTABILITY_REPAIR_ATTEMPTS, requestTurnOpenScadPrintability, toOpenScadCompileResponse, } from "./openscad.js";
 import { createGeometryRepairTracker, createRepairTracker, } from "./repair-state.js";
-import { getSdkSceneAreaId, hasGeometryOverflow, readStableSdkSceneHealth, unverifiedSceneHealth, } from "./scene-health.js";
+import { getSdkSceneAreaId, unverifiedSceneHealth, } from "./scene-health.js";
 const compileMetadata = z.object({
     error: z.string(),
     params: z.array(z.object({ name: z.string() })),
@@ -19,7 +18,6 @@ export function createSdkOpenScadHost(options) {
     const printabilityRepairs = createRepairTracker(options.repairs, "openscad.printability", MAX_PRINTABILITY_REPAIR_ATTEMPTS, (status) => status === "unavailable" ? undefined : status === "failed");
     const pendingTargets = new Set();
     const resolveTarget = async (api, objectId) => {
-        const revision = await api.getSceneRevision();
         const node = objectId === 0 ? undefined : api.getNode(objectId);
         if (objectId === 0 || node?.kind === "union" || node?.kind === "group") {
             return {
@@ -30,18 +28,12 @@ export function createSdkOpenScadHost(options) {
                     title: node?.name ?? "",
                     source: null,
                     params: {},
-                    revision,
                 },
             };
         }
         if (node?.kind !== "openScad")
             throw new Error("The target must be an OpenSCAD part or an Area/Group.");
         const script = api.getOpenScadScript(node.scriptId);
-        let rendererBounds;
-        try {
-            rendererBounds = await api.getNodeBoundingBox(objectId);
-        }
-        catch { }
         return {
             target: {
                 kind: "part",
@@ -50,10 +42,8 @@ export function createSdkOpenScadHost(options) {
                 source: script.source,
                 title: script.name || node.name || "OpenSCAD part",
                 params: structuredClone(node.params ?? {}),
-                revision,
             },
             repairKey: `script:${node.scriptId}`,
-            rendererBounds,
         };
     };
     const write = async (source, targetId, creating, invocation) => {
@@ -68,8 +58,6 @@ export function createSdkOpenScadHost(options) {
         let operationId = "";
         let operationRepairKey = resolved.repairKey;
         try {
-            if (target.revision !== source.expectedRevision)
-                throw new Error("The scene changed. Read it again before editing.");
             if (target.kind !== (creating ? "container" : "part"))
                 throw new Error(creating
                     ? "Creation requires a parent container ID."
@@ -85,63 +73,60 @@ export function createSdkOpenScadHost(options) {
             }
             if (creating && options.canGrow?.() === false)
                 throw new Error("OpenSCAD creation is disabled because scene memory is low.");
-            const params = z
-                .record(z.string(), z.json())
-                .parse({ ...target.params, ...source.params });
-            invocation.reportStatus("running", "Compiling the parametric part...");
-            let rawValidation;
-            try {
-                rawValidation = await editor.read(invocation, (api) => api.validateOpenScad(source.source, params));
-            }
-            catch {
-                invocation.signal.throwIfAborted();
-            }
-            const response = toOpenScadCompileResponse(rawValidation);
-            const metadataAvailable = compileMetadata.safeParse(rawValidation).success;
-            const validation = response && (response.error || metadataAvailable)
-                ? {
-                    status: response.error ? "invalid" : "valid",
-                    error: response.error || undefined,
-                    warnings: response.warnings,
-                }
-                : {
-                    status: "unavailable",
-                    warnings: [
-                        "OpenSCAD validation is unavailable; compilation and parameter validity could not be confirmed.",
-                    ],
-                };
-            if (validation.status === "invalid" ||
-                (creating &&
-                    (validation.status !== "valid" ||
-                        response?.boundingBox === undefined))) {
-                if (creating && response?.boundingBox === undefined)
-                    validation.warnings.push("The part was not added because validated placement bounds are unavailable.");
-                return {
-                    status: "rejected",
-                    objectId,
-                    revision: target.revision,
-                    validation,
-                    repairAttempts: 0,
-                    repairLimit: MAX_PRINTABILITY_REPAIR_ATTEMPTS,
-                };
-            }
-            const validNames = new Set(response && metadataAvailable
-                ? response.params.map((param) => param.name)
-                : Object.keys(params));
-            const nextParams = Object.fromEntries(Object.entries(params).filter(([name]) => validNames.has(name)));
             const receiptTarget = {
                 parentId: target.parentId,
             };
             if (objectId !== undefined)
                 receiptTarget.objectId = objectId;
             let affectedObjectIds = [];
-            let sceneHealth;
-            const applied = await editor.edit({
+            let affectedAreaIds = [];
+            const applied = await editor.access({
                 capability: "openscad",
                 operation: creating ? "create" : "update",
                 target: () => receiptTarget,
-            }, async (_api, draft, id) => {
+            }, async (api, draft, id) => {
                 operationId = id;
+                const current = draft.getNode(targetId);
+                if (creating === false && (current.kind !== "openScad" || `script:${current.scriptId}` !== resolved.repairKey))
+                    throw new Error("The OpenSCAD target changed. Read it again.");
+                const currentParams = current.kind === "openScad" ? current.params : {};
+                const params = z
+                    .record(z.string(), z.json())
+                    .parse({ ...currentParams, ...source.params });
+                invocation.reportStatus("running", "Compiling the parametric part...");
+                let rawValidation;
+                try {
+                    rawValidation = await api.validateOpenScad(source.source, params);
+                }
+                catch {
+                    invocation.signal.throwIfAborted();
+                }
+                const response = toOpenScadCompileResponse(rawValidation);
+                const metadataAvailable = compileMetadata.safeParse(rawValidation).success;
+                const validation = response && (response.error || metadataAvailable)
+                    ? {
+                        status: response.error ? "invalid" : "valid",
+                        ...(response.error ? { error: response.error } : {}),
+                        warnings: response.warnings,
+                    }
+                    : {
+                        status: "unavailable",
+                        warnings: [
+                            "OpenSCAD validation is unavailable; compilation and parameter validity could not be confirmed.",
+                        ],
+                    };
+                if (validation.status === "invalid" ||
+                    (creating &&
+                        (validation.status !== "valid" ||
+                            response?.boundingBox === undefined))) {
+                    if (creating && response?.boundingBox === undefined)
+                        validation.warnings.push("The part was not added because validated placement bounds are unavailable.");
+                    return { rejected: validation };
+                }
+                const validNames = new Set(response && metadataAvailable
+                    ? response.params.map((param) => param.name)
+                    : Object.keys(params));
+                const nextParams = Object.fromEntries(Object.entries(params).filter(([name]) => validNames.has(name)));
                 if (creating === false) {
                     if (resolved.repairKey === undefined)
                         throw new Error("The OpenSCAD repair target is unavailable.");
@@ -158,7 +143,8 @@ export function createSdkOpenScadHost(options) {
                     });
                     draft.setNodeName(targetId, source.title);
                     draft.setOpenScadScript(targetId, node.scriptId, nextParams);
-                    return { objectId: targetId, repairKey: resolved.repairKey };
+                    affectedAreaIds = [...new Set(affectedObjectIds.map(id => Number(getSdkSceneAreaId(draft, id))))];
+                    return { objectId: targetId, repairKey: resolved.repairKey, validation };
                 }
                 if (options.canGrow?.() === false)
                     throw new Error("OpenSCAD creation is disabled because scene memory is low.");
@@ -186,69 +172,46 @@ export function createSdkOpenScadHost(options) {
                 objectId = node.id;
                 affectedObjectIds = [node.id];
                 Object.assign(receiptTarget, { objectId: node.id, parentId });
-                return { objectId: node.id, repairKey: operationRepairKey };
-            }, source.expectedRevision, invocation, async (operation, api) => {
-                if (objectId === undefined)
-                    return;
-                const areaIds = [
-                    ...new Set(affectedObjectIds.map((id) => getSdkSceneAreaId(api, id))),
-                ];
-                try {
-                    const rendererReady = response?.boundingBox === undefined ||
-                        (creating === false && resolved.rendererBounds === undefined)
-                        ? false
-                        : await waitForOpenScadRenderer({
-                            api,
-                            objectId,
-                            expectedBounds: response.boundingBox,
-                            baselineBounds: resolved.rendererBounds,
-                            signal: invocation.signal,
-                        });
-                    sceneHealth = rendererReady
-                        ? await readStableSdkSceneHealth(api, areaIds, invocation.signal)
-                        : unverifiedSceneHealth(areaIds, "The renderer did not confirm the committed OpenSCAD geometry before health checks.");
-                }
-                catch (error) {
-                    sceneHealth = unverifiedSceneHealth(areaIds, `OpenSCAD renderer checks stopped after the edit committed: ${String(error)}`);
-                }
-                options.onHealth?.(sceneHealth);
+                affectedAreaIds = [Number(getSdkSceneAreaId(draft, node.id))];
+                return { objectId: node.id, repairKey: operationRepairKey, validation };
+            }, invocation, async (operation) => {
                 if (operationRepairKey === undefined)
                     return;
-                const recorded = await geometryRepairs.record(operationRepairKey, operation.id, sceneHealth);
+                const recorded = await geometryRepairs.record(operationRepairKey, operation.id, unverifiedSceneHealth([], "Health was not requested."));
                 return {
-                    sceneHealth,
                     affectedObjectIds,
                     geometryRepairAttempts: recorded.repairAttempts,
                     geometryRepairLimit: recorded.repairLimit,
                 };
             });
+            if (applied.value.rejected)
+                return {
+                    status: "rejected", objectId, validation: applied.value.rejected,
+                    repairAttempts: 0, repairLimit: MAX_PRINTABILITY_REPAIR_ATTEMPTS,
+                };
+            const { validation } = applied.value;
             objectId = applied.value.objectId;
             try {
                 await options.onSelect?.(objectId);
             }
             catch { }
-            const revision = applied.operation.resultRevision ?? source.expectedRevision;
-            if (sceneHealth?.status === "unverified" ||
-                (sceneHealth !== undefined && hasGeometryOverflow(sceneHealth))) {
-                await printabilityRepairs.refund(applied.value.repairKey, operationId);
+            // Geometry repairs do not consume the independent printability budget.
+            // Explicit health must resolve the known geometry failure first.
+            if (repairingGeometry) {
                 return {
                     status: "applied",
                     objectId,
-                    revision,
                     validation,
                     repairAttempts: 0,
                     repairLimit: MAX_PRINTABILITY_REPAIR_ATTEMPTS,
                 };
             }
             invocation.reportStatus("running", "Checking wall thickness...");
-            const printability = await editor.read(invocation, (api, beginSettlement) => (options.requestPrintability ?? requestStableOpenScadPrintability)({
+            const printability = await editor.withConnection(invocation, (api, beginSettlement) => (options.requestPrintability ?? requestTurnOpenScadPrintability)({
                 api,
-                expectedRevision: revision,
                 signal: invocation.signal,
                 onSubmissionStarted: beginSettlement,
-                objectIds: [
-                    ...new Set(affectedObjectIds.map((id) => Number(getSdkSceneAreaId(api, id)))),
-                ],
+                objectIds: affectedAreaIds,
             }));
             invocation.signal.throwIfAborted();
             if (printability.reason === "context_busy") {
@@ -256,7 +219,6 @@ export function createSdkOpenScadHost(options) {
                 return {
                     status: "applied",
                     objectId,
-                    revision,
                     validation,
                     printability,
                     repairAttempts: refunded.repairAttempts,
@@ -267,7 +229,6 @@ export function createSdkOpenScadHost(options) {
             return {
                 status: "applied",
                 objectId,
-                revision,
                 validation,
                 printability,
                 repairAttempts: recorded.repairAttempts,

package/dist/sdk-scene-health-host.d.ts

@@ -1,4 +1,5 @@
 import type { SceneHealthHost } from "./capabilities.js";
 import { type SdkSceneEditor } from "./sdk-scene-host.js";
+import { type RepairStateStore } from "./repair-state.js";
 import type { SceneHealth } from "./scene-health.js";
-export declare function createSdkSceneHealthHost(editor: SdkSceneEditor, onHealth?: (health: SceneHealth) => void): SceneHealthHost;
+export declare function createSdkSceneHealthHost(editor: SdkSceneEditor, onHealth?: (health: SceneHealth) => void, repairs?: RepairStateStore): SceneHealthHost;

package/dist/sdk-scene-health-host.js

@@ -1,4 +1,5 @@
-import { getSdkSceneAreaId, getSdkSceneAreaIds, readStableSdkSceneHealth, } from "./scene-health.js";
+import { getSdkSceneAreaId, getSdkSceneAreaIds, readSdkSceneHealth, parseSceneHealth, } from "./scene-health.js";
+import { createGeometryRepairTracker } from "./repair-state.js";
 /**
  * The Area that owns `objectId`, or undefined when the node is in no Area --
  * the scene root 0, a root-level Group, a Light. The engine's thermometer has a
@@ -9,25 +10,74 @@ function owningAreaId(api, objectId) {
     const areaId = getSdkSceneAreaId(api, objectId);
     return api.getNode(Number(areaId)).kind === "union" ? areaId : undefined;
 }
-export function createSdkSceneHealthHost(editor, onHealth) {
+// Health is requested explicitly. Feed its checked Areas back to the same
+// target budgets used by writes, without spending an attempt or settling an
+// operation. A partial reading must not clear a linked target's other Areas.
+async function observeRepairs(api, health, store) {
+    if (health.thermometer === undefined)
+        return;
+    const targets = new Map();
+    const add = (namespace, target, objectId) => {
+        const area = owningAreaId(api, objectId);
+        if (area === undefined)
+            return;
+        const key = `${namespace}:${target}`;
+        const entry = targets.get(key) ?? { namespace, target, areas: new Set() };
+        entry.areas.add(area);
+        targets.set(key, entry);
+    };
+    const unions = api.listNodes({ kind: "union" });
+    const scripts = api.getSceneStorage().scripts;
+    const instances = scripts && typeof scripts === "object" && !Array.isArray(scripts)
+        ? scripts.instances : undefined;
+    for (const node of unions) {
+        if (node.kind !== "union" || node.scriptInstanceId === undefined)
+            continue;
+        const instance = instances && typeof instances === "object" && !Array.isArray(instances)
+            ? instances[node.scriptInstanceId] : undefined;
+        if (instance && typeof instance === "object" && !Array.isArray(instance)
+            && typeof instance.graph_id === "number") {
+            add("geometry", String(instance.graph_id), node.id);
+        }
+    }
+    for (const node of api.listNodes({ kind: "openScad" })) {
+        if (node.kind === "openScad")
+            add("openscad.geometry", `script:${node.scriptId}`, node.id);
+    }
+    const checked = new Set(health.affectedAreaIds);
+    for (const { namespace, target, areas } of targets.values()) {
+        if ([...areas].some((id) => !checked.has(id)))
+            continue;
+        const scoped = parseSceneHealth(health.thermometer, [...areas]);
+        // A zero-count Area does not prove that its output is healthy, even if
+        // another Area in the full thermometer has an overflow flag.
+        if (scoped.emptyAreaIds?.some((id) => areas.has(id)))
+            continue;
+        await createGeometryRepairTracker(store, namespace).observe(target, scoped);
+    }
+}
+export function createSdkSceneHealthHost(editor, onHealth, repairs) {
     return {
         read: (objectIds, context) => editor.read(context, async (api) => {
             const owned = objectIds
                 .map((id) => ({ id, areaId: owningAreaId(api, id) }))
                 .filter((entry) => entry.areaId !== undefined);
-            // `scene.read()` publishes node 0, and ids outside any Area are legal
+            // `scene.access()` publishes node 0, and ids outside any Area are legal
             // arguments. They narrow nothing, so they are reported rather than
             // allowed to make the whole reading unverified; with nothing left to
             // narrow by, this is the whole-scene read `health()` already means.
             const outside = objectIds.filter((id) => owned.some((entry) => entry.id === id) === false);
             const areaIds = owned.length > 0 ? owned.map((entry) => entry.areaId) : getSdkSceneAreaIds(api);
-            const health = await readStableSdkSceneHealth(api, [...new Set(areaIds)], context.signal);
+            const health = await readSdkSceneHealth(api, [...new Set(areaIds)], context.signal);
             const note = outside.length === 0
                 ? undefined
                 : `${outside.join(", ")} ${outside.length === 1 ? "is" : "are"} in no Area, and the engine reports health per Area, so ${owned.length > 0 ? "health is reported for the remaining ids" : "this is the whole scene's health"}.`;
             const reported = note === undefined
                 ? health
                 : { ...health, reason: health.reason === undefined ? note : `${health.reason} ${note}` };
+            context.signal.throwIfAborted();
+            if (repairs)
+                await observeRepairs(api, reported, repairs);
             onHealth?.(reported);
             return reported;
         }),

package/dist/sdk-scene-host.d.ts

@@ -1,4 +1,4 @@
-import type { FontFamily, KakapoAPI, SceneEdit, MaterialResource } from "@womp/kakapo-sdk";
+import type { FontFamily, KakapoAPI, SceneEdit, MaterialResource, NativeSceneSnapshot } from "@womp/kakapo-sdk";
 import type { ArtifactRef, SparkInvocationContext } from "./capabilities.js";
 import type { SceneHost, SceneHealthHost, SceneScreenshotOptions } from "./capabilities/scene.js";
 import { type SceneOperation, type SceneOperationStore } from "./scene-operations.js";
@@ -24,10 +24,10 @@ export type SdkSceneEditorOptions = {
     /** Supply this when the host adds a stricter connection lifetime. */
     context?: SparkInvocationContext) => Promise<T>): Promise<T>;
     assertEditable(context: SparkInvocationContext): void | Promise<void>;
-    /** Acquire after preparation. Cleanup receives false until rollback or host synchronization is confirmed. */
-    prepareCommit?(operation: SceneOperation, context: SparkInvocationContext): Promise<(synchronized: boolean) => void | Promise<void>>;
+    /** Suspend for the complete access, including reads and failed preparation. */
+    acquireAccess?(context: SparkInvocationContext): Promise<(synchronized: boolean) => void | Promise<void>>;
     /** Must adopt each operation ID at most once, including during recovery. */
-    onCommitted?(operation: SceneOperation, api: KakapoAPI, context: SparkInvocationContext, identity: SdkSceneEditIdentity): Promise<Record<string, unknown> | void>;
+    onCommitted?(operation: SceneOperation, api: KakapoAPI, context: SparkInvocationContext, identity: SdkSceneEditIdentity, scene: NativeSceneSnapshot): Promise<Record<string, unknown> | void>;
 };
 export type SdkSceneEditIdentity = {
     capability: string;
@@ -36,8 +36,9 @@ export type SdkSceneEditIdentity = {
 };
 export type SdkSceneEditor = {
     getOperation(operationId: string): Promise<SceneOperation | undefined>;
+    withConnection<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void) => T | Promise<T>): Promise<T>;
     read<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void) => T | Promise<T>): Promise<T>;
-    edit<T>(identity: SdkSceneEditIdentity, callback: (api: KakapoAPI, draft: SceneEdit, operationId: string) => T | Promise<T>, expectedRevision: string, context: SparkInvocationContext, afterCommitted?: (operation: SceneOperation, api: KakapoAPI) => Promise<Record<string, unknown> | void>): Promise<{
+    access<T>(identity: SdkSceneEditIdentity, callback: (api: KakapoAPI, draft: SceneEdit, operationId: string) => T | Promise<T>, context: SparkInvocationContext, afterCommitted?: (operation: SceneOperation, api: KakapoAPI) => Promise<Record<string, unknown> | void>): Promise<{
         value: T;
         operation: SceneOperation;
     }>;
@@ -308,6 +309,20 @@ export declare function createSdkSceneDraft(api: KakapoAPI, scene: SceneEdit, se
         g: number;
         b: number;
     }) => void;
+    unitMultiplier: number;
+    nodes(options?: {
+        ids?: number[];
+        type?: number;
+        parentId?: number;
+        name?: string;
+        offset?: number;
+        limit?: number;
+    }): {
+        id: number;
+        name: string;
+        type: number;
+        parentId: number;
+    }[];
 };
 export declare function createSdkSceneEditor(options: SdkSceneEditorOptions): SdkSceneEditor;
 export declare function createSdkSceneHost(options: SdkSceneEditorOptions & {

package/dist/sdk-scene-host.js

@@ -1,8 +1,15 @@
-import { createWompSceneApi, sceneNodeType } from "./womp-scene-api.js";
-import { sceneUnitMultiplier } from "./coordinates.js";
+import { createWompSceneApi } from "./womp-scene-api.js";
 import { executeSceneOperation, } from "./scene-operations.js";
 import { readMaterialMetadata, writeMaterialMetadata, } from "./scene-metadata.js";
 import { boundedReceiptDetails } from "./scene-health.js";
+function assertSceneSaved(operation) {
+    if (!operation.changed)
+        return;
+    if (operation.save?.status === "failed")
+        throw new Error(`The scene edit was applied, but the save failed: ${operation.save.error} Do not repeat the edit.`);
+    if (operation.save?.status === "unknown" || operation.save?.status === "requested")
+        throw new Error("The scene edit was applied, but its save outcome is unknown. Inspect persistence before continuing; do not repeat the edit.");
+}
 export function createSdkSceneDraft(api, scene, services) {
     let defaultMaterialId = scene
         .listMaterials()
@@ -59,13 +66,17 @@ export function createSdkSceneEditor(options) {
     const ordinals = new WeakMap();
     return {
         getOperation: (operationId) => options.operations.getSceneOperation(options.targetKey, operationId),
+        withConnection: (context, action) => options.withConnection(context, async (api, settle, active = context) => {
+            active.signal.throwIfAborted();
+            return action(api, settle);
+        }),
         read: (context, action) => options.withConnection(context, async (api, beginSettlement, activeContext = context) => {
             activeContext.signal.throwIfAborted();
-            await api.refreshScene();
+            await api.refreshScene({ returnScene: false });
             activeContext.signal.throwIfAborted();
             return action(api, beginSettlement);
         }),
-        edit: (identity, callback, expectedRevision, context, afterCommitted) => {
+        access: (identity, callback, context, afterCommitted) => {
             const operationKey = `${identity.capability}.${identity.operation}`;
             const contextOrdinals = ordinals.get(context) ?? new Map();
             ordinals.set(context, contextOrdinals);
@@ -89,6 +100,8 @@ export function createSdkSceneEditor(options) {
                 });
                 let releaseCommit;
                 let synchronized = false;
+                let saveSettled = true;
+                let committedScene;
                 let hostDetails = {};
                 const record = async (operation, details) => {
                     hostDetails = { ...hostDetails, ...details };
@@ -113,6 +126,8 @@ export function createSdkSceneEditor(options) {
                     });
                 };
                 try {
+                    releaseCommit = await options.acquireAccess?.(activeContext);
+                    synchronized = true;
                     let result;
                     try {
                         result = await executeSceneOperation({
@@ -122,20 +137,20 @@ export function createSdkSceneEditor(options) {
                             operation: {
                                 id,
                                 targetKey: options.targetKey,
-                                expectedRevision,
                             },
                             assertEditable: async () => {
                                 activeContext.signal.throwIfAborted();
                                 await options.assertEditable(activeContext);
                             },
                             edit: (draft) => callback(api, draft, id),
+                            onCommittedScene: scene => { committedScene = scene; },
                             prepareCommit: async (operation) => {
                                 await activeContext.recordReceipt({
                                     ...receipt(),
                                     status: "unknown",
                                 });
-                                releaseCommit = await options.prepareCommit?.(operation, activeContext);
                                 beginSettlement();
+                                synchronized = false;
                             },
                         });
                     }
@@ -153,12 +168,19 @@ export function createSdkSceneEditor(options) {
                         }
                         throw error;
                     }
+                    saveSettled = !result.operation.changed || !["unknown", "requested"].includes(result.operation.save?.status ?? "");
+                    // A duplicate returns its journaled result; retain its original receipt
+                    // and let explicit recovery handle any earlier synchronization failure.
+                    if (result.reused) {
+                        assertSceneSaved(result.operation);
+                        return result;
+                    }
                     synchronized = !result.operation.changed || !options.onCommitted;
                     await record(result.operation);
                     if (!synchronized) {
                         let details;
                         try {
-                            details = await options.onCommitted(result.operation, api, activeContext, identity);
+                            details = await options.onCommitted(result.operation, api, activeContext, identity, committedScene);
                             synchronized = true;
                         }
                         catch (error) {
@@ -175,11 +197,7 @@ export function createSdkSceneEditor(options) {
                         await record(result.operation, details || undefined);
                     }
                     if (result.operation.changed) {
-                        if (result.operation.save?.status === "failed")
-                            throw new Error(`The scene edit was applied, but the save failed: ${result.operation.save.error} Do not repeat the edit.`);
-                        if (result.operation.save?.status === "unknown" ||
-                            result.operation.save?.status === "requested")
-                            throw new Error("The scene edit was applied, but its save outcome is unknown. Inspect persistence before continuing; do not repeat the edit.");
+                        assertSceneSaved(result.operation);
                         const details = await afterCommitted?.(result.operation, api);
                         if (details)
                             await record(result.operation, details);
@@ -187,7 +205,7 @@ export function createSdkSceneEditor(options) {
                     return result;
                 }
                 finally {
-                    await releaseCommit?.(synchronized);
+                    await releaseCommit?.(synchronized && saveSettled);
                 }
             });
         },
@@ -197,23 +215,8 @@ export function createSdkSceneHost(options) {
     const editor = options.editor ?? createSdkSceneEditor(options);
     return {
         health: options.health?.read.bind(options.health),
-        read: (context) => editor.read(context, async (api) => {
-            const scene = api.getScene();
-            const revision = await api.getSceneRevision();
-            return {
-                revision,
-                projectId: options.projectId,
-                unitMultiplier: sceneUnitMultiplier(scene.properties.unit_multiplier),
-                nodes: Object.values(scene.nodes).map(({ id, name, kind, parentId }) => ({
-                    id,
-                    name,
-                    type: sceneNodeType(kind),
-                    parentId: parentId ?? 0,
-                })),
-            };
-        }),
-        edit: (callback, expectedRevision, context) => editor
-            .edit({ capability: "scene", operation: "edit" }, async (api, draft) => {
+        access: (callback, context) => editor
+            .access({ capability: "scene", operation: "access" }, async (api, draft) => {
             const services = await options.services(api, context);
             let active = true;
             const scopedDraft = new Proxy(draft, {
@@ -234,7 +237,7 @@ export function createSdkSceneHost(options) {
             finally {
                 active = false;
             }
-        }, expectedRevision, context, options.onSceneCommitted)
+        }, context, options.onSceneCommitted)
             .then(({ value }) => value),
         screenshot: options.screenshot,
     };

package/dist/sdk-scene-screenshot.d.ts

@@ -1,5 +1,5 @@
 import type { KakapoAPI } from "@womp/kakapo-sdk";
 import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 import type { ExecutionScreenshot } from "./types.js";
-/** Convert Womp scene coordinates at the host boundary; never fit a camera implicitly. */
-export declare function captureSdkSceneScreenshot(api: KakapoAPI, input: SceneScreenshotOptions): Promise<ExecutionScreenshot>;
+/** Capture the current native viewport without fetching the scene or changing its camera. */
+export declare function captureSdkSceneScreenshot(api: KakapoAPI, _input: SceneScreenshotOptions): Promise<ExecutionScreenshot>;

package/dist/sdk-scene-screenshot.js

@@ -1,17 +1,4 @@
-import { INTERNAL_UNITS_PER_MM, sceneUnitMultiplier, toEnginePosition } from "./coordinates.js";
-/** Convert Womp scene coordinates at the host boundary; never fit a camera implicitly. */
-export async function captureSdkSceneScreenshot(api, input) {
-    if (!input.camera)
-        return api.captureScreenshot({ timeoutMs: 30_000 });
-    const scene = await api.refreshScene();
-    const units = sceneUnitMultiplier(scene.properties.unit_multiplier);
-    const camera = {
-        ...input.camera,
-        position: toEnginePosition(input.camera.position, units),
-        target: toEnginePosition(input.camera.target, units),
-    };
-    if (camera.orthographicWidth !== undefined)
-        camera.orthographicWidth *= INTERNAL_UNITS_PER_MM / units;
-    await api.setCamera(camera);
-    return api.captureScreenshot({ camera, timeoutMs: 30_000 });
+/** Capture the current native viewport without fetching the scene or changing its camera. */
+export async function captureSdkSceneScreenshot(api, _input) {
+    return api.captureScreenshot({ timeoutMs: 30_000 });
 }

package/dist/server/scene-access.d.ts

@@ -0,0 +1,4 @@
+export declare function standaloneSceneAccess(url: string): {
+    release(synchronized: boolean): void;
+    run<T>(signal: AbortSignal, action: (signal: AbortSignal, beginSettlement: () => void) => Promise<T>): Promise<T>;
+};

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;
+        },
+    };
+}