@unhingged/vizu-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zoltán Balogh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @vizu/react
+
+React bindings for [@vizu/core](../vizu). Drop a provider in your tree, use hooks to read comments / set identity / register actions.
+
+```bash
+npm install @vizu/core @vizu/react
+```
+
+## Use it
+
+```tsx
+'use client';
+import { VizuProvider, useVizu, useComments, useVizuUser, useVizuEvent, useVizuAction } from '@vizu/react';
+
+export default function App() {
+  return (
+    <VizuProvider options={{
+      namespace: 'my-site',
+      pageVersion: 'v1',
+      shortcut: 'mod+shift+e',
+      user: { name: 'Anonymous' },
+      startEnabled: true,
+    }}>
+      <YourPage />
+    </VizuProvider>
+  );
+}
+
+function YourPage() {
+  // 1. Read current user (re-renders on setUser)
+  const [user, setUser] = useVizuUser();
+
+  // 2. Hydrate identity from your auth/session
+  useEffect(() => {
+    setUser({ id: session.userId, name: session.name, avatarUrl: session.avatar });
+  }, [session]);
+
+  // 3. Read live comments (re-renders on add/remove/clear/set)
+  const comments = useComments();
+
+  // 4. Listen to events — persist to your backend
+  useVizuEvent('comment:added', ({ comment }) => {
+    fetch('/api/comments', { method: 'POST', body: JSON.stringify(comment) });
+  });
+
+  // 5. Register a pill action
+  useVizuAction({
+    id: 'send-to-api',
+    label: 'Send to API',
+    variant: 'primary',
+    onClick: (ctx) => fetch('/api/iterate', {
+      method: 'POST',
+      body: JSON.stringify({ comments: ctx.comments, pageHtml: ctx.pageHtml }),
+    }),
+    visibleWhen: ({ commentsCount }) => commentsCount > 0,
+  });
+
+  // 6. Imperative access
+  const vizu = useVizu();
+  useEffect(() => {
+    // Pre-load comments from your backend
+    fetch(`/api/comments?ns=my-site`).then(r => r.json()).then(c => vizu.setComments(c, { persist: false }));
+  }, [vizu]);
+
+  return <div>Your page content…</div>;
+}
+```
+
+## What you get
+
+- `<VizuProvider>` — mounts a single Vizu instance for the subtree (lazy, destroyed on unmount)
+- `useVizu()` — the instance itself for imperative calls (`vizu.enable()`, `vizu.clearAll()`, etc.)
+- `useComments()` — subscribes to all comment-list events, returns `VizuComment[]`
+- `useVizuUser()` — `[user, setUser]` tuple, re-renders on `user:changed`
+- `useVizuEvent('event', handler)` — subscribe to any Vizu event for the component lifetime
+- `useVizuAction({...})` — register an action while mounted; auto-removed on unmount
+
+## Storage defaults
+
+Programmatic mode defaults to **in-memory** storage. Provide `options.storage` if you want persistence:
+
+```tsx
+<VizuProvider options={{ storage: 'local' }}>...
+<VizuProvider options={{ storage: myCustomAdapter }}>...
+```
+
+Or skip storage entirely and own it in your effects — listen to `comment:added` and POST to your API.
+
+## Next.js (App Router)
+
+`VizuProvider` is a client component (it uses refs + effects). Put it inside a layout that opts in:
+
+```tsx
+// app/(commentable)/layout.tsx
+'use client';
+import { VizuProvider } from '@vizu/react';
+export default function Layout({ children }) {
+  return <VizuProvider options={{ namespace: 'my-app' }}>{children}</VizuProvider>;
+}
+```
+
+Page-level usage stays as Server Components; only the provider and the components that call its hooks need the `'use client'` directive.

package/dist/index.cjs

@@ -0,0 +1,125 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var src_exports = {};
+__export(src_exports, {
+  VizuProvider: () => VizuProvider,
+  useComments: () => useComments,
+  useVizu: () => useVizu,
+  useVizuAction: () => useVizuAction,
+  useVizuEvent: () => useVizuEvent,
+  useVizuUser: () => useVizuUser
+});
+module.exports = __toCommonJS(src_exports);
+var import_react = require("react");
+var import_vizu_core = require("@unhingged/vizu-core");
+var import_jsx_runtime = require("react/jsx-runtime");
+var VizuContext = (0, import_react.createContext)(null);
+function VizuProvider({ options, children }) {
+  const ref = (0, import_react.useRef)(null);
+  if (ref.current === null) {
+    ref.current = new import_vizu_core.Vizu(options ?? {});
+  }
+  const vizu = ref.current;
+  (0, import_react.useEffect)(() => {
+    return () => {
+      vizu.destroy();
+      ref.current = null;
+    };
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(VizuContext.Provider, { value: vizu, children });
+}
+function useVizu() {
+  const v = (0, import_react.useContext)(VizuContext);
+  if (!v) {
+    throw new Error("useVizu must be called inside a <VizuProvider>.");
+  }
+  return v;
+}
+function useVizuEvent(event, handler) {
+  const vizu = useVizu();
+  const handlerRef = (0, import_react.useRef)(handler);
+  handlerRef.current = handler;
+  (0, import_react.useEffect)(() => {
+    const off = vizu.on(event, (payload) => handlerRef.current(payload));
+    return off;
+  }, [vizu, event]);
+}
+function useComments() {
+  const vizu = useVizu();
+  const subscribe = (0, import_react.useMemo)(
+    () => (cb) => {
+      const offs = [
+        vizu.on("comment:added", cb),
+        vizu.on("comment:removed", cb),
+        vizu.on("comments:cleared", cb),
+        vizu.on("comments:set", cb),
+        vizu.on("comments:loaded", cb)
+      ];
+      return () => offs.forEach((off) => off());
+    },
+    [vizu]
+  );
+  const cacheRef = (0, import_react.useRef)(vizu.getComments());
+  const getSnapshot = () => {
+    const next = vizu.getComments();
+    const last = cacheRef.current;
+    if (last.length === next.length && last.every((c, i) => c === next[i] || c.id === next[i].id && c.text === next[i].text)) {
+      return last;
+    }
+    cacheRef.current = next;
+    return next;
+  };
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+}
+function useVizuUser() {
+  const vizu = useVizu();
+  const subscribe = (0, import_react.useMemo)(
+    () => (cb) => vizu.on("user:changed", cb),
+    [vizu]
+  );
+  const getSnapshot = () => vizu.getUser();
+  const user = (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  return [user, (u) => vizu.setUser(u)];
+}
+function useVizuAction(action) {
+  const vizu = useVizu();
+  const actionRef = (0, import_react.useRef)(action);
+  actionRef.current = action;
+  (0, import_react.useEffect)(() => {
+    vizu.addAction({
+      ...action,
+      onClick: (ctx) => actionRef.current.onClick(ctx),
+      visibleWhen: action.visibleWhen ? ({ commentsCount }) => actionRef.current.visibleWhen?.({ commentsCount }) ?? true : void 0
+    });
+    return () => vizu.removeAction(action.id);
+  }, [vizu, action.id]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VizuProvider,
+  useComments,
+  useVizu,
+  useVizuAction,
+  useVizuEvent,
+  useVizuUser
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type ReactNode,\n} from 'react';\nimport {\n  Vizu,\n  type VizuOptions,\n  type VizuComment,\n  type VizuUser,\n  type VizuAction,\n  type VizuEventName,\n  type VizuEventHandler,\n} from '@unhingged/vizu-core';\n\nexport type {\n  Vizu,\n  VizuOptions,\n  VizuComment,\n  VizuUser,\n  VizuAction,\n  VizuEventName,\n  VizuEventHandler,\n};\n\nconst VizuContext = createContext<Vizu | null>(null);\n\nexport interface VizuProviderProps {\n  options?: VizuOptions;\n  children?: ReactNode;\n}\n\n/**\n * Mounts a single Vizu instance for the subtree. The instance is created lazily\n * once and persists across re-renders. Pass options once at construction;\n * imperative changes go through `useVizu()`.\n */\nexport function VizuProvider({ options, children }: VizuProviderProps) {\n  // We need a stable instance across renders. Use a ref so re-renders don't construct new ones.\n  const ref = useRef<Vizu | null>(null);\n  if (ref.current === null) {\n    ref.current = new Vizu(options ?? {});\n  }\n  const vizu = ref.current;\n\n  useEffect(() => {\n    return () => {\n      vizu.destroy();\n      ref.current = null;\n    };\n    // Intentionally only run on unmount. Recreating Vizu mid-tree would lose listeners + state.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return <VizuContext.Provider value={vizu}>{children}</VizuContext.Provider>;\n}\n\n/** Returns the Vizu instance. Throws if used outside a <VizuProvider>. */\nexport function useVizu(): Vizu {\n  const v = useContext(VizuContext);\n  if (!v) {\n    throw new Error('useVizu must be called inside a <VizuProvider>.');\n  }\n  return v;\n}\n\n/** Subscribe to a Vizu event for the component's lifetime. Fire-and-forget. */\nexport function useVizuEvent<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void {\n  const vizu = useVizu();\n  // Stable handler ref — re-subscribe only when the event name changes.\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => {\n    const off = vizu.on(event, (payload) => handlerRef.current(payload));\n    return off;\n  }, [vizu, event]);\n}\n\n/** Returns the current comments array and re-renders when it changes. */\nexport function useComments(): VizuComment[] {\n  const vizu = useVizu();\n  // Stable subscribe + snapshot for useSyncExternalStore.\n  const subscribe = useMemo(\n    () => (cb: () => void) => {\n      const offs = [\n        vizu.on('comment:added', cb),\n        vizu.on('comment:removed', cb),\n        vizu.on('comments:cleared', cb),\n        vizu.on('comments:set', cb),\n        vizu.on('comments:loaded', cb),\n      ];\n      return () => offs.forEach((off) => off());\n    },\n    [vizu],\n  );\n  // getSnapshot must return a referentially stable result when the data hasn't changed.\n  // We re-derive only when the subscribe fires; meanwhile memoize the last array.\n  const cacheRef = useRef<VizuComment[]>(vizu.getComments());\n  const getSnapshot = () => {\n    const next = vizu.getComments();\n    const last = cacheRef.current;\n    if (last.length === next.length && last.every((c, i) => c === next[i] || (c.id === next[i].id && c.text === next[i].text))) {\n      return last;\n    }\n    cacheRef.current = next;\n    return next;\n  };\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/** Returns the current user and re-renders when it changes. Also exposes a setter. */\nexport function useVizuUser(): [VizuUser | null, (u: VizuUser | null) => void] {\n  const vizu = useVizu();\n  const subscribe = useMemo(\n    () => (cb: () => void) => vizu.on('user:changed', cb),\n    [vizu],\n  );\n  const getSnapshot = () => vizu.getUser();\n  const user = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  return [user, (u) => vizu.setUser(u)];\n}\n\n/**\n * Register an action while the component is mounted. The action is removed\n * automatically on unmount. Re-renders DON'T re-register unless `action.id` changes.\n */\nexport function useVizuAction(action: VizuAction): void {\n  const vizu = useVizu();\n  const actionRef = useRef(action);\n  actionRef.current = action;\n  useEffect(() => {\n    // Wrap so we always call the latest action.onClick / visibleWhen\n    vizu.addAction({\n      ...action,\n      onClick: (ctx) => actionRef.current.onClick(ctx),\n      visibleWhen: action.visibleWhen\n        ? ({ commentsCount }) => actionRef.current.visibleWhen?.({ commentsCount }) ?? true\n        : undefined,\n    });\n    return () => vizu.removeAction(action.id);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [vizu, action.id]);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { VizuOptions, VizuComment, Vizu, VizuAction, VizuEventName, VizuEventHandler, VizuUser } from '@unhingged/vizu-core';
+export { Vizu, VizuAction, VizuComment, VizuEventHandler, VizuEventName, VizuOptions, VizuUser } from '@unhingged/vizu-core';
+
+interface VizuProviderProps {
+    options?: VizuOptions;
+    children?: ReactNode;
+}
+/**
+ * Mounts a single Vizu instance for the subtree. The instance is created lazily
+ * once and persists across re-renders. Pass options once at construction;
+ * imperative changes go through `useVizu()`.
+ */
+declare function VizuProvider({ options, children }: VizuProviderProps): react_jsx_runtime.JSX.Element;
+/** Returns the Vizu instance. Throws if used outside a <VizuProvider>. */
+declare function useVizu(): Vizu;
+/** Subscribe to a Vizu event for the component's lifetime. Fire-and-forget. */
+declare function useVizuEvent<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
+/** Returns the current comments array and re-renders when it changes. */
+declare function useComments(): VizuComment[];
+/** Returns the current user and re-renders when it changes. Also exposes a setter. */
+declare function useVizuUser(): [VizuUser | null, (u: VizuUser | null) => void];
+/**
+ * Register an action while the component is mounted. The action is removed
+ * automatically on unmount. Re-renders DON'T re-register unless `action.id` changes.
+ */
+declare function useVizuAction(action: VizuAction): void;
+
+export { VizuProvider, type VizuProviderProps, useComments, useVizu, useVizuAction, useVizuEvent, useVizuUser };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { VizuOptions, VizuComment, Vizu, VizuAction, VizuEventName, VizuEventHandler, VizuUser } from '@unhingged/vizu-core';
+export { Vizu, VizuAction, VizuComment, VizuEventHandler, VizuEventName, VizuOptions, VizuUser } from '@unhingged/vizu-core';
+
+interface VizuProviderProps {
+    options?: VizuOptions;
+    children?: ReactNode;
+}
+/**
+ * Mounts a single Vizu instance for the subtree. The instance is created lazily
+ * once and persists across re-renders. Pass options once at construction;
+ * imperative changes go through `useVizu()`.
+ */
+declare function VizuProvider({ options, children }: VizuProviderProps): react_jsx_runtime.JSX.Element;
+/** Returns the Vizu instance. Throws if used outside a <VizuProvider>. */
+declare function useVizu(): Vizu;
+/** Subscribe to a Vizu event for the component's lifetime. Fire-and-forget. */
+declare function useVizuEvent<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
+/** Returns the current comments array and re-renders when it changes. */
+declare function useComments(): VizuComment[];
+/** Returns the current user and re-renders when it changes. Also exposes a setter. */
+declare function useVizuUser(): [VizuUser | null, (u: VizuUser | null) => void];
+/**
+ * Register an action while the component is mounted. The action is removed
+ * automatically on unmount. Re-renders DON'T re-register unless `action.id` changes.
+ */
+declare function useVizuAction(action: VizuAction): void;
+
+export { VizuProvider, type VizuProviderProps, useComments, useVizu, useVizuAction, useVizuEvent, useVizuUser };

package/dist/index.js

@@ -0,0 +1,105 @@
+"use client";
+
+// src/index.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
+import {
+  Vizu
+} from "@unhingged/vizu-core";
+import { jsx } from "react/jsx-runtime";
+var VizuContext = createContext(null);
+function VizuProvider({ options, children }) {
+  const ref = useRef(null);
+  if (ref.current === null) {
+    ref.current = new Vizu(options ?? {});
+  }
+  const vizu = ref.current;
+  useEffect(() => {
+    return () => {
+      vizu.destroy();
+      ref.current = null;
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(VizuContext.Provider, { value: vizu, children });
+}
+function useVizu() {
+  const v = useContext(VizuContext);
+  if (!v) {
+    throw new Error("useVizu must be called inside a <VizuProvider>.");
+  }
+  return v;
+}
+function useVizuEvent(event, handler) {
+  const vizu = useVizu();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  useEffect(() => {
+    const off = vizu.on(event, (payload) => handlerRef.current(payload));
+    return off;
+  }, [vizu, event]);
+}
+function useComments() {
+  const vizu = useVizu();
+  const subscribe = useMemo(
+    () => (cb) => {
+      const offs = [
+        vizu.on("comment:added", cb),
+        vizu.on("comment:removed", cb),
+        vizu.on("comments:cleared", cb),
+        vizu.on("comments:set", cb),
+        vizu.on("comments:loaded", cb)
+      ];
+      return () => offs.forEach((off) => off());
+    },
+    [vizu]
+  );
+  const cacheRef = useRef(vizu.getComments());
+  const getSnapshot = () => {
+    const next = vizu.getComments();
+    const last = cacheRef.current;
+    if (last.length === next.length && last.every((c, i) => c === next[i] || c.id === next[i].id && c.text === next[i].text)) {
+      return last;
+    }
+    cacheRef.current = next;
+    return next;
+  };
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function useVizuUser() {
+  const vizu = useVizu();
+  const subscribe = useMemo(
+    () => (cb) => vizu.on("user:changed", cb),
+    [vizu]
+  );
+  const getSnapshot = () => vizu.getUser();
+  const user = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return [user, (u) => vizu.setUser(u)];
+}
+function useVizuAction(action) {
+  const vizu = useVizu();
+  const actionRef = useRef(action);
+  actionRef.current = action;
+  useEffect(() => {
+    vizu.addAction({
+      ...action,
+      onClick: (ctx) => actionRef.current.onClick(ctx),
+      visibleWhen: action.visibleWhen ? ({ commentsCount }) => actionRef.current.visibleWhen?.({ commentsCount }) ?? true : void 0
+    });
+    return () => vizu.removeAction(action.id);
+  }, [vizu, action.id]);
+}
+export {
+  VizuProvider,
+  useComments,
+  useVizu,
+  useVizuAction,
+  useVizuEvent,
+  useVizuUser
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type ReactNode,\n} from 'react';\nimport {\n  Vizu,\n  type VizuOptions,\n  type VizuComment,\n  type VizuUser,\n  type VizuAction,\n  type VizuEventName,\n  type VizuEventHandler,\n} from '@unhingged/vizu-core';\n\nexport type {\n  Vizu,\n  VizuOptions,\n  VizuComment,\n  VizuUser,\n  VizuAction,\n  VizuEventName,\n  VizuEventHandler,\n};\n\nconst VizuContext = createContext<Vizu | null>(null);\n\nexport interface VizuProviderProps {\n  options?: VizuOptions;\n  children?: ReactNode;\n}\n\n/**\n * Mounts a single Vizu instance for the subtree. The instance is created lazily\n * once and persists across re-renders. Pass options once at construction;\n * imperative changes go through `useVizu()`.\n */\nexport function VizuProvider({ options, children }: VizuProviderProps) {\n  // We need a stable instance across renders. Use a ref so re-renders don't construct new ones.\n  const ref = useRef<Vizu | null>(null);\n  if (ref.current === null) {\n    ref.current = new Vizu(options ?? {});\n  }\n  const vizu = ref.current;\n\n  useEffect(() => {\n    return () => {\n      vizu.destroy();\n      ref.current = null;\n    };\n    // Intentionally only run on unmount. Recreating Vizu mid-tree would lose listeners + state.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return <VizuContext.Provider value={vizu}>{children}</VizuContext.Provider>;\n}\n\n/** Returns the Vizu instance. Throws if used outside a <VizuProvider>. */\nexport function useVizu(): Vizu {\n  const v = useContext(VizuContext);\n  if (!v) {\n    throw new Error('useVizu must be called inside a <VizuProvider>.');\n  }\n  return v;\n}\n\n/** Subscribe to a Vizu event for the component's lifetime. Fire-and-forget. */\nexport function useVizuEvent<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void {\n  const vizu = useVizu();\n  // Stable handler ref — re-subscribe only when the event name changes.\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => {\n    const off = vizu.on(event, (payload) => handlerRef.current(payload));\n    return off;\n  }, [vizu, event]);\n}\n\n/** Returns the current comments array and re-renders when it changes. */\nexport function useComments(): VizuComment[] {\n  const vizu = useVizu();\n  // Stable subscribe + snapshot for useSyncExternalStore.\n  const subscribe = useMemo(\n    () => (cb: () => void) => {\n      const offs = [\n        vizu.on('comment:added', cb),\n        vizu.on('comment:removed', cb),\n        vizu.on('comments:cleared', cb),\n        vizu.on('comments:set', cb),\n        vizu.on('comments:loaded', cb),\n      ];\n      return () => offs.forEach((off) => off());\n    },\n    [vizu],\n  );\n  // getSnapshot must return a referentially stable result when the data hasn't changed.\n  // We re-derive only when the subscribe fires; meanwhile memoize the last array.\n  const cacheRef = useRef<VizuComment[]>(vizu.getComments());\n  const getSnapshot = () => {\n    const next = vizu.getComments();\n    const last = cacheRef.current;\n    if (last.length === next.length && last.every((c, i) => c === next[i] || (c.id === next[i].id && c.text === next[i].text))) {\n      return last;\n    }\n    cacheRef.current = next;\n    return next;\n  };\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/** Returns the current user and re-renders when it changes. Also exposes a setter. */\nexport function useVizuUser(): [VizuUser | null, (u: VizuUser | null) => void] {\n  const vizu = useVizu();\n  const subscribe = useMemo(\n    () => (cb: () => void) => vizu.on('user:changed', cb),\n    [vizu],\n  );\n  const getSnapshot = () => vizu.getUser();\n  const user = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  return [user, (u) => vizu.setUser(u)];\n}\n\n/**\n * Register an action while the component is mounted. The action is removed\n * automatically on unmount. Re-renders DON'T re-register unless `action.id` changes.\n */\nexport function useVizuAction(action: VizuAction): void {\n  const vizu = useVizu();\n  const actionRef = useRef(action);\n  actionRef.current = action;\n  useEffect(() => {\n    // Wrap so we always call the latest action.onClick / visibleWhen\n    vizu.addAction({\n      ...action,\n      onClick: (ctx) => actionRef.current.onClick(ctx),\n      visibleWhen: action.visibleWhen\n        ? ({ commentsCount }) => actionRef.current.visibleWhen?.({ commentsCount }) ?? true\n        : undefined,\n    });\n    return () => vizu.removeAction(action.id);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [vizu, action.id]);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@unhingged/vizu-react",
+  "version": "0.1.0",
+  "description": "React bindings for @unhingged/vizu-core — VizuProvider, useVizu, useComments, useVizuUser, useVizuEvent.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@unhingged/vizu-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "keywords": [
+    "vizu",
+    "react",
+    "annotation",
+    "comments",
+    "feedback"
+  ],
+  "license": "MIT",
+  "author": "Zoltán Balogh",
+  "homepage": "https://github.com/unhingedshoobydoo/vizu/tree/main/packages/vizu-react",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unhingedshoobydoo/vizu.git",
+    "directory": "packages/vizu-react"
+  },
+  "bugs": {
+    "url": "https://github.com/unhingedshoobydoo/vizu/issues"
+  }
+}