ice-render 1.4.10 → 2.0.0

package/dist/types/ICE.d.mts

@@ -70,7 +70,14 @@ declare class ICE {
      * （见 `addChild` / `addTool` 中的 `__reapplyPreset`）。
      */
     theme: ICETheme;
-    typeMapping: {};
+    /**
+     * 类型名（canonical typeId，`namespace:Type`）与构造函数之间的映射关系。
+     *
+     * 序列化时由构造函数反查类型名，反序列化时由类型名取出构造函数。
+     * 用**无原型对象**承载：否则 `getType('constructor')` / `getType('toString')`
+     * 这类历史脏数据会命中 `Object.prototype` 上的成员，拿到一个非构造函数的东西。
+     */
+    typeMapping: Record<string, any>;
     /** 构造函数 → 类型名 的反查表（序列化用）。惰性构建，registerType/init 后失效重建。 */
     private __typeIdMapping;
     renderer: any;
@@ -170,19 +177,27 @@ declare class ICE {
     /**
      * @method registerType 注册组件类型
      *
-     * - 需要在反序列化之前调用，否则无法反序列化。
-     * - ICE 内置的类型已经自动注册，不需要手动注册。
+     * 类型标识必须使用 `namespace:Type` 格式（例：`ice-render:Rect`、`my-app:Badge`）。
      *
-     * @param className
-     * @param Clazz
+     * 冲突策略（全部**明确抛错**，绝不静默覆盖）：
+     * - 同一 typeId + 同一构造函数：幂等，不抛错（多入口 / 热更新会重复调用）；
+     * - 同一 typeId + 不同构造函数：抛错；
+     * - 同一构造函数注册第二个 typeId：抛错（否则 getTypeId 反查歧义，写出哪个名字取决于注册顺序）。
+     *
+     * 类型名**只有 canonical 一种形式**：引擎不做「旧的无 namespace 类名」兼容
+     * （ICE 家族仍在发布初期，用旧的只有自己的示例与测试，直接改名比养一套别名简单）。
      */
-    registerType(className: string, Clazz: new (...args: any[]) => any): void;
+    registerType(typeId: string, Clazz: new (...args: any[]) => any): void;
+    /** 是否注册了某个 canonical typeId。 */
+    hasType(typeId: string): boolean;
+    /** 当前实例的 canonical typeId 列表（快照）。 */
+    getRegisteredTypeIds(): string[];
     /**
      * 由构造函数反查稳定的类型名（序列化用）。
      *
-     * - 已注册的类型：返回注册名（与类的 JS 名解耦，压缩改名不影响已存数据）
+     * - 已注册的类型：返回 canonical typeId（`namespace:Type`，与类的 JS 名解耦，压缩改名不影响已存数据）
      * - 未注册：返回 undefined，调用方回退到 `constructor.name`（保持既有行为）
-     * - 同一个构造函数注册了多个名字时，**先注册的优先**（内置类型因此不会被别名顶掉）
+     * - 一个构造函数只可能有一个 canonical typeId（重复注册会抛错，见 registerType）
      */
     getTypeId(Clazz: new (...args: any[]) => any): string | undefined;
     /**
@@ -229,11 +244,17 @@ declare class ICE {
     /** 当前键盘焦点组件（未设置时为 null）。 */
     getFocusedComponent(): any;
     /**
+     * 根据类型名取构造函数（反序列化用）。
+     *
+     * 类型名**只有 canonical 一种形式**（`namespace:Type`）：注册表里没有的名字一律返回
+     * undefined（`Deserializer` 会把该节点记入 `unknownTypes` 并跳过）。因此引擎不做
+     * 「旧的无 namespace 类名」兼容 —— 那是另一条迟早要还的技术债。
+     *
      * @method getType 获取组件构造函数
-     * @param className
-     * @returns
+     * @param typeId canonical typeId（`namespace:Type`）
+     * @returns 构造函数；未注册时返回 undefined
      */
-    getType(className: string): any;
+    getType(typeId: string): any;
     /**
      * 加载自定义字体（平台适配）：浏览器走 FontFace API，小程序走 wx.loadFont。
      * 加载后，在 ICEText 的 style.fontFamily 里引用该字体名即可。

package/dist/types/ICE.d.ts

@@ -70,7 +70,14 @@ declare class ICE {
      * （见 `addChild` / `addTool` 中的 `__reapplyPreset`）。
      */
     theme: ICETheme;
-    typeMapping: {};
+    /**
+     * 类型名（canonical typeId，`namespace:Type`）与构造函数之间的映射关系。
+     *
+     * 序列化时由构造函数反查类型名，反序列化时由类型名取出构造函数。
+     * 用**无原型对象**承载：否则 `getType('constructor')` / `getType('toString')`
+     * 这类历史脏数据会命中 `Object.prototype` 上的成员，拿到一个非构造函数的东西。
+     */
+    typeMapping: Record<string, any>;
     /** 构造函数 → 类型名 的反查表（序列化用）。惰性构建，registerType/init 后失效重建。 */
     private __typeIdMapping;
     renderer: any;
@@ -170,19 +177,27 @@ declare class ICE {
     /**
      * @method registerType 注册组件类型
      *
-     * - 需要在反序列化之前调用，否则无法反序列化。
-     * - ICE 内置的类型已经自动注册，不需要手动注册。
+     * 类型标识必须使用 `namespace:Type` 格式（例：`ice-render:Rect`、`my-app:Badge`）。
      *
-     * @param className
-     * @param Clazz
+     * 冲突策略（全部**明确抛错**，绝不静默覆盖）：
+     * - 同一 typeId + 同一构造函数：幂等，不抛错（多入口 / 热更新会重复调用）；
+     * - 同一 typeId + 不同构造函数：抛错；
+     * - 同一构造函数注册第二个 typeId：抛错（否则 getTypeId 反查歧义，写出哪个名字取决于注册顺序）。
+     *
+     * 类型名**只有 canonical 一种形式**：引擎不做「旧的无 namespace 类名」兼容
+     * （ICE 家族仍在发布初期，用旧的只有自己的示例与测试，直接改名比养一套别名简单）。
      */
-    registerType(className: string, Clazz: new (...args: any[]) => any): void;
+    registerType(typeId: string, Clazz: new (...args: any[]) => any): void;
+    /** 是否注册了某个 canonical typeId。 */
+    hasType(typeId: string): boolean;
+    /** 当前实例的 canonical typeId 列表（快照）。 */
+    getRegisteredTypeIds(): string[];
     /**
      * 由构造函数反查稳定的类型名（序列化用）。
      *
-     * - 已注册的类型：返回注册名（与类的 JS 名解耦，压缩改名不影响已存数据）
+     * - 已注册的类型：返回 canonical typeId（`namespace:Type`，与类的 JS 名解耦，压缩改名不影响已存数据）
      * - 未注册：返回 undefined，调用方回退到 `constructor.name`（保持既有行为）
-     * - 同一个构造函数注册了多个名字时，**先注册的优先**（内置类型因此不会被别名顶掉）
+     * - 一个构造函数只可能有一个 canonical typeId（重复注册会抛错，见 registerType）
      */
     getTypeId(Clazz: new (...args: any[]) => any): string | undefined;
     /**
@@ -229,11 +244,17 @@ declare class ICE {
     /** 当前键盘焦点组件（未设置时为 null）。 */
     getFocusedComponent(): any;
     /**
+     * 根据类型名取构造函数（反序列化用）。
+     *
+     * 类型名**只有 canonical 一种形式**（`namespace:Type`）：注册表里没有的名字一律返回
+     * undefined（`Deserializer` 会把该节点记入 `unknownTypes` 并跳过）。因此引擎不做
+     * 「旧的无 namespace 类名」兼容 —— 那是另一条迟早要还的技术债。
+     *
      * @method getType 获取组件构造函数
-     * @param className
-     * @returns
+     * @param typeId canonical typeId（`namespace:Type`）
+     * @returns 构造函数；未注册时返回 undefined
      */
-    getType(className: string): any;
+    getType(typeId: string): any;
     /**
      * 加载自定义字体（平台适配）：浏览器走 FontFace API，小程序走 wx.loadFont。
      * 加载后，在 ICEText 的 style.fontFamily 里引用该字体名即可。

package/dist/types/consts/COMPONENT_TYPE_MAPPING.d.mts

@@ -5,41 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-import ICEGroup from '../graphic/container/ICEGroup.mjs';
-import ICEImage from '../graphic/ICEImage.mjs';
-import ICEBezier from '../graphic/link/ICEBezier.mjs';
-import ICEPolyLine from '../graphic/link/ICEPolyLine.mjs';
-import ICEVisioLink from '../graphic/link/ICEVisioLink.mjs';
-import ICECircle from '../graphic/shape/ICECircle.mjs';
-import ICEEllipse from '../graphic/shape/ICEEllipse.mjs';
-import ICEIsogon from '../graphic/shape/ICEIsogon.mjs';
-import ICERect from '../graphic/shape/ICERect.mjs';
-import ICERose from '../graphic/shape/ICERose.mjs';
-import ICEStar from '../graphic/shape/ICEStar.mjs';
-import ICEText from '../graphic/text/ICEText.mjs';
 /**
  * 组件名称和构造函数引用之间的映射关系，把序列化之后的 JSON 字符串重新解析成图形时需要用到此映射关系。
  *
- * key 是**稳定的类型名（typeId）**，与类的 JS 名解耦：序列化时由构造函数反查这张表得到 typeId，
- * 因此压缩/改名（terser mangle）不会破坏已存数据；只有**未注册**的类型才回退到 `constructor.name`。
- * 表里的 key 同时充当反序列化的查找键，所以旧数据里写类名的历史格式仍然能加载。
+ * key 是**稳定的类型名（typeId）**，格式为 `namespace:Type`，与类的 JS 名解耦：序列化时由构造函数
+ * 反查这张表得到 typeId，因此压缩/改名（terser mangle）不会破坏已存数据；只有**未注册**的类型
+ * 才回退到 `constructor.name`（此时 `Serializer.unregisteredTypes` 会记录并告警）。
  *
  * 注意：工具层组件（ICELinkSlot / ICELinkHook / 各类 ControlPanel）不进这张表，它们不被序列化。
  *
  * @author 大漠穷秋<damoqiongqiu@126.com>
  */
-declare const componentTypeMap: {
-    ICERect: typeof ICERect;
-    ICECircle: typeof ICECircle;
-    ICEEllipse: typeof ICEEllipse;
-    ICEStar: typeof ICEStar;
-    ICEIsogon: typeof ICEIsogon;
-    ICERose: typeof ICERose;
-    ICEText: typeof ICEText;
-    ICEImage: typeof ICEImage;
-    ICEGroup: typeof ICEGroup;
-    ICEVisioLink: typeof ICEVisioLink;
-    ICEPolyLine: typeof ICEPolyLine;
-    ICEBezier: typeof ICEBezier;
-};
+export interface ComponentTypeEntry {
+    typeId: string;
+    ctor: any;
+}
+/**
+ * 内置类型的注册表：typeId 统一为 `ice-render:Type`（引擎自己的 namespace）。
+ */
+export declare const componentTypeEntries: ComponentTypeEntry[];
+declare const componentTypeMap: Record<string, any>;
 export default componentTypeMap;

package/dist/types/consts/COMPONENT_TYPE_MAPPING.d.ts

@@ -5,41 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-import ICEGroup from '../graphic/container/ICEGroup';
-import ICEImage from '../graphic/ICEImage';
-import ICEBezier from '../graphic/link/ICEBezier';
-import ICEPolyLine from '../graphic/link/ICEPolyLine';
-import ICEVisioLink from '../graphic/link/ICEVisioLink';
-import ICECircle from '../graphic/shape/ICECircle';
-import ICEEllipse from '../graphic/shape/ICEEllipse';
-import ICEIsogon from '../graphic/shape/ICEIsogon';
-import ICERect from '../graphic/shape/ICERect';
-import ICERose from '../graphic/shape/ICERose';
-import ICEStar from '../graphic/shape/ICEStar';
-import ICEText from '../graphic/text/ICEText';
 /**
  * 组件名称和构造函数引用之间的映射关系，把序列化之后的 JSON 字符串重新解析成图形时需要用到此映射关系。
  *
- * key 是**稳定的类型名（typeId）**，与类的 JS 名解耦：序列化时由构造函数反查这张表得到 typeId，
- * 因此压缩/改名（terser mangle）不会破坏已存数据；只有**未注册**的类型才回退到 `constructor.name`。
- * 表里的 key 同时充当反序列化的查找键，所以旧数据里写类名的历史格式仍然能加载。
+ * key 是**稳定的类型名（typeId）**，格式为 `namespace:Type`，与类的 JS 名解耦：序列化时由构造函数
+ * 反查这张表得到 typeId，因此压缩/改名（terser mangle）不会破坏已存数据；只有**未注册**的类型
+ * 才回退到 `constructor.name`（此时 `Serializer.unregisteredTypes` 会记录并告警）。
  *
  * 注意：工具层组件（ICELinkSlot / ICELinkHook / 各类 ControlPanel）不进这张表，它们不被序列化。
  *
  * @author 大漠穷秋<damoqiongqiu@126.com>
  */
-declare const componentTypeMap: {
-    ICERect: typeof ICERect;
-    ICECircle: typeof ICECircle;
-    ICEEllipse: typeof ICEEllipse;
-    ICEStar: typeof ICEStar;
-    ICEIsogon: typeof ICEIsogon;
-    ICERose: typeof ICERose;
-    ICEText: typeof ICEText;
-    ICEImage: typeof ICEImage;
-    ICEGroup: typeof ICEGroup;
-    ICEVisioLink: typeof ICEVisioLink;
-    ICEPolyLine: typeof ICEPolyLine;
-    ICEBezier: typeof ICEBezier;
-};
+export interface ComponentTypeEntry {
+    typeId: string;
+    ctor: any;
+}
+/**
+ * 内置类型的注册表：typeId 统一为 `ice-render:Type`（引擎自己的 namespace）。
+ */
+export declare const componentTypeEntries: ComponentTypeEntry[];
+declare const componentTypeMap: Record<string, any>;
 export default componentTypeMap;

package/dist/types/index.d.mts

@@ -55,5 +55,6 @@ export { default as PluginHost } from './plugin/PluginHost.mjs';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost.mjs';
 export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer.mjs';
 export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer.mjs';
+export { TYPE_ID_PATTERN, isTypeId, assertTypeId, parseTypeId, makeTypeId } from './util/type-id.mjs';
 export { buildAccessibilityTree } from './a11y/accessibility.mjs';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility.mjs';

package/dist/types/index.d.ts

@@ -55,5 +55,6 @@ export { default as PluginHost } from './plugin/PluginHost';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost';
 export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer';
 export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer';
+export { TYPE_ID_PATTERN, isTypeId, assertTypeId, parseTypeId, makeTypeId } from './util/type-id';
 export { buildAccessibilityTree } from './a11y/accessibility';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility';

package/dist/types/persistence/Serializer.d.mts

@@ -11,6 +11,15 @@ export declare const SERIALIZATION_VERSION = 1;
  */
 export default class Serializer {
     private ice;
+    /**
+     * 本次序列化中遇到的、未注册的组件类型名（去重）。
+     *
+     * 未注册类型只能回退写出 `constructor.name`，而下游打包器会 mangle 类名——写出去的
+     * 名字**下次不一定读得回来**。这里记录并告警，让应用层有机会提示用户先
+     * `ice.registerType('your-namespace:Type', Type)`。
+     */
+    private _unregisteredTypes;
+    get unregisteredTypes(): string[];
     constructor(ice: any);
     /**
      * 把对象序列化成 JSON 字符串：

package/dist/types/persistence/Serializer.d.ts

@@ -11,6 +11,15 @@ export declare const SERIALIZATION_VERSION = 1;
  */
 export default class Serializer {
     private ice;
+    /**
+     * 本次序列化中遇到的、未注册的组件类型名（去重）。
+     *
+     * 未注册类型只能回退写出 `constructor.name`，而下游打包器会 mangle 类名——写出去的
+     * 名字**下次不一定读得回来**。这里记录并告警，让应用层有机会提示用户先
+     * `ice.registerType('your-namespace:Type', Type)`。
+     */
+    private _unregisteredTypes;
+    get unregisteredTypes(): string[];
     constructor(ice: any);
     /**
      * 把对象序列化成 JSON 字符串：

package/dist/types/plugin/PluginHost.d.mts

@@ -3,7 +3,9 @@
  *
  * 设计取向与 09-roadmap 的边界一致——**只提供原语，不做应用层 UX**：
  * - 组件层：插件声明自定义图元类型，宿主代为 `registerType`（因此自动获得
- *   序列化 typeId 反查能力，见 `ICE.getTypeId`）。
+ *   序列化 typeId 反查能力，见 `ICE.getTypeId`）。声明键必须是 `namespace:Type`
+ *   格式的 canonical typeId；格式非法或与已注册类型冲突时明确抛错，并把插件名
+ *   带上（否则插件作者无从判断是哪个插件注册失败）。
  * - 渲染层：插件拿到每帧的绘制回调，在与组件相同的坐标系（世界坐标）下叠加绘制。
  *   局部重绘帧里回调在 clip 之内执行，语义与组件一致（超出脏区域的旧内容不会被擦除也不会被重画；
  *   若插件内容会随时间变化而没有任何组件变脏，引擎本身会因「无脏组件」回退全量，仍然正确）。
@@ -45,7 +47,9 @@ export interface ICEPluginTool {
 export interface ICEPlugin {
     /** 插件唯一名（幂等注册键） */
     name: string;
-    /** 组件层：typeId → 构造函数 */
+    /**
+     * 组件层：canonical typeId（`namespace:Type`）→ 构造函数。例：`{ 'my-app:Badge': Badge }`。
+     */
     components?: Record<string, new (...args: any[]) => any>;
     /** 渲染层：每帧绘制回调（世界坐标） */
     render?: ICERenderHook;

package/dist/types/plugin/PluginHost.d.ts

@@ -3,7 +3,9 @@
  *
  * 设计取向与 09-roadmap 的边界一致——**只提供原语，不做应用层 UX**：
  * - 组件层：插件声明自定义图元类型，宿主代为 `registerType`（因此自动获得
- *   序列化 typeId 反查能力，见 `ICE.getTypeId`）。
+ *   序列化 typeId 反查能力，见 `ICE.getTypeId`）。声明键必须是 `namespace:Type`
+ *   格式的 canonical typeId；格式非法或与已注册类型冲突时明确抛错，并把插件名
+ *   带上（否则插件作者无从判断是哪个插件注册失败）。
  * - 渲染层：插件拿到每帧的绘制回调，在与组件相同的坐标系（世界坐标）下叠加绘制。
  *   局部重绘帧里回调在 clip 之内执行，语义与组件一致（超出脏区域的旧内容不会被擦除也不会被重画；
  *   若插件内容会随时间变化而没有任何组件变脏，引擎本身会因「无脏组件」回退全量，仍然正确）。
@@ -45,7 +47,9 @@ export interface ICEPluginTool {
 export interface ICEPlugin {
     /** 插件唯一名（幂等注册键） */
     name: string;
-    /** 组件层：typeId → 构造函数 */
+    /**
+     * 组件层：canonical typeId（`namespace:Type`）→ 构造函数。例：`{ 'my-app:Badge': Badge }`。
+     */
     components?: Record<string, new (...args: any[]) => any>;
     /** 渲染层：每帧绘制回调（世界坐标） */
     render?: ICERenderHook;

package/dist/types/util/type-id.d.mts

@@ -0,0 +1,19 @@
+/**
+ * 组件类型标识（typeId）的格式契约。
+ *
+ * 统一格式：`namespace:Type`
+ *
+ * - namespace：小写字母开头，只允许小写字母、数字、连字符。
+ * - Type：字母或下划线开头，允许字母、数字、下划线、连字符。
+ *
+ * 例：`ice-render:Rect`、`ice-entity-designer:FlowNode`、
+ * `ice-chart:PlotArea`、`my-company:Widget`。
+ */
+export declare const TYPE_ID_PATTERN: RegExp;
+export declare function isTypeId(value: unknown): value is string;
+export declare function assertTypeId(value: unknown, label?: string): asserts value is string;
+export declare function parseTypeId(typeId: string): {
+    namespace: string;
+    type: string;
+};
+export declare function makeTypeId(namespace: string, type: string): string;

package/dist/types/util/type-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 组件类型标识（typeId）的格式契约。
+ *
+ * 统一格式：`namespace:Type`
+ *
+ * - namespace：小写字母开头，只允许小写字母、数字、连字符。
+ * - Type：字母或下划线开头，允许字母、数字、下划线、连字符。
+ *
+ * 例：`ice-render:Rect`、`ice-entity-designer:FlowNode`、
+ * `ice-chart:PlotArea`、`my-company:Widget`。
+ */
+export declare const TYPE_ID_PATTERN: RegExp;
+export declare function isTypeId(value: unknown): value is string;
+export declare function assertTypeId(value: unknown, label?: string): asserts value is string;
+export declare function parseTypeId(typeId: string): {
+    namespace: string;
+    type: string;
+};
+export declare function makeTypeId(namespace: string, type: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-render",
-  "version": "1.4.10",
+  "version": "2.0.0",
   "description": "A canvas engine for interactive graphics.",
   "repository": {
     "type": "git",
@@ -64,7 +64,7 @@
     "@commitlint/config-conventional": "17.8.1",
     "@playwright/test": "^1.40.0",
     "@rollup/plugin-babel": "6.1.0",
-    "@rollup/plugin-commonjs": "25.0.8",
+    "@rollup/plugin-commonjs": "28.0.1",
     "@rollup/plugin-json": "6.1.0",
     "@rollup/plugin-node-resolve": "15.3.1",
     "@rollup/plugin-strip": "3.0.4",
@@ -73,6 +73,7 @@
     "@types/node": "18.19.130",
     "@typescript-eslint/eslint-plugin": "6.21.0",
     "@typescript-eslint/parser": "6.21.0",
+    "babel-jest": "29.7.0",
     "eslint": "8.57.1",
     "eslint-config-prettier": "9.1.2",
     "eslint-plugin-jest": "27.9.0",
@@ -108,7 +109,7 @@
     ]
   },
   "engines": {
-    "npm": ">=6.4.1",
+    "npm": ">=9",
     "node": ">=18"
   },
   "license": "MIT",