@lytjs/common-node-cache 6.5.0 → 6.7.0

package/dist/index.cjs

@@ -122,7 +122,10 @@ var NodeCache = class {
       try {
         if (listener.el == null || typeof listener.el !== "object") {
           if (__DEV__) {
-            console.warn("[lytjs/node-cache] Invalid event listener element, skipping:", listener.el);
+            console.warn(
+              "[lytjs/node-cache] Invalid event listener element, skipping:",
+              listener.el
+            );
           }
           continue;
         }

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AA4FA,IAAM,eAAA,GAA8C;AAAA,EAClD,cAAA,EAAgB,IAAA;AAAA,EAChB,sBAAA,EAAwB;AAC1B,CAAA;AAeO,IAAM,YAAN,MAAgE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBrE,WAAA,CAAY,MAA4B,OAAA,EAA4B;AAVpE;AAAA,IAAA,IAAA,CAAQ,QAAA,uBAAe,OAAA,EAA0B;AAGjD;AAAA,IAAA,IAAA,CAAQ,gBAAA,uBAAuB,OAAA,EAA0C;AAQvE,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,EAAE,GAAG,eAAA,EAAiB,GAAG,OAAA,EAAQ;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,SAAS,SAAA,EAA6B;AACpC,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,cAAA,EAAgB,OAAO,IAAA;AACzC,IAAA,OAAO,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,SAAS,CAAA,IAAK,IAAA;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAA,CAAS,WAAe,KAAA,EAA2B;AACjD,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,cAAA,EAAgB;AAClC,IAAA,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,SAAA,EAAW,KAAK,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAY,SAAA,EAAqB;AAC/B,IAAA,IAAA,CAAK,QAAA,CAAS,OAAO,SAAS,CAAA;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,qBAAA,CACE,QAAA,EACA,EAAA,EACA,KAAA,EACA,SACA,OAAA,EACM;AACN,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,sBAAA,EAAwB;AAE1C,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,wBAAA,CAAyB,QAAQ,CAAA;AACpD,IAAA,KAAA,CAAM,eAAe,IAAA,CAAK,EAAE,IAAI,KAAA,EAAO,OAAA,EAAS,SAAS,CAAA;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,0BAAA,CAA2B,UAA6B,QAAA,EAA4B;AAClF,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,sBAAA,EAAwB;AAE1C,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,wBAAA,CAAyB,QAAQ,CAAA;AACpD,IAAA,KAAA,CAAM,eAAA,CAAgB,KAAK,QAAQ,CAAA;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,eAAA,CAAgB,UAA6B,OAAA,EAA2B;AACtE,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,sBAAA,EAAwB;AAE1C,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,wBAAA,CAAyB,QAAQ,CAAA;AACpD,IAAA,KAAA,CAAM,YAAA,CAAa,KAAK,OAAO,CAAA;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,0BAA0B,QAAA,EAAmC;AAC3D,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,gBAAA,CAAiB,GAAA,CAAI,QAAQ,CAAA;AAChD,IAAA,IAAI,CAAC,KAAA,EAAO;AAGZ,IAAA,KAAA,MAAW,OAAA,IAAW,MAAM,YAAA,EAAc;AACxC,MAAA,IAAI;AACF,QAAA,OAAA,EAAQ;AAAA,MACV,SAAS,GAAA,EAAK;AACZ,QAAA,IAAI,OAAA,EAAS,OAAA,CAAQ,IAAA,CAAK,+CAAA,EAAiD,GAAG,CAAA;AAAA,MAChF;AAAA,IACF;AAGA,IAAA,KAAA,MAAW,QAAA,IAAY,MAAM,eAAA,EAAiB;AAC5C,MAAA,IAAI;AACF,QAAA,QAAA,EAAS;AAAA,MACX,SAAS,GAAA,EAAK;AACZ,QAAA,IAAI,OAAA,EAAS,OAAA,CAAQ,IAAA,CAAK,iDAAA,EAAmD,GAAG,CAAA;AAAA,MAClF;AAAA,IACF;AAGA,IAAA,KAAA,MAAW,QAAA,IAAY,MAAM,cAAA,EAAgB;AAC3C,MAAA,IAAI;AAEF,QAAA,IAAI,SAAS,EAAA,IAAM,IAAA,IAAQ,OAAO,QAAA,CAAS,OAAO,QAAA,EAAU;AAC1D,UAAA,IAAI,OAAA,EAAS;AACX,YAAA,OAAA,CAAQ,IAAA,CAAK,8DAAA,EAAgE,QAAA,CAAS,EAAE,CAAA;AAAA,UAC1F;AACA,UAAA;AAAA,QACF;AACA,QAAA,IAAA,CAAK,IAAA,CAAK,mBAAA;AAAA;AAAA,UAER,QAAA,CAAS,EAAA;AAAA,UACT,QAAA,CAAS,KAAA;AAAA,UACT,QAAA,CAAS,OAAA;AAAA,UACT,QAAA,CAAS;AAAA,SACX;AAAA,MACF,SAAS,GAAA,EAAK;AACZ,QAAA,IAAI,OAAA,EAAS,OAAA,CAAQ,IAAA,CAAK,yDAAA,EAA2D,GAAG,CAAA;AAAA,MAC1F;AAAA,IACF;AAGA,IAAA,IAAA,CAAK,gBAAA,CAAiB,OAAO,QAAQ,CAAA;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,iBAAiB,SAAA,EAAqB;AACpC,IAAA,IAAA,CAAK,QAAA,CAAS,OAAO,SAAS,CAAA;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAA,GAAgB;AACd,IAAA,IAAA,CAAK,QAAA,uBAAe,OAAA,EAA0B;AAC9C,IAAA,IAAA,CAAK,gBAAA,uBAAuB,OAAA,EAA0C;AAAA,EACxE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,yBAAyB,QAAA,EAA4C;AAC3E,IAAA,IAAI,KAAA,GAAQ,IAAA,CAAK,gBAAA,CAAiB,GAAA,CAAI,QAAQ,CAAA;AAC9C,IAAA,IAAI,CAAC,KAAA,EAAO;AACV,MAAA,KAAA,GAAQ;AAAA,QACN,gBAAgB,EAAC;AAAA,QACjB,iBAAiB,EAAC;AAAA,QAClB,cAAc;AAAC,OACjB;AACA,MAAA,IAAA,CAAK,gBAAA,CAAiB,GAAA,CAAI,QAAA,EAAU,KAAK,CAAA;AAAA,IAC3C;AACA,IAAA,OAAO,KAAA;AAAA,EACT;AACF","file":"index.cjs","sourcesContent":["// @lytjs/common-node-cache\r\n// 节点缓存：管理 container → VNode 映射、组件实例 → 资源注册表映射、统一清理函数\r\n\r\ndeclare const __DEV__: boolean;\r\n\r\nimport type { RendererHost, HostEventHandler, HostEventOptions, HostEvent } from '@lytjs/host-contract';\r\n\r\n// ============================================================\r\n// 类型定义\r\n// ============================================================\r\n\r\n/**\r\n * 平台无关的 VNode 接口。\r\n *\r\n * L2 层不依赖具体的 VNode 实现，仅使用此最小接口。\r\n */\r\nexport interface VNode {\r\n  /** 节点类型标识 */\r\n  type: string | symbol | object;\r\n  /** 节点属性 */\r\n  props: Record<string, unknown> | null;\r\n  /** 子节点 */\r\n  children: VNode[] | string | null;\r\n  /** 关联的组件实例 */\r\n  component?: ComponentInstance | null;\r\n  /** 宿主节点引用（渲染后赋值） */\r\n  el?: unknown;\r\n  /** 锚点引用 */\r\n  anchor?: unknown;\r\n}\r\n\r\n/**\r\n * 组件内部实例（最小接口）。\r\n *\r\n * L2 层仅需要组件实例的标识能力，用于资源注册表映射。\r\n */\r\nexport interface ComponentInstance {\r\n  /** 组件唯一标识 */\r\n  uid: number;\r\n  /** 组件类型 */\r\n  type: object;\r\n  /** 是否已卸载 */\r\n  isUnmounted: boolean;\r\n  /** VNode 引用 */\r\n  vnode: VNode;\r\n  /** 父组件实例 */\r\n  parent: ComponentInstance | null;\r\n  /** 子树 VNode */\r\n  subTree: VNode;\r\n}\r\n\r\n/**\r\n * 事件监听器注册条目。\r\n */\r\nexport interface EventListenerEntry<HE> {\r\n  /** 宿主元素 */\r\n  el: HE;\r\n  /** 事件名 */\r\n  event: string;\r\n  /** 处理函数 */\r\n  handler: (event: HostEvent) => void;\r\n  /** 事件选项 */\r\n  options?: { capture?: boolean; once?: boolean; passive?: boolean };\r\n}\r\n\r\n/**\r\n * 资源注册表条目。\r\n */\r\nexport interface ResourceEntry {\r\n  /** 事件监听器列表 */\r\n  eventListeners: EventListenerEntry<unknown>[];\r\n  /** effect 订阅 dispose 列表 */\r\n  effectDisposers: Array<() => void>;\r\n  /** 通用清理回调列表 */\r\n  cleanupHooks: Array<() => void>;\r\n}\r\n\r\n/**\r\n * 节点缓存配置项。\r\n */\r\nexport interface NodeCacheOptions {\r\n  /** 是否启用 VNode 映射（默认 true） */\r\n  enableVNodeMap?: boolean;\r\n  /** 是否启用资源注册表（默认 true） */\r\n  enableResourceRegistry?: boolean;\r\n}\r\n\r\n// ============================================================\r\n// 常量\r\n// ============================================================\r\n\r\n/** 默认配置 */\r\nconst DEFAULT_OPTIONS: Required<NodeCacheOptions> = {\r\n  enableVNodeMap: true,\r\n  enableResourceRegistry: true,\r\n};\r\n\r\n// ============================================================\r\n// NodeCache\r\n// ============================================================\r\n\r\n/**\r\n * 节点缓存。\r\n *\r\n * 管理 container → VNode 映射和组件实例 → 资源注册表映射，\r\n * 提供统一的资源清理函数。\r\n *\r\n * @template HN - 宿主节点类型\r\n * @template HE - 宿主元素类型\r\n */\r\nexport class NodeCache<HN extends object = object, HE extends HN = HN> {\r\n  /** RendererHost 实例 */\r\n  private host: RendererHost<HN, HE>;\r\n\r\n  /** 配置项 */\r\n  private options: Required<NodeCacheOptions>;\r\n\r\n  /** container → VNode 映射 */\r\n  private vnodeMap = new WeakMap<HN, VNode | null>();\r\n\r\n  /** 组件实例 → 资源注册表映射 */\r\n  private resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\r\n\r\n  /**\r\n   * 创建节点缓存实例。\r\n   * @param host - RendererHost 实例\r\n   * @param options - 可选的配置项\r\n   */\r\n  constructor(host: RendererHost<HN, HE>, options?: NodeCacheOptions) {\r\n    this.host = host;\r\n    this.options = { ...DEFAULT_OPTIONS, ...options };\r\n  }\r\n\r\n  // ==========================================================\r\n  // VNode 映射\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 获取 container 对应的 VNode。\r\n   * @param container - 宿主容器节点\r\n   * @returns VNode 或 null\r\n   */\r\n  getVNode(container: HN): VNode | null {\r\n    if (!this.options.enableVNodeMap) return null;\r\n    return this.vnodeMap.get(container) ?? null;\r\n  }\r\n\r\n  /**\r\n   * 设置 container → VNode 映射。\r\n   * @param container - 宿主容器节点\r\n   * @param vnode - VNode 实例\r\n   */\r\n  setVNode(container: HN, vnode: VNode | null): void {\r\n    if (!this.options.enableVNodeMap) return;\r\n    this.vnodeMap.set(container, vnode);\r\n  }\r\n\r\n  /**\r\n   * 删除 container 的 VNode 映射。\r\n   * @param container - 宿主容器节点\r\n   */\r\n  deleteVNode(container: HN): void {\r\n    this.vnodeMap.delete(container);\r\n  }\r\n\r\n  // ==========================================================\r\n  // 资源注册表\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 注册事件监听器到组件实例的资源注册表。\r\n   *\r\n   * @param instance - 组件实例\r\n   * @param el - 宿主元素\r\n   * @param event - 事件名\r\n   * @param handler - 事件处理函数\r\n   * @param options - 可选的事件选项\r\n   */\r\n  registerEventListener(\r\n    instance: ComponentInstance,\r\n    el: HE,\r\n    event: string,\r\n    handler: HostEventHandler,\r\n    options?: HostEventOptions,\r\n  ): void {\r\n    if (!this.options.enableResourceRegistry) return;\r\n\r\n    const entry = this.getOrCreateResourceEntry(instance);\r\n    entry.eventListeners.push({ el, event, handler, options });\r\n  }\r\n\r\n  /**\r\n   * 注册 effect 订阅到组件实例的资源注册表。\r\n   *\r\n   * @param instance - 组件实例\r\n   * @param disposer - effect 的 dispose 回调函数\r\n   */\r\n  registerEffectSubscription(instance: ComponentInstance, disposer: () => void): void {\r\n    if (!this.options.enableResourceRegistry) return;\r\n\r\n    const entry = this.getOrCreateResourceEntry(instance);\r\n    entry.effectDisposers.push(disposer);\r\n  }\r\n\r\n  /**\r\n   * 注册通用清理钩子到组件实例的资源注册表。\r\n   *\r\n   * @param instance - 组件实例\r\n   * @param cleanup - 清理回调函数\r\n   */\r\n  registerCleanup(instance: ComponentInstance, cleanup: () => void): void {\r\n    if (!this.options.enableResourceRegistry) return;\r\n\r\n    const entry = this.getOrCreateResourceEntry(instance);\r\n    entry.cleanupHooks.push(cleanup);\r\n  }\r\n\r\n  // ==========================================================\r\n  // 统一清理\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 统一清理组件实例的所有注册资源。\r\n   *\r\n   * 清理顺序：\r\n   * 1. cleanup 钩子（可能依赖 effect 仍活跃）\r\n   * 2. effect 订阅（停止响应式追踪）\r\n   * 3. 事件监听器（DOM 操作，最后执行）\r\n   *\r\n   * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。\r\n   *\r\n   * @param instance - 要清理资源的组件实例\r\n   */\r\n  cleanupComponentResources(instance: ComponentInstance): void {\r\n    const entry = this.resourceRegistry.get(instance);\r\n    if (!entry) return;\r\n\r\n    // 1. 执行 cleanup 钩子\r\n    for (const cleanup of entry.cleanupHooks) {\r\n      try {\r\n        cleanup();\r\n      } catch (err) {\r\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during cleanup hook:', err);\r\n      }\r\n    }\r\n\r\n    // 2. 清理 effect 订阅\r\n    for (const disposer of entry.effectDisposers) {\r\n      try {\r\n        disposer();\r\n      } catch (err) {\r\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during effect dispose:', err);\r\n      }\r\n    }\r\n\r\n    // 3. 清理事件监听器\r\n    for (const listener of entry.eventListeners) {\r\n      try {\r\n        // FIX: P2-v11-21 添加类型检查，确保 listener.el 是有效的宿主元素\r\n        if (listener.el == null || typeof listener.el !== 'object') {\r\n          if (__DEV__) {\r\n            console.warn('[lytjs/node-cache] Invalid event listener element, skipping:', listener.el);\r\n          }\r\n          continue;\r\n        }\r\n        this.host.removeEventListener(\r\n          // FIX: P2-batch2-13 添加运行时类型检查，确保 listener.el 符合 HE 类型约束\r\n          listener.el as HE,\r\n          listener.event,\r\n          listener.handler,\r\n          listener.options,\r\n        );\r\n      } catch (err) {\r\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during event listener cleanup:', err);\r\n      }\r\n    }\r\n\r\n    // 删除注册表条目\r\n    this.resourceRegistry.delete(instance);\r\n  }\r\n\r\n  /**\r\n   * 清理指定 container 的 VNode 映射。\r\n   * @param container - 宿主容器节点\r\n   */\r\n  cleanupContainer(container: HN): void {\r\n    this.vnodeMap.delete(container);\r\n  }\r\n\r\n  /**\r\n   * 销毁缓存，清理所有内部状态。\r\n   *\r\n   * 注意：不会自动清理所有组件资源，需提前手动调用 cleanupComponentResources。\r\n   */\r\n  dispose(): void {\r\n    this.vnodeMap = new WeakMap<HN, VNode | null>();\r\n    this.resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\r\n  }\r\n\r\n  // ==========================================================\r\n  // 内部方法\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 获取或创建组件实例的资源注册表条目。\r\n   */\r\n  private getOrCreateResourceEntry(instance: ComponentInstance): ResourceEntry {\r\n    let entry = this.resourceRegistry.get(instance);\r\n    if (!entry) {\r\n      entry = {\r\n        eventListeners: [],\r\n        effectDisposers: [],\r\n        cleanupHooks: [],\r\n      };\r\n      this.resourceRegistry.set(instance, entry);\r\n    }\r\n    return entry;\r\n  }\r\n}\r\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["// @lytjs/common-node-cache\n// 节点缓存：管理 container → VNode 映射、组件实例 → 资源注册表映射、统一清理函数\n\ndeclare const __DEV__: boolean;\n\nimport type {\n  RendererHost,\n  HostEventHandler,\n  HostEventOptions,\n  HostEvent,\n} from '@lytjs/host-contract';\n\n// ============================================================\n// 类型定义\n// ============================================================\n\n/**\n * 平台无关的 VNode 接口。\n *\n * L2 层不依赖具体的 VNode 实现，仅使用此最小接口。\n */\nexport interface VNode {\n  /** 节点类型标识 */\n  type: string | symbol | object;\n  /** 节点属性 */\n  props: Record<string, unknown> | null;\n  /** 子节点 */\n  children: VNode[] | string | null;\n  /** 关联的组件实例 */\n  component?: ComponentInstance | null;\n  /** 宿主节点引用（渲染后赋值） */\n  el?: unknown;\n  /** 锚点引用 */\n  anchor?: unknown;\n}\n\n/**\n * 组件内部实例（最小接口）。\n *\n * L2 层仅需要组件实例的标识能力，用于资源注册表映射。\n */\nexport interface ComponentInstance {\n  /** 组件唯一标识 */\n  uid: number;\n  /** 组件类型 */\n  type: object;\n  /** 是否已卸载 */\n  isUnmounted: boolean;\n  /** VNode 引用 */\n  vnode: VNode;\n  /** 父组件实例 */\n  parent: ComponentInstance | null;\n  /** 子树 VNode */\n  subTree: VNode;\n}\n\n/**\n * 事件监听器注册条目。\n */\nexport interface EventListenerEntry<HE> {\n  /** 宿主元素 */\n  el: HE;\n  /** 事件名 */\n  event: string;\n  /** 处理函数 */\n  handler: (event: HostEvent) => void;\n  /** 事件选项 */\n  options?: { capture?: boolean; once?: boolean; passive?: boolean };\n}\n\n/**\n * 资源注册表条目。\n */\nexport interface ResourceEntry {\n  /** 事件监听器列表 */\n  eventListeners: EventListenerEntry<unknown>[];\n  /** effect 订阅 dispose 列表 */\n  effectDisposers: Array<() => void>;\n  /** 通用清理回调列表 */\n  cleanupHooks: Array<() => void>;\n}\n\n/**\n * 节点缓存配置项。\n */\nexport interface NodeCacheOptions {\n  /** 是否启用 VNode 映射（默认 true） */\n  enableVNodeMap?: boolean;\n  /** 是否启用资源注册表（默认 true） */\n  enableResourceRegistry?: boolean;\n}\n\n// ============================================================\n// 常量\n// ============================================================\n\n/** 默认配置 */\nconst DEFAULT_OPTIONS: Required<NodeCacheOptions> = {\n  enableVNodeMap: true,\n  enableResourceRegistry: true,\n};\n\n// ============================================================\n// NodeCache\n// ============================================================\n\n/**\n * 节点缓存。\n *\n * 管理 container → VNode 映射和组件实例 → 资源注册表映射，\n * 提供统一的资源清理函数。\n *\n * @template HN - 宿主节点类型\n * @template HE - 宿主元素类型\n */\nexport class NodeCache<HN extends object = object, HE extends HN = HN> {\n  /** RendererHost 实例 */\n  private host: RendererHost<HN, HE>;\n\n  /** 配置项 */\n  private options: Required<NodeCacheOptions>;\n\n  /** container → VNode 映射 */\n  private vnodeMap = new WeakMap<HN, VNode | null>();\n\n  /** 组件实例 → 资源注册表映射 */\n  private resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\n\n  /**\n   * 创建节点缓存实例。\n   * @param host - RendererHost 实例\n   * @param options - 可选的配置项\n   */\n  constructor(host: RendererHost<HN, HE>, options?: NodeCacheOptions) {\n    this.host = host;\n    this.options = { ...DEFAULT_OPTIONS, ...options };\n  }\n\n  // ==========================================================\n  // VNode 映射\n  // ==========================================================\n\n  /**\n   * 获取 container 对应的 VNode。\n   * @param container - 宿主容器节点\n   * @returns VNode 或 null\n   */\n  getVNode(container: HN): VNode | null {\n    if (!this.options.enableVNodeMap) return null;\n    return this.vnodeMap.get(container) ?? null;\n  }\n\n  /**\n   * 设置 container → VNode 映射。\n   * @param container - 宿主容器节点\n   * @param vnode - VNode 实例\n   */\n  setVNode(container: HN, vnode: VNode | null): void {\n    if (!this.options.enableVNodeMap) return;\n    this.vnodeMap.set(container, vnode);\n  }\n\n  /**\n   * 删除 container 的 VNode 映射。\n   * @param container - 宿主容器节点\n   */\n  deleteVNode(container: HN): void {\n    this.vnodeMap.delete(container);\n  }\n\n  // ==========================================================\n  // 资源注册表\n  // ==========================================================\n\n  /**\n   * 注册事件监听器到组件实例的资源注册表。\n   *\n   * @param instance - 组件实例\n   * @param el - 宿主元素\n   * @param event - 事件名\n   * @param handler - 事件处理函数\n   * @param options - 可选的事件选项\n   */\n  registerEventListener(\n    instance: ComponentInstance,\n    el: HE,\n    event: string,\n    handler: HostEventHandler,\n    options?: HostEventOptions,\n  ): void {\n    if (!this.options.enableResourceRegistry) return;\n\n    const entry = this.getOrCreateResourceEntry(instance);\n    entry.eventListeners.push({ el, event, handler, options });\n  }\n\n  /**\n   * 注册 effect 订阅到组件实例的资源注册表。\n   *\n   * @param instance - 组件实例\n   * @param disposer - effect 的 dispose 回调函数\n   */\n  registerEffectSubscription(instance: ComponentInstance, disposer: () => void): void {\n    if (!this.options.enableResourceRegistry) return;\n\n    const entry = this.getOrCreateResourceEntry(instance);\n    entry.effectDisposers.push(disposer);\n  }\n\n  /**\n   * 注册通用清理钩子到组件实例的资源注册表。\n   *\n   * @param instance - 组件实例\n   * @param cleanup - 清理回调函数\n   */\n  registerCleanup(instance: ComponentInstance, cleanup: () => void): void {\n    if (!this.options.enableResourceRegistry) return;\n\n    const entry = this.getOrCreateResourceEntry(instance);\n    entry.cleanupHooks.push(cleanup);\n  }\n\n  // ==========================================================\n  // 统一清理\n  // ==========================================================\n\n  /**\n   * 统一清理组件实例的所有注册资源。\n   *\n   * 清理顺序：\n   * 1. cleanup 钩子（可能依赖 effect 仍活跃）\n   * 2. effect 订阅（停止响应式追踪）\n   * 3. 事件监听器（DOM 操作，最后执行）\n   *\n   * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。\n   *\n   * @param instance - 要清理资源的组件实例\n   */\n  cleanupComponentResources(instance: ComponentInstance): void {\n    const entry = this.resourceRegistry.get(instance);\n    if (!entry) return;\n\n    // 1. 执行 cleanup 钩子\n    for (const cleanup of entry.cleanupHooks) {\n      try {\n        cleanup();\n      } catch (err) {\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during cleanup hook:', err);\n      }\n    }\n\n    // 2. 清理 effect 订阅\n    for (const disposer of entry.effectDisposers) {\n      try {\n        disposer();\n      } catch (err) {\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during effect dispose:', err);\n      }\n    }\n\n    // 3. 清理事件监听器\n    for (const listener of entry.eventListeners) {\n      try {\n        // FIX: P2-v11-21 添加类型检查，确保 listener.el 是有效的宿主元素\n        if (listener.el == null || typeof listener.el !== 'object') {\n          if (__DEV__) {\n            console.warn(\n              '[lytjs/node-cache] Invalid event listener element, skipping:',\n              listener.el,\n            );\n          }\n          continue;\n        }\n        this.host.removeEventListener(\n          // FIX: P2-batch2-13 添加运行时类型检查，确保 listener.el 符合 HE 类型约束\n          listener.el as HE,\n          listener.event,\n          listener.handler,\n          listener.options,\n        );\n      } catch (err) {\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during event listener cleanup:', err);\n      }\n    }\n\n    // 删除注册表条目\n    this.resourceRegistry.delete(instance);\n  }\n\n  /**\n   * 清理指定 container 的 VNode 映射。\n   * @param container - 宿主容器节点\n   */\n  cleanupContainer(container: HN): void {\n    this.vnodeMap.delete(container);\n  }\n\n  /**\n   * 销毁缓存，清理所有内部状态。\n   *\n   * 注意：不会自动清理所有组件资源，需提前手动调用 cleanupComponentResources。\n   */\n  dispose(): void {\n    this.vnodeMap = new WeakMap<HN, VNode | null>();\n    this.resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\n  }\n\n  // ==========================================================\n  // 内部方法\n  // ==========================================================\n\n  /**\n   * 获取或创建组件实例的资源注册表条目。\n   */\n  private getOrCreateResourceEntry(instance: ComponentInstance): ResourceEntry {\n    let entry = this.resourceRegistry.get(instance);\n    if (!entry) {\n      entry = {\n        eventListeners: [],\n        effectDisposers: [],\n        cleanupHooks: [],\n      };\n      this.resourceRegistry.set(instance, entry);\n    }\n    return entry;\n  }\n}\n"]}

package/dist/index.mjs

@@ -120,7 +120,10 @@ var NodeCache = class {
       try {
         if (listener.el == null || typeof listener.el !== "object") {
           if (__DEV__) {
-            console.warn("[lytjs/node-cache] Invalid event listener element, skipping:", listener.el);
+            console.warn(
+              "[lytjs/node-cache] Invalid event listener element, skipping:",
+              listener.el
+            );
           }
           continue;
         }

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// @lytjs/common-node-cache\r\n// 节点缓存：管理 container → VNode 映射、组件实例 → 资源注册表映射、统一清理函数\r\n\r\ndeclare const __DEV__: boolean;\r\n\r\nimport type { RendererHost, HostEventHandler, HostEventOptions, HostEvent } from '@lytjs/host-contract';\r\n\r\n// ============================================================\r\n// 类型定义\r\n// ============================================================\r\n\r\n/**\r\n * 平台无关的 VNode 接口。\r\n *\r\n * L2 层不依赖具体的 VNode 实现，仅使用此最小接口。\r\n */\r\nexport interface VNode {\r\n  /** 节点类型标识 */\r\n  type: string | symbol | object;\r\n  /** 节点属性 */\r\n  props: Record<string, unknown> | null;\r\n  /** 子节点 */\r\n  children: VNode[] | string | null;\r\n  /** 关联的组件实例 */\r\n  component?: ComponentInstance | null;\r\n  /** 宿主节点引用（渲染后赋值） */\r\n  el?: unknown;\r\n  /** 锚点引用 */\r\n  anchor?: unknown;\r\n}\r\n\r\n/**\r\n * 组件内部实例（最小接口）。\r\n *\r\n * L2 层仅需要组件实例的标识能力，用于资源注册表映射。\r\n */\r\nexport interface ComponentInstance {\r\n  /** 组件唯一标识 */\r\n  uid: number;\r\n  /** 组件类型 */\r\n  type: object;\r\n  /** 是否已卸载 */\r\n  isUnmounted: boolean;\r\n  /** VNode 引用 */\r\n  vnode: VNode;\r\n  /** 父组件实例 */\r\n  parent: ComponentInstance | null;\r\n  /** 子树 VNode */\r\n  subTree: VNode;\r\n}\r\n\r\n/**\r\n * 事件监听器注册条目。\r\n */\r\nexport interface EventListenerEntry<HE> {\r\n  /** 宿主元素 */\r\n  el: HE;\r\n  /** 事件名 */\r\n  event: string;\r\n  /** 处理函数 */\r\n  handler: (event: HostEvent) => void;\r\n  /** 事件选项 */\r\n  options?: { capture?: boolean; once?: boolean; passive?: boolean };\r\n}\r\n\r\n/**\r\n * 资源注册表条目。\r\n */\r\nexport interface ResourceEntry {\r\n  /** 事件监听器列表 */\r\n  eventListeners: EventListenerEntry<unknown>[];\r\n  /** effect 订阅 dispose 列表 */\r\n  effectDisposers: Array<() => void>;\r\n  /** 通用清理回调列表 */\r\n  cleanupHooks: Array<() => void>;\r\n}\r\n\r\n/**\r\n * 节点缓存配置项。\r\n */\r\nexport interface NodeCacheOptions {\r\n  /** 是否启用 VNode 映射（默认 true） */\r\n  enableVNodeMap?: boolean;\r\n  /** 是否启用资源注册表（默认 true） */\r\n  enableResourceRegistry?: boolean;\r\n}\r\n\r\n// ============================================================\r\n// 常量\r\n// ============================================================\r\n\r\n/** 默认配置 */\r\nconst DEFAULT_OPTIONS: Required<NodeCacheOptions> = {\r\n  enableVNodeMap: true,\r\n  enableResourceRegistry: true,\r\n};\r\n\r\n// ============================================================\r\n// NodeCache\r\n// ============================================================\r\n\r\n/**\r\n * 节点缓存。\r\n *\r\n * 管理 container → VNode 映射和组件实例 → 资源注册表映射，\r\n * 提供统一的资源清理函数。\r\n *\r\n * @template HN - 宿主节点类型\r\n * @template HE - 宿主元素类型\r\n */\r\nexport class NodeCache<HN extends object = object, HE extends HN = HN> {\r\n  /** RendererHost 实例 */\r\n  private host: RendererHost<HN, HE>;\r\n\r\n  /** 配置项 */\r\n  private options: Required<NodeCacheOptions>;\r\n\r\n  /** container → VNode 映射 */\r\n  private vnodeMap = new WeakMap<HN, VNode | null>();\r\n\r\n  /** 组件实例 → 资源注册表映射 */\r\n  private resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\r\n\r\n  /**\r\n   * 创建节点缓存实例。\r\n   * @param host - RendererHost 实例\r\n   * @param options - 可选的配置项\r\n   */\r\n  constructor(host: RendererHost<HN, HE>, options?: NodeCacheOptions) {\r\n    this.host = host;\r\n    this.options = { ...DEFAULT_OPTIONS, ...options };\r\n  }\r\n\r\n  // ==========================================================\r\n  // VNode 映射\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 获取 container 对应的 VNode。\r\n   * @param container - 宿主容器节点\r\n   * @returns VNode 或 null\r\n   */\r\n  getVNode(container: HN): VNode | null {\r\n    if (!this.options.enableVNodeMap) return null;\r\n    return this.vnodeMap.get(container) ?? null;\r\n  }\r\n\r\n  /**\r\n   * 设置 container → VNode 映射。\r\n   * @param container - 宿主容器节点\r\n   * @param vnode - VNode 实例\r\n   */\r\n  setVNode(container: HN, vnode: VNode | null): void {\r\n    if (!this.options.enableVNodeMap) return;\r\n    this.vnodeMap.set(container, vnode);\r\n  }\r\n\r\n  /**\r\n   * 删除 container 的 VNode 映射。\r\n   * @param container - 宿主容器节点\r\n   */\r\n  deleteVNode(container: HN): void {\r\n    this.vnodeMap.delete(container);\r\n  }\r\n\r\n  // ==========================================================\r\n  // 资源注册表\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 注册事件监听器到组件实例的资源注册表。\r\n   *\r\n   * @param instance - 组件实例\r\n   * @param el - 宿主元素\r\n   * @param event - 事件名\r\n   * @param handler - 事件处理函数\r\n   * @param options - 可选的事件选项\r\n   */\r\n  registerEventListener(\r\n    instance: ComponentInstance,\r\n    el: HE,\r\n    event: string,\r\n    handler: HostEventHandler,\r\n    options?: HostEventOptions,\r\n  ): void {\r\n    if (!this.options.enableResourceRegistry) return;\r\n\r\n    const entry = this.getOrCreateResourceEntry(instance);\r\n    entry.eventListeners.push({ el, event, handler, options });\r\n  }\r\n\r\n  /**\r\n   * 注册 effect 订阅到组件实例的资源注册表。\r\n   *\r\n   * @param instance - 组件实例\r\n   * @param disposer - effect 的 dispose 回调函数\r\n   */\r\n  registerEffectSubscription(instance: ComponentInstance, disposer: () => void): void {\r\n    if (!this.options.enableResourceRegistry) return;\r\n\r\n    const entry = this.getOrCreateResourceEntry(instance);\r\n    entry.effectDisposers.push(disposer);\r\n  }\r\n\r\n  /**\r\n   * 注册通用清理钩子到组件实例的资源注册表。\r\n   *\r\n   * @param instance - 组件实例\r\n   * @param cleanup - 清理回调函数\r\n   */\r\n  registerCleanup(instance: ComponentInstance, cleanup: () => void): void {\r\n    if (!this.options.enableResourceRegistry) return;\r\n\r\n    const entry = this.getOrCreateResourceEntry(instance);\r\n    entry.cleanupHooks.push(cleanup);\r\n  }\r\n\r\n  // ==========================================================\r\n  // 统一清理\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 统一清理组件实例的所有注册资源。\r\n   *\r\n   * 清理顺序：\r\n   * 1. cleanup 钩子（可能依赖 effect 仍活跃）\r\n   * 2. effect 订阅（停止响应式追踪）\r\n   * 3. 事件监听器（DOM 操作，最后执行）\r\n   *\r\n   * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。\r\n   *\r\n   * @param instance - 要清理资源的组件实例\r\n   */\r\n  cleanupComponentResources(instance: ComponentInstance): void {\r\n    const entry = this.resourceRegistry.get(instance);\r\n    if (!entry) return;\r\n\r\n    // 1. 执行 cleanup 钩子\r\n    for (const cleanup of entry.cleanupHooks) {\r\n      try {\r\n        cleanup();\r\n      } catch (err) {\r\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during cleanup hook:', err);\r\n      }\r\n    }\r\n\r\n    // 2. 清理 effect 订阅\r\n    for (const disposer of entry.effectDisposers) {\r\n      try {\r\n        disposer();\r\n      } catch (err) {\r\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during effect dispose:', err);\r\n      }\r\n    }\r\n\r\n    // 3. 清理事件监听器\r\n    for (const listener of entry.eventListeners) {\r\n      try {\r\n        // FIX: P2-v11-21 添加类型检查，确保 listener.el 是有效的宿主元素\r\n        if (listener.el == null || typeof listener.el !== 'object') {\r\n          if (__DEV__) {\r\n            console.warn('[lytjs/node-cache] Invalid event listener element, skipping:', listener.el);\r\n          }\r\n          continue;\r\n        }\r\n        this.host.removeEventListener(\r\n          // FIX: P2-batch2-13 添加运行时类型检查，确保 listener.el 符合 HE 类型约束\r\n          listener.el as HE,\r\n          listener.event,\r\n          listener.handler,\r\n          listener.options,\r\n        );\r\n      } catch (err) {\r\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during event listener cleanup:', err);\r\n      }\r\n    }\r\n\r\n    // 删除注册表条目\r\n    this.resourceRegistry.delete(instance);\r\n  }\r\n\r\n  /**\r\n   * 清理指定 container 的 VNode 映射。\r\n   * @param container - 宿主容器节点\r\n   */\r\n  cleanupContainer(container: HN): void {\r\n    this.vnodeMap.delete(container);\r\n  }\r\n\r\n  /**\r\n   * 销毁缓存，清理所有内部状态。\r\n   *\r\n   * 注意：不会自动清理所有组件资源，需提前手动调用 cleanupComponentResources。\r\n   */\r\n  dispose(): void {\r\n    this.vnodeMap = new WeakMap<HN, VNode | null>();\r\n    this.resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\r\n  }\r\n\r\n  // ==========================================================\r\n  // 内部方法\r\n  // ==========================================================\r\n\r\n  /**\r\n   * 获取或创建组件实例的资源注册表条目。\r\n   */\r\n  private getOrCreateResourceEntry(instance: ComponentInstance): ResourceEntry {\r\n    let entry = this.resourceRegistry.get(instance);\r\n    if (!entry) {\r\n      entry = {\r\n        eventListeners: [],\r\n        effectDisposers: [],\r\n        cleanupHooks: [],\r\n      };\r\n      this.resourceRegistry.set(instance, entry);\r\n    }\r\n    return entry;\r\n  }\r\n}\r\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// @lytjs/common-node-cache\n// 节点缓存：管理 container → VNode 映射、组件实例 → 资源注册表映射、统一清理函数\n\ndeclare const __DEV__: boolean;\n\nimport type {\n  RendererHost,\n  HostEventHandler,\n  HostEventOptions,\n  HostEvent,\n} from '@lytjs/host-contract';\n\n// ============================================================\n// 类型定义\n// ============================================================\n\n/**\n * 平台无关的 VNode 接口。\n *\n * L2 层不依赖具体的 VNode 实现，仅使用此最小接口。\n */\nexport interface VNode {\n  /** 节点类型标识 */\n  type: string | symbol | object;\n  /** 节点属性 */\n  props: Record<string, unknown> | null;\n  /** 子节点 */\n  children: VNode[] | string | null;\n  /** 关联的组件实例 */\n  component?: ComponentInstance | null;\n  /** 宿主节点引用（渲染后赋值） */\n  el?: unknown;\n  /** 锚点引用 */\n  anchor?: unknown;\n}\n\n/**\n * 组件内部实例（最小接口）。\n *\n * L2 层仅需要组件实例的标识能力，用于资源注册表映射。\n */\nexport interface ComponentInstance {\n  /** 组件唯一标识 */\n  uid: number;\n  /** 组件类型 */\n  type: object;\n  /** 是否已卸载 */\n  isUnmounted: boolean;\n  /** VNode 引用 */\n  vnode: VNode;\n  /** 父组件实例 */\n  parent: ComponentInstance | null;\n  /** 子树 VNode */\n  subTree: VNode;\n}\n\n/**\n * 事件监听器注册条目。\n */\nexport interface EventListenerEntry<HE> {\n  /** 宿主元素 */\n  el: HE;\n  /** 事件名 */\n  event: string;\n  /** 处理函数 */\n  handler: (event: HostEvent) => void;\n  /** 事件选项 */\n  options?: { capture?: boolean; once?: boolean; passive?: boolean };\n}\n\n/**\n * 资源注册表条目。\n */\nexport interface ResourceEntry {\n  /** 事件监听器列表 */\n  eventListeners: EventListenerEntry<unknown>[];\n  /** effect 订阅 dispose 列表 */\n  effectDisposers: Array<() => void>;\n  /** 通用清理回调列表 */\n  cleanupHooks: Array<() => void>;\n}\n\n/**\n * 节点缓存配置项。\n */\nexport interface NodeCacheOptions {\n  /** 是否启用 VNode 映射（默认 true） */\n  enableVNodeMap?: boolean;\n  /** 是否启用资源注册表（默认 true） */\n  enableResourceRegistry?: boolean;\n}\n\n// ============================================================\n// 常量\n// ============================================================\n\n/** 默认配置 */\nconst DEFAULT_OPTIONS: Required<NodeCacheOptions> = {\n  enableVNodeMap: true,\n  enableResourceRegistry: true,\n};\n\n// ============================================================\n// NodeCache\n// ============================================================\n\n/**\n * 节点缓存。\n *\n * 管理 container → VNode 映射和组件实例 → 资源注册表映射，\n * 提供统一的资源清理函数。\n *\n * @template HN - 宿主节点类型\n * @template HE - 宿主元素类型\n */\nexport class NodeCache<HN extends object = object, HE extends HN = HN> {\n  /** RendererHost 实例 */\n  private host: RendererHost<HN, HE>;\n\n  /** 配置项 */\n  private options: Required<NodeCacheOptions>;\n\n  /** container → VNode 映射 */\n  private vnodeMap = new WeakMap<HN, VNode | null>();\n\n  /** 组件实例 → 资源注册表映射 */\n  private resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\n\n  /**\n   * 创建节点缓存实例。\n   * @param host - RendererHost 实例\n   * @param options - 可选的配置项\n   */\n  constructor(host: RendererHost<HN, HE>, options?: NodeCacheOptions) {\n    this.host = host;\n    this.options = { ...DEFAULT_OPTIONS, ...options };\n  }\n\n  // ==========================================================\n  // VNode 映射\n  // ==========================================================\n\n  /**\n   * 获取 container 对应的 VNode。\n   * @param container - 宿主容器节点\n   * @returns VNode 或 null\n   */\n  getVNode(container: HN): VNode | null {\n    if (!this.options.enableVNodeMap) return null;\n    return this.vnodeMap.get(container) ?? null;\n  }\n\n  /**\n   * 设置 container → VNode 映射。\n   * @param container - 宿主容器节点\n   * @param vnode - VNode 实例\n   */\n  setVNode(container: HN, vnode: VNode | null): void {\n    if (!this.options.enableVNodeMap) return;\n    this.vnodeMap.set(container, vnode);\n  }\n\n  /**\n   * 删除 container 的 VNode 映射。\n   * @param container - 宿主容器节点\n   */\n  deleteVNode(container: HN): void {\n    this.vnodeMap.delete(container);\n  }\n\n  // ==========================================================\n  // 资源注册表\n  // ==========================================================\n\n  /**\n   * 注册事件监听器到组件实例的资源注册表。\n   *\n   * @param instance - 组件实例\n   * @param el - 宿主元素\n   * @param event - 事件名\n   * @param handler - 事件处理函数\n   * @param options - 可选的事件选项\n   */\n  registerEventListener(\n    instance: ComponentInstance,\n    el: HE,\n    event: string,\n    handler: HostEventHandler,\n    options?: HostEventOptions,\n  ): void {\n    if (!this.options.enableResourceRegistry) return;\n\n    const entry = this.getOrCreateResourceEntry(instance);\n    entry.eventListeners.push({ el, event, handler, options });\n  }\n\n  /**\n   * 注册 effect 订阅到组件实例的资源注册表。\n   *\n   * @param instance - 组件实例\n   * @param disposer - effect 的 dispose 回调函数\n   */\n  registerEffectSubscription(instance: ComponentInstance, disposer: () => void): void {\n    if (!this.options.enableResourceRegistry) return;\n\n    const entry = this.getOrCreateResourceEntry(instance);\n    entry.effectDisposers.push(disposer);\n  }\n\n  /**\n   * 注册通用清理钩子到组件实例的资源注册表。\n   *\n   * @param instance - 组件实例\n   * @param cleanup - 清理回调函数\n   */\n  registerCleanup(instance: ComponentInstance, cleanup: () => void): void {\n    if (!this.options.enableResourceRegistry) return;\n\n    const entry = this.getOrCreateResourceEntry(instance);\n    entry.cleanupHooks.push(cleanup);\n  }\n\n  // ==========================================================\n  // 统一清理\n  // ==========================================================\n\n  /**\n   * 统一清理组件实例的所有注册资源。\n   *\n   * 清理顺序：\n   * 1. cleanup 钩子（可能依赖 effect 仍活跃）\n   * 2. effect 订阅（停止响应式追踪）\n   * 3. 事件监听器（DOM 操作，最后执行）\n   *\n   * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。\n   *\n   * @param instance - 要清理资源的组件实例\n   */\n  cleanupComponentResources(instance: ComponentInstance): void {\n    const entry = this.resourceRegistry.get(instance);\n    if (!entry) return;\n\n    // 1. 执行 cleanup 钩子\n    for (const cleanup of entry.cleanupHooks) {\n      try {\n        cleanup();\n      } catch (err) {\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during cleanup hook:', err);\n      }\n    }\n\n    // 2. 清理 effect 订阅\n    for (const disposer of entry.effectDisposers) {\n      try {\n        disposer();\n      } catch (err) {\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during effect dispose:', err);\n      }\n    }\n\n    // 3. 清理事件监听器\n    for (const listener of entry.eventListeners) {\n      try {\n        // FIX: P2-v11-21 添加类型检查，确保 listener.el 是有效的宿主元素\n        if (listener.el == null || typeof listener.el !== 'object') {\n          if (__DEV__) {\n            console.warn(\n              '[lytjs/node-cache] Invalid event listener element, skipping:',\n              listener.el,\n            );\n          }\n          continue;\n        }\n        this.host.removeEventListener(\n          // FIX: P2-batch2-13 添加运行时类型检查，确保 listener.el 符合 HE 类型约束\n          listener.el as HE,\n          listener.event,\n          listener.handler,\n          listener.options,\n        );\n      } catch (err) {\n        if (__DEV__) console.warn('[lytjs/node-cache] Error during event listener cleanup:', err);\n      }\n    }\n\n    // 删除注册表条目\n    this.resourceRegistry.delete(instance);\n  }\n\n  /**\n   * 清理指定 container 的 VNode 映射。\n   * @param container - 宿主容器节点\n   */\n  cleanupContainer(container: HN): void {\n    this.vnodeMap.delete(container);\n  }\n\n  /**\n   * 销毁缓存，清理所有内部状态。\n   *\n   * 注意：不会自动清理所有组件资源，需提前手动调用 cleanupComponentResources。\n   */\n  dispose(): void {\n    this.vnodeMap = new WeakMap<HN, VNode | null>();\n    this.resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();\n  }\n\n  // ==========================================================\n  // 内部方法\n  // ==========================================================\n\n  /**\n   * 获取或创建组件实例的资源注册表条目。\n   */\n  private getOrCreateResourceEntry(instance: ComponentInstance): ResourceEntry {\n    let entry = this.resourceRegistry.get(instance);\n    if (!entry) {\n      entry = {\n        eventListeners: [],\n        effectDisposers: [],\n        cleanupHooks: [],\n      };\n      this.resourceRegistry.set(instance, entry);\n    }\n    return entry;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lytjs/common-node-cache",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "description": "Node cache for managing container-VNode mappings and component resource registries in LytJS",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -27,7 +27,7 @@
   "sideEffects": false,
   "license": "MIT",
   "dependencies": {
-    "@lytjs/host-contract": "^6.0.0"
+    "@lytjs/host-contract": "^6.7.0"
   },
   "devDependencies": {
     "tsup": "^8.4.0",

package/src/index.ts

@@ -1,319 +1,327 @@
-// @lytjs/common-node-cache
-// 节点缓存：管理 container → VNode 映射、组件实例 → 资源注册表映射、统一清理函数
-
-declare const __DEV__: boolean;
-
-import type { RendererHost, HostEventHandler, HostEventOptions, HostEvent } from '@lytjs/host-contract';
-
-// ============================================================
-// 类型定义
-// ============================================================
-
-/**
- * 平台无关的 VNode 接口。
- *
- * L2 层不依赖具体的 VNode 实现，仅使用此最小接口。
- */
-export interface VNode {
-  /** 节点类型标识 */
-  type: string | symbol | object;
-  /** 节点属性 */
-  props: Record<string, unknown> | null;
-  /** 子节点 */
-  children: VNode[] | string | null;
-  /** 关联的组件实例 */
-  component?: ComponentInstance | null;
-  /** 宿主节点引用（渲染后赋值） */
-  el?: unknown;
-  /** 锚点引用 */
-  anchor?: unknown;
-}
-
-/**
- * 组件内部实例（最小接口）。
- *
- * L2 层仅需要组件实例的标识能力，用于资源注册表映射。
- */
-export interface ComponentInstance {
-  /** 组件唯一标识 */
-  uid: number;
-  /** 组件类型 */
-  type: object;
-  /** 是否已卸载 */
-  isUnmounted: boolean;
-  /** VNode 引用 */
-  vnode: VNode;
-  /** 父组件实例 */
-  parent: ComponentInstance | null;
-  /** 子树 VNode */
-  subTree: VNode;
-}
-
-/**
- * 事件监听器注册条目。
- */
-export interface EventListenerEntry<HE> {
-  /** 宿主元素 */
-  el: HE;
-  /** 事件名 */
-  event: string;
-  /** 处理函数 */
-  handler: (event: HostEvent) => void;
-  /** 事件选项 */
-  options?: { capture?: boolean; once?: boolean; passive?: boolean };
-}
-
-/**
- * 资源注册表条目。
- */
-export interface ResourceEntry {
-  /** 事件监听器列表 */
-  eventListeners: EventListenerEntry<unknown>[];
-  /** effect 订阅 dispose 列表 */
-  effectDisposers: Array<() => void>;
-  /** 通用清理回调列表 */
-  cleanupHooks: Array<() => void>;
-}
-
-/**
- * 节点缓存配置项。
- */
-export interface NodeCacheOptions {
-  /** 是否启用 VNode 映射（默认 true） */
-  enableVNodeMap?: boolean;
-  /** 是否启用资源注册表（默认 true） */
-  enableResourceRegistry?: boolean;
-}
-
-// ============================================================
-// 常量
-// ============================================================
-
-/** 默认配置 */
-const DEFAULT_OPTIONS: Required<NodeCacheOptions> = {
-  enableVNodeMap: true,
-  enableResourceRegistry: true,
-};
-
-// ============================================================
-// NodeCache
-// ============================================================
-
-/**
- * 节点缓存。
- *
- * 管理 container → VNode 映射和组件实例 → 资源注册表映射，
- * 提供统一的资源清理函数。
- *
- * @template HN - 宿主节点类型
- * @template HE - 宿主元素类型
- */
-export class NodeCache<HN extends object = object, HE extends HN = HN> {
-  /** RendererHost 实例 */
-  private host: RendererHost<HN, HE>;
-
-  /** 配置项 */
-  private options: Required<NodeCacheOptions>;
-
-  /** container → VNode 映射 */
-  private vnodeMap = new WeakMap<HN, VNode | null>();
-
-  /** 组件实例 → 资源注册表映射 */
-  private resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();
-
-  /**
-   * 创建节点缓存实例。
-   * @param host - RendererHost 实例
-   * @param options - 可选的配置项
-   */
-  constructor(host: RendererHost<HN, HE>, options?: NodeCacheOptions) {
-    this.host = host;
-    this.options = { ...DEFAULT_OPTIONS, ...options };
-  }
-
-  // ==========================================================
-  // VNode 映射
-  // ==========================================================
-
-  /**
-   * 获取 container 对应的 VNode。
-   * @param container - 宿主容器节点
-   * @returns VNode 或 null
-   */
-  getVNode(container: HN): VNode | null {
-    if (!this.options.enableVNodeMap) return null;
-    return this.vnodeMap.get(container) ?? null;
-  }
-
-  /**
-   * 设置 container → VNode 映射。
-   * @param container - 宿主容器节点
-   * @param vnode - VNode 实例
-   */
-  setVNode(container: HN, vnode: VNode | null): void {
-    if (!this.options.enableVNodeMap) return;
-    this.vnodeMap.set(container, vnode);
-  }
-
-  /**
-   * 删除 container 的 VNode 映射。
-   * @param container - 宿主容器节点
-   */
-  deleteVNode(container: HN): void {
-    this.vnodeMap.delete(container);
-  }
-
-  // ==========================================================
-  // 资源注册表
-  // ==========================================================
-
-  /**
-   * 注册事件监听器到组件实例的资源注册表。
-   *
-   * @param instance - 组件实例
-   * @param el - 宿主元素
-   * @param event - 事件名
-   * @param handler - 事件处理函数
-   * @param options - 可选的事件选项
-   */
-  registerEventListener(
-    instance: ComponentInstance,
-    el: HE,
-    event: string,
-    handler: HostEventHandler,
-    options?: HostEventOptions,
-  ): void {
-    if (!this.options.enableResourceRegistry) return;
-
-    const entry = this.getOrCreateResourceEntry(instance);
-    entry.eventListeners.push({ el, event, handler, options });
-  }
-
-  /**
-   * 注册 effect 订阅到组件实例的资源注册表。
-   *
-   * @param instance - 组件实例
-   * @param disposer - effect 的 dispose 回调函数
-   */
-  registerEffectSubscription(instance: ComponentInstance, disposer: () => void): void {
-    if (!this.options.enableResourceRegistry) return;
-
-    const entry = this.getOrCreateResourceEntry(instance);
-    entry.effectDisposers.push(disposer);
-  }
-
-  /**
-   * 注册通用清理钩子到组件实例的资源注册表。
-   *
-   * @param instance - 组件实例
-   * @param cleanup - 清理回调函数
-   */
-  registerCleanup(instance: ComponentInstance, cleanup: () => void): void {
-    if (!this.options.enableResourceRegistry) return;
-
-    const entry = this.getOrCreateResourceEntry(instance);
-    entry.cleanupHooks.push(cleanup);
-  }
-
-  // ==========================================================
-  // 统一清理
-  // ==========================================================
-
-  /**
-   * 统一清理组件实例的所有注册资源。
-   *
-   * 清理顺序：
-   * 1. cleanup 钩子（可能依赖 effect 仍活跃）
-   * 2. effect 订阅（停止响应式追踪）
-   * 3. 事件监听器（DOM 操作，最后执行）
-   *
-   * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。
-   *
-   * @param instance - 要清理资源的组件实例
-   */
-  cleanupComponentResources(instance: ComponentInstance): void {
-    const entry = this.resourceRegistry.get(instance);
-    if (!entry) return;
-
-    // 1. 执行 cleanup 钩子
-    for (const cleanup of entry.cleanupHooks) {
-      try {
-        cleanup();
-      } catch (err) {
-        if (__DEV__) console.warn('[lytjs/node-cache] Error during cleanup hook:', err);
-      }
-    }
-
-    // 2. 清理 effect 订阅
-    for (const disposer of entry.effectDisposers) {
-      try {
-        disposer();
-      } catch (err) {
-        if (__DEV__) console.warn('[lytjs/node-cache] Error during effect dispose:', err);
-      }
-    }
-
-    // 3. 清理事件监听器
-    for (const listener of entry.eventListeners) {
-      try {
-        // FIX: P2-v11-21 添加类型检查，确保 listener.el 是有效的宿主元素
-        if (listener.el == null || typeof listener.el !== 'object') {
-          if (__DEV__) {
-            console.warn('[lytjs/node-cache] Invalid event listener element, skipping:', listener.el);
-          }
-          continue;
-        }
-        this.host.removeEventListener(
-          // FIX: P2-batch2-13 添加运行时类型检查，确保 listener.el 符合 HE 类型约束
-          listener.el as HE,
-          listener.event,
-          listener.handler,
-          listener.options,
-        );
-      } catch (err) {
-        if (__DEV__) console.warn('[lytjs/node-cache] Error during event listener cleanup:', err);
-      }
-    }
-
-    // 删除注册表条目
-    this.resourceRegistry.delete(instance);
-  }
-
-  /**
-   * 清理指定 container 的 VNode 映射。
-   * @param container - 宿主容器节点
-   */
-  cleanupContainer(container: HN): void {
-    this.vnodeMap.delete(container);
-  }
-
-  /**
-   * 销毁缓存，清理所有内部状态。
-   *
-   * 注意：不会自动清理所有组件资源，需提前手动调用 cleanupComponentResources。
-   */
-  dispose(): void {
-    this.vnodeMap = new WeakMap<HN, VNode | null>();
-    this.resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();
-  }
-
-  // ==========================================================
-  // 内部方法
-  // ==========================================================
-
-  /**
-   * 获取或创建组件实例的资源注册表条目。
-   */
-  private getOrCreateResourceEntry(instance: ComponentInstance): ResourceEntry {
-    let entry = this.resourceRegistry.get(instance);
-    if (!entry) {
-      entry = {
-        eventListeners: [],
-        effectDisposers: [],
-        cleanupHooks: [],
-      };
-      this.resourceRegistry.set(instance, entry);
-    }
-    return entry;
-  }
-}
+// @lytjs/common-node-cache
+// 节点缓存：管理 container → VNode 映射、组件实例 → 资源注册表映射、统一清理函数
+
+declare const __DEV__: boolean;
+
+import type {
+  RendererHost,
+  HostEventHandler,
+  HostEventOptions,
+  HostEvent,
+} from '@lytjs/host-contract';
+
+// ============================================================
+// 类型定义
+// ============================================================
+
+/**
+ * 平台无关的 VNode 接口。
+ *
+ * L2 层不依赖具体的 VNode 实现，仅使用此最小接口。
+ */
+export interface VNode {
+  /** 节点类型标识 */
+  type: string | symbol | object;
+  /** 节点属性 */
+  props: Record<string, unknown> | null;
+  /** 子节点 */
+  children: VNode[] | string | null;
+  /** 关联的组件实例 */
+  component?: ComponentInstance | null;
+  /** 宿主节点引用（渲染后赋值） */
+  el?: unknown;
+  /** 锚点引用 */
+  anchor?: unknown;
+}
+
+/**
+ * 组件内部实例（最小接口）。
+ *
+ * L2 层仅需要组件实例的标识能力，用于资源注册表映射。
+ */
+export interface ComponentInstance {
+  /** 组件唯一标识 */
+  uid: number;
+  /** 组件类型 */
+  type: object;
+  /** 是否已卸载 */
+  isUnmounted: boolean;
+  /** VNode 引用 */
+  vnode: VNode;
+  /** 父组件实例 */
+  parent: ComponentInstance | null;
+  /** 子树 VNode */
+  subTree: VNode;
+}
+
+/**
+ * 事件监听器注册条目。
+ */
+export interface EventListenerEntry<HE> {
+  /** 宿主元素 */
+  el: HE;
+  /** 事件名 */
+  event: string;
+  /** 处理函数 */
+  handler: (event: HostEvent) => void;
+  /** 事件选项 */
+  options?: { capture?: boolean; once?: boolean; passive?: boolean };
+}
+
+/**
+ * 资源注册表条目。
+ */
+export interface ResourceEntry {
+  /** 事件监听器列表 */
+  eventListeners: EventListenerEntry<unknown>[];
+  /** effect 订阅 dispose 列表 */
+  effectDisposers: Array<() => void>;
+  /** 通用清理回调列表 */
+  cleanupHooks: Array<() => void>;
+}
+
+/**
+ * 节点缓存配置项。
+ */
+export interface NodeCacheOptions {
+  /** 是否启用 VNode 映射（默认 true） */
+  enableVNodeMap?: boolean;
+  /** 是否启用资源注册表（默认 true） */
+  enableResourceRegistry?: boolean;
+}
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** 默认配置 */
+const DEFAULT_OPTIONS: Required<NodeCacheOptions> = {
+  enableVNodeMap: true,
+  enableResourceRegistry: true,
+};
+
+// ============================================================
+// NodeCache
+// ============================================================
+
+/**
+ * 节点缓存。
+ *
+ * 管理 container → VNode 映射和组件实例 → 资源注册表映射，
+ * 提供统一的资源清理函数。
+ *
+ * @template HN - 宿主节点类型
+ * @template HE - 宿主元素类型
+ */
+export class NodeCache<HN extends object = object, HE extends HN = HN> {
+  /** RendererHost 实例 */
+  private host: RendererHost<HN, HE>;
+
+  /** 配置项 */
+  private options: Required<NodeCacheOptions>;
+
+  /** container → VNode 映射 */
+  private vnodeMap = new WeakMap<HN, VNode | null>();
+
+  /** 组件实例 → 资源注册表映射 */
+  private resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();
+
+  /**
+   * 创建节点缓存实例。
+   * @param host - RendererHost 实例
+   * @param options - 可选的配置项
+   */
+  constructor(host: RendererHost<HN, HE>, options?: NodeCacheOptions) {
+    this.host = host;
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+  }
+
+  // ==========================================================
+  // VNode 映射
+  // ==========================================================
+
+  /**
+   * 获取 container 对应的 VNode。
+   * @param container - 宿主容器节点
+   * @returns VNode 或 null
+   */
+  getVNode(container: HN): VNode | null {
+    if (!this.options.enableVNodeMap) return null;
+    return this.vnodeMap.get(container) ?? null;
+  }
+
+  /**
+   * 设置 container → VNode 映射。
+   * @param container - 宿主容器节点
+   * @param vnode - VNode 实例
+   */
+  setVNode(container: HN, vnode: VNode | null): void {
+    if (!this.options.enableVNodeMap) return;
+    this.vnodeMap.set(container, vnode);
+  }
+
+  /**
+   * 删除 container 的 VNode 映射。
+   * @param container - 宿主容器节点
+   */
+  deleteVNode(container: HN): void {
+    this.vnodeMap.delete(container);
+  }
+
+  // ==========================================================
+  // 资源注册表
+  // ==========================================================
+
+  /**
+   * 注册事件监听器到组件实例的资源注册表。
+   *
+   * @param instance - 组件实例
+   * @param el - 宿主元素
+   * @param event - 事件名
+   * @param handler - 事件处理函数
+   * @param options - 可选的事件选项
+   */
+  registerEventListener(
+    instance: ComponentInstance,
+    el: HE,
+    event: string,
+    handler: HostEventHandler,
+    options?: HostEventOptions,
+  ): void {
+    if (!this.options.enableResourceRegistry) return;
+
+    const entry = this.getOrCreateResourceEntry(instance);
+    entry.eventListeners.push({ el, event, handler, options });
+  }
+
+  /**
+   * 注册 effect 订阅到组件实例的资源注册表。
+   *
+   * @param instance - 组件实例
+   * @param disposer - effect 的 dispose 回调函数
+   */
+  registerEffectSubscription(instance: ComponentInstance, disposer: () => void): void {
+    if (!this.options.enableResourceRegistry) return;
+
+    const entry = this.getOrCreateResourceEntry(instance);
+    entry.effectDisposers.push(disposer);
+  }
+
+  /**
+   * 注册通用清理钩子到组件实例的资源注册表。
+   *
+   * @param instance - 组件实例
+   * @param cleanup - 清理回调函数
+   */
+  registerCleanup(instance: ComponentInstance, cleanup: () => void): void {
+    if (!this.options.enableResourceRegistry) return;
+
+    const entry = this.getOrCreateResourceEntry(instance);
+    entry.cleanupHooks.push(cleanup);
+  }
+
+  // ==========================================================
+  // 统一清理
+  // ==========================================================
+
+  /**
+   * 统一清理组件实例的所有注册资源。
+   *
+   * 清理顺序：
+   * 1. cleanup 钩子（可能依赖 effect 仍活跃）
+   * 2. effect 订阅（停止响应式追踪）
+   * 3. 事件监听器（DOM 操作，最后执行）
+   *
+   * 每个清理操作均通过 try-catch 保护，单个失败不影响其余流程。
+   *
+   * @param instance - 要清理资源的组件实例
+   */
+  cleanupComponentResources(instance: ComponentInstance): void {
+    const entry = this.resourceRegistry.get(instance);
+    if (!entry) return;
+
+    // 1. 执行 cleanup 钩子
+    for (const cleanup of entry.cleanupHooks) {
+      try {
+        cleanup();
+      } catch (err) {
+        if (__DEV__) console.warn('[lytjs/node-cache] Error during cleanup hook:', err);
+      }
+    }
+
+    // 2. 清理 effect 订阅
+    for (const disposer of entry.effectDisposers) {
+      try {
+        disposer();
+      } catch (err) {
+        if (__DEV__) console.warn('[lytjs/node-cache] Error during effect dispose:', err);
+      }
+    }
+
+    // 3. 清理事件监听器
+    for (const listener of entry.eventListeners) {
+      try {
+        // FIX: P2-v11-21 添加类型检查，确保 listener.el 是有效的宿主元素
+        if (listener.el == null || typeof listener.el !== 'object') {
+          if (__DEV__) {
+            console.warn(
+              '[lytjs/node-cache] Invalid event listener element, skipping:',
+              listener.el,
+            );
+          }
+          continue;
+        }
+        this.host.removeEventListener(
+          // FIX: P2-batch2-13 添加运行时类型检查，确保 listener.el 符合 HE 类型约束
+          listener.el as HE,
+          listener.event,
+          listener.handler,
+          listener.options,
+        );
+      } catch (err) {
+        if (__DEV__) console.warn('[lytjs/node-cache] Error during event listener cleanup:', err);
+      }
+    }
+
+    // 删除注册表条目
+    this.resourceRegistry.delete(instance);
+  }
+
+  /**
+   * 清理指定 container 的 VNode 映射。
+   * @param container - 宿主容器节点
+   */
+  cleanupContainer(container: HN): void {
+    this.vnodeMap.delete(container);
+  }
+
+  /**
+   * 销毁缓存，清理所有内部状态。
+   *
+   * 注意：不会自动清理所有组件资源，需提前手动调用 cleanupComponentResources。
+   */
+  dispose(): void {
+    this.vnodeMap = new WeakMap<HN, VNode | null>();
+    this.resourceRegistry = new WeakMap<ComponentInstance, ResourceEntry>();
+  }
+
+  // ==========================================================
+  // 内部方法
+  // ==========================================================
+
+  /**
+   * 获取或创建组件实例的资源注册表条目。
+   */
+  private getOrCreateResourceEntry(instance: ComponentInstance): ResourceEntry {
+    let entry = this.resourceRegistry.get(instance);
+    if (!entry) {
+      entry = {
+        eventListeners: [],
+        effectDisposers: [],
+        cleanupHooks: [],
+      };
+      this.resourceRegistry.set(instance, entry);
+    }
+    return entry;
+  }
+}