@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/commands/basic/resolveLinkNodeIds.js

@@ -0,0 +1,49 @@
+"use strict";
+// Shared link-endpoint → owning-node resolution for clipboard/delete commands
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLinkNodeIds = resolveLinkNodeIds;
+/**
+ * Resolve the ids of the nodes a link is attached to.
+ *
+ * WHY THIS EXISTS: a link's `sourcePortId`/`targetPortId` are PORT ids — engine
+ * nanoids — NOT `"nodeId:portName"` strings. Commands that used
+ * `portId.split(':')[0]` to get a node id therefore resolved nothing for links
+ * created the production way (`diagram.connectNodes()` / the interactive connect
+ * path), which silently:
+ *   - made CopyCommand skip every link between the copied nodes, and
+ *   - made DeleteSelectionCommand leave ORPHAN links behind when it deleted the
+ *     nodes at both ends (`removeNode()` does not cascade to links).
+ *
+ * Resolution order:
+ *   1. the ids LinkModel caches (`sourceNodeId` / `targetNodeId`, backfilled by
+ *      `addLink()` / `restoreLink()` from the port index),
+ *   2. the diagram's O(1) port index (`getNodeByPortId`),
+ *   3. the legacy `"nodeId:portName"` convention — still used by hand-built test
+ *      links and older documents — but only when it names a node that actually
+ *      exists.
+ *
+ * @returns the owning node ids; either may be `undefined` for a dangling endpoint.
+ */
+function resolveLinkNodeIds(diagram, link) {
+    return {
+        sourceNodeId: resolveEndpointNodeId(diagram, link.sourcePortId, link.sourceNodeId),
+        targetNodeId: resolveEndpointNodeId(diagram, link.targetPortId, link.targetNodeId),
+    };
+}
+function resolveEndpointNodeId(diagram, portId, cachedNodeId) {
+    var _a;
+    if (cachedNodeId && diagram.getNode(cachedNodeId)) {
+        return cachedNodeId;
+    }
+    const owner = (_a = diagram.getNodeByPortId) === null || _a === void 0 ? void 0 : _a.call(diagram, portId);
+    if (owner) {
+        return owner.id;
+    }
+    // Legacy "nodeId:portName" endpoints.
+    const legacyId = portId.split(':')[0];
+    if (legacyId && legacyId !== portId && diagram.getNode(legacyId)) {
+        return legacyId;
+    }
+    return undefined;
+}
+//# sourceMappingURL=resolveLinkNodeIds.js.map

package/src/libs/engine/src/commands/composite/BatchCommand.d.ts

@@ -0,0 +1,19 @@
+import { Command, CommandContext, SerializedCommand } from '../Command';
+export declare class BatchCommand extends Command {
+    private commands;
+    constructor(name: string, commands: Command[]);
+    execute(context: CommandContext): Promise<void>;
+    undo(context: CommandContext): Promise<void>;
+    canExecute(context: CommandContext): boolean;
+    canUndo(context: CommandContext): boolean;
+    serialize(): SerializedCommand;
+    getDescription(): string;
+    /**
+     * Get all commands in batch
+     */
+    getCommands(): ReadonlyArray<Command>;
+    /**
+     * Add command to batch
+     */
+    addCommand(command: Command): void;
+}

package/src/libs/engine/src/commands/composite/BatchCommand.js

@@ -0,0 +1,61 @@
+"use strict";
+// BatchCommand - Executes multiple commands as a single operation
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchCommand = void 0;
+const tslib_1 = require("tslib");
+const Command_1 = require("../Command");
+class BatchCommand extends Command_1.Command {
+    constructor(name, commands) {
+        super(name);
+        this.commands = commands;
+    }
+    execute(context) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            for (const command of this.commands) {
+                yield command.execute(context);
+            }
+        });
+    }
+    undo(context) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Undo in reverse order
+            for (let i = this.commands.length - 1; i >= 0; i--) {
+                yield ((_a = this.commands[i]) === null || _a === void 0 ? void 0 : _a.undo(context));
+            }
+        });
+    }
+    canExecute(context) {
+        return this.commands.every((cmd) => cmd.canExecute(context));
+    }
+    canUndo(context) {
+        return this.commands.every((cmd) => cmd.canUndo(context));
+    }
+    serialize() {
+        return {
+            id: this.id,
+            name: this.name,
+            timestamp: this.timestamp,
+            data: {
+                commands: this.commands.map((cmd) => cmd.serialize()),
+            },
+        };
+    }
+    getDescription() {
+        return `${this.name} (${this.commands.length} operations)`;
+    }
+    /**
+     * Get all commands in batch
+     */
+    getCommands() {
+        return [...this.commands];
+    }
+    /**
+     * Add command to batch
+     */
+    addCommand(command) {
+        this.commands.push(command);
+    }
+}
+exports.BatchCommand = BatchCommand;
+//# sourceMappingURL=BatchCommand.js.map

package/src/libs/engine/src/commands/composite/MacroCommand.d.ts

@@ -0,0 +1,35 @@
+import { Command, CommandContext, SerializedCommand } from '../Command';
+export interface MacroStep {
+    command: Command;
+    delay?: number;
+}
+export declare class MacroCommand extends Command {
+    private steps;
+    constructor(name: string);
+    /**
+     * Add step to macro
+     */
+    addStep(command: Command, delay?: number): void;
+    /**
+     * Add multiple steps
+     */
+    addSteps(commands: Command[]): void;
+    execute(context: CommandContext): Promise<void>;
+    undo(context: CommandContext): Promise<void>;
+    canExecute(context: CommandContext): boolean;
+    canUndo(context: CommandContext): boolean;
+    serialize(): SerializedCommand;
+    getDescription(): string;
+    /**
+     * Get all steps in macro
+     */
+    getSteps(): ReadonlyArray<MacroStep>;
+    /**
+     * Clear all steps
+     */
+    clear(): void;
+    /**
+     * Sleep utility for delays
+     */
+    private sleep;
+}

package/src/libs/engine/src/commands/composite/MacroCommand.js

@@ -0,0 +1,87 @@
+"use strict";
+// MacroCommand - Named sequence of commands that can be recorded and replayed
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MacroCommand = void 0;
+const tslib_1 = require("tslib");
+const Command_1 = require("../Command");
+class MacroCommand extends Command_1.Command {
+    constructor(name) {
+        super(name);
+        this.steps = [];
+    }
+    /**
+     * Add step to macro
+     */
+    addStep(command, delay) {
+        this.steps.push({ command, delay });
+    }
+    /**
+     * Add multiple steps
+     */
+    addSteps(commands) {
+        commands.forEach((cmd) => this.addStep(cmd));
+    }
+    execute(context) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            for (const step of this.steps) {
+                if (step.delay) {
+                    yield this.sleep(step.delay);
+                }
+                yield step.command.execute(context);
+            }
+        });
+    }
+    undo(context) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            // Undo in reverse order
+            for (let i = this.steps.length - 1; i >= 0; i--) {
+                const step = this.steps[i];
+                if (step) {
+                    yield step.command.undo(context);
+                }
+            }
+        });
+    }
+    canExecute(context) {
+        return this.steps.every((step) => step.command.canExecute(context));
+    }
+    canUndo(context) {
+        return this.steps.every((step) => step.command.canUndo(context));
+    }
+    serialize() {
+        return {
+            id: this.id,
+            name: this.name,
+            timestamp: this.timestamp,
+            data: {
+                steps: this.steps.map((step) => ({
+                    command: step.command.serialize(),
+                    delay: step.delay,
+                })),
+            },
+        };
+    }
+    getDescription() {
+        return `${this.name} (${this.steps.length} steps)`;
+    }
+    /**
+     * Get all steps in macro
+     */
+    getSteps() {
+        return [...this.steps];
+    }
+    /**
+     * Clear all steps
+     */
+    clear() {
+        this.steps = [];
+    }
+    /**
+     * Sleep utility for delays
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.MacroCommand = MacroCommand;
+//# sourceMappingURL=MacroCommand.js.map

package/src/libs/engine/src/commands/composite/index.d.ts

@@ -0,0 +1,2 @@
+export * from './BatchCommand';
+export * from './MacroCommand';

package/src/libs/engine/src/commands/composite/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// Composite commands index
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./BatchCommand"), exports);
+tslib_1.__exportStar(require("./MacroCommand"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/engine/src/commands/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Command';
+export * from './CommandManager';
+export * from './basic';
+export * from './composite';

package/src/libs/engine/src/commands/index.js

@@ -0,0 +1,9 @@
+"use strict";
+// Commands index - exports command system
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./Command"), exports);
+tslib_1.__exportStar(require("./CommandManager"), exports);
+tslib_1.__exportStar(require("./basic"), exports);
+tslib_1.__exportStar(require("./composite"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/engine/src/comments/comment-store.d.ts

@@ -0,0 +1,238 @@
+import { DiagramModel } from '../models/DiagramModel';
+import { type MentionNotifier } from './mentions';
+import { ReadState } from './read-state';
+import { type CommentAnchor, type CommentThreadView, type ResolvedAnchor } from './types';
+/** What a caller asks for. The store fills in the obituary (fallback point + label). */
+export type AnchorSpec = {
+    kind: 'node';
+    id: string;
+} | {
+    kind: 'link';
+    id: string;
+} | {
+    kind: 'region';
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+};
+export interface CommentStoreOptions {
+    /**
+     * The PERSON at this peer. Not the actor/session id.
+     *
+     * These are genuinely different and conflating them is a real bug: an actor id is
+     * per-session (open two tabs, get two actors) and exists to break ties in the total
+     * order. A comment is authored by a HUMAN, who is the same human in both tabs and is
+     * still the same human tomorrow when the session id is long gone.
+     */
+    viewer: string;
+    /** Deterministic ids for tests. Default: unique by construction (see `mintId`). */
+    idFactory?: () => string;
+    /** Deterministic time for tests. Default: Date.now. */
+    now?: () => number;
+    /** The @mention seam. Absent ⇒ mentions are still parsed, stored and queryable. */
+    notifier?: MentionNotifier;
+    /** This viewer's unread watermarks — hand back what you persisted. */
+    readState?: ReadState;
+    /** How to name an entity. Default: `metadata.label`, then `type`, then the id. */
+    labelOf?: (kind: 'node' | 'link', id: string) => string | undefined;
+}
+type Unsub = () => void;
+export declare class CommentStore {
+    readonly diagram: DiagramModel;
+    private readonly opts;
+    readonly readState: ReadState;
+    /**
+     * WHERE THE TARGET WAS, LAST TIME WE SAW IT ALIVE.
+     *
+     * The anchor carries a `fallback` point captured when the thread was CREATED. If the
+     * node then gets dragged across the canvas and only afterwards deleted, that fallback
+     * is stale by however far it moved, and the ghost pin would appear somewhere the node
+     * has not been for an hour — which is worse than useless, it is misleading.
+     *
+     * The fix must not cost traffic: broadcasting the node's position into the anchor on
+     * every drag frame would sync DERIVED geometry, which is exactly what capture.ts
+     * refuses to do and for exactly the right reasons. So each peer simply REMEMBERS,
+     * locally, where it last saw the target. Free, precise, and not one byte on the wire.
+     *
+     * A peer that joined after the delete never saw it and falls back to the op-borne
+     * snapshot. That peer's ghost pin is a little stale. It is also the only thing anyone
+     * could possibly know, so it is the right answer.
+     */
+    private readonly lastKnownPoint;
+    /** Message ids this store has already dispatched mention events for. */
+    private readonly notified;
+    private readonly subs;
+    private unsubscribe;
+    private counter;
+    constructor(diagram: DiagramModel, options: CommentStoreOptions);
+    /**
+     * Start a thread. Three ops: head, anchor, first message.
+     *
+     * Three and not one, because `comments.<tid>` and `comments.<tid>.status` would be
+     * OVERLAPPING registers — LWW cannot order two writes to different paths, so a
+     * whole-thread write that arrived late would silently wipe a resolve. Prefix-free
+     * leaves are the price of correctness under out-of-order delivery, and the fuzz test
+     * asserts prefix-freedom rather than trusting me to remember it.
+     */
+    createThread(spec: AnchorSpec, body: string): string;
+    /** Add a message. ONE register — which is why a colleague's simultaneous reply lives. */
+    reply(threadId: string, body: string): string;
+    /**
+     * Edit a message: rewrite its register whole.
+     *
+     * Two people editing the same message concurrently is a genuine conflict on one
+     * register and LWW picks one, deterministically, on every peer. That is the right
+     * answer — an edit IS a whole-body replacement, so there is no finer cut that would
+     * have saved both, and merging two rewrites of one sentence produces a sentence
+     * neither person wrote.
+     */
+    editMessage(threadId: string, messageId: string, body: string): boolean;
+    /**
+     * Delete a message — TOMBSTONE, never key removal.
+     *
+     * Removing the key would let a concurrent edit of the same message resurrect it from
+     * the dead (the edit's register write auto-creates the path again), and it would shift
+     * the ordering of the surviving messages on a peer that has not yet seen the delete.
+     * A tombstone keeps the author and the timestamp, so the conversation still reads in
+     * the order it happened, with a hole where somebody withdrew something — which is what
+     * actually occurred.
+     */
+    deleteMessage(threadId: string, messageId: string): boolean;
+    resolve(threadId: string): boolean;
+    reopen(threadId: string): boolean;
+    /** Re-point a thread — the manual rescue for an orphan, and the only way to move one. */
+    reanchor(threadId: string, spec: AnchorSpec): boolean;
+    private setStatus;
+    private writeMessage;
+    /** Snapshot the target's position and name INTO the anchor. Its obituary, written early. */
+    private buildAnchor;
+    /**
+     * WHERE THE PIN GOES, AND WHETHER ITS SUBJECT STILL EXISTS.
+     *
+     * ===========================================================================
+     * WHAT HAPPENS TO A COMMENT WHEN SOMEBODY DELETES ITS NODE
+     * ===========================================================================
+     *
+     * It survives. It becomes ORPHANED — visibly detached, still readable, still
+     * replyable, still listed — and it never, under any circumstance, disappears.
+     *
+     * Argued from the user's side, because that is the only side that matters here. A
+     * thread is a conversation between PEOPLE. The node is merely what it was about. If
+     * Ben deletes a box and that silently destroys the eight-message design argument Ada
+     * and Chen had about it, then a routine edit has quietly deleted other people's work —
+     * work they cannot recover, cannot see was lost, and were never asked about. Worse, the
+     * comment is very often ABOUT the deletion ("why is this still here? we cut this in
+     * March") — so the delete would destroy precisely the discussion that authorised it.
+     * There is no version of that trade that is worth a tidier canvas.
+     *
+     * The inverse mistake is just as bad: keeping the pin attached to nothing, hovering at
+     * the coordinates of a box that is gone. That is a lie with a timestamp on it. So the
+     * orphan is DRAWN DIFFERENTLY, NAMED DIFFERENTLY ("detached"), and grouped separately
+     * in the panel. The user is told, in the place they are looking, exactly what happened.
+     *
+     * ===========================================================================
+     * AND WHY `attached` IS DERIVED RATHER THAN STORED — this is the subtle half
+     * ===========================================================================
+     *
+     * The obvious implementation writes an `orphaned: true` flag when the node dies. It is
+     * wrong three ways, and every one of them bites:
+     *
+     *   1. IT RACES. Marking a thread orphaned would be an OP, emitted by whichever peer
+     *      noticed the delete first. Two peers notice, two ops. Worse, the flag now merges
+     *      by LWW against a concurrent un-delete, and the flag can converge to a value that
+     *      contradicts the diagram it is meant to describe: `orphaned: true` on a thread
+     *      whose node is manifestly right there. Derived state cannot contradict its source.
+     *      Stored state can, and eventually will.
+     *   2. IT BREAKS UNDO. Ctrl-Z brings the node back. A stored flag would need a second
+     *      op to un-orphan the thread, from some peer that thought to look, and until then
+     *      the thread sits detached beside the node it is attached to. Derived, the thread
+     *      RE-ATTACHES on the very next read, with zero ops and zero code.
+     *   3. IT ASSUMES AN ANSWER THE CRDT CARD HAS NOT GIVEN YET. Card 4 is concurrently
+     *      deciding whether a remove beats a concurrent add, or whether an observed-remove
+     *      set lets the add survive. If they land on add-wins, a node this store had marked
+     *      dead comes back. Deriving the state means BOTH answers are already handled and
+     *      neither can be wrong: whatever the diagram says right now, the pin agrees with
+     *      it. That is the only way to be robust to a decision that has not been made.
+     *
+     * So: nothing is stored, nothing is broadcast, and `attached` is simply "is the entity
+     * in the diagram, right now". The thread survives the delete BY NOT DEPENDING ON THE
+     * ENTITY AT ALL.
+     */
+    resolveAnchor(threadId: string, anchor: CommentAnchor): ResolvedAnchor;
+    /** The live world point for an entity, or undefined if it is not in the diagram. */
+    private livePoint;
+    private linkMidpoint;
+    private endpointCenter;
+    private labelOf;
+    private tree;
+    private head;
+    private message;
+    /**
+     * Assemble a thread for reading.
+     *
+     * INCOMPLETE THREADS ARE INVISIBLE, NOT BROKEN. A thread is three ops, and an
+     * unreliable transport is free to deliver the reply before the head that owns it — the
+     * substrate says so out loud (causal readiness is explicitly Card 4/5's, and until they
+     * ship it, `applyOp` will happily write `comments.t1.messages.m1` into a tree with no
+     * `t1.head`). A store that crashed on that would be broken by a packet reorder; a store
+     * that rendered a half-thread would show a message from nobody, about nothing. So a
+     * thread without a head or an anchor simply does not exist yet, and it appears — whole,
+     * with every message that arrived early already in it — the moment its head lands.
+     * Nothing is dropped; the pieces just wait.
+     */
+    thread(threadId: string): CommentThreadView | undefined;
+    /** Every readable thread, in a stable order identical on every peer. */
+    threads(options?: {
+        includeResolved?: boolean;
+    }): CommentThreadView[];
+    /** Threads whose subject is gone. Derived, every time. Never stored, never synced. */
+    orphans(): CommentThreadView[];
+    /** Threads anchored to a given entity — attached ones only. */
+    threadsFor(kind: 'node' | 'link', id: string): CommentThreadView[];
+    markRead(threadId: string): void;
+    markUnread(threadId: string): void;
+    /** Unread messages across every unresolved thread — the number a badge shows. */
+    totalUnread(): number;
+    /** Threads that @mention this viewer and that they have not read. */
+    mentionsOfViewer(): CommentThreadView[];
+    /**
+     * A message has entered the store — local or remote, first time only. Fire the seam.
+     *
+     * Fires on EVERY peer that receives the op, with an idempotency key that is identical
+     * on all of them. That is deliberate and it is documented in mentions.ts: the engine
+     * cannot know which peer is privileged, so it tells all of them the same true thing and
+     * gives the host the one piece of information it needs to send exactly one email.
+     */
+    private onCommentsChanged;
+    /** Fired whenever the comment DATA or this viewer's READ STATE changes. */
+    onChange(cb: () => void): Unsub;
+    private emit;
+    dispose(): void;
+    private now;
+    /**
+     * A globally unique id, minted by the AUTHORING peer and carried in the op.
+     *
+     * Determinism is preserved even though this is random, and the distinction matters: a
+     * random id chosen INSIDE a reducer would make replay non-deterministic and destroy
+     * every guarantee in the substrate. A random id chosen at AUTHORING time is just a
+     * value in the payload — every peer replays the same one forever.
+     *
+     * A per-session counter alone would be a disaster: restart the tab and it restarts at
+     * 1, so `alice-m1` collides with a message alice wrote yesterday, whose register it
+     * would then silently OVERWRITE. Hence time + a counter + randomness, and an
+     * `idFactory` seam so tests can be deterministic without the production path pretending
+     * to be.
+     *
+     * THE COUNTER SITS BEFORE THE RANDOM SUFFIX, AND THAT ORDERING IS LOAD-BEARING. The id
+     * is the LAST tiebreak in `messageOrder` — (createdAt, author, id) — so it decides the
+     * order of two messages written by the same person in the same MILLISECOND. Put the
+     * random part first and that decision is a coin toss: paste two comments in quick
+     * succession and they can read back in the wrong order. (Found by a test with a frozen
+     * clock, which is the only way a millisecond collision is reliably reproducible.) With
+     * the zero-padded counter in front, same-millisecond messages sort in the order they
+     * were actually written — on every peer, forever, because the id travels in the op.
+     */
+    private mintId;
+}
+export {};