@grafloria/element 0.3.20 → 0.3.21

package/src/libs/engine/src/models/readonly-lock.js

@@ -1,125 +0,0 @@
-"use strict";
-/**
- * The read-only lock — Wave 9, Card 7.
- *
- * ## Why this exists
- *
- * `DiagramMode.VIEW` / `DiagramMode.PRESENTATION` and `ModeManager.isReadOnlyMode()`
- * have existed in this engine since long before this wave. They were documented as
- * "All editing disabled" / "No structural changes allowed".
- *
- * **They gated nothing.** Not one command, not one model mutator, not the DOM event
- * binder. `isReadOnlyMode()` was advisory — a boolean nobody asked. A "read-only"
- * diagram would happily accept a node drag, a Delete key, a paste, or a
- * `node.setPosition()` from any caller. That is not a feature, it is a
- * security-shaped lie: it *looks* locked and is not.
- *
- * This module is the enforcement primitive those modes now hang off.
- *
- * ## The distinction that makes it safe: DOCUMENT writes vs SYSTEM writes
- *
- * A naive lock ("refuse every `setSize`") breaks the renderer, because the engine
- * writes model fields at render time for reasons that have nothing to do with a
- * user editing the document:
- *
- *   - `svg/auto-size.ts`      measures text and writes `node.setSize()`
- *   - `ext/node-component.ts` measures a custom component and writes `node.setSize()`
- *   - `ext/portal.ts`         positions a portal via `setPosition()`
- *   - `instance/model-input.ts` writes geometry while LOADING the document
- *
- * Block those and a read-only diagram renders at the wrong size — the lock would
- * have "worked" in a unit test and destroyed the actual product. So writes come in
- * two kinds:
- *
- *   - **Document writes** — user/API intent that changes what the document MEANS.
- *     Refused while locked. (drag, delete, paste, connect, waypoint edit, command.)
- *   - **System writes** — derived/measured values the engine recomputes to render
- *     what the document ALREADY means. Always allowed, via {@link ReadonlyLock.runSystemWrite}.
- *
- * A system write must never be reachable from user input. The three call sites above
- * are the entire allowlist, and each is wrapped explicitly at the call site so the
- * bypass is greppable rather than ambient.
- *
- * ## Refusal semantics
- *
- * Guarded mutators **no-op** (and return a neutral value) rather than throw. A throw
- * from deep inside a model setter would take down a render pass or a host's event
- * handler; a locked document should be inert, not explosive. Callers that need to
- * know can ask {@link ReadonlyLock.isReadonly} up front — which is exactly what the
- * UI layers do to avoid arming a gesture they cannot finish.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReadonlyLock = void 0;
-exports.writeBlocked = writeBlocked;
-exports.isSystemWrite = isSystemWrite;
-/**
- * The lock itself. Held by `DiagramModel`; consulted by `NodeModel` / `LinkModel`
- * through their `diagram` back-reference, and by `CommandManager` through its context.
- */
-class ReadonlyLock {
-    constructor() {
-        this.locked = false;
-        /**
-         * Re-entrant depth of in-flight system writes. A counter, not a boolean, because
-         * auto-size can run inside a render that is itself inside a system write.
-         */
-        this.systemWriteDepth = 0;
-    }
-    isReadonly() {
-        return this.locked;
-    }
-    setReadonly(value) {
-        this.locked = value;
-    }
-    /** True when a document mutation must be refused: locked AND not a system write. */
-    blocksDocumentWrite() {
-        return this.locked && this.systemWriteDepth === 0;
-    }
-    /** True while a system write is in flight, whether or not the document is locked. */
-    inSystemWrite() {
-        return this.systemWriteDepth > 0;
-    }
-    /**
-     * Run `fn` as a SYSTEM write — a derived/measured value the engine needs in order
-     * to render the document as it already is. Permitted even while locked.
-     *
-     * Exception-safe: the depth is restored in `finally`, so a throwing measurement
-     * cannot leave the lock permanently open (which would silently un-lock the
-     * document — the worst possible failure mode for this class).
-     */
-    runSystemWrite(fn) {
-        this.systemWriteDepth++;
-        try {
-            return fn();
-        }
-        finally {
-            this.systemWriteDepth--;
-        }
-    }
-}
-exports.ReadonlyLock = ReadonlyLock;
-/**
- * True when `owner` is locked against document writes.
- *
- * Tolerates `undefined` because a model can legitimately be detached: a `NodeModel`
- * built with `new NodeModel()` and not yet added to a diagram has no back-reference,
- * and must stay freely mutable — you have to be able to BUILD a node before you can
- * add it to a locked document (and `addNode` itself is what refuses).
- */
-function writeBlocked(owner) {
-    var _a;
-    return ((_a = owner === null || owner === void 0 ? void 0 : owner.blocksDocumentWrite) === null || _a === void 0 ? void 0 : _a.call(owner)) === true;
-}
-/**
- * True when `owner` is currently performing a SYSTEM write — a measured/derived
- * value the engine needs in order to render the document as it already is.
- *
- * Same `undefined` tolerance as {@link writeBlocked}, and the same answer for a
- * host that predates the accessor: `false` (assume a document write), which is the
- * conservative reading — it refuses rather than silently permits.
- */
-function isSystemWrite(owner) {
-    var _a;
-    return ((_a = owner === null || owner === void 0 ? void 0 : owner.inSystemWrite) === null || _a === void 0 ? void 0 : _a.call(owner)) === true;
-}
-//# sourceMappingURL=readonly-lock.js.map

package/src/libs/engine/src/performance/LRUCache.d.ts

@@ -1,78 +0,0 @@
-export interface LRUCacheOptions<K, V> {
-    /**
-     * Callback invoked when an item is evicted due to capacity
-     * Not called for explicit delete() or clear()
-     */
-    onEvict?: (key: K, value: V) => void;
-}
-/**
- * LRU (Least Recently Used) Cache with automatic eviction
- *
- * Features:
- * - O(1) get, set, delete operations
- * - Automatic eviction when capacity exceeded
- * - Customizable eviction callback
- * - Prevents unbounded memory growth
- *
- * @example
- * ```typescript
- * const cache = new LRUCache<string, Route>(100);
- * cache.set('route1', calculatedRoute);
- * const route = cache.get('route1'); // O(1) lookup
- * // When 101st item added, oldest unused item is evicted
- * ```
- */
-export declare class LRUCache<K, V> {
-    private capacity;
-    private cache;
-    private head;
-    private tail;
-    private onEvict?;
-    constructor(capacity: number, options?: LRUCacheOptions<K, V>);
-    /**
-     * Get value by key, marks as recently used
-     * @returns Value if found, undefined otherwise
-     */
-    get(key: K): V | undefined;
-    /**
-     * Set key-value pair, evicts LRU item if capacity exceeded
-     */
-    set(key: K, value: V): void;
-    /**
-     * Check if key exists in cache
-     */
-    has(key: K): boolean;
-    /**
-     * Delete key from cache
-     * @returns true if key existed, false otherwise
-     */
-    delete(key: K): boolean;
-    /**
-     * Clear all entries from cache
-     */
-    clear(): void;
-    /**
-     * Get current number of entries in cache
-     */
-    size(): number;
-    /**
-     * Get cache capacity
-     */
-    getCapacity(): number;
-    /**
-     * Move node to head (most recently used position)
-     */
-    private moveToHead;
-    /**
-     * Add node to head of list
-     */
-    private addToHead;
-    /**
-     * Remove node from list
-     */
-    private removeNode;
-    /**
-     * Evict least recently used item (tail)
-     */
-    private evictLRU;
-}

package/src/libs/engine/src/performance/LRUCache.js

@@ -1,179 +0,0 @@
-"use strict";
-// LRUCache - Least Recently Used cache with automatic eviction (Phase 5.3)
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LRUCache = void 0;
-/**
- * Doubly-linked list node for O(1) removal and insertion
- */
-class LRUNode {
-    constructor(key, value, prev = null, next = null) {
-        this.key = key;
-        this.value = value;
-        this.prev = prev;
-        this.next = next;
-    }
-}
-/**
- * LRU (Least Recently Used) Cache with automatic eviction
- *
- * Features:
- * - O(1) get, set, delete operations
- * - Automatic eviction when capacity exceeded
- * - Customizable eviction callback
- * - Prevents unbounded memory growth
- *
- * @example
- * ```typescript
- * const cache = new LRUCache<string, Route>(100);
- * cache.set('route1', calculatedRoute);
- * const route = cache.get('route1'); // O(1) lookup
- * // When 101st item added, oldest unused item is evicted
- * ```
- */
-class LRUCache {
-    constructor(capacity, options) {
-        this.cache = new Map();
-        this.head = null; // Most recently used
-        this.tail = null; // Least recently used
-        if (capacity <= 0) {
-            throw new Error('Cache capacity must be greater than 0');
-        }
-        this.capacity = capacity;
-        this.onEvict = options === null || options === void 0 ? void 0 : options.onEvict;
-    }
-    /**
-     * Get value by key, marks as recently used
-     * @returns Value if found, undefined otherwise
-     */
-    get(key) {
-        const node = this.cache.get(key);
-        if (!node) {
-            return undefined;
-        }
-        // Move to head (most recently used)
-        this.moveToHead(node);
-        return node.value;
-    }
-    /**
-     * Set key-value pair, evicts LRU item if capacity exceeded
-     */
-    set(key, value) {
-        const existingNode = this.cache.get(key);
-        if (existingNode) {
-            // Update existing node
-            existingNode.value = value;
-            this.moveToHead(existingNode);
-        }
-        else {
-            // Create new node
-            const newNode = new LRUNode(key, value);
-            this.cache.set(key, newNode);
-            this.addToHead(newNode);
-            // Evict if over capacity
-            if (this.cache.size > this.capacity) {
-                this.evictLRU();
-            }
-        }
-    }
-    /**
-     * Check if key exists in cache
-     */
-    has(key) {
-        return this.cache.has(key);
-    }
-    /**
-     * Delete key from cache
-     * @returns true if key existed, false otherwise
-     */
-    delete(key) {
-        const node = this.cache.get(key);
-        if (!node) {
-            return false;
-        }
-        this.removeNode(node);
-        this.cache.delete(key);
-        return true;
-    }
-    /**
-     * Clear all entries from cache
-     */
-    clear() {
-        this.cache.clear();
-        this.head = null;
-        this.tail = null;
-    }
-    /**
-     * Get current number of entries in cache
-     */
-    size() {
-        return this.cache.size;
-    }
-    /**
-     * Get cache capacity
-     */
-    getCapacity() {
-        return this.capacity;
-    }
-    /**
-     * Move node to head (most recently used position)
-     */
-    moveToHead(node) {
-        if (node === this.head) {
-            return; // Already at head
-        }
-        // Remove from current position
-        this.removeNode(node);
-        // Add to head
-        this.addToHead(node);
-    }
-    /**
-     * Add node to head of list
-     */
-    addToHead(node) {
-        node.prev = null;
-        node.next = this.head;
-        if (this.head) {
-            this.head.prev = node;
-        }
-        this.head = node;
-        if (!this.tail) {
-            this.tail = node;
-        }
-    }
-    /**
-     * Remove node from list
-     */
-    removeNode(node) {
-        if (node.prev) {
-            node.prev.next = node.next;
-        }
-        else {
-            // Node is head
-            this.head = node.next;
-        }
-        if (node.next) {
-            node.next.prev = node.prev;
-        }
-        else {
-            // Node is tail
-            this.tail = node.prev;
-        }
-    }
-    /**
-     * Evict least recently used item (tail)
-     */
-    evictLRU() {
-        if (!this.tail) {
-            return;
-        }
-        const evicted = this.tail;
-        this.removeNode(evicted);
-        this.cache.delete(evicted.key);
-        // Call eviction callback if provided
-        if (this.onEvict) {
-            this.onEvict(evicted.key, evicted.value);
-        }
-    }
-}
-exports.LRUCache = LRUCache;
-//# sourceMappingURL=LRUCache.js.map

package/src/libs/engine/src/performance/PerformanceMonitor.d.ts

@@ -1,47 +0,0 @@
-export interface PerformanceConfig {
-    enableMonitoring?: boolean;
-    enableProfiling?: boolean;
-    warnThreshold?: number;
-}
-export interface PerformanceReport {
-    metrics: Record<string, PerformanceMetric>;
-    summary: {
-        totalOperations: number;
-        averageTime: number;
-        slowestOperation: string;
-        fastestOperation: string;
-    };
-}
-export interface PerformanceMetric {
-    count: number;
-    totalTime: number;
-    averageTime: number;
-    minTime: number;
-    maxTime: number;
-}
-export declare class PerformanceMonitor {
-    private config;
-    private metrics;
-    private warnThreshold;
-    constructor(config?: PerformanceConfig);
-    /**
-     * Measure operation performance
-     */
-    measure<T>(name: string, fn: () => T | Promise<T>): T | Promise<T>;
-    /**
-     * Set warning threshold
-     */
-    setWarnThreshold(threshold: number): void;
-    /**
-     * Get performance report
-     */
-    getReport(): PerformanceReport;
-    /**
-     * Clear all metrics
-     */
-    clear(): void;
-    /**
-     * Record metric
-     */
-    private recordMetric;
-}

package/src/libs/engine/src/performance/PerformanceMonitor.js

@@ -1,112 +0,0 @@
-"use strict";
-// PerformanceMonitor - Tracks operation performance and generates reports
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PerformanceMonitor = void 0;
-class PerformanceMonitor {
-    constructor(config = {}) {
-        var _a, _b, _c, _d;
-        this.metrics = new Map();
-        this.config = {
-            enableMonitoring: (_a = config.enableMonitoring) !== null && _a !== void 0 ? _a : false,
-            enableProfiling: (_b = config.enableProfiling) !== null && _b !== void 0 ? _b : false,
-            warnThreshold: (_c = config.warnThreshold) !== null && _c !== void 0 ? _c : 100,
-        };
-        this.warnThreshold = (_d = this.config.warnThreshold) !== null && _d !== void 0 ? _d : 100;
-    }
-    /**
-     * Measure operation performance
-     */
-    measure(name, fn) {
-        if (!this.config.enableMonitoring) {
-            return fn();
-        }
-        const startTime = performance.now();
-        const result = fn();
-        // Handle async functions
-        if (result instanceof Promise) {
-            return result.then((value) => {
-                const endTime = performance.now();
-                const duration = endTime - startTime;
-                this.recordMetric(name, duration);
-                if (duration > this.warnThreshold) {
-                    console.warn(`Performance warning: ${name} took ${duration.toFixed(2)}ms`);
-                }
-                return value;
-            });
-        }
-        // Handle sync functions
-        const endTime = performance.now();
-        const duration = endTime - startTime;
-        this.recordMetric(name, duration);
-        if (duration > this.warnThreshold) {
-            console.warn(`Performance warning: ${name} took ${duration.toFixed(2)}ms`);
-        }
-        return result;
-    }
-    /**
-     * Set warning threshold
-     */
-    setWarnThreshold(threshold) {
-        this.warnThreshold = threshold;
-    }
-    /**
-     * Get performance report
-     */
-    getReport() {
-        const metricsObj = {};
-        let totalOps = 0;
-        let totalTime = 0;
-        let slowest = { name: '', time: 0 };
-        let fastest = { name: '', time: Infinity };
-        for (const [name, metric] of this.metrics.entries()) {
-            metricsObj[name] = metric;
-            totalOps += metric.count;
-            totalTime += metric.totalTime;
-            if (metric.maxTime > slowest.time) {
-                slowest = { name, time: metric.maxTime };
-            }
-            if (metric.minTime < fastest.time) {
-                fastest = { name, time: metric.minTime };
-            }
-        }
-        return {
-            metrics: metricsObj,
-            summary: {
-                totalOperations: totalOps,
-                averageTime: totalOps > 0 ? totalTime / totalOps : 0,
-                slowestOperation: slowest.name,
-                fastestOperation: fastest.time !== Infinity ? fastest.name : '',
-            },
-        };
-    }
-    /**
-     * Clear all metrics
-     */
-    clear() {
-        this.metrics.clear();
-    }
-    /**
-     * Record metric
-     */
-    recordMetric(name, duration) {
-        const existing = this.metrics.get(name);
-        if (existing) {
-            existing.count++;
-            existing.totalTime += duration;
-            existing.averageTime = existing.totalTime / existing.count;
-            existing.minTime = Math.min(existing.minTime, duration);
-            existing.maxTime = Math.max(existing.maxTime, duration);
-        }
-        else {
-            this.metrics.set(name, {
-                count: 1,
-                totalTime: duration,
-                averageTime: duration,
-                minTime: duration,
-                maxTime: duration,
-            });
-        }
-    }
-}
-exports.PerformanceMonitor = PerformanceMonitor;
-//# sourceMappingURL=PerformanceMonitor.js.map

package/src/libs/engine/src/performance/SpatialIndex.d.ts

@@ -1,157 +0,0 @@
-import type { Rectangle } from '../types/geometry.types';
-/**
- * Configuration for SpatialIndex
- */
-export interface SpatialIndexConfig<T> {
-    /**
-     * Size of grid cells for spatial partitioning (default: 100)
-     */
-    cellSize?: number;
-    /**
-     * Function to extract bounds from entity
-     */
-    getBounds: (entity: T) => Rectangle;
-}
-/**
- * Query options for spatial queries
- */
-export interface QueryOptions<T> {
-    /**
-     * Filter function to exclude entities from results
-     */
-    filter?: (entity: T) => boolean;
-    /**
-     * Maximum number of entities to return
-     */
-    limit?: number;
-}
-/**
- * Generic spatial index using grid-based partitioning
- * Enables fast viewport queries for virtualization (O(visible) instead of O(all))
- *
- * Phase 5.1: Viewport Virtualization
- *
- * @example
- * ```typescript
- * const index = new SpatialIndex<NodeModel>({
- *   cellSize: 100,
- *   getBounds: (node) => ({
- *     x: node.position.x,
- *     y: node.position.y,
- *     width: node.size.width,
- *     height: node.size.height,
- *   }),
- * });
- *
- * index.add(node);
- * const visible = index.queryRegion(viewport);
- * ```
- */
-export declare class SpatialIndex<T extends {
-    id: string;
-}> {
-    private readonly cellSize;
-    private readonly getBounds;
-    /**
-     * Map of entity ID to entity
-     */
-    private entities;
-    /**
-     * Grid cells: cellKey -> Set<entityId>
-     * cellKey format: "row,col"
-     */
-    private grid;
-    constructor(config: SpatialIndexConfig<T>);
-    /**
-     * Add entity to spatial index
-     */
-    add(entity: T): void;
-    /**
-     * Update entity position in spatial index
-     */
-    update(entity: T): void;
-    /**
-     * Remove entity from spatial index
-     */
-    remove(id: string): boolean;
-    /**
-     * Get entity by ID
-     */
-    get(id: string): T | undefined;
-    /**
-     * Get number of entities in index
-     */
-    size(): number;
-    /**
-     * Clear all entities from index
-     */
-    clear(): void;
-    /**
-     * Query entities in rectangular region (viewport).
-     * This is the key method for viewport virtualization.
-     *
-     * Cost: O(cells(region) + k), where k = entities the region touches — EXCEPT
-     * that the grid walk is skipped entirely when it would be the slower half (see
-     * `shouldScanLinearly`), so the true bound is O(min(cells, n) + k).
-     */
-    queryRegion(region: Rectangle, options?: QueryOptions<T>): T[];
-    /**
-     * All entities whose bounds fall within `radius` of `point`, nearest first.
-     *
-     * wave8/culling — Card 2. Exists so interactive hit-testing (the nearest PORT
-     * to a dragged link end, the node under the cursor) is served by the index
-     * instead of a linear scan of the scene: a drag is a per-pointermove query, so
-     * an O(n) answer is O(n) sixty times a second.
-     *
-     * Distance is measured to the entity's bounding box (0 when the point is
-     * inside it), which is the right metric for "what am I pointing at" and lets
-     * a big entity win over a small distant one.
-     */
-    queryNear(point: {
-        x: number;
-        y: number;
-    }, radius: number, options?: QueryOptions<T>): T[];
-    /**
-     * True when walking the region's cells would touch more cells than the index
-     * holds entities — i.e. when the grid has stopped paying for itself.
-     *
-     * Counted, never materialised: building the key array to measure it would be
-     * the very cost we are avoiding.
-     */
-    private shouldScanLinearly;
-    /** Distance from a point to a rectangle; 0 when the point is inside it. */
-    private distanceToBounds;
-    /**
-     * Add entity to grid cells
-     */
-    private addToGrid;
-    /**
-     * Remove entity from grid cells
-     */
-    private removeFromGrid;
-    /**
-     * Get all grid cells that overlap with rectangle
-     */
-    private getOverlappingCells;
-    /**
-     * Get cell key for grid map
-     */
-    private getCellKey;
-    /**
-     * Check if two rectangles intersect
-     */
-    private rectanglesIntersect;
-    /**
-     * Get all entities (for testing/debugging)
-     */
-    getAllEntities(): T[];
-    /**
-     * Get grid statistics (for performance monitoring)
-     */
-    getStats(): {
-        entities: number;
-        cells: number;
-        averageEntitiesPerCell: number;
-        maxEntitiesPerCell: number;
-    };
-}