@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/cameraRegistry.d.ts

@@ -0,0 +1,65 @@
+import type { ISheet, ISheetObject } from '@dreamerbird/core';
+import type { Object3D } from 'three';
+/** 注册表对象的 theatre key(大纲顶层 "Cameras" 行,和 Placements 同款) */
+export declare const CAMERAS_REGISTRY_KEY = "Cameras";
+/**
+ * 一台相机 = 一个 theatre 对象;旧清单里的 targetKey 解析时忽略
+ * (不做迁移,老相机自由朝向)
+ */
+export type CameraEntry = {
+    cameraKey: string;
+};
+/** 新相机的初始取景(添加时从导演视角捕获,组件挂载后消费) */
+export type CameraSeed = {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+export declare function getCamerasRegistry(sheet: ISheet): ISheetObject<{
+    list: import("@dreamerbird/core").PropTypeConfig_String;
+}>;
+/** 解析清单 JSON;坏数据一律回退空(注册表是底账,勿手改) */
+export declare function parseCameraEntries(json: string): CameraEntry[];
+export declare function readCameraEntries(registry: ISheetObject<any>): CameraEntry[];
+/**
+ * 多相机(P2)的命名:第一台 Shot Camera,之后 Shot Camera 2 / 3…。
+ * 顶层扁平后无前缀隔离,编号要同时避开注册表已用 key 和全场景已占用
+ * 路径(放置模型可能叫 "Shot Camera 2.fbx" 这种,探测只查不建)
+ */
+export declare function nextCameraEntry(sheet: ISheet, existing: readonly CameraEntry[]): CameraEntry;
+/** 界面显示名:旧状态(套文件夹时期)的 key 去掉 " / Camera" 后缀;
+ *  扁平化后的新 key 无后缀,原样即显示名 */
+export declare function cameraDisplayName(cameraKey: string): string;
+/** 响应式读相机清单:scrub 提交/撤销/同步都会触发 onValuesChange */
+export declare function useCamerasList(sheet: ISheet): CameraEntry[];
+export declare function stashCameraSeed(cameraKey: string, seed: CameraSeed): void;
+export declare function consumeCameraSeed(cameraKey: string): CameraSeed | undefined;
+/** 添加相机:注册表加一行(App 按清单渲染,组件挂载即创建对象) */
+export declare function addCameraToRegistry(sheet: ISheet, entry: CameraEntry, seed?: CameraSeed): void;
+/**
+ * 删除相机:单个事务完成 forgetObject + 注册表移除 = 一步撤销
+ * (2026-10-19,Task 14 合并;原先两个事务两步撤销)。
+ *
+ * forgetObject 走 stateEditors 按地址清持久数据(静态覆盖 + 时间轴
+ * 轨道,同步到所有客户端):不再要求挂载中的对象句柄——注册表有条目
+ * 但组件未挂载(或已脱离对象表)的相机同样真删,不静默跳过
+ * (schema 编辑器对无持久数据的对象先查后删,幂等不抛)。
+ * 注册表行移除 → 组件卸载 → detachObject → 大纲行消失。
+ */
+export declare function removeCamera(sheet: ISheet, entry: CameraEntry): void;
+/**
+ * 活动相机推导(2026-10-19,Task 14 抽成纯函数):activeCameraKey 失效
+ * (被删/对端同步)时顺位清单第一台,空清单为 null。CameraScene 的
+ * 活动相机、objects.delete 的「删除活动相机按现有规则回退」共用。
+ */
+export declare function resolveActiveCamera(cameras: readonly CameraEntry[], activeCameraKey: string | null): CameraEntry | null;
+export declare function registerShotCameraObject(cameraKey: string, obj: Object3D | null): void;
+export declare function getShotCameraObjects(): ReadonlyMap<string, Object3D>;
+//# sourceMappingURL=cameraRegistry.d.ts.map

package/dist/cameraRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameraRegistry.d.ts","sourceRoot":"","sources":["../src/cameraRegistry.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAC,MAAM,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAM3D,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,OAAO,CAAA;AAGnC,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAE7C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAAA;AAE7C,mCAAmC;AACnC,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;IAC3C,QAAQ,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;CAC5C,CAAA;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM;;GAO/C;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAgB9D;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,WAAW,EAAE,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,WAAW,EAAE,GAC/B,WAAW,CAQb;AAED;4BAC4B;AAC5B,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAU3D;AAQD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,QAElE;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAI3E;AAED,uCAAuC;AACvC,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,EAClB,IAAI,CAAC,EAAE,UAAU,QAclB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,QAoB7D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B,WAAW,GAAG,IAAI,CAIpB;AAKD,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,QAAQ,GAAG,IAAI,GACnB,IAAI,CAMN;AAED,wBAAgB,oBAAoB,IAAI,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAEpE"}

package/dist/cameraRegistry.js

@@ -0,0 +1,151 @@
+// packages/camera-studio/src/cameraRegistry.ts
+/**
+ * 相机注册表:场景里有几台相机 = 注册表清单里有几行,每台相机是一个
+ * theatre 对象。照搬放置模型(Placements)的注册表模式,结构天然支持
+ * 多相机;P1 在工具条上限一台。
+ *
+ * 生命周期:添加 = 注册表加一行(App 按清单渲染 ShotCamera,组件挂载
+ * 即创建对象、大纲行出现);删除 = forgetObject 清持久数据 + 注册表
+ * 移除(组件卸载 → detachObject → 大纲行消失)。
+ */
+import { getStudioSync, types as t, val } from '@dreamerbird/core';
+// 内部 Studio 通道:合并事务需要 stateEditors.forgetObject(按地址清持久
+// 数据,不要求对象已挂载)——与 keyframeTracks/poseTrack 同先例
+import getStudio from '@dreamerbird/studio/getStudio';
+import { useEffect, useMemo, useState } from 'react';
+import { notifyTargetRegistryChange, sheetObjectExists } from './aimTargets';
+/** 注册表对象的 theatre key(大纲顶层 "Cameras" 行,和 Placements 同款) */
+export const CAMERAS_REGISTRY_KEY = 'Cameras';
+export function getCamerasRegistry(sheet) {
+    // 注册表只是存数据的对象,不出现在大纲树
+    return sheet.object(CAMERAS_REGISTRY_KEY, { list: t.string('[]') }, { hideFromOutline: true });
+}
+/** 解析清单 JSON;坏数据一律回退空(注册表是底账,勿手改) */
+export function parseCameraEntries(json) {
+    try {
+        const list = JSON.parse(json);
+        if (!Array.isArray(list))
+            return [];
+        return list
+            .filter((item) => typeof item === 'object' &&
+            item !== null &&
+            typeof item.cameraKey === 'string' &&
+            item.cameraKey.length > 0)
+            .map((item) => ({ cameraKey: item.cameraKey }));
+    }
+    catch {
+        return [];
+    }
+}
+export function readCameraEntries(registry) {
+    return parseCameraEntries(val(registry.props.list));
+}
+/**
+ * 多相机(P2)的命名:第一台 Shot Camera,之后 Shot Camera 2 / 3…。
+ * 顶层扁平后无前缀隔离,编号要同时避开注册表已用 key 和全场景已占用
+ * 路径(放置模型可能叫 "Shot Camera 2.fbx" 这种,探测只查不建)
+ */
+export function nextCameraEntry(sheet, existing) {
+    const used = new Set(existing.map((e) => e.cameraKey));
+    for (let n = 1;; n++) {
+        const cameraKey = n === 1 ? 'Shot Camera' : `Shot Camera ${n}`;
+        if (!used.has(cameraKey) && !sheetObjectExists(sheet, cameraKey)) {
+            return { cameraKey };
+        }
+    }
+}
+/** 界面显示名:旧状态(套文件夹时期)的 key 去掉 " / Camera" 后缀;
+ *  扁平化后的新 key 无后缀,原样即显示名 */
+export function cameraDisplayName(cameraKey) {
+    return cameraKey.replace(/ \/ Camera$/, '');
+}
+/** 响应式读相机清单:scrub 提交/撤销/同步都会触发 onValuesChange */
+export function useCamerasList(sheet) {
+    const registry = useMemo(() => getCamerasRegistry(sheet), [sheet]);
+    const [list, setList] = useState(() => readCameraEntries(registry));
+    useEffect(() => {
+        setList(readCameraEntries(registry));
+        return registry.onValuesChange(() => setList(readCameraEntries(registry)));
+    }, [registry]);
+    return list;
+}
+/**
+ * 新相机的取景种子:组件挂载前对象还不存在,没法直接写属性——
+ * 添加时先把种子存这里,ShotCamera 挂载后消费一次。
+ */
+const pendingSeeds = new Map();
+export function stashCameraSeed(cameraKey, seed) {
+    pendingSeeds.set(cameraKey, seed);
+}
+export function consumeCameraSeed(cameraKey) {
+    const seed = pendingSeeds.get(cameraKey);
+    pendingSeeds.delete(cameraKey);
+    return seed;
+}
+/** 添加相机:注册表加一行(App 按清单渲染,组件挂载即创建对象) */
+export function addCameraToRegistry(sheet, entry, seed) {
+    const studio = getStudioSync();
+    if (!studio)
+        return;
+    const registry = getCamerasRegistry(sheet);
+    const list = readCameraEntries(registry);
+    // 连击/重入防护:同一 cameraKey 已存在就不重复提交
+    if (list.some((e) => e.cameraKey === entry.cameraKey))
+        return;
+    const scrub = studio.scrub();
+    scrub.capture(({ set }) => set(registry.props.list, JSON.stringify([...list, entry])));
+    scrub.commit();
+    if (seed)
+        stashCameraSeed(entry.cameraKey, seed);
+}
+/**
+ * 删除相机:单个事务完成 forgetObject + 注册表移除 = 一步撤销
+ * (2026-10-19,Task 14 合并;原先两个事务两步撤销)。
+ *
+ * forgetObject 走 stateEditors 按地址清持久数据(静态覆盖 + 时间轴
+ * 轨道,同步到所有客户端):不再要求挂载中的对象句柄——注册表有条目
+ * 但组件未挂载(或已脱离对象表)的相机同样真删,不静默跳过
+ * (schema 编辑器对无持久数据的对象先查后删,幂等不抛)。
+ * 注册表行移除 → 组件卸载 → detachObject → 大纲行消失。
+ */
+export function removeCamera(sheet, entry) {
+    const studio = getStudio();
+    if (!studio)
+        return;
+    // 没来得及挂载消费掉的取景种子一并清掉,不留残留
+    pendingSeeds.delete(entry.cameraKey);
+    const registry = getCamerasRegistry(sheet);
+    const list = readCameraEntries(registry);
+    studio.transaction(({ set, stateEditors }) => {
+        stateEditors.coreByProject.historic.sheetsById.forgetObject({
+            projectId: sheet.address.projectId,
+            sheetId: sheet.address.sheetId,
+            // 业务 key 跨适配层边界按不透明字符串传递,此处回到 core 的名义类型
+            // (同 keyframeTracks 的 trackId as SequenceTrackId)
+            objectKey: entry.cameraKey,
+        });
+        set(registry.props.list, JSON.stringify(list.filter((e) => e.cameraKey !== entry.cameraKey)));
+    });
+}
+/**
+ * 活动相机推导(2026-10-19,Task 14 抽成纯函数):activeCameraKey 失效
+ * (被删/对端同步)时顺位清单第一台,空清单为 null。CameraScene 的
+ * 活动相机、objects.delete 的「删除活动相机按现有规则回退」共用。
+ */
+export function resolveActiveCamera(cameras, activeCameraKey) {
+    return (cameras.find((e) => e.cameraKey === activeCameraKey) ?? cameras[0] ?? null);
+}
+/** 拍摄相机的 cameraKey → three 相机对象(锚点父级绑定的 camera: 解析用) */
+const shotCameraObjects = new Map();
+export function registerShotCameraObject(cameraKey, obj) {
+    if (obj)
+        shotCameraObjects.set(cameraKey, obj);
+    else
+        shotCameraObjects.delete(cameraKey);
+    // 与 registerAnchorObject 同机制:登记表变更广播,ShotCamera 等的
+    // 瞄准/父级解析随挂载/注销即时翻正(循环 import 仅运行时调用,安全)
+    notifyTargetRegistryChange();
+}
+export function getShotCameraObjects() {
+    return shotCameraObjects;
+}

package/dist/cameraRegistry.test.d.ts

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

package/dist/cameraRegistry.test.d.ts.map

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

package/dist/cameraRegistry.test.js

@@ -0,0 +1,68 @@
+// packages/camera-studio/src/cameraRegistry.test.ts
+import { setPrivateAPI } from '@dreamerbird/core/privateAPIs';
+import { nextCameraEntry, parseCameraEntries, cameraDisplayName, stashCameraSeed, consumeCameraSeed, } from './cameraRegistry';
+describe('parseCameraEntries', () => {
+    test('解析合法清单;坏 JSON/非数组回退空', () => {
+        expect(parseCameraEntries('[]')).toEqual([]);
+        const one = [
+            { cameraKey: 'Shot Camera / Camera', targetKey: 'Shot Camera / Target' },
+        ];
+        // 旧格式宽容解析:targetKey 被忽略
+        expect(parseCameraEntries(JSON.stringify(one))).toEqual([
+            { cameraKey: 'Shot Camera / Camera' },
+        ]);
+        expect(parseCameraEntries('not json')).toEqual([]);
+        expect(parseCameraEntries('{"a":1}')).toEqual([]);
+    });
+    test('过滤畸形项', () => {
+        expect(parseCameraEntries('[{"cameraKey":"A","targetKey":"B"},{"foo":"bar"},{"cameraKey":1,"targetKey":"T"}]')).toEqual([{ cameraKey: 'A' }]);
+    });
+});
+describe('cameraDisplayName', () => {
+    test('旧格式(套文件夹时期)的 key 去掉 " / Camera" 后缀', () => {
+        expect(cameraDisplayName('Shot Camera / Camera')).toBe('Shot Camera');
+        expect(cameraDisplayName('Shot Camera 3 / Camera')).toBe('Shot Camera 3');
+    });
+    test('扁平化后的新 key 无后缀,原样即显示名', () => {
+        expect(cameraDisplayName('Shot Camera')).toBe('Shot Camera');
+        expect(cameraDisplayName('Shot Camera 2')).toBe('Shot Camera 2');
+        expect(cameraDisplayName('')).toBe('');
+    });
+});
+describe('nextCameraEntry', () => {
+    // 顶层扁平化后的命名:第一台 Shot Camera,之后 Shot Camera 2/3…;
+    // 编号同时避开注册表已用 key 与全场景已占用路径(sheetObjectExists 探测)
+    test('空清单给第一台', () => {
+        expect(nextCameraEntry({}, [])).toEqual({ cameraKey: 'Shot Camera' });
+    });
+    test('占用后递增编号,跳过已用的', () => {
+        const existing = [{ cameraKey: 'Shot Camera' }, { cameraKey: 'Shot Camera 3' }];
+        expect(nextCameraEntry({}, existing)).toEqual({
+            cameraKey: 'Shot Camera 2',
+        });
+    });
+    test('旧格式(套文件夹)key 不占新名:新旧路径不同,第一台仍给 Shot Camera', () => {
+        expect(nextCameraEntry({}, [{ cameraKey: 'Shot Camera / Camera' }])).toEqual({
+            cameraKey: 'Shot Camera',
+        });
+    });
+    test('全场景路径被占(如模型叫了 Shot Camera.fbx)时跳过', () => {
+        const sheet = { type: 'Sheet' };
+        setPrivateAPI(sheet, {
+            getObject: (key) => (key === 'Shot Camera' ? {} : undefined),
+        });
+        expect(nextCameraEntry(sheet, [])).toEqual({ cameraKey: 'Shot Camera 2' });
+    });
+});
+describe('相机取景种子', () => {
+    test('consume 一次性:取走就没', () => {
+        const seed = {
+            position: { x: 1, y: 2, z: 3 },
+            rotation: { x: 0, y: 0, z: 0 },
+        };
+        stashCameraSeed('Shot Camera / Camera', seed);
+        expect(consumeCameraSeed('Shot Camera / Camera')).toEqual(seed);
+        expect(consumeCameraSeed('Shot Camera / Camera')).toBeUndefined();
+        expect(consumeCameraSeed('没存过的')).toBeUndefined();
+    });
+});

package/dist/config.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 宿主可见的配置与句柄类型(spec §3 逐字为宿主所见形态)。
+ *
+ * CameraFlows 类型取自 ./hostFlows(定义所在);简报草样写 './App',
+ * 但 App.tsx 只默认导出组件、不转出口该类型,从定义处引入才编译得过。
+ */
+import type { IProject } from '@dreamerbird/core';
+import type { WritableLibrarySource } from './assetLibrary/source';
+import type { CameraStudioErrorHandler } from './errors';
+import type { CameraFlows } from './hostFlows';
+import type { CameraStudioApi } from './agent/api';
+/**
+ * Agent 桥接连接配置(spec §10.3/§10.4,Task 6)。
+ * 浏览器默认不连接桥接:只有宿主显式配置本项才启动桥接客户端;
+ * 配置变化按既有 boot 规则处理(重挂告警,换配置需整页刷新)。
+ */
+export type CameraStudioAgentBridgeConfig = {
+    /** 桥接 WebSocket 地址,如 ws://127.0.0.1:43110 */
+    url: string;
+    /**
+     * Bearer 凭据:WebSocket subprotocol(token.<encoded>)与桥接 HTTP
+     * 文件传输(Authorization)共用;绝不写入日志
+     */
+    token: string;
+    /** 桥接 HTTP 地址(二进制 File/Blob ↔ fileId 适配),如 http://127.0.0.1:43110 */
+    httpUrl: string;
+};
+/** Agent JS API 配置(spec §7;首 boot 锁定,重挂换配置不生效) */
+export type CameraStudioAgentConfig = {
+    /**
+     * 场景 ready 后把 api 挂载为 window.__cameraStudioApi(浏览器默认不挂,
+     * 不连接桥接);会话拆解时删除。缺省 false
+     */
+    exposeGlobal?: boolean;
+    /** 本机桥接连接;缺省不连接(浏览器默认不连桥接) */
+    bridge?: CameraStudioAgentBridgeConfig;
+};
+export interface CameraStudioConfig {
+    /** id 字符串(getProject)或 IProject 实例;缺省 'Space' */
+    project?: string | IProject;
+    /** 场景状态宿主接管;传了即关 theatre 本地持久化 */
+    state?: {
+        initialState?: unknown;
+        onStateChange?: (content: unknown) => void;
+        /** onStateChange 节流,缺省 1000ms(尾部触发,卸载时 flush) */
+        throttleMs?: number;
+    };
+    /** 宿主错误提示入口:库存储/启动清理/视频导出错误统一上告;不传保持内置提示行为 */
+    onError?: CameraStudioErrorHandler;
+    /** 可写源实例 | 「namespace」内置 IDB 简写(库名 toybox-asset-library[-namespace],
+        不带 namespace 与现状一字不差) | false 纯查看器(仅内置目录);缺省 = 现状 */
+    storage?: WritableLibrarySource | {
+        namespace?: string;
+    } | false;
+    /** 内置目录文件根;缺省包内 assets */
+    assets?: {
+        baseUrl?: string;
+    };
+    /** 协作端点;缺省 false(关) */
+    sync?: {
+        serverUrl?: string;
+    } | false;
+    ui?: {
+        portalContainer?: HTMLElement;
+        zIndexBase?: number;
+        locale?: string;
+        /** 隐藏 studio 左上角带 logo 的整条 LeftStrip(应用 logo + 工作区按钮) */
+        hideLeftStrip?: boolean;
+    };
+    flows?: {
+        onFlows?: (flows: CameraFlows) => void;
+    };
+    /** Agent JS API 行为配置;缺省不挂 window 全局 */
+    agent?: CameraStudioAgentConfig;
+}
+/** CameraScene 的 props 形态(T9 落地组件);对宿主不透明,不解构 */
+export type CameraSceneProps = {
+    project: IProject;
+    onFlows?: (flows: CameraFlows) => void;
+    onError?: CameraStudioErrorHandler;
+};
+export interface CameraStudioHandle {
+    ready: boolean;
+    error: Error | undefined;
+    sceneProps: CameraSceneProps;
+    /**
+     * Agent JS API 门面(spec §7):模块级单例,首帧即稳定(后续 render
+     * 同一对象);`api.ready` 在 project+studio+Scene Runtime 就位后兑现
+     */
+    api: CameraStudioApi;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,uBAAuB,CAAA;AAChE,OAAO,KAAK,EAAC,wBAAwB,EAAC,MAAM,UAAU,CAAA;AACtD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAA;AAEhD;;;;GAIG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,kDAAkD;AAClD,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,6BAA6B,CAAA;CACvC,CAAA;AAED,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC3B,kCAAkC;IAClC,KAAK,CAAC,EAAE;QACN,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;QAC1C,iDAAiD;QACjD,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,CAAA;IACD,8CAA8C;IAC9C,OAAO,CAAC,EAAE,wBAAwB,CAAA;IAClC;4DACwD;IACxD,OAAO,CAAC,EAAE,qBAAqB,GAAG;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,KAAK,CAAA;IAC9D,0BAA0B;IAC1B,MAAM,CAAC,EAAE;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;IAC3B,uBAAuB;IACvB,IAAI,CAAC,EAAE;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAC,GAAG,KAAK,CAAA;IACnC,EAAE,CAAC,EAAE;QACH,eAAe,CAAC,EAAE,WAAW,CAAA;QAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,yDAAyD;QACzD,aAAa,CAAC,EAAE,OAAO,CAAA;KACxB,CAAA;IACD,KAAK,CAAC,EAAE;QAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;KAAC,CAAA;IAChD,uCAAuC;IACvC,KAAK,CAAC,EAAE,uBAAuB,CAAA;CAChC;AAED,iDAAiD;AACjD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,QAAQ,CAAA;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,OAAO,CAAC,EAAE,wBAAwB,CAAA;CACnC,CAAA;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;IACxB,UAAU,EAAE,gBAAgB,CAAA;IAC5B;;;OAGG;IACH,GAAG,EAAE,eAAe,CAAA;CACrB"}

package/dist/config.js

@@ -0,0 +1 @@
+export {};

package/dist/contextMenu.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 画布右键菜单的统一出口：studio ContextMenu 的薄封装。
+ * 样式/定位/点外关闭/Esc 关闭全部交给 studio 实现，
+ * 这里只把"光标位置 + 菜单项 + 关闭回调"对齐过去。
+ */
+import React from 'react';
+import type { ContextMenuItem } from '@dreamerbird/studio/uiComponents/chordial/chordialInternals';
+export declare function CanvasContextMenu({ position, items, onClose, }: {
+    position: {
+        x: number;
+        y: number;
+    };
+    items: ContextMenuItem[];
+    onClose: () => void;
+}): React.JSX.Element;
+//# sourceMappingURL=contextMenu.d.ts.map

package/dist/contextMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextMenu.d.ts","sourceRoot":"","sources":["../src/contextMenu.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,6DAA6D,CAAA;AAEhG,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,KAAK,EACL,OAAO,GACR,EAAE;IACD,QAAQ,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAA;IAChC,KAAK,EAAE,eAAe,EAAE,CAAA;IACxB,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,qBAQA"}

package/dist/contextMenu.js

@@ -0,0 +1,10 @@
+/**
+ * 画布右键菜单的统一出口：studio ContextMenu 的薄封装。
+ * 样式/定位/点外关闭/Esc 关闭全部交给 studio 实现，
+ * 这里只把"光标位置 + 菜单项 + 关闭回调"对齐过去。
+ */
+import React from 'react';
+import ContextMenu from '@dreamerbird/studio/uiComponents/simpleContextMenu/ContextMenu/ContextMenu';
+export function CanvasContextMenu({ position, items, onClose, }) {
+    return (React.createElement(ContextMenu, { items: items, clickPoint: { clientX: position.x, clientY: position.y }, onRequestClose: onClose }));
+}

package/dist/dropPoint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 指针位置 → 场景落点:登记过的物体表面优先,y=0 地面(数学平面,无限大)
+ * 兜底,视线朝天/贴地时退到"前方 30 个单位、压到地面"——任何视角都有落点。
+ * 从 PlacementRigCore 抽出,模型放置幽灵和路径预设落点标记共用。
+ *
+ * 不用不可见网格接事件:视线与地面平行时网格永远打不中,事件根本不触发。
+ */
+import { Vector3 } from 'three';
+import type { Camera, Object3D, Raycaster } from 'three';
+export declare function computeDropPoint(raycaster: Raycaster, camera: Camera, surfaces: Iterable<Object3D>, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, clientX: number, clientY: number, 
+/** 表面分支胜出时回填命中的登记根(命中网格往上走到 surfaces 里的祖先) */
+out?: {
+    surfaceRoot: Object3D | null;
+}): Vector3;
+/**
+ * 指针位置 → 视平面落点(Blender G 抓取的默认语义):指针射线与
+ * 「过锚点、垂直于视线的平面」求交。视平面随相机倾斜,指针上移 =
+ * 世界里升高,高度自由;顶视时平面水平,退化为纯水平移动(同 Blender
+ * 顶视图里 G 只能平移)。射线与平面平行/平面退到相机身后时返回 null,
+ * 调用方保持上一帧点位不动。
+ */
+export declare function computeViewPlanePoint(raycaster: Raycaster, camera: Camera, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, clientX: number, clientY: number, 
+/** 视平面锚点:决定平面的深度和基准高度(拖动开始时的落点) */
+anchor: Vector3): Vector3 | null;
+/**
+ * 竖直轴向约束(Blender 拖动中按 Z):锁定基准点的 x/z,指针控制 y。
+ * 取「过基准点的竖直线」与指针射线的最近点参数——射线到轴线的垂足即
+ * 手感上"指针所指的高度"。视线与竖直轴平行(正顶/正仰视)时无解,返回
+ * null,调用方保持上一帧点位。
+ */
+export declare function computeVerticalConstraintPoint(raycaster: Raycaster, camera: Camera, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, clientX: number, clientY: number, 
+/** 约束基准点:x/z 被锁定为它,y 从它起算 */
+base: Vector3): Vector3 | null;
+/**
+ * 水平面约束(Blender 拖动中按 Shift+Z):锁定基准点的 y,指针在
+ * 水平面内自由移动 x/z。视线与水平面平行时无解,返回 null。
+ */
+export declare function computeHorizontalConstraintPoint(raycaster: Raycaster, camera: Camera, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, clientX: number, clientY: number, 
+/** 约束基准点:y 被锁定为它 */
+base: Vector3): Vector3 | null;
+//# sourceMappingURL=dropPoint.d.ts.map

package/dist/dropPoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropPoint.d.ts","sourceRoot":"","sources":["../src/dropPoint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAiB,OAAO,EAAC,MAAM,OAAO,CAAA;AAC7C,OAAO,KAAK,EAAC,MAAM,EAAQ,QAAQ,EAAE,SAAS,EAAC,MAAM,OAAO,CAAA;AAI5D,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC5B,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,EAChE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;AACf,8CAA8C;AAC9C,GAAG,CAAC,EAAE;IAAC,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAC,GACnC,OAAO,CAmCT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,EAChE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;AACf,mCAAmC;AACnC,MAAM,EAAE,OAAO,GACd,OAAO,GAAG,IAAI,CAShB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,EAChE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;AACf,6BAA6B;AAC7B,IAAI,EAAE,OAAO,GACZ,OAAO,GAAG,IAAI,CAkBhB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,EAChE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;AACf,oBAAoB;AACpB,IAAI,EAAE,OAAO,GACZ,OAAO,GAAG,IAAI,CAQhB"}

package/dist/dropPoint.js

@@ -0,0 +1,97 @@
+/**
+ * 指针位置 → 场景落点:登记过的物体表面优先,y=0 地面(数学平面,无限大)
+ * 兜底,视线朝天/贴地时退到"前方 30 个单位、压到地面"——任何视角都有落点。
+ * 从 PlacementRigCore 抽出,模型放置幽灵和路径预设落点标记共用。
+ *
+ * 不用不可见网格接事件:视线与地面平行时网格永远打不中,事件根本不触发。
+ */
+import { Plane, Vector2, Vector3 } from 'three';
+const GROUND_PLANE = new Plane(new Vector3(0, 1, 0), 0);
+export function computeDropPoint(raycaster, camera, surfaces, rect, clientX, clientY, 
+/** 表面分支胜出时回填命中的登记根(命中网格往上走到 surfaces 里的祖先) */
+out) {
+    const ndc = new Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+    raycaster.setFromCamera(ndc, camera);
+    // 表面优先:只对登记过的落点表面检测,只认 Mesh 命中
+    const roots = [...surfaces];
+    const surface = raycaster
+        .intersectObjects(roots, true)
+        .find((h) => h.object.isMesh);
+    const ground = raycaster.ray.intersectPlane(GROUND_PLANE, new Vector3());
+    // 相机贴地(y≈0)时地面会在"相机脚下"命中(t≈0),这个命中比任何
+    // 表面都"近"但就在相机自己身上,没有放置意义——半单位以内丢弃
+    const usableGround = ground && raycaster.ray.origin.distanceTo(ground) > 0.5 ? ground : null;
+    if (surface &&
+        (!usableGround ||
+            surface.distance <= raycaster.ray.origin.distanceTo(usableGround))) {
+        if (out) {
+            const rootSet = new Set(roots);
+            let node = surface.object;
+            while (node && !rootSet.has(node))
+                node = node.parent;
+            out.surfaceRoot = node;
+        }
+        return surface.point;
+    }
+    if (out)
+        out.surfaceRoot = null;
+    if (usableGround)
+        return usableGround;
+    // 视线与地面平行、朝天、或贴地:放到正前方 30 个单位、压到地面
+    const ahead = raycaster.ray.at(30, new Vector3());
+    ahead.y = 0;
+    return ahead;
+}
+/**
+ * 指针位置 → 视平面落点(Blender G 抓取的默认语义):指针射线与
+ * 「过锚点、垂直于视线的平面」求交。视平面随相机倾斜,指针上移 =
+ * 世界里升高,高度自由;顶视时平面水平,退化为纯水平移动(同 Blender
+ * 顶视图里 G 只能平移)。射线与平面平行/平面退到相机身后时返回 null,
+ * 调用方保持上一帧点位不动。
+ */
+export function computeViewPlanePoint(raycaster, camera, rect, clientX, clientY, 
+/** 视平面锚点:决定平面的深度和基准高度(拖动开始时的落点) */
+anchor) {
+    const ndc = new Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+    raycaster.setFromCamera(ndc, camera);
+    const forward = camera.getWorldDirection(new Vector3());
+    const plane = new Plane().setFromNormalAndCoplanarPoint(forward, anchor);
+    return raycaster.ray.intersectPlane(plane, new Vector3());
+}
+/**
+ * 竖直轴向约束(Blender 拖动中按 Z):锁定基准点的 x/z,指针控制 y。
+ * 取「过基准点的竖直线」与指针射线的最近点参数——射线到轴线的垂足即
+ * 手感上"指针所指的高度"。视线与竖直轴平行(正顶/正仰视)时无解,返回
+ * null,调用方保持上一帧点位。
+ */
+export function computeVerticalConstraintPoint(raycaster, camera, rect, clientX, clientY, 
+/** 约束基准点:x/z 被锁定为它,y 从它起算 */
+base) {
+    const ndc = new Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+    raycaster.setFromCamera(ndc, camera);
+    const ro = raycaster.ray.origin;
+    const rd = raycaster.ray.direction; // 单位向量
+    // 线-线最近点:轴线 L = base + t·(0,1,0),射线 R = ro + s·rd。
+    // 对 |L−R|² 求偏导得 t(1−b²) = w0.y − e·b,其中 b = rd.y,
+    // w0 = ro − base,e = w0·rd
+    const b = rd.y;
+    const denom = 1 - b * b;
+    if (Math.abs(denom) < 1e-6)
+        return null;
+    const w0 = new Vector3().subVectors(ro, base);
+    const e = w0.dot(rd);
+    const t = (w0.y - e * b) / denom;
+    return new Vector3(base.x, base.y + t, base.z);
+}
+/**
+ * 水平面约束(Blender 拖动中按 Shift+Z):锁定基准点的 y,指针在
+ * 水平面内自由移动 x/z。视线与水平面平行时无解,返回 null。
+ */
+export function computeHorizontalConstraintPoint(raycaster, camera, rect, clientX, clientY, 
+/** 约束基准点:y 被锁定为它 */
+base) {
+    const ndc = new Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+    raycaster.setFromCamera(ndc, camera);
+    const plane = new Plane(new Vector3(0, 1, 0), -base.y);
+    return raycaster.ray.intersectPlane(plane, new Vector3());
+}

package/dist/dropPoint.test.d.ts

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

package/dist/dropPoint.test.d.ts.map

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