ice-render 2.0.0 → 2.0.1

package/dist/types/ICE.d.mts

@@ -80,6 +80,18 @@ declare class ICE {
     typeMapping: Record<string, any>;
     /** 构造函数 → 类型名 的反查表（序列化用）。惰性构建，registerType/init 后失效重建。 */
     private __typeIdMapping;
+    /**
+     * 文档级元信息（当前只有 `createTime`）。
+     *
+     * 语义：**首次创建时间跨「打开 → 再保存」保留**。
+     * - `Deserializer` 读到合法 `createTime` 时写在这里（归一化成 ISO 8601 UTC）；
+     * - `Serializer` 写出时优先用它，`lastModifyTime` 才是"这一次写出的时刻"；
+     * - `clearAll()` 清空场景时一并清掉（清空后新建的内容属于新文档，不该继承旧文档的创建时间）；
+     * - 因此"打开 A → 编辑 → 保存"里 `createTime` 稳定不变，只有 `lastModifyTime` 前进。
+     */
+    documentMeta: {
+        createTime?: string;
+    };
     renderer: any;
     animationManager: AnimationManager;
     eventDispatcher: DOMEventDispatcher;

package/dist/types/ICE.d.ts

@@ -80,6 +80,18 @@ declare class ICE {
     typeMapping: Record<string, any>;
     /** 构造函数 → 类型名 的反查表（序列化用）。惰性构建，registerType/init 后失效重建。 */
     private __typeIdMapping;
+    /**
+     * 文档级元信息（当前只有 `createTime`）。
+     *
+     * 语义：**首次创建时间跨「打开 → 再保存」保留**。
+     * - `Deserializer` 读到合法 `createTime` 时写在这里（归一化成 ISO 8601 UTC）；
+     * - `Serializer` 写出时优先用它，`lastModifyTime` 才是"这一次写出的时刻"；
+     * - `clearAll()` 清空场景时一并清掉（清空后新建的内容属于新文档，不该继承旧文档的创建时间）；
+     * - 因此"打开 A → 编辑 → 保存"里 `createTime` 稳定不变，只有 `lastModifyTime` 前进。
+     */
+    documentMeta: {
+        createTime?: string;
+    };
     renderer: any;
     animationManager: AnimationManager;
     eventDispatcher: DOMEventDispatcher;

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

@@ -23,6 +23,13 @@ export default class Deserializer {
     private _unknownTypes;
     get unknownTypes(): string[];
     fromJSONObject(jsonObj: any): void;
+    /**
+     * 记住文档的「首次创建时间」，供之后 `Serializer` 沿用（见 `ICE.documentMeta`）。
+     *
+     * - 旧数据里的 `2022/1/1 00:00:00` 这类历史格式会被归一化成 ISO 8601 UTC；
+     * - 数据里没有 / 解析不了 → 清掉，让下一次写出取当前时刻（避免沿用上一个文档的时间）。
+     */
+    private __rememberCreateTime;
     fromJSONString(jsonStr: string): void;
     /**
      * 版本迁移钩子：当序列化格式版本变化时，在此处按版本逐级升级数据结构。

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

@@ -23,6 +23,13 @@ export default class Deserializer {
     private _unknownTypes;
     get unknownTypes(): string[];
     fromJSONObject(jsonObj: any): void;
+    /**
+     * 记住文档的「首次创建时间」，供之后 `Serializer` 沿用（见 `ICE.documentMeta`）。
+     *
+     * - 旧数据里的 `2022/1/1 00:00:00` 这类历史格式会被归一化成 ISO 8601 UTC；
+     * - 数据里没有 / 解析不了 → 清掉，让下一次写出取当前时刻（避免沿用上一个文档的时间）。
+     */
+    private __rememberCreateTime;
     fromJSONString(jsonStr: string): void;
     /**
      * 版本迁移钩子：当序列化格式版本变化时，在此处按版本逐级升级数据结构。

package/dist/types/persistence/document-time.d.mts

@@ -0,0 +1,16 @@
+/**
+ * 文档时间戳工具。
+ *
+ * 序列化产物里的 `createTime` / `lastModifyTime` 统一是 **ISO 8601 UTC**
+ * （`2026-09-13T04:12:33.123Z`）：与运行环境的语言/时区无关、定长、字典序即时间序、任何工具都能解析。
+ *
+ * 但读进来的数据可能是历史格式（例如 `2022/1/1 00:00:00`），所以这里统一做一次归一化：
+ * 能解析成合法时间就转成 ISO，解析不了就当作"没有这个信息"（调用方回退到当前时刻）。
+ */
+/**
+ * 把任意历史时间值归一化成 ISO 8601 UTC 字符串。
+ *
+ * @param value 待归一化的值（字符串 / 数字 / Date 都可以，其它类型一律视为无值）
+ * @returns ISO 字符串；无法解析时返回 `undefined`
+ */
+export declare function toIsoTime(value: unknown): string | undefined;

package/dist/types/persistence/document-time.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 文档时间戳工具。
+ *
+ * 序列化产物里的 `createTime` / `lastModifyTime` 统一是 **ISO 8601 UTC**
+ * （`2026-09-13T04:12:33.123Z`）：与运行环境的语言/时区无关、定长、字典序即时间序、任何工具都能解析。
+ *
+ * 但读进来的数据可能是历史格式（例如 `2022/1/1 00:00:00`），所以这里统一做一次归一化：
+ * 能解析成合法时间就转成 ISO，解析不了就当作"没有这个信息"（调用方回退到当前时刻）。
+ */
+/**
+ * 把任意历史时间值归一化成 ISO 8601 UTC 字符串。
+ *
+ * @param value 待归一化的值（字符串 / 数字 / Date 都可以，其它类型一律视为无值）
+ * @returns ISO 字符串；无法解析时返回 `undefined`
+ */
+export declare function toIsoTime(value: unknown): string | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-render",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A canvas engine for interactive graphics.",
   "repository": {
     "type": "git",