# 七个挂载点

挂载点	触发	推荐责任
js_enter	鼠标移入或触摸按下	创建高亮、提示或轻音
js_leave	移出、松开或取消	清理 enter/move/long 会话
js_press	主指针按下控件	开始跨设备按下反馈
js_release	已按下指针松开或取消	结束按下反馈并清理
js_move	指针按住移动	更新跟手提示或拖拽预览
js_long	达到长按阈值	显示延迟确认或菜单反馈
js_drop	来源在目标区域释放	校验来源并提交一次放置动作

js_enter / js_leave 是 PC hover 语义；移动端为了兼容旧项目，仍会把按下/释放映射给它们。新建跨设备按下反馈应使用 js_press / js_release。一次触摸可能按 enter -> press -> move -> long -> release -> leave 连续触发；这些事件不是互斥按钮。

# 上下文

外层脚本可读取：

• tools.kwargs.itemID、effectTargetId 和实际渲染实例 effectScopedTargetId；
• tools.kwargs.object、objID；
• tools.kwargs.triggerType、pointer、payload 和 isPC；
• 拖放的 source、sourceItemID、sourceObjID 和 dropTarget。

pointer 是可序列化快照，包含相对控件、游戏屏幕和浏览器视口的坐标，以及可用的按键/压力字段。payload 携带 Canvas binding 或其他交互入口的可序列化参数。调试、旧布局和 Canvas 路径提供的上下文并不完全相同，读取前要判断字段存在。

api、target 和 targets 只存在于 runClientEffect 内层字符串，不可在外层直接使用。

# 成对生命周期

js_enter 创建稳定 label：

const label = `hover-` + tools.kwargs.effectTargetId;
tools.runClientEffect(`
  const current = api.getTarget();
  if (!current) return;
  current.setStyle({
    outline: "2px solid rgba(255,255,255,.65)",
    filter: "brightness(1.08)"
  });
`, { label });

js_leave 必须用同一规则清理：

tools.disposeClientEffect(`hover-` + tools.kwargs.effectTargetId);

js_press 创建按下反馈，js_release 使用相同 label 清理。js_move 使用 mode: "update"、稳定 label 和 upsert key，只传最新坐标。js_long 应提供不同于 enter/press 的延迟反馈，并在 release/leave 中清理。

# 手势责任表

需求	所属挂载点	配对清理
桌面 hover 高亮	js_enter	js_leave
跨设备按下状态	js_press	js_release，并由 js_leave 防御清理
跟随指针提示	js_move	js_leave
长按确认反馈	js_long	js_release / js_leave
拖拽预览	来源 press/move	来源 release/leave
业务投放	目标 js_drop	来源表现单独清理

一个挂载点可以同时启动视觉和音频会话，但两者 label 属于不同命名空间。label 应根据触发类型、控件 ID 和对象 ID 稳定构造。

# 拖放事务

const sourceObjID = tools.kwargs.sourceObjID;
const target = tools.kwargs.dropTarget;

if (!sourceObjID || target?.itemID !== "equipment-slot-id") return;

// 查询来源对象、校验槽位，然后在这里提交一次离散动作。

来源控件的 release 负责清理拖动视觉；目标控件的 js_drop 负责验证来源和提交。不要依赖浏览器原生 draggable/drop，也不要在 move 期间提前修改存档。

# 纯 AI 提示词契约

描述桌面和触摸手势、当前控件还是其他目标、对象行身份、label 规则、拖放来源校验、取消行为和清理时机。要求 AI 成对生成 enter/leave 与 move/cleanup。

# 验收

覆盖鼠标进入/离开、触摸按下/取消、快速移动、长按前松开、长按完成、拖到合法/非法目标、对象销毁、页面切换和重复放下。任何取消路径都不留下 DOM、音频或临时状态。

下一步：客户端音频。