@allbluecn/web-app 0.19.2 → 0.19.4

package/src/components/design/canvas/document/constraints.ts

@@ -26,6 +26,10 @@ function applyAxis(
       const ratio = oldSize === 0 ? 1 : newSize / oldSize
       return { start: start * ratio, size: size * ratio }
     }
+    default:
+      // 历史数据可能出现非法 mode（守卫遗漏时）——按 min 兜底，避免隐式
+      // undefined 写进 x/width（后续渲染/序列化行为不可预期）
+      return { start, size }
   }
 }
 
@@ -72,8 +76,10 @@ export function applyConstraintsDiff(prevDoc: SceneDocument, nextDoc: SceneDocum
   }
 
   const patchedById = new Map<string, SceneNode>()
+  // 父节点查表一次构建，避免 changedParents × nodes 的 O(n×m) 扫描
+  const nextById = new Map(nextDoc.nodes.map((n) => [n.id, n]))
   for (const [parentId, rect] of changedParents) {
-    const parent = nextDoc.nodes.find((n) => n.id === parentId)
+    const parent = nextById.get(parentId)
     if (!parent) continue
     for (const patched of applyConstraints(parent, byParent.get(parentId) ?? [], rect.oldRect, rect.newRect)) {
       patchedById.set(patched.id, patched)

package/src/components/design/canvas/document/frames.ts

@@ -81,7 +81,7 @@ export const FRAME_PRESETS: Record<FramePresetKind, { items: FramePresetItem[] }
     items: [
       { name: "iPhone 18 Pro Max 440×956", width: 440, height: 956, cornerRadius: 62, model: "iPhone 18 Pro Max" },
       { name: "iPhone Duo（外屏）466×678", width: 466, height: 678, corners: [8, 62, 62, 8], model: "iPhone Duo（外屏）" },
-      { name: "iPhone Duo（内屏）626×890", width: 890, height: 626, cornerRadius: 62, model: "iPhone Duo（内屏）" },
+      { name: "iPhone Duo（内屏）890×626", width: 890, height: 626, cornerRadius: 62, model: "iPhone Duo（内屏）" },
       { name: "iPhone SE 375×667", width: 375, height: 667, model: "iPhone SE" },
       { name: "Mate 90 Pro 360×800", width: 360, height: 800, cornerRadius: 20, model: "Mate 90 Pro" },
       { name: "Mate 90 Pro Max 360×776", width: 360, height: 776, cornerRadius: 20, model: "Mate 90 Pro Max" },
@@ -156,7 +156,8 @@ export function createFrameNode(
     kind: "group",
     type: "frame",
     parentId: BOARD_NODE_ID,
-    name: name ?? "Frame",
+    // 兜底名走 i18n（调用方未传 name 时不再产出英文 "Frame"）
+    name: name ?? m.canvas_frameDefaultName({ count: 1 }),
     x: bounds.x,
     y: bounds.y,
     width: bounds.width,

package/src/components/design/canvas/document/layer-order.ts

@@ -57,6 +57,10 @@ export function reorderNodesDoc(
     if (to === at) continue
     const [moved] = siblings.splice(at, 1)
     siblings.splice(to, 0, moved)
+    // 回写当前顺序：同组多选时后续 id 基于前序移动的结果继续，
+    // 否则每个 id 都从原始顺序出发重排，先处理节点的移动被后处理节点的
+    // 整组覆写静默丢失
+    group.items = siblings
     for (let s = 0; s < siblings.length; s++) {
       out[group.indexes[s]] = siblings[s]
     }

package/src/components/design/canvas/document/reconcile.ts

@@ -109,10 +109,6 @@ function fastSameProjection(a: SceneNode, b: SceneNode): boolean {
   return true
 }
 
-function sameProjection(a: SceneNode, b: SceneNode): boolean {
-  return fastSameProjection(a, b)
-}
-
 export function planSceneDiff(prev: SceneDocument, next: SceneDocument): SceneDiffPlan {
   const prevById = new Map(prev.nodes.map((node) => [node.id, node]))
   const nextById = new Map(next.nodes.map((node) => [node.id, node]))
@@ -141,7 +137,7 @@ export function planSceneDiff(prev: SceneDocument, next: SceneDocument): SceneDi
     if (before.parentId !== node.parentId) {
       // 结构变化（re-parent）：leaf 引用保留，几何走 patch（doc 坐标已权威）
       toPatch.push(node.id)
-    } else if (!sameProjection(before, node)) {
+    } else if (!fastSameProjection(before, node)) {
       toPatch.push(node.id)
     }
     // 名称标签状态

package/src/components/design/canvas/document/style/color-utils.ts

@@ -51,9 +51,9 @@ function cssNumberOrPercent(token: string, scale: number): number {
   return Number.isFinite(v) ? v : NaN
 }
 
-/** CSS 色相角：deg（无单位同 deg）/ grad / rad / turn */
+/** CSS 色相角：deg（无单位同 deg）/ grad / rad / turn；CSS Color 4 允许负角度（等价 mod 360） */
 function cssHue(token: string): number {
-  const m = token.match(/^([\d.]+)(deg|grad|rad|turn)?$/)
+  const m = token.match(/^(-?[\d.]+)(deg|grad|rad|turn)?$/)
   if (!m) return NaN
   const v = Number(m[1])
   switch (m[2]) {

package/src/components/design/canvas/document/style/theme-color.ts

@@ -44,8 +44,23 @@ let cache = new Map<ThemeName, string>()
 let cacheTime = 0
 const TTL = 30_000
 
+// 主题明暗切换最终体现为 documentElement class 变化（next-themes / theme-mode）。
+// 缓存命中路径挂一个惰性 observer：class 变化即失效缓存，避免主题切换后
+// TTL 窗口内 resolveThemeColor 持续供给旧主题色（画布新取色用错主题色）。
+let invalidationWired = false
+
+function ensureThemeInvalidation(): void {
+  if (invalidationWired || typeof document === "undefined") return
+  invalidationWired = true
+  new MutationObserver(() => {
+    cache = new Map()
+    cacheTime = 0
+  }).observe(document.documentElement, { attributes: true, attributeFilter: ["class"] })
+}
+
 export function resolveThemeColor(name: ThemeName): string {
   if (typeof document === "undefined") return FALLBACKS[name]
+  ensureThemeInvalidation()
   const now = Date.now()
   if (cacheTime === 0 || now - cacheTime > TTL) {
     const cs = getComputedStyle(document.documentElement)

package/src/components/design/canvas/document/types.ts

@@ -23,9 +23,13 @@ export const BOARD_DEFAULT_HEIGHT = 812
 export const BOARD_NODE_ID = "board"
 
 export type SceneNodeKind = "shape" | "component" | "group"
-export type SceneNodeType =
+// 已知节点字面量 + 开放 string 扩展（registry 自定义组件 type 不封闭）。
+// `(string & {})` 保住字面量的 IDE 自动补全与拼写提示；直接 `| string` 会把
+// 整个联合坍缩为 string，字面量全部失去提示与穷举检查作用。
+export type KnownSceneNodeType =
   | "board"
   | "group"
+  | "frame"
   | "rect"
   | "ellipse"
   | "line"
@@ -35,7 +39,7 @@ export type SceneNodeType =
   | "path"
   | "polygon"
   | "star"
-  | string
+export type SceneNodeType = KnownSceneNodeType | (string & {})
 
 export const STRUCTURAL_TYPES = new Set<SceneNodeType>(["board", "group", "frame"])
 

package/src/components/design/canvas/panels/__tests__/color-paint-picker.test.tsx

@@ -15,7 +15,7 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-import { fireEvent, render, screen } from "@testing-library/react"
+import { act, fireEvent, render, screen } from "@testing-library/react"
 import { describe, expect, it, vi } from "vitest"
 
 import { ColorPaintPicker } from "../controls/color-paint-picker"
@@ -24,13 +24,48 @@ function open() {
   fireEvent.click(screen.getByRole("button", { name: "选择颜色" }))
 }
 
+/** 给饱和度区交互层一个 100×100 rect 并构造带 pageX 的指针事件：
+ *  react-colorful 以 pageX/pageY 计算取色位置，jsdom 的 MouseEvent 不支持
+ *  pageX init 且容器 rect 恒 0；坐标 (x,y) 即 s=x%、v=(100-y)%。
+ *  document 级 move/up 须 act 包裹以同步 flush react-colorful 的 emit effect。 */
+function setupPickerGeometry(): HTMLElement {
+  const interactive = document.querySelector(
+    ".react-colorful__saturation .react-colorful__interactive",
+  ) as HTMLElement
+  Object.defineProperty(interactive, "getBoundingClientRect", {
+    value: () =>
+      ({ left: 0, top: 0, width: 100, height: 100, right: 100, bottom: 100, x: 0, y: 0, toJSON: () => ({}) }),
+  })
+  return interactive
+}
+
+function pickerPointer(
+  type: "mousedown" | "mousemove" | "mouseup",
+  target: EventTarget,
+  x: number,
+  y: number,
+): void {
+  const evt = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    clientX: x,
+    clientY: y,
+    buttons: type === "mouseup" ? 0 : 1,
+  })
+  Object.defineProperty(evt, "pageX", { value: x })
+  Object.defineProperty(evt, "pageY", { value: y })
+  act(() => {
+    target.dispatchEvent(evt)
+  })
+}
+
 describe("ColorPaintPicker", () => {
   it("点击色板展开 Popover 含 HEX 输入与 react-colorful 取色器", () => {
     render(<ColorPaintPicker color="#ff0000" opacity={0.5} onChange={vi.fn()} />)
     open()
     // 三合一形态：Hash 图标前缀，输入框值不带 #
     expect(screen.getByLabelText("颜色值")).toHaveDisplayValue("ff0000")
-    expect(screen.getByLabelText("透明度")).toHaveDisplayValue("50")
+    expect(screen.getByLabelText("不透明度")).toHaveDisplayValue("50")
     expect(document.querySelector(".react-colorful")).toBeInTheDocument()
   })
 
@@ -53,4 +88,44 @@ describe("ColorPaintPicker", () => {
     fireEvent.blur(hex)
     expect(onChange).not.toHaveBeenCalled()
   })
+
+  it("透明度方向键以输入框草稿为基准（不丢弃未提交草稿）", () => {
+    const onChange = vi.fn()
+    render(<ColorPaintPicker color="#ff0000" opacity={1} onChange={onChange} />)
+    open()
+    const opacity = screen.getByLabelText("不透明度")
+    // 输入草稿 30 但未 blur/Enter 提交
+    fireEvent.change(opacity, { target: { value: "30" } })
+    fireEvent.keyDown(opacity, { key: "ArrowUp" })
+    expect(onChange).toHaveBeenCalledWith("#ff0000", 0.31)
+  })
+
+  it("提供 onChangeLive 时色板拖拽走 live 通道，松手 onChangeEnd 提交一次", () => {
+    const onChange = vi.fn()
+    const onChangeLive = vi.fn()
+    render(
+      <ColorPaintPicker color="#ff0000" opacity={1} onChange={onChange} onChangeLive={onChangeLive} />,
+    )
+    open()
+    const interactive = setupPickerGeometry()
+    // react-colorful 以 mouse 事件工作：mousedown 后挂 document mousemove/mouseup
+    pickerPointer("mousedown", interactive, 10, 10)
+    pickerPointer("mousemove", document, 40, 30)
+    expect(onChangeLive).toHaveBeenCalled()
+    expect(onChange).not.toHaveBeenCalled()
+    pickerPointer("mouseup", document, 40, 30)
+    expect(onChange).toHaveBeenCalledTimes(1)
+    // 提交值与最后一次 live 值一致
+    const lastLive = onChangeLive.mock.calls.at(-1) as [string, number]
+    expect(onChange).toHaveBeenCalledWith(lastLive[0], lastLive[1])
+  })
+
+  it("未提供 onChangeLive 时色板保持既有逐次提交行为", () => {
+    const onChange = vi.fn()
+    render(<ColorPaintPicker color="#ff0000" opacity={1} onChange={onChange} />)
+    open()
+    const interactive = setupPickerGeometry()
+    pickerPointer("mousedown", interactive, 10, 10)
+    expect(onChange).toHaveBeenCalledTimes(1)
+  })
 })

package/src/components/design/canvas/panels/__tests__/number-drag-input.test.tsx

@@ -133,6 +133,31 @@ describe("NumberDragInput", () => {
     expect(onCommit).toHaveBeenCalledWith(155)
   })
 
+  it("拖拽中途卸载：移除 document 监听，不再向已卸载组件提交冻结值", () => {
+    const onCommit = vi.fn()
+    const { unmount } = render(
+      <NumberDragInput
+        label="W"
+        value={100}
+        min={1}
+        max={10000}
+        step={1}
+        icon={<span />}
+        onCommit={onCommit}
+      />,
+    )
+    const input = screen.getByLabelText("W")
+    const iconSpan = input.parentElement?.querySelector("span[aria-hidden]") as HTMLElement
+    fireEvent.pointerDown(iconSpan, { pointerId: 1, clientX: 0, button: 0 })
+    fireEvent.pointerMove(document, { pointerId: 1, clientX: 30, buttons: 1 })
+    unmount()
+    // 卸载即清理：释放指针 / window blur 兜底均不再触发 commit
+    //（旧实现会以冻结草稿向已卸载组件提交一次）
+    fireEvent.pointerUp(document, { pointerId: 1 })
+    fireEvent(window, new Event("blur"))
+    expect(onCommit).not.toHaveBeenCalled()
+  })
+
   it("滚轮防抖合并提交（两次滚动一次提交终值）", async () => {
     const onCommit = vi.fn()
     render(<NumberDragInput label="H" value={10} min={1} max={10000} step={1} onCommit={onCommit} />)

package/src/components/design/canvas/panels/__tests__/rows.test.tsx

@@ -17,7 +17,7 @@ describe("PaintRow", () => {
   it("不透明度输入提交 opacity（% → 0-1）", () => {
     const onChange = vi.fn()
     render(<PaintRow value={createPaint()} onChange={onChange} />)
-    const pct = screen.getByLabelText("透明度")
+    const pct = screen.getByLabelText("不透明度")
     fireEvent.change(pct, { target: { value: "50" } })
     fireEvent.keyDown(pct, { key: "Enter" })
     expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ opacity: 0.5 }))

package/src/components/design/canvas/panels/__tests__/toolbar.test.tsx

@@ -354,8 +354,7 @@ describe("折线绘制快捷键接线（捕获相防御，最终审查 F2）", (
     document.addEventListener("keydown", documentListener)
 
     function Harness() {
-      const hostRef = { current: null }
-      useCanvasDrawing(hostRef, "polyline")
+      useCanvasDrawing("polyline")
       return <div data-testid="host" />
     }
 

package/src/components/design/canvas/panels/component-library-data.ts

@@ -24,6 +24,7 @@ import { m } from "@/paraglide/messages.js"
 
 import type { INodeFactory } from "../registry/registry"
 import { getNodeFactory, resolveDefaults } from "../registry/registry"
+import { BUILTIN_TEXT_DEFAULTS, builtinTextDefault } from "../registry/builtin/default-labels"
 import { BOARD_NODE_ID, type DeviceType, type SceneNode, type SceneNodeType } from "../document/types"
 
 export type CanvasPoint = { x: number; y: number }
@@ -68,6 +69,13 @@ export function buildComponentNode(
 ): SceneNode {
   const size = resolveDefaults(type, device)
   const factory = getNodeFactory(type)
+  const props = defaultPropsOf(factory?.propsSchema)
+  // 文案类默认值走 i18n：schema default 为空占位（注册期静态、不可按 locale
+  // 惰性求值）时，创建时按当前 locale 注入单一来源 builtinTextDefault 的值；
+  // schema 已有显式默认值则尊重 schema（自定义注册可覆盖）
+  if (props.text === "" && type in BUILTIN_TEXT_DEFAULTS) {
+    props.text = builtinTextDefault(type)
+  }
   return {
     id,
     kind: "component",
@@ -77,6 +85,6 @@ export function buildComponentNode(
     y: Math.round(point.y - size.height / 2),
     width: size.width,
     height: size.height,
-    props: defaultPropsOf(factory?.propsSchema),
+    props,
   }
 }

package/src/components/design/canvas/panels/controls/color-paint-picker.tsx

@@ -4,6 +4,7 @@ import { Blend, Hash } from "lucide-react";
 import { HexAlphaColorPicker } from "react-colorful";
 
 import { colorToHexAlpha, parseColor, toHex } from "@/components/design/canvas/document/style/color-utils";
+import { m } from "@/paraglide/messages.js";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
 import { cn } from "@/lib/utils";
 
@@ -40,6 +41,10 @@ export function ColorPaintPicker({
   const [hexDraft, setHexDraft] = useState<string>(color);
   const [opacityDraft, setOpacityDraft] = useState<string>(`${Math.round(opacity * 100)}`);
   const [open, setOpen] = useState(false);
+  // 色板拖拽期间的最新草稿：提供 onChangeLive 时拖拽中走 live 通道（不入 history），
+  // 松手/键盘释放（react-colorful 的 onChangeEnd）提交一次。无位移的纯点击也会
+  // 触发一次 onChange，latest 始终有值；未提供 onChangeLive 时保持逐次提交行为。
+  const latestRef = useRef<{ color: string; opacity: number } | null>(null);
   // 弹窗内最后一次 pointerdown 的时间戳：用于识别「拖拽从弹窗内起、释落在触发器上」的 click，
   // 该 click 会被 Base UI 触发器当作 toggle 关闭弹窗（reason=trigger-press），需拦截
   const popupPressAtRef = useRef(0);
@@ -91,8 +96,8 @@ export function ColorPaintPicker({
           // 若按压起始于弹窗内（600ms 内），视为拖拽尾部误关，拦截
           if (
             !nextOpen &&
-            (details.reason === "trigger-press" ||
-              details.reason === "outside-press") &&
+            (details?.reason === "trigger-press" ||
+              details?.reason === "outside-press") &&
             Date.now() - popupPressAtRef.current < 600
           ) {
             return;
@@ -103,7 +108,7 @@ export function ColorPaintPicker({
         <PopoverTrigger
           className="size-6 shrink-0 rounded-full border border-border ring-offset-background outline-none hover:ring-2 hover:ring-foreground/20"
           style={{ backgroundColor: colorToHexAlpha(color, opacity) }}
-          aria-label="选择颜色"
+          aria-label={m.canvas_colorSwatch()}
         />
         <PopoverContent
           align="start"
@@ -127,7 +132,18 @@ export function ColorPaintPicker({
                 const newAlpha = Number(parsed.a.toFixed(4));
                 setHexDraft(newHex);
                 setOpacityDraft(`${Math.round(newAlpha * 100)}`);
-                onChange(newHex, newAlpha);
+                if (onChangeLive) {
+                  // 拖拽/键盘调色走实时预览通道（不入 history），松手经 onChangeEnd 提交一次
+                  latestRef.current = { color: newHex, opacity: newAlpha };
+                  onChangeLive(newHex, newAlpha);
+                } else {
+                  onChange(newHex, newAlpha);
+                }
+              }}
+              onChangeEnd={() => {
+                const latest = latestRef.current;
+                latestRef.current = null;
+                if (latest) onChange(latest.color, latest.opacity);
               }}
           />
         </PopoverContent>
@@ -138,7 +154,7 @@ export function ColorPaintPicker({
           <Hash className="size-3" />
         </span>
         <input
-          aria-label="颜色值"
+          aria-label={m.canvas_colorValue()}
           type="text"
           value={hexDraft.replace(/^#/, "")}
           disabled={colorDisabled}
@@ -166,7 +182,7 @@ export function ColorPaintPicker({
             <Blend className="size-3" />
           </span>
           <input
-            aria-label="透明度"
+            aria-label={m.canvas_opacityField()}
             type="text"
             inputMode="numeric"
             value={opacityDraft}
@@ -177,15 +193,14 @@ export function ColorPaintPicker({
             onKeyDown={(e) => {
               if (e.key === "Enter") commitOpacity(e.currentTarget.value);
               if (e.key === "Escape") setOpacityDraft(`${Math.round(opacity * 100)}`);
-              if (e.key === "ArrowUp") {
-                e.preventDefault();
-                const next = Math.min(100, Math.max(0, Math.round(opacity * 100) + 1));
-                setOpacityDraft(String(next));
-                onChange(color, next / 100);
-              }
-              if (e.key === "ArrowDown") {
+              if (e.key === "ArrowUp" || e.key === "ArrowDown") {
                 e.preventDefault();
-                const next = Math.min(100, Math.max(0, Math.round(opacity * 100) - 1));
+                // 以输入框当前草稿为基准（与显示值一致）；草稿非法时退回已提交值
+                const parsedDraft = Number(opacityDraft);
+                const base = Number.isFinite(parsedDraft) && opacityDraft !== ""
+                  ? Math.round(parsedDraft)
+                  : Math.round(opacity * 100);
+                const next = Math.min(100, Math.max(0, base + (e.key === "ArrowUp" ? 1 : -1)));
                 setOpacityDraft(String(next));
                 onChange(color, next / 100);
               }

package/src/components/design/canvas/panels/controls/gradient-editor.tsx

@@ -20,6 +20,7 @@ import { ColorPaintPicker } from "./color-paint-picker"
 import { defaultGradientStops, type GradientPaint } from "./gradient-data"
 import { PATTERN_TEXTURES } from "./pattern-data"
 import { NumberDragInput } from "./number-drag-input"
+import { usePointerDrag } from "./use-pointer-drag"
 
 // 渐变几何字段（stops/from/to）：渐变互切时保留同语义字段
 // （linear/radial 有 from+to，angular 仅 from；stretch/rotation 为类型私有，仅同型保留）
@@ -241,41 +242,42 @@ export function GradientEditor({
     onChange({ ...paint, stops: nextStops })
   }
 
-  const startDrag = (index: number, e: ReactPointerEvent<HTMLButtonElement>): void => {
+  const offsetFromClientX = (clientX: number, startOffset: number): number => {
+    const rect = barRef.current?.getBoundingClientRect()
+    if (!rect || rect.width <= 0) return startOffset
+    return Math.min(1, Math.max(0, (clientX - rect.left) / rect.width))
+  }
+
+  // 拖拽会话内可变状态（onMove/onEnd 经 usePointerDrag 的 ref 每次渲染刷新，
+  // 每拖拽会话的 index/起止 offset 存 ref 供闭包读写）
+  const stopDragRef = useRef<{ index: number; startOffset: number; latest: number } | null>(null)
+
+  // document 级指针拖拽生命周期公共底座（pointerId 过滤 + blur 兜底 + 卸载清理：
+  // 拖拽中途面板被卸载时移除监听且不再 commit）
+  const { startDrag: startPointerDrag } = usePointerDrag({
+    onMove: (clientX) => {
+      const drag = stopDragRef.current
+      if (!drag) return
+      drag.latest = offsetFromClientX(clientX, drag.startOffset)
+      emitStops(stops, drag.index, { offset: drag.latest }, true)
+    },
+    onEnd: () => {
+      const drag = stopDragRef.current
+      stopDragRef.current = null
+      if (!drag) return
+      // 无位移的按下-松开只做选中，不入 history
+      if (Math.abs(drag.latest - drag.startOffset) > 1e-6) {
+        emitStops(stops, drag.index, { offset: drag.latest }, false)
+      }
+    },
+  })
+
+  const startDrag = (index: number, e: ReactPointerEvent<HTMLElement>): void => {
     if (mixed || e.button !== 0) return
     setSelected(index)
-    const pointerId = e.pointerId
     const startOffset = stops[index]?.offset ?? 0
-    const offsetFromClientX = (clientX: number): number => {
-      const rect = barRef.current?.getBoundingClientRect()
-      if (!rect || rect.width <= 0) return startOffset
-      return Math.min(1, Math.max(0, (clientX - rect.left) / rect.width))
-    }
-    let latest = offsetFromClientX(e.clientX)
-    const onMove = (ev: PointerEvent): void => {
-      if (ev.pointerId !== pointerId) return
-      latest = offsetFromClientX(ev.clientX)
-      emitStops(stops, index, { offset: latest }, true)
-    }
-    const stop = (): void => {
-      document.removeEventListener("pointermove", onMove)
-      document.removeEventListener("pointerup", onUp)
-      document.removeEventListener("pointercancel", onUp)
-      window.removeEventListener("blur", onBlur)
-      // 无位移的按下-松开只做选中，不入 history
-      if (Math.abs(latest - startOffset) > 1e-6) {
-        emitStops(stops, index, { offset: latest }, false)
-      }
-    }
-    const onUp = (ev: PointerEvent): void => {
-      if (ev.pointerId !== pointerId) return
-      stop()
-    }
-    const onBlur = (): void => stop()
-    document.addEventListener("pointermove", onMove)
-    document.addEventListener("pointerup", onUp)
-    document.addEventListener("pointercancel", onUp)
-    window.addEventListener("blur", onBlur)
+    stopDragRef.current = { index, startOffset, latest: offsetFromClientX(e.clientX, startOffset) }
+    startPointerDrag(e)
   }
 
   const anchor =

package/src/components/design/canvas/panels/controls/number-drag-input.tsx

@@ -5,6 +5,8 @@ import type { KeyboardEvent, PointerEvent as ReactPointerEvent, ReactNode, Wheel
 import { useDebouncedCallback } from "@/lib/pacer"
 import { cn } from "@/lib/utils"
 
+import { usePointerDrag } from "./use-pointer-drag"
+
 // 每移动多少 CSS 像素算作一步：值越小越灵敏
 const DRAG_PX_PER_STEP = 1
 const WHEEL_DEBOUNCE_MS = 400
@@ -206,13 +208,14 @@ export function NumberDragInput({
   const [dragging, setDragging] = useState(false)
   const draftRef = useRef<string>(String(value))
   const prevValue = useRef(value)
-  // 拖拽起点：{ 起始鼠标 x, 起始数值, 指针 id }。用 ref 而非 state，避免 re-render 打断。
-  const dragBase = useRef<{ startX: number; startValue: number; pointerId: number } | null>(null)
+  // 拖拽起点：{ 起始鼠标 x, 起始数值 }。用 ref 而非 state，避免 re-render 打断
+  //（指针 id 过滤由 usePointerDrag 承担）
+  const dragBase = useRef<{ startX: number; startValue: number } | null>(null)
   // rAF 节流：pointermove 每帧可能多次触发，但 onChange 只按渲染帧发一次，
   // 避免上层 pushDoc 排队导致后续事件堆积/丢帧。
   const rafId = useRef<number | null>(null)
   const pendingValue = useRef<number | null>(null)
-  // 稳定化回调，便于 document 监听闭包中调用
+  // 稳定化回调，便于拖拽闭包中调用
   const onChangeRef = useRef(onChange)
   onChangeRef.current = onChange
 
@@ -246,46 +249,13 @@ export function NumberDragInput({
   const wheelState = useRef({ value, draft: draftRef.current, disabled, min, max, step })
   wheelState.current = { value, draft: draftRef.current, disabled, min, max, step }
 
-  const onPointerDown = (e: ReactPointerEvent<HTMLSpanElement>): void => {
-    if (disabled || e.button !== 0) return
-    if (dragBase.current !== null) return // 已有拖拽进行中
-    // 关键：不调用 e.preventDefault()。调用它会阻止后续兼容 mouse 事件派发，
-    // 影响 pointer capture 的隐式释放语义（拖出元素后 pointerup 不一定会派发到该元素）。
-    // 我们改用 document 级 pointer 监听 + 拖中标签内层 select-none，文本选中自然被 CSS 关闭。
-    const startX = e.clientX
-    const startValue = value
-    const pointerId = e.pointerId
-    dragBase.current = { startX, startValue, pointerId }
-    setDragging(true)
-
-    let stopped = false
-    const stop = (): void => {
-      if (stopped) return
-      stopped = true
-      document.removeEventListener("pointermove", docMove)
-      document.removeEventListener("pointerup", docUp)
-      document.removeEventListener("pointercancel", docUp)
-      window.removeEventListener("blur", docBlur)
-      // 拖动结束前 flush 最后一次 pending，再 commit
-      if (rafId.current !== null) {
-        cancelAnimationFrame(rafId.current)
-        rafId.current = null
-      }
-      if (pendingValue.current !== null) {
-        onChangeRef.current?.(pendingValue.current)
-        pendingValue.current = null
-      }
-      dragBase.current = null
-      setDragging(false)
-      const parsed = parseDraft(draftRef.current)
-      if (parsed !== null) commit(parsed)
-    }
-
-    const docMove = (ev: PointerEvent): void => {
-      if (ev.pointerId !== pointerId) return
+  // document 级指针拖拽生命周期公共底座（pointerId 过滤 + blur 兜底 + 卸载清理：
+  // 拖拽中途面板被卸载时移除监听且不再 commit，避免向已卸载组件提交冻结草稿）
+  const { startDrag } = usePointerDrag({
+    onMove: (clientX) => {
       const base = dragBase.current
       if (!base) return
-      const deltaSteps = Math.round((ev.clientX - base.startX) / DRAG_PX_PER_STEP)
+      const deltaSteps = Math.round((clientX - base.startX) / DRAG_PX_PER_STEP)
       const next = clamp(base.startValue + deltaSteps * step, min, max)
       // 立即更新显示，保证丝滑；onChange 走 rAF 节流，避免堆叠
       setDraftValue(String(next))
@@ -299,18 +269,33 @@ export function NumberDragInput({
           }
         })
       }
-    }
-    const docUp = (ev: PointerEvent): void => {
-      if (ev.pointerId !== pointerId) return
-      stop()
-    }
-    // 拖出窗口外释放时 pointerup 可能不触发，用 window blur 兜底
-    const docBlur = (): void => stop()
+    },
+    onEnd: () => {
+      // 拖动结束前 flush 最后一次 pending，再 commit
+      if (rafId.current !== null) {
+        cancelAnimationFrame(rafId.current)
+        rafId.current = null
+      }
+      if (pendingValue.current !== null) {
+        onChangeRef.current?.(pendingValue.current)
+        pendingValue.current = null
+      }
+      dragBase.current = null
+      setDragging(false)
+      const parsed = parseDraft(draftRef.current)
+      if (parsed !== null) commit(parsed)
+    },
+  })
 
-    document.addEventListener("pointermove", docMove)
-    document.addEventListener("pointerup", docUp)
-    document.addEventListener("pointercancel", docUp)
-    window.addEventListener("blur", docBlur)
+  const onPointerDown = (e: ReactPointerEvent<HTMLSpanElement>): void => {
+    if (disabled || e.button !== 0) return
+    if (dragBase.current !== null) return // 已有拖拽进行中
+    // 关键：不调用 e.preventDefault()。调用它会阻止后续兼容 mouse 事件派发，
+    // 影响 pointer capture 的隐式释放语义（拖出元素后 pointerup 不一定会派发到该元素）。
+    // 我们改用 document 级 pointer 监听 + 拖中标签内层 select-none，文本选中自然被 CSS 关闭。
+    dragBase.current = { startX: e.clientX, startValue: value }
+    setDragging(true)
+    startDrag(e)
   }
 
   const onKeyDown = (e: KeyboardEvent<HTMLInputElement>): void => {
@@ -375,7 +360,7 @@ export function NumberDragInput({
     }
   }, [])
 
-  // 卸载时清理 rAF 与拖拽状态
+  // 卸载时清理 rAF（document 拖拽监听由 usePointerDrag 卸载路径统一摘除）
   useEffect(() => {
     return () => {
       if (rafId.current !== null) cancelAnimationFrame(rafId.current)