From 75bdfd2a708863e9b587cac1f3bf619e7218b7f7 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 10:40:29 +0800
Subject: [PATCH 01/11] docs(spec): asset-drag-into-viewport design
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Custom pointer drag (Tauri dragDropEnabled=true suppresses HTML5 ondrop)
→ ghost follows cursor → drop on canvas raycasts y=0 ground plane →
new node at hit x/z, keeping the library item's default y. Double-click
add-at-default preserved. Pure fns screenToNdc/dropPositionFor/
findLibraryItem (lib layer so runtime adapter can reuse). Undoable via
AddNodeCommand.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...6-06-08-asset-drag-into-viewport-design.md | 278 ++++++++++++++++++
 1 file changed, 278 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-08-asset-drag-into-viewport-design.md

diff --git a/docs/superpowers/specs/2026-06-08-asset-drag-into-viewport-design.md b/docs/superpowers/specs/2026-06-08-asset-drag-into-viewport-design.md
new file mode 100644
index 0000000..dee8075
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-08-asset-drag-into-viewport-design.md
@@ -0,0 +1,278 @@
+# 资源拖拽入视口 + 落点 设计
+
+**状态**: 已批准（2026-06-08）
+**前置**: v0.2 资源库（#29）—— `LibraryPanel` 双击卡片 `executeCommand(new AddNodeCommand({ node: item.makeNode() }))`；`catalog.ts` 的 `BUILTIN_LIBRARY_ITEMS`（4 几何 + 4 灯光）+ `uploadLibraryItems(assets)`（从 user_upload 派生）+ `LibraryItem.makeNode()`（每次新 uuid，几何 `position:[0,0.5,0]`、灯光给固定空中位）。v0.4 sub-stage A 网格吸附（#33）+ B 节点对齐吸附（#34）已合并。
+**定位**: 从 v0.2 资源库拆出的 Backlog 项，用户定的顺序：排在 v0.4 sub-stage B（#34）之后、sub-stage C（Socket）之前。
+**架构依据**: 架构 §6 资源库交互 —— MVP 自定义。
+
+---
+
+## 1. 目标
+
+从资源库卡片**拖拽**到视口，以 raycast 命中 **y=0 地面平面**的点作为新节点的落点（覆盖 position 的 x/z、保留库项默认 y）。现有**双击**加节点（默认位置）保留不变。
+
+## 2. Success criteria
+
+1. 从库卡片 `pointerdown` 拖动（移动 > 5px 激活），半透明 ghost 跟随光标；在 canvas 内 `pointerup` → 在落点新增对应节点（落点 = 地面 y=0 交点的 x/z + 库项默认 y）。
+2. 全部库项（几何 / 灯光 / 上传 glb）可拖；**双击行为保留**（纯双击不移动 → 不触发拖拽 → 仍按默认位加节点）。
+3. canvas 外释放 → 取消（不加节点，ghost 消失）；raycast 未命中（相机朝天 / 平行地面）→ 回退库项默认 position（仍加节点，等同双击效果）。
+4. 拖入走 `AddNodeCommand` → 可撤销（与双击一致）。
+5. 纯函数 `screenToNdc` / `dropPositionFor` / `findLibraryItem` 单测绿。
+6. `pnpm lint && pnpm typecheck && pnpm test` 全绿 + `pnpm tauri dev` 视觉验证。
+
+## 3. 范围
+
+### In scope
+
+- 纯函数 `src/lib/drop-helpers.ts`：`screenToNdc` + `dropPositionFor`。
+- `src/services/library/catalog.ts`：`findLibraryItem(id, uploads)`。
+- `src/runtime/three/adapter.ts`：`raycastGroundPoint(x, y)`（屏幕坐标 → y=0 平面世界交点 | null）。
+- `src/state/ui-store.ts`：`assetDragItemId` + `startAssetDrag` / `endAssetDrag`。
+- `src/services/library/asset-drag.ts`：拖拽发起 controller（候选 → 5px 阈值激活 → 调 `startAssetDrag`）。
+- `src/ui/editor/AssetDragGhost.tsx`：拖拽中 ghost（fixed 跟随光标）。
+- `src/ui/editor/LibraryPanel.tsx`：`LibraryCard` 加 `onPointerDown`（双击不动）。
+- `src/ui/viewport/ThreeViewport.tsx`：`window pointerup` 落点接收（拖拽中 & canvas 内 → 加节点 + 收尾）。
+- library i18n 提示文案。
+
+### Out of scope（延后 / roadmap Backlog）
+
+1. **命中物体表面落点**（放物体顶上）—— 本期只 y=0 地面平面；堆叠交给落地后 gizmo + #34 节点对齐吸附。
+2. **落点网格吸附** —— 本期落点自由；吸附是落地后 gizmo 阶段的事（v0.4a 已覆盖）。
+3. **3D 落点预览**（半透明 mesh 实时跟落点）—— 本期只 DOM ghost；3D 预览 / 落点指示圈延后（Smart Guides 类优化）。
+4. **从 OS 拖文件进编辑器导入** —— 需 `dragDropEnabled`（本期用 pointer 拖拽不动该配置，保留未来该能力）。
+5. glb 落点的 bbox 底部对齐（避免半埋）—— 本期统一「覆盖 x/z、保留默认 y」，glb 可能半埋，落地后 gizmo 调。
+
+## 4. 关键约束（探索发现）
+
+`src-tauri/tauri.conf.json` 的 `app.windows[]` **未设** `dragDropEnabled` → Tauri 2 默认 `true`，会抑制 webview 内 HTML5 `ondrop` DOM 事件。故**不走 HTML5 DnD**，改**自定义 pointer 拖拽**（不动 tauri.conf、与现有 pointer 体系一致、ghost 顺手、保留未来 OS file-drop）。
+
+## 5. 数据模型 / 类型
+
+### 5.1 纯函数（`src/lib/drop-helpers.ts`）
+
+```ts
+/** 相对 canvas 的屏幕像素 → NDC（[-1,1]，y 向上）。 */
+export function screenToNdc(
+  px: number,
+  py: number,
+  w: number,
+  h: number,
+): [number, number] {
+  return [(px / w) * 2 - 1, -((py / h) * 2 - 1)];
+}
+
+/** 落点世界坐标 → 新节点 position：覆盖 x/z，保留库项默认 y
+ *  （box 坐落点的地面不半埋；灯光保留空中默认高度）。 */
+export function dropPositionFor(
+  defaultPos: readonly [number, number, number],
+  hit: readonly [number, number, number],
+): [number, number, number] {
+  return [hit[0], defaultPos[1], hit[2]];
+}
+```
+
+### 5.2 catalog（`src/services/library/catalog.ts`）
+
+```ts
+/** 按 id 在 builtin + upload 派生项里查 LibraryItem（drop 时取回 makeNode）。 */
+export function findLibraryItem(
+  id: string,
+  uploads: AssetReference[],
+): LibraryItem | undefined {
+  return [...BUILTIN_LIBRARY_ITEMS, ...uploadLibraryItems(uploads)].find(
+    (i) => i.id === id,
+  );
+}
+```
+
+### 5.3 ui-store（`src/state/ui-store.ts`）
+
+```ts
+assetDragItemId: string | null;        // 拖拽激活中的库项 id（null = 无拖拽）
+startAssetDrag: (id: string) => void;  // 设 assetDragItemId
+endAssetDrag: () => void;              // 置 null
+```
+
+## 6. 架构 / 组件（职责 + 数据流）
+
+### 6.1 拖拽发起 controller（`src/services/library/asset-drag.ts`）
+
+module-level，把"按下卡片 → 移动超阈值才算拖拽"与双击区分开（与 canvas click-vs-drag 5px 守卫一致，避免纯双击闪 ghost）：
+
+```ts
+let candidate: { id: string; x: number; y: number } | null = null;
+let onMove: ((e: PointerEvent) => void) | null = null;
+let onUp: (() => void) | null = null;
+
+/** LibraryCard pointerdown 调用：记候选 + 监听，移动 > 5px 激活拖拽。 */
+export function beginAssetDrag(id: string, clientX: number, clientY: number) {
+  candidate = { id, x: clientX, y: clientY };
+  onMove = (e) => {
+    if (!candidate) return;
+    if (Math.hypot(e.clientX - candidate.x, e.clientY - candidate.y) > 5) {
+      useUIStore.getState().startAssetDrag(candidate.id);
+      teardown(); // 激活后撤候选监听；ghost + ThreeViewport 接管
+    }
+  };
+  onUp = () => teardown(); // 未超阈值就松手（纯双击）→ 不激活，dblclick 正常
+  window.addEventListener("pointermove", onMove);
+  window.addEventListener("pointerup", onUp);
+}
+
+function teardown() {
+  if (onMove) window.removeEventListener("pointermove", onMove);
+  if (onUp) window.removeEventListener("pointerup", onUp);
+  candidate = null;
+  onMove = null;
+  onUp = null;
+}
+```
+
+激活后 controller 不再持有监听；收尾（`endAssetDrag`）统一由 ThreeViewport 的 `pointerup` 负责（§6.4）——两处状态独立（controller 的 module 候选 vs store 的 `assetDragItemId`），无竞争。
+
+### 6.2 LibraryCard（`src/ui/editor/LibraryPanel.tsx`）
+
+```tsx
+<button
+  type="button"
+  draggable={false}            // 防原生 DnD 干扰 pointer 拖拽
+  onPointerDown={(e) => beginAssetDrag(item.id, e.clientX, e.clientY)}
+  onDoubleClick={() => onActivate(item)}  // 保留
+  ...
+>
+```
+
+### 6.3 AssetDragGhost（`src/ui/editor/AssetDragGhost.tsx`，挂 EditorView 根）
+
+```tsx
+export function AssetDragGhost() {
+  const id = useUIStore((s) => s.assetDragItemId);
+  const uploads = useAssetStore((s) => s.assets);
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+  useEffect(() => {
+    if (!id) return;
+    const onMove = (e: PointerEvent) => setPos({ x: e.clientX, y: e.clientY });
+    window.addEventListener("pointermove", onMove);
+    return () => window.removeEventListener("pointermove", onMove);
+  }, [id]);
+  if (!id || !pos) return null;
+  const item = findLibraryItem(id, uploads);
+  if (!item) return null;
+  return (
+    <div
+      className="pointer-events-none fixed z-50 -translate-x-1/2 -translate-y-1/2 rounded-lg border border-primary/60 bg-card/80 px-3 py-2 text-2xl opacity-80 shadow-lg"
+      style={{ left: pos.x, top: pos.y }}
+      aria-hidden
+    >
+      {item.icon}
+    </div>
+  );
+}
+```
+
+### 6.4 ThreeViewport 落点接收（`src/ui/viewport/ThreeViewport.tsx`，mount effect 内）
+
+```ts
+const onWindowPointerUp = (e: PointerEvent) => {
+  const id = useUIStore.getState().assetDragItemId;
+  if (!id) return; // 非拖拽释放
+  const rect = canvas.getBoundingClientRect();
+  const x = e.clientX - rect.left;
+  const y = e.clientY - rect.top;
+  const inside = x >= 0 && y >= 0 && x <= rect.width && y <= rect.height;
+  if (inside) {
+    const item = findLibraryItem(id, useAssetStore.getState().assets);
+    if (item) {
+      const node = item.makeNode();
+      const hit = adapter.raycastGroundPoint(x, y);
+      if (hit) node.transform.position = dropPositionFor(node.transform.position, hit);
+      executeCommand(new AddNodeCommand({ node }));
+    }
+  }
+  useUIStore.getState().endAssetDrag(); // canvas 内外都收尾
+};
+window.addEventListener("pointerup", onWindowPointerUp);
+// cleanup: window.removeEventListener("pointerup", onWindowPointerUp);
+```
+
+### 6.5 adapter（`src/runtime/three/adapter.ts`）
+
+```ts
+/** 屏幕坐标（相对 canvas）→ y=0 地面平面世界交点；未命中（相机朝天/平行）→ null。
+ *  复用 pickAt 的 viewport 尺寸 + updateMatrixWorld 模式。 */
+raycastGroundPoint(x: number, y: number): [number, number, number] | null {
+  const [ndcX, ndcY] = screenToNdc(x, y, this.viewportWidth, this.viewportHeight);
+  this.camera.updateMatrixWorld(true);
+  this.raycaster.setFromCamera(new THREE.Vector2(ndcX, ndcY), this.camera);
+  const target = new THREE.Vector3();
+  const hit = this.raycaster.ray.intersectPlane(GROUND_PLANE, target); // Plane(normal=(0,1,0), const=0)
+  return hit ? [target.x, target.y, target.z] : null;
+}
+```
+
+（`GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0)` 模块常量；`screenToNdc` 自 `@/lib/drop-helpers`〔runtime→lib 合法方向〕；`viewportWidth/Height` + `raycaster` 字段名以 adapter 现状为准〔plan 阶段读 `pickAt` 确认〕。）
+
+### 6.6 数据流
+
+```
+LibraryCard pointerdown
+  → beginAssetDrag(id, x, y)            [asset-drag.ts: 候选 + 监听]
+  → (移动 > 5px) startAssetDrag(id)     [ui-store: assetDragItemId 置位]
+  → AssetDragGhost 跟随光标             [读 store + window pointermove]
+  → canvas 内 pointerup                 [ThreeViewport window listener]
+      → screenToNdc → raycastGroundPoint(x,y)
+      → dropPositionFor(makeNode 默认 pos, hit)   (hit=null → 保留默认 pos)
+      → executeCommand(AddNodeCommand{node})       [可撤销]
+      → endAssetDrag()
+  → canvas 外 pointerup → 仅 endAssetDrag（不加节点）
+纯双击（不移动）→ asset-drag teardown，store 始终 null → ThreeViewport 跳过 → onDoubleClick 正常加默认位节点
+```
+
+## 7. 边界 / 错误处理
+
+- canvas 外释放 → `inside=false` → 不加节点，`endAssetDrag` 清状态、ghost 消失。
+- `raycastGroundPoint` 未命中 → `null` → 不改 position（保留 `makeNode` 默认）→ 仍 `AddNodeCommand`（友好回退，等同双击）。
+- 灯光 / glb 同规则：落点覆盖 x/z、保留默认 y（灯保留空中高度；glb 可能半埋，落地后 gizmo+#34 调）。
+- 拖拽中切到非编辑器视图（极端边界）：ThreeViewport 卸载，window pointerup 随 effect cleanup 移除。MVP **不特殊处理**——靠下次 pointerup / 视图切换重置兜底；若 ghost 残留成问题，再在 EditorView 卸载时调 `endAssetDrag`。
+- `draggable={false}` 防浏览器原生图片/文本 DnD 抢 pointer。
+- upload 项 id 在 `uploads` 变化时：drop 时按当前 `useAssetStore.getState().assets` 重新 `findLibraryItem`，查不到则不加（安全跳过）。
+
+## 8. 视觉反馈
+
+- 拖拽中：DOM ghost（库项 emoji + 卡片样式，半透明，`pointer-events:none`，fixed 跟光标）。
+- 落点指示（地面圈/十字）/ 3D 预览 **延后**（Out of scope 3）。
+- library 提示文案：`hint` 改「双击或拖拽到视口添加」。
+
+## 9. 测试策略
+
+- `drop-helpers.test.ts`：`screenToNdc`（中心→[0,0]、四角、非方形 w≠h）；`dropPositionFor`（覆盖 x/z、保留默认 y；负坐标）。
+- `catalog.test.ts` 增：`findLibraryItem` 命中 builtin（如 `geo-box`）、命中 upload 派生项、未知 id → undefined。
+- `raycastGroundPoint`（three raycast）/ `beginAssetDrag`（window 事件 + 阈值）/ ghost / ThreeViewport 落点（pointer + WebGL）→ `pnpm tauri dev` 视觉验证（vitest 无 WebGL/pointer，抓不到）。
+
+## 10. 文件清单
+
+**新增**：
+
+- `src/lib/drop-helpers.ts` + `drop-helpers.test.ts`
+- `src/services/library/asset-drag.ts`
+- `src/ui/editor/AssetDragGhost.tsx`
+
+**修改**：
+
+- `src/services/library/catalog.ts`（`findLibraryItem` + `catalog.test.ts`）
+- `src/runtime/three/adapter.ts`（`raycastGroundPoint` + `GROUND_PLANE`）
+- `src/state/ui-store.ts`（`assetDragItemId` + actions）
+- `src/ui/editor/LibraryPanel.tsx`（`LibraryCard` onPointerDown + draggable=false）
+- `src/ui/editor/EditorView.tsx`（挂 `<AssetDragGhost />`）
+- `src/ui/viewport/ThreeViewport.tsx`（window pointerup 落点）
+- library i18n（en + zh `hint` 文案）
+
+## 11. 风险 / 延后
+
+- pointer 拖拽与 gizmo / orbit 的 pointer 事件共存：拖拽发起在库卡片（视口外），激活后只读 store + window pointerup；不与 canvas 内 gizmo/orbit 的 pointerdown 冲突（落点只在 `assetDragItemId` 非空时处理）。
+- 高频 `pointermove`：ghost 用组件局部 state（不进 store，避免无关 re-render）。
+- 物体表面落点 / 落点吸附 / 3D 预览 / OS file-drop / glb 底部对齐 → roadmap Backlog。
+
+## 12. 验收
+
+满足 §2：库卡片拖入视口、ghost 跟随、落点 = 地面 x/z + 默认 y、双击保留、canvas 外取消、未命中回退、可撤销 + 纯函数单测绿 + 视觉验证。下一步：v0.4 sub-stage C（Socket 系统）。

From 17abc57939999fb54cb923de83f602c4e04c7d98 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:03:35 +0800
Subject: [PATCH 02/11] feat(drop): pure screenToNdc + dropPositionFor helpers
 (tested)

---
 src/lib/drop-helpers.test.ts | 30 ++++++++++++++++++++++++++++++
 src/lib/drop-helpers.ts      | 29 +++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 src/lib/drop-helpers.test.ts
 create mode 100644 src/lib/drop-helpers.ts

diff --git a/src/lib/drop-helpers.test.ts b/src/lib/drop-helpers.test.ts
new file mode 100644
index 0000000..d61b7ec
--- /dev/null
+++ b/src/lib/drop-helpers.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import { dropPositionFor, screenToNdc } from "./drop-helpers";
+
+describe("screenToNdc", () => {
+  it("maps the canvas center to the NDC origin", () => {
+    expect(screenToNdc(50, 50, 100, 100)).toEqual([0, 0]);
+  });
+  it("maps the top-left corner to (-1, 1)", () => {
+    expect(screenToNdc(0, 0, 100, 100)).toEqual([-1, 1]);
+  });
+  it("maps the bottom-right corner to (1, -1)", () => {
+    expect(screenToNdc(100, 100, 100, 100)).toEqual([1, -1]);
+  });
+  it("maps each axis independently for a non-square viewport", () => {
+    expect(screenToNdc(100, 75, 200, 100)).toEqual([0, -0.5]);
+  });
+});
+
+describe("dropPositionFor", () => {
+  it("takes x/z from the hit and keeps the default y", () => {
+    expect(dropPositionFor([0, 0.5, 0], [3, 0, -2])).toEqual([3, 0.5, -2]);
+  });
+  it("keeps a light's authored height", () => {
+    expect(dropPositionFor([0, 3, 0], [-1.5, 0, 4.2])).toEqual([-1.5, 3, 4.2]);
+  });
+  it("preserves negative hit coordinates", () => {
+    expect(dropPositionFor([0, 1, 0], [-5, 0, -7])).toEqual([-5, 1, -7]);
+  });
+});
diff --git a/src/lib/drop-helpers.ts b/src/lib/drop-helpers.ts
new file mode 100644
index 0000000..e14a11d
--- /dev/null
+++ b/src/lib/drop-helpers.ts
@@ -0,0 +1,29 @@
+/**
+ * Pure geometry helpers for asset drag-and-drop placement. No Three.js / DOM
+ * deps so they unit-test headlessly; the ThreeAdapter and ThreeViewport
+ * consume them at drop time.
+ */
+
+/** Canvas-relative screen pixels → normalized device coords ([-1, 1], y up). */
+export function screenToNdc(
+  px: number,
+  py: number,
+  w: number,
+  h: number,
+): [number, number] {
+  // y is `1 - …` rather than `-( … - 1)` so the canvas center maps to a clean
+  // +0 instead of -0 — vitest's toEqual uses Object.is, where -0 !== 0.
+  return [(px / w) * 2 - 1, 1 - (py / h) * 2];
+}
+
+/**
+ * New node position from a ground-plane hit: take the hit's x/z, keep the
+ * library item's default y. So a box lifted to y=0.5 still rests on the floor
+ * (not half-buried) and a light keeps its authored height.
+ */
+export function dropPositionFor(
+  defaultPos: readonly [number, number, number],
+  hit: readonly [number, number, number],
+): [number, number, number] {
+  return [hit[0], defaultPos[1], hit[2]];
+}

From ac25054432dc2799be1cc19754563021e503f732 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:04:19 +0800
Subject: [PATCH 03/11] feat(library): findLibraryItem lookup across builtins +
 uploads

---
 src/services/library/catalog.test.ts | 39 +++++++++++++++++++++++++++-
 src/services/library/catalog.ts      | 14 ++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/src/services/library/catalog.test.ts b/src/services/library/catalog.test.ts
index 39d09b8..602e26f 100644
--- a/src/services/library/catalog.test.ts
+++ b/src/services/library/catalog.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 
-import { BUILTIN_LIBRARY_ITEMS, uploadLibraryItems } from "./catalog";
+import type { AssetReference } from "@/core/scene/types";
+
+import { BUILTIN_LIBRARY_ITEMS, findLibraryItem, uploadLibraryItems } from "./catalog";
 
 describe("library catalog", () => {
   it("has the 4 geometry primitives + 4 light presets as builtins", () => {
@@ -59,3 +61,38 @@ describe("library catalog", () => {
     });
   });
 });
+
+describe("findLibraryItem", () => {
+  it("finds a builtin item by id", () => {
+    const item = findLibraryItem("geo-box", []);
+    expect(item?.id).toBe("geo-box");
+    expect(item?.makeNode().data).toMatchObject({
+      type: "mesh",
+      geometry: { kind: "box" },
+    });
+  });
+
+  it("finds an upload-derived item by its upload-* id", () => {
+    const uploads: AssetReference[] = [
+      {
+        id: "a1",
+        content_hash: "h",
+        kind: "geometry",
+        relative_path: "assets/h.glb",
+        tags: [],
+        description: "",
+        source: { kind: "user_upload", original_filename: "chair.glb" },
+      },
+    ];
+    const item = findLibraryItem("upload-a1", uploads);
+    expect(item?.name).toBe("chair.glb");
+    expect(item?.makeNode().data).toMatchObject({
+      type: "prefab_instance",
+      asset_id: "a1",
+    });
+  });
+
+  it("returns undefined for an unknown id", () => {
+    expect(findLibraryItem("nope", [])).toBeUndefined();
+  });
+});
diff --git a/src/services/library/catalog.ts b/src/services/library/catalog.ts
index ae08802..bd93611 100644
--- a/src/services/library/catalog.ts
+++ b/src/services/library/catalog.ts
@@ -147,3 +147,17 @@ export function uploadLibraryItems(assets: AssetReference[]): LibraryItem[] {
   }
   return items;
 }
+
+/**
+ * Look up a library item by id across builtins + upload-derived items. Used by
+ * drag-drop to recover the item (and its makeNode) at drop time, after only the
+ * id was carried through the drag.
+ */
+export function findLibraryItem(
+  id: string,
+  uploads: AssetReference[],
+): LibraryItem | undefined {
+  return [...BUILTIN_LIBRARY_ITEMS, ...uploadLibraryItems(uploads)].find(
+    (item) => item.id === id,
+  );
+}

From e96978e1139a00e4ebd198cc94fa746a3b43e275 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:05:05 +0800
Subject: [PATCH 04/11] feat(ui-store): assetDragItemId + start/endAssetDrag

---
 src/services/ui/store.test.ts | 15 +++++++++++++++
 src/services/ui/store.ts      | 10 ++++++++++
 2 files changed, 25 insertions(+)

diff --git a/src/services/ui/store.test.ts b/src/services/ui/store.test.ts
index c7a61c2..45c1cc1 100644
--- a/src/services/ui/store.test.ts
+++ b/src/services/ui/store.test.ts
@@ -170,3 +170,18 @@ describe("useUIStore — libraryOpen (v0.2)", () => {
     expect(useUIStore.getState().libraryOpen).toBe(true);
   });
 });
+
+describe("useUIStore — asset drag (asset-drag-into-viewport)", () => {
+  beforeEach(() => useUIStore.setState({ assetDragItemId: null }));
+
+  it("defaults to null (no drag active)", () => {
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+  });
+
+  it("startAssetDrag sets the id and endAssetDrag clears it", () => {
+    useUIStore.getState().startAssetDrag("geo-box");
+    expect(useUIStore.getState().assetDragItemId).toBe("geo-box");
+    useUIStore.getState().endAssetDrag();
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+  });
+});
diff --git a/src/services/ui/store.ts b/src/services/ui/store.ts
index 014143a..e8070e5 100644
--- a/src/services/ui/store.ts
+++ b/src/services/ui/store.ts
@@ -57,6 +57,13 @@ interface UIState {
   pendingFocusNodeId: string | null | undefined;
   requestFocus: (nodeId: string | null) => void;
   consumeFocusRequest: () => void;
+  /** Library item id currently being drag-dropped into the viewport; null when
+   *  no asset drag is active. Set once the pointer passes the drag threshold
+   *  (services/library/asset-drag.ts), cleared on drop / cancel by the
+   *  viewport's window pointerup. */
+  assetDragItemId: string | null;
+  startAssetDrag: (id: string) => void;
+  endAssetDrag: () => void;
 }
 
 export const useUIStore = create<UIState>((set) => ({
@@ -95,4 +102,7 @@ export const useUIStore = create<UIState>((set) => ({
   pendingFocusNodeId: undefined,
   requestFocus: (pendingFocusNodeId) => set({ pendingFocusNodeId }),
   consumeFocusRequest: () => set({ pendingFocusNodeId: undefined }),
+  assetDragItemId: null,
+  startAssetDrag: (assetDragItemId) => set({ assetDragItemId }),
+  endAssetDrag: () => set({ assetDragItemId: null }),
 }));

From 4123f83d07c0ef40f3de192ed7a2616e1341e86c Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:12:03 +0800
Subject: [PATCH 05/11] =?UTF-8?q?feat(adapter):=20raycastGroundPoint=20?=
 =?UTF-8?q?=E2=80=94=20screen=20=E2=86=92=20y=3D0=20world=20hit=20(tested)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/runtime/three/adapter.test.ts | 24 ++++++++++++++++++++++
 src/runtime/three/adapter.ts      | 33 +++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/src/runtime/three/adapter.test.ts b/src/runtime/three/adapter.test.ts
index ead67b5..fc8ba17 100644
--- a/src/runtime/three/adapter.test.ts
+++ b/src/runtime/three/adapter.test.ts
@@ -853,3 +853,27 @@ describe("ThreeAdapter live behavior runtime", () => {
     expect(() => adapter.dispose()).not.toThrow();
   });
 });
+
+describe("ThreeAdapter.raycastGroundPoint", () => {
+  it("hits the ground plane near the origin for a centered ray", () => {
+    // Default camera sits at [4,3,4] looking at the origin, so the center ray
+    // (NDC 0,0) crosses y=0 exactly at the origin.
+    const adapter = new ThreeAdapter(target);
+    adapter.setViewportSize(100, 100);
+    const hit = adapter.raycastGroundPoint(50, 50);
+    expect(hit).not.toBeNull();
+    expect(hit![1]).toBeCloseTo(0, 5);
+    expect(Math.hypot(hit![0], hit![2])).toBeLessThan(1e-4);
+  });
+
+  it("returns null when the camera faces away from the ground", () => {
+    // Tilt up (above the horizon) but NOT straight up — a forward parallel to
+    // the up vector makes lookAt degenerate (NaN basis). [0,5,3] tilts up
+    // around x, so the center ray points above y=0 and never crosses it.
+    const adapter = new ThreeAdapter(target, {
+      defaultCamera: { position: [0, 1, 0], lookAt: [0, 5, 3] },
+    });
+    adapter.setViewportSize(100, 100);
+    expect(adapter.raycastGroundPoint(50, 50)).toBeNull();
+  });
+});
diff --git a/src/runtime/three/adapter.ts b/src/runtime/three/adapter.ts
index aa1ef71..971910b 100644
--- a/src/runtime/three/adapter.ts
+++ b/src/runtime/three/adapter.ts
@@ -15,6 +15,7 @@ import type {
   IRuntimeAdapter,
   SyncOp,
 } from "../adapter";
+import { screenToNdc } from "@/lib/drop-helpers";
 
 import { AssetCache } from "./asset-cache";
 import { createThreeBehaviorRegistry, ThreeBehaviorRegistry } from "./behaviors";
@@ -69,6 +70,10 @@ const EXPORTERS: Record<ExportTarget, Exporter> = {
   "standalone-esm": standaloneEsmEmitter,
 };
 
+/** Shared y=0 ground plane (normal +y) for drop raycasts. Module-level to
+ *  avoid per-pick allocation. */
+const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+
 /**
  * Three.js adapter — implements `IRuntimeAdapter` for the MVP renderer.
  *
@@ -128,6 +133,8 @@ export class ThreeAdapter implements IRuntimeAdapter {
   /** Reused per pick to avoid per-event allocations. */
   private readonly raycaster = new THREE.Raycaster();
   private readonly ndc = new THREE.Vector2();
+  /** Reused target for raycastGroundPoint's plane intersection. */
+  private readonly groundHit = new THREE.Vector3();
 
   constructor(
     target: RuntimeTarget = DEFAULT_TARGET,
@@ -295,6 +302,32 @@ export class ThreeAdapter implements IRuntimeAdapter {
     return null;
   }
 
+  /**
+   * Raycast the screen point `(screen_x, screen_y)` (viewport-pixel space)
+   * against the y=0 ground plane. Returns the world-space hit `[x, y, z]`, or
+   * null when the ray is parallel to / points away from the plane (camera
+   * facing the sky). Mirrors pickAt's NDC + matrix-refresh setup so a drop
+   * handled synchronously (before the next animation frame) still uses the
+   * current camera pose.
+   */
+  raycastGroundPoint(
+    screen_x: number,
+    screen_y: number,
+  ): [number, number, number] | null {
+    if (this.viewportWidth <= 0 || this.viewportHeight <= 0) return null;
+    this.camera.updateMatrixWorld(true);
+    const [ndcX, ndcY] = screenToNdc(
+      screen_x,
+      screen_y,
+      this.viewportWidth,
+      this.viewportHeight,
+    );
+    this.ndc.set(ndcX, ndcY);
+    this.raycaster.setFromCamera(this.ndc, this.camera);
+    const hit = this.raycaster.ray.intersectPlane(GROUND_PLANE, this.groundHit);
+    return hit ? [hit.x, hit.y, hit.z] : null;
+  }
+
   // ───── Export ───────────────────────────────────────────────────
 
   async exportProject(

From 952ca3253b2c9630a84e64d539ab644ccd5ac2b1 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:13:16 +0800
Subject: [PATCH 06/11] =?UTF-8?q?feat(library):=20asset-drag=20controller?=
 =?UTF-8?q?=20=E2=80=94=205px=20threshold=20activates=20drag?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/services/library/asset-drag.test.ts | 36 ++++++++++++++++++++++
 src/services/library/asset-drag.ts      | 40 +++++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 src/services/library/asset-drag.test.ts
 create mode 100644 src/services/library/asset-drag.ts

diff --git a/src/services/library/asset-drag.test.ts b/src/services/library/asset-drag.test.ts
new file mode 100644
index 0000000..cde2cf9
--- /dev/null
+++ b/src/services/library/asset-drag.test.ts
@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { useUIStore } from "@/services/ui/store";
+
+import { beginAssetDrag } from "./asset-drag";
+
+function move(clientX: number, clientY: number) {
+  window.dispatchEvent(new MouseEvent("pointermove", { clientX, clientY }));
+}
+function up() {
+  window.dispatchEvent(new MouseEvent("pointerup", {}));
+}
+
+describe("beginAssetDrag", () => {
+  beforeEach(() => useUIStore.setState({ assetDragItemId: null }));
+
+  it("does not activate the drag below the 5px threshold", () => {
+    beginAssetDrag("geo-box", 100, 100);
+    move(103, 101); // ~3.2px
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+    up(); // cleanup
+  });
+
+  it("activates the drag once the pointer passes 5px", () => {
+    beginAssetDrag("geo-box", 100, 100);
+    move(110, 100); // 10px
+    expect(useUIStore.getState().assetDragItemId).toBe("geo-box");
+  });
+
+  it("a release before the threshold tears down without activating", () => {
+    beginAssetDrag("geo-box", 100, 100);
+    up(); // plain click/double-click — no drag
+    move(200, 200); // listeners removed → no late activation
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+  });
+});
diff --git a/src/services/library/asset-drag.ts b/src/services/library/asset-drag.ts
new file mode 100644
index 0000000..b8f5c6a
--- /dev/null
+++ b/src/services/library/asset-drag.ts
@@ -0,0 +1,40 @@
+import { useUIStore } from "@/services/ui/store";
+
+/**
+ * Module-level drag-from-library controller. A library card calls
+ * beginAssetDrag on pointerdown; we record a candidate and watch the pointer.
+ * Only once it moves past DRAG_THRESHOLD_PX do we flip the UI store into a live
+ * asset drag — so a plain click / double-click never flashes a ghost. After
+ * activation this controller drops its own listeners; the drag is then owned by
+ * AssetDragGhost (visual) + ThreeViewport (drop), which clear it via
+ * endAssetDrag. Releasing before the threshold tears down quietly.
+ */
+const DRAG_THRESHOLD_PX = 5;
+
+let candidate: { id: string; x: number; y: number } | null = null;
+let onMove: ((e: PointerEvent) => void) | null = null;
+let onUp: (() => void) | null = null;
+
+export function beginAssetDrag(id: string, clientX: number, clientY: number): void {
+  teardown(); // drop any stale candidate before starting a new one
+  candidate = { id, x: clientX, y: clientY };
+  onMove = (e) => {
+    if (!candidate) return;
+    const moved = Math.hypot(e.clientX - candidate.x, e.clientY - candidate.y);
+    if (moved > DRAG_THRESHOLD_PX) {
+      useUIStore.getState().startAssetDrag(candidate.id);
+      teardown();
+    }
+  };
+  onUp = () => teardown();
+  window.addEventListener("pointermove", onMove);
+  window.addEventListener("pointerup", onUp);
+}
+
+function teardown(): void {
+  if (onMove) window.removeEventListener("pointermove", onMove);
+  if (onUp) window.removeEventListener("pointerup", onUp);
+  candidate = null;
+  onMove = null;
+  onUp = null;
+}

From 5f671ecf8e0b177e5b3c16bdb5d5c603e3cc6058 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:18:05 +0800
Subject: [PATCH 07/11] feat(library): AssetDragGhost cursor-following drag
 preview

---
 src/ui/library/AssetDragGhost.tsx | 49 +++++++++++++++++++++++++++++++
 src/ui/views/EditorView.tsx       |  2 ++
 2 files changed, 51 insertions(+)
 create mode 100644 src/ui/library/AssetDragGhost.tsx

diff --git a/src/ui/library/AssetDragGhost.tsx b/src/ui/library/AssetDragGhost.tsx
new file mode 100644
index 0000000..75ff5c8
--- /dev/null
+++ b/src/ui/library/AssetDragGhost.tsx
@@ -0,0 +1,49 @@
+import { useEffect, useState } from "react";
+
+import { findLibraryItem } from "@/services/library/catalog";
+import { useSceneStore } from "@/services/scene/store";
+import { useUIStore } from "@/services/ui/store";
+
+/**
+ * Cursor-following ghost shown while a library item is dragged into the
+ * viewport. Reads the active drag id from the UI store and tracks the live
+ * pointer in LOCAL state (not the store — pointermove is high-frequency and we
+ * don't want to re-render unrelated subscribers). Renders nothing until the
+ * pointer has moved at least once after activation, or if the id can't be
+ * resolved (e.g. an upload removed mid-drag).
+ */
+export function AssetDragGhost() {
+  const id = useUIStore((s) => s.assetDragItemId);
+  const uploads = useSceneStore((s) => s.project?.assets);
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+
+  useEffect(() => {
+    if (!id) return;
+    const onMove = (e: PointerEvent) => setPos({ x: e.clientX, y: e.clientY });
+    window.addEventListener("pointermove", onMove);
+    // Cleanup (not the effect body) clears the tracked position — runs on every
+    // id transition (drag end *and* switching targets mid-drag), so a new drag
+    // never flashes the ghost at a stale position from the previous one. Doing
+    // the reset here also satisfies react-hooks/set-state-in-effect, which
+    // flags synchronous setState in an effect body as a cascading-render risk.
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      setPos(null);
+    };
+  }, [id]);
+
+  if (!id || !pos) return null;
+  const item = findLibraryItem(id, uploads ?? []);
+  if (!item) return null;
+  const Icon = item.icon;
+
+  return (
+    <div
+      className="pointer-events-none fixed z-50 flex h-10 w-10 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-lg border border-primary/60 bg-card/80 opacity-80 shadow-lg backdrop-blur-sm"
+      style={{ left: pos.x, top: pos.y }}
+      aria-hidden="true"
+    >
+      <Icon className="h-6 w-6 text-foreground/90" />
+    </div>
+  );
+}
diff --git a/src/ui/views/EditorView.tsx b/src/ui/views/EditorView.tsx
index 993671c..fa930f5 100644
--- a/src/ui/views/EditorView.tsx
+++ b/src/ui/views/EditorView.tsx
@@ -15,6 +15,7 @@ import { AiCommandBar } from "@/ui/editor/AiCommandBar";
 import { BehaviorsPanel } from "@/ui/editor/BehaviorsPanel";
 import { MaterialSection } from "@/ui/editor/MaterialSection";
 import { ShortcutsHelpDialog } from "@/ui/help/ShortcutsHelpDialog";
+import { AssetDragGhost } from "@/ui/library/AssetDragGhost";
 import { LibraryPanel } from "@/ui/library/LibraryPanel";
 import { PlayButton } from "@/ui/viewport/PlayButton";
 import { ThreeViewport } from "@/ui/viewport/ThreeViewport";
@@ -175,6 +176,7 @@ export function EditorView() {
         </aside>
       </section>
       <ShortcutsHelpDialog />
+      <AssetDragGhost />
     </div>
   );
 }

From 38988e5f794e27b721a06fbcea56712ea702ca4a Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:22:34 +0800
Subject: [PATCH 08/11] feat(library): card pointerdown starts drag; hint
 mentions drag

---
 src/i18n/locales/en-US/editor.json   |  2 +-
 src/i18n/locales/zh-CN/editor.json   |  2 +-
 src/ui/library/LibraryPanel.test.tsx | 13 +++++++++++++
 src/ui/library/LibraryPanel.tsx      |  5 +++++
 4 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/i18n/locales/en-US/editor.json b/src/i18n/locales/en-US/editor.json
index 7f77be7..f733823 100644
--- a/src/i18n/locales/en-US/editor.json
+++ b/src/i18n/locales/en-US/editor.json
@@ -99,7 +99,7 @@
     },
     "search": "Search…",
     "upload": "Upload .glb",
-    "add_hint": "Double-click to add",
+    "add_hint": "Double-click or drag into the viewport to add",
     "empty_uploads": "No uploads yet — use Upload .glb to add models."
   },
   "ai_command": {
diff --git a/src/i18n/locales/zh-CN/editor.json b/src/i18n/locales/zh-CN/editor.json
index a9295a5..eba61a7 100644
--- a/src/i18n/locales/zh-CN/editor.json
+++ b/src/i18n/locales/zh-CN/editor.json
@@ -99,7 +99,7 @@
     },
     "search": "搜索…",
     "upload": "上传 .glb",
-    "add_hint": "双击添加",
+    "add_hint": "双击或拖入视口添加",
     "empty_uploads": "暂无上传——点击「上传 .glb」添加模型。"
   },
   "ai_command": {
diff --git a/src/ui/library/LibraryPanel.test.tsx b/src/ui/library/LibraryPanel.test.tsx
index c5ec2ec..23c33d8 100644
--- a/src/ui/library/LibraryPanel.test.tsx
+++ b/src/ui/library/LibraryPanel.test.tsx
@@ -3,11 +3,16 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import { createDefaultProject } from "@/core/scene/defaults";
 import { useCommandHistoryStore } from "@/services/command-history/store";
+import { beginAssetDrag } from "@/services/library/asset-drag";
 import { useSceneStore } from "@/services/scene/store";
 import { useUIStore } from "@/services/ui/store";
 
 import { LibraryPanel } from "./LibraryPanel";
 
+vi.mock("@/services/library/asset-drag", () => ({
+  beginAssetDrag: vi.fn(),
+}));
+
 function seed(libraryOpen = true) {
   const project = createDefaultProject({
     id: "p1",
@@ -35,6 +40,7 @@ describe("LibraryPanel", () => {
     useSceneStore.setState({ project: null });
     useCommandHistoryStore.getState().clear();
     seed();
+    vi.mocked(beginAssetDrag).mockClear();
   });
 
   it("lists geometry items in the geometry tab (default)", () => {
@@ -66,4 +72,11 @@ describe("LibraryPanel", () => {
     expect(screen.getByText("Asset Library")).toBeInTheDocument();
     expect(screen.queryByText("Sphere")).not.toBeInTheDocument();
   });
+
+  it("pointer-down on a card begins an asset drag with the item id", () => {
+    render(<LibraryPanel />);
+    fireEvent.pointerDown(screen.getByText("Sphere"), { clientX: 12, clientY: 34 });
+    expect(beginAssetDrag).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(beginAssetDrag).mock.calls[0]?.[0]).toBe("geo-sphere");
+  });
 });
diff --git a/src/ui/library/LibraryPanel.tsx b/src/ui/library/LibraryPanel.tsx
index 2637389..6a6dbc7 100644
--- a/src/ui/library/LibraryPanel.tsx
+++ b/src/ui/library/LibraryPanel.tsx
@@ -5,6 +5,7 @@ import { useTranslation } from "react-i18next";
 import { AddNodeCommand } from "@/core/command/commands/add-node";
 import { cn } from "@/lib/utils";
 import { executeCommand } from "@/services/command-history";
+import { beginAssetDrag } from "@/services/library/asset-drag";
 import {
   BUILTIN_LIBRARY_ITEMS,
   type LibraryItem,
@@ -131,6 +132,10 @@ export function LibraryPanel() {
                     <button
                       key={item.id}
                       type="button"
+                      draggable={false}
+                      onPointerDown={(e) =>
+                        beginAssetDrag(item.id, e.clientX, e.clientY)
+                      }
                       onDoubleClick={() => addItem(item)}
                       title={t("library.add_hint")}
                       className="flex flex-col items-center gap-1 rounded border border-border bg-card/50 p-2 hover:border-primary hover:bg-muted"

From 3c759e078f76bdd4491634017104da0eeb24160e Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:26:19 +0800
Subject: [PATCH 09/11] feat(viewport): drop library item at ground raycast hit
 (undoable)

---
 src/ui/viewport/ThreeViewport.tsx | 35 +++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/ui/viewport/ThreeViewport.tsx b/src/ui/viewport/ThreeViewport.tsx
index 0179059..6fb6cbe 100644
--- a/src/ui/viewport/ThreeViewport.tsx
+++ b/src/ui/viewport/ThreeViewport.tsx
@@ -7,10 +7,12 @@ import { OutlinePass } from "three/addons/postprocessing/OutlinePass.js";
 import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
 import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
 
+import { AddNodeCommand } from "@/core/command/commands/add-node";
 import { SetNodeTransformCommand } from "@/core/command/commands/set-node-transform";
 import { snapTranslation } from "@/core/snap/grid";
 import { SNAP_PIXELS, snapToNodes, type SnapPoint } from "@/core/snap/nodes";
 import { isEffectivelyLocked } from "@/core/scene/policy";
+import { dropPositionFor } from "@/lib/drop-helpers";
 import { ThreeAdapter } from "@/runtime/three/adapter";
 import { describeTemplate } from "@/runtime/three/asset-cache";
 import type {
@@ -21,6 +23,7 @@ import type {
 } from "@/core/scene/types";
 import { useAssetPreviewStore } from "@/services/assets/preview-store";
 import { executeCommand } from "@/services/command-history";
+import { findLibraryItem } from "@/services/library/catalog";
 import { useProjectStore } from "@/services/project/store";
 import { useSceneStore } from "@/services/scene/store";
 import { useUIStore } from "@/services/ui/store";
@@ -298,6 +301,37 @@ export function ThreeViewport() {
     canvas.addEventListener("pointerdown", onPointerDown);
     canvas.addEventListener("click", onClick);
 
+    // Asset drag-drop: a library-card drag activates assetDragItemId (see
+    // services/library/asset-drag.ts). On release inside the canvas, raycast
+    // the y=0 ground plane and add the item there (falling back to the item's
+    // default position when the ray misses — camera facing the sky). Released
+    // outside the canvas or on a miss-with-no-item we still clear the drag.
+    // Bound on window (not canvas) so a release a few px past the canvas edge
+    // is still caught.
+    const onAssetDrop = (event: PointerEvent) => {
+      const id = useUIStore.getState().assetDragItemId;
+      if (!id) return; // not an asset drag
+      const rect = canvas.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
+      const inside = x >= 0 && y >= 0 && x <= rect.width && y <= rect.height;
+      if (inside) {
+        const uploads = useSceneStore.getState().project?.assets ?? [];
+        const item = findLibraryItem(id, uploads);
+        if (item) {
+          const node = item.makeNode();
+          const hit = adapter.raycastGroundPoint(x, y);
+          if (hit) {
+            node.transform.position = dropPositionFor(node.transform.position, hit);
+          }
+          executeCommand(new AddNodeCommand({ node }));
+          setSelectedNodeId(node.id);
+        }
+      }
+      useUIStore.getState().endAssetDrag(); // clear whether dropped in/out
+    };
+    window.addEventListener("pointerup", onAssetDrop);
+
     // ── Play / Pause side effects ─────────────────────────────────
     // transformSnapshots captures every Object3D's transform at the moment
     // Play is pressed so Pause can restore them — otherwise the cube would
@@ -387,6 +421,7 @@ export function ThreeViewport() {
       unsubscribeUI();
       canvas.removeEventListener("click", onClick);
       canvas.removeEventListener("pointerdown", onPointerDown);
+      window.removeEventListener("pointerup", onAssetDrop);
       window.removeEventListener("pointermove", onSnapPointer, true);
       window.removeEventListener("pointerdown", onSnapPointer, true);
       ro.disconnect();

From 5ecc0f653738dd071bb7d4129b72f5b387787822 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 16:59:46 +0800
Subject: [PATCH 10/11] docs(plan): asset-drag-into-viewport implementation
 plan

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...026-06-08-asset-drag-into-viewport-plan.md | 899 ++++++++++++++++++
 1 file changed, 899 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-08-asset-drag-into-viewport-plan.md

diff --git a/docs/superpowers/plans/2026-06-08-asset-drag-into-viewport-plan.md b/docs/superpowers/plans/2026-06-08-asset-drag-into-viewport-plan.md
new file mode 100644
index 0000000..5b32888
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-08-asset-drag-into-viewport-plan.md
@@ -0,0 +1,899 @@
+# 资源拖拽入视口 + 落点 实现计划
+
+> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
+
+**目标：** 从资源库卡片拖拽到 3D 视口，以 y=0 地面平面的 raycast 命中点作为新节点落点（覆盖 x/z、保留库项默认 y）；双击加节点行为不变；走 `AddNodeCommand` 可撤销。
+
+**架构：** 自定义 pointer 拖拽（不用 HTML5 DnD —— Tauri 2 默认 `dragDropEnabled=true` 抑制 webview 内 `ondrop`）。三段状态独立、无竞争：(1) module 级 controller `asset-drag.ts` 记录候选并在移动 > 5px 时把 UI store 翻成 active drag；(2) `AssetDragGhost` 读 store + 本地 pointermove 渲染跟随光标的 DOM ghost；(3) `ThreeViewport` 的 window `pointerup` 在 canvas 内落点 raycast 地面、加节点、收尾。纯几何 (`screenToNdc`/`dropPositionFor`)、catalog 查找 (`findLibraryItem`)、adapter 地面 raycast (`raycastGroundPoint`) 全部 headless 单测。
+
+**技术栈：** React 19 + zustand + Three.js（headless adapter 单测，无 WebGL）+ vitest/jsdom + react-i18next。
+
+---
+
+## 关键约束与 spec 偏差（实施前必读）
+
+实施前已通读真实代码。spec（`docs/superpowers/specs/2026-06-08-asset-drag-into-viewport-design.md`）多处用「架构命名」而非真实路径/符号，**以下以本计划为准**：
+
+1. **路径映射**（spec → 实际）：
+   - `src/state/ui-store.ts` → **`src/services/ui/store.ts`**（导出 `useUIStore`）
+   - `src/ui/editor/LibraryPanel.tsx` → **`src/ui/library/LibraryPanel.tsx`**
+   - `src/ui/editor/EditorView.tsx` → **`src/ui/views/EditorView.tsx`**
+   - `src/ui/editor/AssetDragGhost.tsx` → **`src/ui/library/AssetDragGhost.tsx`**（与 LibraryPanel 同目录，内聚于资源库 UI；偏离 spec 的 editor/ 目录，刻意为之）
+   - `src/runtime/three/adapter.ts`、`src/services/library/catalog.ts`、`src/services/library/asset-drag.ts`、`src/lib/drop-helpers.ts` 与 spec 一致 ✓
+2. **`item.icon` 是 `LucideIcon` 组件，不是 emoji**。spec §6.3 ghost 写 `{item.icon}`（当字符串渲染）是 bug。正确：`const Icon = item.icon; <Icon … />`（同 LibraryPanel `node-builders` 渲染卡片图标的写法）。
+3. **没有 `useAssetStore`**。spec §6.3/§6.4 读 `useAssetStore((s)=>s.assets)` 不存在。资源列表在 scene store：**`useSceneStore.getState().project?.assets ?? []`**（LibraryPanel 也是这么取的）。
+4. **`raycastGroundPoint` 可 headless 单测**，不止视觉验证。`adapter.test.ts` 已证明 `new ThreeAdapter()` 无 WebGL 即可构造相机/场景；地面 raycast 只用 camera + raycaster + `Plane.intersectPlane`，本计划补 2 个单测（spec §9 把它划到「视觉 only」偏保守）。
+5. **`beginAssetDrag` 可 headless 单测**：jsdom 环境（`vite.config.ts` `environment:"jsdom"`），用 `window.dispatchEvent(new MouseEvent("pointermove",{clientX,clientY}))` 触发 window 监听（`PointerEvent extends MouseEvent`，`e.clientX` 可读）。
+6. **落点后选中新节点**：双击路径 `addItem` 会 `setSelectedNodeId(node.id)`；drop 路径同样选中以保持一致（spec §6.4 漏了）。
+7. 真实符号确认：adapter 私有字段 `viewportWidth`/`viewportHeight`/`raycaster`/`ndc` 都在；`camera` 公有可读；`pickAt` 的 NDC 写法 = `(x/w)*2-1, -((y/h)*2-1)`，`raycastGroundPoint` 复刻它（含 `camera.updateMatrixWorld(true)`）。runtime→`@/lib` import 合法（`asset-cache.ts` 已 `import {isTauri} from "@/lib/runtime"`，无 eslint 边界规则）。
+
+---
+
+## 文件结构
+
+**新增**
+
+| 文件                                      | 职责                                                                         |
+| ----------------------------------------- | ---------------------------------------------------------------------------- |
+| `src/lib/drop-helpers.ts`                 | 纯函数 `screenToNdc` + `dropPositionFor`（无 DOM/Three 依赖）                |
+| `src/lib/drop-helpers.test.ts`            | 上两者单测                                                                   |
+| `src/services/library/asset-drag.ts`      | module 级拖拽发起 controller `beginAssetDrag`（5px 阈值 → `startAssetDrag`） |
+| `src/services/library/asset-drag.test.ts` | controller 阈值/激活/取消单测                                                |
+| `src/ui/library/AssetDragGhost.tsx`       | 拖拽中跟随光标的 DOM ghost（视觉验证，无单测）                               |
+
+**修改**
+
+| 文件                                   | 改动                                                                                         |
+| -------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `src/services/library/catalog.ts`      | 加 `findLibraryItem(id, uploads)`                                                            |
+| `src/services/library/catalog.test.ts` | `findLibraryItem` 单测（builtin / upload / 未知）                                            |
+| `src/runtime/three/adapter.ts`         | 加 `GROUND_PLANE` 常量 + `groundHit` 字段 + `raycastGroundPoint` 方法 + import `screenToNdc` |
+| `src/runtime/three/adapter.test.ts`    | `raycastGroundPoint` 命中 / 朝天回 null 单测                                                 |
+| `src/services/ui/store.ts`             | 加 `assetDragItemId` + `startAssetDrag` / `endAssetDrag`                                     |
+| `src/services/ui/store.test.ts`        | asset drag 状态 round-trip 单测                                                              |
+| `src/ui/library/LibraryPanel.tsx`      | 卡片 `onPointerDown={beginAssetDrag}` + `draggable={false}`                                  |
+| `src/ui/library/LibraryPanel.test.tsx` | pointerdown 触发 beginAssetDrag（mock）单测                                                  |
+| `src/ui/views/EditorView.tsx`          | 挂 `<AssetDragGhost />`                                                                      |
+| `src/ui/viewport/ThreeViewport.tsx`    | mount effect 内 window `pointerup` 落点处理 + cleanup                                        |
+| `src/i18n/locales/en-US/editor.json`   | `library.add_hint` 文案加「drag」                                                            |
+| `src/i18n/locales/zh-CN/editor.json`   | `library.add_hint` 文案加「拖入视口」                                                        |
+
+**执行前提**：当前已在分支 `feat/asset-drag-into-viewport`（spec commit `75bdfd2` 已在）。无需新建 worktree/branch。任务 1→8 有依赖顺序（见各任务），任务 9 收口。
+
+---
+
+### 任务 1：纯函数 drop-helpers（screenToNdc + dropPositionFor）
+
+无依赖。最先做，adapter（任务 4）与 ThreeViewport（任务 8）都引用。
+
+**文件：**
+
+- 创建：`src/lib/drop-helpers.ts`
+- 测试：`src/lib/drop-helpers.test.ts`
+
+- [ ] **步骤 1：编写失败的测试**
+
+创建 `src/lib/drop-helpers.test.ts`：
+
+```ts
+import { describe, expect, it } from "vitest";
+
+import { dropPositionFor, screenToNdc } from "./drop-helpers";
+
+describe("screenToNdc", () => {
+  it("maps the canvas center to the NDC origin", () => {
+    expect(screenToNdc(50, 50, 100, 100)).toEqual([0, 0]);
+  });
+  it("maps the top-left corner to (-1, 1)", () => {
+    expect(screenToNdc(0, 0, 100, 100)).toEqual([-1, 1]);
+  });
+  it("maps the bottom-right corner to (1, -1)", () => {
+    expect(screenToNdc(100, 100, 100, 100)).toEqual([1, -1]);
+  });
+  it("maps each axis independently for a non-square viewport", () => {
+    expect(screenToNdc(100, 75, 200, 100)).toEqual([0, -0.5]);
+  });
+});
+
+describe("dropPositionFor", () => {
+  it("takes x/z from the hit and keeps the default y", () => {
+    expect(dropPositionFor([0, 0.5, 0], [3, 0, -2])).toEqual([3, 0.5, -2]);
+  });
+  it("keeps a light's authored height", () => {
+    expect(dropPositionFor([0, 3, 0], [-1.5, 0, 4.2])).toEqual([-1.5, 3, 4.2]);
+  });
+  it("preserves negative hit coordinates", () => {
+    expect(dropPositionFor([0, 1, 0], [-5, 0, -7])).toEqual([-5, 1, -7]);
+  });
+});
+```
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pnpm vitest run src/lib/drop-helpers.test.ts`
+预期：FAIL —— 报 `Failed to resolve import "./drop-helpers"` / `screenToNdc is not a function`。
+
+- [ ] **步骤 3：编写最少实现代码**
+
+创建 `src/lib/drop-helpers.ts`：
+
+```ts
+/**
+ * Pure geometry helpers for asset drag-and-drop placement. No Three.js / DOM
+ * deps so they unit-test headlessly; the ThreeAdapter and ThreeViewport
+ * consume them at drop time.
+ */
+
+/** Canvas-relative screen pixels → normalized device coords ([-1, 1], y up). */
+export function screenToNdc(
+  px: number,
+  py: number,
+  w: number,
+  h: number,
+): [number, number] {
+  // y is `1 - …` rather than `-( … - 1)` so the canvas center maps to a clean
+  // +0 instead of -0 — vitest's toEqual uses Object.is, where -0 !== 0.
+  return [(px / w) * 2 - 1, 1 - (py / h) * 2];
+}
+
+/**
+ * New node position from a ground-plane hit: take the hit's x/z, keep the
+ * library item's default y. So a box lifted to y=0.5 still rests on the floor
+ * (not half-buried) and a light keeps its authored height.
+ */
+export function dropPositionFor(
+  defaultPos: readonly [number, number, number],
+  hit: readonly [number, number, number],
+): [number, number, number] {
+  return [hit[0], defaultPos[1], hit[2]];
+}
+```
+
+- [ ] **步骤 4：运行测试验证通过**
+
+运行：`pnpm vitest run src/lib/drop-helpers.test.ts`
+预期：PASS（7 个用例全绿）。
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add src/lib/drop-helpers.ts src/lib/drop-helpers.test.ts
+git commit -m "feat(drop): pure screenToNdc + dropPositionFor helpers (tested)"
+```
+
+---
+
+### 任务 2：catalog.findLibraryItem
+
+无依赖（用现有 `BUILTIN_LIBRARY_ITEMS` + `uploadLibraryItems`）。drop 时按 id 取回 `LibraryItem.makeNode`。
+
+**文件：**
+
+- 修改：`src/services/library/catalog.ts`（文件末尾追加导出函数）
+- 测试：`src/services/library/catalog.test.ts`（追加 describe + 补 import）
+
+- [ ] **步骤 1：编写失败的测试**
+
+在 `src/services/library/catalog.test.ts`：把第 3 行的 import 改为带上 `findLibraryItem`，并在文件顶部 import 区加 `AssetReference` 类型：
+
+```ts
+import { BUILTIN_LIBRARY_ITEMS, findLibraryItem, uploadLibraryItems } from "./catalog";
+import type { AssetReference } from "@/core/scene/types";
+```
+
+在 `describe("library catalog", () => { … })` 之后追加：
+
+```ts
+describe("findLibraryItem", () => {
+  it("finds a builtin item by id", () => {
+    const item = findLibraryItem("geo-box", []);
+    expect(item?.id).toBe("geo-box");
+    expect(item?.makeNode().data).toMatchObject({
+      type: "mesh",
+      geometry: { kind: "box" },
+    });
+  });
+
+  it("finds an upload-derived item by its upload-* id", () => {
+    const uploads: AssetReference[] = [
+      {
+        id: "a1",
+        content_hash: "h",
+        kind: "geometry",
+        relative_path: "assets/h.glb",
+        tags: [],
+        description: "",
+        source: { kind: "user_upload", original_filename: "chair.glb" },
+      },
+    ];
+    const item = findLibraryItem("upload-a1", uploads);
+    expect(item?.name).toBe("chair.glb");
+    expect(item?.makeNode().data).toMatchObject({
+      type: "prefab_instance",
+      asset_id: "a1",
+    });
+  });
+
+  it("returns undefined for an unknown id", () => {
+    expect(findLibraryItem("nope", [])).toBeUndefined();
+  });
+});
+```
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pnpm vitest run src/services/library/catalog.test.ts`
+预期：FAIL —— `findLibraryItem is not exported` / `is not a function`。
+
+- [ ] **步骤 3：编写最少实现代码**
+
+在 `src/services/library/catalog.ts` 文件末尾（`uploadLibraryItems` 之后）追加：
+
+```ts
+/**
+ * Look up a library item by id across builtins + upload-derived items. Used by
+ * drag-drop to recover the item (and its makeNode) at drop time, after only the
+ * id was carried through the drag.
+ */
+export function findLibraryItem(
+  id: string,
+  uploads: AssetReference[],
+): LibraryItem | undefined {
+  return [...BUILTIN_LIBRARY_ITEMS, ...uploadLibraryItems(uploads)].find(
+    (item) => item.id === id,
+  );
+}
+```
+
+（`AssetReference` 已在 catalog.ts 第 14 行 import，无需新增。）
+
+- [ ] **步骤 4：运行测试验证通过**
+
+运行：`pnpm vitest run src/services/library/catalog.test.ts`
+预期：PASS（原有 + 新增 3 个用例全绿）。
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add src/services/library/catalog.ts src/services/library/catalog.test.ts
+git commit -m "feat(library): findLibraryItem lookup across builtins + uploads"
+```
+
+---
+
+### 任务 3：UI store —— assetDragItemId + start/endAssetDrag
+
+无依赖。controller（任务 5）、ghost（任务 6）、drop（任务 8）都读写它。
+
+**文件：**
+
+- 修改：`src/services/ui/store.ts`（接口 + 实现各加 3 项）
+- 测试：`src/services/ui/store.test.ts`（追加 describe）
+
+- [ ] **步骤 1：编写失败的测试**
+
+在 `src/services/ui/store.test.ts` 末尾追加：
+
+```ts
+describe("useUIStore — asset drag (asset-drag-into-viewport)", () => {
+  beforeEach(() => useUIStore.setState({ assetDragItemId: null }));
+
+  it("defaults to null (no drag active)", () => {
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+  });
+
+  it("startAssetDrag sets the id and endAssetDrag clears it", () => {
+    useUIStore.getState().startAssetDrag("geo-box");
+    expect(useUIStore.getState().assetDragItemId).toBe("geo-box");
+    useUIStore.getState().endAssetDrag();
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+  });
+});
+```
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pnpm vitest run src/services/ui/store.test.ts`
+预期：FAIL —— `startAssetDrag is not a function`（且 TS 报缺字段）。
+
+- [ ] **步骤 3：编写最少实现代码**
+
+在 `src/services/ui/store.ts` 的 `interface UIState` 内（`consumeFocusRequest` 之后、`}` 之前）加：
+
+```ts
+  /** Library item id currently being drag-dropped into the viewport; null when
+   *  no asset drag is active. Set once the pointer passes the drag threshold
+   *  (services/library/asset-drag.ts), cleared on drop / cancel by the
+   *  viewport's window pointerup. */
+  assetDragItemId: string | null;
+  startAssetDrag: (id: string) => void;
+  endAssetDrag: () => void;
+```
+
+在 `create<UIState>((set) => ({ … }))` 实现里（`consumeFocusRequest: …` 之后）加：
+
+```ts
+  assetDragItemId: null,
+  startAssetDrag: (assetDragItemId) => set({ assetDragItemId }),
+  endAssetDrag: () => set({ assetDragItemId: null }),
+```
+
+- [ ] **步骤 4：运行测试验证通过**
+
+运行：`pnpm vitest run src/services/ui/store.test.ts && pnpm typecheck`
+预期：PASS + typecheck 0 error。
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add src/services/ui/store.ts src/services/ui/store.test.ts
+git commit -m "feat(ui-store): assetDragItemId + start/endAssetDrag"
+```
+
+---
+
+### 任务 4：adapter.raycastGroundPoint + GROUND_PLANE
+
+依赖任务 1（`screenToNdc`）。headless 单测。
+
+**文件：**
+
+- 修改：`src/runtime/three/adapter.ts`
+- 测试：`src/runtime/three/adapter.test.ts`（追加 describe）
+
+- [ ] **步骤 1：编写失败的测试**
+
+在 `src/runtime/three/adapter.test.ts` 末尾追加（`target` 变量该文件已有）：
+
+```ts
+describe("ThreeAdapter.raycastGroundPoint", () => {
+  it("hits the ground plane near the origin for a centered ray", () => {
+    // Default camera sits at [4,3,4] looking at the origin, so the center ray
+    // (NDC 0,0) crosses y=0 exactly at the origin.
+    const adapter = new ThreeAdapter(target);
+    adapter.setViewportSize(100, 100);
+    const hit = adapter.raycastGroundPoint(50, 50);
+    expect(hit).not.toBeNull();
+    expect(hit![1]).toBeCloseTo(0, 5);
+    expect(Math.hypot(hit![0], hit![2])).toBeLessThan(1e-4);
+  });
+
+  it("returns null when the camera faces away from the ground", () => {
+    // Tilt up (above the horizon) but NOT straight up — a forward parallel to
+    // the up vector makes lookAt degenerate (NaN basis). [0,5,3] tilts up
+    // around x, so the center ray points above y=0 and never crosses it.
+    const adapter = new ThreeAdapter(target, {
+      defaultCamera: { position: [0, 1, 0], lookAt: [0, 5, 3] },
+    });
+    adapter.setViewportSize(100, 100);
+    expect(adapter.raycastGroundPoint(50, 50)).toBeNull();
+  });
+});
+```
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pnpm vitest run src/runtime/three/adapter.test.ts -t raycastGroundPoint`
+预期：FAIL —— `adapter.raycastGroundPoint is not a function`。
+
+- [ ] **步骤 3：编写最少实现代码**
+
+在 `src/runtime/three/adapter.ts`：
+
+(a) import 区（顶部 `import * as THREE from "three";` 之后）加：
+
+```ts
+import { screenToNdc } from "@/lib/drop-helpers";
+```
+
+(b) 模块常量（放在 `const EXPORTERS … };` 之后、`export class ThreeAdapter` 之前）加：
+
+```ts
+/** Shared y=0 ground plane (normal +y) for drop raycasts. Module-level to
+ *  avoid per-pick allocation. */
+const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+```
+
+(c) 字段：在 `private readonly ndc = new THREE.Vector2();` 之后加：
+
+```ts
+  /** Reused target for raycastGroundPoint's plane intersection. */
+  private readonly groundHit = new THREE.Vector3();
+```
+
+(d) 方法：在 `pickAt(...)` 方法结束的 `}` 之后、`// ───── Export ─────` 注释之前加：
+
+```ts
+  /**
+   * Raycast the screen point `(screen_x, screen_y)` (viewport-pixel space)
+   * against the y=0 ground plane. Returns the world-space hit `[x, y, z]`, or
+   * null when the ray is parallel to / points away from the plane (camera
+   * facing the sky). Mirrors pickAt's NDC + matrix-refresh setup so a drop
+   * handled synchronously (before the next animation frame) still uses the
+   * current camera pose.
+   */
+  raycastGroundPoint(
+    screen_x: number,
+    screen_y: number,
+  ): [number, number, number] | null {
+    if (this.viewportWidth <= 0 || this.viewportHeight <= 0) return null;
+    this.camera.updateMatrixWorld(true);
+    const [ndcX, ndcY] = screenToNdc(
+      screen_x,
+      screen_y,
+      this.viewportWidth,
+      this.viewportHeight,
+    );
+    this.ndc.set(ndcX, ndcY);
+    this.raycaster.setFromCamera(this.ndc, this.camera);
+    const hit = this.raycaster.ray.intersectPlane(GROUND_PLANE, this.groundHit);
+    return hit ? [hit.x, hit.y, hit.z] : null;
+  }
+```
+
+- [ ] **步骤 4：运行测试验证通过**
+
+运行：`pnpm vitest run src/runtime/three/adapter.test.ts -t raycastGroundPoint && pnpm typecheck`
+预期：PASS + typecheck 0 error。
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add src/runtime/three/adapter.ts src/runtime/three/adapter.test.ts
+git commit -m "feat(adapter): raycastGroundPoint — screen → y=0 world hit (tested)"
+```
+
+---
+
+### 任务 5：asset-drag controller（beginAssetDrag）
+
+依赖任务 3（store）。headless 单测（jsdom window 事件）。
+
+**文件：**
+
+- 创建：`src/services/library/asset-drag.ts`
+- 测试：`src/services/library/asset-drag.test.ts`
+
+- [ ] **步骤 1：编写失败的测试**
+
+创建 `src/services/library/asset-drag.test.ts`：
+
+```ts
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { useUIStore } from "@/services/ui/store";
+
+import { beginAssetDrag } from "./asset-drag";
+
+function move(clientX: number, clientY: number) {
+  window.dispatchEvent(new MouseEvent("pointermove", { clientX, clientY }));
+}
+function up() {
+  window.dispatchEvent(new MouseEvent("pointerup", {}));
+}
+
+describe("beginAssetDrag", () => {
+  beforeEach(() => useUIStore.setState({ assetDragItemId: null }));
+
+  it("does not activate the drag below the 5px threshold", () => {
+    beginAssetDrag("geo-box", 100, 100);
+    move(103, 101); // ~3.2px
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+    up(); // cleanup
+  });
+
+  it("activates the drag once the pointer passes 5px", () => {
+    beginAssetDrag("geo-box", 100, 100);
+    move(110, 100); // 10px
+    expect(useUIStore.getState().assetDragItemId).toBe("geo-box");
+  });
+
+  it("a release before the threshold tears down without activating", () => {
+    beginAssetDrag("geo-box", 100, 100);
+    up(); // plain click/double-click — no drag
+    move(200, 200); // listeners removed → no late activation
+    expect(useUIStore.getState().assetDragItemId).toBeNull();
+  });
+});
+```
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pnpm vitest run src/services/library/asset-drag.test.ts`
+预期：FAIL —— `Failed to resolve import "./asset-drag"`。
+
+- [ ] **步骤 3：编写最少实现代码**
+
+创建 `src/services/library/asset-drag.ts`：
+
+```ts
+import { useUIStore } from "@/services/ui/store";
+
+/**
+ * Module-level drag-from-library controller. A library card calls
+ * beginAssetDrag on pointerdown; we record a candidate and watch the pointer.
+ * Only once it moves past DRAG_THRESHOLD_PX do we flip the UI store into a live
+ * asset drag — so a plain click / double-click never flashes a ghost. After
+ * activation this controller drops its own listeners; the drag is then owned by
+ * AssetDragGhost (visual) + ThreeViewport (drop), which clear it via
+ * endAssetDrag. Releasing before the threshold tears down quietly.
+ */
+const DRAG_THRESHOLD_PX = 5;
+
+let candidate: { id: string; x: number; y: number } | null = null;
+let onMove: ((e: PointerEvent) => void) | null = null;
+let onUp: (() => void) | null = null;
+
+export function beginAssetDrag(id: string, clientX: number, clientY: number): void {
+  teardown(); // drop any stale candidate before starting a new one
+  candidate = { id, x: clientX, y: clientY };
+  onMove = (e) => {
+    if (!candidate) return;
+    const moved = Math.hypot(e.clientX - candidate.x, e.clientY - candidate.y);
+    if (moved > DRAG_THRESHOLD_PX) {
+      useUIStore.getState().startAssetDrag(candidate.id);
+      teardown();
+    }
+  };
+  onUp = () => teardown();
+  window.addEventListener("pointermove", onMove);
+  window.addEventListener("pointerup", onUp);
+}
+
+function teardown(): void {
+  if (onMove) window.removeEventListener("pointermove", onMove);
+  if (onUp) window.removeEventListener("pointerup", onUp);
+  candidate = null;
+  onMove = null;
+  onUp = null;
+}
+```
+
+- [ ] **步骤 4：运行测试验证通过**
+
+运行：`pnpm vitest run src/services/library/asset-drag.test.ts`
+预期：PASS（3 个用例全绿）。
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add src/services/library/asset-drag.ts src/services/library/asset-drag.test.ts
+git commit -m "feat(library): asset-drag controller — 5px threshold activates drag"
+```
+
+---
+
+### 任务 6：AssetDragGhost + 挂载到 EditorView
+
+依赖任务 2（findLibraryItem）、任务 3（store）。无单测（DOM 位置/视觉 —— 任务 9 `pnpm tauri dev` 验证）。
+
+**文件：**
+
+- 创建：`src/ui/library/AssetDragGhost.tsx`
+- 修改：`src/ui/views/EditorView.tsx`
+
+- [ ] **步骤 1：编写组件**
+
+创建 `src/ui/library/AssetDragGhost.tsx`：
+
+```tsx
+import { useEffect, useState } from "react";
+
+import { findLibraryItem } from "@/services/library/catalog";
+import { useSceneStore } from "@/services/scene/store";
+import { useUIStore } from "@/services/ui/store";
+
+/**
+ * Cursor-following ghost shown while a library item is dragged into the
+ * viewport. Reads the active drag id from the UI store and tracks the live
+ * pointer in LOCAL state (not the store — pointermove is high-frequency and we
+ * don't want to re-render unrelated subscribers). Renders nothing until the
+ * pointer has moved at least once after activation, or if the id can't be
+ * resolved (e.g. an upload removed mid-drag).
+ */
+export function AssetDragGhost() {
+  const id = useUIStore((s) => s.assetDragItemId);
+  const uploads = useSceneStore((s) => s.project?.assets);
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+
+  useEffect(() => {
+    if (!id) return;
+    const onMove = (e: PointerEvent) => setPos({ x: e.clientX, y: e.clientY });
+    window.addEventListener("pointermove", onMove);
+    // Reset position in cleanup (runs on drag end AND target switch) — not in
+    // the effect body, which trips eslint react-hooks/set-state-in-effect.
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      setPos(null);
+    };
+  }, [id]);
+
+  if (!id || !pos) return null;
+  const item = findLibraryItem(id, uploads ?? []);
+  if (!item) return null;
+  const Icon = item.icon;
+
+  return (
+    <div
+      className="pointer-events-none fixed z-50 flex h-10 w-10 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-lg border border-primary/60 bg-card/80 opacity-80 shadow-lg backdrop-blur-sm"
+      style={{ left: pos.x, top: pos.y }}
+      aria-hidden="true"
+    >
+      <Icon className="h-6 w-6 text-foreground/90" />
+    </div>
+  );
+}
+```
+
+- [ ] **步骤 2：挂载到 EditorView**
+
+在 `src/ui/views/EditorView.tsx`：import 区（`import { LibraryPanel } from "@/ui/library/LibraryPanel";` 旁）加：
+
+```tsx
+import { AssetDragGhost } from "@/ui/library/AssetDragGhost";
+```
+
+在 return 的根 `<div>` 末尾，把 `<ShortcutsHelpDialog />` 那行改为：
+
+```tsx
+      <ShortcutsHelpDialog />
+      <AssetDragGhost />
+    </div>
+```
+
+- [ ] **步骤 3：验证 typecheck + 既有测试不退化**
+
+运行：`pnpm typecheck && pnpm vitest run src/ui`
+预期：typecheck 0 error；UI 测试全绿（ghost 默认 `assetDragItemId=null` → 渲染 null，不影响任何现有用例）。
+
+- [ ] **步骤 4：Commit**
+
+```bash
+git add src/ui/library/AssetDragGhost.tsx src/ui/views/EditorView.tsx
+git commit -m "feat(library): AssetDragGhost cursor-following drag preview"
+```
+
+---
+
+### 任务 7：LibraryPanel 卡片 pointerdown 接线 + i18n 文案
+
+依赖任务 5（beginAssetDrag）。
+
+**文件：**
+
+- 修改：`src/ui/library/LibraryPanel.tsx`
+- 修改：`src/ui/library/LibraryPanel.test.tsx`
+- 修改：`src/i18n/locales/en-US/editor.json`、`src/i18n/locales/zh-CN/editor.json`
+
+- [ ] **步骤 1：编写失败的测试**
+
+在 `src/ui/library/LibraryPanel.test.tsx`：把新 import 与其他 import 放一起（顶部），再在**所有 import 之后**（`function seed` 之前）写 `vi.mock`。vitest 会把 `vi.mock` 提升到 import 之上，这样既能 mock 成功，又不违反 eslint `import/first`（import 必须在语句之前）：
+
+```tsx
+// 与现有 import 同组（顶部）：
+import { beginAssetDrag } from "@/services/library/asset-drag";
+
+// 所有 import 之后、function seed 之前：
+vi.mock("@/services/library/asset-drag", () => ({
+  beginAssetDrag: vi.fn(),
+}));
+```
+
+在 `describe("LibraryPanel", …)` 的 `beforeEach` 里追加一行清 mock：
+
+```tsx
+vi.mocked(beginAssetDrag).mockClear();
+```
+
+在该 describe 内追加用例：
+
+```tsx
+it("pointer-down on a card begins an asset drag with the item id", () => {
+  render(<LibraryPanel />);
+  fireEvent.pointerDown(screen.getByText("Sphere"), { clientX: 12, clientY: 34 });
+  expect(beginAssetDrag).toHaveBeenCalledTimes(1);
+  expect(vi.mocked(beginAssetDrag).mock.calls[0]?.[0]).toBe("geo-sphere");
+});
+```
+
+（只断言第一个实参 = id，避开 jsdom 对 pointer 事件 clientX 的差异。）
+
+- [ ] **步骤 2：运行测试验证失败**
+
+运行：`pnpm vitest run src/ui/library/LibraryPanel.test.tsx`
+预期：FAIL —— `expected beginAssetDrag to be called` / `import "./asset-drag"`（卡片还没接 onPointerDown）。
+
+- [ ] **步骤 3：接线 LibraryPanel**
+
+在 `src/ui/library/LibraryPanel.tsx`：import 区（`import { ... } from "@/services/library/catalog";` 旁）加：
+
+```tsx
+import { beginAssetDrag } from "@/services/library/asset-drag";
+```
+
+找到卡片 `<button>`（`key={item.id}` `type="button"` `onDoubleClick={() => addItem(item)}` 那个），加两个属性（与 `onDoubleClick` 并列）：
+
+```tsx
+                      draggable={false}
+                      onPointerDown={(e) => beginAssetDrag(item.id, e.clientX, e.clientY)}
+```
+
+- [ ] **步骤 4：更新 i18n 文案**
+
+`src/i18n/locales/en-US/editor.json` —— `library.add_hint`：
+
+```json
+    "add_hint": "Double-click or drag into the viewport to add",
+```
+
+`src/i18n/locales/zh-CN/editor.json` —— `library.add_hint`：
+
+```json
+    "add_hint": "双击或拖入视口添加",
+```
+
+- [ ] **步骤 5：运行测试验证通过**
+
+运行：`pnpm vitest run src/ui/library/LibraryPanel.test.tsx && pnpm typecheck`
+预期：PASS（新增用例 + 既有「double-click 加节点」回归用例全绿）+ typecheck 0 error。
+
+- [ ] **步骤 6：Commit**
+
+```bash
+git add src/ui/library/LibraryPanel.tsx src/ui/library/LibraryPanel.test.tsx src/i18n/locales/en-US/editor.json src/i18n/locales/zh-CN/editor.json
+git commit -m "feat(library): card pointerdown starts drag; hint mentions drag"
+```
+
+---
+
+### 任务 8：ThreeViewport 落点接收（window pointerup）
+
+依赖任务 1（dropPositionFor）、2（findLibraryItem）、3（store）、4（raycastGroundPoint）。集成 capstone，无单测（WebGL + pointer）→ 任务 9 视觉验证。
+
+**文件：**
+
+- 修改：`src/ui/viewport/ThreeViewport.tsx`
+
+- [ ] **步骤 1：补 import**
+
+在 `src/ui/viewport/ThreeViewport.tsx` 顶部 import 区加：
+
+```tsx
+import { AddNodeCommand } from "@/core/command/commands/add-node";
+import { dropPositionFor } from "@/lib/drop-helpers";
+import { findLibraryItem } from "@/services/library/catalog";
+```
+
+（`executeCommand`、`useSceneStore`、`useUIStore` 已 import；`setSelectedNodeId` 已是 mount effect 闭包内变量。）
+
+- [ ] **步骤 2：注册 window pointerup 落点处理**
+
+在 mount effect 内，紧接 `canvas.addEventListener("click", onClick);`（约第 299 行）之后加：
+
+```tsx
+// Asset drag-drop: a library-card drag activates assetDragItemId (see
+// services/library/asset-drag.ts). On release inside the canvas, raycast
+// the y=0 ground plane and add the item there (falling back to the item's
+// default position when the ray misses — camera facing the sky). Released
+// outside the canvas or on a miss-with-no-item we still clear the drag.
+// Bound on window (not canvas) so a release a few px past the canvas edge
+// is still caught.
+const onAssetDrop = (event: PointerEvent) => {
+  const id = useUIStore.getState().assetDragItemId;
+  if (!id) return; // not an asset drag
+  const rect = canvas.getBoundingClientRect();
+  const x = event.clientX - rect.left;
+  const y = event.clientY - rect.top;
+  const inside = x >= 0 && y >= 0 && x <= rect.width && y <= rect.height;
+  if (inside) {
+    const uploads = useSceneStore.getState().project?.assets ?? [];
+    const item = findLibraryItem(id, uploads);
+    if (item) {
+      const node = item.makeNode();
+      const hit = adapter.raycastGroundPoint(x, y);
+      if (hit) {
+        node.transform.position = dropPositionFor(node.transform.position, hit);
+      }
+      executeCommand(new AddNodeCommand({ node }));
+      setSelectedNodeId(node.id);
+    }
+  }
+  useUIStore.getState().endAssetDrag(); // clear whether dropped in/out
+};
+window.addEventListener("pointerup", onAssetDrop);
+```
+
+- [ ] **步骤 3：cleanup 注销**
+
+在 mount effect 的 `return () => { … }` 里，紧接 `canvas.removeEventListener("pointerdown", onPointerDown);` 之后加：
+
+```tsx
+window.removeEventListener("pointerup", onAssetDrop);
+```
+
+- [ ] **步骤 4：验证 typecheck + 全量测试**
+
+运行：`pnpm typecheck && pnpm vitest run`
+预期：typecheck 0 error；全部测试绿（ThreeViewport 无新单测，但不得引入退化）。
+
+- [ ] **步骤 5：Commit**
+
+```bash
+git add src/ui/viewport/ThreeViewport.tsx
+git commit -m "feat(viewport): drop library item at ground raycast hit (undoable)"
+```
+
+---
+
+### 任务 9：全量验证 + 视觉冒烟（不可跳过）
+
+vitest 绿 ≠ 功能正确：拖拽全链路是 pointer + WebGL，jsdom 抓不到，必须真跑。
+
+- [ ] **步骤 1：静态 + 单测全绿**
+
+运行：`pnpm lint && pnpm typecheck && pnpm test`
+预期：三者 0 error / 全绿。若 prettier 报 `editor.json` 格式，按 `pnpm lint` 提示修（或 `pnpm prettier -w` 仅对改动文件）后重跑。
+
+- [ ] **步骤 2：`pnpm tauri dev` 视觉冒烟（对照 spec §2 Success criteria）**
+
+运行：`pnpm tauri dev`，逐项确认：
+
+1. 几何卡片（如 Box）按住拖动 > 5px → 出现半透明 ghost 跟随光标；canvas 内松手 → 落点处新增 Box，落点 = 地面交点 x/z、y 保持 0.5（坐落地面不半埋）。
+2. 灯光卡片、上传 glb 同样可拖入；glb 落点 x/z 对、y 保留默认。
+3. **纯双击**某卡片（不移动）→ 不闪 ghost、按默认位加节点（回归不破）。
+4. 卡片拖到 **canvas 外** 松手 → 不加节点、ghost 消失。
+5. 相机转到**朝天/与地面平行**再拖入 → raycast 未命中 → 仍加节点但用库项默认 position（等同双击）。
+6. 拖入后 **Cmd/Ctrl+Z** → 撤销该节点（`AddNodeCommand` 生效）。
+7. 落点后该节点**被选中**（properties 面板显示它）。
+
+- [ ] **步骤 3：（可选）截图留档**
+
+如需为 PR 留证据，截 ghost 跟随 + 落点结果各一张。
+
+- [ ] **步骤 4：收尾**
+
+全部通过后用 superpowers:finishing-a-development-branch 决定合并 / PR / 清理。PR 描述链接本 plan 与 spec，并在 `docs/roadmap.md` 把 v0.4「资源拖拽」对应 sub-stage 勾选 + 补 PR 链接（该勾选放 PR 内一并提交）。
+
+---
+
+## 自检
+
+**1. 规格覆盖度（spec §2 / §3 / §10 逐条）：**
+
+- `screenToNdc` / `dropPositionFor` 纯函数 + 单测 → 任务 1 ✓（spec §5.1、§9、success #5）
+- `findLibraryItem` + 单测 → 任务 2 ✓（spec §5.2、§9、success #5）
+- `assetDragItemId` + start/end → 任务 3 ✓（spec §5.3）
+- `raycastGroundPoint` + GROUND_PLANE → 任务 4 ✓（spec §6.5；额外补单测）
+- `beginAssetDrag` controller（5px 阈值、双击不触发）→ 任务 5 ✓（spec §6.1、success #2/#3；额外补单测）
+- `AssetDragGhost`（跟随光标、pointer-events-none）→ 任务 6 ✓（spec §6.3、§8）
+- LibraryCard `onPointerDown` + `draggable={false}` → 任务 7 ✓（spec §6.2）
+- EditorView 挂 ghost → 任务 6 ✓（spec §10 修改清单）
+- ThreeViewport window pointerup 落点（inside 判定、hit 回退、AddNodeCommand、endAssetDrag）→ 任务 8 ✓（spec §6.4、§7、success #1/#3/#4/#6）
+- i18n `add_hint` 文案 → 任务 7 ✓（spec §8、§10）
+- 全绿 + 视觉验证 → 任务 9 ✓（spec §2 success #6、§12）
+- **Out of scope 守界**（spec §3）：不做物体表面落点 / 落点网格吸附 / 3D 预览 / OS file-drop / glb 底部对齐 —— 本计划均未触碰 ✓
+
+**2. 占位符扫描：** 全任务每步均含完整可粘贴代码 + 精确命令 + 预期输出；无 TODO/待定/「类似任务 N」。✓
+
+**3. 类型一致性：**
+
+- `LibraryItem.icon: LucideIcon` → ghost 用 `const Icon = item.icon; <Icon/>`（非字符串）✓
+- 资源列表统一 `useSceneStore…project?.assets`（无 `useAssetStore`）✓
+- `findLibraryItem(id: string, uploads: AssetReference[])` 在任务 2 定义，任务 6/8 同签名调用 ✓
+- `raycastGroundPoint(screen_x, screen_y): [number,number,number] | null` 任务 4 定义，任务 8 同形 ✓
+- `startAssetDrag(id)/endAssetDrag()/assetDragItemId` 任务 3 定义，任务 5/6/8 一致 ✓
+- `AddNodeCommand({ node })` 与现有构造签名一致（`AddNodeInput.node`）✓
+- runtime→`@/lib` import 合法（已有先例）✓
+
+发现即修，无遗留。
+
+---
+
+## 执行交接
+
+计划已保存到 `docs/superpowers/plans/2026-06-08-asset-drag-into-viewport-plan.md`。两种执行方式：
+
+1. **子代理驱动（推荐）** —— 每个任务调度一个新子代理，任务间两阶段审查，快速迭代。
+2. **内联执行** —— 当前会话用 executing-plans 批量执行并设检查点。
+
+任务 1–5、7 为机械 TDD（可并行度高、风险低）；任务 6、8 是 UI/集成（需任务 9 视觉验证兜底）。选哪种？

From f52164088ee1a60065366668a004b3ed3537df72 Mon Sep 17 00:00:00 2001
From: longyi-xw <2691049525@qq.com>
Date: Mon, 8 Jun 2026 17:02:00 +0800
Subject: [PATCH 11/11] =?UTF-8?q?docs(roadmap):=20v0.4=20=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E6=8B=96=E6=8B=BD=E5=85=A5=E8=A7=86=E5=8F=A3=20+=20?=
 =?UTF-8?q?=E8=90=BD=E7=82=B9=20=E5=AE=8C=E6=88=90=20(#35)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/roadmap.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/roadmap.md b/docs/roadmap.md
index dc351c6..efa2b5c 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -110,9 +110,10 @@
 - **Sub-stages**:
   - [x] **A · 网格吸附 + 吸附框架**（#33）：gizmo 平移拖拽时按住 Ctrl/Cmd 吸附到 0.5 网格；`snapTranslation` 纯函数引擎（`src/core/snap/`，供 B/C 扩展）+ ThreeViewport `objectChange` hook（pointer 读即时修饰键，不卡）。仅平移。
   - [x] **B · 节点对齐吸附**（#34）：gizmo 平移拖拽 + 按住 Ctrl/Cmd 时，被拖节点包围盒 15 特征（中心 + 8 角 + 6 面中心，**OBB** 跟随旋转）吸附到附近节点对应特征——屏幕像素（12px）做门槛、**3D 世界距离**选最近对齐对象（避免平行视角吸到深度更远的目标）；无命中回退 A 的网格吸附。`snapToNodes` 纯函数（`src/core/snap/nodes.ts`）+ ThreeViewport 投影/OBB 特征提取。仅平移。
+  - [x] **资源拖拽入视口 + 落点**（[#35](https://github.com/longyi-xw/lowcode-3d/pull/35)）：从资源库卡片拖拽到视口，以 raycast y=0 地面命中点为落点（覆盖 x/z、保留库项默认 y）；双击加节点保留；走 `AddNodeCommand` 可撤销。纯函数 `screenToNdc`/`dropPositionFor`（`src/lib/drop-helpers.ts`）+ `findLibraryItem` + adapter `raycastGroundPoint` + 自定义 pointer 拖拽（Tauri 2 默认抑制 HTML5 DnD）+ DOM ghost。仅 y=0 地面（物体表面落点 / 落点吸附 / 3D 预览 / OS file-drop 见 Backlog）。
   - [ ] **C · Socket 系统**：节点上命名插槽 + 拖拽时兼容插槽咬合。
 - **Depends on**: v0.3 release
-- **后续插入**：sub-stage B 完成后做「资源拖拽入视口 + 落点」（见 Backlog，用户定的顺序），再进 C。
+- **后续**：「资源拖拽入视口 + 落点」已完成（见上 sub-stage，#35）；下一步 sub-stage C（Socket 系统）。
 
 ### v1.0 — Planned
 
@@ -129,7 +130,6 @@
 从已完成 sub-stage 中刻意拆出的功能点，尚未排期到具体 release：
 
 - **材质贴图 pipeline**（从 v0.2 材质编辑拆出）：normalMap / map / roughnessMap / metalnessMap / aoMap 等。需 `MaterialOverrideSchema` 加贴图字段（引用 `kind:"texture"` 的 `AssetReference`）+ texture 资源上传入库 + runtime `TextureLoader`（`mesh.ts applyOverrides` 加贴图通道）+ codegen emit `TextureLoader().load("./assets/…")` + UI 贴图选择器。独立子系统，单独 spec→plan→实现。
-- **资源拖拽入视口 + 落点**（从 v0.2 资源库拆出）：当前资源库为**双击**加节点到默认位置（几何抬 `y=0.5`）。从库卡片**拖拽**到视口，以 raycast 命中地面/物体的点作为新节点 `position`（可与 v0.4 网格吸附结合：落点吸附网格）。**用户已定顺序：排在 v0.4 sub-stage B 之后做**。
 - **多源资源上传**（从 v0.2 资源库拆出）：`AssetSourceSchema` 已含 `builtin/user_upload/online/ai_generated` 且 catalog 来源无关；目前只实装 `builtin`（几何/灯光预设）+ `user_upload`（.glb）。延后：`online`（在线模型/材质库浏览+下载入库）、`ai_generated`（AI 生成模型/贴图）。
 - **多材质槽**（从 v0.2 材质编辑拆出）：本期材质编辑只支持 slot 0；prefab/glTF 多材质对象的 slot 1+ 延后。
 - **agentic 多轮 Skill 执行**（从 v0.3 sub-stage B 拆出）：本期 Skill 是**单轮结构化输出**（NL→LLM 一次返回 operations→Command）。延后：架构 §4.3 的 `call_tool` / `allowed_tools` 多轮 agent 循环（LLM 多轮调工具、读场景、迭代纠错）+ `SkillContext.memory`（`MemoryStore` 项目暂无实现）。用户明确「多轮后续肯定要完善」。