@grafloria/element 0.3.20 → 0.3.22

package/src/libs/engine/src/serialization/DiagramMigrations.js

@@ -1,124 +0,0 @@
-"use strict";
-// Document-level schema versioning + ordered migration chain.
-//
-// `schemaVersion` describes the SHAPE of a serialized diagram document and is
-// distinct from the per-entity `version` counter (which counts mutations of a
-// live entity). Documents written before this system exist are treated as
-// schemaVersion 1; the current writer stamps DIAGRAM_SCHEMA_VERSION.
-//
-// On load, `runDiagramMigrations` upgrades an older document step by step
-// (1→2→…→current) through registered migrations, and FAILS LOUDLY — instead of
-// silently mis-loading — when the document is newer than the runtime or when a
-// migration step is missing.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DIAGRAM_SCHEMA_VERSION = void 0;
-exports.registerDiagramMigration = registerDiagramMigration;
-exports.getDiagramMigrations = getDiagramMigrations;
-exports.runDiagramMigrations = runDiagramMigrations;
-const tslib_1 = require("tslib");
-/**
- * The schema version this engine writes.
- *
- * History:
- *  - 1: implicit — documents written before schemaVersion existed
- *       (fromJSON bypassed the wired restore path; groups could carry a
- *       runtime 'diagram' metadata key).
- *  - 2: documents written by the unified load/save path. Structurally
- *       identical to v1 except: `schemaVersion` is stamped, `groups` is
- *       always present, and runtime-only metadata is never serialized.
- */
-exports.DIAGRAM_SCHEMA_VERSION = 3;
-const registry = [];
-/**
- * Register a document migration. Apps embedding the engine can register their
- * own steps when they extend the document shape.
- */
-function registerDiagramMigration(migration) {
-    if (migration.to !== migration.from + 1) {
-        throw new Error(`Diagram migration must upgrade exactly one step (got ${migration.from} → ${migration.to})`);
-    }
-    if (registry.some((m) => m.from === migration.from)) {
-        throw new Error(`A diagram migration from schemaVersion ${migration.from} is already registered`);
-    }
-    registry.push(migration);
-    registry.sort((a, b) => a.from - b.from);
-}
-/** Registered migrations, in order (primarily for tests/diagnostics). */
-function getDiagramMigrations() {
-    return registry;
-}
-/**
- * Upgrade a serialized document to DIAGRAM_SCHEMA_VERSION.
- *
- * - A document with no `schemaVersion` is treated as v1.
- * - A document NEWER than the runtime throws (loading it would silently drop
- *   or mangle data written by a newer app — the caller must upgrade instead).
- * - A missing step in the chain throws (a partial upgrade is worse than none).
- *
- * @param migrations override the global registry (tests / embedders).
- */
-function runDiagramMigrations(data, migrations = registry) {
-    var _a;
-    let doc = data;
-    let v = (_a = doc.schemaVersion) !== null && _a !== void 0 ? _a : 1;
-    if (v > exports.DIAGRAM_SCHEMA_VERSION) {
-        throw new Error(`Diagram document has schemaVersion ${v}, but this engine only knows ` +
-            `${exports.DIAGRAM_SCHEMA_VERSION}. Refusing to load a newer document — ` +
-            `upgrade the engine (or re-export from an app on schema ${exports.DIAGRAM_SCHEMA_VERSION}).`);
-    }
-    while (v < exports.DIAGRAM_SCHEMA_VERSION) {
-        const step = migrations.find((m) => m.from === v);
-        if (!step) {
-            throw new Error(`No diagram migration registered for schemaVersion ${v} → ${v + 1}; ` +
-                `cannot upgrade this document to ${exports.DIAGRAM_SCHEMA_VERSION}.`);
-        }
-        doc = step.migrate(doc);
-        v = step.to;
-        // Stamp defensively so a forgetful migrate() cannot stall the loop.
-        doc.schemaVersion = v;
-    }
-    return doc;
-}
-// ---------------------------------------------------------------------------
-// Built-in chain
-// ---------------------------------------------------------------------------
-registerDiagramMigration({
-    from: 1,
-    to: 2,
-    description: 'v1 → v2: stamp schemaVersion, guarantee the groups collection exists, ' +
-        'and strip runtime-only group metadata (the live diagram back-reference) ' +
-        'that pre-unified writers could leak into payloads.',
-    migrate(data) {
-        var _a;
-        const groups = ((_a = data.groups) !== null && _a !== void 0 ? _a : []).map((g) => {
-            if (g && g.metadata && 'diagram' in g.metadata) {
-                const _a = g.metadata, { diagram: _runtimeRef } = _a, metadata = tslib_1.__rest(_a, ["diagram"]);
-                return Object.assign(Object.assign({}, g), { metadata });
-            }
-            return g;
-        });
-        return Object.assign(Object.assign({}, data), { groups, schemaVersion: 2 });
-    },
-});
-registerDiagramMigration({
-    from: 2,
-    to: 3,
-    description: 'v2 → v3: a node with a parentId is RELATIVE unless it explicitly says otherwise. ' +
-        'Pre-v3 engines summed the parent chain in getWorldPosition() regardless of ' +
-        'positionMode, so a parented node whose mode was absent or the "absolute" default ' +
-        'was in fact rendered relatively. v3 makes getWorldPosition honour positionMode; ' +
-        're-labelling those nodes "relative" here is what keeps every legacy document ' +
-        'rendering BYTE-IDENTICALLY under the new, consistent semantics. ("layout" mode ' +
-        'is left alone — it was never part of the summation contract.)',
-    migrate(data) {
-        var _a;
-        const nodes = ((_a = data.nodes) !== null && _a !== void 0 ? _a : []).map((n) => {
-            if (n && n.parentId && (n.positionMode === undefined || n.positionMode === 'absolute')) {
-                return Object.assign(Object.assign({}, n), { positionMode: 'relative' });
-            }
-            return n;
-        });
-        return Object.assign(Object.assign({}, data), { nodes, schemaVersion: 3 });
-    },
-});
-//# sourceMappingURL=DiagramMigrations.js.map

package/src/libs/engine/src/serialization/DiagramValidator.d.ts

@@ -1,20 +0,0 @@
-import type { SerializedDiagram } from '../models/DiagramModel';
-export interface DiagramValidationFinding {
-    severity: 'error' | 'warning';
-    /** Stable machine-readable code (e.g. 'duplicate-id', 'dangling-link-endpoint'). */
-    code: string;
-    message: string;
-    /** Id of the entity the finding is about, when applicable. */
-    entityId?: string;
-}
-export interface DiagramValidationReport {
-    ok: boolean;
-    errors: DiagramValidationFinding[];
-    warnings: DiagramValidationFinding[];
-}
-/** Thrown by strict-mode loads when the document has integrity errors. */
-export declare class DiagramValidationError extends Error {
-    readonly report: DiagramValidationReport;
-    constructor(report: DiagramValidationReport);
-}
-export declare function validateSerializedDiagram(data: SerializedDiagram): DiagramValidationReport;

package/src/libs/engine/src/serialization/DiagramValidator.js

@@ -1,136 +0,0 @@
-"use strict";
-// Load-time structural integrity validation for serialized diagrams.
-//
-// The validator inspects the SERIALIZED shape (before entities are
-// constructed) and reports structured findings instead of throwing, so
-// callers choose their policy: ignore, warn, or fail hard. It catches the
-// corruption classes that otherwise surface as silent misbehavior long after
-// load — dangling link endpoints, duplicate ids, orphaned group references.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DiagramValidationError = void 0;
-exports.validateSerializedDiagram = validateSerializedDiagram;
-/** Thrown by strict-mode loads when the document has integrity errors. */
-class DiagramValidationError extends Error {
-    constructor(report) {
-        super(`Diagram document failed integrity validation with ${report.errors.length} error(s): ` +
-            report.errors.map((e) => `[${e.code}] ${e.message}`).join('; '));
-        this.report = report;
-        this.name = 'DiagramValidationError';
-    }
-}
-exports.DiagramValidationError = DiagramValidationError;
-function validateSerializedDiagram(data) {
-    var _a, _b, _c, _d, _e, _f;
-    const errors = [];
-    const warnings = [];
-    const error = (code, message, entityId) => errors.push({ severity: 'error', code, message, entityId });
-    const warning = (code, message, entityId) => warnings.push({ severity: 'warning', code, message, entityId });
-    const nodes = (_a = data.nodes) !== null && _a !== void 0 ? _a : [];
-    const links = (_b = data.links) !== null && _b !== void 0 ? _b : [];
-    const groups = (_c = data.groups) !== null && _c !== void 0 ? _c : [];
-    const strokes = (_d = data.strokes) !== null && _d !== void 0 ? _d : []; // wave10/whiteboard
-    // --- duplicate ids (within and across collections) -----------------------
-    const seen = new Map(); // id -> collection
-    const checkId = (id, kind) => {
-        if (!id) {
-            error('missing-id', `A serialized ${kind} has no id`);
-            return;
-        }
-        const prior = seen.get(id);
-        if (prior) {
-            error('duplicate-id', `Id '${id}' is used by both a ${prior} and a ${kind}`, id);
-        }
-        else {
-            seen.set(id, kind);
-        }
-    };
-    nodes.forEach((n) => checkId(n === null || n === void 0 ? void 0 : n.id, 'node'));
-    links.forEach((l) => checkId(l === null || l === void 0 ? void 0 : l.id, 'link'));
-    groups.forEach((g) => checkId(g === null || g === void 0 ? void 0 : g.id, 'group'));
-    // wave10/whiteboard. Ink joins the CROSS-COLLECTION id check, which is the point: a
-    // stroke sharing an id with a node is exactly the corruption `applyOp` cannot survive
-    // (the op targets are per-kind, but undo's register key is `target id path`, and two
-    // kinds under one id make two different entities share one register).
-    strokes.forEach((s) => checkId(s === null || s === void 0 ? void 0 : s.id, 'stroke'));
-    // A stroke with no points draws nothing and hit-tests as nothing — it is invisible
-    // débris that can only be removed by an eraser that cannot find it. Not an error (the
-    // document is structurally sound), but the user should know it is there.
-    for (const s of strokes) {
-        if (!s)
-            continue;
-        if (!Array.isArray(s.points) || s.points.length === 0) {
-            warning('empty-stroke', `Stroke '${s.id}' has no points and can never be seen`, s.id);
-        }
-        else if (s.points.some((p) => !p || !isFinite(p.x) || !isFinite(p.y))) {
-            error('invalid-stroke-point', `Stroke '${s.id}' has a non-finite point, which poisons its bounds to NaN and ` +
-                `culls it from every viewport query`, s.id);
-        }
-    }
-    // --- port ownership map ---------------------------------------------------
-    const portOwner = new Map(); // portId -> nodeId
-    for (const n of nodes) {
-        for (const p of (_e = n === null || n === void 0 ? void 0 : n.ports) !== null && _e !== void 0 ? _e : []) {
-            if (!(p === null || p === void 0 ? void 0 : p.id))
-                continue;
-            const prior = portOwner.get(p.id);
-            if (prior && prior !== n.id) {
-                error('duplicate-port-id', `Port id '${p.id}' appears on both node '${prior}' and node '${n.id}'`, p.id);
-            }
-            portOwner.set(p.id, n.id);
-        }
-    }
-    // --- link endpoints resolve to real ports ---------------------------------
-    for (const l of links) {
-        if (!l)
-            continue;
-        for (const [end, portId] of [
-            ['source', l.sourcePortId],
-            ['target', l.targetPortId],
-        ]) {
-            if (!portId || !portOwner.has(portId)) {
-                error('dangling-link-endpoint', `Link '${l.id}' ${end} port '${portId !== null && portId !== void 0 ? portId : '(none)'}' does not exist on any serialized node`, l.id);
-            }
-        }
-    }
-    // --- node parent references ------------------------------------------------
-    const nodeIds = new Set(nodes.map((n) => n === null || n === void 0 ? void 0 : n.id).filter(Boolean));
-    for (const n of nodes) {
-        if ((n === null || n === void 0 ? void 0 : n.parentId) && !nodeIds.has(n.parentId)) {
-            warning('missing-parent', `Node '${n.id}' references missing parent '${n.parentId}'`, n.id);
-        }
-    }
-    // --- group membership + containment tree -----------------------------------
-    const groupIds = new Set(groups.map((g) => g === null || g === void 0 ? void 0 : g.id).filter(Boolean));
-    for (const g of groups) {
-        if (!g)
-            continue;
-        for (const member of (_f = g.members) !== null && _f !== void 0 ? _f : []) {
-            if (!nodeIds.has(member) && !groupIds.has(member)) {
-                warning('missing-group-member', `Group '${g.id}' references missing member '${member}'`, g.id);
-            }
-        }
-        if (g.parentGroupId !== undefined) {
-            if (!groupIds.has(g.parentGroupId)) {
-                error('missing-parent-group', `Group '${g.id}' references missing parent group '${g.parentGroupId}'`, g.id);
-            }
-        }
-    }
-    // containment cycles (follow parentGroupId pointers)
-    const parentOf = new Map(groups.filter(Boolean).map((g) => [g.id, g.parentGroupId]));
-    for (const g of groups) {
-        if (!g)
-            continue;
-        const trail = new Set([g.id]);
-        let cur = parentOf.get(g.id);
-        while (cur !== undefined) {
-            if (trail.has(cur)) {
-                error('group-cycle', `Group containment cycle involving '${g.id}'`, g.id);
-                break;
-            }
-            trail.add(cur);
-            cur = parentOf.get(cur);
-        }
-    }
-    return { ok: errors.length === 0, errors, warnings };
-}
-//# sourceMappingURL=DiagramValidator.js.map

package/src/libs/engine/src/serialization/DocumentEnvelope.d.ts

@@ -1,53 +0,0 @@
-import type { SerializedDiagram } from '../models/DiagramModel';
-export declare const DIAGRAM_ENVELOPE_FORMAT: "grafloria-diagram";
-export declare const DIAGRAM_ENVELOPE_VERSION = 1;
-export interface DiagramDocumentEnvelope {
-    format: typeof DIAGRAM_ENVELOPE_FORMAT;
-    envelopeVersion: number;
-    /** Writer identity, e.g. '@grafloria/engine'. */
-    generator: string;
-    /** Writer version — the document schemaVersion the writer targets. */
-    generatorVersion: string;
-    /** ISO-8601 creation timestamp. */
-    createdAt: string;
-    /** FNV-1a hash of the canonical JSON of `document` (see canonicalStringify). */
-    checksum?: string;
-    document: SerializedDiagram;
-}
-/**
- * Deterministic JSON: object keys sorted recursively so the same logical
- * document always hashes identically, regardless of property insertion order.
- * (Arrays keep their order — element order IS meaning in nodes/links.)
- */
-export declare function canonicalStringify(value: unknown): string;
-/** FNV-1a 32-bit over a string, hex encoded — cheap, dependency-free. */
-export declare function fnv1aHex(text: string): string;
-/** Integrity checksum of a document's canonical JSON. */
-export declare function checksumOf(document: SerializedDiagram): string;
-export interface WrapOptions {
-    generator?: string;
-    generatorVersion?: string;
-    /** Include an integrity checksum (default true). */
-    checksum?: boolean;
-    /** Timestamp override (tests / deterministic exports). */
-    createdAt?: string;
-}
-export declare function wrapDiagramDocument(document: SerializedDiagram, options?: WrapOptions): DiagramDocumentEnvelope;
-export declare function isDiagramDocumentEnvelope(value: unknown): value is DiagramDocumentEnvelope;
-export declare class DiagramChecksumError extends Error {
-    readonly expected: string;
-    readonly actual: string;
-    constructor(expected: string, actual: string);
-}
-export interface UnwrapResult {
-    document: SerializedDiagram;
-    /** Present when the input was enveloped. */
-    envelope?: DiagramDocumentEnvelope;
-}
-/**
- * Accepts an enveloped document OR a legacy flat SerializedDiagram and
- * returns the inner document. When the envelope carries a checksum it is
- * verified (throws DiagramChecksumError on mismatch — an integrity failure
- * must never load silently).
- */
-export declare function unwrapDiagramDocument(input: SerializedDiagram | DiagramDocumentEnvelope): UnwrapResult;

package/src/libs/engine/src/serialization/DocumentEnvelope.js

@@ -1,111 +0,0 @@
-"use strict";
-// Portable document envelope — the stable OUTER shape of a persisted diagram.
-//
-// The envelope answers the questions a document store, an export file, or a
-// support ticket needs answered WITHOUT parsing the model: what format is
-// this, which app/version wrote it, when, and has it been corrupted in
-// transit (checksum over a canonical serialization). The inner `document` is
-// the SerializedDiagram, which carries its own schemaVersion + migration
-// chain (DiagramMigrations).
-//
-// Adoption is opt-in: `unwrapDiagramDocument` accepts BOTH enveloped and
-// legacy flat payloads, so existing persisted documents keep loading.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DiagramChecksumError = exports.DIAGRAM_ENVELOPE_VERSION = exports.DIAGRAM_ENVELOPE_FORMAT = void 0;
-exports.canonicalStringify = canonicalStringify;
-exports.fnv1aHex = fnv1aHex;
-exports.checksumOf = checksumOf;
-exports.wrapDiagramDocument = wrapDiagramDocument;
-exports.isDiagramDocumentEnvelope = isDiagramDocumentEnvelope;
-exports.unwrapDiagramDocument = unwrapDiagramDocument;
-exports.DIAGRAM_ENVELOPE_FORMAT = 'grafloria-diagram';
-exports.DIAGRAM_ENVELOPE_VERSION = 1;
-/**
- * Deterministic JSON: object keys sorted recursively so the same logical
- * document always hashes identically, regardless of property insertion order.
- * (Arrays keep their order — element order IS meaning in nodes/links.)
- */
-function canonicalStringify(value) {
-    return JSON.stringify(sortKeysDeep(value));
-}
-function sortKeysDeep(value) {
-    if (Array.isArray(value)) {
-        return value.map(sortKeysDeep);
-    }
-    if (value && typeof value === 'object') {
-        const sorted = {};
-        for (const key of Object.keys(value).sort()) {
-            sorted[key] = sortKeysDeep(value[key]);
-        }
-        return sorted;
-    }
-    return value;
-}
-/** FNV-1a 32-bit over a string, hex encoded — cheap, dependency-free. */
-function fnv1aHex(text) {
-    let hash = 0x811c9dc5;
-    for (let i = 0; i < text.length; i++) {
-        hash ^= text.charCodeAt(i);
-        hash = Math.imul(hash, 0x01000193);
-    }
-    return (hash >>> 0).toString(16).padStart(8, '0');
-}
-/** Integrity checksum of a document's canonical JSON. */
-function checksumOf(document) {
-    return fnv1aHex(canonicalStringify(document));
-}
-function wrapDiagramDocument(document, options = {}) {
-    var _a, _b, _c, _d;
-    const envelope = {
-        format: exports.DIAGRAM_ENVELOPE_FORMAT,
-        envelopeVersion: exports.DIAGRAM_ENVELOPE_VERSION,
-        generator: (_a = options.generator) !== null && _a !== void 0 ? _a : '@grafloria/engine',
-        generatorVersion: (_b = options.generatorVersion) !== null && _b !== void 0 ? _b : String((_c = document.schemaVersion) !== null && _c !== void 0 ? _c : 1),
-        createdAt: (_d = options.createdAt) !== null && _d !== void 0 ? _d : new Date().toISOString(),
-        document,
-    };
-    if (options.checksum !== false) {
-        envelope.checksum = checksumOf(document);
-    }
-    return envelope;
-}
-function isDiagramDocumentEnvelope(value) {
-    return (!!value &&
-        typeof value === 'object' &&
-        value.format === exports.DIAGRAM_ENVELOPE_FORMAT &&
-        typeof value.envelopeVersion === 'number' &&
-        !!value.document);
-}
-class DiagramChecksumError extends Error {
-    constructor(expected, actual) {
-        super(`Diagram document checksum mismatch (expected ${expected}, computed ${actual}) — ` +
-            `the payload was modified or corrupted after it was written.`);
-        this.expected = expected;
-        this.actual = actual;
-        this.name = 'DiagramChecksumError';
-    }
-}
-exports.DiagramChecksumError = DiagramChecksumError;
-/**
- * Accepts an enveloped document OR a legacy flat SerializedDiagram and
- * returns the inner document. When the envelope carries a checksum it is
- * verified (throws DiagramChecksumError on mismatch — an integrity failure
- * must never load silently).
- */
-function unwrapDiagramDocument(input) {
-    if (isDiagramDocumentEnvelope(input)) {
-        if (input.envelopeVersion > exports.DIAGRAM_ENVELOPE_VERSION) {
-            throw new Error(`Diagram envelope version ${input.envelopeVersion} is newer than this runtime ` +
-                `(${exports.DIAGRAM_ENVELOPE_VERSION}) — refusing to load.`);
-        }
-        if (input.checksum) {
-            const actual = checksumOf(input.document);
-            if (actual !== input.checksum) {
-                throw new DiagramChecksumError(input.checksum, actual);
-            }
-        }
-        return { document: input.document, envelope: input };
-    }
-    return { document: input };
-}
-//# sourceMappingURL=DocumentEnvelope.js.map

package/src/libs/engine/src/serialization/Incremental.d.ts

@@ -1,77 +0,0 @@
-import type { DiagramModel } from '../models/DiagramModel';
-import type { SerializedNode } from '../models/NodeModel';
-import type { SerializedLink } from '../models/LinkModel';
-import type { SerializedGroup } from '../models/GroupModel';
-import type { SerializedStroke } from '../models/StrokeModel';
-export declare const INCREMENTAL_FORMAT: "grafloria-incremental";
-export interface DiagramIncremental {
-    format: typeof INCREMENTAL_FORMAT;
-    schemaVersion: number;
-    /** diagram.version at the moment the window began (ordering hint). */
-    baseVersion: number;
-    /** diagram.version at commit — apply converges the replica's counter to it. */
-    targetVersion: number;
-    added: {
-        nodes: SerializedNode[];
-        links: SerializedLink[];
-        groups: SerializedGroup[];
-        strokes?: SerializedStroke[];
-    };
-    removed: {
-        nodes: string[];
-        links: string[];
-        groups: string[];
-        strokes?: string[];
-    };
-    modified: {
-        nodes: SerializedNode[];
-        links: SerializedLink[];
-        groups: SerializedGroup[];
-        strokes?: SerializedStroke[];
-    };
-    diagram?: {
-        name?: string;
-        viewport?: {
-            x: number;
-            y: number;
-            width: number;
-            height: number;
-            zoom: number;
-        };
-        metadata?: Record<string, unknown>;
-    };
-}
-/**
- * Watches a live diagram and produces a DiagramIncremental per commit().
- * Continues capturing after commit (autosave-loop friendly) until stop().
- */
-export declare class IncrementalCapture {
-    private readonly diagram;
-    private nodes;
-    private links;
-    private groups;
-    private strokes;
-    private baseVersion;
-    private nameSnapshot;
-    private viewportSnapshot;
-    private metadataSnapshot;
-    private disposers;
-    private groupDisposers;
-    private stopped;
-    constructor(diagram: DiagramModel);
-    private watchGroup;
-    private unwatchGroup;
-    /** Anything captured since the window began? */
-    hasChanges(): boolean;
-    private diagramChanges;
-    /**
-     * Drain the window into a patch (null when nothing changed) and keep
-     * capturing. Added/modified entities are serialized LIVE at commit time,
-     * so intra-window churn costs nothing.
-     */
-    commit(): DiagramIncremental | null;
-    /** Unsubscribe everything. The capture cannot be reused afterwards. */
-    stop(): void;
-}
-/** Convenience: start watching a diagram for incremental commits. */
-export declare function beginIncrementalCapture(diagram: DiagramModel): IncrementalCapture;