@skenora/sdk 0.1.2

package/dist/skenora-scene.js

@@ -0,0 +1,832 @@
+import { assertSceneDocument, createEmptySceneDocument, normalizeSceneDocument, } from "@skenora/contracts";
+import { addEntityCommand, createProceduralEntityCommand, createPrimitiveCommand, importModelCommand, removeAssetCommand, removeEntityCommand, removeLightCommand, reparentEntityCommand, replaceDocumentCommand, setEntityEnabledCommand, setEntityTransformCommand, setEntityVisibleCommand, setEnvironmentCommand, setFogCommand, setGroundCommand, setPostProcessCommand, setPropertyCommand, setWeatherCommand, setViewportCameraCommand, upsertAssetCommand, upsertLightCommand, upsertMaterialCommand, } from "@skenora/editor";
+import { EditorSession } from "@skenora/editor";
+import { createCausationMetadata, EventHub, } from "@skenora/events";
+import { assetReferenceFromDescriptor, supportsResourceDiscovery, } from "@skenora/resources";
+import { createWorkspaceResourceContext, } from "@skenora/resources/workspace";
+import { EditorFlowBridge, EditorRuntimeBridge, } from "@skenora/babylon-editor";
+import { RUNTIME_CAMERA_CAPABILITY, RuntimeSession, } from "@skenora/runtime/projection";
+import { DEFAULT_SCENE_FILE, MemoryWorkspaceSource, WorkspaceSession, } from "@skenora/workspace";
+import { applySceneConfig, exportSceneJsonBundle, getSceneConfig, parseSceneConfig, parseSceneJson, serializeSceneConfig, serializeSceneJson, } from "./scene-config.js";
+import { getSkenoraPlaybackConfig, normalizeSkenoraPlaybackConfig, SKENORA_PLAYBACK_EXTENSION_ID, } from "./playback-config.js";
+import { ScenePlanExecutor } from "./scene-plan/executor.js";
+import { ScenePlanGateway } from "./scene-plan/gateway.js";
+/**
+ * High-level, instance-scoped scene SDK.
+ *
+ * Persistent writes are translated to EditorCommand objects. Runtime state is
+ * always a disposable projection of the current SceneDocument snapshot.
+ */
+export class SkenoraScene {
+    events;
+    #options;
+    #ownsEvents;
+    #workspace = null;
+    #resources = null;
+    #resourceContext = null;
+    #editor = null;
+    #runtime = null;
+    #bridge = null;
+    #scenePlanExecutor = null;
+    #scenePlan = null;
+    #flow = null;
+    #lifetime = null;
+    #initializing = null;
+    #modelFailures = [];
+    #previewing = false;
+    #status = "idle";
+    #error = null;
+    constructor(options) {
+        this.#options = options;
+        this.events = options.events ?? new EventHub();
+        this.#ownsEvents = options.events === undefined;
+    }
+    static async create(options) {
+        const scene = new SkenoraScene(options);
+        try {
+            await scene.init();
+            return scene;
+        }
+        catch (error) {
+            scene.dispose();
+            throw error;
+        }
+    }
+    get status() {
+        return this.#status;
+    }
+    get error() {
+        return this.#error;
+    }
+    get ready() {
+        return this.#status === "ready";
+    }
+    get modelFailures() {
+        return Object.freeze(this.#modelFailures.map((item) => ({ ...item })));
+    }
+    get workspace() {
+        this.#assertReady();
+        return this.#workspace;
+    }
+    get editor() {
+        this.#assertReady();
+        return this.#editor;
+    }
+    get resources() {
+        this.#assertReady();
+        return this.#resources;
+    }
+    get runtime() {
+        this.#assertReady();
+        return this.#runtime;
+    }
+    getBackendSnapshot() {
+        return this.runtime.getBackendSnapshot();
+    }
+    getGpuProgramCacheSnapshot() {
+        return this.runtime.getGpuProgramCacheSnapshot();
+    }
+    probe() {
+        return this.runtime.probe();
+    }
+    get flow() {
+        this.#assertReady();
+        return this.#flow;
+    }
+    /** Declarative SceneBlueprint/ScenePatch gateway for AI and host callers. */
+    get scenePlan() {
+        this.#assertReady();
+        return this.#scenePlan;
+    }
+    get selectionController() {
+        this.#assertReady();
+        return this.#bridge.selection;
+    }
+    get document() {
+        return this.editor.snapshot;
+    }
+    get revision() {
+        return this.editor.revision;
+    }
+    get dirty() {
+        return this.editor.dirty;
+    }
+    /** Whether manually requested scene behavior preview is active. */
+    get previewing() {
+        return this.#previewing;
+    }
+    get selection() {
+        return this.editor.selection;
+    }
+    get canUndo() {
+        return this.editor.canUndo;
+    }
+    get canRedo() {
+        return this.editor.canRedo;
+    }
+    async init() {
+        if (this.#status === "ready")
+            return this;
+        if (this.#status === "disposed") {
+            throw new Error("SkenoraScene has been disposed");
+        }
+        if (this.#initializing)
+            return (await this.#initializing);
+        const initializing = this.#initialize();
+        this.#initializing = initializing;
+        try {
+            return (await initializing);
+        }
+        finally {
+            if (this.#initializing === initializing)
+                this.#initializing = null;
+        }
+    }
+    on(type, handler, signal) {
+        return this.events.subscribe(type, handler, signal ? { signal } : {});
+    }
+    getConfig(section) {
+        return section
+            ? getSceneConfig(this.document, section)
+            : structuredClone(this.document);
+    }
+    getJson(sectionOrOptions, options = {}) {
+        return typeof sectionOrOptions === "string"
+            ? serializeSceneConfig(this.document, sectionOrOptions, options)
+            : serializeSceneJson(this.document, sectionOrOptions ?? {});
+    }
+    exportJson(options = {}) {
+        return options.mode === "split"
+            ? exportSceneJsonBundle(this.document, options)
+            : serializeSceneJson(this.document, options);
+    }
+    async loadConfig(document) {
+        const owned = normalizeSceneDocument(structuredClone(document));
+        assertSceneDocument(owned);
+        return this.#execute(replaceDocumentCommand(owned, "Load scene config"));
+    }
+    async loadJson(input) {
+        return this.loadConfig(parseSceneJson(input));
+    }
+    async applyConfig(section, config) {
+        const next = applySceneConfig(this.document, section, config);
+        return this.#execute(replaceDocumentCommand(next, `Apply ${section} config`));
+    }
+    async applyJson(section, json) {
+        return this.applyConfig(section, parseSceneConfig(json, section));
+    }
+    async setEnvironment(update) {
+        const current = this.document.environment;
+        return this.#execute(setEnvironmentCommand({
+            ...current,
+            ...update,
+            background: {
+                ...current.background,
+                ...update.background,
+            },
+        }));
+    }
+    async setScene(update) {
+        const commands = [];
+        if (update.id !== undefined) {
+            commands.push(setPropertyCommand(["id"], update.id, "Set scene id"));
+        }
+        if (update.name !== undefined) {
+            commands.push(setPropertyCommand(["name"], update.name, "Set scene name"));
+        }
+        return this.#executeMany("Update scene", commands);
+    }
+    async setSky(update) {
+        const current = this.document.environment;
+        const background = {
+            ...current.background,
+            ...(update.mode === undefined ? {} : { mode: update.mode }),
+            ...(update.color === undefined ? {} : { color: update.color }),
+            ...(update.blur === undefined ? {} : { blur: update.blur }),
+        };
+        if (update.backgroundAssetId === null)
+            delete background.assetId;
+        else if (update.backgroundAssetId !== undefined) {
+            background.assetId = update.backgroundAssetId;
+        }
+        if (update.skybox === null)
+            delete background.skybox;
+        else if (update.skybox !== undefined) {
+            background.skybox = structuredClone(update.skybox);
+        }
+        const next = {
+            ...current,
+            background,
+            ...(update.intensity === undefined
+                ? {}
+                : { intensity: update.intensity }),
+            ...(update.rotationY === undefined
+                ? {}
+                : { rotationY: update.rotationY }),
+        };
+        if (update.environmentAssetId === null)
+            delete next.assetId;
+        else if (update.environmentAssetId !== undefined) {
+            next.assetId = update.environmentAssetId;
+            next.enabled = true;
+        }
+        return this.#execute(setEnvironmentCommand(next));
+    }
+    async setViewportCamera(update) {
+        const current = this.document.camera;
+        return this.#execute(setViewportCameraCommand({
+            ...current,
+            ...update,
+            position: { ...current.position, ...update.position },
+            target: { ...current.target, ...update.target },
+        }));
+    }
+    async setGround(update) {
+        return this.#execute(setGroundCommand({ ...this.document.ground, ...update }));
+    }
+    async setFog(update) {
+        const current = this.document.fog;
+        return this.#execute(setFogCommand({
+            ...current,
+            ...update,
+            color: { ...current.color, ...update.color },
+        }));
+    }
+    async setWeather(update) {
+        const current = this.document.weather;
+        return this.#execute(setWeatherCommand({
+            ...current,
+            ...update,
+            wind: { ...current.wind, ...update.wind },
+        }));
+    }
+    async setPostProcess(update) {
+        const current = this.document.postProcess;
+        return this.#execute(setPostProcessCommand({
+            ...current,
+            ...update,
+            colorCurves: {
+                ...current.colorCurves,
+                ...update.colorCurves,
+            },
+            ssao: { ...current.ssao, ...update.ssao },
+        }));
+    }
+    async setLights(lights) {
+        return this.#execute(setPropertyCommand(["lights"], [...lights], "Set scene lights"));
+    }
+    async upsertLight(light) {
+        return this.#execute(upsertLightCommand(light));
+    }
+    async removeLight(lightId) {
+        return this.#execute(removeLightCommand(lightId));
+    }
+    async upsertAsset(asset) {
+        return this.#execute(upsertAssetCommand(asset));
+    }
+    async searchResources(query = {}) {
+        this.#assertReady();
+        if (!supportsResourceDiscovery(this.resources)) {
+            throw new Error("Configured resource resolver does not support search");
+        }
+        return this.resources.search(query);
+    }
+    async describeResource(locator) {
+        this.#assertReady();
+        if (!supportsResourceDiscovery(this.resources)) {
+            throw new Error("Configured resource resolver does not support describe");
+        }
+        return this.resources.describe(locator);
+    }
+    async attachResource(descriptor, assetId) {
+        const asset = assetReferenceFromDescriptor(descriptor, assetId);
+        await this.upsertAsset(asset);
+        return this.document.assets[assetId];
+    }
+    async preflightResources(assetIds = Object.keys(this.document.assets)) {
+        this.#assertReady();
+        if (!supportsResourceDiscovery(this.resources)) {
+            throw new Error("Configured resource resolver does not support preflight");
+        }
+        const assets = assetIds.map((assetId) => {
+            const asset = this.document.assets[assetId];
+            if (!asset)
+                throw new Error(`Asset not found: ${assetId}`);
+            return asset;
+        });
+        return this.resources.preflight(assets);
+    }
+    async removeAsset(assetId) {
+        return this.#execute(removeAssetCommand(assetId));
+    }
+    async upsertMaterial(material) {
+        return this.#execute(upsertMaterialCommand(material));
+    }
+    async addModel(input) {
+        this.#assertReady();
+        const asset = typeof input.asset === "string"
+            ? this.document.assets[input.asset]
+            : input.asset;
+        if (!asset)
+            throw new Error(`Model asset not found: ${input.asset}`);
+        const commands = [
+            importModelCommand(asset, input.id, input.name ?? asset.label ?? "Model"),
+        ];
+        if (input.parentId !== undefined) {
+            commands.push(reparentEntityCommand(input.id, input.parentId));
+        }
+        if (input.transform !== undefined) {
+            commands.push(setEntityTransformCommand(input.id, input.transform));
+        }
+        if (input.alignment !== undefined) {
+            commands.push(setPropertyCommand(["entities", input.id, "properties"], { alignment: structuredClone(input.alignment) }, "Align model"));
+        }
+        if (input.enabled !== undefined) {
+            commands.push(setEntityEnabledCommand(input.id, input.enabled));
+        }
+        if (input.visible !== undefined) {
+            commands.push(setEntityVisibleCommand(input.id, input.visible));
+        }
+        await this.#executeMany("Add model", commands);
+        return this.#requireEntity(input.id);
+    }
+    async importModel(input) {
+        this.#assertReady();
+        const primary = {
+            file: input.file,
+            ...(input.relativePath === undefined
+                ? {}
+                : { relativePath: input.relativePath }),
+        };
+        const imported = await this.workspace.importModelBundle(primary, input.dependencies ?? [], {
+            ...(input.targetDirectory === undefined
+                ? {}
+                : { targetDirectory: input.targetDirectory }),
+            ...(input.conflict === undefined ? {} : { conflict: input.conflict }),
+        });
+        const baseId = normalizeId(input.file.name.replace(/\.(?:glb|gltf)$/iu, ""));
+        const assetId = input.assetId ?? availableId(this.document.assets, baseId || "model");
+        const entityId = input.entityId ?? availableId(this.document.entities, assetId);
+        const asset = {
+            id: assetId,
+            uri: imported.primaryPath,
+            source: { type: "workspace", path: imported.primaryPath },
+            kind: "model",
+            label: input.name ?? input.file.name,
+            ...(input.file.type ? { mediaType: input.file.type } : {}),
+        };
+        const entity = await this.addModel({
+            id: entityId,
+            asset,
+            name: input.name ?? input.file.name,
+            ...(input.transform === undefined ? {} : { transform: input.transform }),
+            ...(input.alignment === undefined ? {} : { alignment: input.alignment }),
+        });
+        return { ...imported, asset, entity };
+    }
+    async updateEntity(entityId, update) {
+        this.#requireEntity(entityId);
+        const commands = [];
+        if (update.name !== undefined) {
+            commands.push(setPropertyCommand(["entities", entityId, "name"], update.name, "Rename entity"));
+        }
+        if (update.parentId !== undefined) {
+            commands.push(reparentEntityCommand(entityId, update.parentId));
+        }
+        if (update.transform !== undefined) {
+            commands.push(setEntityTransformCommand(entityId, update.transform));
+        }
+        if (update.alignment !== undefined) {
+            const entity = this.#requireModel(entityId);
+            commands.push(setPropertyCommand(["entities", entityId, "properties"], {
+                ...entity.properties,
+                alignment: structuredClone(update.alignment),
+            }, "Align model"));
+        }
+        if (update.enabled !== undefined) {
+            commands.push(setEntityEnabledCommand(entityId, update.enabled));
+        }
+        if (update.visible !== undefined) {
+            commands.push(setEntityVisibleCommand(entityId, update.visible));
+        }
+        await this.#executeMany("Update entity", commands);
+        return this.#requireEntity(entityId);
+    }
+    async setModelTransform(entityId, transform) {
+        this.#requireModel(entityId);
+        return this.#execute(setEntityTransformCommand(entityId, transform));
+    }
+    async setModelAlignment(entityId, alignment) {
+        const entity = this.#requireModel(entityId);
+        return this.#execute(setPropertyCommand(["entities", entityId, "properties"], {
+            ...entity.properties,
+            alignment: structuredClone(alignment),
+        }, "Align model"));
+    }
+    async setModelVisible(entityId, visible) {
+        this.#requireModel(entityId);
+        return this.#execute(setEntityVisibleCommand(entityId, visible));
+    }
+    async setModelMaterial(entityId, material) {
+        this.#requireModel(entityId);
+        return this.#execute(upsertMaterialCommand({
+            ...material,
+            targetEntityId: entityId,
+        }));
+    }
+    async removeModel(entityId, options = {}) {
+        const entity = this.#requireModel(entityId);
+        const commands = [removeEntityCommand(entityId)];
+        if (options.removeAsset && entity.assetId) {
+            commands.push(removeAssetCommand(entity.assetId));
+        }
+        return this.#executeMany("Remove model", commands);
+    }
+    async addPrimitive(options) {
+        await this.#execute(createPrimitiveCommand(options));
+        return this.#requireEntity(options.id);
+    }
+    async addProcedural(options) {
+        await this.#execute(createProceduralEntityCommand(options));
+        return this.#requireEntity(options.id);
+    }
+    async addEntity(entity) {
+        await this.#execute(addEntityCommand(entity));
+        return this.#requireEntity(entity.id);
+    }
+    async removeEntity(entityId) {
+        return this.#execute(removeEntityCommand(entityId));
+    }
+    getEntity(entityId) {
+        return this.document.entities[entityId] ?? null;
+    }
+    getEntities() {
+        return Object.freeze(Object.values(this.document.entities));
+    }
+    select(entityIds) {
+        this.editor.select(entityIds);
+    }
+    async execute(command) {
+        return this.#execute(command);
+    }
+    async executeMany(label, commands) {
+        return this.#executeMany(label, commands);
+    }
+    async undo() {
+        this.#assertReady();
+        const change = this.editor.undo();
+        await this.#bridge.flush();
+        return change;
+    }
+    async redo() {
+        this.#assertReady();
+        const change = this.editor.redo();
+        await this.#bridge.flush();
+        return change;
+    }
+    async save(path, options = {}) {
+        this.#assertReady();
+        await this.workspace.saveDocument(structuredClone(this.document), path, options);
+        this.editor.markSaved();
+    }
+    async checkpoint(sourcePath = null) {
+        this.#assertReady();
+        return this.workspace.checkpointDocument(structuredClone(this.document), sourcePath);
+    }
+    async listCheckpoints(documentId = this.document.id) {
+        this.#assertReady();
+        return this.workspace.listCheckpoints(documentId);
+    }
+    async restoreCheckpoint(checkpointPath, documentPath = this.workspace.documentPath ?? DEFAULT_SCENE_FILE) {
+        this.#assertReady();
+        await this.workspace.restoreCheckpoint(checkpointPath, documentPath);
+        const restored = await this.workspace.loadDocument(documentPath);
+        await this.loadConfig(restored);
+        this.editor.markSaved();
+    }
+    frame(entityIds) {
+        this.runtime.capabilities
+            .require(RUNTIME_CAMERA_CAPABILITY)
+            .frame(entityIds);
+    }
+    showGrid(visible) {
+        return this.runtime.showGrid(visible);
+    }
+    getPlaybackConfig() {
+        return getSkenoraPlaybackConfig(this.document);
+    }
+    async setPlaybackConfig(config) {
+        const normalized = normalizeSkenoraPlaybackConfig(config);
+        return this.#execute(setPropertyCommand(["extensions", SKENORA_PLAYBACK_EXTENSION_ID], normalized, "Set renderer playback"));
+    }
+    async startFlows(payload) {
+        this.#assertReady();
+        if (!this.#flow)
+            throw new Error("Flow support is disabled");
+        await this.#flow.controller.start(payload);
+        this.events.publish("flow.changed", { running: this.#flow.controller.running }, { source: "sdk" });
+    }
+    stopFlows() {
+        this.#assertReady();
+        if (!this.#flow)
+            return 0;
+        const cancelled = this.#flow.controller.stop();
+        this.events.publish("flow.changed", { running: false }, { source: "sdk" });
+        return cancelled;
+    }
+    /**
+     * Manually starts document behaviors and Flow while keeping authoring APIs
+     * available. Editor initialization itself never starts preview.
+     */
+    async startPreview(payload) {
+        this.#assertReady();
+        if (this.#previewing)
+            return;
+        this.runtime.startDocumentBehaviors();
+        this.#previewing = true;
+        this.events.publish("preview.changed", { running: true }, { source: "sdk" });
+        try {
+            if (this.#flow) {
+                const start = this.#flow.controller.start(payload);
+                this.events.publish("flow.changed", { running: this.#flow.controller.running }, { source: "sdk" });
+                await start;
+            }
+        }
+        catch (error) {
+            this.#flow?.controller.stop();
+            this.runtime.stopDocumentBehaviors();
+            this.#previewing = false;
+            this.events.publish("flow.changed", { running: false }, { source: "sdk" });
+            this.events.publish("preview.changed", { running: false }, { source: "sdk" });
+            throw error;
+        }
+    }
+    /** Stops manual preview without unloading the editable scene. */
+    stopPreview() {
+        this.#assertReady();
+        const cancelled = this.#flow?.controller.stop() ?? 0;
+        this.runtime.stopDocumentBehaviors();
+        const changed = this.#previewing;
+        this.#previewing = false;
+        if (this.#flow) {
+            this.events.publish("flow.changed", { running: false }, { source: "sdk" });
+        }
+        if (changed) {
+            this.events.publish("preview.changed", { running: false }, { source: "sdk" });
+        }
+        return cancelled;
+    }
+    dispose() {
+        if (this.#status === "disposed")
+            return;
+        this.#lifetime?.abort();
+        this.#previewing = false;
+        this.#flow?.dispose();
+        this.#scenePlanExecutor?.dispose();
+        this.#bridge?.dispose();
+        this.#runtime?.dispose();
+        this.#editor?.dispose();
+        this.#resourceContext?.ownedResources?.dispose();
+        this.#workspace?.dispose();
+        this.#flow = null;
+        this.#scenePlan = null;
+        this.#scenePlanExecutor = null;
+        this.#bridge = null;
+        this.#runtime = null;
+        this.#editor = null;
+        this.#resources = null;
+        this.#resourceContext = null;
+        this.#workspace = null;
+        this.#lifetime = null;
+        this.#setStatus("disposed");
+        if (this.#ownsEvents)
+            this.events.dispose();
+    }
+    async #initialize() {
+        this.#setStatus("initializing");
+        const source = this.#options.source ?? new MemoryWorkspaceSource();
+        const workspace = new WorkspaceSession(source);
+        const resourceContext = createWorkspaceResourceContext(source, {
+            ...(this.#options.resources
+                ? { resources: this.#options.resources }
+                : {}),
+            ...(this.#options.resourceProviders
+                ? { resourceProviders: this.#options.resourceProviders }
+                : {}),
+        });
+        const resources = resourceContext.resources;
+        let editor = null;
+        let runtime = null;
+        let bridge = null;
+        let scenePlanExecutor = null;
+        let scenePlan = null;
+        let flow = null;
+        const lifetime = new AbortController();
+        this.#lifetime = lifetime;
+        try {
+            const document = await this.#resolveInitialDocument(workspace);
+            throwIfInitializationCancelled(lifetime.signal);
+            editor = new EditorSession(document, this.#options.editor);
+            runtime = new RuntimeSession(this.#options.canvas, {
+                adaptToDeviceRatio: true,
+                ...this.#options.runtime,
+                executionMode: "authoring",
+            });
+            bridge = new EditorRuntimeBridge(editor, runtime, resources, {
+                modelLoadPolicy: "best-effort",
+                ...this.#options.bridge,
+            });
+            const capabilityAvailability = runtime.getCapabilityAvailability();
+            scenePlanExecutor = new ScenePlanExecutor({
+                editor,
+                bridge,
+                resources,
+                capabilities: capabilityAvailability.map(({ id, version }) => ({
+                    id,
+                    version,
+                })),
+                getCapabilityAvailability: () => runtime.getCapabilityAvailability(),
+                signal: lifetime.signal,
+            });
+            scenePlan = new ScenePlanGateway(scenePlanExecutor);
+            flow =
+                this.#options.flow === false
+                    ? null
+                    : new EditorFlowBridge(editor, runtime, {
+                        ...this.#options.flow,
+                        startOnFlowChange: false,
+                    });
+            this.#workspace = workspace;
+            this.#resources = resources;
+            this.#resourceContext = resourceContext;
+            this.#editor = editor;
+            this.#runtime = runtime;
+            this.#bridge = bridge;
+            this.#scenePlanExecutor = scenePlanExecutor;
+            this.#scenePlan = scenePlan;
+            this.#flow = flow;
+            this.#bindEvents(lifetime.signal);
+            await bridge.initialize();
+            throwIfInitializationCancelled(lifetime.signal);
+            this.#setStatus("ready");
+            return this;
+        }
+        catch (error) {
+            const disposed = this.#status === "disposed";
+            lifetime.abort();
+            flow?.dispose();
+            scenePlanExecutor?.dispose();
+            bridge?.dispose();
+            runtime?.dispose();
+            editor?.dispose();
+            resourceContext.ownedResources?.dispose();
+            workspace.dispose();
+            this.#flow = null;
+            this.#scenePlan = null;
+            this.#scenePlanExecutor = null;
+            this.#bridge = null;
+            this.#runtime = null;
+            this.#editor = null;
+            this.#resources = null;
+            this.#resourceContext = null;
+            this.#workspace = null;
+            this.#lifetime = null;
+            if (!disposed) {
+                this.#setStatus("error", error);
+                this.#publishError(error, "initialize");
+            }
+            throw error;
+        }
+    }
+    async #resolveInitialDocument(workspace) {
+        if (this.#options.document) {
+            const document = normalizeSceneDocument(structuredClone(this.#options.document));
+            assertSceneDocument(document);
+            return document;
+        }
+        await workspace.scan();
+        if (this.#options.documentPath) {
+            return workspace.loadDocument(this.#options.documentPath);
+        }
+        const documents = await workspace.discoverSceneDocuments();
+        if (documents.length > 0)
+            return workspace.loadDocument();
+        return createEmptySceneDocument(this.#options.id ?? "scene", this.#options.name ?? "Untitled scene");
+    }
+    #bindEvents(signal) {
+        const editor = this.#editor;
+        const runtime = this.#runtime;
+        editor.subscribe("document.changed", (change, event) => this.events.publish("document.changed", { change, document: editor.snapshot }, createCausationMetadata(event, "sdk")), signal);
+        editor.subscribe("selection.changed", ({ entityIds }, event) => this.events.publish("selection.changed", { entityIds }, createCausationMetadata(event, "sdk")), signal);
+        editor.subscribe("dirty.changed", ({ dirty }, event) => this.events.publish("dirty.changed", { dirty }, createCausationMetadata(event, "sdk")), signal);
+        runtime.events.subscribe("runtime.loading", ({ loading }, event) => {
+            if (loading)
+                this.#modelFailures.length = 0;
+            this.events.publish("runtime.loading", { loading }, createCausationMetadata(event, "sdk"));
+        }, { signal });
+        runtime.events.subscribe("runtime.document.applied", () => {
+            if (!this.#previewing)
+                return;
+            try {
+                runtime.startDocumentBehaviors();
+            }
+            catch (error) {
+                this.#publishError(error, "restartPreviewBehaviors");
+            }
+        }, { signal });
+        runtime.events.subscribe("runtime.loading.progress", (progress, event) => this.events.publish("model.loading.progress", progress, createCausationMetadata(event, "sdk")), { signal });
+        runtime.events.subscribe("runtime.model.loaded", ({ entityId }, event) => this.events.publish("model.loaded", { entityId }, createCausationMetadata(event, "sdk")), { signal });
+        runtime.events.subscribe("runtime.model.failed", ({ entityId, error }, event) => {
+            this.#modelFailures.push({ entityId, error });
+            this.events.publish("model.failed", { entityId, error }, createCausationMetadata(event, "sdk"));
+        }, { signal });
+        runtime.events.subscribe("runtime.error", ({ error, operation }, event) => this.#publishError(error, operation, createCausationMetadata(event, "sdk")), { signal });
+    }
+    async #execute(command) {
+        this.#assertReady();
+        try {
+            const change = this.editor.execute(command);
+            await this.#bridge.flush();
+            return change;
+        }
+        catch (error) {
+            this.#publishError(error, command.id);
+            throw error;
+        }
+    }
+    async #executeMany(label, commands) {
+        this.#assertReady();
+        if (commands.length === 0)
+            return null;
+        try {
+            const change = this.editor.transaction(label, commands);
+            await this.#bridge.flush();
+            return change;
+        }
+        catch (error) {
+            this.#publishError(error, label);
+            throw error;
+        }
+    }
+    #requireEntity(entityId) {
+        const entity = this.document.entities[entityId];
+        if (!entity)
+            throw new Error(`Entity not found: ${entityId}`);
+        return entity;
+    }
+    #requireModel(entityId) {
+        const entity = this.#requireEntity(entityId);
+        if (entity.type !== "model") {
+            throw new Error(`Model entity not found: ${entityId}`);
+        }
+        return entity;
+    }
+    #setStatus(status, error = null) {
+        this.#status = status;
+        this.#error = error;
+        this.events.publish("status.changed", { status, error }, { source: "sdk" });
+    }
+    #publishError(error, operation, metadata = { source: "sdk" }) {
+        this.events.publish("error", { error, operation }, metadata);
+    }
+    #assertReady() {
+        if (this.#status !== "ready") {
+            throw new Error(`SkenoraScene is not ready: ${this.#status}`);
+        }
+    }
+}
+function normalizeId(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/gu, "-")
+        .replace(/^-+|-+$/gu, "");
+}
+function availableId(record, requested) {
+    if (!record[requested])
+        return requested;
+    let suffix = 2;
+    while (record[`${requested}-${suffix}`])
+        suffix += 1;
+    return `${requested}-${suffix}`;
+}
+function throwIfInitializationCancelled(signal) {
+    if (!signal.aborted)
+        return;
+    throw new DOMException("SkenoraScene initialization was cancelled", "AbortError");
+}
+/** Preferred name for the authoring-only high-level facade. */
+export class SkenoraEditor extends SkenoraScene {
+    static async create(options) {
+        const editor = new SkenoraEditor(options);
+        try {
+            await editor.init();
+            return editor;
+        }
+        catch (error) {
+            editor.dispose();
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=skenora-scene.js.map