@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/layout/layout-history.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Layout History and Undo/Redo System
+ *
+ * Manages layout state history and enables undo/redo operations.
+ * Essential for interactive editing workflows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LayoutHistory = void 0;
+/**
+ * Layout History Manager
+ *
+ * Manages undo/redo stack for layout operations
+ */
+class LayoutHistory {
+    constructor(options = {}) {
+        this.history = [];
+        this.currentIndex = -1;
+        this.lastSnapshotTime = 0;
+        this.maxHistorySize = options.maxHistorySize || 50;
+        this.minSnapshotInterval = options.minSnapshotInterval || 1000; // 1 second
+    }
+    /**
+     * Create and push a new snapshot
+     *
+     * @param nodes - Current nodes
+     * @param description - Optional description
+     * @param algorithm - Layout algorithm used
+     * @param options - Layout options used
+     * @returns The created snapshot
+     */
+    pushSnapshot(nodes, description, algorithm, options) {
+        const now = Date.now();
+        // Check if enough time has passed since last snapshot
+        if (now - this.lastSnapshotTime < this.minSnapshotInterval) {
+            // Return last snapshot without creating a new one
+            return this.history[this.currentIndex];
+        }
+        // Create position map
+        const positions = new Map();
+        nodes.forEach(node => {
+            const pos = node.position;
+            positions.set(node.id, { x: pos.x, y: pos.y });
+        });
+        const snapshot = {
+            id: this.generateId(),
+            timestamp: now,
+            positions,
+            description,
+            algorithm,
+            options,
+        };
+        // If we're not at the end, remove all entries after current
+        if (this.currentIndex < this.history.length - 1) {
+            this.history = this.history.slice(0, this.currentIndex + 1);
+        }
+        // Add new snapshot
+        this.history.push(snapshot);
+        this.currentIndex++;
+        // Limit history size
+        if (this.history.length > this.maxHistorySize) {
+            this.history.shift();
+            this.currentIndex--;
+        }
+        this.lastSnapshotTime = now;
+        return snapshot;
+    }
+    /**
+     * Undo to previous snapshot
+     *
+     * @returns The snapshot to restore, or undefined if can't undo
+     */
+    undo() {
+        if (!this.canUndo()) {
+            return undefined;
+        }
+        this.currentIndex--;
+        return this.history[this.currentIndex];
+    }
+    /**
+     * Redo to next snapshot
+     *
+     * @returns The snapshot to restore, or undefined if can't redo
+     */
+    redo() {
+        if (!this.canRedo()) {
+            return undefined;
+        }
+        this.currentIndex++;
+        return this.history[this.currentIndex];
+    }
+    /**
+     * Check if undo is possible
+     */
+    canUndo() {
+        return this.currentIndex > 0;
+    }
+    /**
+     * Check if redo is possible
+     */
+    canRedo() {
+        return this.currentIndex < this.history.length - 1;
+    }
+    /**
+     * Get current snapshot
+     */
+    getCurrentSnapshot() {
+        return this.history[this.currentIndex];
+    }
+    /**
+     * Get all snapshots
+     */
+    getAllSnapshots() {
+        return [...this.history];
+    }
+    /**
+     * Get snapshot by ID
+     */
+    getSnapshotById(id) {
+        return this.history.find(s => s.id === id);
+    }
+    /**
+     * Restore a specific snapshot by ID
+     *
+     * @param id - Snapshot ID to restore
+     * @returns The snapshot, or undefined if not found
+     */
+    restoreSnapshot(id) {
+        const index = this.history.findIndex(s => s.id === id);
+        if (index === -1) {
+            return undefined;
+        }
+        this.currentIndex = index;
+        return this.history[index];
+    }
+    /**
+     * Clear all history
+     */
+    clear() {
+        this.history = [];
+        this.currentIndex = -1;
+        this.lastSnapshotTime = 0;
+    }
+    /**
+     * Get history size
+     */
+    size() {
+        return this.history.length;
+    }
+    /**
+     * Get current index in history
+     */
+    getCurrentIndex() {
+        return this.currentIndex;
+    }
+    /**
+     * Apply snapshot to nodes
+     *
+     * @param snapshot - Snapshot to apply
+     * @param nodes - Nodes to update
+     * @returns Number of nodes updated
+     */
+    static applySnapshot(snapshot, nodes) {
+        let updatedCount = 0;
+        nodes.forEach(node => {
+            const pos = snapshot.positions.get(node.id);
+            if (pos) {
+                node.setPosition(pos.x, pos.y);
+                updatedCount++;
+            }
+        });
+        return updatedCount;
+    }
+    /**
+     * Generate unique ID for snapshot
+     */
+    generateId() {
+        return `snapshot-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Export history to JSON
+     */
+    exportToJSON() {
+        const exportData = {
+            history: this.history.map(snapshot => ({
+                id: snapshot.id,
+                timestamp: snapshot.timestamp,
+                positions: Array.from(snapshot.positions.entries()),
+                description: snapshot.description,
+                algorithm: snapshot.algorithm,
+                options: snapshot.options,
+            })),
+            currentIndex: this.currentIndex,
+        };
+        return JSON.stringify(exportData, null, 2);
+    }
+    /**
+     * Import history from JSON
+     *
+     * @param json - JSON string to import
+     * @returns True if successful
+     */
+    importFromJSON(json) {
+        try {
+            const data = JSON.parse(json);
+            this.history = data.history.map((item) => ({
+                id: item.id,
+                timestamp: item.timestamp,
+                positions: new Map(item.positions),
+                description: item.description,
+                algorithm: item.algorithm,
+                options: item.options,
+            }));
+            this.currentIndex = data.currentIndex;
+            return true;
+        }
+        catch (error) {
+            console.error('Failed to import layout history:', error);
+            return false;
+        }
+    }
+    /**
+     * Get history statistics
+     */
+    getStatistics() {
+        const snapshots = this.history;
+        if (snapshots.length === 0) {
+            return {
+                totalSnapshots: 0,
+                currentIndex: -1,
+                canUndo: false,
+                canRedo: false,
+                oldestTimestamp: 0,
+                newestTimestamp: 0,
+                averageInterval: 0,
+            };
+        }
+        const timestamps = snapshots.map(s => s.timestamp);
+        const intervals = [];
+        for (let i = 1; i < timestamps.length; i++) {
+            intervals.push(timestamps[i] - timestamps[i - 1]);
+        }
+        const averageInterval = intervals.length > 0
+            ? intervals.reduce((a, b) => a + b, 0) / intervals.length
+            : 0;
+        return {
+            totalSnapshots: snapshots.length,
+            currentIndex: this.currentIndex,
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+            oldestTimestamp: timestamps[0],
+            newestTimestamp: timestamps[timestamps.length - 1],
+            averageInterval,
+        };
+    }
+}
+exports.LayoutHistory = LayoutHistory;
+//# sourceMappingURL=layout-history.js.map

package/src/libs/engine/src/layout/layout-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-history.js","sourceRoot":"","sources":["../../../../../../engine/src/layout/layout-history.ts"],"names":[],"mappings":"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"}

package/src/libs/engine/src/layout/layout-host.d.ts

@@ -0,0 +1,172 @@
+import type { LayoutAdapter, LayoutOptions, LayoutResult } from './layout-adapter.interface';
+import { type LayoutGraph } from './layout-graph';
+/**
+ * Options as they cross the wire: the named ones, plus whatever adapter-specific
+ * knobs the caller supplied (`iterations`, `repulsion`, `rankdir`, …). Anything
+ * here must be structured-clone-safe — `stripNonClonable` enforces that at the
+ * seam rather than trusting callers to.
+ */
+export type LayoutWireOptions = Partial<LayoutOptions> & Record<string, unknown>;
+export interface LayoutRequestRun {
+    seq: number;
+    kind: 'run';
+    algorithm: string;
+    graph: LayoutGraph;
+    options: LayoutWireOptions;
+    /** Stop and return the best-so-far once this many ms have elapsed. */
+    timeBudgetMs?: number;
+    /** How long to compute before surrendering the thread so `cancel` can land. */
+    sliceMs?: number;
+    /**
+     * Stop after exactly N iterations — a DETERMINISTIC pre-emption.
+     *
+     * A time budget is by nature a nondeterministic stopping rule (it consults a
+     * clock), so a partial result produced by one is not reproducible and cannot
+     * be golden-tested. This knob is the deterministic counterpart, and it is how
+     * we prove the thing worth proving: that a *partial* result from the worker is
+     * byte-identical to a *partial* result from the inline path.
+     */
+    stopAfterIteration?: number;
+}
+export interface LayoutRequestCancel {
+    seq: number;
+    kind: 'cancel';
+    /** The seq of the run to cancel. */
+    target: number;
+}
+export type LayoutRequest = LayoutRequestRun | LayoutRequestCancel;
+/** Why a run stopped early. Absent when it ran to completion. */
+export type LayoutStopReason = 'cancelled' | 'timeout' | 'iteration-cap';
+export interface LayoutProgressMessage {
+    seq: number;
+    kind: 'progress';
+    /** 0..1. Monotonic. */
+    progress: number;
+    phase: string;
+    iteration: number;
+    totalIterations: number;
+}
+export interface LayoutResultMessage {
+    seq: number;
+    kind: 'result';
+    algorithm: string;
+    positions: Array<[string, {
+        x: number;
+        y: number;
+    }]>;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** True when the run stopped early — the answer is the best-so-far, not the end. */
+    partial: boolean;
+    reason?: LayoutStopReason;
+    iteration: number;
+    totalIterations: number;
+    /**
+     * Everything else the adapter reported, carried verbatim.
+     *
+     * Not decoration: `quality` only exists when the caller asked for it with
+     * `calculateQuality`, and a result message that dropped it would make that
+     * option silently do nothing on the worker path while working inline — the
+     * single most common bug shape in this codebase, and one this card exists to
+     * stop repeating.
+     */
+    metadata?: LayoutResult['metadata'];
+    quality?: LayoutResult['quality'];
+    portAware?: LayoutResult['portAware'];
+    subgraph?: LayoutResult['subgraph'];
+    edgeBundling?: LayoutResult['edgeBundling'];
+}
+export interface LayoutErrorMessage {
+    seq: number;
+    kind: 'error';
+    message: string;
+}
+export type LayoutResponse = LayoutProgressMessage | LayoutResultMessage | LayoutErrorMessage;
+/** The message-port surface the host needs — a real Worker satisfies it. */
+export interface LayoutPort {
+    postMessage(msg: LayoutRequest): void;
+    onmessage: ((ev: {
+        data: LayoutResponse;
+    }) => void) | null;
+}
+/** The port surface the SERVER side needs — a worker's `self` satisfies it. */
+export interface LayoutServePort {
+    onmessage: ((ev: {
+        data: LayoutRequest;
+    }) => void) | null;
+    postMessage(msg: LayoutResponse): void;
+}
+export interface ServeLayoutDeps {
+    /**
+     * Name → algorithm. Injected, because the INLINE host resolves against the
+     * engine's live registry (so a host-registered custom layout still works),
+     * while a real worker resolves against whatever its own bundle registered —
+     * a function cannot be posted across a thread boundary, so an extension
+     * layout registered at runtime is inline-only, by physics rather than choice.
+     */
+    resolve?: (name: string) => LayoutAdapter | undefined;
+    /** The clock. Injected so tests can stop it lying. */
+    now?: () => number;
+}
+/**
+ * Serve layout requests on a port. This IS the worker's message loop — call it
+ * inside the worker script with `self`, or in a test with a fake port, or (see
+ * `LayoutHost`) on the inline side of a loopback pair.
+ */
+export declare function serveLayout(port: LayoutServePort, deps?: ServeLayoutDeps): void;
+export interface LayoutProgress {
+    /** 0..1. */
+    progress: number;
+    phase: string;
+    iteration: number;
+    totalIterations: number;
+}
+/** Caller-side options that must NEVER cross the wire (they are not clonable). */
+export interface LayoutRunOptions {
+    /** Cancel the run. Cooperative: takes effect within one slice. */
+    signal?: AbortSignal;
+    /** Streaming progress. Called on the caller's thread. */
+    onProgress?: (progress: LayoutProgress) => void;
+    /** Give up after this long and return the best-so-far, flagged partial. */
+    timeBudgetMs?: number;
+    /** Compute-between-yields, ms. Lower = promper cancellation, more overhead. */
+    sliceMs?: number;
+    /** Deterministic pre-emption after N iterations. See LayoutRequestRun. */
+    stopAfterIteration?: number;
+}
+export interface HostLayoutResult extends LayoutResult {
+    algorithm: string;
+    nodePositions: Map<string, {
+        x: number;
+        y: number;
+    }>;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** True when this is a best-so-far answer rather than a finished one. */
+    partial: boolean;
+    reason?: LayoutStopReason;
+    iteration: number;
+    totalIterations: number;
+}
+/**
+ * The caller-side host.
+ *
+ * Pass a real Worker (or anything satisfying `LayoutPort`) to run off-thread;
+ * pass nothing to run inline on the same thread. Identical behaviour, no protocol
+ * drift, because BOTH paths speak through `serveLayout`.
+ */
+export declare class LayoutHost {
+    private seq;
+    private readonly pending;
+    private readonly port;
+    constructor(port?: LayoutPort, deps?: ServeLayoutDeps);
+    run(algorithm: string, graph: LayoutGraph, options?: LayoutWireOptions, runOptions?: LayoutRunOptions): Promise<HostLayoutResult>;
+}