@dreamerbird/camera-studio 0.0.0-stage → 0.1.0

package/dist/gestureProps.test.js

@@ -0,0 +1,182 @@
+// packages/camera-studio/src/gestureProps.test.ts
+/**
+ * 手势属性纯件:条目判定/侧过滤/选项构建/显示文本/注册形态。
+ * QBX 手势条目左右手骨都带(未动侧 rest),侧过滤是叠加语义的关键。
+ */
+import { buildGestureOptions, filterGestureBonesBySide, gestureDisplayText, gestureEntryNameSide, gesturePropConfigShape, isHandPoseEntry, resolveGestureBones, } from './gestureProps';
+import { poseInterpolate } from './poseMode/poseInterpolate';
+import { serializeLibPose } from './poseMode/poseValue';
+import { __primeLibPoseCache } from './poseMode/poseLibResolve';
+const rot = [0, 0, 0, 1];
+const L_FINGERS = Object.fromEntries(['Thumb1', 'Index1', 'Middle1', 'Ring1', 'Pinky1'].map((s) => [
+    `mixamorigLeftHand${s}`,
+    { rotation: rot },
+]));
+const R_FINGERS = Object.fromEntries(['Thumb1', 'Index1', 'Middle1', 'Ring1', 'Pinky1'].map((s) => [
+    `mixamorigRightHand${s}`,
+    { rotation: rot },
+]));
+const BOTH_HANDS = { ...L_FINGERS, ...R_FINGERS };
+test('isHandPoseEntry:全手指骨才算;含躯干/手腕/空 bones 都不算', () => {
+    expect(isHandPoseEntry({ bones: BOTH_HANDS })).toBe(true);
+    expect(isHandPoseEntry({ bones: L_FINGERS })).toBe(true);
+    // 全身姿势(带 Hips)不是手势
+    expect(isHandPoseEntry({ bones: { ...BOTH_HANDS, mixamorigHips: { rotation: rot } } })).toBe(false);
+    // 手腕(裸 …Hand)不算手指骨
+    expect(isHandPoseEntry({
+        bones: { ...L_FINGERS, mixamorigLeftHand: { rotation: rot } },
+    })).toBe(false);
+    expect(isHandPoseEntry({ bones: {} })).toBe(false);
+    expect(isHandPoseEntry({})).toBe(false);
+});
+test('filterGestureBonesBySide:只留本侧手指骨', () => {
+    const left = filterGestureBonesBySide(BOTH_HANDS, 'left');
+    expect(Object.keys(left)).toHaveLength(5);
+    expect(Object.keys(left).every((k) => k.includes('LeftHand'))).toBe(true);
+    const right = filterGestureBonesBySide(BOTH_HANDS, 'right');
+    expect(Object.keys(right).every((k) => k.includes('RightHand'))).toBe(true);
+});
+test('gestureEntryNameSide:名字后缀判侧,无后缀 = 双手', () => {
+    expect(gestureEntryNameSide('其他 · Fist · 左手')).toBe('left');
+    expect(gestureEntryNameSide('手势 · Thumbs Up · 右手')).toBe('right');
+    expect(gestureEntryNameSide('手势 · Peace Flipped')).toBe(null);
+});
+test('resolveGestureBones:lib 引用解析后裁到本侧;空值/无本侧骨回 null', () => {
+    __primeLibPoseCache('gest_both', BOTH_HANDS);
+    __primeLibPoseCache('gest_right_only', R_FINGERS);
+    const left = resolveGestureBones(serializeLibPose('gest_both'), 'left');
+    expect(Object.keys(left ?? {})).toHaveLength(5);
+    expect(Object.keys(left ?? {})[0]).toContain('LeftHand');
+    expect(resolveGestureBones('', 'left')).toBe(null);
+    // 条目只有右手骨:左手势应用回 null(跳过,不碰左手)
+    expect(resolveGestureBones(serializeLibPose('gest_right_only'), 'left')).toBe(null);
+});
+const t = ((k) => k);
+const LIB = [
+    { id: 'g_fist_l', name: '其他 · Fist · 左手', rig: 'rig-a', bones: BOTH_HANDS },
+    { id: 'g_fist_r', name: '其他 · Fist · 右手', rig: 'rig-a', bones: BOTH_HANDS },
+    {
+        id: 'g_peace',
+        name: '手势 · Peace Flipped',
+        rig: 'rig-a',
+        bones: BOTH_HANDS,
+    },
+    {
+        id: 'p_body',
+        name: '超级英雄 · Fist F',
+        rig: 'rig-a',
+        bones: { ...BOTH_HANDS, mixamorigHips: { rotation: rot } },
+    },
+    { id: 'g_alien', name: '手势 · OK · 左手', rig: 'rig-b', bones: BOTH_HANDS },
+];
+test('buildGestureOptions:左手框 = 无手势 + 左手条目 + 双手条目;身体姿势不进框', () => {
+    const { options, current } = buildGestureOptions({
+        gestureJson: '',
+        libEntries: LIB,
+        side: 'left',
+        selectedRig: 'rig-a',
+        t,
+    });
+    expect(current).toBe('none');
+    expect(options.map((o) => o.key)).toEqual([
+        'none',
+        'lib:g_fist_l',
+        'lib:g_peace',
+        'lib:g_alien',
+    ]);
+    // 异族置灰
+    expect(options.find((o) => o.key === 'lib:g_alien')?.disabled).toBe(true);
+    expect(options.find((o) => o.key === 'lib:g_fist_l')?.disabled).toBeUndefined();
+});
+test('buildGestureOptions:右手框对称(左手条目不进);缺省 rig 不过滤全可点', () => {
+    const { options } = buildGestureOptions({
+        gestureJson: '',
+        libEntries: LIB,
+        side: 'right',
+        t,
+    });
+    expect(options.map((o) => o.key)).toEqual([
+        'none',
+        'lib:g_fist_r',
+        'lib:g_peace',
+    ]);
+    expect(options.every((o) => !o.disabled)).toBe(true);
+});
+test('buildGestureOptions:当前值引用的条目不在本侧列表(含已删)追加置灰缺失项', () => {
+    const { options, current } = buildGestureOptions({
+        gestureJson: serializeLibPose('g_fist_r'), // 右手术条目出现在左手框:缺失项
+        libEntries: LIB,
+        side: 'left',
+        t,
+    });
+    expect(current).toBe('lib:g_fist_r');
+    const missing = options[options.length - 1];
+    expect(missing.key).toBe('lib:g_fist_r');
+    expect(missing.disabled).toBe(true);
+});
+test('buildGestureOptions:thumbUrlOf 注入时透传缩略图;无图条目不带 thumbUrl 字段', () => {
+    const withThumb = LIB.map((e) => e.id === 'g_fist_l' ? { ...e, thumbnailId: 'blob-x' } : e);
+    const { options } = buildGestureOptions({
+        gestureJson: '',
+        libEntries: withThumb,
+        side: 'left',
+        thumbUrlOf: (e) => (e.thumbnailId ? `url:${e.thumbnailId}` : undefined),
+        t,
+    });
+    expect(options.find((o) => o.key === 'lib:g_fist_l')?.thumbUrl).toBe('url:blob-x');
+    const peace = options.find((o) => o.key === 'lib:g_peace');
+    expect(peace && 'thumbUrl' in peace).toBe(false);
+    // 不注入 thumbUrlOf:一律无图
+    const plain = buildGestureOptions({
+        gestureJson: '',
+        libEntries: withThumb,
+        side: 'left',
+        t,
+    });
+    expect(plain.options.every((o) => !('thumbUrl' in o))).toBe(true);
+});
+test('buildGestureOptions:「无手势」项挂 noneThumbUrl(放松手预览);不传则无图', () => {
+    const withThumb = buildGestureOptions({
+        gestureJson: '',
+        libEntries: LIB,
+        side: 'left',
+        noneThumbUrl: 'url:base-l',
+        t,
+    });
+    expect(withThumb.options[0]).toMatchObject({
+        key: 'none',
+        thumbUrl: 'url:base-l',
+    });
+    const plain = buildGestureOptions({
+        gestureJson: '',
+        libEntries: LIB,
+        side: 'left',
+        t,
+    });
+    expect(plain.options[0].thumbUrl).toBeUndefined();
+});
+test('gestureDisplayText:空值无手势;库引用显名;缺失带标记;custom 报自定义', () => {
+    expect(gestureDisplayText({ gestureJson: '', libEntries: LIB, t })).toBe('pg.gesture.none');
+    expect(gestureDisplayText({
+        gestureJson: serializeLibPose('g_fist_l'),
+        libEntries: LIB,
+        t,
+    })).toBe('其他 · Fist · 左手');
+    expect(gestureDisplayText({
+        gestureJson: serializeLibPose('gone'),
+        libEntries: LIB,
+        t,
+    })).toBe('gonepg.pose.libMissing');
+    expect(gestureDisplayText({
+        gestureJson: '{"kind":"custom","bones":{}}',
+        libEntries: LIB,
+        t,
+    })).toBe('pg.pose.statusCustom');
+});
+test('gesturePropConfigShape:editor 按侧分 key + 复用姿势插值器', () => {
+    expect(gesturePropConfigShape('left').opts.editor).toBe('gestureL');
+    expect(gesturePropConfigShape('right').opts.editor).toBe('gestureR');
+    expect(gesturePropConfigShape('left').opts.interpolate).toBe(poseInterpolate);
+    expect(gesturePropConfigShape('right').defaultValue).toBe('');
+    expect(typeof gesturePropConfigShape('left').opts.label).toBe('function');
+});

package/dist/gesturePropsEditor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 手势属性编辑器(2026-10-05,左手势/右手势):姿势属性编辑器的「纯选择」版——
+ * 值区域显示 无手势/手势名,点开左侧停靠选择框(PosePickerFrame 复用,
+ * 标题按侧),选项 = 无手势 + 本侧(或双手)手势条目,异族置灰。
+ * 没有自定义入口:不写 custom 快照、不挂姿势模式;打帧/撤销走 theatre
+ * 原生通道(permanentlySetValue 有轨道写帧、无轨道写静态,与姿势一致)。
+ *
+ * 数据自给自足(同 PosePropEditor 的跨树约束):t 来自 studio 树 i18n
+ * provider;库条目来自模块级库单例订阅;骨架族经 obj → placement →
+ * 模型库条目异步解析,解析不出则不过滤全可点。
+ *
+ * 注册:App 里按侧注册两个 editor key(gestureL/gestureR),组件本体带
+ * side prop,两个薄封装导出给注册表(签名对齐 ISimplePropEditorReactProps)。
+ */
+import React from 'react';
+import type { PropTypeConfig_AllSimples } from '@dreamerbird/core/types/public';
+import type { ISimplePropEditorReactProps } from '@dreamerbird/studio/propEditors/simpleEditors/ISimplePropEditorReactProps';
+import type { GestureSide } from './gestureProps';
+type EditorProps = ISimplePropEditorReactProps<PropTypeConfig_AllSimples>;
+export declare function GesturePropEditor({ editingTools, value, obj, side, }: EditorProps & {
+    side: GestureSide;
+}): React.ReactElement;
+/** 注册表薄封装:editor key gestureL/gestureR 各绑一侧 */
+export declare const GesturePropEditorLeft: React.FC<EditorProps>;
+export declare const GesturePropEditorRight: React.FC<EditorProps>;
+export {};
+//# sourceMappingURL=gesturePropsEditor.d.ts.map

package/dist/gesturePropsEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gesturePropsEditor.d.ts","sourceRoot":"","sources":["../src/gesturePropsEditor.tsx"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAwC,MAAM,OAAO,CAAA;AAI5D,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAC,2BAA2B,EAAC,MAAM,2EAA2E,CAAA;AAO1H,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAA;AAM/C,KAAK,WAAW,GAAG,2BAA2B,CAAC,yBAAyB,CAAC,CAAA;AAEzE,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,EACZ,KAAK,EACL,GAAG,EACH,IAAI,GACL,EAAE,WAAW,GAAG;IAAC,IAAI,EAAE,WAAW,CAAA;CAAC,GAAG,KAAK,CAAC,YAAY,CAwHxD;AAED,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAEvD,CAAA;AACD,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,CAExD,CAAA"}

package/dist/gesturePropsEditor.js

@@ -0,0 +1,121 @@
+// packages/camera-studio/src/gesturePropsEditor.tsx
+/**
+ * 手势属性编辑器(2026-10-05,左手势/右手势):姿势属性编辑器的「纯选择」版——
+ * 值区域显示 无手势/手势名,点开左侧停靠选择框(PosePickerFrame 复用,
+ * 标题按侧),选项 = 无手势 + 本侧(或双手)手势条目,异族置灰。
+ * 没有自定义入口:不写 custom 快照、不挂姿势模式;打帧/撤销走 theatre
+ * 原生通道(permanentlySetValue 有轨道写帧、无轨道写静态,与姿势一致)。
+ *
+ * 数据自给自足(同 PosePropEditor 的跨树约束):t 来自 studio 树 i18n
+ * provider;库条目来自模块级库单例订阅;骨架族经 obj → placement →
+ * 模型库条目异步解析,解析不出则不过滤全可点。
+ *
+ * 注册:App 里按侧注册两个 editor key(gestureL/gestureR),组件本体带
+ * side prop,两个薄封装导出给注册表(签名对齐 ISimplePropEditorReactProps)。
+ */
+import React, { useContext, useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useI18n } from '@dreamerbird/studio/i18n';
+import { PopoverAutoCloseLock } from '@dreamerbird/studio/uiComponents/Popover/usePopover';
+import { getLibrary, useLibraryEntries } from './assetLibrary/library';
+import { useModelThumbUrl } from './assetLibrary/useModelThumbUrl';
+import { getPlacementEntryForObject } from './PlacementManager';
+import { buildGestureOptions, gestureDisplayText } from './gestureProps';
+import { poseEntryName } from './poseNames';
+import { serializeLibPose } from './poseMode/poseValue';
+import { PosePickerFrame } from './poseMode/PosePickerFrame';
+import { getUiConfig } from './uiConfig';
+export function GesturePropEditor({ editingTools, value, obj, side, }) {
+    const { t } = useI18n();
+    const poseEntries = useLibraryEntries('pose');
+    // 内置手势由 StaticCatalogSource 目录提供(2026-10-10 去播种),无需触发
+    const [pickerOpen, setPickerOpen] = useState(false);
+    const [valueHovered, setValueHovered] = useState(false);
+    // 停靠框打开期间持父弹框锁(时间轴帧弹框嵌套场景,同 PosePropEditor)
+    const parentPopoverLock = useContext(PopoverAutoCloseLock);
+    useEffect(() => {
+        if (!pickerOpen)
+            return;
+        const held = parentPopoverLock.takeFocus();
+        return () => held.releaseFocus();
+    }, [pickerOpen, parentPopoverLock]);
+    // 编辑器所属对象的骨架族(obj → placement → 模型库条目),过滤异族手势
+    const [rig, setRig] = useState(undefined);
+    useEffect(() => {
+        let cancelled = false;
+        const entry = obj
+            ? getPlacementEntryForObject(obj)
+            : undefined;
+        if (!entry?.libraryEntryId) {
+            setRig(undefined);
+            return;
+        }
+        void getLibrary()
+            .getEntry(entry.libraryEntryId)
+            .then((libEntry) => {
+            if (!cancelled)
+                setRig(libEntry?.rig);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [obj]);
+    const gestureJson = value ?? '';
+    // 缩略图懒加载(QBX 预览图):命中缓存直接给 URL,未命中触发加载后重渲
+    const { getThumbUrl } = useModelThumbUrl();
+    // 「无手势」项配图(2026-10-05):用本侧「基础·放松」条目的预览图——
+    // 放松手就是无叠加手势的样子。种子条目 id 稳定(seed-pose-<key>)
+    const baseEntry = poseEntries.find((e) => e.id ===
+        `seed-pose-qbx-hands-01-base-base-${side === 'left' ? 'l' : 'r'}`);
+    const noneThumbUrl = baseEntry ? getThumbUrl(baseEntry) : undefined;
+    // 显示名:种子条目查 i18n 词典(纯姿势名),用户自存姿势回退条目名原文
+    const nameOf = (e) => poseEntryName(e, t);
+    const { options, current } = buildGestureOptions({
+        gestureJson,
+        libEntries: poseEntries,
+        side,
+        selectedRig: rig,
+        thumbUrlOf: getThumbUrl,
+        noneThumbUrl,
+        nameOf,
+        t,
+    });
+    const display = gestureDisplayText({
+        gestureJson,
+        libEntries: poseEntries,
+        nameOf,
+        t,
+    });
+    // 选后不关框(2026-10-05 与用户对齐,同姿势框):可连续换手势看效果
+    const handlePick = (key) => {
+        editingTools.permanentlySetValue(key === 'none' ? '' : serializeLibPose(key.slice(4)));
+    };
+    return (React.createElement(React.Fragment, null,
+        React.createElement("div", { "data-testid": side === 'left' ? 'GesturePropValueL' : 'GesturePropValueR', title: display, onClick: () => setPickerOpen(true), onMouseEnter: () => setValueHovered(true), onMouseLeave: () => setValueHovered(false), style: {
+                width: '100%',
+                boxSizing: 'border-box',
+                height: 'calc(100% - 4px)',
+                display: 'flex',
+                alignItems: 'center',
+                padding: '1px 6px',
+                borderRadius: 2,
+                border: `1px solid ${valueHovered ? '#00000059' : 'transparent'}`,
+                background: valueHovered ? '#10101042' : 'transparent',
+                color: 'rgba(255, 255, 255, 0.9)',
+                fontSize: 11,
+                cursor: 'pointer',
+                whiteSpace: 'nowrap',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                userSelect: 'none',
+            } }, display),
+        pickerOpen &&
+            createPortal(React.createElement(PosePickerFrame, { options: options, current: current, title: t(side === 'left'
+                    ? 'pg.gesture.selectorTitleL'
+                    : 'pg.gesture.selectorTitleR'), onPick: handlePick, onClose: () => setPickerOpen(false) }), 
+            // 宿主可配 portal 容器(ui.portalContainer),缺省挂 document.body
+            getUiConfig().portalContainer ?? document.body)));
+}
+/** 注册表薄封装:editor key gestureL/gestureR 各绑一侧 */
+export const GesturePropEditorLeft = (props) => (React.createElement(GesturePropEditor, { ...props, side: "left" }));
+export const GesturePropEditorRight = (props) => (React.createElement(GesturePropEditor, { ...props, side: "right" }));

package/dist/getDeep.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 本地等价实现,取代 \@dreamerbird/utils/getDeep——该包 private 未发布,
+ * 不能成为本包的运行时依赖(peerDeps 完整性核对时收编,2026-10-12)。
+ * 按路径数组逐段取值;路径为空返回原值,任一段不存在返回 undefined,
+ * 与原实现(lodash-es/get 包装)在调用点的语义一致。
+ */
+export default function getDeep(v: unknown, path: readonly (string | number)[]): unknown;
+//# sourceMappingURL=getDeep.d.ts.map

package/dist/getDeep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getDeep.d.ts","sourceRoot":"","sources":["../src/getDeep.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,CAAC,EAAE,OAAO,EACV,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GACjC,OAAO,CAOT"}

package/dist/getDeep.js

@@ -0,0 +1,15 @@
+/**
+ * 本地等价实现,取代 \@dreamerbird/utils/getDeep——该包 private 未发布,
+ * 不能成为本包的运行时依赖(peerDeps 完整性核对时收编,2026-10-12)。
+ * 按路径数组逐段取值;路径为空返回原值,任一段不存在返回 undefined,
+ * 与原实现(lodash-es/get 包装)在调用点的语义一致。
+ */
+export default function getDeep(v, path) {
+    let cur = v;
+    for (const key of path) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}

package/dist/gizmoRegistry.test.d.ts

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

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

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

package/dist/gizmoRegistry.test.js

@@ -0,0 +1,40 @@
+/**
+ * 选中 gizmo 登记表的包围盒高亮标记:没有自带选中高亮的对象(放置的
+ * 模型)默认画橙色包围盒线框;相机/路径/锚点有自己的变色高亮,登记时
+ * 传 boxHighlight:false 不重复画。
+ */
+import { Object3D } from 'three';
+import { getGizmoTargetEntry, onGizmoRegistryChange, registerGizmoTarget, } from './PlacementManager';
+const fakeObj = () => ({});
+test('默认登记:包围盒高亮开', () => {
+    const obj = fakeObj();
+    const node = new Object3D();
+    const unregister = registerGizmoTarget(obj, node);
+    const entry = getGizmoTargetEntry(obj);
+    expect(entry?.node).toBe(node);
+    expect(entry?.boxHighlight).toBe(true);
+    unregister();
+});
+test('boxHighlight:false 登记:不画包围盒(相机/路径/锚点有自己的高亮)', () => {
+    const obj = fakeObj();
+    const unregister = registerGizmoTarget(obj, new Object3D(), {
+        boxHighlight: false,
+    });
+    expect(getGizmoTargetEntry(obj)?.boxHighlight).toBe(false);
+    unregister();
+});
+test('注销后查不到登记项', () => {
+    const obj = fakeObj();
+    const unregister = registerGizmoTarget(obj, new Object3D());
+    unregister();
+    expect(getGizmoTargetEntry(obj)).toBeUndefined();
+});
+test('登记与注销都广播给监听者(选中态要立刻重算)', () => {
+    const listener = jest.fn();
+    const off = onGizmoRegistryChange(listener);
+    const unregister = registerGizmoTarget(fakeObj(), new Object3D());
+    expect(listener).toHaveBeenCalledTimes(1);
+    unregister();
+    expect(listener).toHaveBeenCalledTimes(2);
+    off();
+});

package/dist/hostFlows.d.ts

@@ -0,0 +1,55 @@
+import type { PlacingState } from './PlacementManager';
+import type { ModelEntry } from './assetLibrary/types';
+import type { PathPreset } from './pathPresets';
+export type { Vec3 } from './agent/types';
+import type { Vec3 } from './agent/types';
+export type CameraFlows = {
+    /** 点选放置:宿主选中模型后调用,进入画布放置模式 */
+    startPlacingModel(entry: ModelEntry): Promise<void>;
+    /** 拖拽放置:在指定三维落点直接放置,无幽灵阶段 */
+    placeModelAt(entry: ModelEntry, point: Vec3): void;
+    /** 路径预设生成路径;不传 at = 场景中心(现状语义) */
+    addPresetPath(preset: PathPreset, at?: Vec3): void;
+    addCamera(): void;
+    addAnchor(): void;
+    cancelPlacing(): void;
+    /** 宿主外部模型入库(走既有导入管线),返回正式库条目 */
+    importModel(file: File): Promise<ModelEntry>;
+    /** 指针客户端坐标 → 场景三维落点;场景未就绪返回 null */
+    dropPointFromClient(clientX: number, clientY: number): Vec3 | null;
+};
+export declare function setHostFlowsHandle(f: CameraFlows | null): void;
+export declare function getHostFlowsHandle(): CameraFlows | null;
+export declare function setPlacingSnapshot(p: PlacingState | null): void;
+export declare function getPlacingSnapshot(): PlacingState | null;
+export declare function subscribePlacing(l: () => void): () => void;
+export declare function usePlacing(): PlacingState | null;
+import type { Camera } from 'three';
+export type DropPointContext = {
+    gl: {
+        domElement: HTMLElement;
+    };
+    camera: Camera;
+};
+export declare function setDropPointContext(ctx: DropPointContext | null): void;
+export declare function dropPointFromClient(clientX: number, clientY: number): Vec3 | null;
+/**
+ * App 用既有函数注入组装 CameraFlows;纯转发,可单测。
+ * 注入改为 getDeps 惰性取数:句柄生命周期内 App 侧的依赖函数可能换代
+ * (如 activeCamera 切换经 pathPresetHeight 级联重建 placePresetPath),
+ * 各方法在调用时才执行 getDeps() 取最新 deps 转发,不缓存——保证
+ * createHostFlows([]) 一次组装的句柄永远调最新实现,无陈旧闭包。
+ */
+export type HostFlowDeps = {
+    startPlacingFromLibrary: (entry: ModelEntry) => Promise<void>;
+    placeLibraryEntryAt: (entry: ModelEntry, point: Vec3) => void;
+    placePresetPath: (preset: PathPreset, at?: Vec3) => void;
+    addCamera: () => void;
+    addAnchor: () => void;
+    cancelPlacing: () => void;
+    importModel: (file: File) => Promise<ModelEntry>;
+};
+export declare function createHostFlows(getDeps: () => HostFlowDeps): CameraFlows;
+/** 顶栏按钮分流:宿主接了选择框就只通知宿主,否则开内置框体(现状)。 */
+export declare function pickerToggleHandler(hostCb: (() => void) | undefined, toggleFrame: (kind: 'model' | 'path') => void, kind: 'model' | 'path'): () => void;
+//# sourceMappingURL=hostFlows.d.ts.map

package/dist/hostFlows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostFlows.d.ts","sourceRoot":"","sources":["../src/hostFlows.ts"],"names":[],"mappings":"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"}

package/dist/hostFlows.js

@@ -0,0 +1,77 @@
+/**
+ * 宿主能力句柄的基础设施(规格 §1–§3)。
+ * 句柄注册表:onFlows 一次性交付,宿主自存;模块级单例,场景卸载清空。
+ * placing store:useSyncExternalStore 的外部 store,宿主组件(含 portal
+ * 到 body 的 shadcn Dialog)用 usePlacing() 读放置状态,不依赖 context。
+ * dropPointFromClient 与 createHostFlows 在同文件后续任务补齐。
+ */
+import { useSyncExternalStore } from 'react';
+// ── 句柄注册表 ──────────────────────────────────────────────
+let currentHandle = null;
+export function setHostFlowsHandle(f) {
+    currentHandle = f;
+}
+export function getHostFlowsHandle() {
+    return currentHandle;
+}
+// ── placing 外部 store ──────────────────────────────────────
+let placingSnapshot = null;
+const placingListeners = new Set();
+export function setPlacingSnapshot(p) {
+    if (p === placingSnapshot)
+        return;
+    placingSnapshot = p;
+    placingListeners.forEach((l) => l());
+}
+export function getPlacingSnapshot() {
+    return placingSnapshot;
+}
+export function subscribePlacing(l) {
+    placingListeners.add(l);
+    return () => {
+        placingListeners.delete(l);
+    };
+}
+export function usePlacing() {
+    return useSyncExternalStore(subscribePlacing, getPlacingSnapshot);
+}
+// ── 落点换算 ────────────────────────────────────────────────
+// 场景内(HostFlowsDropPointCapture,App 的 Canvas 子树)把 gl/camera
+// 捕获进来;宿主 dragover/drop 事件里的 clientX/clientY 直接喂给
+// dropPointFromClient,规则与放置幽灵一致(表面优先、地面兜底)。
+import { Raycaster } from 'three';
+import { computeDropPoint } from './dropPoint';
+import { getPlacementSurfaces } from './PlacementManager';
+let dropCtx = null;
+export function setDropPointContext(ctx) {
+    dropCtx = ctx;
+}
+export function dropPointFromClient(clientX, clientY) {
+    if (!dropCtx)
+        return null;
+    const { gl, camera } = dropCtx;
+    const rect = gl.domElement.getBoundingClientRect();
+    const p = computeDropPoint(new Raycaster(), camera, getPlacementSurfaces(), rect, clientX, clientY);
+    return { x: p.x, y: p.y, z: p.z };
+}
+export function createHostFlows(getDeps) {
+    return {
+        startPlacingModel: (entry) => getDeps().startPlacingFromLibrary(entry),
+        placeModelAt: (entry, point) => getDeps().placeLibraryEntryAt(entry, point),
+        addPresetPath: (preset, at) => getDeps().placePresetPath(preset, at),
+        addCamera: () => getDeps().addCamera(),
+        addAnchor: () => getDeps().addAnchor(),
+        cancelPlacing: () => getDeps().cancelPlacing(),
+        importModel: (file) => getDeps().importModel(file),
+        dropPointFromClient,
+    };
+}
+/** 顶栏按钮分流:宿主接了选择框就只通知宿主,否则开内置框体(现状)。 */
+export function pickerToggleHandler(hostCb, toggleFrame, kind) {
+    return () => {
+        if (hostCb)
+            hostCb();
+        else
+            toggleFrame(kind);
+    };
+}

package/dist/hostFlows.test.d.ts

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

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

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