@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/registry.d.ts

@@ -0,0 +1,33 @@
+import type { CommandContext, CommandDefinition } from './types';
+/** 命令的可发布元数据:`describe()` 与后续 SKILL/HTTP schema 共用 */
+export type CommandDescription = {
+    name: string;
+    kind: CommandDefinition<unknown, unknown>['kind'];
+    stateDomain: CommandDefinition<unknown, unknown>['stateDomain'];
+    undoable: CommandDefinition<unknown, unknown>['undoable'];
+    completion?: CommandDefinition<unknown, unknown>['completion'];
+    cancelable?: boolean;
+    inputSchema: CommandDefinition<unknown, unknown>['inputSchema'];
+    outputSchema: CommandDefinition<unknown, unknown>['outputSchema'];
+    jobResultSchema?: CommandDefinition<unknown, unknown>['jobResultSchema'];
+    errorCodes: readonly string[];
+    /** 命令是否接受 `expectedRevision` 做乐观并发控制(spec 8.7) */
+    acceptsExpectedRevision: boolean;
+};
+/** 注册表自描述快照 */
+export type RegistryDescription = {
+    apiVersion: 1;
+    commands: CommandDescription[];
+};
+export declare class AgentCommandRegistry {
+    private readonly definitions;
+    register<A, R>(definition: CommandDefinition<A, R>): void;
+    has(name: string): boolean;
+    /**
+     * 分发顺序固定:查命令 → validate(args) → execute → asAgentApiError 归一。
+     */
+    execute(name: string, args: unknown, context: CommandContext): Promise<unknown>;
+    /** 返回按 name 排序的元数据快照;不含 validate/execute 函数 */
+    describe(): RegistryDescription;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/agent/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agent/registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,SAAS,CAAA;AAE9D,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;IACjD,WAAW,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,aAAa,CAAC,CAAA;IAC/D,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,CAAA;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,CAAA;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,aAAa,CAAC,CAAA;IAC/D,YAAY,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc,CAAC,CAAA;IACjE,eAAe,CAAC,EAAE,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAAC,CAAA;IACxE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,kDAAkD;IAClD,uBAAuB,EAAE,OAAO,CAAA;CACjC,CAAA;AAED,eAAe;AACf,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,CAAC,CAAA;IACb,QAAQ,EAAE,kBAAkB,EAAE,CAAA;CAC/B,CAAA;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGzB;IAEH,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAUzD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC;IAanB,+CAA+C;IAC/C,QAAQ,IAAI,mBAAmB;CAqBhC"}

package/dist/agent/registry.js

@@ -0,0 +1,55 @@
+/**
+ * Agent 命令注册表(2026-10-17):命令的登记、按名分发和自描述。
+ * `describe()` 只复制元数据与 schema,供 SKILL 和 HTTP schema 使用,
+ * 不携带 validate/execute 函数(spec 第 8 节)。
+ */
+import { AgentApiError, asAgentApiError } from './errors';
+export class AgentCommandRegistry {
+    constructor() {
+        this.definitions = new Map();
+    }
+    register(definition) {
+        if (this.definitions.has(definition.name)) {
+            throw new AgentApiError('INVALID_STATE', `命令已注册: ${definition.name}`);
+        }
+        this.definitions.set(definition.name, definition);
+    }
+    has(name) {
+        return this.definitions.has(name);
+    }
+    /**
+     * 分发顺序固定:查命令 → validate(args) → execute → asAgentApiError 归一。
+     */
+    async execute(name, args, context) {
+        const definition = this.definitions.get(name);
+        if (!definition) {
+            throw new AgentApiError('COMMAND_NOT_FOUND', `未知命令: ${name}`);
+        }
+        try {
+            const validated = definition.validate(args);
+            return await definition.execute(validated, context);
+        }
+        catch (error) {
+            throw asAgentApiError(error);
+        }
+    }
+    /** 返回按 name 排序的元数据快照;不含 validate/execute 函数 */
+    describe() {
+        const commands = [...this.definitions.values()]
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+            .map((definition) => ({
+            name: definition.name,
+            kind: definition.kind,
+            stateDomain: definition.stateDomain,
+            undoable: definition.undoable,
+            completion: definition.completion,
+            cancelable: definition.cancelable,
+            inputSchema: definition.inputSchema,
+            outputSchema: definition.outputSchema,
+            jobResultSchema: definition.jobResultSchema,
+            errorCodes: definition.errorCodes,
+            acceptsExpectedRevision: definition.stateDomain === 'project' && definition.kind !== 'query',
+        }));
+        return { apiVersion: 1, commands };
+    }
+}

package/dist/agent/registry.test.d.ts

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

package/dist/agent/registry.test.d.ts.map

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

package/dist/agent/registry.test.js

@@ -0,0 +1,106 @@
+import { AgentCommandRegistry } from './registry';
+import { AgentApiError } from './errors';
+const context = { requestId: 'r1', signal: new AbortController().signal };
+test('validates args and returns the domain result', async () => {
+    const registry = new AgentCommandRegistry();
+    registry.register({
+        name: 'test.double',
+        kind: 'query',
+        stateDomain: 'transport',
+        undoable: 'none',
+        inputSchema: { type: 'object' },
+        outputSchema: { type: 'number' },
+        errorCodes: [],
+        validate: (value) => {
+            if (typeof value !== 'number') {
+                throw new AgentApiError('INVALID_ARGUMENT', 'number expected');
+            }
+            return value;
+        },
+        execute: async (value) => value * 2,
+    });
+    await expect(registry.execute('test.double', 3, context)).resolves.toBe(6);
+    await expect(registry.execute('test.double', '3', context)).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' });
+    const description = registry.describe();
+    expect(description.apiVersion).toBe(1);
+    expect(description.commands[0]).toMatchObject({ name: 'test.double' });
+    expect(description.commands[0]).not.toHaveProperty('execute');
+    expect(description.commands[0]).not.toHaveProperty('validate');
+});
+test('rejects duplicate and unknown commands', async () => {
+    const registry = new AgentCommandRegistry();
+    await expect(registry.execute('missing', {}, context)).rejects.toMatchObject({
+        code: 'COMMAND_NOT_FOUND',
+    });
+    const definition = {
+        name: 'test.double',
+        kind: 'query',
+        stateDomain: 'transport',
+        undoable: 'none',
+        inputSchema: { type: 'object' },
+        outputSchema: { type: 'number' },
+        errorCodes: [],
+        validate: (value) => {
+            if (typeof value !== 'number') {
+                throw new AgentApiError('INVALID_ARGUMENT', 'number expected');
+            }
+            return value;
+        },
+        execute: async (value) => value * 2,
+    };
+    registry.register(definition);
+    expect(() => registry.register(definition)).toThrowError(expect.objectContaining({ code: 'INVALID_STATE' }));
+});
+test('describe() sorts commands by name and marks acceptsExpectedRevision', () => {
+    const registry = new AgentCommandRegistry();
+    const makeDefinition = (name, stateDomain) => ({
+        name,
+        kind: 'mutation',
+        stateDomain,
+        undoable: 'single-step',
+        inputSchema: { type: 'object' },
+        outputSchema: { type: 'object' },
+        errorCodes: [],
+        validate: (value) => value,
+        execute: async (value) => value,
+    });
+    registry.register(makeDefinition('test.beta', 'project'));
+    registry.register(makeDefinition('test.alpha', 'project'));
+    const description = registry.describe();
+    expect(description.commands.map((command) => command.name)).toEqual([
+        'test.alpha',
+        'test.beta',
+    ]);
+    expect(description.commands[0]).toMatchObject({ acceptsExpectedRevision: true });
+    for (const command of description.commands) {
+        expect(command).not.toHaveProperty('execute');
+        expect(command).not.toHaveProperty('validate');
+    }
+    const query = makeDefinition('test.gamma', 'project');
+    registry.register({ ...query, kind: 'query' });
+    expect(registry.describe().commands.find((c) => c.name === 'test.gamma')).toMatchObject({
+        acceptsExpectedRevision: false,
+    });
+    expect(registry.has('test.alpha')).toBe(true);
+    expect(registry.has('test.missing')).toBe(false);
+});
+test('execute wraps unknown errors as INTERNAL_ERROR', async () => {
+    const registry = new AgentCommandRegistry();
+    registry.register({
+        name: 'test.boom',
+        kind: 'query',
+        stateDomain: 'transport',
+        undoable: 'none',
+        inputSchema: { type: 'object' },
+        outputSchema: { type: 'object' },
+        errorCodes: [],
+        validate: (value) => value,
+        execute: async () => {
+            throw new Error('boom');
+        },
+    });
+    await expect(registry.execute('test.boom', {}, context)).rejects.toMatchObject({
+        code: 'INTERNAL_ERROR',
+        details: { cause: 'boom' },
+    });
+});

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

@@ -0,0 +1,25 @@
+/**
+ * 动画资源加载状态登记(2026-10-17,Task 9):PlacementManager 的动画加载
+ * effect 在加载开始/成功/失败时按 placement key 登记,React cleanup
+ * (卸载或 animationId 切换)必须删除对应 key——`animations.getStatus`
+ * 只读这里的登记,绝不从 props 猜测 loaded(未挂载即无登记,查询方按
+ * 「加载中」如实上报,不留陈旧 loaded)。
+ *
+ * 模块级表与 objectRuntime/placementLifecycle 同模式:单页单场景。
+ */
+import type { AgentErrorDto } from '../types';
+/** 某放置模型当前的动画加载状态 */
+export type AnimationLoadStatus = {
+    /** 正在加载/已加载/失败的动画资产 id */
+    assetId: string;
+    loaded: boolean;
+    /** 加载失败的结构化错误;成功/进行中缺省 */
+    error?: AgentErrorDto;
+};
+/** PlacementManager 动画加载 effect 调用:开始(loaded:false)/成功/失败 */
+export declare function setAnimationLoadStatus(key: string, status: AnimationLoadStatus): void;
+/** React cleanup 必须调用:卸载或切换动画后不得残留陈旧状态 */
+export declare function clearAnimationLoadStatus(key: string): void;
+/** animations.getStatus 读取;未登记为 undefined(调用方按加载中处理) */
+export declare function getAnimationLoadStatus(key: string): AnimationLoadStatus | undefined;
+//# sourceMappingURL=animationStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animationStatus.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/animationStatus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAE3C,qBAAqB;AACrB,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,0BAA0B;IAC1B,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB,CAAA;AAID,6DAA6D;AAC7D,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAEN;AAED,0CAA0C;AAC1C,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED,wDAAwD;AACxD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,GACV,mBAAmB,GAAG,SAAS,CAEjC"}

package/dist/agent/runtime/animationStatus.js

@@ -0,0 +1,13 @@
+const statuses = new Map();
+/** PlacementManager 动画加载 effect 调用:开始(loaded:false)/成功/失败 */
+export function setAnimationLoadStatus(key, status) {
+    statuses.set(key, status);
+}
+/** React cleanup 必须调用:卸载或切换动画后不得残留陈旧状态 */
+export function clearAnimationLoadStatus(key) {
+    statuses.delete(key);
+}
+/** animations.getStatus 读取;未登记为 undefined(调用方按加载中处理) */
+export function getAnimationLoadStatus(key) {
+    return statuses.get(key);
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 相机/锚点挂载等待(2026-10-17,Task 10):key → deferred waiter,
+ * 与 placementLifecycle 同模式。
+ *
+ * Agent `cameras.create` / `anchors.create` 的 completion:mounted 靠它
+ * 兑现:命令在 Scene Runtime handler 同步写注册表并返回 key 后创建
+ * waiter;`ShotCamera` / `AnchorObject` 的种子 layout effect 结束时
+ * `notifyCameraReady` / `notifyAnchorReady`(没有 seed 的恢复对象同样
+ * 通知,不重复写值);组件在 waiter 未 settle 时卸载则 reject,
+ * 等待方不悬挂。
+ *
+ * waiter settle 后立即从 Map 删除(settle 幂等由此而来);notify/reject
+ * 对未知 key 静默 no-op —— UI 的添加相机/锚点路径不创建 waiter。
+ *
+ * 模块级表与 placementLifecycle/objectRuntime 同模式:单页单场景。
+ */
+/** cameras.create 在 handler 返回 key 后创建;resolve 于 ShotCamera 挂载就绪 */
+export declare function createCameraWaiter(cameraKey: string): Promise<void>;
+/** ShotCamera 的种子 layout effect 结束(含无 seed 的恢复对象)时调用 */
+export declare function notifyCameraReady(cameraKey: string): void;
+/** ShotCamera 在 waiter 未 settle 时卸载调用;无 waiter 时 no-op */
+export declare function rejectCameraMount(cameraKey: string, error: unknown): void;
+/** 该 cameraKey 是否有未 settle 的 waiter(测试与调试用) */
+export declare function hasCameraWaiter(cameraKey: string): boolean;
+/** 会话拆解时拒绝全部未 settle 的相机挂载 waiter(Task 15) */
+export declare function rejectAllCameraMounts(error: unknown): void;
+/** anchors.create 在 handler 返回 key 后创建;resolve 于 AnchorObject 挂载就绪 */
+export declare function createAnchorWaiter(anchorKey: string): Promise<void>;
+/** AnchorObject 的种子 layout effect 结束(含无 seed 的恢复对象)时调用 */
+export declare function notifyAnchorReady(anchorKey: string): void;
+/** AnchorObject 在 waiter 未 settle 时卸载调用;无 waiter 时 no-op */
+export declare function rejectAnchorMount(anchorKey: string, error: unknown): void;
+/** 该 anchorKey 是否有未 settle 的 waiter(测试与调试用) */
+export declare function hasAnchorWaiter(anchorKey: string): boolean;
+/** 会话拆解时拒绝全部未 settle 的锚点挂载 waiter(Task 15) */
+export declare function rejectAllAnchorMounts(error: unknown): void;
+//# sourceMappingURL=cameraLifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cameraLifecycle.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/cameraLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiEH,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEzE;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,8CAA8C;AAC9C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE1D;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEzE;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,8CAA8C;AAC9C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE1D"}

package/dist/agent/runtime/cameraLifecycle.js

@@ -0,0 +1,112 @@
+/**
+ * 相机/锚点挂载等待(2026-10-17,Task 10):key → deferred waiter,
+ * 与 placementLifecycle 同模式。
+ *
+ * Agent `cameras.create` / `anchors.create` 的 completion:mounted 靠它
+ * 兑现:命令在 Scene Runtime handler 同步写注册表并返回 key 后创建
+ * waiter;`ShotCamera` / `AnchorObject` 的种子 layout effect 结束时
+ * `notifyCameraReady` / `notifyAnchorReady`(没有 seed 的恢复对象同样
+ * 通知,不重复写值);组件在 waiter 未 settle 时卸载则 reject,
+ * 等待方不悬挂。
+ *
+ * waiter settle 后立即从 Map 删除(settle 幂等由此而来);notify/reject
+ * 对未知 key 静默 no-op —— UI 的添加相机/锚点路径不创建 waiter。
+ *
+ * 模块级表与 placementLifecycle/objectRuntime 同模式:单页单场景。
+ */
+function makeMountLifecycle(label) {
+    const waiters = new Map();
+    return {
+        /**
+         * 创建某 key 的挂载等待器,返回 ready promise。
+         * 同 key 已有未 settle 的 waiter 时先拒绝旧的(它的挂载永远不会来了),
+         * 以新 waiter 为准 —— 旧等待方 settle 为失败,不悬挂。
+         */
+        create(key) {
+            waiters
+                .get(key)
+                ?.reject(new Error(`${label}挂载等待被同 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;
+        },
+        /** 挂载对象的种子 layout effect 结束后调用;未知 key no-op */
+        notify(key) {
+            waiters.get(key)?.resolve();
+        },
+        /** waiter 未 settle 组件即卸载时拒绝;未知 key no-op */
+        reject(key, error) {
+            waiters.get(key)?.reject(error);
+        },
+        /** 该 key 是否有未 settle 的 waiter(测试与调试用) */
+        has(key) {
+            return waiters.has(key);
+        },
+        /**
+         * 会话拆解兜底(Task 15):拒绝全部未 settle 的 waiter。
+         * dispose 不伴随组件卸载时,pending waiter 由此拒绝,不悬挂。
+         */
+        rejectAll(error) {
+            for (const key of [...waiters.keys()]) {
+                waiters.get(key)?.reject(error);
+            }
+        },
+    };
+}
+const cameraLifecycle = makeMountLifecycle('相机');
+const anchorLifecycle = makeMountLifecycle('锚点');
+/** cameras.create 在 handler 返回 key 后创建;resolve 于 ShotCamera 挂载就绪 */
+export function createCameraWaiter(cameraKey) {
+    return cameraLifecycle.create(cameraKey);
+}
+/** ShotCamera 的种子 layout effect 结束(含无 seed 的恢复对象)时调用 */
+export function notifyCameraReady(cameraKey) {
+    cameraLifecycle.notify(cameraKey);
+}
+/** ShotCamera 在 waiter 未 settle 时卸载调用;无 waiter 时 no-op */
+export function rejectCameraMount(cameraKey, error) {
+    cameraLifecycle.reject(cameraKey, error);
+}
+/** 该 cameraKey 是否有未 settle 的 waiter(测试与调试用) */
+export function hasCameraWaiter(cameraKey) {
+    return cameraLifecycle.has(cameraKey);
+}
+/** 会话拆解时拒绝全部未 settle 的相机挂载 waiter(Task 15) */
+export function rejectAllCameraMounts(error) {
+    cameraLifecycle.rejectAll(error);
+}
+/** anchors.create 在 handler 返回 key 后创建;resolve 于 AnchorObject 挂载就绪 */
+export function createAnchorWaiter(anchorKey) {
+    return anchorLifecycle.create(anchorKey);
+}
+/** AnchorObject 的种子 layout effect 结束(含无 seed 的恢复对象)时调用 */
+export function notifyAnchorReady(anchorKey) {
+    anchorLifecycle.notify(anchorKey);
+}
+/** AnchorObject 在 waiter 未 settle 时卸载调用;无 waiter 时 no-op */
+export function rejectAnchorMount(anchorKey, error) {
+    anchorLifecycle.reject(anchorKey, error);
+}
+/** 该 anchorKey 是否有未 settle 的 waiter(测试与调试用) */
+export function hasAnchorWaiter(anchorKey) {
+    return anchorLifecycle.has(anchorKey);
+}
+/** 会话拆解时拒绝全部未 settle 的锚点挂载 waiter(Task 15) */
+export function rejectAllAnchorMounts(error) {
+    anchorLifecycle.rejectAll(error);
+}

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

@@ -0,0 +1,42 @@
+/**
+ * 导演视角控制器(2026-10-17,Task 12):MainOrbitControls 挂载时把
+ * orbit/pan/dolly/reset 一组函数登记到这里,`view.*` 导演视角命令
+ * 经此转发到活着的 OrbitControls 实例(写回 theatre 的 scrub 事件流
+ * 由 MainOrbitControls 内部复用)。未注册 = 场景尚未挂载轨道控制器,
+ * 命令返回 API_NOT_READY,不静默成功。
+ *
+ * 卸载只解绑自己的控制器:同一对象引用校验,防过期组件的 cleanup
+ * 抹掉新代次的登记(同 registerPathSampler 模式)。模块级表与
+ * objectRuntime/pathRuntime 同模式:单页单场景。
+ */
+/**
+ * 导演视角操作集。增量语义(与 UI 手势速度系数无关,纯世界量):
+ * - orbit:deltaTheta 方位角增量(弧度,正值绕瞄准点逆时针,俯视);
+ *   deltaPhi 极角增量(弧度,正值向水平方向下压,受轨道极角范围夹取)
+ * - pan:deltaX/deltaY 世界单位,沿相机右/上方向平移机位与瞄准点
+ * - dolly:delta 沿视线的距离增量(正值 = 靠近瞄准点,负值 = 拉远;
+ *   结果距离不小于轨道最小距离)
+ * - reset:恢复初始机位与瞄准点(与场景 JSX 的 position 同源常量)
+ */
+export type DirectorViewController = {
+    orbit(args: {
+        deltaTheta: number;
+        deltaPhi: number;
+    }): void;
+    pan(args: {
+        deltaX: number;
+        deltaY: number;
+    }): void;
+    dolly(args: {
+        delta: number;
+    }): void;
+    reset(): void;
+};
+/**
+ * MainOrbitControls 挂载 effect 调用;返回解绑函数
+ * (仅当登记的还是同一控制器才删,防过期 cleanup 抹掉新代次)。
+ */
+export declare function registerDirectorView(next: DirectorViewController): () => void;
+/** 当前登记的导演控制器;未挂载为 undefined(view.* 映射 API_NOT_READY) */
+export declare function getDirectorView(): DirectorViewController | undefined;
+//# sourceMappingURL=directorView.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"directorView.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/directorView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,IAAI,EAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI,CAAA;IACzD,GAAG,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI,CAAA;IACjD,KAAK,CAAC,IAAI,EAAE;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI,CAAA;IAClC,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAK7E;AAED,yDAAyD;AACzD,wBAAgB,eAAe,IAAI,sBAAsB,GAAG,SAAS,CAEpE"}

package/dist/agent/runtime/directorView.js

@@ -0,0 +1,27 @@
+/**
+ * 导演视角控制器(2026-10-17,Task 12):MainOrbitControls 挂载时把
+ * orbit/pan/dolly/reset 一组函数登记到这里,`view.*` 导演视角命令
+ * 经此转发到活着的 OrbitControls 实例(写回 theatre 的 scrub 事件流
+ * 由 MainOrbitControls 内部复用)。未注册 = 场景尚未挂载轨道控制器,
+ * 命令返回 API_NOT_READY,不静默成功。
+ *
+ * 卸载只解绑自己的控制器:同一对象引用校验,防过期组件的 cleanup
+ * 抹掉新代次的登记(同 registerPathSampler 模式)。模块级表与
+ * objectRuntime/pathRuntime 同模式:单页单场景。
+ */
+let controller;
+/**
+ * MainOrbitControls 挂载 effect 调用;返回解绑函数
+ * (仅当登记的还是同一控制器才删,防过期 cleanup 抹掉新代次)。
+ */
+export function registerDirectorView(next) {
+    controller = next;
+    return () => {
+        if (controller === next)
+            controller = undefined;
+    };
+}
+/** 当前登记的导演控制器;未挂载为 undefined(view.* 映射 API_NOT_READY) */
+export function getDirectorView() {
+    return controller;
+}

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

@@ -0,0 +1,95 @@
+/**
+ * 场景视频导出运行时(2026-10-17,Task 13):CameraScene 导出流程的共享
+ * 核心——活动相机校验、ShotView 切换与恢复、canvas 获取、录制
+ * (startShotExport)和异常恢复,从 CameraScene 抽出,UI 导出菜单与
+ * Agent exports.startVideo 共用(保留既有 UI 行为:开录时机仍是
+ * ShotView 生效后的场景副作用,经 notifySceneReady 回调)。
+ *
+ * CameraScene 挂载时 createSceneExportController 建控制器并
+ * registerSceneExportController 登记(模块级表单页单场景,同
+ * directorView/animationStatus 模式);Agent 命令经
+ * getSceneExportController 取用,未登记 = 场景未挂载(SCENE_UNAVAILABLE)。
+ *
+ * 关键不变量:
+ *  - handle.done 是导出终态的唯一权威;拿到 startShotExport 句柄 ≠ 成功;
+ *  - 取消 = handle.abort + sink.abort(sink.abort 幂等,exporter 收尾也会调);
+ *  - 场景 dispose:先 abort 在录任务,再恢复视图,最后拒绝未完成 Promise;
+ *  - JS 结果是 VideoExportResult(含 Blob);Blob 绝不 JSON 序列化,HTTP
+ *    侧由桥接适配为 fileId(jobResultSchema 描述 FileDescriptor)。
+ */
+import type { ISheet } from '@dreamerbird/core';
+import type { ShotExportHandle } from '../../videoExport/exporter';
+import type { ExportSink } from '../../videoExport/sinks';
+/**
+ * Agent 侧导出结果(JS API)。HTTP 桥接把 blob 写入临时文件后改发
+ * FileDescriptor(fileId/fileName/mimeType/size);blob 本身不进 JSON。
+ */
+export type VideoExportResult = {
+    blob: Blob;
+    fileName: string;
+    mimeType: string;
+    size: number;
+};
+/** UI/Agent 共用的导出请求;UI 只传用户所选 sink 与 onError 提示通道 */
+export type ShotExportRequest = {
+    /** 导出目标;缺省 = BlobCollectSink(Agent 路径:内存收集,不触发下载) */
+    sink?: ExportSink;
+    /** 指定相机 key;缺省 = 当前活动相机(不存在则先激活再切视角) */
+    cameraKey?: string;
+    /** 取消信号(jobs.cancel 触发);abort = handle.abort + sink.abort */
+    signal?: AbortSignal;
+    /** 进度回调 0..1(随 sequence 播放头) */
+    onProgress?: (progress: number) => void;
+    /**
+     * 出错提示通道:UI 传(对齐既有 onError 行为,录制失败由它提示);
+     * Agent 不传——失败走 Promise 拒绝,不双通道重复报告。
+     */
+    onError?: (message: string) => void;
+};
+/**
+ * 场景导出控制器。startVideo 返回的 Promise 以录制终态为准:
+ * 正常完成 resolve(UI sink / 用户取消系统对话框时为 undefined,内存
+ * 收集时为 VideoExportResult);失败/取消/dispose reject。
+ */
+export type SceneExportController = {
+    /** 正在导出(含挂起等待视角生效的请求与 UI 发起的导出) */
+    isExporting(): boolean;
+    getActiveCameraKey(): string | null;
+    hasCamera(cameraKey: string): boolean;
+    startVideo(request: ShotExportRequest): Promise<VideoExportResult | undefined>;
+    /**
+     * 场景副作用在 ShotView/活动相机切换生效后调用(对齐既有
+     * "切到镜头视角再开录"的时序);无挂起请求时静默 no-op。
+     */
+    notifySceneReady(): void;
+    /** 场景卸载:先 abort 在录任务,再恢复视图,最后拒绝未完成任务 */
+    dispose(): void;
+};
+/**
+ * CameraScene 挂载 effect 调用;返回解绑函数(仅当登记的还是同一
+ * 控制器才删,防过期 cleanup 抹掉新代次的登记,同 registerDirectorView)。
+ */
+export declare function registerSceneExportController(next: SceneExportController): () => void;
+/** 当前登记的场景导出控制器;未挂载为 undefined(命令映射 SCENE_UNAVAILABLE) */
+export declare function getSceneExportController(): SceneExportController | undefined;
+/** CameraScene 提供给控制器的会话态读写(getter 须经 ref 读最新值) */
+export type SceneExportDeps = {
+    sheet: ISheet;
+    getActiveCameraKey(): string | null;
+    hasCamera(cameraKey: string): boolean;
+    /** 激活指定相机(转发 setActiveCameraKey 会话态) */
+    setActiveCamera(cameraKey: string): void;
+    isExporting(): boolean;
+    getShotView(): boolean;
+    /** 请求切换镜头视角;生效时机由场景副作用经 notifySceneReady 回调 */
+    setShotView(on: boolean): void;
+    /** 页面上只有一个 canvas(快照编辑器的在 shadow DOM 里,查不到) */
+    getCanvas(): HTMLCanvasElement | null;
+    setExporting(on: boolean): void;
+    /** 同步在录句柄给场景(Esc 取消/相机删除中止/停止按钮共用) */
+    setActiveHandle(handle: ShotExportHandle | null): void;
+    /** 锁定开录时的相机:中途被删(本地/对端)由场景中止录制 */
+    lockExportCamera(cameraKey: string | null): void;
+};
+export declare function createSceneExportController(deps: SceneExportDeps): SceneExportController;
+//# sourceMappingURL=exportRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exportRuntime.d.ts","sourceRoot":"","sources":["../../../src/agent/runtime/exportRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAA;AAK7C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAA;AAChE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,yBAAyB,CAAA;AAEvD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,IAAI,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,gCAAgC;IAChC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACpC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,mCAAmC;IACnC,WAAW,IAAI,OAAO,CAAA;IACtB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAAA;IACnC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAA;IAC9E;;;OAGG;IACH,gBAAgB,IAAI,IAAI,CAAA;IACxB,wCAAwC;IACxC,OAAO,IAAI,IAAI,CAAA;CAChB,CAAA;AAID;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,qBAAqB,GAC1B,MAAM,IAAI,CAKZ;AAED,0DAA0D;AAC1D,wBAAgB,wBAAwB,IAAI,qBAAqB,GAAG,SAAS,CAE5E;AAgGD,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAAA;IACnC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC,wCAAwC;IACxC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxC,WAAW,IAAI,OAAO,CAAA;IACtB,WAAW,IAAI,OAAO,CAAA;IACtB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAC9B,+CAA+C;IAC/C,SAAS,IAAI,iBAAiB,GAAG,IAAI,CAAA;IACrC,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IAC/B,sCAAsC;IACtC,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAA;IACtD,kCAAkC;IAClC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;CACjD,CAAA;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,eAAe,GACpB,qBAAqB,CA+JvB"}