@codexo/exojs 0.13.0 → 0.14.0

package/dist/esm/core/serialization/renderingSerializers.js

@@ -0,0 +1,311 @@
+import { Rectangle } from '../../math/Rectangle.js';
+import { Mesh } from '../../rendering/mesh/Mesh.js';
+import { Graphics } from '../../rendering/primitives/Graphics.js';
+import { AnimatedSprite } from '../../rendering/sprite/AnimatedSprite.js';
+import { NineSliceSprite } from '../../rendering/sprite/NineSliceSprite.js';
+import { RepeatingSprite } from '../../rendering/sprite/RepeatingSprite.js';
+import { BitmapText } from '../../rendering/text/BitmapText.js';
+import { BmFont } from '../../rendering/text/BmFont.js';
+import { Texture } from '../../rendering/texture/Texture.js';
+import { Video } from '../../rendering/video/Video.js';
+import { asSerializedNode, asObject, readEnum, asNumberArray, readBoolean, REPEAT_MODES, REPEAT_FITS } from './read.js';
+import { compact, readLayoutOptions, deserializeStyleOptions, serializeStyle } from './serializerHelpers.js';
+
+// ── Small helpers ────────────────────────────────────────────────────────────
+const toF32 = (value) => (Array.isArray(value) ? new Float32Array(value.map(Number)) : new Float32Array());
+const toU16 = (value) => (Array.isArray(value) ? new Uint16Array(value.map(Number)) : new Uint16Array());
+const toU32 = (value) => (Array.isArray(value) ? new Uint32Array(value.map(Number)) : new Uint32Array());
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+/** Read a {@link NineSliceInsets} from JSON, defaulting any missing/invalid edge to 0 (never `undefined` — `slices` is required and `undefined` would crash `normalizeInsets`). */
+const readInsets = (value) => {
+    const source = asObject(value);
+    return {
+        left: num(source?.left) ?? 0,
+        top: num(source?.top) ?? 0,
+        right: num(source?.right) ?? 0,
+        bottom: num(source?.bottom) ?? 0,
+    };
+};
+/** Read {@link NineSliceModes} from JSON, keeping only valid enum fields (invalid ones fall back to the renderer's defaults). */
+const readModes = (value) => {
+    const source = asObject(value);
+    if (source === null) {
+        return undefined;
+    }
+    const out = {};
+    const edges = readEnum(source, 'edges', REPEAT_MODES);
+    if (edges !== undefined)
+        out.edges = edges;
+    const center = readEnum(source, 'center', REPEAT_MODES);
+    if (center !== undefined)
+        out.center = center;
+    const top = readEnum(source, 'top', REPEAT_MODES);
+    if (top !== undefined)
+        out.top = top;
+    const right = readEnum(source, 'right', REPEAT_MODES);
+    if (right !== undefined)
+        out.right = right;
+    const bottom = readEnum(source, 'bottom', REPEAT_MODES);
+    if (bottom !== undefined)
+        out.bottom = bottom;
+    const left = readEnum(source, 'left', REPEAT_MODES);
+    if (left !== undefined)
+        out.left = left;
+    const edgeFit = readEnum(source, 'edgeFit', REPEAT_FITS);
+    if (edgeFit !== undefined)
+        out.edgeFit = edgeFit;
+    const centerFit = readEnum(source, 'centerFit', REPEAT_FITS);
+    if (centerFit !== undefined)
+        out.centerFit = centerFit;
+    return out;
+};
+// ── Mesh ─────────────────────────────────────────────────────────────────────
+const meshSerializer = {
+    write(node, ctx) {
+        const out = { vertices: [...node.vertices] };
+        if (node.indices !== null)
+            out.indices = [...node.indices];
+        if (node.uvs !== null)
+            out.uvs = [...node.uvs];
+        if (node.colors !== null)
+            out.colors = [...node.colors];
+        const source = ctx.keyFor(node.texture);
+        if (source !== null)
+            out.texture = source;
+        if (node.material !== null) ;
+        return out;
+    },
+    read(data, ctx) {
+        return new Mesh(compact({
+            vertices: toF32(data.vertices),
+            indices: data.indices !== undefined ? toU16(data.indices) : undefined,
+            uvs: data.uvs !== undefined ? toF32(data.uvs) : undefined,
+            colors: data.colors !== undefined ? toU32(data.colors) : undefined,
+            texture: ctx.resolveAsset(typeof data.texture === 'string' ? data.texture : null, Texture),
+        }));
+    },
+};
+// ── Graphics ───────────────────────────────────────────────────────────────
+// Graphics is immediate-mode: its authored result is the baked Mesh children it
+// accumulates. Round-trips the rendered geometry (gradient fills, drawn via
+// runtime DataTextures, degrade to their vertex colours — texture refs are
+// unkeyed and dropped). The pen state is transient and not serialized.
+const graphicsSerializer = {
+    write(node, ctx) {
+        if (node.children.length === 0) {
+            return {};
+        }
+        return { children: node.children.map(child => ctx.writeNode(child)) };
+    },
+    read(data, ctx) {
+        const node = new Graphics();
+        const children = data.children;
+        if (Array.isArray(children)) {
+            for (const child of children) {
+                const childNode = asSerializedNode(child);
+                if (childNode !== null)
+                    node.addChild(ctx.readNode(childNode));
+            }
+        }
+        return node;
+    },
+};
+// ── NineSliceSprite ──────────────────────────────────────────────────────────
+const nineSliceSerializer = {
+    write(node, ctx) {
+        const out = {
+            slices: { ...node.slices },
+            border: { ...node.border },
+            modes: { ...node.modes },
+            width: node.width,
+            height: node.height,
+        };
+        const source = ctx.keyFor(node.texture);
+        if (source !== null)
+            out.texture = source;
+        return out;
+    },
+    read(data, ctx) {
+        const texture = ctx.resolveAsset(typeof data.texture === 'string' ? data.texture : null, Texture);
+        if (texture === null) {
+            throw new Error('NineSliceSprite deserialize requires its texture to be pre-loaded into the Loader.');
+        }
+        return new NineSliceSprite(texture, compact({
+            slices: readInsets(data.slices),
+            border: asObject(data.border) !== null ? readInsets(data.border) : undefined,
+            modes: readModes(data.modes),
+            width: num(data.width),
+            height: num(data.height),
+        }));
+    },
+};
+// ── RepeatingSprite ──────────────────────────────────────────────────────────
+const repeatingSerializer = {
+    write(node, ctx) {
+        const out = {
+            width: node.width,
+            height: node.height,
+            modeX: node.modeX,
+            modeY: node.modeY,
+            fitX: node.fitX,
+            fitY: node.fitY,
+            offsetX: node.offsetX,
+            offsetY: node.offsetY,
+        };
+        const source = ctx.keyFor(node.texture);
+        if (source !== null)
+            out.texture = source;
+        return out;
+    },
+    read(data, ctx) {
+        const texture = ctx.resolveAsset(typeof data.texture === 'string' ? data.texture : null, Texture);
+        if (texture === null) {
+            throw new Error('RepeatingSprite deserialize requires its texture to be pre-loaded into the Loader.');
+        }
+        return new RepeatingSprite(texture, compact({
+            width: num(data.width),
+            height: num(data.height),
+            modeX: readEnum(data, 'modeX', REPEAT_MODES),
+            modeY: readEnum(data, 'modeY', REPEAT_MODES),
+            fitX: readEnum(data, 'fitX', REPEAT_FITS),
+            fitY: readEnum(data, 'fitY', REPEAT_FITS),
+            offsetX: num(data.offsetX),
+            offsetY: num(data.offsetY),
+        }));
+    },
+};
+// ── AnimatedSprite ───────────────────────────────────────────────────────────
+// Clips round-trip fully; playback resumes at the active clip's first frame
+// (the exact current frame / elapsed time is runtime state and not restored).
+const animatedSpriteSerializer = {
+    write(node, ctx) {
+        const out = {};
+        const source = ctx.keyFor(node.texture);
+        if (source !== null)
+            out.texture = source;
+        const clips = {};
+        for (const [name, clip] of Object.entries(node._getClipDefinitions())) {
+            clips[name] = {
+                frames: clip.frames.map(frame => [frame.x, frame.y, frame.width, frame.height]),
+                fps: clip.fps,
+                loop: clip.loop,
+            };
+        }
+        out.clips = clips;
+        if (node.currentClip !== null)
+            out.currentClip = node.currentClip;
+        if (node.playing)
+            out.playing = true;
+        return out;
+    },
+    read(data, ctx) {
+        const texture = ctx.resolveAsset(typeof data.texture === 'string' ? data.texture : null, Texture);
+        const clips = {};
+        const clipsData = data.clips;
+        const clipsObject = asObject(clipsData);
+        if (clipsObject !== null) {
+            for (const [name, raw] of Object.entries(clipsObject)) {
+                const clip = asObject(raw);
+                if (clip === null) {
+                    continue;
+                }
+                const frames = Array.isArray(clip.frames)
+                    ? clip.frames.map(frame => {
+                        const values = asNumberArray(frame) ?? [];
+                        return new Rectangle(values[0] ?? 0, values[1] ?? 0, values[2] ?? 0, values[3] ?? 0);
+                    })
+                    : [];
+                clips[name] = compact({ frames, fps: num(clip.fps), loop: readBoolean(clip, 'loop') });
+            }
+        }
+        const sprite = new AnimatedSprite(texture, clips);
+        if (typeof data.currentClip === 'string' && data.currentClip in clips) {
+            sprite.play(data.currentClip);
+            if (data.playing !== true) {
+                sprite.pause();
+            }
+        }
+        return sprite;
+    },
+};
+// ── BitmapText ─────────────────────────────────────────────────────────────
+const bitmapTextSerializer = {
+    write(node, ctx) {
+        const out = { text: node.text };
+        const source = ctx.keyFor(node.font);
+        if (source !== null)
+            out.font = source;
+        if (node.msdf)
+            out.msdf = true;
+        if (node.fontScale !== 1)
+            out.scale = node.fontScale;
+        const style = serializeStyle(node.style);
+        if (style !== undefined)
+            out.style = style;
+        if (Object.keys(node.layout).length > 0)
+            out.layout = { ...node.layout };
+        return out;
+    },
+    read(data, ctx) {
+        const font = ctx.resolveAsset(typeof data.font === 'string' ? data.font : null, BmFont);
+        if (font === null) {
+            throw new Error('BitmapText deserialize requires its BmFont to be pre-loaded into the Loader.');
+        }
+        const layout = readLayoutOptions(data.layout);
+        return new BitmapText(typeof data.text === 'string' ? data.text : '', font, compact({
+            ...deserializeStyleOptions(data.style),
+            msdf: data.msdf === true,
+            scale: num(data.scale),
+            layout,
+        }));
+    },
+};
+// ── Video ────────────────────────────────────────────────────────────────────
+// Captures the source URL + playback options. Deserialize creates a fresh
+// `<video>` element (requires a DOM); the live decode/audio graph is rebuilt by
+// the Video constructor.
+const videoSerializer = {
+    write(node) {
+        const out = { src: node.videoElement.src };
+        if (node.volume !== 1)
+            out.volume = node.volume;
+        if (node.loop)
+            out.loop = true;
+        if (node.playbackRate !== 1)
+            out.playbackRate = node.playbackRate;
+        if (node.muted)
+            out.muted = true;
+        if (node.currentTime > 0)
+            out.time = node.currentTime;
+        return out;
+    },
+    read(data) {
+        const element = document.createElement('video');
+        if (typeof data.src === 'string') {
+            element.src = data.src;
+        }
+        return new Video(element, compact({
+            volume: num(data.volume),
+            loop: data.loop === true ? true : undefined,
+            playbackRate: num(data.playbackRate),
+            muted: data.muted === true ? true : undefined,
+            time: num(data.time),
+        }));
+    },
+};
+/**
+ * Register the rendering-package node serializers on `registry`.
+ * @internal
+ */
+function registerRenderingSerializers(registry) {
+    registry.register('Mesh', Mesh, meshSerializer);
+    registry.register('Graphics', Graphics, graphicsSerializer);
+    registry.register('NineSliceSprite', NineSliceSprite, nineSliceSerializer);
+    registry.register('RepeatingSprite', RepeatingSprite, repeatingSerializer);
+    registry.register('AnimatedSprite', AnimatedSprite, animatedSpriteSerializer);
+    registry.register('BitmapText', BitmapText, bitmapTextSerializer);
+    registry.register('Video', Video, videoSerializer);
+}
+
+export { registerRenderingSerializers };
+//# sourceMappingURL=renderingSerializers.js.map

package/dist/esm/core/serialization/renderingSerializers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderingSerializers.js","sources":["../../../../../src/core/serialization/renderingSerializers.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/core/serialization/serialize.d.ts

@@ -0,0 +1,56 @@
+import type { SceneNode } from '#core/SceneNode';
+import type { Container } from '#rendering/Container';
+import type { Loader } from '#resources/Loader';
+import { type SerializationRegistry } from './SerializationRegistry';
+import { type SerializedNode, type SerializedScene } from './types';
+/**
+ * Reset the process-wide serialization state so test suites do not leak
+ * registrations into one another. Clears both module-level states: the
+ * {@link defaultSerializationRegistry} **and** the `_coreRegistered` latch. Both
+ * are mandatory — clearing the registry alone would leave the latch `true`, so
+ * the core serializers would never re-register and later round-trips would fail
+ * with spurious "No serializer registered" errors.
+ *
+ * Not exported from the public barrel; import via the direct module path in
+ * tests.
+ * @internal — For unit tests only.
+ */
+export declare function _resetDefaultSerializers(): void;
+/**
+ * Serialize a single node and its subtree to a {@link SerializedNode}. Pass a
+ * {@link Loader} so texture/asset references resolve to their source keys.
+ * @internal
+ */
+export declare function serializeTree(node: SceneNode, loader?: Loader | null, registry?: SerializationRegistry): SerializedNode;
+/**
+ * Reconstruct a node subtree from a {@link SerializedNode}. Referenced assets
+ * must be pre-loaded into `loader`.
+ * @internal
+ */
+export declare function deserializeTree(data: SerializedNode, loader?: Loader | null, registry?: SerializationRegistry): SceneNode;
+/**
+ * Rebuild `container`'s contents from `data` in place: clears existing
+ * children, applies `data`'s common fields to the container, then deserializes
+ * and re-adds its children. Used by {@link Scene.deserialize} to reuse the
+ * eagerly-created scene root.
+ * @internal
+ */
+export declare function deserializeInto(container: Container, data: SerializedNode, loader?: Loader | null, registry?: SerializationRegistry): void;
+/**
+ * Validate and migrate a serialized scene document to the current
+ * {@link SERIALIZATION_VERSION}, returning a structurally-sound
+ * {@link SerializedScene}.
+ *
+ * This is the **untrusted top-level boundary**: the parameter is `unknown`
+ * because a save file / cloud document is not guaranteed to match the type. The
+ * frame (`version`/`root`/`ui`) is validated here so downstream `deserialize*`
+ * paths can rely on `root` being a real node. Throws on a non-object document,
+ * a version newer than supported, or a missing/invalid root; an invalid `ui` is
+ * dropped (it is optional) rather than thrown.
+ *
+ * The migration chain is empty at v1; future version bumps register
+ * version→version+1 transforms here.
+ * @internal
+ */
+export declare function migrate(data: unknown): SerializedScene;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/esm/core/serialization/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../../src/core/serialization/serialize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAAY,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAM1D,OAAO,EAAgC,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,EAAyB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAiB3F;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C;AAqFD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,EAAE,QAAQ,GAAE,qBAAoD,GAAG,cAAc,CAI3J;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,EAAE,QAAQ,GAAE,qBAAoD,GAAG,SAAS,CAI7J;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,cAAc,EACpB,MAAM,GAAE,MAAM,GAAG,IAAW,EAC5B,QAAQ,GAAE,qBAAoD,GAC7D,IAAI,CAgBN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAsBtD"}

package/dist/esm/core/serialization/serialize.js

@@ -0,0 +1,144 @@
+import { applyCommonFields, writeCommonFields } from './commonFields.js';
+import { registerCoreSerializers } from './coreSerializers.js';
+import { asSerializedNode, asObject } from './read.js';
+import { defaultSerializationRegistry } from './SerializationRegistry.js';
+import { SERIALIZATION_VERSION } from './types.js';
+
+// Core serializers register lazily (not as an import side effect) so they
+// survive `sideEffects: false` tree-shaking: the registration is reachable
+// only through the framework entry points below, which a consumer must call.
+let _coreRegistered = false;
+/** Idempotently register the built-in node serializers on first use. @internal */
+function ensureCoreSerializers() {
+    if (_coreRegistered) {
+        return;
+    }
+    _coreRegistered = true;
+    registerCoreSerializers(defaultSerializationRegistry);
+}
+function createSerializeContext(loader, registry) {
+    const ctx = {
+        version: SERIALIZATION_VERSION,
+        loader,
+        writeNode: node => writeNodeWith(node, ctx, registry),
+        keyFor: resource => {
+            if (resource === null || resource === undefined || typeof resource !== 'object' || loader === null) {
+                return null;
+            }
+            const key = loader.keyFor(resource);
+            if (key === null) {
+                return null;
+            }
+            return key.source;
+        },
+    };
+    return ctx;
+}
+function createDeserializeContext(loader, version, registry) {
+    const ctx = {
+        version,
+        loader,
+        readNode: data => readNodeWith(data, ctx, registry),
+        resolveAsset: (source, type) => {
+            if (source === null || source === undefined || loader === null) {
+                return null;
+            }
+            const resource = loader.peek(type, source);
+            return resource;
+        },
+    };
+    return ctx;
+}
+function writeNodeWith(node, ctx, registry) {
+    const entry = registry.resolveByNode(node);
+    if (entry === undefined) {
+        throw new Error(`No serializer registered for node type "${node.constructor.name}". Register one via registerSerializer().`);
+    }
+    const out = { type: entry.typeName };
+    writeCommonFields(node, out);
+    Object.assign(out, entry.serializer.write(node, ctx));
+    return out;
+}
+function readNodeWith(data, ctx, registry) {
+    const entry = registry.resolveByName(data.type);
+    if (entry === undefined) {
+        throw new Error(`No serializer registered for type "${data.type}". Register one via registerSerializer().`);
+    }
+    const node = entry.serializer.read(data, ctx);
+    applyCommonFields(node, data);
+    return node;
+}
+/**
+ * Serialize a single node and its subtree to a {@link SerializedNode}. Pass a
+ * {@link Loader} so texture/asset references resolve to their source keys.
+ * @internal
+ */
+function serializeTree(node, loader = null, registry = defaultSerializationRegistry) {
+    ensureCoreSerializers();
+    return writeNodeWith(node, createSerializeContext(loader, registry), registry);
+}
+/**
+ * Reconstruct a node subtree from a {@link SerializedNode}. Referenced assets
+ * must be pre-loaded into `loader`.
+ * @internal
+ */
+function deserializeTree(data, loader = null, registry = defaultSerializationRegistry) {
+    ensureCoreSerializers();
+    return readNodeWith(data, createDeserializeContext(loader, SERIALIZATION_VERSION, registry), registry);
+}
+/**
+ * Rebuild `container`'s contents from `data` in place: clears existing
+ * children, applies `data`'s common fields to the container, then deserializes
+ * and re-adds its children. Used by {@link Scene.deserialize} to reuse the
+ * eagerly-created scene root.
+ * @internal
+ */
+function deserializeInto(container, data, loader = null, registry = defaultSerializationRegistry) {
+    ensureCoreSerializers();
+    const ctx = createDeserializeContext(loader, SERIALIZATION_VERSION, registry);
+    container.removeChildren();
+    applyCommonFields(container, data);
+    const children = data.children;
+    if (Array.isArray(children)) {
+        for (const child of children) {
+            const childNode = asSerializedNode(child);
+            if (childNode !== null)
+                container.addChild(ctx.readNode(childNode));
+        }
+    }
+}
+/**
+ * Validate and migrate a serialized scene document to the current
+ * {@link SERIALIZATION_VERSION}, returning a structurally-sound
+ * {@link SerializedScene}.
+ *
+ * This is the **untrusted top-level boundary**: the parameter is `unknown`
+ * because a save file / cloud document is not guaranteed to match the type. The
+ * frame (`version`/`root`/`ui`) is validated here so downstream `deserialize*`
+ * paths can rely on `root` being a real node. Throws on a non-object document,
+ * a version newer than supported, or a missing/invalid root; an invalid `ui` is
+ * dropped (it is optional) rather than thrown.
+ *
+ * The migration chain is empty at v1; future version bumps register
+ * version→version+1 transforms here.
+ * @internal
+ */
+function migrate(data) {
+    const scene = asObject(data);
+    if (scene === null) {
+        throw new Error('Cannot deserialize scene: the document is not an object.');
+    }
+    const version = typeof scene.version === 'number' ? scene.version : 0;
+    if (version > SERIALIZATION_VERSION) {
+        throw new Error(`Cannot deserialize scene: data version ${version} is newer than the supported version ${SERIALIZATION_VERSION}.`);
+    }
+    const root = asSerializedNode(scene.root);
+    if (root === null) {
+        throw new Error('Cannot deserialize scene: the document has no valid root node.');
+    }
+    const ui = asSerializedNode(scene.ui);
+    return ui !== null ? { version, root, ui } : { version, root };
+}
+
+export { deserializeInto, deserializeTree, migrate, serializeTree };
+//# sourceMappingURL=serialize.js.map

package/dist/esm/core/serialization/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sources":["../../../../../src/core/serialization/serialize.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/core/serialization/serializerHelpers.d.ts

@@ -0,0 +1,46 @@
+import { Color } from '#core/Color';
+import type { LayoutOptions } from '#rendering/text/LayoutOptions';
+import type { TextStyleOptions } from '#rendering/text/TextStyle';
+/**
+ * Return a shallow copy of `options` with every `undefined`-valued key removed,
+ * so an optional property is *omitted* rather than set to `undefined`. Lets a
+ * deserializer build an options bag from sparse JSON without forcing a default
+ * past a constructor's own `?? default` (and stays valid under
+ * `exactOptionalPropertyTypes`).
+ */
+export declare function compact<T extends object>(options: T): {
+    [K in keyof T]: Exclude<T[K], undefined>;
+};
+/** Serialize a colour to `[r, g, b, a]` (r/g/b 0..255, a 0..1). */
+export declare const colorToArray: (color: Color) => [number, number, number, number];
+/** Deserialize a `[r, g, b, a]` tuple back to a {@link Color}, or `undefined`. */
+export declare const arrayToColor: (value: unknown) => Color | undefined;
+/** Serialize the plain-data fields of a {@link TextStyle}, omitting defaults. */
+export declare function serializeStyle(style: {
+    fontFamily: string;
+    fontWeight: string;
+    fontStyle: string;
+    fontSize: number;
+    fillColor: Color;
+    outlineColor: Color;
+    outlineWidth: number;
+    align: string;
+    lineHeight: number;
+    leading: number;
+    shadowColor: Color;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowAlpha: number;
+    shadowBlur: number;
+    gradientColors: [Color, Color] | null;
+    gradientAxis: string;
+}): Record<string, unknown> | undefined;
+/** Rebuild {@link TextStyleOptions} from serialized style data, or `undefined`. */
+export declare function deserializeStyleOptions(data: unknown): TextStyleOptions | undefined;
+/**
+ * Rebuild {@link LayoutOptions} from a serialized layout object, dropping
+ * unknown or mistyped fields. Returns `undefined` when nothing valid remains,
+ * so a corrupt `layout` value degrades to the node's constructor defaults.
+ */
+export declare function readLayoutOptions(value: unknown): LayoutOptions | undefined;
+//# sourceMappingURL=serializerHelpers.d.ts.map

package/dist/esm/core/serialization/serializerHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializerHelpers.d.ts","sourceRoot":"","sources":["../../../../src/core/serialization/serializerHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAMlE;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;CAAE,CAQlG;AAID,mEAAmE;AACnE,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,KAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAyC,CAAC;AAErH,kFAAkF;AAClF,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,GAAG,SACsF,CAAC;AAM7I,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,YAAY,EAAE,KAAK,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA0BtC;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAoDnF;AAQD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CA8B3E"}