@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/presentation/presentation.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presentTo = presentTo;
+exports.followPresenter = followPresenter;
+exports.lockDocument = lockDocument;
+exports.isDocumentLocked = isDocumentLocked;
+exports.loadReadonlySnapshot = loadReadonlySnapshot;
+const engine_1 = require("@grafloria/engine");
+/**
+ * Broadcast this host's camera to `channel` for as long as the returned handle is
+ * alive. Returns a `stop()` that unsubscribes and cancels any pending trailing send.
+ */
+function presentTo(host, channel, options = {}) {
+    var _a;
+    const presenterId = options.presenterId;
+    const throttleMs = (_a = options.throttleMs) !== null && _a !== void 0 ? _a : 50;
+    let lastSentAt = 0;
+    let pending = null;
+    const payload = () => {
+        const vp = host.viewport.getViewport();
+        const zoom = host.viewport.getZoom();
+        // Centre, not origin: see viewport-channel.ts. viewport.width/height are the
+        // PRESENTER's canvas size and must never reach the follower.
+        return {
+            centerX: vp.x + vp.width / 2,
+            centerY: vp.y + vp.height / 2,
+            zoom,
+            presenterId,
+        };
+    };
+    const send = () => {
+        lastSentAt = Date.now();
+        channel.broadcastViewport(payload());
+    };
+    const onViewportChange = () => {
+        const since = Date.now() - lastSentAt;
+        if (since >= throttleMs) {
+            if (pending) {
+                clearTimeout(pending);
+                pending = null;
+            }
+            send();
+            return;
+        }
+        // Trailing edge: guarantee the FINAL position is published even if the
+        // presenter stops moving mid-throttle-window. Without it a follower ends a
+        // pan up to `throttleMs` of movement behind, permanently.
+        if (!pending) {
+            pending = setTimeout(() => {
+                pending = null;
+                send();
+            }, throttleMs - since);
+        }
+    };
+    const unsubscribe = host.viewport.onChange(onViewportChange);
+    // Publish immediately, so a follower who joins later gets the presenter's real
+    // position from the channel's replay rather than waiting for the next movement.
+    send();
+    return {
+        stop: () => {
+            unsubscribe();
+            if (pending) {
+                clearTimeout(pending);
+                pending = null;
+            }
+        },
+    };
+}
+/**
+ * Slave this host's camera to the presenter's, for as long as the handle is alive.
+ *
+ * The follower keeps its OWN canvas size and reconstructs the camera rectangle from
+ * the presenter's centre + zoom, so a follower on a different screen size sees the
+ * same content correctly framed — and, critically, its `clientToWorld()` stays the
+ * exact inverse of what it renders. Copying the presenter's rectangle wholesale
+ * would break that (see viewport-channel.ts).
+ */
+function followPresenter(host, channel, options = {}) {
+    // Re-entrancy guard: applying a remote viewport emits a local viewport change,
+    // and if this host is ALSO presenting, that would immediately re-broadcast what
+    // we just received — an echo loop between two clients that never settles.
+    let applying = false;
+    const unsubscribe = channel.onViewportBroadcast((incoming) => {
+        var _a;
+        if (applying)
+            return;
+        if (options.ignorePresenterId && incoming.presenterId === options.ignorePresenterId) {
+            return;
+        }
+        applying = true;
+        try {
+            const current = host.viewport.getViewport();
+            const width = current.width; // MY canvas, not the presenter's.
+            const height = current.height;
+            host.viewport.setZoom(incoming.zoom);
+            host.viewport.setViewport({
+                x: incoming.centerX - width / 2,
+                y: incoming.centerY - height / 2,
+                width,
+                height,
+            });
+        }
+        finally {
+            applying = false;
+        }
+        // The viewport IS part of the renderer's frame signature, so this repaint is
+        // not swallowed by the wave-8 frame gate — a follow that moves the camera
+        // always redraws. (A presenter CURSOR overlay would be a different story: it
+        // changes the picture without changing model or viewport, and would need
+        // renderer.invalidateFrame(). No cursor is drawn here, deliberately.)
+        host.render();
+        (_a = options.onFollow) === null || _a === void 0 ? void 0 : _a.call(options, incoming);
+    });
+    return { stop: unsubscribe };
+}
+// ===========================================================================
+// Read-only / share mode
+// ===========================================================================
+/**
+ * Lock (or unlock) the document through the engine's own mode.
+ *
+ * Thin on purpose: it drives `DiagramMode`, which this wave finally wired to real
+ * enforcement in the model and the CommandManager. There is no second read-only
+ * flag here, because a second flag is how you end up with two read-only modes that
+ * disagree.
+ */
+function lockDocument(engine, locked = true) {
+    engine.setMode(locked ? engine_1.DiagramMode.PRESENTATION : engine_1.DiagramMode.DESIGNER);
+}
+/** Is this engine's document locked against edits? */
+function isDocumentLocked(engine) {
+    var _a;
+    return ((_a = engine.getDiagram()) === null || _a === void 0 ? void 0 : _a.isReadonly()) === true;
+}
+/**
+ * Build a READ-ONLY document from a snapshot — the "share a link to a frozen copy"
+ * case.
+ *
+ * The load runs as a SYSTEM write, so it works even against an engine that is
+ * already in presentation mode. Otherwise the order of two host calls would decide
+ * whether the share link renders a diagram or an empty canvas: lock-then-load would
+ * have the lock (correctly!) refuse every node the loader tried to add.
+ */
+function loadReadonlySnapshot(engine, snapshot) {
+    // Deserialize into a FRESH model. It is detached and therefore unlocked, so
+    // fromJSON populates it normally — no system-write escape needed for the load
+    // itself, which keeps the escape hatch narrow.
+    const model = engine_1.DiagramModel.fromJSON(snapshot);
+    // Attach with the engine in a writable mode, THEN lock. `setDiagram` syncs the
+    // engine's mode onto the document, so attaching while already in PRESENTATION
+    // would be fine too — but doing it in this order means the lock is applied once,
+    // explicitly, and the snapshot is never racing a locked model.
+    engine.setMode(engine_1.DiagramMode.DESIGNER);
+    engine.setDiagram(model);
+    engine.setMode(engine_1.DiagramMode.PRESENTATION);
+    return model;
+}
+//# sourceMappingURL=presentation.js.map

package/src/libs/renderer/src/presentation/viewport-channel.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The follow-presenter seam — Wave 9, Card 7.
+ *
+ * ## THIS IS THE INTERFACE TO WIRE TO THE REAL AWARENESS CHANNEL
+ *
+ * "Follow presenter" needs a transport, and this wave's collaboration substrate
+ * (op log / CRDT / sync / awareness) is being built in parallel by other agents in
+ * `libs/engine/src/collab/**`. Rather than invent a second transport, or import a
+ * module that does not exist yet, presentation talks to exactly this two-method
+ * interface and nothing else.
+ *
+ * To connect it to the real awareness channel, implement {@link ViewportChannel}
+ * over it — broadcast on the presenter's awareness state, invoke the callback when
+ * a remote presenter's state arrives — and hand that object to `presentTo()` /
+ * `followPresenter()`. Nothing else in the presentation code needs to change, and
+ * nothing here imports from `collab/`.
+ *
+ * ## What travels: CENTRE + ZOOM, not the camera rectangle
+ *
+ * A `ViewportController`'s rectangle is `{x, y, width, height}` where x/y are WORLD
+ * coordinates but **width/height are the canvas's CSS-pixel size** — the viewer's
+ * own screen, not a world span (see the coordinate contract on ViewportController).
+ *
+ * So broadcasting the raw rectangle and applying it verbatim on the follower would
+ * overwrite the follower's canvas size with the presenter's. `clientToWorld()` would
+ * then stop being the inverse of the rendered `viewBox`, and the follower's
+ * hit-testing would silently desynchronise from its own picture — on a laptop
+ * following a phone, every click would land in the wrong place.
+ *
+ * What "follow me" actually means is *show the same world region at the same
+ * magnification*, so what travels is the presenter's world CENTRE and ZOOM. The
+ * follower keeps its own canvas size and derives its rectangle from those. Two
+ * viewers on differently-sized screens both end up looking at the same content,
+ * each correctly framed — which is the only sane behaviour and, not coincidentally,
+ * the only one that keeps hit-testing correct.
+ */
+import type { Unsubscribe } from '../viewport/viewport-controller';
+export type { Unsubscribe };
+/** What a presenter broadcasts. Centre + zoom, deliberately NOT a camera rect. */
+export interface PresenterViewport {
+    /** World X of the centre of the presenter's view. */
+    centerX: number;
+    /** World Y of the centre of the presenter's view. */
+    centerY: number;
+    /** The presenter's magnification. */
+    zoom: number;
+    /** Who is presenting. Lets a follower ignore its own echo, and label the UI. */
+    presenterId?: string;
+}
+/**
+ * The transport seam. Two methods, no lifecycle, no assumptions about the wire.
+ * Implement over WebSocket / WebRTC / Yjs awareness / BroadcastChannel / postMessage.
+ */
+export interface ViewportChannel {
+    /** Publish the presenter's current view to every follower. */
+    broadcastViewport(viewport: PresenterViewport): void;
+    /** Subscribe to presenter broadcasts. Returns an unsubscribe function. */
+    onViewportBroadcast(callback: (viewport: PresenterViewport) => void): Unsubscribe;
+}
+/**
+ * A working, in-process implementation — the local/in-memory transport this card
+ * ships so the feature is demonstrably complete end-to-end rather than an interface
+ * with nothing behind it.
+ *
+ * Genuinely useful beyond tests: it drives two `createDiagram()` instances on the
+ * same page (a presenter canvas and a follower/minimap canvas), which is a real
+ * product surface. Swap it for the network implementation and nothing else moves.
+ */
+export declare class InMemoryViewportChannel implements ViewportChannel {
+    private readonly subscribers;
+    private last;
+    broadcastViewport(viewport: PresenterViewport): void;
+    onViewportBroadcast(callback: (viewport: PresenterViewport) => void): Unsubscribe;
+    /** The most recent broadcast, or null. */
+    getLast(): PresenterViewport | null;
+    /** Drop all subscribers (teardown). */
+    dispose(): void;
+}

package/src/libs/renderer/src/presentation/viewport-channel.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * The follow-presenter seam — Wave 9, Card 7.
+ *
+ * ## THIS IS THE INTERFACE TO WIRE TO THE REAL AWARENESS CHANNEL
+ *
+ * "Follow presenter" needs a transport, and this wave's collaboration substrate
+ * (op log / CRDT / sync / awareness) is being built in parallel by other agents in
+ * `libs/engine/src/collab/**`. Rather than invent a second transport, or import a
+ * module that does not exist yet, presentation talks to exactly this two-method
+ * interface and nothing else.
+ *
+ * To connect it to the real awareness channel, implement {@link ViewportChannel}
+ * over it — broadcast on the presenter's awareness state, invoke the callback when
+ * a remote presenter's state arrives — and hand that object to `presentTo()` /
+ * `followPresenter()`. Nothing else in the presentation code needs to change, and
+ * nothing here imports from `collab/`.
+ *
+ * ## What travels: CENTRE + ZOOM, not the camera rectangle
+ *
+ * A `ViewportController`'s rectangle is `{x, y, width, height}` where x/y are WORLD
+ * coordinates but **width/height are the canvas's CSS-pixel size** — the viewer's
+ * own screen, not a world span (see the coordinate contract on ViewportController).
+ *
+ * So broadcasting the raw rectangle and applying it verbatim on the follower would
+ * overwrite the follower's canvas size with the presenter's. `clientToWorld()` would
+ * then stop being the inverse of the rendered `viewBox`, and the follower's
+ * hit-testing would silently desynchronise from its own picture — on a laptop
+ * following a phone, every click would land in the wrong place.
+ *
+ * What "follow me" actually means is *show the same world region at the same
+ * magnification*, so what travels is the presenter's world CENTRE and ZOOM. The
+ * follower keeps its own canvas size and derives its rectangle from those. Two
+ * viewers on differently-sized screens both end up looking at the same content,
+ * each correctly framed — which is the only sane behaviour and, not coincidentally,
+ * the only one that keeps hit-testing correct.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryViewportChannel = void 0;
+/**
+ * A working, in-process implementation — the local/in-memory transport this card
+ * ships so the feature is demonstrably complete end-to-end rather than an interface
+ * with nothing behind it.
+ *
+ * Genuinely useful beyond tests: it drives two `createDiagram()` instances on the
+ * same page (a presenter canvas and a follower/minimap canvas), which is a real
+ * product surface. Swap it for the network implementation and nothing else moves.
+ */
+class InMemoryViewportChannel {
+    constructor() {
+        this.subscribers = new Set();
+        this.last = null;
+    }
+    broadcastViewport(viewport) {
+        this.last = Object.assign({}, viewport);
+        // Copy the subscriber set before iterating: a follower is allowed to
+        // unsubscribe from inside its own callback (stopFollowing() on the first
+        // frame is a real pattern), and mutating a Set mid-iteration would skip a
+        // subscriber.
+        for (const subscriber of [...this.subscribers]) {
+            subscriber(Object.assign({}, viewport));
+        }
+    }
+    onViewportBroadcast(callback) {
+        this.subscribers.add(callback);
+        // Replay the latest state to a late joiner. Someone who opens the link after
+        // the presenter has already moved must land where the presenter IS, not sit on
+        // a default camera until the presenter happens to twitch.
+        if (this.last)
+            callback(Object.assign({}, this.last));
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    /** The most recent broadcast, or null. */
+    getLast() {
+        return this.last ? Object.assign({}, this.last) : null;
+    }
+    /** Drop all subscribers (teardown). */
+    dispose() {
+        this.subscribers.clear();
+        this.last = null;
+    }
+}
+exports.InMemoryViewportChannel = InMemoryViewportChannel;
+//# sourceMappingURL=viewport-channel.js.map

package/src/libs/renderer/src/services/animation-lifecycle.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Animation Lifecycle Hooks
+ *
+ * Phase 1.1: Provides callbacks for animation lifecycle events
+ * Uses native AnimationEvent API to track when animations start, end, iterate, or cancel
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = new AnimationLifecycleManager();
+ *
+ * // Listen to specific animation events
+ * lifecycle.on('start', 'my-animation', (event) => {
+ *   console.log('Animation started!', event);
+ * });
+ *
+ * lifecycle.on('end', 'my-animation', (event) => {
+ *   console.log('Animation ended!', event);
+ * });
+ *
+ * // Track all animations on an element
+ * lifecycle.trackElement(myElement);
+ * ```
+ */
+/**
+ * Animation lifecycle event types
+ */
+export type AnimationLifecycleEvent = 'start' | 'end' | 'iteration' | 'cancel';
+/**
+ * Animation event data
+ */
+export interface AnimationEventData {
+    /** Animation name */
+    animationName: string;
+    /** Element the animation is applied to */
+    element: HTMLElement;
+    /** Event type */
+    type: AnimationLifecycleEvent;
+    /** Elapsed time when event occurred */
+    elapsedTime: number;
+    /** Pseudo-element (if applicable) */
+    pseudoElement?: string;
+    /** Original AnimationEvent */
+    originalEvent: AnimationEvent;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Lifecycle callback function
+ */
+export type LifecycleCallback = (data: AnimationEventData) => void;
+/**
+ * Animation Lifecycle Manager
+ *
+ * Manages lifecycle event listeners for CSS animations
+ */
+export declare class AnimationLifecycleManager {
+    private trackedElements;
+    private listeners;
+    private globalListeners;
+    private elementListeners;
+    constructor();
+    /**
+     * Initialize listener maps
+     */
+    private initializeListenerMaps;
+    /**
+     * Track an element for animation events
+     */
+    trackElement(element: HTMLElement): void;
+    /**
+     * Untrack an element
+     */
+    untrackElement(element: HTMLElement): void;
+    /**
+     * Listen to a specific animation lifecycle event
+     *
+     * @param eventType - Type of event ('start', 'end', 'iteration', 'cancel')
+     * @param animationName - Name of the animation to listen for
+     * @param callback - Callback function
+     * @returns Unsubscribe function
+     */
+    on(eventType: AnimationLifecycleEvent, animationName: string, callback: LifecycleCallback): () => void;
+    /**
+     * Listen to all animations for a specific event type
+     *
+     * @param eventType - Type of event
+     * @param callback - Callback function
+     * @returns Unsubscribe function
+     */
+    onAll(eventType: AnimationLifecycleEvent, callback: LifecycleCallback): () => void;
+    /**
+     * Listen to animations on a specific element
+     *
+     * @param element - Element to listen to
+     * @param eventType - Type of event
+     * @param callback - Callback function
+     * @returns Unsubscribe function
+     */
+    onElement(element: HTMLElement, eventType: AnimationLifecycleEvent, callback: LifecycleCallback): () => void;
+    /**
+     * Remove all listeners for a specific animation
+     */
+    off(eventType: AnimationLifecycleEvent, animationName: string): void;
+    /**
+     * Handle animation start event
+     */
+    private handleAnimationStart;
+    /**
+     * Handle animation end event
+     */
+    private handleAnimationEnd;
+    /**
+     * Handle animation iteration event
+     */
+    private handleAnimationIteration;
+    /**
+     * Handle animation cancel event
+     */
+    private handleAnimationCancel;
+    /**
+     * Dispatch event to all relevant listeners
+     */
+    private dispatchEvent;
+    /**
+     * Wait for an animation to end
+     * Returns a promise that resolves when the animation ends
+     */
+    waitFor(animationName: string, element?: HTMLElement): Promise<AnimationEventData>;
+    /**
+     * Wait for any animation to complete on an element
+     */
+    waitForElement(element: HTMLElement): Promise<AnimationEventData>;
+    /**
+     * Get all tracked elements
+     */
+    getTrackedElements(): HTMLElement[];
+    /**
+     * Check if element is being tracked
+     */
+    isTracking(element: HTMLElement): boolean;
+    /**
+     * Cleanup: Remove all listeners and untrack all elements
+     */
+    destroy(): void;
+}
+/**
+ * Get the global animation lifecycle manager
+ */
+export declare function getGlobalAnimationLifecycleManager(): AnimationLifecycleManager;
+/**
+ * Reset the global lifecycle manager (useful for testing)
+ */
+export declare function resetGlobalAnimationLifecycleManager(): void;