@grafloria/element 0.3.20 → 0.3.21

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

@@ -1,158 +0,0 @@
-"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

@@ -1,78 +0,0 @@
-/**
- * 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

@@ -1,86 +0,0 @@
-"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

@@ -1,153 +0,0 @@
-/**
- * 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;