@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/runtime/exportRuntime.js

@@ -0,0 +1,227 @@
+import { onChange, val } from '@dreamerbird/core';
+import { AgentApiError } from '../errors';
+import { BlobCollectSink } from '../../videoExport/BlobCollectSink';
+import { startShotExport } from '../../videoExport/exporter';
+let controller;
+/**
+ * CameraScene 挂载 effect 调用;返回解绑函数(仅当登记的还是同一
+ * 控制器才删,防过期 cleanup 抹掉新代次的登记,同 registerDirectorView)。
+ */
+export function registerSceneExportController(next) {
+    controller = next;
+    return () => {
+        if (controller === next)
+            controller = undefined;
+    };
+}
+/** 当前登记的场景导出控制器;未挂载为 undefined(命令映射 SCENE_UNAVAILABLE) */
+export function getSceneExportController() {
+    return controller;
+}
+function isCollectingSink(sink) {
+    return typeof sink.blob === 'function';
+}
+/**
+ * 录制核心:canvas + sink + sheet → startShotExport,外挂进度订阅
+ * (sequence 播放头 → 0..1)与 signal 取消;done 映射为导出结果。
+ * 返回 undefined = 编码器不可用(MediaRecorder 无可用格式)。
+ */
+function recordShot(args) {
+    const { sheet, canvas, sink, signal, onProgress, onError } = args;
+    const handle = startShotExport({ canvas, sheet, sink, onError });
+    if (!handle)
+        return undefined;
+    // exporter 的 abort 收尾(用户 Esc、开录相机被删、signal 取消共用)会调
+    // sink.abort 丢弃已录内容;包一层记录"内容已弃",done 映射时据它把
+    // 用户侧中止(signal 未 abort)也识别为 JOB_CANCELLED,而不是掉进
+    // blob() 的 INVALID_STATE —— 轮询任务的 Agent 必须能区分"被中止"与真失败
+    let sinkAborted = false;
+    const originalAbort = sink.abort.bind(sink);
+    sink.abort = async () => {
+        sinkAborted = true;
+        await originalAbort();
+    };
+    // 进度随序列播放头更新:录制 = 序列从头播到尾,position/length 即进度
+    const sequence = sheet.sequence;
+    const length = val(sequence.pointer.length);
+    const offProgress = onChange(sequence.pointer.position, (position) => {
+        onProgress?.(length > 0 ? Math.min(1, Math.max(0, position / length)) : 0);
+    });
+    const onAbort = () => {
+        handle.abort();
+        // exporter 的 abort 收尾也会调 sink.abort;这里显式再调(幂等),
+        // 保证取消语义不依赖 exporter 内部顺序
+        sink.abort().catch(() => { });
+    };
+    if (signal?.aborted) {
+        onAbort();
+    }
+    else {
+        signal?.addEventListener('abort', onAbort, { once: true });
+    }
+    const done = (async () => {
+        try {
+            // handle.done 是唯一权威:resolve = 录制收尾完成(含 abort 的安静收尾)
+            await handle.done;
+        }
+        finally {
+            offProgress();
+            signal?.removeEventListener('abort', onAbort);
+        }
+        if (signal?.aborted) {
+            throw new AgentApiError('JOB_CANCELLED', '视频导出已取消');
+        }
+        // done resolve 但内容已被丢弃(sink.abort 被调)= 用户侧中止
+        // (Esc/开录相机被删):同样按取消交付,不报 INVALID_STATE 假失败
+        if (sinkAborted) {
+            throw new AgentApiError('JOB_CANCELLED', '视频导出被中止(Esc 取消或开录相机被删除)');
+        }
+        if (isCollectingSink(sink)) {
+            const blob = sink.blob();
+            return {
+                blob,
+                fileName: sink.fileName ?? 'video.webm',
+                mimeType: blob.type || sink.mimeType || '',
+                size: blob.size,
+            };
+        }
+        // UI sink(另存为/直接下载):结果落浏览器,无内存产出
+        return undefined;
+    })();
+    return { handle, done };
+}
+export function createSceneExportController(deps) {
+    let disposed = false;
+    let pending;
+    let active;
+    /** 视角/相机已生效:取 canvas 开录;失败恢复视图并拒绝 */
+    function startPending(p) {
+        const canvas = deps.getCanvas();
+        if (!canvas) {
+            deps.setShotView(p.prevShotView);
+            p.reject(new AgentApiError('INVALID_STATE', '找不到场景画布(canvas),无法导出'));
+            return;
+        }
+        deps.lockExportCamera(p.cameraKey);
+        const record = recordShot({
+            sheet: deps.sheet,
+            canvas,
+            sink: p.request.sink,
+            signal: p.request.signal,
+            onProgress: p.request.onProgress,
+            onError: p.request.onError,
+        });
+        if (!record) {
+            // 编码器不可用:onError 已由 startShotExport 提示(UI 通道),
+            // 这里拒绝 Promise(Agent 通道),两者不重复
+            deps.lockExportCamera(null);
+            deps.setShotView(p.prevShotView);
+            p.reject(new AgentApiError('CAPABILITY_UNAVAILABLE', '当前浏览器不支持视频录制(MediaRecorder 无可用格式)'));
+            return;
+        }
+        active = {
+            handle: record.handle,
+            sink: p.request.sink,
+            prevShotView: p.prevShotView,
+            reject: p.reject,
+        };
+        deps.setActiveHandle(record.handle);
+        deps.setExporting(true);
+        // 收尾(成功/失败/取消共用):清句柄与导出态、恢复导出前视角
+        const settle = () => {
+            if (active?.handle !== record.handle)
+                return;
+            active = undefined;
+            deps.setActiveHandle(null);
+            deps.setExporting(false);
+            deps.setShotView(p.prevShotView);
+            deps.lockExportCamera(null);
+        };
+        record.done.then((result) => {
+            settle();
+            p.resolve(result);
+        }, (error) => {
+            settle();
+            p.reject(error);
+        });
+    }
+    return {
+        isExporting: () => deps.isExporting() || pending !== undefined || active !== undefined,
+        getActiveCameraKey: () => deps.getActiveCameraKey(),
+        hasCamera: (key) => deps.hasCamera(key),
+        startVideo(request) {
+            if (disposed) {
+                throw new AgentApiError('API_DISPOSED', '场景已卸载,无法导出');
+            }
+            if (pending || active || deps.isExporting()) {
+                throw new AgentApiError('INVALID_STATE', '已有视频导出进行中');
+            }
+            const cameraKey = request.cameraKey ?? deps.getActiveCameraKey();
+            if (!cameraKey) {
+                throw new AgentApiError('INVALID_STATE', '没有活动相机,无法导出视频');
+            }
+            if (!deps.hasCamera(cameraKey)) {
+                throw new AgentApiError('OBJECT_NOT_FOUND', `相机不存在: ${cameraKey}`, { details: { cameraKey } });
+            }
+            const sink = request.sink ?? new BlobCollectSink();
+            const prevShotView = deps.getShotView();
+            return new Promise((resolve, reject) => {
+                const p = {
+                    request: { ...request, sink },
+                    cameraKey,
+                    prevShotView,
+                    resolve,
+                    reject,
+                };
+                // 需要先切换(指定了非活动相机/不在镜头视角)就挂起,等场景副作用
+                // 在切换生效后 notifySceneReady 开录——对齐既有 UI 的开录时序;
+                // 无需切换则立即开录
+                const switchCamera = cameraKey !== deps.getActiveCameraKey();
+                const switchView = !deps.getShotView();
+                if (!switchCamera && !switchView) {
+                    startPending(p);
+                    return;
+                }
+                pending = p;
+                if (switchCamera)
+                    deps.setActiveCamera(cameraKey);
+                if (switchView)
+                    deps.setShotView(true);
+            });
+        },
+        notifySceneReady() {
+            if (disposed || !pending)
+                return;
+            const p = pending;
+            pending = undefined;
+            startPending(p);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const p = pending;
+            pending = undefined;
+            const a = active;
+            active = undefined;
+            // 先 abort 在录任务(handle.abort + sink.abort)
+            if (a) {
+                a.handle.abort();
+                a.sink.abort().catch(() => { });
+                deps.setActiveHandle(null);
+                deps.setExporting(false);
+                deps.lockExportCamera(null);
+            }
+            // 再恢复视图
+            const prevShotView = p?.prevShotView ?? a?.prevShotView;
+            if (prevShotView !== undefined && deps.getShotView() !== prevShotView) {
+                deps.setShotView(prevShotView);
+            }
+            // 最后拒绝未完成任务(录制的 done 随后 settle 时 Promise 已拒绝,
+            // 先到的 API_DISPOSED 胜出)
+            const error = new AgentApiError('API_DISPOSED', '场景已卸载,导出终止');
+            p?.reject(error);
+            a?.reject(error);
+        },
+    };
+}

package/dist/agent/runtime/objectRuntime.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 场景 SheetObject 运行时登记(2026-10-17,Task 4):业务对象
+ * (模型/相机/锚点/路径)的组件在 objRef 填充时登记、清空时按 id
+ * 清理。Agent 查询/选择命令经此拿运行时 SheetObject —— 不绕运行时
+ * 直接用 key 调 sheet.object 构造(那会顺手创建不存在的对象,
+ * 查询的"无副作用"契约就破了)。
+ *
+ * 模块级表与 placementObjects/shotCameraObjects 同模式:单页单场景。
+ */
+import type { ISheetObject } from '@dreamerbird/core';
+import type { SceneObjectId } from '../types';
+/** 登记某业务对象当前挂载的 SheetObject(objRef 填充时) */
+export declare function registerSceneSheetObject(id: SceneObjectId, obj: ISheetObject<any>): void;
+/**
+ * 按 id 清理登记(objRef 清空/组件卸载时)。传入 obj 时仅当登记的还是
+ * 同一对象才删 —— 防过期组件的 cleanup 清掉新代次的登记。
+ */
+export declare function unregisterSceneSheetObject(id: SceneObjectId, obj?: ISheetObject<any>): void;
+/** 当前挂载的 SheetObject;未挂载(注册表有条目但组件未起)为 undefined */
+export declare function getSceneSheetObject(id: SceneObjectId): ISheetObject<any> | undefined;
+/**
+ * 反查:selection.get 把 studio.selection 里的 SheetObject 映射回业务 ID;
+ * 未登记的 theatre 对象(Thingy、演示对象等)返回 undefined,由调用方跳过
+ */
+export declare function resolveSceneObjectId(obj: unknown): SceneObjectId | undefined;
+//# sourceMappingURL=objectRuntime.d.ts.map

package/dist/agent/runtime/objectRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectRuntime.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/objectRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAI3C,2CAA2C;AAC3C,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,aAAa,EACjB,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GACrB,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,aAAa,EACjB,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GACtB,IAAI,CAGN;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,aAAa,GAChB,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAE/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAK5E"}

package/dist/agent/runtime/objectRuntime.js

@@ -0,0 +1,29 @@
+const sceneSheetObjects = new Map();
+/** 登记某业务对象当前挂载的 SheetObject(objRef 填充时) */
+export function registerSceneSheetObject(id, obj) {
+    sceneSheetObjects.set(id, obj);
+}
+/**
+ * 按 id 清理登记(objRef 清空/组件卸载时)。传入 obj 时仅当登记的还是
+ * 同一对象才删 —— 防过期组件的 cleanup 清掉新代次的登记。
+ */
+export function unregisterSceneSheetObject(id, obj) {
+    if (obj && sceneSheetObjects.get(id) !== obj)
+        return;
+    sceneSheetObjects.delete(id);
+}
+/** 当前挂载的 SheetObject;未挂载(注册表有条目但组件未起)为 undefined */
+export function getSceneSheetObject(id) {
+    return sceneSheetObjects.get(id);
+}
+/**
+ * 反查:selection.get 把 studio.selection 里的 SheetObject 映射回业务 ID;
+ * 未登记的 theatre 对象(Thingy、演示对象等)返回 undefined,由调用方跳过
+ */
+export function resolveSceneObjectId(obj) {
+    for (const [id, registered] of sceneSheetObjects) {
+        if (registered === obj)
+            return id;
+    }
+    return undefined;
+}

package/dist/agent/runtime/pathRuntime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 路径采样运行时(2026-10-17,Task 11):CameraPath 挂载时把当前曲线的
+ * 采样函数登记到这里,`paths.sample` 经此取世界坐标——与 ShotCamera
+ * 每帧采样(CameraPath 模块级登记表 + samplePathPoint)读同一份
+ * 名单/曲线/进度锚点/整体变换矩阵。
+ *
+ * 卸载只解绑自己的 pathKey:同一函数引用校验,防过期组件的 cleanup
+ * 抹掉新代次的登记(同 unregisterSceneSheetObject 的 obj 校验)。
+ * 模块级表与 objectRuntime/poseSessionRuntime 同模式:单页单场景。
+ */
+import type { Vector3 } from 'three';
+/**
+ * 按进度(0~1)在路径上取世界坐标点。返回 false = 路径没有控制点
+ * (调用方回退手动驱动 / Agent 映射 INVALID_STATE)。
+ */
+export type PathSampler = (u: number, out: Vector3) => boolean;
+/** CameraPath 挂载 effect 调用;返回解绑函数(仅当登记的还是同一函数才删) */
+export declare function registerPathSampler(pathKey: string, sampler: PathSampler): () => void;
+/** 当前登记的采样器;路径未挂载为 undefined(paths.sample 映射 INVALID_STATE) */
+export declare function getPathSampler(pathKey: string): PathSampler | undefined;
+//# sourceMappingURL=pathRuntime.d.ts.map

package/dist/agent/runtime/pathRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathRuntime.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/pathRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,OAAO,CAAA;AAElC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAA;AAI9D,oDAAoD;AACpD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,GACnB,MAAM,IAAI,CAKZ;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE"}

package/dist/agent/runtime/pathRuntime.js

@@ -0,0 +1,13 @@
+const samplers = new Map();
+/** CameraPath 挂载 effect 调用;返回解绑函数(仅当登记的还是同一函数才删) */
+export function registerPathSampler(pathKey, sampler) {
+    samplers.set(pathKey, sampler);
+    return () => {
+        if (samplers.get(pathKey) === sampler)
+            samplers.delete(pathKey);
+    };
+}
+/** 当前登记的采样器;路径未挂载为 undefined(paths.sample 映射 INVALID_STATE) */
+export function getPathSampler(pathKey) {
+    return samplers.get(pathKey);
+}

package/dist/agent/runtime/placementLifecycle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 放置挂载等待(2026-10-17,Task 8):key → deferred waiter。
+ *
+ * Agent `models.create` 的 completion:mounted 靠它兑现:
+ * `placeLibraryEntryAt` 在 `setPendingEntry` 之前创建 waiter 并随
+ * `{key, persisted}` 返回;`PlacedModelCore` 在注册表提交 + `onPersisted()`
+ * 之后 `resolvePlacementPersisted(key)`;`PlacedModelErrorBoundary` 在
+ * 加载/渲染失败时 `rejectPlacement(key, err)`;pending 条目未持久化即卸载
+ * 时由 persist effect 的 cleanup 拒绝,等待方不悬挂。
+ *
+ * waiter settle 后立即从 Map 删除(settle 幂等由此而来);resolve/reject
+ * 对未知 key 静默 no-op —— UI 放置路径(confirmPlacing 等)不创建 waiter。
+ *
+ * 模块级表与 placementObjects/objectRuntime 同模式:单页单场景。
+ */
+/**
+ * 创建某 placement key 的挂载等待器,返回 persisted promise。
+ * 同 key 已有未 settle 的 waiter 时先拒绝旧的(它的挂载永远不会来了),
+ * 以新 waiter 为准 —— 旧等待方 settle 为失败,不悬挂。
+ */
+export declare function createPlacementWaiter(key: string): Promise<void>;
+/** 注册表提交 + onPersisted 之后由 PlacedModelCore 调用;未知 key no-op */
+export declare function resolvePlacementPersisted(key: string): void;
+/** 挂载/加载失败或提前卸载时拒绝;未知 key no-op */
+export declare function rejectPlacement(key: string, error: unknown): void;
+/** 该 key 是否有未 settle 的 waiter(测试与调试用) */
+export declare function hasPlacementWaiter(key: string): boolean;
+/**
+ * 会话拆解兜底(2026-10-19,Task 15):拒绝全部未 settle 的 waiter。
+ * dispose 不伴随 React 卸载的路径(如桥接直连 teardown)上,组件 cleanup
+ * 不会运行,pending waiter 必须由此拒绝(API_DISPOSED),等待方不悬挂。
+ */
+export declare function rejectAllPlacements(error: unknown): void;
+//# sourceMappingURL=placementLifecycle.d.ts.map

package/dist/agent/runtime/placementLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placementLifecycle.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/placementLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhE;AAED,8DAA8D;AAC9D,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEjE;AAED,yCAAyC;AACzC,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAExD"}

package/dist/agent/runtime/placementLifecycle.js

@@ -0,0 +1,63 @@
+/**
+ * 放置挂载等待(2026-10-17,Task 8):key → deferred waiter。
+ *
+ * Agent `models.create` 的 completion:mounted 靠它兑现:
+ * `placeLibraryEntryAt` 在 `setPendingEntry` 之前创建 waiter 并随
+ * `{key, persisted}` 返回;`PlacedModelCore` 在注册表提交 + `onPersisted()`
+ * 之后 `resolvePlacementPersisted(key)`;`PlacedModelErrorBoundary` 在
+ * 加载/渲染失败时 `rejectPlacement(key, err)`;pending 条目未持久化即卸载
+ * 时由 persist effect 的 cleanup 拒绝,等待方不悬挂。
+ *
+ * waiter settle 后立即从 Map 删除(settle 幂等由此而来);resolve/reject
+ * 对未知 key 静默 no-op —— UI 放置路径(confirmPlacing 等)不创建 waiter。
+ *
+ * 模块级表与 placementObjects/objectRuntime 同模式:单页单场景。
+ */
+const waiters = new Map();
+/**
+ * 创建某 placement key 的挂载等待器,返回 persisted promise。
+ * 同 key 已有未 settle 的 waiter 时先拒绝旧的(它的挂载永远不会来了),
+ * 以新 waiter 为准 —— 旧等待方 settle 为失败,不悬挂。
+ */
+export function createPlacementWaiter(key) {
+    rejectPlacement(key, new Error(`放置等待被同 key 的新放置取代: ${key}`));
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+    });
+    waiters.set(key, {
+        resolve: () => {
+            // 先删后兑现:settle 后 Map 不留条目,重复 settle 自然 no-op
+            waiters.delete(key);
+            resolvePromise();
+        },
+        reject: (error) => {
+            waiters.delete(key);
+            rejectPromise(error);
+        },
+    });
+    return promise;
+}
+/** 注册表提交 + onPersisted 之后由 PlacedModelCore 调用;未知 key no-op */
+export function resolvePlacementPersisted(key) {
+    waiters.get(key)?.resolve();
+}
+/** 挂载/加载失败或提前卸载时拒绝;未知 key no-op */
+export function rejectPlacement(key, error) {
+    waiters.get(key)?.reject(error);
+}
+/** 该 key 是否有未 settle 的 waiter(测试与调试用) */
+export function hasPlacementWaiter(key) {
+    return waiters.has(key);
+}
+/**
+ * 会话拆解兜底(2026-10-19,Task 15):拒绝全部未 settle 的 waiter。
+ * dispose 不伴随 React 卸载的路径(如桥接直连 teardown)上,组件 cleanup
+ * 不会运行,pending waiter 必须由此拒绝(API_DISPOSED),等待方不悬挂。
+ */
+export function rejectAllPlacements(error) {
+    for (const key of [...waiters.keys()])
+        rejectPlacement(key, error);
+}

package/dist/agent/runtime/placementLifecycle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=placementLifecycle.test.d.ts.map

package/dist/agent/runtime/placementLifecycle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placementLifecycle.test.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/placementLifecycle.test.ts"],"names":[],"mappings":""}

package/dist/agent/runtime/placementLifecycle.test.js

@@ -0,0 +1,68 @@
+/**
+ * placementLifecycle(2026-10-17,Task 8):key → deferred waiter 语义。
+ *
+ * waiter 在 setPendingEntry 前由 placeLibraryEntryAt 创建;
+ * PlacedModelCore 在注册表提交 + onPersisted 后 resolvePlacementPersisted,
+ * PlacedModelErrorBoundary 失败时 rejectPlacement;settle 后 waiter 立即
+ * 从 Map 删除,resolve/reject 对未知 key(UI 放置路径没有 waiter)静默 no-op。
+ */
+import { createPlacementWaiter, hasPlacementWaiter, rejectAllPlacements, rejectPlacement, resolvePlacementPersisted, } from './placementLifecycle';
+test('create 后 pending;resolvePlacementPersisted 后 promise 兑现且 waiter 从 Map 删除', async () => {
+    const persisted = createPlacementWaiter('k1');
+    expect(hasPlacementWaiter('k1')).toBe(true);
+    let settled = false;
+    void persisted.then(() => {
+        settled = true;
+    });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    resolvePlacementPersisted('k1');
+    await expect(persisted).resolves.toBeUndefined();
+    expect(settled).toBe(true);
+    expect(hasPlacementWaiter('k1')).toBe(false);
+});
+test('rejectPlacement 以原始错误 reject,并从 Map 删除', async () => {
+    const persisted = createPlacementWaiter('k2');
+    const failure = new Error('库模型加载失败');
+    rejectPlacement('k2', failure);
+    await expect(persisted).rejects.toBe(failure);
+    expect(hasPlacementWaiter('k2')).toBe(false);
+});
+test('未知 key 的 resolve/reject 静默 no-op(UI 放置路径没有 waiter)', () => {
+    expect(() => resolvePlacementPersisted('nope')).not.toThrow();
+    expect(() => rejectPlacement('nope', new Error('x'))).not.toThrow();
+    expect(hasPlacementWaiter('nope')).toBe(false);
+});
+test('settle 幂等:resolve 后的迟到 reject 不再生效', async () => {
+    const persisted = createPlacementWaiter('k3');
+    // 兜底消费,防万一实现退化成重复 reject 时出现 unhandled rejection
+    const guarded = persisted.catch((err) => err);
+    resolvePlacementPersisted('k3');
+    rejectPlacement('k3', new Error('late failure'));
+    await expect(persisted).resolves.toBeUndefined();
+    await expect(guarded).resolves.toBeUndefined();
+    expect(hasPlacementWaiter('k3')).toBe(false);
+});
+test('同 key 重复创建:旧 waiter 被拒绝(不悬挂),新 waiter 独立工作', async () => {
+    const first = createPlacementWaiter('k4');
+    const firstOutcome = first.then(() => 'resolved', (err) => (err instanceof Error ? err.message : String(err)));
+    const second = createPlacementWaiter('k4');
+    // 旧 waiter 必须 settle(reject),否则等待方永远悬挂
+    await expect(firstOutcome).resolves.toContain('取代');
+    expect(hasPlacementWaiter('k4')).toBe(true);
+    resolvePlacementPersisted('k4');
+    await expect(second).resolves.toBeUndefined();
+    expect(hasPlacementWaiter('k4')).toBe(false);
+});
+test('rejectAllPlacements:全部 pending waiter 以同一错误拒绝并清空(dispose 不悬挂,Task 15)', async () => {
+    const a = createPlacementWaiter('ra1');
+    const b = createPlacementWaiter('ra2');
+    const disposed = new Error('API_DISPOSED');
+    rejectAllPlacements(disposed);
+    await expect(a).rejects.toBe(disposed);
+    await expect(b).rejects.toBe(disposed);
+    expect(hasPlacementWaiter('ra1')).toBe(false);
+    expect(hasPlacementWaiter('ra2')).toBe(false);
+    // 空 Map 上调 rejectAll 静默 no-op
+    expect(() => rejectAllPlacements(new Error('again'))).not.toThrow();
+});

package/dist/agent/runtime/poseSessionRuntime.d.ts

@@ -0,0 +1,17 @@
+/** PoseModeRig 登记的会话句柄 */
+export type PoseSessionRigHandlers = {
+    /** 提交:脏检查 → 捕获实时骨骼写姿势帧(可撤销)→ 清会话 */
+    commit: () => void;
+    /** 取消:不写回直接清会话(姿势应用 effect 把当前值补刷回骨骼) */
+    cancel: () => void;
+};
+/** PoseModeRig 挂载 effect 调用;返回注销函数(组件卸载时调用) */
+export declare function registerPoseSessionRig(key: string, handlers: PoseSessionRigHandlers): () => void;
+/** 当前登记的 Rig 句柄;未挂载为 undefined */
+export declare function getPoseSessionRig(key: string): PoseSessionRigHandlers | undefined;
+/**
+ * 等待某 placement key 的 Rig 登记;已登记立即兑现。
+ * 同 key 重复等待复用同一 promise(幂等 start)。
+ */
+export declare function whenPoseSessionRig(key: string): Promise<void>;
+//# sourceMappingURL=poseSessionRuntime.d.ts.map

package/dist/agent/runtime/poseSessionRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poseSessionRuntime.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/poseSessionRuntime.ts"],"names":[],"mappings":"AAgBA,0BAA0B;AAC1B,MAAM,MAAM,sBAAsB,GAAG;IACnC,oCAAoC;IACpC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,yCAAyC;IACzC,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB,CAAA;AA2BD,+CAA+C;AAC/C,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,sBAAsB,GAC/B,MAAM,IAAI,CAWZ;AAED,kCAAkC;AAClC,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GACV,sBAAsB,GAAG,SAAS,CAEpC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY7D"}

package/dist/agent/runtime/poseSessionRuntime.js

@@ -0,0 +1,64 @@
+/**
+ * 姿势会话运行时(2026-10-17,Task 9):PoseModeRig 挂载后按 placementKey
+ * 登记提交/取消句柄,Agent `poses.session.*` 命令经此调用——与 UI 的
+ * Esc/双击空白退出同一条提交路径(句柄由 Rig 的挂载 effect 注册,
+ * 卸载即注销,绝不读到陈旧闭包)。
+ *
+ * `whenPoseSessionRig` 是 `poses.session.start` 的 completion:mounted
+ * 等待:Rig 登记即兑现;会话在登记前被清(防御路径:无根骨/无装配表
+ * 时 PoseModeRig 直接 clearPoseSession)或切换到别的模型时,等待方以
+ * INVALID_STATE 拒绝,不悬挂。
+ *
+ * 模块级表与 objectRuntime/placementLifecycle 同模式:单页单场景。
+ */
+import { AgentApiError } from '../errors';
+import { onPoseSessionChange } from '../../poseMode/poseSession';
+const rigs = new Map();
+const waiters = new Map();
+// 会话生灭看护:等待中的 key 对应的会话消失/被切换时,拒绝其 waiter。
+// 模块级单次订阅(单页单会话,同 poseSession 的全局唯一语义)。
+onPoseSessionChange((session) => {
+    for (const [key, waiter] of waiters) {
+        if (session?.key === key)
+            continue;
+        waiters.delete(key);
+        waiter.reject(new AgentApiError('INVALID_STATE', `姿势会话未能建立:模型 ${key} 的 Rig 未挂载`, { details: { key } }));
+    }
+});
+/** PoseModeRig 挂载 effect 调用;返回注销函数(组件卸载时调用) */
+export function registerPoseSessionRig(key, handlers) {
+    rigs.set(key, handlers);
+    const waiter = waiters.get(key);
+    if (waiter) {
+        waiters.delete(key);
+        waiter.resolve();
+    }
+    return () => {
+        // 仅当登记的还是同一句柄才删:A→B 切换时 A 的迟到注销不抹掉 B
+        if (rigs.get(key) === handlers)
+            rigs.delete(key);
+    };
+}
+/** 当前登记的 Rig 句柄;未挂载为 undefined */
+export function getPoseSessionRig(key) {
+    return rigs.get(key);
+}
+/**
+ * 等待某 placement key 的 Rig 登记;已登记立即兑现。
+ * 同 key 重复等待复用同一 promise(幂等 start)。
+ */
+export function whenPoseSessionRig(key) {
+    if (rigs.has(key))
+        return Promise.resolve();
+    const existing = waiters.get(key);
+    if (existing)
+        return existing.promise;
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    waiters.set(key, { promise, resolve, reject });
+    return promise;
+}

package/dist/agent/runtime.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent 运行时(2026-10-17,spec 第 8 节):historic revision 乐观并发、
+ * 执行代次(session 内 remount 隔离)和 scene handler 绑定。
+ * revision 从 1 开始,只随 historic 指针通知递增;每个执行代次持有
+ * 自己的 handlers 与 readiness,会话 dispose 使全部代次失效。
+ */
+import type { IProject, ISheet, IStudio } from '@dreamerbird/core';
+import { AgentJobManager } from './jobs';
+import type { Library } from '../assetLibrary/library';
+/**
+ * 场景运行时 handler 宿主接口:Task 3 先导出空接口,
+ * 各领域任务(模型/相机/路径/姿势/导出…)通过 TypeScript
+ * declaration merging 往这个接口上增加自己的 handler 签名。
+ */
+export interface AgentSceneRuntimeHandlers {
+}
+type Handlers = Partial<AgentSceneRuntimeHandlers>;
+export type AgentRuntimeDeps = {
+    project: IProject;
+    sheet: ISheet;
+    library: Library;
+    getStudio: () => IStudio | undefined;
+    /** 生产由 bootstrap 传入:
+     * `(listener) => onChange(privateAPI(project).pointers.historic, () => listener())` */
+    subscribeHistoric: (listener: () => void) => () => void;
+};
+export type AgentRuntime = {
+    readonly project: IProject;
+    readonly sheet: ISheet;
+    readonly library: Library;
+    readonly getStudio: () => IStudio | undefined;
+    readonly jobs: AgentJobManager;
+    /** 当前会话的 historic revision,从 1 开始 */
+    readonly revision: number;
+    /**
+     * 写命令返回用的 revision(F2):historic 通知是 tick 调度的,事务后
+     * 同步读 revision 拿到的是写入前的值——这里等一个 core tick 再读,
+     * 返回值反映本次写入,expectedRevision 链式调用才不错误冲突。
+     * 等待期间会话拆解 → API_DISPOSED。
+     */
+    nextRevision(): Promise<number>;
+    /** 本代次的 readiness:CameraScene 绑定完整 handlers 后 markReady resolve,dispose reject */
+    readonly ready: Promise<void>;
+    /** 本代次当前绑定的 handlers(live 视图) */
+    readonly handlers: Readonly<Handlers>;
+    /** 乐观并发:先检查活动代次,再比较 revision;冲突 details 含 expected/actual */
+    assertRevision(expected: number): void;
+    /** 会话未被 dispose */
+    assertActive(): void;
+    /** 会话未 dispose 且本代次未被 activate() 替换 */
+    assertCurrent(): void;
+    /** 合并绑定 handlers,返回解绑函数;代次失效后绑定抛 API_DISPOSED,解绑静默失效 */
+    bindHandlers(handlers: Handlers): () => void;
+    /** 创建新执行代次;旧代次的 assertCurrent/markReady 从此抛 API_DISPOSED,
+        其未 settle 的 ready 以 API_NOT_READY 拒绝(handler 解绑换代,Task 15) */
+    activate(): AgentRuntime;
+    /** 标记本代次 ready(通常由 CameraScene 绑定完整 handlers 后调用) */
+    markReady(): void;
+    /** 会话拆解:取消 historic 订阅、硬取消在途任务、拒绝全部挂载 waiter
+        (placement/camera/anchor)、失效全部代次并拒绝未 settle 的 ready */
+    dispose(): void;
+};
+/** 判定错误是否来自"代次被替换但会话未 dispose"(门面映射 API_NOT_READY 的依据) */
+export declare function isGenerationSupersededError(error: unknown): boolean;
+export declare function createAgentRuntime(deps: AgentRuntimeDeps): AgentRuntime;
+export {};
+//# sourceMappingURL=runtime.d.ts.map