rendx-engine 0.2.0 → 0.4.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,
@@ -476,7 +477,7 @@ getEmitter_fn = function() {
 };
 
 // src/core/graphics.ts
-var _nameMap, _classlist, _Graphics_instances, removeFromNameMap_fn, updateMat2d_fn, updateWorldMatrix_fn, updateEZ_fn;
+var _nameMap, _classlist, _Graphics_instances, removeFromNameMap_fn, inheritState_fn, updateMat2d_fn, updateWorldMatrix_fn, updateEZ_fn;
 var Graphics = class extends EventTarget {
   constructor() {
     super(...arguments);
@@ -592,6 +593,7 @@ var Graphics = class extends EventTarget {
     this.children.push(child);
     if (__privateGet(this, _nameMap).has(child.name)) throw new Error(`The name "${child.name}" is already used.`);
     if (child.name) __privateGet(this, _nameMap).set(child.name, child);
+    __privateMethod(this, _Graphics_instances, inheritState_fn).call(this, child);
     this.setDirty(true);
     return this;
   }
@@ -600,6 +602,7 @@ var Graphics = class extends EventTarget {
     child.parent = this;
     this.children.unshift(child);
     __privateMethod(this, _Graphics_instances, removeFromNameMap_fn).call(this, child);
+    __privateMethod(this, _Graphics_instances, inheritState_fn).call(this, child);
     this.setDirty(true);
     return this;
   }
@@ -842,6 +845,22 @@ _Graphics_instances = new WeakSet();
 removeFromNameMap_fn = function(g) {
   if (__privateGet(this, _nameMap).has(g.name)) __privateGet(this, _nameMap).delete(g.name);
 };
+/**
+ * 将父节点的可继承状态（visible / display / pointerEvents）传播给新增子节点。
+ * 模拟 DOM 中 CSS 继承属性的行为：
+ * - 父级 pointer-events: none → 子级默认继承 none，除非子级显式覆盖
+ * - 父级 visibility: hidden → 同上
+ * - 父级 display: none → 整棵子树不渲染
+ *
+ * 使用 bySelf=false 调用，尊重子节点的 autoX 标记：
+ * - autoX=true（默认）→ 接受父级值
+ * - autoX=false（子节点显式设置过）→ 保持自身值不变
+ */
+inheritState_fn = function(child) {
+  if (!this.visible) child.setVisible(false, false);
+  if (!this.display) child.setDisplay(false, false);
+  if (!this.pointerEvents) child.setPointerEvents(false, false);
+};
 updateMat2d_fn = function() {
   if (!this.needUpdate) return;
   import_gl_matrix.mat2d.identity(this.matrix);
@@ -1251,7 +1270,7 @@ var Group = class extends Graphics {
 
 // src/scene/node.ts
 var import_gl_matrix3 = require("gl-matrix");
-var import_rendx_bounding15 = require("rendx-bounding");
+var import_rendx_bounding16 = require("rendx-bounding");
 
 // src/shapes/symbol.ts
 var import_rendx_bounding2 = require("rendx-bounding");
@@ -1648,6 +1667,8 @@ var ArcShape = class extends Shape {
 };
 
 // src/shapes/path.ts
+var import_rendx_bounding9 = require("rendx-bounding");
+var import_rendx_path9 = require("rendx-path");
 var PathShape = class extends Shape {
   constructor() {
     super(...arguments);
@@ -1656,11 +1677,19 @@ var PathShape = class extends Shape {
   from(d) {
     this.d = d;
     this.p = null;
+    if (this.autoNeedUpdate) this.needUpdate = true;
+  }
+  box() {
+    const result = (0, import_rendx_path9.pathBBox)(this.d);
+    if (result) {
+      this.boundingBox = import_rendx_bounding9.BoundingBox.fromPoints(result[0], result[1], result[2], result[3]);
+    }
+    return this.boundingBox;
   }
 };
 
 // src/shapes/text.ts
-var import_rendx_bounding9 = require("rendx-bounding");
+var import_rendx_bounding10 = require("rendx-bounding");
 var _attrs;
 var _TextShape = class _TextShape extends Shape {
   constructor() {
@@ -1693,7 +1722,7 @@ var _TextShape = class _TextShape extends Shape {
     if (measureFn && this.text) {
       const bb = measureFn(this.text, __privateGet(this, _attrs));
       if (bb) {
-        this.boundingBox = import_rendx_bounding9.BoundingBox.fromRect(this.x, this.y - bb.height, bb.width, bb.height);
+        this.boundingBox = import_rendx_bounding10.BoundingBox.fromRect(this.x, this.y - bb.height, bb.width, bb.height);
         return this.boundingBox;
       }
     }
@@ -1724,7 +1753,7 @@ _TextShape.defaultMeasure = null;
 var TextShape = _TextShape;
 
 // src/shapes/line.ts
-var import_rendx_bounding10 = require("rendx-bounding");
+var import_rendx_bounding11 = require("rendx-bounding");
 var LineShape = class extends Shape {
   constructor() {
     super(...arguments);
@@ -1756,13 +1785,13 @@ var LineShape = class extends Shape {
   }
   box() {
     const { x1, y1, x2, y2 } = this;
-    this.boundingBox = import_rendx_bounding10.BoundingBox.fromPoints(x1, y1, x2, y2);
+    this.boundingBox = import_rendx_bounding11.BoundingBox.fromPoints(x1, y1, x2, y2);
     return this.boundingBox;
   }
 };
 
 // src/shapes/rect.ts
-var import_rendx_bounding11 = require("rendx-bounding");
+var import_rendx_bounding12 = require("rendx-bounding");
 var RectShape = class extends Shape {
   constructor() {
     super(...arguments);
@@ -1792,13 +1821,13 @@ var RectShape = class extends Shape {
   }
   box() {
     const { x, y, width, height } = this;
-    this.boundingBox = import_rendx_bounding11.BoundingBox.fromRect(x, y, width, height);
+    this.boundingBox = import_rendx_bounding12.BoundingBox.fromRect(x, y, width, height);
     return this.boundingBox;
   }
 };
 
 // src/shapes/circle.ts
-var import_rendx_bounding12 = require("rendx-bounding");
+var import_rendx_bounding13 = require("rendx-bounding");
 var CircleShape = class extends Shape {
   constructor() {
     super(...arguments);
@@ -1825,13 +1854,13 @@ var CircleShape = class extends Shape {
   }
   box() {
     const { cx, cy, r } = this;
-    this.boundingBox = import_rendx_bounding12.BoundingBox.fromPoints(cx - r, cy - r, cx + r, cy + r);
+    this.boundingBox = import_rendx_bounding13.BoundingBox.fromPoints(cx - r, cy - r, cx + r, cy + r);
     return this.boundingBox;
   }
 };
 
 // src/shapes/image.ts
-var import_rendx_bounding13 = require("rendx-bounding");
+var import_rendx_bounding14 = require("rendx-bounding");
 var ImageShape = class extends Shape {
   constructor() {
     super(...arguments);
@@ -1875,15 +1904,15 @@ var ImageShape = class extends Shape {
   }
   box() {
     const { x, y, width, height } = this;
-    this.boundingBox = import_rendx_bounding13.BoundingBox.fromRect(x, y, width, height);
+    this.boundingBox = import_rendx_bounding14.BoundingBox.fromRect(x, y, width, height);
     return this.boundingBox;
   }
 };
 
 // src/shapes/rect-buffer.ts
-var import_rendx_bounding14 = require("rendx-bounding");
+var import_rendx_bounding15 = require("rendx-bounding");
 var import_rendx_shape8 = require("rendx-shape");
-var import_rendx_path9 = require("rendx-path");
+var import_rendx_path10 = require("rendx-path");
 var RectBufferShape = class extends Shape {
   constructor() {
     super(...arguments);
@@ -1900,7 +1929,7 @@ var RectBufferShape = class extends Shape {
   build() {
     if (!this.needUpdate) return;
     if (this.mode === "render") {
-      if (!this.creator) this.creator = new import_rendx_path9.Path();
+      if (!this.creator) this.creator = new import_rendx_path10.Path();
       else this.creator.clear();
       const { buffer } = this;
       for (let i = 0; i < buffer.length; i += 4) {
@@ -1947,7 +1976,7 @@ var RectBufferShape = class extends Shape {
       x1 = Math.max(x1, x + width);
       y1 = Math.max(y1, y + height);
     }
-    this.boundingBox = import_rendx_bounding14.BoundingBox.fromPoints(x0, y0, x1, y1);
+    this.boundingBox = import_rendx_bounding15.BoundingBox.fromPoints(x0, y0, x1, y1);
     return this.boundingBox;
   }
 };
@@ -2050,7 +2079,7 @@ var _Node = class _Node extends Graphics {
     if (wx > maxX) maxX = wx;
     if (wy < minY) minY = wy;
     if (wy > maxY) maxY = wy;
-    return import_rendx_bounding15.BoundingBox.fromPoints(minX, minY, maxX, maxY);
+    return import_rendx_bounding16.BoundingBox.fromPoints(minX, minY, maxX, maxY);
   }
   /**
    * 命中检测：将屏幕坐标通过逆世界矩阵变换为本地坐标，然后检测是否命中
@@ -2560,6 +2589,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 +2792,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 +2897,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 +2928,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 +2952,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 +2994,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)));
+    }
   }
   /**
    * 调整画布尺寸，同步更新所有层、容器和视口矩阵
@@ -2861,6 +3025,26 @@ var _App = class _App {
       plugin.resize?.(width, height);
     }
   }
+  // ========================
+  // Cursor
+  // ========================
+  /**
+   * 设置容器的鼠标光标样式。
+   * @param cursor - CSS cursor 值（如 'pointer'、'crosshair'、'grab'）
+   */
+  setCursor(cursor) {
+    if (__privateGet(this, _container)) {
+      __privateGet(this, _container).style.cursor = cursor;
+    }
+  }
+  /**
+   * 重置鼠标光标为默认值。
+   */
+  resetCursor() {
+    if (__privateGet(this, _container)) {
+      __privateGet(this, _container).style.cursor = "";
+    }
+  }
   clear() {
     if (__privateGet(this, _rafId) !== null) {
       cancelAnimationFrame(__privateGet(this, _rafId));
@@ -2876,6 +3060,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 +3098,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 +3147,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 +3198,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 +3233,7 @@ var App = _App;
   Renderer,
   RoundShape,
   Scene,
+  Scheduler,
   SectorShape,
   SectorTransform,
   Shape,