rendx-engine 0.2.0 → 0.3.0

package/dist/main.cjs

@@ -64,6 +64,7 @@ __export(main_exports, {
   Renderer: () => Renderer,
   RoundShape: () => RoundShape,
   Scene: () => Scene,
+  Scheduler: () => Scheduler,
   SectorShape: () => SectorShape,
   SectorTransform: () => SectorTransform,
   Shape: () => Shape,
@@ -2560,6 +2561,48 @@ createListener_fn = function(type) {
   };
 };
 
+// src/app.ts
+var import_eventemitter32 = __toESM(require("eventemitter3"), 1);
+
+// src/scheduler.ts
+var _pendingState, _microTaskQueued, _onFlush;
+var Scheduler = class {
+  constructor(onFlush) {
+    __privateAdd(this, _pendingState, /* @__PURE__ */ new Set());
+    __privateAdd(this, _microTaskQueued, false);
+    __privateAdd(this, _onFlush);
+    __privateSet(this, _onFlush, onFlush);
+  }
+  /**
+   * 标记 state key 变更，批量到微任务统一通知。
+   * 同一轮微任务内多次调用同一 key 只通知一次。
+   */
+  markState(key) {
+    __privateGet(this, _pendingState).add(key);
+    if (!__privateGet(this, _microTaskQueued)) {
+      __privateSet(this, _microTaskQueued, true);
+      queueMicrotask(() => {
+        __privateSet(this, _microTaskQueued, false);
+        const keys = new Set(__privateGet(this, _pendingState));
+        __privateGet(this, _pendingState).clear();
+        __privateGet(this, _onFlush).call(this, keys);
+      });
+    }
+  }
+  /** 是否有待通知的 state 变更 */
+  get hasPending() {
+    return __privateGet(this, _pendingState).size > 0;
+  }
+  /** 清空待通知队列（用于 dispose） */
+  clear() {
+    __privateGet(this, _pendingState).clear();
+    __privateSet(this, _microTaskQueued, false);
+  }
+};
+_pendingState = new WeakMap();
+_microTaskQueued = new WeakMap();
+_onFlush = new WeakMap();
+
 // src/serialization.ts
 var SHAPE_FROM_KEYS = {
   text: ["text", "x", "y"],
@@ -2721,21 +2764,39 @@ function deserialize(json, cfg) {
 }
 
 // src/app.ts
-var _rafId, _mounted, _container, _eventLayer, _resizeObserver, _plugins, _App_instances, tick_fn;
+var _rafId, _renderDirty, _mounted, _container, _eventLayer, _resizeObserver, _plugins, _state, _stateMeta, _scheduler, _App_instances, resolveIndex_fn, nextAvailableIndex_fn, frame_fn;
 var _App = class _App {
   /**
    * @param cfg - 引擎配置（width/height/layers/autoResize 等）
    */
   constructor(cfg = {}) {
     __privateAdd(this, _App_instances);
+    /**
+     * 中心化事件总线 — 纯信号（不传数据）。
+     * 插件通过 `app.bus.emit('eventName')` 发布信号，
+     * 消费方通过 `app.bus.on('eventName', handler)` 订阅。
+     */
+    this.bus = new import_eventemitter32.default();
     __privateAdd(this, _rafId, null);
+    __privateAdd(this, _renderDirty, false);
     __privateAdd(this, _mounted, false);
     __privateAdd(this, _container, null);
     __privateAdd(this, _eventLayer);
     __privateAdd(this, _resizeObserver, null);
     __privateAdd(this, _plugins, []);
+    // ========================
+    // State Management
+    // ========================
+    __privateAdd(this, _state, /* @__PURE__ */ new Map());
+    __privateAdd(this, _stateMeta, /* @__PURE__ */ new Map());
+    __privateAdd(this, _scheduler);
     this.cfg = cfg;
     this.scene = new Scene();
+    __privateSet(this, _scheduler, new Scheduler((keys) => {
+      for (const key of keys) {
+        this.bus.emit(`state:${key}`);
+      }
+    }));
     __privateSet(this, _eventLayer, new Layer("__event__", 99999, this.cfg, true));
     this.scene.registerLayer(__privateGet(this, _eventLayer));
     this.scene.registerLayer(new Layer("default", 0, this.cfg));
@@ -2808,7 +2869,30 @@ var _App = class _App {
     return this.scene.getLayer(name);
   }
   /**
-   * 注册插件（同名插件不会重复注册）
+   * 获取或创建图层（get-or-create 语义）。
+   * 多个插件声明同名图层时，只会创建一次。
+   *
+   * zIndex 语义：
+   * - 传入时代表全局层级意图（负数 = default 之下，正数 = default 之上）
+   * - 若与已有层冲突，自动向上偏移到最近可用值
+   * - 省略时自动分配（当前最高非事件层 + 1）
+   *
+   * @param name - 层名称
+   * @param zIndex - 全局层级意图（可选）
+   */
+  acquireLayer(name, zIndex) {
+    const existing = this.scene.getLayer(name);
+    if (existing) return existing;
+    const index = zIndex !== void 0 ? __privateMethod(this, _App_instances, resolveIndex_fn).call(this, zIndex) : __privateMethod(this, _App_instances, nextAvailableIndex_fn).call(this);
+    return this.addLayer(name, index);
+  }
+  /**
+   * 注册插件。流程：
+   * 1. 去重检查（同名跳过）
+   * 2. 注册 state 声明（key 冲突则抛错）
+   * 3. 自动 acquireLayer（声明的图层）
+   * 4. 调用 plugin.install(app)
+   *
    * @param plugin - 实现 Plugin 接口的插件实例
    */
   use(plugin) {
@@ -2816,6 +2900,22 @@ var _App = class _App {
       console.warn(`Plugin "${plugin.name}" is already registered.`);
       return this;
     }
+    if (plugin.state) {
+      for (const decl of plugin.state) {
+        if (__privateGet(this, _stateMeta).has(decl.key)) {
+          const owner = __privateGet(this, _stateMeta).get(decl.key).owner;
+          throw new Error(`State key "${decl.key}" already declared by plugin "${owner}". Plugin "${plugin.name}" cannot redeclare it.`);
+        }
+        __privateGet(this, _stateMeta).set(decl.key, { owner: plugin.name, description: decl.description });
+        __privateGet(this, _state).set(decl.key, decl.initial);
+      }
+    }
+    if (plugin.layers) {
+      const sorted = [...plugin.layers].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
+      for (const decl of sorted) {
+        this.acquireLayer(decl.name, decl.zIndex);
+      }
+    }
     __privateGet(this, _plugins).push(plugin);
     plugin.install(this);
     return this;
@@ -2824,6 +2924,40 @@ var _App = class _App {
   getPlugin(name) {
     return __privateGet(this, _plugins).find((p) => p.name === name);
   }
+  // ========================
+  // Centralized State
+  // ========================
+  /**
+   * 写入 state（同步写入 + 异步批量通知）。
+   * key 必须先由某个插件在 `state[]` 中声明，否则抛错。
+   * 写入后立即可通过 `getState()` 读到最新值，通知在微任务中批量发出。
+   */
+  setState(key, value) {
+    if (!__privateGet(this, _stateMeta).has(key)) {
+      throw new Error(`State key "${key}" is not declared by any plugin. Plugins must declare state keys in their "state" array.`);
+    }
+    __privateGet(this, _state).set(key, value);
+    __privateGet(this, _scheduler).markState(key);
+  }
+  /**
+   * 读取 state（同步读取，始终返回最新值）。
+   * @returns 对应 key 的当前值，不存在则返回 undefined
+   */
+  getState(key) {
+    return __privateGet(this, _state).get(key);
+  }
+  /**
+   * 导出完整 state 快照（调试/devtools 用）。
+   * 返回每个 key 的当前值、所属插件和描述信息。
+   */
+  dumpState() {
+    const result = {};
+    for (const [key, value] of __privateGet(this, _state)) {
+      const meta = __privateGet(this, _stateMeta).get(key);
+      result[key] = { value, owner: meta.owner, description: meta.description };
+    }
+    return result;
+  }
   /** 同步渲染一帧。适用于静态内容，仅重绘脏层 */
   render() {
     for (const layer of this.scene.layers) {
@@ -2832,10 +2966,12 @@ var _App = class _App {
       }
     }
   }
-  /** 请求异步渲染循环（rAF），有动画时自动继续，无变化时停止 */
+  /** 请求异步渲染帧（幂等，一帧只执行一次）。无变化时自动停止 rAF 链 */
   requestRender() {
-    if (__privateGet(this, _rafId) !== null) return;
-    __privateSet(this, _rafId, requestAnimationFrame((t) => __privateMethod(this, _App_instances, tick_fn).call(this, t)));
+    __privateSet(this, _renderDirty, true);
+    if (__privateGet(this, _rafId) === null) {
+      __privateSet(this, _rafId, requestAnimationFrame((t) => __privateMethod(this, _App_instances, frame_fn).call(this, t)));
+    }
   }
   /**
    * 调整画布尺寸，同步更新所有层、容器和视口矩阵
@@ -2876,6 +3012,10 @@ var _App = class _App {
       plugin.dispose?.();
     }
     __privateSet(this, _plugins, []);
+    this.bus.removeAllListeners();
+    __privateGet(this, _state).clear();
+    __privateGet(this, _stateMeta).clear();
+    __privateGet(this, _scheduler).clear();
     if (__privateGet(this, _resizeObserver)) {
       __privateGet(this, _resizeObserver).disconnect();
       __privateSet(this, _resizeObserver, null);
@@ -2910,7 +3050,17 @@ var _App = class _App {
   }
   /** 序列化所有渲染层的场景图为 JSON，可用于保存/回放 */
   toJSON() {
-    return serialize(this.scene.layers, this.cfg.width ?? 800, this.cfg.height ?? 600);
+    const json = serialize(this.scene.layers, this.cfg.width ?? 800, this.cfg.height ?? 600);
+    const pluginsData = {};
+    for (const plugin of __privateGet(this, _plugins)) {
+      if (plugin.serialize) {
+        pluginsData[plugin.name] = plugin.serialize();
+      }
+    }
+    if (Object.keys(pluginsData).length > 0) {
+      json.plugins = pluginsData;
+    }
+    return json;
   }
   /**
    * 从 JSON 快照创建新的 App 实例（静态工厂方法）
@@ -2949,17 +3099,49 @@ var _App = class _App {
         __privateGet(this, _container).insertBefore(layer.renderer.el, __privateGet(this, _eventLayer).renderer.el);
       }
     }
+    if (json.plugins) {
+      for (const plugin of __privateGet(this, _plugins)) {
+        const data = json.plugins[plugin.name];
+        if (data && plugin.deserialize) {
+          plugin.deserialize(data);
+        }
+      }
+    }
   }
 };
 _rafId = new WeakMap();
+_renderDirty = new WeakMap();
 _mounted = new WeakMap();
 _container = new WeakMap();
 _eventLayer = new WeakMap();
 _resizeObserver = new WeakMap();
 _plugins = new WeakMap();
+_state = new WeakMap();
+_stateMeta = new WeakMap();
+_scheduler = new WeakMap();
 _App_instances = new WeakSet();
-tick_fn = function(time) {
-  __privateSet(this, _rafId, null);
+/**
+ * 解析 zIndex：若已被占用则向上偏移到最近可用值。
+ * 保证返回值不会与任何已有层的 layerIndex 冲突。
+ */
+resolveIndex_fn = function(desired) {
+  const used = new Set(this.scene.layers.map((l) => l.layerIndex));
+  while (used.has(desired)) desired++;
+  return desired;
+};
+/**
+ * 自动分配：当前最高非事件层 index + 1。
+ * 保证返回值始终 >= 1（default 层固定为 0）。
+ */
+nextAvailableIndex_fn = function() {
+  let max = 0;
+  for (const l of this.scene.layers) {
+    if (!l.isEventLayer && l.layerIndex > max) max = l.layerIndex;
+  }
+  return max + 1;
+};
+frame_fn = function(time) {
+  __privateSet(this, _renderDirty, false);
   this.scene.tick(time);
   let anyDirty = false;
   for (const layer of this.scene.layers) {
@@ -2968,8 +3150,10 @@ tick_fn = function(time) {
       anyDirty = true;
     }
   }
-  if (anyDirty) {
-    this.requestRender();
+  if (anyDirty || __privateGet(this, _renderDirty)) {
+    __privateSet(this, _rafId, requestAnimationFrame((t) => __privateMethod(this, _App_instances, frame_fn).call(this, t)));
+  } else {
+    __privateSet(this, _rafId, null);
   }
 };
 var App = _App;
@@ -3001,6 +3185,7 @@ var App = _App;
   Renderer,
   RoundShape,
   Scene,
+  Scheduler,
   SectorShape,
   SectorTransform,
   Shape,

package/dist/main.d.cts

@@ -2,6 +2,7 @@ import { vec2, mat2d } from 'gl-matrix';
 import { AO, ClipPath, GF, Mat2d, Point, GradientOptions, IGraphicsRenderer, Size } from 'rendx-core';
 import { BoundingBox } from 'rendx-bounding';
 import { Path } from 'rendx-path';
+import EventEmitter from 'eventemitter3';
 
 type TransformStatus = 'start' | 'init' | 'waiting' | 'running' | 'last' | 'clear' | 'end';
 /**
@@ -745,6 +746,8 @@ interface RendxJSON {
     width: number;
     height: number;
     layers: LayerJSON[];
+    /** 插件序列化数据（key = plugin.name） */
+    plugins?: Record<string, Record<string, unknown>>;
 }
 interface LayerJSON {
     name: string;
@@ -783,19 +786,60 @@ declare function serialize(layers: Layer[], width: number, height: number): Rend
 /** 从 JSON 反序列化，创建层和节点（不包含 App 实例） */
 declare function deserialize(json: RendxJSON, cfg: Partial<RendererConfig>): Layer[];
 
+/**
+ * 插件 state 声明 — 每个插件声明自己管理的 state key、描述和初始值。
+ * App 在 use() 时校验 key 不冲突，并以初始值写入 state map。
+ */
+interface PluginStateDeclaration {
+    /** state key（推荐 `pluginName:field` 命名空间格式） */
+    key: string;
+    /** 描述（文档/调试用） */
+    description: string;
+    /** 初始值 */
+    initial: unknown;
+}
+/**
+ * 插件图层声明 — 插件声明需要使用的渲染层。
+ * App 在 use() 时自动 acquireLayer（有则复用，无则创建）。
+ */
+interface PluginLayerDeclaration {
+    /** 层名称 */
+    name: string;
+    /**
+     * 全局层级意图（可选）。
+     *
+     * - 负数：在 default 层（index=0）之下（如 grid 背景层）
+     * - 正数：在 default 层之上（如节点层、选区层）
+     * - 同值冲突时 App 自动向上偏移，保证唯一
+     * - 省略时自动分配（当前最高层 + 1）
+     */
+    zIndex?: number;
+}
 /**
  * 插件接口
  *
- * 插件通过 `app.use(plugin)` 注册，框架会调用 `install(app)` 完成初始化。
+ * 插件通过 `app.use(plugin)` 注册，框架会：
+ * 1. 校验并注册 state 声明
+ * 2. 自动创建/复用所需图层
+ * 3. 调用 `install(app)` 完成初始化
+ *
  * 当 App dispose 时，若插件提供了 `dispose` 方法，则会自动调用。
  */
 interface Plugin {
     /** 插件名称（用于去重和调试） */
     name: string;
+    /** 声明本插件管理的 state keys */
+    state?: PluginStateDeclaration[];
+    /** 声明需要使用的渲染层 */
+    layers?: PluginLayerDeclaration[];
     /** 安装插件，在 `app.use()` 时调用 */
     install(app: App): void;
     /** 当 App resize 时调用 */
     resize?(width: number, height: number): void;
+    /** 序列化插件自身状态（持久化） */
+    serialize?(): Record<string, unknown>;
+    /** 从持久化数据恢复插件状态 */
+    deserialize?(data: Record<string, unknown>): void;
     /** 卸载插件，在 `app.dispose()` 时自动调用 */
     dispose?(): void;
 }
@@ -824,6 +868,12 @@ declare class App {
     cfg: AppConfig;
     scene: Scene;
     observer: EventObserver;
+    /**
+     * 中心化事件总线 — 纯信号（不传数据）。
+     * 插件通过 `app.bus.emit('eventName')` 发布信号，
+     * 消费方通过 `app.bus.on('eventName', handler)` 订阅。
+     */
+    bus: EventEmitter<string | symbol, any>;
     /** 挂载容器（供插件访问） */
     get container(): HTMLDivElement | null;
     /** 是否已挂载 */
@@ -842,15 +892,53 @@ declare class App {
     /** 获取层 */
     getLayer(name: string): Layer | undefined;
     /**
-     * 注册插件（同名插件不会重复注册）
+     * 获取或创建图层（get-or-create 语义）。
+     * 多个插件声明同名图层时，只会创建一次。
+     *
+     * zIndex 语义：
+     * - 传入时代表全局层级意图（负数 = default 之下，正数 = default 之上）
+     * - 若与已有层冲突，自动向上偏移到最近可用值
+     * - 省略时自动分配（当前最高非事件层 + 1）
+     *
+     * @param name - 层名称
+     * @param zIndex - 全局层级意图（可选）
+     */
+    acquireLayer(name: string, zIndex?: number): Layer;
+    /**
+     * 注册插件。流程：
+     * 1. 去重检查（同名跳过）
+     * 2. 注册 state 声明（key 冲突则抛错）
+     * 3. 自动 acquireLayer（声明的图层）
+     * 4. 调用 plugin.install(app)
+     *
      * @param plugin - 实现 Plugin 接口的插件实例
      */
     use(plugin: Plugin): this;
     /** 获取已注册的插件 */
     getPlugin(name: string): Plugin | undefined;
+    /**
+     * 写入 state（同步写入 + 异步批量通知）。
+     * key 必须先由某个插件在 `state[]` 中声明，否则抛错。
+     * 写入后立即可通过 `getState()` 读到最新值，通知在微任务中批量发出。
+     */
+    setState(key: string, value: unknown): void;
+    /**
+     * 读取 state（同步读取，始终返回最新值）。
+     * @returns 对应 key 的当前值，不存在则返回 undefined
+     */
+    getState<T>(key: string): T | undefined;
+    /**
+     * 导出完整 state 快照（调试/devtools 用）。
+     * 返回每个 key 的当前值、所属插件和描述信息。
+     */
+    dumpState(): Record<string, {
+        value: unknown;
+        owner: string;
+        description: string;
+    }>;
     /** 同步渲染一帧。适用于静态内容，仅重绘脏层 */
     render(): void;
-    /** 请求异步渲染循环（rAF），有动画时自动继续，无变化时停止 */
+    /** 请求异步渲染帧（幂等，一帧只执行一次）。无变化时自动停止 rAF 链 */
     requestRender(): void;
     /**
      * 调整画布尺寸，同步更新所有层、容器和视口矩阵
@@ -877,4 +965,24 @@ declare class App {
     restoreFromJSON(json: RendxJSON): void;
 }
 
-export { App, type AppConfig, ArcShape, ArcTransform, AreaShape, AttributeTransform, Attributes, BaseTransform, type ChildJSON, CircleShape, ClipBoxTransform, CurveShape, EventDispatcher, type EventListener, type EventListenerOptions, EventObserver, EventTarget, Graphics, type GraphicsJSON, GraphicsTransform, Group, type GroupJSON, ImageShape, Layer, type LayerJSON, LineShape, Node, type NodeJSON, PathShape, type Plugin, PolygonShape, RectShape, Renderer, type RendererConfig, type RendxJSON, RoundShape, Scene, SectorShape, SectorTransform, Shape, type ShapeCommand, SimulatedEvent, SymbolShape, type TextMeasureFn, TextShape, type TransformStatus, createShape, deserialize, imageLoader, isHit, serialize, serializeLayer, setCanvasRenderingContext2StrokeAttrs };
+/**
+ * 调度器 — 协调状态通知与渲染帧
+ *
+ * - state 变更通知：批量到微任务（同一事件循环内多次 setState 只通知一次）
+ * - 渲染帧：幂等 rAF，从不 cancel，通过 dirty 标记决定是否续帧
+ */
+declare class Scheduler {
+    #private;
+    constructor(onFlush: (keys: Set<string>) => void);
+    /**
+     * 标记 state key 变更，批量到微任务统一通知。
+     * 同一轮微任务内多次调用同一 key 只通知一次。
+     */
+    markState(key: string): void;
+    /** 是否有待通知的 state 变更 */
+    get hasPending(): boolean;
+    /** 清空待通知队列（用于 dispose） */
+    clear(): void;
+}
+
+export { App, type AppConfig, ArcShape, ArcTransform, AreaShape, AttributeTransform, Attributes, BaseTransform, type ChildJSON, CircleShape, ClipBoxTransform, CurveShape, EventDispatcher, type EventListener, type EventListenerOptions, EventObserver, EventTarget, Graphics, type GraphicsJSON, GraphicsTransform, Group, type GroupJSON, ImageShape, Layer, type LayerJSON, LineShape, Node, type NodeJSON, PathShape, type Plugin, type PluginLayerDeclaration, type PluginStateDeclaration, PolygonShape, RectShape, Renderer, type RendererConfig, type RendxJSON, RoundShape, Scene, Scheduler, SectorShape, SectorTransform, Shape, type ShapeCommand, SimulatedEvent, SymbolShape, type TextMeasureFn, TextShape, type TransformStatus, createShape, deserialize, imageLoader, isHit, serialize, serializeLayer, setCanvasRenderingContext2StrokeAttrs };

package/dist/main.d.ts

@@ -2,6 +2,7 @@ import { vec2, mat2d } from 'gl-matrix';
 import { AO, ClipPath, GF, Mat2d, Point, GradientOptions, IGraphicsRenderer, Size } from 'rendx-core';
 import { BoundingBox } from 'rendx-bounding';
 import { Path } from 'rendx-path';
+import EventEmitter from 'eventemitter3';
 
 type TransformStatus = 'start' | 'init' | 'waiting' | 'running' | 'last' | 'clear' | 'end';
 /**
@@ -745,6 +746,8 @@ interface RendxJSON {
     width: number;
     height: number;
     layers: LayerJSON[];
+    /** 插件序列化数据（key = plugin.name） */
+    plugins?: Record<string, Record<string, unknown>>;
 }
 interface LayerJSON {
     name: string;
@@ -783,19 +786,60 @@ declare function serialize(layers: Layer[], width: number, height: number): Rend
 /** 从 JSON 反序列化，创建层和节点（不包含 App 实例） */
 declare function deserialize(json: RendxJSON, cfg: Partial<RendererConfig>): Layer[];
 
+/**
+ * 插件 state 声明 — 每个插件声明自己管理的 state key、描述和初始值。
+ * App 在 use() 时校验 key 不冲突，并以初始值写入 state map。
+ */
+interface PluginStateDeclaration {
+    /** state key（推荐 `pluginName:field` 命名空间格式） */
+    key: string;
+    /** 描述（文档/调试用） */
+    description: string;
+    /** 初始值 */
+    initial: unknown;
+}
+/**
+ * 插件图层声明 — 插件声明需要使用的渲染层。
+ * App 在 use() 时自动 acquireLayer（有则复用，无则创建）。
+ */
+interface PluginLayerDeclaration {
+    /** 层名称 */
+    name: string;
+    /**
+     * 全局层级意图（可选）。
+     *
+     * - 负数：在 default 层（index=0）之下（如 grid 背景层）
+     * - 正数：在 default 层之上（如节点层、选区层）
+     * - 同值冲突时 App 自动向上偏移，保证唯一
+     * - 省略时自动分配（当前最高层 + 1）
+     */
+    zIndex?: number;
+}
 /**
  * 插件接口
  *
- * 插件通过 `app.use(plugin)` 注册，框架会调用 `install(app)` 完成初始化。
+ * 插件通过 `app.use(plugin)` 注册，框架会：
+ * 1. 校验并注册 state 声明
+ * 2. 自动创建/复用所需图层
+ * 3. 调用 `install(app)` 完成初始化
+ *
  * 当 App dispose 时，若插件提供了 `dispose` 方法，则会自动调用。
  */
 interface Plugin {
     /** 插件名称（用于去重和调试） */
     name: string;
+    /** 声明本插件管理的 state keys */
+    state?: PluginStateDeclaration[];
+    /** 声明需要使用的渲染层 */
+    layers?: PluginLayerDeclaration[];
     /** 安装插件，在 `app.use()` 时调用 */
     install(app: App): void;
     /** 当 App resize 时调用 */
     resize?(width: number, height: number): void;
+    /** 序列化插件自身状态（持久化） */
+    serialize?(): Record<string, unknown>;
+    /** 从持久化数据恢复插件状态 */
+    deserialize?(data: Record<string, unknown>): void;
     /** 卸载插件，在 `app.dispose()` 时自动调用 */
     dispose?(): void;
 }
@@ -824,6 +868,12 @@ declare class App {
     cfg: AppConfig;
     scene: Scene;
     observer: EventObserver;
+    /**
+     * 中心化事件总线 — 纯信号（不传数据）。
+     * 插件通过 `app.bus.emit('eventName')` 发布信号，
+     * 消费方通过 `app.bus.on('eventName', handler)` 订阅。
+     */
+    bus: EventEmitter<string | symbol, any>;
     /** 挂载容器（供插件访问） */
     get container(): HTMLDivElement | null;
     /** 是否已挂载 */
@@ -842,15 +892,53 @@ declare class App {
     /** 获取层 */
     getLayer(name: string): Layer | undefined;
     /**
-     * 注册插件（同名插件不会重复注册）
+     * 获取或创建图层（get-or-create 语义）。
+     * 多个插件声明同名图层时，只会创建一次。
+     *
+     * zIndex 语义：
+     * - 传入时代表全局层级意图（负数 = default 之下，正数 = default 之上）
+     * - 若与已有层冲突，自动向上偏移到最近可用值
+     * - 省略时自动分配（当前最高非事件层 + 1）
+     *
+     * @param name - 层名称
+     * @param zIndex - 全局层级意图（可选）
+     */
+    acquireLayer(name: string, zIndex?: number): Layer;
+    /**
+     * 注册插件。流程：
+     * 1. 去重检查（同名跳过）
+     * 2. 注册 state 声明（key 冲突则抛错）
+     * 3. 自动 acquireLayer（声明的图层）
+     * 4. 调用 plugin.install(app)
+     *
      * @param plugin - 实现 Plugin 接口的插件实例
      */
     use(plugin: Plugin): this;
     /** 获取已注册的插件 */
     getPlugin(name: string): Plugin | undefined;
+    /**
+     * 写入 state（同步写入 + 异步批量通知）。
+     * key 必须先由某个插件在 `state[]` 中声明，否则抛错。
+     * 写入后立即可通过 `getState()` 读到最新值，通知在微任务中批量发出。
+     */
+    setState(key: string, value: unknown): void;
+    /**
+     * 读取 state（同步读取，始终返回最新值）。
+     * @returns 对应 key 的当前值，不存在则返回 undefined
+     */
+    getState<T>(key: string): T | undefined;
+    /**
+     * 导出完整 state 快照（调试/devtools 用）。
+     * 返回每个 key 的当前值、所属插件和描述信息。
+     */
+    dumpState(): Record<string, {
+        value: unknown;
+        owner: string;
+        description: string;
+    }>;
     /** 同步渲染一帧。适用于静态内容，仅重绘脏层 */
     render(): void;
-    /** 请求异步渲染循环（rAF），有动画时自动继续，无变化时停止 */
+    /** 请求异步渲染帧（幂等，一帧只执行一次）。无变化时自动停止 rAF 链 */
     requestRender(): void;
     /**
      * 调整画布尺寸，同步更新所有层、容器和视口矩阵
@@ -877,4 +965,24 @@ declare class App {
     restoreFromJSON(json: RendxJSON): void;
 }
 
-export { App, type AppConfig, ArcShape, ArcTransform, AreaShape, AttributeTransform, Attributes, BaseTransform, type ChildJSON, CircleShape, ClipBoxTransform, CurveShape, EventDispatcher, type EventListener, type EventListenerOptions, EventObserver, EventTarget, Graphics, type GraphicsJSON, GraphicsTransform, Group, type GroupJSON, ImageShape, Layer, type LayerJSON, LineShape, Node, type NodeJSON, PathShape, type Plugin, PolygonShape, RectShape, Renderer, type RendererConfig, type RendxJSON, RoundShape, Scene, SectorShape, SectorTransform, Shape, type ShapeCommand, SimulatedEvent, SymbolShape, type TextMeasureFn, TextShape, type TransformStatus, createShape, deserialize, imageLoader, isHit, serialize, serializeLayer, setCanvasRenderingContext2StrokeAttrs };
+/**
+ * 调度器 — 协调状态通知与渲染帧
+ *
+ * - state 变更通知：批量到微任务（同一事件循环内多次 setState 只通知一次）
+ * - 渲染帧：幂等 rAF，从不 cancel，通过 dirty 标记决定是否续帧
+ */
+declare class Scheduler {
+    #private;
+    constructor(onFlush: (keys: Set<string>) => void);
+    /**
+     * 标记 state key 变更，批量到微任务统一通知。
+     * 同一轮微任务内多次调用同一 key 只通知一次。
+     */
+    markState(key: string): void;
+    /** 是否有待通知的 state 变更 */
+    get hasPending(): boolean;
+    /** 清空待通知队列（用于 dispose） */
+    clear(): void;
+}
+
+export { App, type AppConfig, ArcShape, ArcTransform, AreaShape, AttributeTransform, Attributes, BaseTransform, type ChildJSON, CircleShape, ClipBoxTransform, CurveShape, EventDispatcher, type EventListener, type EventListenerOptions, EventObserver, EventTarget, Graphics, type GraphicsJSON, GraphicsTransform, Group, type GroupJSON, ImageShape, Layer, type LayerJSON, LineShape, Node, type NodeJSON, PathShape, type Plugin, type PluginLayerDeclaration, type PluginStateDeclaration, PolygonShape, RectShape, Renderer, type RendererConfig, type RendxJSON, RoundShape, Scene, Scheduler, SectorShape, SectorTransform, Shape, type ShapeCommand, SimulatedEvent, SymbolShape, type TextMeasureFn, TextShape, type TransformStatus, createShape, deserialize, imageLoader, isHit, serialize, serializeLayer, setCanvasRenderingContext2StrokeAttrs };

package/dist/main.js

@@ -2487,6 +2487,48 @@ createListener_fn = function(type) {
   };
 };
 
+// src/app.ts
+import EventEmitter2 from "eventemitter3";
+
+// src/scheduler.ts
+var _pendingState, _microTaskQueued, _onFlush;
+var Scheduler = class {
+  constructor(onFlush) {
+    __privateAdd(this, _pendingState, /* @__PURE__ */ new Set());
+    __privateAdd(this, _microTaskQueued, false);
+    __privateAdd(this, _onFlush);
+    __privateSet(this, _onFlush, onFlush);
+  }
+  /**
+   * 标记 state key 变更，批量到微任务统一通知。
+   * 同一轮微任务内多次调用同一 key 只通知一次。
+   */
+  markState(key) {
+    __privateGet(this, _pendingState).add(key);
+    if (!__privateGet(this, _microTaskQueued)) {
+      __privateSet(this, _microTaskQueued, true);
+      queueMicrotask(() => {
+        __privateSet(this, _microTaskQueued, false);
+        const keys = new Set(__privateGet(this, _pendingState));
+        __privateGet(this, _pendingState).clear();
+        __privateGet(this, _onFlush).call(this, keys);
+      });
+    }
+  }
+  /** 是否有待通知的 state 变更 */
+  get hasPending() {
+    return __privateGet(this, _pendingState).size > 0;
+  }
+  /** 清空待通知队列（用于 dispose） */
+  clear() {
+    __privateGet(this, _pendingState).clear();
+    __privateSet(this, _microTaskQueued, false);
+  }
+};
+_pendingState = new WeakMap();
+_microTaskQueued = new WeakMap();
+_onFlush = new WeakMap();
+
 // src/serialization.ts
 var SHAPE_FROM_KEYS = {
   text: ["text", "x", "y"],
@@ -2648,21 +2690,39 @@ function deserialize(json, cfg) {
 }
 
 // src/app.ts
-var _rafId, _mounted, _container, _eventLayer, _resizeObserver, _plugins, _App_instances, tick_fn;
+var _rafId, _renderDirty, _mounted, _container, _eventLayer, _resizeObserver, _plugins, _state, _stateMeta, _scheduler, _App_instances, resolveIndex_fn, nextAvailableIndex_fn, frame_fn;
 var _App = class _App {
   /**
    * @param cfg - 引擎配置（width/height/layers/autoResize 等）
    */
   constructor(cfg = {}) {
     __privateAdd(this, _App_instances);
+    /**
+     * 中心化事件总线 — 纯信号（不传数据）。
+     * 插件通过 `app.bus.emit('eventName')` 发布信号，
+     * 消费方通过 `app.bus.on('eventName', handler)` 订阅。
+     */
+    this.bus = new EventEmitter2();
     __privateAdd(this, _rafId, null);
+    __privateAdd(this, _renderDirty, false);
     __privateAdd(this, _mounted, false);
     __privateAdd(this, _container, null);
     __privateAdd(this, _eventLayer);
     __privateAdd(this, _resizeObserver, null);
     __privateAdd(this, _plugins, []);
+    // ========================
+    // State Management
+    // ========================
+    __privateAdd(this, _state, /* @__PURE__ */ new Map());
+    __privateAdd(this, _stateMeta, /* @__PURE__ */ new Map());
+    __privateAdd(this, _scheduler);
     this.cfg = cfg;
     this.scene = new Scene();
+    __privateSet(this, _scheduler, new Scheduler((keys) => {
+      for (const key of keys) {
+        this.bus.emit(`state:${key}`);
+      }
+    }));
     __privateSet(this, _eventLayer, new Layer("__event__", 99999, this.cfg, true));
     this.scene.registerLayer(__privateGet(this, _eventLayer));
     this.scene.registerLayer(new Layer("default", 0, this.cfg));
@@ -2735,7 +2795,30 @@ var _App = class _App {
     return this.scene.getLayer(name);
   }
   /**
-   * 注册插件（同名插件不会重复注册）
+   * 获取或创建图层（get-or-create 语义）。
+   * 多个插件声明同名图层时，只会创建一次。
+   *
+   * zIndex 语义：
+   * - 传入时代表全局层级意图（负数 = default 之下，正数 = default 之上）
+   * - 若与已有层冲突，自动向上偏移到最近可用值
+   * - 省略时自动分配（当前最高非事件层 + 1）
+   *
+   * @param name - 层名称
+   * @param zIndex - 全局层级意图（可选）
+   */
+  acquireLayer(name, zIndex) {
+    const existing = this.scene.getLayer(name);
+    if (existing) return existing;
+    const index = zIndex !== void 0 ? __privateMethod(this, _App_instances, resolveIndex_fn).call(this, zIndex) : __privateMethod(this, _App_instances, nextAvailableIndex_fn).call(this);
+    return this.addLayer(name, index);
+  }
+  /**
+   * 注册插件。流程：
+   * 1. 去重检查（同名跳过）
+   * 2. 注册 state 声明（key 冲突则抛错）
+   * 3. 自动 acquireLayer（声明的图层）
+   * 4. 调用 plugin.install(app)
+   *
    * @param plugin - 实现 Plugin 接口的插件实例
    */
   use(plugin) {
@@ -2743,6 +2826,22 @@ var _App = class _App {
       console.warn(`Plugin "${plugin.name}" is already registered.`);
       return this;
     }
+    if (plugin.state) {
+      for (const decl of plugin.state) {
+        if (__privateGet(this, _stateMeta).has(decl.key)) {
+          const owner = __privateGet(this, _stateMeta).get(decl.key).owner;
+          throw new Error(`State key "${decl.key}" already declared by plugin "${owner}". Plugin "${plugin.name}" cannot redeclare it.`);
+        }
+        __privateGet(this, _stateMeta).set(decl.key, { owner: plugin.name, description: decl.description });
+        __privateGet(this, _state).set(decl.key, decl.initial);
+      }
+    }
+    if (plugin.layers) {
+      const sorted = [...plugin.layers].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
+      for (const decl of sorted) {
+        this.acquireLayer(decl.name, decl.zIndex);
+      }
+    }
     __privateGet(this, _plugins).push(plugin);
     plugin.install(this);
     return this;
@@ -2751,6 +2850,40 @@ var _App = class _App {
   getPlugin(name) {
     return __privateGet(this, _plugins).find((p) => p.name === name);
   }
+  // ========================
+  // Centralized State
+  // ========================
+  /**
+   * 写入 state（同步写入 + 异步批量通知）。
+   * key 必须先由某个插件在 `state[]` 中声明，否则抛错。
+   * 写入后立即可通过 `getState()` 读到最新值，通知在微任务中批量发出。
+   */
+  setState(key, value) {
+    if (!__privateGet(this, _stateMeta).has(key)) {
+      throw new Error(`State key "${key}" is not declared by any plugin. Plugins must declare state keys in their "state" array.`);
+    }
+    __privateGet(this, _state).set(key, value);
+    __privateGet(this, _scheduler).markState(key);
+  }
+  /**
+   * 读取 state（同步读取，始终返回最新值）。
+   * @returns 对应 key 的当前值，不存在则返回 undefined
+   */
+  getState(key) {
+    return __privateGet(this, _state).get(key);
+  }
+  /**
+   * 导出完整 state 快照（调试/devtools 用）。
+   * 返回每个 key 的当前值、所属插件和描述信息。
+   */
+  dumpState() {
+    const result = {};
+    for (const [key, value] of __privateGet(this, _state)) {
+      const meta = __privateGet(this, _stateMeta).get(key);
+      result[key] = { value, owner: meta.owner, description: meta.description };
+    }
+    return result;
+  }
   /** 同步渲染一帧。适用于静态内容，仅重绘脏层 */
   render() {
     for (const layer of this.scene.layers) {
@@ -2759,10 +2892,12 @@ var _App = class _App {
       }
     }
   }
-  /** 请求异步渲染循环（rAF），有动画时自动继续，无变化时停止 */
+  /** 请求异步渲染帧（幂等，一帧只执行一次）。无变化时自动停止 rAF 链 */
   requestRender() {
-    if (__privateGet(this, _rafId) !== null) return;
-    __privateSet(this, _rafId, requestAnimationFrame((t) => __privateMethod(this, _App_instances, tick_fn).call(this, t)));
+    __privateSet(this, _renderDirty, true);
+    if (__privateGet(this, _rafId) === null) {
+      __privateSet(this, _rafId, requestAnimationFrame((t) => __privateMethod(this, _App_instances, frame_fn).call(this, t)));
+    }
   }
   /**
    * 调整画布尺寸，同步更新所有层、容器和视口矩阵
@@ -2803,6 +2938,10 @@ var _App = class _App {
       plugin.dispose?.();
     }
     __privateSet(this, _plugins, []);
+    this.bus.removeAllListeners();
+    __privateGet(this, _state).clear();
+    __privateGet(this, _stateMeta).clear();
+    __privateGet(this, _scheduler).clear();
     if (__privateGet(this, _resizeObserver)) {
       __privateGet(this, _resizeObserver).disconnect();
       __privateSet(this, _resizeObserver, null);
@@ -2837,7 +2976,17 @@ var _App = class _App {
   }
   /** 序列化所有渲染层的场景图为 JSON，可用于保存/回放 */
   toJSON() {
-    return serialize(this.scene.layers, this.cfg.width ?? 800, this.cfg.height ?? 600);
+    const json = serialize(this.scene.layers, this.cfg.width ?? 800, this.cfg.height ?? 600);
+    const pluginsData = {};
+    for (const plugin of __privateGet(this, _plugins)) {
+      if (plugin.serialize) {
+        pluginsData[plugin.name] = plugin.serialize();
+      }
+    }
+    if (Object.keys(pluginsData).length > 0) {
+      json.plugins = pluginsData;
+    }
+    return json;
   }
   /**
    * 从 JSON 快照创建新的 App 实例（静态工厂方法）
@@ -2876,17 +3025,49 @@ var _App = class _App {
         __privateGet(this, _container).insertBefore(layer.renderer.el, __privateGet(this, _eventLayer).renderer.el);
       }
     }
+    if (json.plugins) {
+      for (const plugin of __privateGet(this, _plugins)) {
+        const data = json.plugins[plugin.name];
+        if (data && plugin.deserialize) {
+          plugin.deserialize(data);
+        }
+      }
+    }
   }
 };
 _rafId = new WeakMap();
+_renderDirty = new WeakMap();
 _mounted = new WeakMap();
 _container = new WeakMap();
 _eventLayer = new WeakMap();
 _resizeObserver = new WeakMap();
 _plugins = new WeakMap();
+_state = new WeakMap();
+_stateMeta = new WeakMap();
+_scheduler = new WeakMap();
 _App_instances = new WeakSet();
-tick_fn = function(time) {
-  __privateSet(this, _rafId, null);
+/**
+ * 解析 zIndex：若已被占用则向上偏移到最近可用值。
+ * 保证返回值不会与任何已有层的 layerIndex 冲突。
+ */
+resolveIndex_fn = function(desired) {
+  const used = new Set(this.scene.layers.map((l) => l.layerIndex));
+  while (used.has(desired)) desired++;
+  return desired;
+};
+/**
+ * 自动分配：当前最高非事件层 index + 1。
+ * 保证返回值始终 >= 1（default 层固定为 0）。
+ */
+nextAvailableIndex_fn = function() {
+  let max = 0;
+  for (const l of this.scene.layers) {
+    if (!l.isEventLayer && l.layerIndex > max) max = l.layerIndex;
+  }
+  return max + 1;
+};
+frame_fn = function(time) {
+  __privateSet(this, _renderDirty, false);
   this.scene.tick(time);
   let anyDirty = false;
   for (const layer of this.scene.layers) {
@@ -2895,8 +3076,10 @@ tick_fn = function(time) {
       anyDirty = true;
     }
   }
-  if (anyDirty) {
-    this.requestRender();
+  if (anyDirty || __privateGet(this, _renderDirty)) {
+    __privateSet(this, _rafId, requestAnimationFrame((t) => __privateMethod(this, _App_instances, frame_fn).call(this, t)));
+  } else {
+    __privateSet(this, _rafId, null);
   }
 };
 var App = _App;
@@ -2927,6 +3110,7 @@ export {
   Renderer,
   RoundShape,
   Scene,
+  Scheduler,
   SectorShape,
   SectorTransform,
   Shape,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rendx-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "2D scene graph engine with animation, events, and plugin system",
   "license": "MIT",
   "author": "wei.liang (https://github.com/weiliang0121)",
@@ -32,14 +32,14 @@
   "dependencies": {
     "eventemitter3": "^5.0.4",
     "gl-matrix": "^3.4.4",
-    "rendx-bounding": "^0.1.0",
-    "rendx-canvas": "^0.1.0",
-    "rendx-ease": "^0.1.0",
-    "rendx-interpolate": "^0.1.0",
-    "rendx-path": "^0.1.0",
-    "rendx-shape": "^0.1.0",
-    "rendx-svg": "^0.1.0",
-    "rendx-core": "^0.1.0"
+    "rendx-bounding": "^0.1.1",
+    "rendx-canvas": "^0.1.1",
+    "rendx-ease": "^0.1.1",
+    "rendx-interpolate": "^0.1.1",
+    "rendx-path": "^0.1.1",
+    "rendx-shape": "^0.1.1",
+    "rendx-svg": "^0.1.1",
+    "rendx-core": "^0.1.1"
   },
   "sideEffects": false,
   "files": [