refactor(core/target-zone): introduce setDispatcherProvider and set default dispatch strategy of TargetZone

Author: coocoodaegap

packages/core/src/entities/TargetZoneCore.ts

@@ -6,6 +6,15 @@ import { clamp, isVec2Equal, percentToPx, pxToPercent } from '../utils/math';
 import { createRafThrottler } from '../runtime/performance';
 import { BaseEntity } from './BaseEntity';
 import { ACTION_TYPES, CMP_TYPES } from '../constants';
+import { DispatcherProvider, getDispatcher } from '../runtime/dispatch';
+
+let _defaultDispatcher: DispatcherProvider | null = null;
+
+const getDefaultDispatcher = () => {
+  if (_defaultDispatcher) return _defaultDispatcher;
+  _defaultDispatcher = getDispatcher() as DispatcherProvider;
+  return _defaultDispatcher;
+};
 
 /**
  * Interface for delegating DOM operations within a target zone.
@@ -45,9 +54,12 @@ export class TargetZoneCore
   private throttledMoveExecution: (payload: any) => void;
 
   private delegates: TargetZoneDelegates = {
-    dispatchKeyboardEvent: () => {},
-    dispatchPointerEventAtPos: () => {},
-    reclaimFocusAtPos: () => {},
+    dispatchKeyboardEvent: (type: string, payload: any) =>
+      getDefaultDispatcher()?.dispatchKeyboard(type, payload),
+    dispatchPointerEventAtPos: (type: string, x: number, y: number, opts: any) =>
+      getDefaultDispatcher()?.dispatchPointerAtPos(type, x, y, opts),
+    reclaimFocusAtPos: (x: number, y: number, callback: () => void) =>
+      getDefaultDispatcher()?.reclaimFocus(x, y, callback),
   };
 
   constructor(uid: string, config: TargetZoneConfig, customTypeName?: EntityType) {

packages/core/src/runtime/dispatch.ts

@@ -0,0 +1,51 @@
+/**
+ * Interface defining the required capabilities for an environment-specific event dispatcher.
+ */
+export interface DispatcherProvider {
+  /**
+   * Simulates a keyboard event in the host environment.
+   *
+   * @param type - The action type (e.g., 'keydown', 'keyup').
+   * @param payload - Keyboard event data containing key, code, and keyCode.
+   */
+  dispatchKeyboard: (type: string, payload: any) => void;
+
+  /**
+   * Simulates a pointer or mouse event at a specific viewport coordinate.
+   *
+   * @param type - The action type (e.g., 'pointerdown', 'pointermove', 'click').
+   * @param x - Absolute viewport X coordinate in pixels.
+   * @param y - Absolute viewport Y coordinate in pixels.
+   * @param opts - Additional pointer event options like buttons or pressure.
+   */
+  dispatchPointerAtPos: (type: string, x: number, y: number, opts: any) => void;
+
+  /**
+   * Reclaims and forces focus back to the interaction target at the specified position.
+   *
+   * @param x - Viewport X coordinate in pixels.
+   * @param y - Viewport Y coordinate in pixels.
+   */
+  reclaimFocus: (x: number, y: number, callback: () => void) => void;
+}
+
+/** Internal storage for the active dispatcher implementation. */
+let _dispatcher: DispatcherProvider | null = null;
+
+/**
+ * Injects a platform-specific dispatcher implementation into the core engine.
+ * This is the bridge that allows the headless core to "hit" the real world.
+ *
+ * @param p - The dispatcher implementation (typically from @omnipad/web).
+ */
+export function setDispatcherProvider(p: DispatcherProvider) {
+  _dispatcher = p;
+}
+
+/**
+ * Retrieves the currently active dispatcher provider.
+ * Returns null if no provider has been injected.
+ *
+ * @internal
+ */
+export const getDispatcher = () => _dispatcher;

packages/core/src/runtime/index.ts

@@ -1,3 +1,4 @@
 export * from './adapter';
-export * from './performance';
-export * from './profile';
+export { setDispatcherProvider } from './dispatch';
+export { setRafProvider, createRafThrottler, createTicker, delayFrames } from './performance';
+export { setSecurityPolicy, validateProfile, parseProfileForest, exportProfile } from './profile';

packages/vue/src/components/TargetZone.vue

@@ -8,13 +8,7 @@ import {
   type LayoutBox,
   type TargetZoneConfig,
 } from '@omnipad/core';
-import { resolveLayoutStyle, projectPercentToBox } from '@omnipad/web';
-import {
-  supportsContainerQueries,
-  dispatchKeyboardEvent,
-  dispatchPointerEventAtPos,
-  reclaimFocusAtPos,
-} from '@omnipad/web';
+import { resolveLayoutStyle, projectPercentToBox, supportsContainerQueries } from '@omnipad/web';
 import { useWidgetSetup } from '../composables/useWidgetSetup';
 
 interface TargetZoneProps {
@@ -44,11 +38,11 @@ const defaultProps = {
 const { uid, core, state, domEvents, effectiveConfig, effectiveLayout, elementRef } =
   useWidgetSetup<TargetZoneCore, CursorState, TargetZoneConfig>(OmniPad.Types.TARGET_ZONE, props, {
     defaultProps,
-    initialDelegates: {
-      dispatchKeyboardEvent: dispatchKeyboardEvent,
-      dispatchPointerEventAtPos: dispatchPointerEventAtPos,
-      reclaimFocusAtPos: reclaimFocusAtPos,
-    },
+    // initialDelegates: {
+    //   dispatchKeyboardEvent: dispatchKeyboardEvent,
+    //   dispatchPointerEventAtPos: dispatchPointerEventAtPos,
+    //   reclaimFocusAtPos: reclaimFocusAtPos,
+    // },
   });
 
 const containerStyle = computed(() => {

packages/web/src/dom/action.ts

@@ -75,7 +75,7 @@ export const dispatchPointerEventAtPos = (
  *
  * @param x - The horizontal coordinate relative to the viewport.
  * @param y - The vertical coordinate relative to the viewport.
- * @returns True if the focus was successfully moved to the target; false if it was already focused or no target found.
+ * @param callback - The function called when the focus is to be reclaimed.
  */
 export const reclaimFocusAtPos = (x: number, y: number, callback: () => void): void => {
   // Find the deepest element at coordinates, penetrating Shadow DOM boundaries

packages/web/src/index.ts

@@ -1,12 +1,13 @@
 import {
   AbstractGamepad,
   OmniPad,
+  setDispatcherProvider,
   setGamepadProvider,
   setGlobalSignalHandler,
   setRafProvider,
   setSecurityPolicy,
 } from '@omnipad/core';
-import { dispatchKeyboardEvent } from './dom/action';
+import { dispatchKeyboardEvent, dispatchPointerEventAtPos, reclaimFocusAtPos } from './dom/action';
 import { sanitizeCssClass, sanitizePrototypePollution } from './ts/security';
 import { validateLayoutBox } from './ts/layout';
 
@@ -17,34 +18,64 @@ export * from './singletons/ElementObserver';
 export * from './singletons/IFrameManager';
 export * from './singletons/WindowManager';
 
+// =============================================================
+// 1. Performance: Heartbeat Synchronization
+// 将核心库的逻辑循环与浏览器的渲染节拍同步
+// =============================================================
 if (typeof window !== 'undefined') {
   setRafProvider(
     window.requestAnimationFrame.bind(window),
     window.cancelAnimationFrame.bind(window),
   );
 }
 
+// =============================================================
+// 2. Dispatcher: Physical Action Execution
+// 注入具体的 DOM 副作用实现，负责将抽象信号转化为真实的浏览器事件
+// =============================================================
+setDispatcherProvider({
+  dispatchKeyboard: dispatchKeyboardEvent,
+  dispatchPointerAtPos: dispatchPointerEventAtPos,
+  reclaimFocus: reclaimFocusAtPos,
+});
+
+// =============================================================
+// 3. Global Signals: Orphaned Signal Recovery
+// 兜底策略：当输入控件没有绑定具体的 TargetZone 时，信号直接打在顶层 window 上
+// =============================================================
 setGlobalSignalHandler((signal) => {
   if (signal.type === OmniPad.ActionTypes.KEYDOWN || signal.type === OmniPad.ActionTypes.KEYUP) {
     dispatchKeyboardEvent(signal.type as any, signal.payload as any);
   }
 });
 
+// =============================================================
+// 4. Gamepad: Hardware Input Polling
+// 注入硬件采集能力。使用固定长度数组作为对象池，减少高频轮询产生的 GC 压力
+// =============================================================
 const gamepadSnapshot: (AbstractGamepad | null)[] = [null, null, null, null];
 
 if (typeof navigator !== 'undefined' && navigator.getGamepads) {
   setGamepadProvider(() => {
     const rawPads = navigator.getGamepads();
+    // 映射原生手柄数据到抽象接口，确保 Core 层平台无关性
+    // Map native gamepad data to abstract interfaces for platform-agnostic core logic
     for (let i = 0; i < 4; i++) {
       gamepadSnapshot[i] = rawPads[i] || null;
     }
     return gamepadSnapshot;
   });
 }
 
+// =============================================================
+// 5. Security: Policy Injection
+// 注入针对 Web 环境的安全校验规则（如 CSS 单位白名单、原型链防护）
+// =============================================================
 setSecurityPolicy({
+  // 过滤非法键名，防止恶意配置篡改运行时原型 / Prevent prototype pollution from malicious JSON
   sanitizeObject: (obj) => sanitizePrototypePollution(obj),
 
+  // 执行业务层面的脱毒，确保布局参数符合浏览器 CSS 标准 / Sanitize business config for CSS standard
   validateConfig: (_, config) => {
     return {
       ...config,