@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/comments/mentions.js

@@ -0,0 +1,94 @@
+"use strict";
+// Wave 9 — Card 6: @mentions.
+//
+// ===========================================================================
+// A SEAM, NOT A NOTIFICATION BACKEND
+// ===========================================================================
+//
+// A diagram engine has no business owning email, push, Slack or a user directory. What
+// it CAN own, and what nobody else can, is the two facts a notifier needs and cannot
+// reconstruct: WHO was mentioned, and WHICH message mentioned them. That is the seam.
+//
+// THE HARD PART IS NOT PARSING. It is that a collaborative document has N peers, every
+// one of which will observe the same @mention op, and every one of which will fire this
+// event. Wire a naive notifier to it and Ada gets one email per peer that happened to
+// have the file open. That is not a hypothetical: it is what happens the first time
+// somebody does the obvious thing.
+//
+// So the event carries an IDEMPOTENCY KEY — `${threadId}:${messageId}` — which is the
+// SAME string on every peer, forever, across reloads and replays, because it is derived
+// from data carried in the op rather than from anything local. A host has two correct
+// ways to use it, and the seam supports both:
+//
+//   • SERVER-SIDE (recommended): run the notifier on the relay/server replica only. It
+//     sees every op exactly once and is the only peer that should hold mail credentials.
+//   • CLIENT-SIDE: fire from every peer and DEDUPE ON `key` at the backend (an upsert on
+//     a unique index, a Redis SETNX, whatever). The key makes that a one-liner.
+//
+// What a host must wire, in full:
+//   1. an implementation of MentionNotifier (email/push/websocket/whatever),
+//   2. a directory that maps the ids in `mentioned` to real users — the engine never
+//      invents one, because a mention id is a HOST identifier and only the host knows
+//      what `@ada` means,
+//   3. deduplication on `key` (or a single privileged replica).
+//
+// Everything else is done here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMentions = parseMentions;
+exports.mentionIds = mentionIds;
+exports.mentionKey = mentionKey;
+/**
+ * Two syntaxes, because two things are true at once.
+ *
+ * `@[Ada Lovelace](u_ada)` — what a real mention-PICKER emits: the display name and the
+ * stable id, decoupled, so renaming Ada does not orphan the mention and two Adas do not
+ * collide. This is the form the product should write.
+ *
+ * `@ada` — what a human TYPES. It is ambiguous by nature (a handle is not an id), and we
+ * do not pretend otherwise: the id is the handle verbatim, and it is the host's directory
+ * that decides whether `ada` resolves to anyone at all. Refusing to parse it would just
+ * mean every host writes this regex again, worse.
+ *
+ * Ordered `@[...](...)` first so the explicit form is never mis-lexed as a bare handle.
+ */
+const EXPLICIT = /@\[([^\]\n]+)\]\(([^)\s]+)\)/g;
+// A bare handle: letters, digits, dot, dash, underscore. Must not be preceded by a word
+// character — otherwise every email address in a comment becomes a mention of its domain.
+const BARE = /(^|[^\w@[\]()])@([A-Za-z0-9][\w.-]*)/g;
+/**
+ * Extract the mentions from a body. Pure, and total: never throws, never re-orders.
+ *
+ * Deduplicated by id — mentioning Ada three times in one message is one notification, not
+ * three, and that is a property of the DATA, not of the notifier's retry policy.
+ */
+function parseMentions(body) {
+    if (!body)
+        return [];
+    const found = [];
+    const claimed = [];
+    EXPLICIT.lastIndex = 0;
+    for (let m = EXPLICIT.exec(body); m; m = EXPLICIT.exec(body)) {
+        found.push({ id: m[2], display: m[1], raw: m[0], index: m.index });
+        claimed.push([m.index, m.index + m[0].length]);
+    }
+    BARE.lastIndex = 0;
+    for (let m = BARE.exec(body); m; m = BARE.exec(body)) {
+        const at = m.index + m[1].length; // skip the required preceding character
+        // Do not double-count the `@` of an explicit mention we already took.
+        if (claimed.some(([s, e]) => at >= s && at < e))
+            continue;
+        found.push({ id: m[2], display: m[2], raw: `@${m[2]}`, index: at });
+    }
+    found.sort((a, b) => a.index - b.index);
+    const seen = new Set();
+    return found.filter((r) => (seen.has(r.id) ? false : (seen.add(r.id), true)));
+}
+/** Just the ids — what gets stored on the message register. */
+function mentionIds(body) {
+    return parseMentions(body).map((r) => r.id);
+}
+/** The idempotency key. Derived only from op-borne data — never from local state. */
+function mentionKey(threadId, messageId) {
+    return `${threadId}:${messageId}`;
+}
+//# sourceMappingURL=mentions.js.map

package/src/libs/engine/src/comments/read-state.d.ts

@@ -0,0 +1,37 @@
+import { type CommentMessage } from './types';
+/** The serializable shape. Give this to the host to persist; hand it back on load. */
+export interface SerializedReadState {
+    viewer: string;
+    /** threadId → the messageKey of the newest message this viewer has seen. */
+    watermarks: Record<string, string>;
+}
+/**
+ * What THIS viewer has seen. Local. Never synced.
+ */
+export declare class ReadState {
+    readonly viewer: string;
+    private readonly watermarks;
+    constructor(viewer: string);
+    /**
+     * Mark a thread read up to its newest message.
+     *
+     * Takes the messages rather than a key so the caller cannot accidentally set a
+     * watermark ahead of the messages it has actually seen — which would silently swallow
+     * a message that is still in flight.
+     */
+    markRead(threadId: string, messages: readonly CommentMessage[]): void;
+    /** Explicitly mark unread again (a "mark as unread" affordance). */
+    markUnread(threadId: string): void;
+    /**
+     * How many messages in this thread the viewer has not seen.
+     *
+     * A message YOU wrote is never unread — you were there. A tombstoned message is never
+     * unread either: a badge that says "1 unread" and opens onto "message deleted" is a
+     * badge that has wasted someone's attention, which is the only currency a notification
+     * has.
+     */
+    unreadCount(threadId: string, messages: readonly CommentMessage[]): number;
+    isRead(threadId: string, messages: readonly CommentMessage[]): boolean;
+    toJSON(): SerializedReadState;
+    static fromJSON(data: SerializedReadState): ReadState;
+}

package/src/libs/engine/src/comments/read-state.js

@@ -0,0 +1,105 @@
+"use strict";
+// Wave 9 — Card 6: unread markers.
+//
+// ===========================================================================
+// READ STATE IS NOT DOCUMENT STATE. THIS IS THE WHOLE FILE.
+// ===========================================================================
+//
+// Everything else in this card rides the op log, because everything else is a fact about
+// the DOCUMENT. "Ada has read this thread" is not a fact about the document. It is a fact
+// about Ada. Putting it in the shared log would be wrong three separate ways, and it is
+// the single most common mistake in this feature:
+//
+//   1. WRONG SEMANTICS. Ada opens a thread; the op replicates; Ben's unread badge clears.
+//      Ben never read it. The badge — the one thing whose entire job is to tell YOU what
+//      YOU have not seen — now lies to everyone but the last person to scroll.
+//   2. WRONG ECONOMICS. Reading is the most common action in a comment system by two
+//      orders of magnitude. Making every read a broadcast op turns a passive act into
+//      write traffic to every peer, and it puts it in the persisted history forever.
+//   3. WRONG LIFETIME. It would be replayed, undone, and merged. Undoing a node move
+//      should not mark a comment unread again.
+//
+// So read state is LOCAL, per viewer, and the seam to persist it is `toJSON()`/`fromJSON()`
+// — the host puts it in localStorage or on its own user-scoped API. That is a seam with no
+// machinery behind it, which is the correct amount for something the engine cannot know.
+//
+// (A product that genuinely wants shared "seen by" receipts wants a DIFFERENT feature —
+// per-user receipts keyed by user id, which is additive shared data rather than a shared
+// mutable flag. Not built, deliberately, and called out so nobody mistakes its absence
+// for an oversight.)
+//
+// THE MARKER IS A WATERMARK, NOT A COUNT. We store the sort key of the newest message the
+// viewer has seen in each thread. A count would be wrong the instant a message arrived
+// out of order or a tombstone changed the length; a watermark is monotone and compares
+// against the SAME total order the messages are displayed in (`messageKey`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadState = void 0;
+const types_1 = require("./types");
+/**
+ * What THIS viewer has seen. Local. Never synced.
+ */
+class ReadState {
+    constructor(viewer) {
+        this.viewer = viewer;
+        this.watermarks = new Map();
+    }
+    /**
+     * Mark a thread read up to its newest message.
+     *
+     * Takes the messages rather than a key so the caller cannot accidentally set a
+     * watermark ahead of the messages it has actually seen — which would silently swallow
+     * a message that is still in flight.
+     */
+    markRead(threadId, messages) {
+        var _a;
+        let max = (_a = this.watermarks.get(threadId)) !== null && _a !== void 0 ? _a : '';
+        for (const m of messages) {
+            const k = (0, types_1.messageKey)(m);
+            if (k > max)
+                max = k;
+        }
+        if (max)
+            this.watermarks.set(threadId, max);
+    }
+    /** Explicitly mark unread again (a "mark as unread" affordance). */
+    markUnread(threadId) {
+        this.watermarks.delete(threadId);
+    }
+    /**
+     * How many messages in this thread the viewer has not seen.
+     *
+     * A message YOU wrote is never unread — you were there. A tombstoned message is never
+     * unread either: a badge that says "1 unread" and opens onto "message deleted" is a
+     * badge that has wasted someone's attention, which is the only currency a notification
+     * has.
+     */
+    unreadCount(threadId, messages) {
+        var _a;
+        const mark = (_a = this.watermarks.get(threadId)) !== null && _a !== void 0 ? _a : '';
+        let n = 0;
+        for (const m of messages) {
+            if (m.deleted)
+                continue;
+            if (m.author === this.viewer)
+                continue;
+            if ((0, types_1.messageKey)(m) > mark)
+                n++;
+        }
+        return n;
+    }
+    isRead(threadId, messages) {
+        return this.unreadCount(threadId, messages) === 0;
+    }
+    toJSON() {
+        return { viewer: this.viewer, watermarks: Object.fromEntries(this.watermarks) };
+    }
+    static fromJSON(data) {
+        var _a;
+        const rs = new ReadState(data.viewer);
+        for (const [k, v] of Object.entries((_a = data.watermarks) !== null && _a !== void 0 ? _a : {}))
+            rs.watermarks.set(k, v);
+        return rs;
+    }
+}
+exports.ReadState = ReadState;
+//# sourceMappingURL=read-state.js.map

package/src/libs/engine/src/comments/types.d.ts

@@ -0,0 +1,154 @@
+/** A point in WORLD space. Never screen space — see CommentAnchor. */
+export interface WorldPoint {
+    x: number;
+    y: number;
+}
+/**
+ * WHAT A COMMENT IS ABOUT.
+ *
+ * ANCHOR BY IDENTITY, NEVER BY COORDINATES — for anything that has an identity. A
+ * comment pinned to (420, 180) is a comment about whatever happens to be at (420, 180)
+ * *right now*, which after one auto-layout is a different node and a different meaning.
+ * The comment would still be there, still timestamped, still confidently wrong. So a
+ * node/link anchor stores the ENTITY ID and derives its position from the live entity
+ * every frame; move the node across the canvas and the pin comes with it, and not one
+ * op is emitted to make that happen (position is derived, and derived state is never
+ * synced — the same rule capture.ts applies to link routes).
+ *
+ * A FREE-REGION anchor genuinely is coordinates, and they are WORLD coordinates. Screen
+ * coordinates would make the pin's meaning depend on the reader's scroll position and
+ * zoom — a note about the top-right corner of a subsystem would drift onto empty canvas
+ * the moment anyone panned. World coordinates are invariant under pan and zoom by
+ * construction, and the renderer draws them inside the viewBox, so the pin sticks to
+ * the diagram rather than to the glass.
+ *
+ * `fallback` and `targetLabel` are the ANCHOR'S OBITUARY: where the target was and what
+ * it was called, captured at the moment the thread was created. They exist for exactly
+ * one purpose — so that a thread whose target has been DELETED can still be shown, in
+ * the right place, saying what it was about. See ResolvedAnchor.
+ */
+export type CommentAnchor = {
+    kind: 'node';
+    /** The node this thread is about. The pin follows it. */
+    id: string;
+    /** Where it was when the thread was created. Used only if the node is gone. */
+    fallback: WorldPoint;
+    /** What it was called when the thread was created. Used only if the node is gone. */
+    targetLabel?: string;
+} | {
+    kind: 'link';
+    id: string;
+    fallback: WorldPoint;
+    targetLabel?: string;
+} | {
+    /** A note about a REGION of the canvas, attached to nothing. World coordinates. */
+    kind: 'region';
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+};
+/** Write-once thread identity. One register, so a thread appears whole or not at all. */
+export interface CommentThreadHead {
+    id: string;
+    /** The PERSON who started the thread (a user id, not a session/actor id). */
+    author: string;
+    /**
+     * Wall-clock milliseconds, captured at authoring time and carried IN the op.
+     *
+     * The substrate bans wall time from deciding CAUSALITY, and rightly: a clock that
+     * runs backwards would corrupt merge. It does not ban wall time from being DATA.
+     * `Date.now()` read inside a reducer destroys replay determinism; `Date.now()`
+     * captured into an op's payload at the moment a human pressed Enter is just a
+     * number, identical on every peer forever. This is the latter.
+     */
+    createdAt: number;
+}
+/** Resolve/reopen. ONE register, so the flag and its attribution can never split. */
+export interface CommentThreadStatus {
+    resolved: boolean;
+    by: string;
+    at: number;
+}
+/**
+ * One message. ONE register — the rule that makes concurrent replies survive.
+ *
+ * An edit rewrites the whole register (an edit IS a whole-body replacement, so nothing
+ * is gained by splitting it). A delete rewrites it as a TOMBSTONE — `deleted: true`,
+ * body cleared, author and createdAt kept — rather than removing the key, because
+ * removing it would let a concurrent edit resurrect the message with no body, and
+ * because the ordering of the surviving messages must not shift under a peer that has
+ * not yet seen the delete.
+ */
+export interface CommentMessage {
+    id: string;
+    author: string;
+    body: string;
+    createdAt: number;
+    /** User ids extracted from the body at authoring time. Convergent, queryable. */
+    mentions?: string[];
+    editedAt?: number;
+    deleted?: boolean;
+}
+/** The raw register tree as it sits on the model and in the serialized document. */
+export interface StoredThread {
+    head?: CommentThreadHead;
+    anchor?: CommentAnchor;
+    status?: CommentThreadStatus;
+    messages?: Record<string, CommentMessage>;
+}
+export type CommentRegisterTree = Record<string, StoredThread>;
+/**
+ * WHERE A THREAD'S PIN GOES, AND WHETHER ITS SUBJECT STILL EXISTS.
+ *
+ * `attached` is DERIVED — computed from the live diagram on every read, never stored
+ * and never synced. That is the single most important decision in this file, and it is
+ * argued at length in comment-store.ts (`resolveAnchor`).
+ */
+export interface ResolvedAnchor {
+    /** World coordinates for the pin. */
+    point: WorldPoint;
+    /** False ⇒ ORPHANED: the node/link this thread is about is not in the diagram. */
+    attached: boolean;
+    /** The live label if attached; the snapshot taken at anchor time if not. */
+    targetLabel: string;
+    targetKind: 'node' | 'link' | 'region';
+    targetId?: string;
+}
+/** A thread, assembled for reading: sorted messages, derived anchor, viewer's unread count. */
+export interface CommentThreadView {
+    id: string;
+    author: string;
+    createdAt: number;
+    anchor: CommentAnchor;
+    resolved: boolean;
+    resolvedBy?: string;
+    resolvedAt?: number;
+    /** Total order, identical on every peer. Tombstones included (flagged `deleted`). */
+    messages: CommentMessage[];
+    /** Messages this viewer has not seen, authored by someone else. LOCAL, never synced. */
+    unread: number;
+    /** Derived from the live diagram — see ResolvedAnchor. */
+    resolvedAnchor: ResolvedAnchor;
+}
+/**
+ * THE TOTAL ORDER ON MESSAGES.
+ *
+ * Every peer must list a thread's messages in the SAME order or two people reading the
+ * same conversation read different conversations. `(createdAt, author, id)` is total
+ * (ids are unique) and it is computed from data that travels IN the ops, so it is
+ * identical on every peer and stable across replay.
+ *
+ * It is wall time, and that is a deliberate, bounded concession. Wall time may not
+ * decide MERGE — a skewed clock deciding which edit wins is silent data loss, which is
+ * why the substrate uses Lamport clocks for that and why this function is not used for
+ * anything but display order. Wall time deciding the ORDER OF A CHAT LIST is what every
+ * messaging product on earth does, and its worst case is cosmetic: two messages sent
+ * within the clock skew of each other may read in the wrong order. Nobody loses a
+ * comment. (The alternative — a per-message Lamport stamp — is unavailable without
+ * reaching into OpCapture's clock, and buying strict causal order for a chat list at
+ * the price of a second way to mint stamps is a bad trade.)
+ */
+export declare function messageOrder(a: CommentMessage, b: CommentMessage): number;
+/** The sort key of a message, as an opaque comparable string. Used by read-state. */
+export declare function messageKey(m: CommentMessage): string;

package/src/libs/engine/src/comments/types.js

@@ -0,0 +1,107 @@
+"use strict";
+// Wave 9 (Collaboration) — Card 6: comments, annotations & @mentions.
+//
+// ===========================================================================
+// WHERE COMMENTS LIVE, AND WHY
+// ===========================================================================
+//
+// Comments RIDE THE OP LOG. They are not a side store. `diagram.comments` is a
+// register namespace on the model, written through the same `set(diagram, …)` ops
+// as everything else, so a comment gets convergence, transport, persistence and
+// causal ordering for free — the same four things every other card had to build.
+//
+//   • CONVERGENCE. Two people commenting on the same node, offline, must both keep
+//     their comment. Riding the log means the LWW register table (Card 0) already
+//     decides this — provided the REGISTERS ARE CUT CORRECTLY, which is the whole
+//     of the design below.
+//   • TRANSPORT. The sync card (Card 5) ships ops. Comments ship with them. No second
+//     channel, no second auth handshake, no second reconnect/backfill path.
+//   • PERSISTENCE. serialize() → save → fromJSON, and replay(log) reconstructs the
+//     comments exactly as it reconstructs the nodes.
+//   • CAUSALITY. A comment saying "delete this box" and the deletion of the box are
+//     ordered against each other by the same Lamport clock. Two clocks would not be.
+//
+// THE ARGUMENT FOR A SEPARATE STORE, honestly: comments are unbounded text, they are
+// a distinct privacy/ACL surface (a reviewer may comment but not edit), and you may
+// want to load them lazily. That is a real argument, and it is answered WITHOUT a
+// second store: the register namespace `comments.*` IS the seam. A host that wants
+// separate storage or separate ACLs filters ops by `op.path.startsWith('comments.')`
+// at the transport — a three-line predicate — and gets both. Splitting the store to
+// buy that would cost a second clock, and a second clock is not free (see below).
+//
+// A SECOND CLOCK IS A BUG, not a design choice. `opId()` is `${clock}@${actor}`. Give
+// comments their own LamportClock under the same actor and the very first comment
+// mints op id `1@alice` — which the OpLog has already seen (alice's first node edit)
+// and therefore SILENTLY DROPS. The comment is gone. No error. That single fact is
+// what makes "reuse the diagram's op stream" the only cheap answer.
+//
+// ===========================================================================
+// HOW THE REGISTERS ARE CUT — the part that decides whether comments survive
+// ===========================================================================
+//
+// A register is a property path, and LWW resolves two writes to the SAME path. So the
+// cut of the paths IS the concurrency semantics. Two rules, both load-bearing:
+//
+//   1. ONE MESSAGE = ONE REGISTER (`comments.<tid>.messages.<mid>`).
+//      This is the rule that makes concurrent replies safe. Two people replying to the
+//      same thread while offline write to DIFFERENT registers (different message ids),
+//      so LWW never has to choose and BOTH replies survive. Store the messages as a
+//      single `messages: [...]` array register instead — the obvious shape — and the
+//      two replies collide on one register, LWW picks one, and somebody's comment is
+//      deleted by a stranger. Silently. (There is a test that builds exactly that
+//      wrong design and watches it lose a message, so the claim is demonstrated and
+//      not merely asserted.)
+//
+//   2. THE WRITTEN PATHS ARE PREFIX-FREE. No path we ever write is a prefix of another
+//      path we ever write. This is not tidiness, it is correctness under out-of-order
+//      delivery: `set(comments.t1)` and `set(comments.t1.status)` are DIFFERENT LWW
+//      registers, so the gate cannot order them — whichever is APPLIED last wins, and
+//      arrival order is a property of the network. A late whole-thread write would
+//      silently wipe a resolve. So a thread is written as leaves:
+//
+//          comments.<tid>.head              { id, author, createdAt }   — write-once
+//          comments.<tid>.anchor            CommentAnchor               — re-anchorable
+//          comments.<tid>.status            { resolved, by, at }        — resolve/reopen
+//          comments.<tid>.messages.<mid>    CommentMessage              — one per message
+//
+//      `comments.<tid>` and `comments.<tid>.messages` are NEVER written. The fuzz test
+//      asserts prefix-freedom over every op the store has ever emitted, so this cannot
+//      rot.
+//
+// A consequence, faced rather than hidden: a thread arrives as SEVERAL ops, and an
+// unreliable transport can deliver a message before the head that owns it. The read
+// model therefore treats an incomplete thread as INVISIBLE, not as a crash and not as
+// a half-thread — it appears, whole, when its head lands. See `readThreads`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.messageOrder = messageOrder;
+exports.messageKey = messageKey;
+/**
+ * THE TOTAL ORDER ON MESSAGES.
+ *
+ * Every peer must list a thread's messages in the SAME order or two people reading the
+ * same conversation read different conversations. `(createdAt, author, id)` is total
+ * (ids are unique) and it is computed from data that travels IN the ops, so it is
+ * identical on every peer and stable across replay.
+ *
+ * It is wall time, and that is a deliberate, bounded concession. Wall time may not
+ * decide MERGE — a skewed clock deciding which edit wins is silent data loss, which is
+ * why the substrate uses Lamport clocks for that and why this function is not used for
+ * anything but display order. Wall time deciding the ORDER OF A CHAT LIST is what every
+ * messaging product on earth does, and its worst case is cosmetic: two messages sent
+ * within the clock skew of each other may read in the wrong order. Nobody loses a
+ * comment. (The alternative — a per-message Lamport stamp — is unavailable without
+ * reaching into OpCapture's clock, and buying strict causal order for a chat list at
+ * the price of a second way to mint stamps is a bad trade.)
+ */
+function messageOrder(a, b) {
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt - b.createdAt;
+    if (a.author !== b.author)
+        return a.author < b.author ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** The sort key of a message, as an opaque comparable string. Used by read-state. */
+function messageKey(m) {
+    return `${String(m.createdAt).padStart(16, '0')}|${m.author}|${m.id}`;
+}
+//# sourceMappingURL=types.js.map