@unhingged/vizu-core 0.1.22 → 0.2.0

package/dist/internal.d.cts

@@ -162,6 +162,79 @@ interface VizuComment {
      */
     fingerprintsRefreshedAt?: number | null;
 }
+/**
+ * Storage event emitted by adapters that support push notifications of
+ * remote changes.
+ */
+type StorageEvent = {
+    type: 'added';
+    comment: VizuComment;
+} | {
+    type: 'updated';
+    comment: VizuComment;
+} | {
+    type: 'removed';
+    id: string;
+} | {
+    type: 'cleared';
+};
+/**
+ * Optional authorization context an adapter may surface to the host.
+ * Cloud adapters set this after the user signs in; the Vizu class
+ * forwards it via `vizu.getAuthContext()` for hosts that need to call
+ * the same backend with the same session.
+ */
+interface AuthContext {
+    /** Identity provider's user id (e.g. Clerk user id). */
+    userId: string;
+    /** Short-lived bearer token. Adapter is responsible for refresh. */
+    token: string;
+    /** ISO timestamp the token expires; informational. */
+    expiresAt?: string;
+}
+/**
+ * Storage contract implemented by {@link CloudStorageAdapter} — the only
+ * adapter Vizu constructs. The type stays exported because it is
+ * load-bearing for CloudStorageAdapter's public typing; the interface is
+ * per-comment so each mutation is one network call and the adapter can do
+ * optimistic-concurrency without re-shipping the whole list.
+ *
+ * The `namespace` parameter is the workspace slug (Vizu passes
+ * `options.workspace` through).
+ *
+ * Reply ops (`addReply` / `removeReply`) are optional: adapters that don't
+ * implement them fall back to `updateComment` with a manually-patched
+ * `replies` array. Wrapping logic lives in the Vizu class, not here.
+ */
+interface StorageAdapter {
+    /** Load all comments for this namespace. Called once at boot, plus on `setComments`. */
+    load(namespace: string): Promise<VizuComment[]>;
+    /** Persist a new comment. */
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    /** Patch an existing comment by id. Adapter returns the updated doc or `null` if not found. */
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    /** Remove a comment by id. */
+    removeComment(namespace: string, id: string): Promise<void>;
+    /** Replace the entire list (used by hosts that hydrate from their own backend). */
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    /** Wipe the namespace. */
+    clear(namespace: string): Promise<void>;
+    /** Append a reply to a comment. Adapter returns the parent or null if not found. */
+    addReply?(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    /** Remove a reply by id from a comment. Adapter returns the parent or null if not found. */
+    removeReply?(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+    /**
+     * Upload a file attachment. Returns the resolved {@link Attachment} with
+     * a public URL the host can persist on a comment. Adapters that don't
+     * implement this surface report `vizu.canUploadAttachments() === false`
+     * and the popover hides the upload UI.
+     */
+    uploadAttachment?(namespace: string, file: File): Promise<Attachment>;
+    /** Optional remote-change subscription. Returns an unsubscribe function. */
+    subscribe?(namespace: string, handler: (event: StorageEvent) => void): () => void;
+    /** Optional auth context (cloud adapters). */
+    getAuthContext?(): AuthContext | null;
+}
 /** Context handed to every action's onClick. Has the data and the side-effect helpers. */
 interface ActionContext {
     comments: VizuComment[];
@@ -243,7 +316,7 @@ interface PopoverCallbacks {
      * Fetch the workspace's mentionable users for the @ picker dropdown.
      * Called every time the user opens the picker — keeps the list fresh
      * if members were added/removed in another tab. Returns [] for hosts
-     * that don't support mentions (local/memory storage adapters).
+     * that don't support mentions.
      */
     onMentionSearch?: () => Promise<MentionableUser[]>;
 }
@@ -450,4 +523,51 @@ declare class Sidebar {
 
 declare function injectStyles(): void;
 
-export { Highlighter, Pill, type PillCallbacks, Popover, type PopoverCallbacks, Sidebar, injectStyles };
+/**
+ * Persist comments to the host page's localStorage. One JSON document per
+ * namespace. Migrations are applied on read.
+ *
+ * v2 per-comment ops are emulated via read-modify-write of the underlying
+ * array — fine for localStorage's <1ms cost. Cloud adapters do real
+ * single-document writes.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    load(namespace: string): Promise<VizuComment[]>;
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+    addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+}
+/**
+ * Stores comments in RAM only — wipes on reload. Useful when the host owns
+ * persistence via events (the integrator listens to `comment:added` and
+ * forwards to its own backend).
+ */
+declare class InMemoryStorageAdapter implements StorageAdapter {
+    private store;
+    load(namespace: string): Promise<VizuComment[]>;
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+    addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+}
+/**
+ * No-op adapter — never persists. The host hydrates via `setComments` and
+ * listens to events to drive its own storage.
+ */
+declare class NullStorageAdapter implements StorageAdapter {
+    load(): Promise<VizuComment[]>;
+    addComment(): Promise<void>;
+    updateComment(): Promise<VizuComment | null>;
+    removeComment(): Promise<void>;
+    setAll(): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { Highlighter, InMemoryStorageAdapter, LocalStorageAdapter, NullStorageAdapter, Pill, type PillCallbacks, Popover, type PopoverCallbacks, Sidebar, type StorageAdapter, injectStyles };

package/dist/internal.d.ts

@@ -162,6 +162,79 @@ interface VizuComment {
      */
     fingerprintsRefreshedAt?: number | null;
 }
+/**
+ * Storage event emitted by adapters that support push notifications of
+ * remote changes.
+ */
+type StorageEvent = {
+    type: 'added';
+    comment: VizuComment;
+} | {
+    type: 'updated';
+    comment: VizuComment;
+} | {
+    type: 'removed';
+    id: string;
+} | {
+    type: 'cleared';
+};
+/**
+ * Optional authorization context an adapter may surface to the host.
+ * Cloud adapters set this after the user signs in; the Vizu class
+ * forwards it via `vizu.getAuthContext()` for hosts that need to call
+ * the same backend with the same session.
+ */
+interface AuthContext {
+    /** Identity provider's user id (e.g. Clerk user id). */
+    userId: string;
+    /** Short-lived bearer token. Adapter is responsible for refresh. */
+    token: string;
+    /** ISO timestamp the token expires; informational. */
+    expiresAt?: string;
+}
+/**
+ * Storage contract implemented by {@link CloudStorageAdapter} — the only
+ * adapter Vizu constructs. The type stays exported because it is
+ * load-bearing for CloudStorageAdapter's public typing; the interface is
+ * per-comment so each mutation is one network call and the adapter can do
+ * optimistic-concurrency without re-shipping the whole list.
+ *
+ * The `namespace` parameter is the workspace slug (Vizu passes
+ * `options.workspace` through).
+ *
+ * Reply ops (`addReply` / `removeReply`) are optional: adapters that don't
+ * implement them fall back to `updateComment` with a manually-patched
+ * `replies` array. Wrapping logic lives in the Vizu class, not here.
+ */
+interface StorageAdapter {
+    /** Load all comments for this namespace. Called once at boot, plus on `setComments`. */
+    load(namespace: string): Promise<VizuComment[]>;
+    /** Persist a new comment. */
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    /** Patch an existing comment by id. Adapter returns the updated doc or `null` if not found. */
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    /** Remove a comment by id. */
+    removeComment(namespace: string, id: string): Promise<void>;
+    /** Replace the entire list (used by hosts that hydrate from their own backend). */
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    /** Wipe the namespace. */
+    clear(namespace: string): Promise<void>;
+    /** Append a reply to a comment. Adapter returns the parent or null if not found. */
+    addReply?(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    /** Remove a reply by id from a comment. Adapter returns the parent or null if not found. */
+    removeReply?(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+    /**
+     * Upload a file attachment. Returns the resolved {@link Attachment} with
+     * a public URL the host can persist on a comment. Adapters that don't
+     * implement this surface report `vizu.canUploadAttachments() === false`
+     * and the popover hides the upload UI.
+     */
+    uploadAttachment?(namespace: string, file: File): Promise<Attachment>;
+    /** Optional remote-change subscription. Returns an unsubscribe function. */
+    subscribe?(namespace: string, handler: (event: StorageEvent) => void): () => void;
+    /** Optional auth context (cloud adapters). */
+    getAuthContext?(): AuthContext | null;
+}
 /** Context handed to every action's onClick. Has the data and the side-effect helpers. */
 interface ActionContext {
     comments: VizuComment[];
@@ -243,7 +316,7 @@ interface PopoverCallbacks {
      * Fetch the workspace's mentionable users for the @ picker dropdown.
      * Called every time the user opens the picker — keeps the list fresh
      * if members were added/removed in another tab. Returns [] for hosts
-     * that don't support mentions (local/memory storage adapters).
+     * that don't support mentions.
      */
     onMentionSearch?: () => Promise<MentionableUser[]>;
 }
@@ -450,4 +523,51 @@ declare class Sidebar {
 
 declare function injectStyles(): void;
 
-export { Highlighter, Pill, type PillCallbacks, Popover, type PopoverCallbacks, Sidebar, injectStyles };
+/**
+ * Persist comments to the host page's localStorage. One JSON document per
+ * namespace. Migrations are applied on read.
+ *
+ * v2 per-comment ops are emulated via read-modify-write of the underlying
+ * array — fine for localStorage's <1ms cost. Cloud adapters do real
+ * single-document writes.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    load(namespace: string): Promise<VizuComment[]>;
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+    addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+}
+/**
+ * Stores comments in RAM only — wipes on reload. Useful when the host owns
+ * persistence via events (the integrator listens to `comment:added` and
+ * forwards to its own backend).
+ */
+declare class InMemoryStorageAdapter implements StorageAdapter {
+    private store;
+    load(namespace: string): Promise<VizuComment[]>;
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+    addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+}
+/**
+ * No-op adapter — never persists. The host hydrates via `setComments` and
+ * listens to events to drive its own storage.
+ */
+declare class NullStorageAdapter implements StorageAdapter {
+    load(): Promise<VizuComment[]>;
+    addComment(): Promise<void>;
+    updateComment(): Promise<VizuComment | null>;
+    removeComment(): Promise<void>;
+    setAll(): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { Highlighter, InMemoryStorageAdapter, LocalStorageAdapter, NullStorageAdapter, Pill, type PillCallbacks, Popover, type PopoverCallbacks, Sidebar, type StorageAdapter, injectStyles };

package/dist/internal.js

@@ -1,3 +1,6 @@
+// src/types.ts
+var SCHEMA_VERSION = 2;
+
 // src/util.ts
 function isInside(target, selector) {
   return !!target.closest(selector);
@@ -74,6 +77,41 @@ function renderAttachmentsHtml(attachments) {
   }).join("");
   return `<div class="vz-attachment-grid">${items}</div>`;
 }
+function migrateComment(raw) {
+  if (!raw || typeof raw !== "object") return raw;
+  const next = { ...raw };
+  if (next.id == null && next._id != null) {
+    next.id = next._id;
+  }
+  if (!Array.isArray(next.fingerprints) || next.fingerprints.length === 0) {
+    if (next.fingerprint) {
+      next.fingerprints = [next.fingerprint];
+    }
+  }
+  delete next.fingerprint;
+  if (next.url && !next.pageUrl) {
+    next.pageUrl = next.url;
+  }
+  if (!("status" in next) || !isValidStatus(next.status)) next.status = "open";
+  if (!Array.isArray(next.replies)) next.replies = [];
+  if (!Array.isArray(next.attachments)) next.attachments = [];
+  if (!Array.isArray(next.mentions)) next.mentions = [];
+  if (!("fingerprintsRefreshedAt" in next)) next.fingerprintsRefreshedAt = null;
+  next.schemaVersion = SCHEMA_VERSION;
+  return next;
+}
+function isValidStatus(s) {
+  return s === "open" || s === "resolved" || s === "wontfix";
+}
+function migrateComments(raws) {
+  if (!Array.isArray(raws)) return [];
+  const out = [];
+  for (const raw of raws) {
+    if (!raw || typeof raw !== "object") continue;
+    out.push(migrateComment(raw));
+  }
+  return out;
+}
 
 // src/pill.ts
 var Pill = class {
@@ -388,8 +426,8 @@ var Popover = class {
       const removeBtn = target.closest('[data-vz="remove-anchor"]');
       if (removeBtn) {
         e.stopPropagation();
-        const key = removeBtn.getAttribute("data-fp-key");
-        if (key) this.removeAnchor(key);
+        const key2 = removeBtn.getAttribute("data-fp-key");
+        if (key2) this.removeAnchor(key2);
         return;
       }
       const refEl = target.closest('[data-vz="ref"]');
@@ -484,8 +522,8 @@ var Popover = class {
   }
   /** Add another anchor to the in-progress comment (Shift+Click flow). */
   addAnchor(fp, target) {
-    const key = fingerprintKey(fp);
-    if (this.anchorFingerprints.some((x) => fingerprintKey(x) === key)) return false;
+    const key2 = fingerprintKey(fp);
+    if (this.anchorFingerprints.some((x) => fingerprintKey(x) === key2)) return false;
     this.anchorFingerprints.push(fp);
     if (target) this.anchorTargets.push(target);
     this.callbacks.onAnchorsChanged([...this.anchorFingerprints]);
@@ -494,9 +532,9 @@ var Popover = class {
     return true;
   }
   /** Remove an anchor by fingerprint key. Never removes the last anchor. */
-  removeAnchor(key) {
+  removeAnchor(key2) {
     if (this.anchorFingerprints.length <= 1) return false;
-    const idx = this.anchorFingerprints.findIndex((x) => fingerprintKey(x) === key);
+    const idx = this.anchorFingerprints.findIndex((x) => fingerprintKey(x) === key2);
     if (idx < 0) return false;
     this.anchorFingerprints.splice(idx, 1);
     this.anchorTargets.splice(idx, 1);
@@ -606,9 +644,9 @@ var Popover = class {
       return;
     }
     const chips = this.anchorFingerprints.map((fp) => {
-      const key = fingerprintKey(fp);
+      const key2 = fingerprintKey(fp);
       const label = fingerprintLabel(fp);
-      return `<span class="vz-anchor-chip" data-fp-key="${escapeHtml(key)}">${escapeHtml(label)}<button class="vz-anchor-chip-remove" data-vz="remove-anchor" data-fp-key="${escapeHtml(key)}" aria-label="Remove anchor">\xD7</button></span>`;
+      return `<span class="vz-anchor-chip" data-fp-key="${escapeHtml(key2)}">${escapeHtml(label)}<button class="vz-anchor-chip-remove" data-vz="remove-anchor" data-fp-key="${escapeHtml(key2)}" aria-label="Remove anchor">\xD7</button></span>`;
     }).join("");
     wrap.innerHTML = `
       <div class="vz-anchor-hint">Anchored to ${this.anchorFingerprints.length} elements:</div>
@@ -1329,10 +1367,10 @@ var Sidebar = class {
       const fps = c.fingerprints || [];
       const primary = fps[0];
       if (!primary) continue;
-      const key = fingerprintKey(primary);
-      const g = groups.get(key);
+      const key2 = fingerprintKey(primary);
+      const g = groups.get(key2);
       if (g) g.comments.push(c);
-      else groups.set(key, { fp: primary, comments: [c] });
+      else groups.set(key2, { fp: primary, comments: [c] });
     }
     const groupHtml = [];
     let gi = 0;
@@ -1393,8 +1431,8 @@ var Sidebar = class {
     }
     const chips = this.el.querySelectorAll('[data-vz="jump-fp"]');
     for (const chip of chips) {
-      const key = chip.getAttribute("data-fp-key");
-      const fp = findFingerprintByKey(visible, key || "");
+      const key2 = chip.getAttribute("data-fp-key");
+      const fp = findFingerprintByKey(visible, key2 || "");
       chip.__fp = fp;
     }
   }
@@ -1482,10 +1520,10 @@ function renderOrphansHtml(orphans) {
     </div>
   `;
 }
-function findFingerprintByKey(comments, key) {
+function findFingerprintByKey(comments, key2) {
   for (const c of comments) {
     for (const fp of c.fingerprints || []) {
-      if (fingerprintKey(fp) === key) return fp;
+      if (fingerprintKey(fp) === key2) return fp;
     }
   }
   return null;
@@ -2517,8 +2555,154 @@ function injectStyles() {
   style.textContent = STYLES;
   (document.head || document.documentElement).appendChild(style);
 }
+
+// src/storage.ts
+var key = (ns) => `vizu:comments:${ns}`;
+var LocalStorageAdapter = class {
+  async load(namespace) {
+    return readArray(namespace);
+  }
+  async addComment(namespace, comment) {
+    const list = readArray(namespace);
+    list.push(comment);
+    writeArray(namespace, list);
+  }
+  async updateComment(namespace, id, patch) {
+    const list = readArray(namespace);
+    const idx = list.findIndex((c) => c.id === id);
+    if (idx === -1) return null;
+    const next = { ...list[idx], ...patch, id: list[idx].id };
+    list[idx] = next;
+    writeArray(namespace, list);
+    return next;
+  }
+  async removeComment(namespace, id) {
+    const list = readArray(namespace);
+    writeArray(namespace, list.filter((c) => c.id !== id));
+  }
+  async setAll(namespace, comments) {
+    writeArray(namespace, comments);
+  }
+  async clear(namespace) {
+    if (typeof localStorage === "undefined") return;
+    localStorage.removeItem(key(namespace));
+  }
+  async addReply(namespace, commentId, reply) {
+    const list = readArray(namespace);
+    const idx = list.findIndex((c) => c.id === commentId);
+    if (idx === -1) return null;
+    const next = { ...list[idx], replies: [...list[idx].replies ?? [], reply] };
+    list[idx] = next;
+    writeArray(namespace, list);
+    return next;
+  }
+  async removeReply(namespace, commentId, replyId) {
+    const list = readArray(namespace);
+    const idx = list.findIndex((c) => c.id === commentId);
+    if (idx === -1) return null;
+    const next = {
+      ...list[idx],
+      replies: (list[idx].replies ?? []).filter((r) => r.id !== replyId)
+    };
+    list[idx] = next;
+    writeArray(namespace, list);
+    return next;
+  }
+};
+function readArray(namespace) {
+  if (typeof localStorage === "undefined") return [];
+  const raw = localStorage.getItem(key(namespace));
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? migrateComments(parsed) : [];
+  } catch {
+    return [];
+  }
+}
+function writeArray(namespace, comments) {
+  if (typeof localStorage === "undefined") return;
+  localStorage.setItem(key(namespace), JSON.stringify(comments));
+}
+var InMemoryStorageAdapter = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async load(namespace) {
+    return [...this.store.get(namespace) || []];
+  }
+  async addComment(namespace, comment) {
+    const list = this.store.get(namespace) ?? [];
+    this.store.set(namespace, [...list, comment]);
+  }
+  async updateComment(namespace, id, patch) {
+    const list = this.store.get(namespace) ?? [];
+    const idx = list.findIndex((c) => c.id === id);
+    if (idx === -1) return null;
+    const next = { ...list[idx], ...patch, id: list[idx].id };
+    const copy = [...list];
+    copy[idx] = next;
+    this.store.set(namespace, copy);
+    return next;
+  }
+  async removeComment(namespace, id) {
+    const list = this.store.get(namespace) ?? [];
+    this.store.set(
+      namespace,
+      list.filter((c) => c.id !== id)
+    );
+  }
+  async setAll(namespace, comments) {
+    this.store.set(namespace, [...comments]);
+  }
+  async clear(namespace) {
+    this.store.delete(namespace);
+  }
+  async addReply(namespace, commentId, reply) {
+    const list = this.store.get(namespace) ?? [];
+    const idx = list.findIndex((c) => c.id === commentId);
+    if (idx === -1) return null;
+    const next = { ...list[idx], replies: [...list[idx].replies ?? [], reply] };
+    const copy = [...list];
+    copy[idx] = next;
+    this.store.set(namespace, copy);
+    return next;
+  }
+  async removeReply(namespace, commentId, replyId) {
+    const list = this.store.get(namespace) ?? [];
+    const idx = list.findIndex((c) => c.id === commentId);
+    if (idx === -1) return null;
+    const next = {
+      ...list[idx],
+      replies: (list[idx].replies ?? []).filter((r) => r.id !== replyId)
+    };
+    const copy = [...list];
+    copy[idx] = next;
+    this.store.set(namespace, copy);
+    return next;
+  }
+};
+var NullStorageAdapter = class {
+  async load() {
+    return [];
+  }
+  async addComment() {
+  }
+  async updateComment() {
+    return null;
+  }
+  async removeComment() {
+  }
+  async setAll() {
+  }
+  async clear() {
+  }
+};
 export {
   Highlighter,
+  InMemoryStorageAdapter,
+  LocalStorageAdapter,
+  NullStorageAdapter,
   Pill,
   Popover,
   Sidebar,