@dreamerbird/camera-studio 0.0.0-stage → 0.2.0

package/dist/agent/pathCommands.d.ts

@@ -0,0 +1,78 @@
+import type { ISheet } from '@dreamerbird/core';
+import type { BoundCameraReset } from '../pathRegistry';
+import type { Vec3Like } from '../pathModel';
+import type { PathPreset } from '../pathPresets';
+/**
+ * 预设创建:注册表取下一个可用 key → 同名孤儿(对象带旧点/已建轨)
+ * 先真删(同 UI placePresetPath 的教训:不删会被当既有路径延伸) →
+ * 一个事务同时写 meta points(局部坐标,P1..Pn)、position(落点)和
+ * Paths 注册表清单 = 一步撤销。
+ *
+ * center 由命令层算好(显式 at 或 findFreeSpot 避让结果)。
+ */
+export declare function createPresetPath(sheet: ISheet, preset: PathPreset, center: Vec3Like, beforeWrite?: () => void): {
+    pathKey: string;
+    pointKeys: string[];
+};
+/**
+ * 默认落点:findFreeSpot 避开已放置模型和已有路径的原点,基点原点
+ * (高度语义属 UI 的取景便利,Agent 命令默认落地面原点;要精确落点
+ * 传显式 at)。
+ */
+export declare function defaultPresetSpot(sheet: ISheet): Vec3Like;
+/** 加点:沿最后一段方向延伸等长一段;空名单拒绝(没点就不出现) */
+export declare function addPathPointDomain(sheet: ISheet, pathKey: string, beforeWrite?: () => void): {
+    pointKey: string;
+};
+/**
+ * 改控制点:position 整体替换(局部坐标),handle 拖一侧
+ * (withDraggedHandle 对齐规则:被拖侧取新偏移,另一侧共线镜像,
+ * 与 UI 手柄拖动同一纯函数)。两者可同一次给出 = 一个事务。
+ */
+export declare function updatePathPointDomain(sheet: ISheet, pathKey: string, pointKey: string, patch: {
+    position?: Vec3Like;
+    handle?: {
+        side: 'left' | 'right';
+        offset: Vec3Like;
+    };
+}, beforeWrite?: () => void): void;
+/**
+ * 调进度锚点:内部点写显式 u(withMovedU 夹到相邻锚点之间,保住单调,
+ * 与 UI 数值浮条同一纯函数);u:null = 清掉显式锚点恢复自动(弧长等比)。
+ * 首尾点恒为 0/1,显式设置/恢复都拒绝。
+ */
+export declare function setPathPointTimingDomain(sheet: ISheet, pathKey: string, pointKey: string, u: number | null, beforeWrite?: () => void): void;
+/**
+ * 删除路径前收集绑定它的相机(连同机位定格),折进清单移除的同一个
+ * scrub 回退——撤销删除时清单行/绑定/机位一起还原,不留"绑定还在但
+ * 路径没了"的中间态(见 pathRegistry.removePathFromRegistry 的撤销陷阱
+ * 注释)。
+ *
+ * 与 CameraScene.collectBoundCameraResets 同语义,数据源换成 Agent
+ * 运行时:相机 SheetObject 来自 objectRuntime(ShotCamera 登记),
+ * 定格采样来自 pathRuntime(CameraPath 登记);路径未挂载(无采样器)
+ * 或没点 = 没被驱动过,只清绑定不定格。
+ */
+export declare function collectBoundCamerasForPath(sheet: ISheet, pathKey: string): BoundCameraReset[];
+/**
+ * 删除整条路径(preflight ruling:领域函数的家在 agent 层,CameraScene
+ * UI、最后一点删除和 Task 14 的 objects.delete 都调这里):
+ * forgetObject 清持久数据 + 注册表移除 + 绑定相机回退(定格机位/清
+ * 绑定)合并为单个事务 = 一步撤销(2026-10-19,Task 14 合并,见
+ * removePathFromRegistry);detachObject 显式脱离是非 historic 清理,
+ * 放在事务之后。
+ *
+ * boundCameras 缺省时按 Agent 运行时登记现收集;CameraScene 传入自己
+ * 按 refs 收集的结果(既有 UI 行为逐行保留)。
+ */
+export declare function deletePathDomain(sheet: ISheet, pathKey: string, options?: {
+    boundCameras?: BoundCameraReset[];
+}): void;
+/**
+ * 删控制点:非最后一点只更新名单(一步撤销);删掉最后一个点 = 删除
+ * 整条路径("没点就不出现",走 deletePathDomain 的完整清理)。
+ */
+export declare function deletePathPointDomain(sheet: ISheet, pathKey: string, pointKey: string, beforeWrite?: () => void): {
+    pathDeleted: boolean;
+};
+//# sourceMappingURL=pathCommands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pathCommands.d.ts","sourceRoot":"","sources":["../../src/agent/pathCommands.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,MAAM,EAAwB,MAAM,mBAAmB,CAAA;AASpE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,iBAAiB,CAAA;AAcrD,OAAO,KAAK,EAAiB,QAAQ,EAAC,MAAM,cAAc,CAAA;AAE1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,gBAAgB,CAAA;AAiD9C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,QAAQ,EAChB,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAC,CA0BxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAUzD;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAiBpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE;IACL,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,MAAM,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAA;CACpD,EACD,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB,IAAI,CAoBN;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,CAAC,EAAE,MAAM,GAAG,IAAI,EAChB,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB,IAAI,CAoBN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,gBAAgB,EAAE,CA2BpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAC,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAAM,GAChD,IAAI,CAKN;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,IAAI,GACvB;IAAC,WAAW,EAAE,OAAO,CAAA;CAAC,CAoBxB"}

package/dist/agent/pathCommands.js

@@ -0,0 +1,240 @@
+/**
+ * 路径领域命令(2026-10-17,Task 11):预设创建、控制点读改写、
+ * 进度锚点和整路径删除的纯领域实现,供 `paths.*` 命令、CameraScene UI
+ * 和 Task 14 的 objects.delete 共用(preflight ruling:deletePathDomain
+ * 的家在这里,UI 不做领域所有者)。
+ *
+ * 约定:
+ * - 名单读改写一律 parsePathPoints → pathModel 纯函数变换 →
+ *   serializePathPoints,写入是单个 studio.transaction(一个命令一个
+ *   撤销步骤);回调同步,不跨 await。
+ * - `points` 是领域专属属性(propAccess.domainOwnedProps):写前先做
+ *   建轨预检(isPropSequenced),已建轨抛 INVALID_STATE——与
+ *   cameras/poses 的 domainOwned 写入同一 ruling。
+ * - beforeWrite 钩子:所有校验(点存在/建轨)之后、第一个历史写入之前
+ *   调用,命令层用它挂 expectedRevision 检查(先校验后 revision,
+ *   revision 先于任何副作用——同 cameras 的 writeCameraStaticProp 排序)。
+ * - 写路径允许落实 meta 句柄(getPathMeta);路径在注册表=对象必然
+ *   存在或允许创建(mutation 语义)。查询不走这里。
+ */
+import { getStudioSync, val } from '@dreamerbird/core';
+import { Vector3 } from 'three';
+import { getPathMeta, pathExists } from '../CameraPath';
+import { getPathsRegistry, nextPathEntry, readPathEntries, removePathFromRegistry, } from '../pathRegistry';
+import { getCamerasRegistry, readCameraEntries } from '../cameraRegistry';
+import { resolveBoundPathKey } from '../pathBinding';
+import { buildCurve, extendPathPoint, nextPointKey, parsePathPoints, serializePathPoints, withDraggedHandle, withMovedPoint, withMovedU, withResetU, } from '../pathModel';
+import { findFreeSpot, presetPlacement } from '../pathPresets';
+import { readPlacementPositions } from '../PlacementManager';
+import { isPropSequenced } from './propAccess';
+import { AgentApiError } from './errors';
+import { formatSceneObjectId } from './objectIds';
+import { getSceneSheetObject } from './runtime/objectRuntime';
+import { getPathSampler } from './runtime/pathRuntime';
+/** Studio 不可用 = SCENE_UNAVAILABLE(spec 8.3:静默 return 不得翻译成成功) */
+function requireStudio() {
+    const studio = getStudioSync();
+    if (!studio) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法写入路径');
+    }
+    return studio;
+}
+/** points 建轨预检:已建轨的名单写入会落成关键帧,拒绝(改用 keyframes.*) */
+function assertPointsStatic(meta, pathKey) {
+    if (isPropSequenced(meta, 'points')) {
+        throw new AgentApiError('INVALID_STATE', `路径 ${pathKey} 的控制点已建轨,拒绝静态写入`, { details: { pathKey, prop: 'points' } });
+    }
+}
+/** 单事务写名单(+ 可选同事务额外写入);调用前必须完成全部校验 */
+function commitPoints(studio, meta, entries, extra) {
+    studio.transaction(({ set }) => {
+        set(meta.props.points, serializePathPoints(entries));
+        extra?.(set);
+    });
+}
+function pointNotFound(pathKey, pointKey) {
+    return new AgentApiError('PATH_POINT_NOT_FOUND', `路径 ${pathKey} 没有控制点 ${pointKey}`, { details: { pathKey, pointKey } });
+}
+/**
+ * 预设创建:注册表取下一个可用 key → 同名孤儿(对象带旧点/已建轨)
+ * 先真删(同 UI placePresetPath 的教训:不删会被当既有路径延伸) →
+ * 一个事务同时写 meta points(局部坐标,P1..Pn)、position(落点)和
+ * Paths 注册表清单 = 一步撤销。
+ *
+ * center 由命令层算好(显式 at 或 findFreeSpot 避让结果)。
+ */
+export function createPresetPath(sheet, preset, center, beforeWrite) {
+    const studio = requireStudio();
+    const registry = getPathsRegistry(sheet);
+    const entry = nextPathEntry(readPathEntries(registry));
+    const orphanMeta = getPathMeta(sheet, entry.pathKey);
+    const orphan = parsePathPoints(orphanMeta.value.points).length > 0 ||
+        isPropSequenced(orphanMeta, 'points');
+    // 校验与探测完毕;revision 检查先于孤儿删除和播种这两个副作用
+    beforeWrite?.();
+    if (orphan) {
+        removePathFromRegistry(sheet, entry);
+    }
+    const meta = getPathMeta(sheet, entry.pathKey);
+    // 落点 = 路径原点:控制点存相对落点的局部坐标,位置变换在同一次提交里
+    const { points, position } = presetPlacement(preset, center);
+    const entries = points.map((p, i) => ({
+        key: `P${i + 1}`,
+        position: { x: p.x, y: p.y, z: p.z },
+    }));
+    const list = readPathEntries(registry);
+    commitPoints(studio, meta, entries, (set) => {
+        set(meta.props.position, { x: position.x, y: position.y, z: position.z });
+        set(registry.props.list, JSON.stringify([...list, entry]));
+    });
+    return { pathKey: entry.pathKey, pointKeys: entries.map((e) => e.key) };
+}
+/**
+ * 默认落点:findFreeSpot 避开已放置模型和已有路径的原点,基点原点
+ * (高度语义属 UI 的取景便利,Agent 命令默认落地面原点;要精确落点
+ * 传显式 at)。
+ */
+export function defaultPresetSpot(sheet) {
+    const occupied = [...readPlacementPositions(sheet)];
+    for (const entry of readPathEntries(getPathsRegistry(sheet))) {
+        if (!pathExists(sheet, entry.pathKey))
+            continue;
+        const position = val(getPathMeta(sheet, entry.pathKey).props.position);
+        if (position)
+            occupied.push(position);
+    }
+    return findFreeSpot(occupied);
+}
+/** 加点:沿最后一段方向延伸等长一段;空名单拒绝(没点就不出现) */
+export function addPathPointDomain(sheet, pathKey, beforeWrite) {
+    const studio = requireStudio();
+    const meta = getPathMeta(sheet, pathKey);
+    const entries = parsePathPoints(meta.value.points);
+    if (entries.length === 0) {
+        throw new AgentApiError('INVALID_STATE', `路径 ${pathKey} 没有控制点,无法延伸;请用 paths.createPreset 播种`, { details: { pathKey } });
+    }
+    assertPointsStatic(meta, pathKey);
+    const pointKey = nextPointKey(entries);
+    const position = extendPathPoint(entries);
+    beforeWrite?.();
+    commitPoints(studio, meta, [...entries, { key: pointKey, position }]);
+    return { pointKey };
+}
+/**
+ * 改控制点:position 整体替换(局部坐标),handle 拖一侧
+ * (withDraggedHandle 对齐规则:被拖侧取新偏移,另一侧共线镜像,
+ * 与 UI 手柄拖动同一纯函数)。两者可同一次给出 = 一个事务。
+ */
+export function updatePathPointDomain(sheet, pathKey, pointKey, patch, beforeWrite) {
+    const studio = requireStudio();
+    const meta = getPathMeta(sheet, pathKey);
+    const entries = parsePathPoints(meta.value.points);
+    if (!entries.some((e) => e.key === pointKey)) {
+        throw pointNotFound(pathKey, pointKey);
+    }
+    assertPointsStatic(meta, pathKey);
+    let next = entries;
+    if (patch.position)
+        next = withMovedPoint(next, pointKey, patch.position);
+    if (patch.handle) {
+        next = withDraggedHandle(next, pointKey, patch.handle.side, patch.handle.offset);
+    }
+    beforeWrite?.();
+    commitPoints(studio, meta, next);
+}
+/**
+ * 调进度锚点:内部点写显式 u(withMovedU 夹到相邻锚点之间,保住单调,
+ * 与 UI 数值浮条同一纯函数);u:null = 清掉显式锚点恢复自动(弧长等比)。
+ * 首尾点恒为 0/1,显式设置/恢复都拒绝。
+ */
+export function setPathPointTimingDomain(sheet, pathKey, pointKey, u, beforeWrite) {
+    const studio = requireStudio();
+    const meta = getPathMeta(sheet, pathKey);
+    const entries = parsePathPoints(meta.value.points);
+    const idx = entries.findIndex((e) => e.key === pointKey);
+    if (idx < 0)
+        throw pointNotFound(pathKey, pointKey);
+    if (idx === 0 || idx === entries.length - 1) {
+        throw new AgentApiError('INVALID_ARGUMENT', `首尾控制点的进度锚点固定为 0/1,只有内部点可调: ${pointKey}`, { details: { pathKey, pointKey } });
+    }
+    assertPointsStatic(meta, pathKey);
+    const next = u === null
+        ? withResetU(entries, pointKey)
+        : withMovedU(entries, pointKey, u, buildCurve(entries));
+    beforeWrite?.();
+    commitPoints(studio, meta, next);
+}
+/**
+ * 删除路径前收集绑定它的相机(连同机位定格),折进清单移除的同一个
+ * scrub 回退——撤销删除时清单行/绑定/机位一起还原,不留"绑定还在但
+ * 路径没了"的中间态(见 pathRegistry.removePathFromRegistry 的撤销陷阱
+ * 注释)。
+ *
+ * 与 CameraScene.collectBoundCameraResets 同语义,数据源换成 Agent
+ * 运行时:相机 SheetObject 来自 objectRuntime(ShotCamera 登记),
+ * 定格采样来自 pathRuntime(CameraPath 登记);路径未挂载(无采样器)
+ * 或没点 = 没被驱动过,只清绑定不定格。
+ */
+export function collectBoundCamerasForPath(sheet, pathKey) {
+    const registeredKeys = readPathEntries(getPathsRegistry(sheet)).map((e) => e.pathKey);
+    let freeze = null;
+    const sampler = getPathSampler(pathKey);
+    if (sampler && pathExists(sheet, pathKey)) {
+        const meta = getPathMeta(sheet, pathKey);
+        if (parsePathPoints(meta.value.points).length > 0) {
+            const progress = val(meta.props.progress) ?? 0;
+            const tmp = new Vector3();
+            if (sampler(progress, tmp)) {
+                freeze = { x: tmp.x, y: tmp.y, z: tmp.z };
+            }
+        }
+    }
+    const resets = [];
+    for (const entry of readCameraEntries(getCamerasRegistry(sheet))) {
+        const obj = getSceneSheetObject(formatSceneObjectId('camera', entry.cameraKey));
+        if (!obj)
+            continue;
+        const bound = val(obj.props.pathKey) ?? '';
+        if (resolveBoundPathKey(bound, registeredKeys) !== pathKey)
+            continue;
+        resets.push({ obj, freeze });
+    }
+    return resets;
+}
+/**
+ * 删除整条路径(preflight ruling:领域函数的家在 agent 层,CameraScene
+ * UI、最后一点删除和 Task 14 的 objects.delete 都调这里):
+ * forgetObject 清持久数据 + 注册表移除 + 绑定相机回退(定格机位/清
+ * 绑定)合并为单个事务 = 一步撤销(2026-10-19,Task 14 合并,见
+ * removePathFromRegistry);detachObject 显式脱离是非 historic 清理,
+ * 放在事务之后。
+ *
+ * boundCameras 缺省时按 Agent 运行时登记现收集;CameraScene 传入自己
+ * 按 refs 收集的结果(既有 UI 行为逐行保留)。
+ */
+export function deletePathDomain(sheet, pathKey, options = {}) {
+    requireStudio();
+    const boundCameras = options.boundCameras ?? collectBoundCamerasForPath(sheet, pathKey);
+    removePathFromRegistry(sheet, { pathKey }, boundCameras);
+}
+/**
+ * 删控制点:非最后一点只更新名单(一步撤销);删掉最后一个点 = 删除
+ * 整条路径("没点就不出现",走 deletePathDomain 的完整清理)。
+ */
+export function deletePathPointDomain(sheet, pathKey, pointKey, beforeWrite) {
+    const studio = requireStudio();
+    const meta = getPathMeta(sheet, pathKey);
+    const entries = parsePathPoints(meta.value.points);
+    if (!entries.some((e) => e.key === pointKey)) {
+        throw pointNotFound(pathKey, pointKey);
+    }
+    if (entries.length <= 1) {
+        beforeWrite?.();
+        deletePathDomain(sheet, pathKey);
+        return { pathDeleted: true };
+    }
+    assertPointsStatic(meta, pathKey);
+    beforeWrite?.();
+    commitPoints(studio, meta, entries.filter((e) => e.key !== pointKey));
+    return { pathDeleted: false };
+}

package/dist/agent/propAccess.d.ts

@@ -0,0 +1,42 @@
+import type { ISheetObject } from '@dreamerbird/core';
+import type { $IntentionalAny } from '@dreamerbird/core/types/public';
+import type { Pointer } from '@dreamerbird/dataverse';
+/**
+ * 领域命令专属属性:generic objects.update 拒绝写入;姿势/相机/锚点/路径
+ * 命令完成自身校验与建轨检查后,经 setStaticProps 写各自显式拥有的属性。
+ */
+declare const domainOwnedProps: Set<string>;
+export { domainOwnedProps };
+/** 按点路径('position.x')从 obj.props 导航出叶子指针,供 keyframes.* 使用 */
+export declare function getSimplePropPointer(obj: ISheetObject<$IntentionalAny>, propPath: string): Pointer<$IntentionalAny>;
+/**
+ * 检测属性是否已建轨。propPath 为顶层名('position')或点路径('position.x'):
+ * - 顶层简单属性:getTrackIdForProp 直接命中;
+ * - 顶层 compound:当前值的任一叶子建轨即整属性视为已建轨;
+ * - 叶子路径:sheet.sequence.getKeyframes(同 getKeyframesOfSimpleProp 的
+ *   内部 track map)非空即已建轨。
+ */
+export declare function isPropSequenced(obj: ISheetObject<$IntentionalAny>, propPath: string): boolean;
+/**
+ * 写前校验:属性存在、值形状递归匹配(有限数字/完整 compound)、未建轨。
+ * 全部通过才返回;任何一项失败抛出,调用方不得已进入事务。
+ */
+export declare function assertStaticPropsWritable(sheetObject: ISheetObject<$IntentionalAny>, props: Record<string, unknown>): void;
+/**
+ * 低层静态写入:先全量校验(值形状 + 建轨),再在单个事务内写完整个
+ * patch。供 objects.update 与领域命令复用;Studio 不可用抛
+ * SCENE_UNAVAILABLE(不静默返回,spec 8.3)。
+ */
+export declare function setStaticProps(sheetObject: ISheetObject<$IntentionalAny>, props: Record<string, unknown>): void;
+/**
+ * 领域静态写入 + 坐标定格同事务(2026-10-19,Agent API F1 修复):
+ * 绑定/父级切换类命令(setParent/clearParent/unbindPath/setAimTarget 解除)
+ * 把看护 effect 的坐标定格折进写领域属性的同一事务,守住
+ * undoable:'single-step' 契约(一次撤销同时回退属性与定格)。
+ *
+ * preflight(值形状 + 建轨拒绝)只覆盖 props 里的领域属性;freeze 里的
+ * position/rotation 与 UI 看护的 scrub 写入同语义——不做建轨拒绝
+ * (已建轨时 UI 看护同样照写),但只在领域属性通过校验后才落笔。
+ */
+export declare function setStaticPropsWithFreeze(sheetObject: ISheetObject<$IntentionalAny>, props: Record<string, unknown>, freeze: Record<string, unknown>): void;
+//# sourceMappingURL=propAccess.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"propAccess.d.ts","sourceRoot":"","sources":["../../src/agent/propAccess.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gCAAgC,CAAA;AACnE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAA;AAInD;;;GAGG;AACH,QAAA,MAAM,gBAAgB,aAWpB,CAAA;AAEF,OAAO,EAAC,gBAAgB,EAAC,CAAA;AAEzB,6DAA6D;AAC7D,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAM1B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,YAAY,CAAC,eAAe,CAAC,EAClC,QAAQ,EAAE,MAAM,GACf,OAAO,CAaT;AA4FD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAyBN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAGN;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,YAAY,CAAC,eAAe,CAAC,EAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAGN"}

package/dist/agent/propAccess.js

@@ -0,0 +1,181 @@
+/**
+ * 静态属性访问守卫(2026-10-17,Task 5):objects.update 与姿势/相机/路径
+ * 领域命令共用的值形状校验、建轨检测和单事务静态写入。检测逻辑集中在
+ * 本模块,不散落到各命令。
+ *
+ * 建轨检测与 poseTrack.getTrackIdForProp、Sequence.getKeyframesOfSimpleProp
+ * 读同一份内部 track map(historic tracksByObject):顶层简单属性直接复用
+ * getTrackIdForProp;compound 顶层与叶子路径经公共 sheet.sequence.getKeyframes
+ * 适配(其内部即 trackIdByPropPath,键为 encodePathToProp(path))。
+ *
+ * 写入经 getStudioSync(与 poseTrack/Anchors/ShotCamera 同先例);整个 patch
+ * 在单个 transaction 回调内同步写完,回调不跨 await。
+ */
+import { getStudioSync } from '@dreamerbird/core';
+import { getTrackIdForProp } from '../poseMode/poseTrack';
+import { AgentApiError } from './errors';
+/**
+ * 领域命令专属属性:generic objects.update 拒绝写入;姿势/相机/锚点/路径
+ * 命令完成自身校验与建轨检查后,经 setStaticProps 写各自显式拥有的属性。
+ */
+const domainOwnedProps = new Set([
+    'points',
+    'pose',
+    'poseOverride',
+    'gestureL',
+    'gestureR',
+    'animation',
+    'aimTarget',
+    'pathKey',
+    'parent',
+    'source',
+]);
+export { domainOwnedProps };
+/** 按点路径('position.x')从 obj.props 导航出叶子指针,供 keyframes.* 使用 */
+export function getSimplePropPointer(obj, propPath) {
+    let pointer = obj.props;
+    for (const segment of propPath.split('.')) {
+        pointer = pointer?.[segment];
+    }
+    return pointer;
+}
+/**
+ * 检测属性是否已建轨。propPath 为顶层名('position')或点路径('position.x'):
+ * - 顶层简单属性:getTrackIdForProp 直接命中;
+ * - 顶层 compound:当前值的任一叶子建轨即整属性视为已建轨;
+ * - 叶子路径:sheet.sequence.getKeyframes(同 getKeyframesOfSimpleProp 的
+ *   内部 track map)非空即已建轨。
+ */
+export function isPropSequenced(obj, propPath) {
+    const segments = propPath.split('.').filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        return false;
+    const [top, ...rest] = segments;
+    if (getTrackIdForProp(obj, top))
+        return true;
+    if (rest.length > 0)
+        return leafSequenced(obj, segments);
+    const current = obj.value?.[top];
+    if (current && typeof current === 'object') {
+        return collectLeafPaths(current).some((leaf) => leafSequenced(obj, [top, ...leaf]));
+    }
+    return false;
+}
+function leafSequenced(obj, segments) {
+    const pointer = getSimplePropPointer(obj, segments.join('.'));
+    return obj.sheet.sequence.getKeyframes(pointer).length > 0;
+}
+/** 收集 compound 当前值的全部叶子相对路径(空对象无叶子) */
+function collectLeafPaths(value, prefix = []) {
+    const paths = [];
+    for (const [key, child] of Object.entries(value)) {
+        if (child && typeof child === 'object' && !Array.isArray(child)) {
+            paths.push(...collectLeafPaths(child, [...prefix, key]));
+        }
+        else {
+            paths.push([...prefix, key]);
+        }
+    }
+    return paths;
+}
+/** 值形状与当前求值递归匹配;compound 键集合必须完全一致(不做部分深合并) */
+function validateValueShape(label, current, value) {
+    if (typeof current === 'number') {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是有限数字`);
+        }
+        return;
+    }
+    if (typeof current === 'string' || typeof current === 'boolean') {
+        if (typeof value !== typeof current) {
+            throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是 ${typeof current} 类型`);
+        }
+        return;
+    }
+    if (Array.isArray(current)) {
+        if (!Array.isArray(value) || value.length !== current.length) {
+            throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是长度为 ${current.length} 的数组`);
+        }
+        current.forEach((item, index) => validateValueShape(`${label}[${index}]`, item, value[index]));
+        return;
+    }
+    if (current && typeof current === 'object') {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须是对象`);
+        }
+        const currentRecord = current;
+        const valueRecord = value;
+        const missing = Object.keys(currentRecord).filter((key) => !(key in valueRecord));
+        const extra = Object.keys(valueRecord).filter((key) => !(key in currentRecord));
+        if (missing.length > 0 || extra.length > 0) {
+            const parts = [];
+            if (missing.length > 0)
+                parts.push(`缺少 ${missing.join('、')}`);
+            if (extra.length > 0)
+                parts.push(`多余 ${extra.join('、')}`);
+            throw new AgentApiError('INVALID_ARGUMENT', `${label} 必须提供完整 compound 值(${parts.join(';')})`);
+        }
+        for (const key of Object.keys(currentRecord)) {
+            validateValueShape(`${label}.${key}`, currentRecord[key], valueRecord[key]);
+        }
+        return;
+    }
+    throw new AgentApiError('INVALID_ARGUMENT', `${label} 的当前值无法确定形状,拒绝写入`);
+}
+/**
+ * 写前校验:属性存在、值形状递归匹配(有限数字/完整 compound)、未建轨。
+ * 全部通过才返回;任何一项失败抛出,调用方不得已进入事务。
+ */
+export function assertStaticPropsWritable(sheetObject, props) {
+    const current = sheetObject.value;
+    for (const [key, value] of Object.entries(props)) {
+        if (key.includes('.')) {
+            throw new AgentApiError('INVALID_ARGUMENT', `props 是顶层属性 patch,不接受嵌套路径: ${key}`);
+        }
+        if (!current || !(key in current)) {
+            throw new AgentApiError('INVALID_ARGUMENT', `未知属性: ${key}`, {
+                details: { prop: key },
+            });
+        }
+        validateValueShape(key, current[key], value);
+    }
+    for (const key of Object.keys(props)) {
+        if (isPropSequenced(sheetObject, key)) {
+            throw new AgentApiError('INVALID_STATE', `属性 ${key} 已建轨,请改用 keyframes.* 写入`, { details: { prop: key } });
+        }
+    }
+}
+/**
+ * 低层静态写入:先全量校验(值形状 + 建轨),再在单个事务内写完整个
+ * patch。供 objects.update 与领域命令复用;Studio 不可用抛
+ * SCENE_UNAVAILABLE(不静默返回,spec 8.3)。
+ */
+export function setStaticProps(sheetObject, props) {
+    assertStaticPropsWritable(sheetObject, props);
+    writePropsInTransaction(sheetObject, props);
+}
+/**
+ * 领域静态写入 + 坐标定格同事务(2026-10-19,Agent API F1 修复):
+ * 绑定/父级切换类命令(setParent/clearParent/unbindPath/setAimTarget 解除)
+ * 把看护 effect 的坐标定格折进写领域属性的同一事务,守住
+ * undoable:'single-step' 契约(一次撤销同时回退属性与定格)。
+ *
+ * preflight(值形状 + 建轨拒绝)只覆盖 props 里的领域属性;freeze 里的
+ * position/rotation 与 UI 看护的 scrub 写入同语义——不做建轨拒绝
+ * (已建轨时 UI 看护同样照写),但只在领域属性通过校验后才落笔。
+ */
+export function setStaticPropsWithFreeze(sheetObject, props, freeze) {
+    assertStaticPropsWritable(sheetObject, props);
+    writePropsInTransaction(sheetObject, { ...props, ...freeze });
+}
+function writePropsInTransaction(sheetObject, props) {
+    const studio = getStudioSync();
+    if (!studio) {
+        throw new AgentApiError('SCENE_UNAVAILABLE', 'Studio 不可用,无法写入静态属性');
+    }
+    studio.transaction(({ set }) => {
+        for (const [key, value] of Object.entries(props)) {
+            set(sheetObject.props[key], value);
+        }
+    });
+}

package/dist/agent/registerCommands.d.ts

@@ -0,0 +1,9 @@
+import type { AgentCommandRegistry } from './registry';
+import type { AgentRuntime } from './runtime';
+/**
+ * 注册全部 Agent 命令。每个执行代次一份注册表(命令闭包绑定该代次的
+ * runtime facade:handlers 是代次级 live 视图,assertCurrent 按代次判定),
+ * 换代由调用方重建。
+ */
+export declare function registerAllAgentCommands(registry: AgentCommandRegistry, runtime: AgentRuntime): void;
+//# sourceMappingURL=registerCommands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registerCommands.d.ts","sourceRoot":"","sources":["../../src/agent/registerCommands.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,WAAW,CAAA;AA8B3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,YAAY,GACpB,IAAI,CAkCN"}

package/dist/agent/registerCommands.js

@@ -0,0 +1,77 @@
+/**
+ * 全量 Agent 命令注册(2026-10-19,Task 15):按 Task 4–14 落地顺序
+ * 注册全部 18 个命令组(spec §9 命令面,71 条命令),供生产会话与
+ * 契约测试共用同一个注册入口。
+ *
+ * 重复命令兜底:registry.register 本身按名拒重(INVALID_STATE),注册
+ * 结束后再断言一次清单无重名——任何一个 register 模块被误注册两次
+ * (或将来合并模块时漏改名)都在这里立即炸,不带病运行。
+ */
+import { AgentApiError } from './errors';
+// Task 4:场景查询与选择(scene.getSnapshot / objects.list / objects.get)
+import { registerSceneCommands } from './commands/scene';
+import { registerSelectionCommands } from './commands/selection';
+// Task 5 + Task 14:静态属性更新(objects.update)与统一删除(objects.delete)
+import { registerObjectCommands } from './commands/objects';
+// Task 6:sequence 播放/定位/时长 + history 撤销重做
+import { registerSequenceCommands } from './commands/sequence';
+import { registerHistoryCommands } from './commands/history';
+// Task 7:显式关键帧
+import { registerKeyframeCommands } from './commands/keyframes';
+// Task 8:模型创建 + 资产管理 + 任务查询/取消
+import { registerModelCommands } from './commands/models';
+import { registerAssetCommands } from './commands/assets';
+import { registerJobCommands } from './commands/jobs';
+// Task 9:姿势/手势 + 动画
+import { registerPoseCommands } from './commands/poses';
+import { registerAnimationCommands } from './commands/animations';
+// Task 10:相机 + 锚点
+import { registerCameraCommands } from './commands/cameras';
+import { registerAnchorCommands } from './commands/anchors';
+// Task 11:路径预设/控制点/编辑会话
+import { registerPathCommands } from './commands/paths';
+// Task 12:视图 + UI + 项目导出
+import { registerViewCommands } from './commands/view';
+import { registerUiCommands } from './commands/ui';
+import { registerProjectCommands } from './commands/project';
+// Task 13:视频导出任务
+import { registerExportCommands } from './commands/exports';
+/**
+ * 注册全部 Agent 命令。每个执行代次一份注册表(命令闭包绑定该代次的
+ * runtime facade:handlers 是代次级 live 视图,assertCurrent 按代次判定),
+ * 换代由调用方重建。
+ */
+export function registerAllAgentCommands(registry, runtime) {
+    // Task 4
+    registerSceneCommands(registry, runtime);
+    registerSelectionCommands(registry, runtime);
+    // Task 5 + Task 14
+    registerObjectCommands(registry, runtime);
+    // Task 6
+    registerSequenceCommands(registry, runtime);
+    registerHistoryCommands(registry, runtime);
+    // Task 7
+    registerKeyframeCommands(registry, runtime);
+    // Task 8
+    registerModelCommands(registry, runtime);
+    registerAssetCommands(registry, runtime);
+    registerJobCommands(registry, runtime);
+    // Task 9
+    registerPoseCommands(registry, runtime);
+    registerAnimationCommands(registry, runtime);
+    // Task 10
+    registerCameraCommands(registry, runtime);
+    registerAnchorCommands(registry, runtime);
+    // Task 11
+    registerPathCommands(registry, runtime);
+    // Task 12
+    registerViewCommands(registry, runtime);
+    registerUiCommands(registry, runtime);
+    registerProjectCommands(registry, runtime);
+    // Task 13
+    registerExportCommands(registry, runtime);
+    const names = registry.describe().commands.map((command) => command.name);
+    if (new Set(names).size !== names.length) {
+        throw new AgentApiError('INVALID_STATE', '命令注册表存在重复命令名');
+    }
+}