@unhingged/vizu-react 0.1.20 → 0.1.22

package/README.md

@@ -66,9 +66,43 @@ function YourPage() {
 }
 ```
 
+## Floating launcher pill
+
+Not everyone knows the keyboard shortcut. Drop `<VizuLauncher />` anywhere inside the provider and visitors get a floating pill that turns Vizu on with one click (and kicks the sign-in popup in cloud mode, same as the shortcut):
+
+```tsx
+import { VizuProvider, VizuLauncher } from '@vizu/react';
+
+<VizuProvider options={{ namespace: 'my-site' }}>
+  <YourPage />
+  <VizuLauncher />
+</VizuProvider>
+```
+
+By default it sits bottom-right (Vizu's own toolbar takes bottom-center), shows the saved-comment count as a badge, and hides itself while Vizu is active — reappearing when Vizu is disabled. Everything is tweakable:
+
+```tsx
+<VizuLauncher
+  label="Leave feedback"          // pill text, default "Feedback"
+  position="bottom-left"          // bottom-right | bottom-left | top-right | top-left
+  offset={32}                     // px from the viewport edges, default 20
+  showCount={false}               // hide the comment-count badge
+  hideWhenActive={false}          // keep it visible as an on/off toggle
+  accent="#7C5CFF"                // dot + active border color
+  onToggle={(enabled) => track('vizu_toggled', { enabled })}
+/>
+```
+
+Or replace the content entirely while keeping the pill shell and behavior:
+
+```tsx
+<VizuLauncher>💬 Comments</VizuLauncher>
+```
+
 ## What you get
 
 - `<VizuProvider>` — mounts a single Vizu instance for the subtree (lazy, destroyed on unmount)
+- `<VizuLauncher>` — floating pill that enables Vizu with a click (see above)
 - `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`
@@ -88,7 +122,7 @@ Or skip storage entirely and own it in your effects — listen to `comment:added
 
 ## Next.js (App Router)
 
-`VizuProvider` is a client component (it uses refs + effects). Put it inside a layout that opts in:
+`VizuProvider` is a client component (it uses refs + effects) and is StrictMode-safe — dev-mode's mount→cleanup→remount cycle recreates the instance instead of leaving a destroyed one in context. Put it inside a layout that opts in:
 
 ```tsx
 // app/(commentable)/layout.tsx

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.tsx
 var src_exports = {};
 __export(src_exports, {
+  VizuLauncher: () => VizuLauncher,
   VizuProvider: () => VizuProvider,
   useComments: () => useComments,
   useVizu: () => useVizu,
@@ -29,26 +30,166 @@ __export(src_exports, {
   useVizuUser: () => useVizuUser
 });
 module.exports = __toCommonJS(src_exports);
-var import_react = require("react");
+var import_react2 = require("react");
 var import_vizu_core = require("@unhingged/vizu-core");
+
+// src/launcher.tsx
+var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-var VizuContext = (0, import_react.createContext)(null);
+function useVizuEnabled(vizu) {
+  const subscribe = (0, import_react.useMemo)(
+    () => (cb) => {
+      const offs = [vizu.on("enabled", cb), vizu.on("disabled", cb)];
+      return () => offs.forEach((off) => off());
+    },
+    [vizu]
+  );
+  const getSnapshot = () => vizu.isEnabled();
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, () => false);
+}
+function useCommentCount(vizu) {
+  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 getSnapshot = () => vizu.getComments().length;
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, () => 0);
+}
+var ACCENT_DEFAULT = "#FF6647";
+function VizuLauncher({
+  label = "Feedback",
+  position = "bottom-right",
+  offset = 20,
+  showCount = true,
+  hideWhenActive = true,
+  accent = ACCENT_DEFAULT,
+  zIndex = 2147483646,
+  className,
+  style,
+  children,
+  onToggle
+}) {
+  const vizu = useVizu();
+  const enabled = useVizuEnabled(vizu);
+  const count = useCommentCount(vizu);
+  const [hovered, setHovered] = (0, import_react.useState)(false);
+  const buttonRef = (0, import_react.useRef)(null);
+  if (enabled && hideWhenActive) return null;
+  const [vSide, hSide] = position.split("-");
+  const base = {
+    position: "fixed",
+    [vSide]: offset,
+    [hSide]: offset,
+    zIndex,
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 8,
+    padding: "9px 16px",
+    borderRadius: 999,
+    border: `1px solid ${enabled ? accent : hovered ? "#3A3A3A" : "#2A2A2A"}`,
+    background: hovered ? "#1A1A1A" : "#0A0A0A",
+    color: "#fafafa",
+    font: '500 13px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif',
+    cursor: "pointer",
+    boxShadow: "0 8px 24px rgba(0,0,0,.4), inset 0 0 0 1px rgba(255,255,255,.04)",
+    userSelect: "none",
+    transition: "background 120ms, border-color 120ms, transform 120ms",
+    transform: hovered ? "translateY(-1px)" : "none"
+  };
+  const handleClick = () => {
+    vizu.toggle();
+    if (vizu.isEnabled()) vizu.requestAuth();
+    onToggle?.(vizu.isEnabled());
+    buttonRef.current?.blur();
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "button",
+    {
+      ref: buttonRef,
+      type: "button",
+      "data-vizu-ignore": "",
+      className,
+      style: { ...base, ...style },
+      onClick: handleClick,
+      onMouseEnter: () => setHovered(true),
+      onMouseLeave: () => setHovered(false),
+      "aria-pressed": enabled,
+      title: enabled ? "Turn off commenting" : "Comment on this page",
+      children: children ?? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "span",
+          {
+            "aria-hidden": "true",
+            style: {
+              width: 7,
+              height: 7,
+              borderRadius: "50%",
+              background: accent,
+              boxShadow: `0 0 8px ${accent}`,
+              flexShrink: 0
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: label }),
+        showCount && count > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "span",
+          {
+            style: {
+              minWidth: 18,
+              height: 18,
+              padding: "0 5px",
+              borderRadius: 9,
+              background: "#2A2A2A",
+              color: "#fafafa",
+              fontSize: 11,
+              fontWeight: 600,
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center"
+            },
+            children: count
+          }
+        )
+      ] })
+    }
+  );
+}
+
+// src/index.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var VizuContext = (0, import_react2.createContext)(null);
 function VizuProvider({ options, children }) {
-  const ref = (0, import_react.useRef)(null);
+  const optionsRef = (0, import_react2.useRef)(options);
+  optionsRef.current = options;
+  const ref = (0, import_react2.useRef)(null);
   if (ref.current === null) {
     ref.current = new import_vizu_core.Vizu(options ?? {});
   }
-  const vizu = ref.current;
-  (0, import_react.useEffect)(() => {
+  const [vizu, setVizu] = (0, import_react2.useState)(ref.current);
+  (0, import_react2.useEffect)(() => {
+    if (ref.current === null) {
+      ref.current = new import_vizu_core.Vizu(optionsRef.current ?? {});
+      setVizu(ref.current);
+    }
+    const instance = ref.current;
     return () => {
-      vizu.destroy();
+      instance.destroy();
       ref.current = null;
     };
   }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(VizuContext.Provider, { value: vizu, children });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(VizuContext.Provider, { value: vizu, children });
 }
 function useVizu() {
-  const v = (0, import_react.useContext)(VizuContext);
+  const v = (0, import_react2.useContext)(VizuContext);
   if (!v) {
     throw new Error("useVizu must be called inside a <VizuProvider>.");
   }
@@ -56,16 +197,16 @@ function useVizu() {
 }
 function useVizuEvent(event, handler) {
   const vizu = useVizu();
-  const handlerRef = (0, import_react.useRef)(handler);
+  const handlerRef = (0, import_react2.useRef)(handler);
   handlerRef.current = handler;
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.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)(
+  const subscribe = (0, import_react2.useMemo)(
     () => (cb) => {
       const offs = [
         vizu.on("comment:added", cb),
@@ -78,7 +219,7 @@ function useComments() {
     },
     [vizu]
   );
-  const cacheRef = (0, import_react.useRef)(vizu.getComments());
+  const cacheRef = (0, import_react2.useRef)(vizu.getComments());
   const getSnapshot = () => {
     const next = vizu.getComments();
     const last = cacheRef.current;
@@ -88,23 +229,23 @@ function useComments() {
     cacheRef.current = next;
     return next;
   };
-  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  return (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 }
 function useVizuUser() {
   const vizu = useVizu();
-  const subscribe = (0, import_react.useMemo)(
+  const subscribe = (0, import_react2.useMemo)(
     () => (cb) => vizu.on("user:changed", cb),
     [vizu]
   );
   const getSnapshot = () => vizu.getUser();
-  const user = (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const user = (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return [user, (u) => vizu.setUser(u)];
 }
 function useVizuAction(action) {
   const vizu = useVizu();
-  const actionRef = (0, import_react.useRef)(action);
+  const actionRef = (0, import_react2.useRef)(action);
   actionRef.current = action;
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     vizu.addAction({
       ...action,
       onClick: (ctx) => actionRef.current.onClick(ctx),
@@ -115,6 +256,7 @@ function useVizuAction(action) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  VizuLauncher,
   VizuProvider,
   useComments,
   useVizu,

package/dist/index.cjs.map

@@ -1 +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":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,mBAQO;AACP,uBAQO;AAyCE;AA7BT,IAAM,kBAAc,4BAA2B,IAAI;AAY5C,SAAS,aAAa,EAAE,SAAS,SAAS,GAAsB;AAErE,QAAM,UAAM,qBAAoB,IAAI;AACpC,MAAI,IAAI,YAAY,MAAM;AACxB,QAAI,UAAU,IAAI,sBAAK,WAAW,CAAC,CAAC;AAAA,EACtC;AACA,QAAM,OAAO,IAAI;AAEjB,8BAAU,MAAM;AACd,WAAO,MAAM;AACX,WAAK,QAAQ;AACb,UAAI,UAAU;AAAA,IAChB;AAAA,EAGF,GAAG,CAAC,CAAC;AAEL,SAAO,4CAAC,YAAY,UAAZ,EAAqB,OAAO,MAAO,UAAS;AACtD;AAGO,SAAS,UAAgB;AAC9B,QAAM,QAAI,yBAAW,WAAW;AAChC,MAAI,CAAC,GAAG;AACN,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AACA,SAAO;AACT;AAGO,SAAS,aAAsC,OAAU,SAAoC;AAClG,QAAM,OAAO,QAAQ;AAErB,QAAM,iBAAa,qBAAO,OAAO;AACjC,aAAW,UAAU;AACrB,8BAAU,MAAM;AACd,UAAM,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,WAAW,QAAQ,OAAO,CAAC;AACnE,WAAO;AAAA,EACT,GAAG,CAAC,MAAM,KAAK,CAAC;AAClB;AAGO,SAAS,cAA6B;AAC3C,QAAM,OAAO,QAAQ;AAErB,QAAM,gBAAY;AAAA,IAChB,MAAM,CAAC,OAAmB;AACxB,YAAM,OAAO;AAAA,QACX,KAAK,GAAG,iBAAiB,EAAE;AAAA,QAC3B,KAAK,GAAG,mBAAmB,EAAE;AAAA,QAC7B,KAAK,GAAG,oBAAoB,EAAE;AAAA,QAC9B,KAAK,GAAG,gBAAgB,EAAE;AAAA,QAC1B,KAAK,GAAG,mBAAmB,EAAE;AAAA,MAC/B;AACA,aAAO,MAAM,KAAK,QAAQ,CAAC,QAAQ,IAAI,CAAC;AAAA,IAC1C;AAAA,IACA,CAAC,IAAI;AAAA,EACP;AAGA,QAAM,eAAW,qBAAsB,KAAK,YAAY,CAAC;AACzD,QAAM,cAAc,MAAM;AACxB,UAAM,OAAO,KAAK,YAAY;AAC9B,UAAM,OAAO,SAAS;AACtB,QAAI,KAAK,WAAW,KAAK,UAAU,KAAK,MAAM,CAAC,GAAG,MAAM,MAAM,KAAK,CAAC,KAAM,EAAE,OAAO,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,KAAK,CAAC,EAAE,IAAK,GAAG;AAC1H,aAAO;AAAA,IACT;AACA,aAAS,UAAU;AACnB,WAAO;AAAA,EACT;AACA,aAAO,mCAAqB,WAAW,aAAa,WAAW;AACjE;AAGO,SAAS,cAA+D;AAC7E,QAAM,OAAO,QAAQ;AACrB,QAAM,gBAAY;AAAA,IAChB,MAAM,CAAC,OAAmB,KAAK,GAAG,gBAAgB,EAAE;AAAA,IACpD,CAAC,IAAI;AAAA,EACP;AACA,QAAM,cAAc,MAAM,KAAK,QAAQ;AACvC,QAAM,WAAO,mCAAqB,WAAW,aAAa,WAAW;AACrE,SAAO,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;AACtC;AAMO,SAAS,cAAc,QAA0B;AACtD,QAAM,OAAO,QAAQ;AACrB,QAAM,gBAAY,qBAAO,MAAM;AAC/B,YAAU,UAAU;AACpB,8BAAU,MAAM;AAEd,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,SAAS,CAAC,QAAQ,UAAU,QAAQ,QAAQ,GAAG;AAAA,MAC/C,aAAa,OAAO,cAChB,CAAC,EAAE,cAAc,MAAM,UAAU,QAAQ,cAAc,EAAE,cAAc,CAAC,KAAK,OAC7E;AAAA,IACN,CAAC;AACD,WAAO,MAAM,KAAK,aAAa,OAAO,EAAE;AAAA,EAE1C,GAAG,CAAC,MAAM,OAAO,EAAE,CAAC;AACtB;","names":[]}
+{"version":3,"sources":["../src/index.tsx","../src/launcher.tsx"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\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\nexport { VizuLauncher } from './launcher';\nexport type { VizuLauncherProps, VizuLauncherPosition } from './launcher';\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  // Latest options, so a StrictMode recreation (below) doesn't construct\n  // from a stale first-render snapshot.\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  // The instance must exist during the first render (children call useVizu\n  // immediately), so construct lazily here rather than in the effect.\n  const ref = useRef<Vizu | null>(null);\n  if (ref.current === null) {\n    ref.current = new Vizu(options ?? {});\n  }\n  // Context value lives in state so a recreated instance propagates to\n  // consumers; re-renders don't construct new ones.\n  const [vizu, setVizu] = useState<Vizu>(ref.current);\n\n  useEffect(() => {\n    // StrictMode's mount→cleanup→remount cycle destroys the render-time\n    // instance in the first cleanup without re-running the render-phase\n    // construction. Recreate here and push it through state so every\n    // consumer re-subscribes to the live instance.\n    if (ref.current === null) {\n      ref.current = new Vizu(optionsRef.current ?? {});\n      setVizu(ref.current);\n    }\n    const instance = ref.current;\n    return () => {\n      instance.destroy();\n      ref.current = null;\n    };\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","'use client';\n\nimport {\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type CSSProperties,\n  type ReactNode,\n} from 'react';\nimport type { Vizu } from '@unhingged/vizu-core';\nimport { useVizu } from './index';\n\nexport type VizuLauncherPosition =\n  | 'bottom-right'\n  | 'bottom-left'\n  | 'top-right'\n  | 'top-left';\n\nexport interface VizuLauncherProps {\n  /** Text inside the pill. Default: \"Feedback\". */\n  label?: string;\n  /** Which corner the pill floats in. Default: 'bottom-right' (Vizu's own toolbar sits bottom-center). */\n  position?: VizuLauncherPosition;\n  /** Distance from the two nearest viewport edges, in px. Default: 20. */\n  offset?: number;\n  /** Show the saved-comment count as a badge. Default: true. */\n  showCount?: boolean;\n  /**\n   * Hide the pill while Vizu is enabled. Default: true — Vizu's own toolbar\n   * has a disable button, so a second toggle would be redundant. Pass false\n   * to keep the pill visible as an on/off toggle instead.\n   */\n  hideWhenActive?: boolean;\n  /** Accent for the dot + active border. Default: Vizu's accent (#FF6647). */\n  accent?: string;\n  /** Stacking context. Default: 2147483646 (one below Vizu's own overlay). */\n  zIndex?: number;\n  className?: string;\n  /** Merged over the pill's base styles — positioning included, so `style={{ inset: ... }}` can relocate it entirely. */\n  style?: CSSProperties;\n  /** Replaces the default dot + label + count content. Styling of the pill shell still applies. */\n  children?: ReactNode;\n  /** Called after the pill toggles Vizu, with the new enabled state. */\n  onToggle?: (enabled: boolean) => void;\n}\n\nfunction useVizuEnabled(vizu: Vizu): boolean {\n  const subscribe = useMemo(\n    () => (cb: () => void) => {\n      const offs = [vizu.on('enabled', cb), vizu.on('disabled', cb)];\n      return () => offs.forEach((off) => off());\n    },\n    [vizu],\n  );\n  const getSnapshot = () => vizu.isEnabled();\n  return useSyncExternalStore(subscribe, getSnapshot, () => false);\n}\n\nfunction useCommentCount(vizu: Vizu): number {\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  const getSnapshot = () => vizu.getComments().length;\n  return useSyncExternalStore(subscribe, getSnapshot, () => 0);\n}\n\nconst ACCENT_DEFAULT = '#FF6647';\n\n/**\n * A floating pill the host app renders anywhere inside <VizuProvider>.\n * One click enables Vizu — no keyboard shortcut needed. In cloud mode the\n * click also kicks the sign-in popup (same as the shortcut path), so a\n * signed-out reviewer lands straight in the auth flow.\n *\n * By default the pill hides itself while Vizu is active (Vizu's own toolbar\n * takes over) and reappears when Vizu is disabled.\n */\nexport function VizuLauncher({\n  label = 'Feedback',\n  position = 'bottom-right',\n  offset = 20,\n  showCount = true,\n  hideWhenActive = true,\n  accent = ACCENT_DEFAULT,\n  zIndex = 2147483646,\n  className,\n  style,\n  children,\n  onToggle,\n}: VizuLauncherProps) {\n  const vizu = useVizu();\n  const enabled = useVizuEnabled(vizu);\n  const count = useCommentCount(vizu);\n  const [hovered, setHovered] = useState(false);\n  const buttonRef = useRef<HTMLButtonElement>(null);\n\n  if (enabled && hideWhenActive) return null;\n\n  const [vSide, hSide] = position.split('-') as ['bottom' | 'top', 'left' | 'right'];\n\n  const base: CSSProperties = {\n    position: 'fixed',\n    [vSide]: offset,\n    [hSide]: offset,\n    zIndex,\n    display: 'inline-flex',\n    alignItems: 'center',\n    gap: 8,\n    padding: '9px 16px',\n    borderRadius: 999,\n    border: `1px solid ${enabled ? accent : hovered ? '#3A3A3A' : '#2A2A2A'}`,\n    background: hovered ? '#1A1A1A' : '#0A0A0A',\n    color: '#fafafa',\n    font: '500 13px/1 -apple-system, BlinkMacSystemFont, \"Segoe UI\", system-ui, sans-serif',\n    cursor: 'pointer',\n    boxShadow: '0 8px 24px rgba(0,0,0,.4), inset 0 0 0 1px rgba(255,255,255,.04)',\n    userSelect: 'none',\n    transition: 'background 120ms, border-color 120ms, transform 120ms',\n    transform: hovered ? 'translateY(-1px)' : 'none',\n  };\n\n  const handleClick = () => {\n    vizu.toggle();\n    // Enabling from a click is explicit user intent — kick cloud sign-in\n    // now (no-op outside cloud mode / when signed in), mirroring the\n    // keyboard shortcut's behavior.\n    if (vizu.isEnabled()) vizu.requestAuth();\n    onToggle?.(vizu.isEnabled());\n    buttonRef.current?.blur();\n  };\n\n  return (\n    <button\n      ref={buttonRef}\n      type=\"button\"\n      // Keeps Vizu's highlighter from treating the launcher as a commentable\n      // element when it stays visible while Vizu is active (hideWhenActive={false}).\n      data-vizu-ignore=\"\"\n      className={className}\n      style={{ ...base, ...style }}\n      onClick={handleClick}\n      onMouseEnter={() => setHovered(true)}\n      onMouseLeave={() => setHovered(false)}\n      aria-pressed={enabled}\n      title={enabled ? 'Turn off commenting' : 'Comment on this page'}\n    >\n      {children ?? (\n        <>\n          <span\n            aria-hidden=\"true\"\n            style={{\n              width: 7,\n              height: 7,\n              borderRadius: '50%',\n              background: accent,\n              boxShadow: `0 0 8px ${accent}`,\n              flexShrink: 0,\n            }}\n          />\n          <span>{label}</span>\n          {showCount && count > 0 && (\n            <span\n              style={{\n                minWidth: 18,\n                height: 18,\n                padding: '0 5px',\n                borderRadius: 9,\n                background: '#2A2A2A',\n                color: '#fafafa',\n                fontSize: 11,\n                fontWeight: 600,\n                display: 'inline-flex',\n                alignItems: 'center',\n                justifyContent: 'center',\n              }}\n            >\n              {count}\n            </span>\n          )}\n        </>\n      )}\n    </button>\n  );\n}\n"],"mappings":"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","names":["import_react","import_jsx_runtime"]}

package/dist/index.d.cts

@@ -1,8 +1,47 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import { CSSProperties, 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';
 
+type VizuLauncherPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+interface VizuLauncherProps {
+    /** Text inside the pill. Default: "Feedback". */
+    label?: string;
+    /** Which corner the pill floats in. Default: 'bottom-right' (Vizu's own toolbar sits bottom-center). */
+    position?: VizuLauncherPosition;
+    /** Distance from the two nearest viewport edges, in px. Default: 20. */
+    offset?: number;
+    /** Show the saved-comment count as a badge. Default: true. */
+    showCount?: boolean;
+    /**
+     * Hide the pill while Vizu is enabled. Default: true — Vizu's own toolbar
+     * has a disable button, so a second toggle would be redundant. Pass false
+     * to keep the pill visible as an on/off toggle instead.
+     */
+    hideWhenActive?: boolean;
+    /** Accent for the dot + active border. Default: Vizu's accent (#FF6647). */
+    accent?: string;
+    /** Stacking context. Default: 2147483646 (one below Vizu's own overlay). */
+    zIndex?: number;
+    className?: string;
+    /** Merged over the pill's base styles — positioning included, so `style={{ inset: ... }}` can relocate it entirely. */
+    style?: CSSProperties;
+    /** Replaces the default dot + label + count content. Styling of the pill shell still applies. */
+    children?: ReactNode;
+    /** Called after the pill toggles Vizu, with the new enabled state. */
+    onToggle?: (enabled: boolean) => void;
+}
+/**
+ * A floating pill the host app renders anywhere inside <VizuProvider>.
+ * One click enables Vizu — no keyboard shortcut needed. In cloud mode the
+ * click also kicks the sign-in popup (same as the shortcut path), so a
+ * signed-out reviewer lands straight in the auth flow.
+ *
+ * By default the pill hides itself while Vizu is active (Vizu's own toolbar
+ * takes over) and reappears when Vizu is disabled.
+ */
+declare function VizuLauncher({ label, position, offset, showCount, hideWhenActive, accent, zIndex, className, style, children, onToggle, }: VizuLauncherProps): react_jsx_runtime.JSX.Element | null;
+
 interface VizuProviderProps {
     options?: VizuOptions;
     children?: ReactNode;
@@ -27,4 +66,4 @@ declare function useVizuUser(): [VizuUser | null, (u: VizuUser | null) => void];
  */
 declare function useVizuAction(action: VizuAction): void;
 
-export { VizuProvider, type VizuProviderProps, useComments, useVizu, useVizuAction, useVizuEvent, useVizuUser };
+export { VizuLauncher, type VizuLauncherPosition, type VizuLauncherProps, VizuProvider, type VizuProviderProps, useComments, useVizu, useVizuAction, useVizuEvent, useVizuUser };

package/dist/index.d.ts

@@ -1,8 +1,47 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import { CSSProperties, 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';
 
+type VizuLauncherPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+interface VizuLauncherProps {
+    /** Text inside the pill. Default: "Feedback". */
+    label?: string;
+    /** Which corner the pill floats in. Default: 'bottom-right' (Vizu's own toolbar sits bottom-center). */
+    position?: VizuLauncherPosition;
+    /** Distance from the two nearest viewport edges, in px. Default: 20. */
+    offset?: number;
+    /** Show the saved-comment count as a badge. Default: true. */
+    showCount?: boolean;
+    /**
+     * Hide the pill while Vizu is enabled. Default: true — Vizu's own toolbar
+     * has a disable button, so a second toggle would be redundant. Pass false
+     * to keep the pill visible as an on/off toggle instead.
+     */
+    hideWhenActive?: boolean;
+    /** Accent for the dot + active border. Default: Vizu's accent (#FF6647). */
+    accent?: string;
+    /** Stacking context. Default: 2147483646 (one below Vizu's own overlay). */
+    zIndex?: number;
+    className?: string;
+    /** Merged over the pill's base styles — positioning included, so `style={{ inset: ... }}` can relocate it entirely. */
+    style?: CSSProperties;
+    /** Replaces the default dot + label + count content. Styling of the pill shell still applies. */
+    children?: ReactNode;
+    /** Called after the pill toggles Vizu, with the new enabled state. */
+    onToggle?: (enabled: boolean) => void;
+}
+/**
+ * A floating pill the host app renders anywhere inside <VizuProvider>.
+ * One click enables Vizu — no keyboard shortcut needed. In cloud mode the
+ * click also kicks the sign-in popup (same as the shortcut path), so a
+ * signed-out reviewer lands straight in the auth flow.
+ *
+ * By default the pill hides itself while Vizu is active (Vizu's own toolbar
+ * takes over) and reappears when Vizu is disabled.
+ */
+declare function VizuLauncher({ label, position, offset, showCount, hideWhenActive, accent, zIndex, className, style, children, onToggle, }: VizuLauncherProps): react_jsx_runtime.JSX.Element | null;
+
 interface VizuProviderProps {
     options?: VizuOptions;
     children?: ReactNode;
@@ -27,4 +66,4 @@ declare function useVizuUser(): [VizuUser | null, (u: VizuUser | null) => void];
  */
 declare function useVizuAction(action: VizuAction): void;
 
-export { VizuProvider, type VizuProviderProps, useComments, useVizu, useVizuAction, useVizuEvent, useVizuUser };
+export { VizuLauncher, type VizuLauncherPosition, type VizuLauncherProps, VizuProvider, type VizuProviderProps, useComments, useVizu, useVizuAction, useVizuEvent, useVizuUser };

package/dist/index.js

@@ -5,28 +5,174 @@ import {
   createContext,
   useContext,
   useEffect,
-  useMemo,
-  useRef,
-  useSyncExternalStore
+  useMemo as useMemo2,
+  useRef as useRef2,
+  useState as useState2,
+  useSyncExternalStore as useSyncExternalStore2
 } from "react";
 import {
   Vizu
 } from "@unhingged/vizu-core";
-import { jsx } from "react/jsx-runtime";
+
+// src/launcher.tsx
+import {
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+function useVizuEnabled(vizu) {
+  const subscribe = useMemo(
+    () => (cb) => {
+      const offs = [vizu.on("enabled", cb), vizu.on("disabled", cb)];
+      return () => offs.forEach((off) => off());
+    },
+    [vizu]
+  );
+  const getSnapshot = () => vizu.isEnabled();
+  return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}
+function useCommentCount(vizu) {
+  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 getSnapshot = () => vizu.getComments().length;
+  return useSyncExternalStore(subscribe, getSnapshot, () => 0);
+}
+var ACCENT_DEFAULT = "#FF6647";
+function VizuLauncher({
+  label = "Feedback",
+  position = "bottom-right",
+  offset = 20,
+  showCount = true,
+  hideWhenActive = true,
+  accent = ACCENT_DEFAULT,
+  zIndex = 2147483646,
+  className,
+  style,
+  children,
+  onToggle
+}) {
+  const vizu = useVizu();
+  const enabled = useVizuEnabled(vizu);
+  const count = useCommentCount(vizu);
+  const [hovered, setHovered] = useState(false);
+  const buttonRef = useRef(null);
+  if (enabled && hideWhenActive) return null;
+  const [vSide, hSide] = position.split("-");
+  const base = {
+    position: "fixed",
+    [vSide]: offset,
+    [hSide]: offset,
+    zIndex,
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 8,
+    padding: "9px 16px",
+    borderRadius: 999,
+    border: `1px solid ${enabled ? accent : hovered ? "#3A3A3A" : "#2A2A2A"}`,
+    background: hovered ? "#1A1A1A" : "#0A0A0A",
+    color: "#fafafa",
+    font: '500 13px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif',
+    cursor: "pointer",
+    boxShadow: "0 8px 24px rgba(0,0,0,.4), inset 0 0 0 1px rgba(255,255,255,.04)",
+    userSelect: "none",
+    transition: "background 120ms, border-color 120ms, transform 120ms",
+    transform: hovered ? "translateY(-1px)" : "none"
+  };
+  const handleClick = () => {
+    vizu.toggle();
+    if (vizu.isEnabled()) vizu.requestAuth();
+    onToggle?.(vizu.isEnabled());
+    buttonRef.current?.blur();
+  };
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      ref: buttonRef,
+      type: "button",
+      "data-vizu-ignore": "",
+      className,
+      style: { ...base, ...style },
+      onClick: handleClick,
+      onMouseEnter: () => setHovered(true),
+      onMouseLeave: () => setHovered(false),
+      "aria-pressed": enabled,
+      title: enabled ? "Turn off commenting" : "Comment on this page",
+      children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            "aria-hidden": "true",
+            style: {
+              width: 7,
+              height: 7,
+              borderRadius: "50%",
+              background: accent,
+              boxShadow: `0 0 8px ${accent}`,
+              flexShrink: 0
+            }
+          }
+        ),
+        /* @__PURE__ */ jsx("span", { children: label }),
+        showCount && count > 0 && /* @__PURE__ */ jsx(
+          "span",
+          {
+            style: {
+              minWidth: 18,
+              height: 18,
+              padding: "0 5px",
+              borderRadius: 9,
+              background: "#2A2A2A",
+              color: "#fafafa",
+              fontSize: 11,
+              fontWeight: 600,
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center"
+            },
+            children: count
+          }
+        )
+      ] })
+    }
+  );
+}
+
+// src/index.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
 var VizuContext = createContext(null);
 function VizuProvider({ options, children }) {
-  const ref = useRef(null);
+  const optionsRef = useRef2(options);
+  optionsRef.current = options;
+  const ref = useRef2(null);
   if (ref.current === null) {
     ref.current = new Vizu(options ?? {});
   }
-  const vizu = ref.current;
+  const [vizu, setVizu] = useState2(ref.current);
   useEffect(() => {
+    if (ref.current === null) {
+      ref.current = new Vizu(optionsRef.current ?? {});
+      setVizu(ref.current);
+    }
+    const instance = ref.current;
     return () => {
-      vizu.destroy();
+      instance.destroy();
       ref.current = null;
     };
   }, []);
-  return /* @__PURE__ */ jsx(VizuContext.Provider, { value: vizu, children });
+  return /* @__PURE__ */ jsx2(VizuContext.Provider, { value: vizu, children });
 }
 function useVizu() {
   const v = useContext(VizuContext);
@@ -37,7 +183,7 @@ function useVizu() {
 }
 function useVizuEvent(event, handler) {
   const vizu = useVizu();
-  const handlerRef = useRef(handler);
+  const handlerRef = useRef2(handler);
   handlerRef.current = handler;
   useEffect(() => {
     const off = vizu.on(event, (payload) => handlerRef.current(payload));
@@ -46,7 +192,7 @@ function useVizuEvent(event, handler) {
 }
 function useComments() {
   const vizu = useVizu();
-  const subscribe = useMemo(
+  const subscribe = useMemo2(
     () => (cb) => {
       const offs = [
         vizu.on("comment:added", cb),
@@ -59,7 +205,7 @@ function useComments() {
     },
     [vizu]
   );
-  const cacheRef = useRef(vizu.getComments());
+  const cacheRef = useRef2(vizu.getComments());
   const getSnapshot = () => {
     const next = vizu.getComments();
     const last = cacheRef.current;
@@ -69,21 +215,21 @@ function useComments() {
     cacheRef.current = next;
     return next;
   };
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return useSyncExternalStore2(subscribe, getSnapshot, getSnapshot);
 }
 function useVizuUser() {
   const vizu = useVizu();
-  const subscribe = useMemo(
+  const subscribe = useMemo2(
     () => (cb) => vizu.on("user:changed", cb),
     [vizu]
   );
   const getSnapshot = () => vizu.getUser();
-  const user = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const user = useSyncExternalStore2(subscribe, getSnapshot, getSnapshot);
   return [user, (u) => vizu.setUser(u)];
 }
 function useVizuAction(action) {
   const vizu = useVizu();
-  const actionRef = useRef(action);
+  const actionRef = useRef2(action);
   actionRef.current = action;
   useEffect(() => {
     vizu.addAction({
@@ -95,6 +241,7 @@ function useVizuAction(action) {
   }, [vizu, action.id]);
 }
 export {
+  VizuLauncher,
   VizuProvider,
   useComments,
   useVizu,

package/dist/index.js.map

@@ -1 +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":[]}
+{"version":3,"sources":["../src/index.tsx","../src/launcher.tsx"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\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\nexport { VizuLauncher } from './launcher';\nexport type { VizuLauncherProps, VizuLauncherPosition } from './launcher';\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  // Latest options, so a StrictMode recreation (below) doesn't construct\n  // from a stale first-render snapshot.\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  // The instance must exist during the first render (children call useVizu\n  // immediately), so construct lazily here rather than in the effect.\n  const ref = useRef<Vizu | null>(null);\n  if (ref.current === null) {\n    ref.current = new Vizu(options ?? {});\n  }\n  // Context value lives in state so a recreated instance propagates to\n  // consumers; re-renders don't construct new ones.\n  const [vizu, setVizu] = useState<Vizu>(ref.current);\n\n  useEffect(() => {\n    // StrictMode's mount→cleanup→remount cycle destroys the render-time\n    // instance in the first cleanup without re-running the render-phase\n    // construction. Recreate here and push it through state so every\n    // consumer re-subscribes to the live instance.\n    if (ref.current === null) {\n      ref.current = new Vizu(optionsRef.current ?? {});\n      setVizu(ref.current);\n    }\n    const instance = ref.current;\n    return () => {\n      instance.destroy();\n      ref.current = null;\n    };\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","'use client';\n\nimport {\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type CSSProperties,\n  type ReactNode,\n} from 'react';\nimport type { Vizu } from '@unhingged/vizu-core';\nimport { useVizu } from './index';\n\nexport type VizuLauncherPosition =\n  | 'bottom-right'\n  | 'bottom-left'\n  | 'top-right'\n  | 'top-left';\n\nexport interface VizuLauncherProps {\n  /** Text inside the pill. Default: \"Feedback\". */\n  label?: string;\n  /** Which corner the pill floats in. Default: 'bottom-right' (Vizu's own toolbar sits bottom-center). */\n  position?: VizuLauncherPosition;\n  /** Distance from the two nearest viewport edges, in px. Default: 20. */\n  offset?: number;\n  /** Show the saved-comment count as a badge. Default: true. */\n  showCount?: boolean;\n  /**\n   * Hide the pill while Vizu is enabled. Default: true — Vizu's own toolbar\n   * has a disable button, so a second toggle would be redundant. Pass false\n   * to keep the pill visible as an on/off toggle instead.\n   */\n  hideWhenActive?: boolean;\n  /** Accent for the dot + active border. Default: Vizu's accent (#FF6647). */\n  accent?: string;\n  /** Stacking context. Default: 2147483646 (one below Vizu's own overlay). */\n  zIndex?: number;\n  className?: string;\n  /** Merged over the pill's base styles — positioning included, so `style={{ inset: ... }}` can relocate it entirely. */\n  style?: CSSProperties;\n  /** Replaces the default dot + label + count content. Styling of the pill shell still applies. */\n  children?: ReactNode;\n  /** Called after the pill toggles Vizu, with the new enabled state. */\n  onToggle?: (enabled: boolean) => void;\n}\n\nfunction useVizuEnabled(vizu: Vizu): boolean {\n  const subscribe = useMemo(\n    () => (cb: () => void) => {\n      const offs = [vizu.on('enabled', cb), vizu.on('disabled', cb)];\n      return () => offs.forEach((off) => off());\n    },\n    [vizu],\n  );\n  const getSnapshot = () => vizu.isEnabled();\n  return useSyncExternalStore(subscribe, getSnapshot, () => false);\n}\n\nfunction useCommentCount(vizu: Vizu): number {\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  const getSnapshot = () => vizu.getComments().length;\n  return useSyncExternalStore(subscribe, getSnapshot, () => 0);\n}\n\nconst ACCENT_DEFAULT = '#FF6647';\n\n/**\n * A floating pill the host app renders anywhere inside <VizuProvider>.\n * One click enables Vizu — no keyboard shortcut needed. In cloud mode the\n * click also kicks the sign-in popup (same as the shortcut path), so a\n * signed-out reviewer lands straight in the auth flow.\n *\n * By default the pill hides itself while Vizu is active (Vizu's own toolbar\n * takes over) and reappears when Vizu is disabled.\n */\nexport function VizuLauncher({\n  label = 'Feedback',\n  position = 'bottom-right',\n  offset = 20,\n  showCount = true,\n  hideWhenActive = true,\n  accent = ACCENT_DEFAULT,\n  zIndex = 2147483646,\n  className,\n  style,\n  children,\n  onToggle,\n}: VizuLauncherProps) {\n  const vizu = useVizu();\n  const enabled = useVizuEnabled(vizu);\n  const count = useCommentCount(vizu);\n  const [hovered, setHovered] = useState(false);\n  const buttonRef = useRef<HTMLButtonElement>(null);\n\n  if (enabled && hideWhenActive) return null;\n\n  const [vSide, hSide] = position.split('-') as ['bottom' | 'top', 'left' | 'right'];\n\n  const base: CSSProperties = {\n    position: 'fixed',\n    [vSide]: offset,\n    [hSide]: offset,\n    zIndex,\n    display: 'inline-flex',\n    alignItems: 'center',\n    gap: 8,\n    padding: '9px 16px',\n    borderRadius: 999,\n    border: `1px solid ${enabled ? accent : hovered ? '#3A3A3A' : '#2A2A2A'}`,\n    background: hovered ? '#1A1A1A' : '#0A0A0A',\n    color: '#fafafa',\n    font: '500 13px/1 -apple-system, BlinkMacSystemFont, \"Segoe UI\", system-ui, sans-serif',\n    cursor: 'pointer',\n    boxShadow: '0 8px 24px rgba(0,0,0,.4), inset 0 0 0 1px rgba(255,255,255,.04)',\n    userSelect: 'none',\n    transition: 'background 120ms, border-color 120ms, transform 120ms',\n    transform: hovered ? 'translateY(-1px)' : 'none',\n  };\n\n  const handleClick = () => {\n    vizu.toggle();\n    // Enabling from a click is explicit user intent — kick cloud sign-in\n    // now (no-op outside cloud mode / when signed in), mirroring the\n    // keyboard shortcut's behavior.\n    if (vizu.isEnabled()) vizu.requestAuth();\n    onToggle?.(vizu.isEnabled());\n    buttonRef.current?.blur();\n  };\n\n  return (\n    <button\n      ref={buttonRef}\n      type=\"button\"\n      // Keeps Vizu's highlighter from treating the launcher as a commentable\n      // element when it stays visible while Vizu is active (hideWhenActive={false}).\n      data-vizu-ignore=\"\"\n      className={className}\n      style={{ ...base, ...style }}\n      onClick={handleClick}\n      onMouseEnter={() => setHovered(true)}\n      onMouseLeave={() => setHovered(false)}\n      aria-pressed={enabled}\n      title={enabled ? 'Turn off commenting' : 'Comment on this page'}\n    >\n      {children ?? (\n        <>\n          <span\n            aria-hidden=\"true\"\n            style={{\n              width: 7,\n              height: 7,\n              borderRadius: '50%',\n              background: accent,\n              boxShadow: `0 0 8px ${accent}`,\n              flexShrink: 0,\n            }}\n          />\n          <span>{label}</span>\n          {showCount && count > 0 && (\n            <span\n              style={{\n                minWidth: 18,\n                height: 18,\n                padding: '0 5px',\n                borderRadius: 9,\n                background: '#2A2A2A',\n                color: '#fafafa',\n                fontSize: 11,\n                fontWeight: 600,\n                display: 'inline-flex',\n                alignItems: 'center',\n                justifyContent: 'center',\n              }}\n            >\n              {count}\n            </span>\n          )}\n        </>\n      )}\n    </button>\n  );\n}\n"],"mappings":"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","names":["useMemo","useRef","useState","useSyncExternalStore","jsx","useRef","useState","useMemo","useSyncExternalStore"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unhingged/vizu-react",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "React bindings for @unhingged/vizu-core — VizuProvider, useVizu, useComments, useVizuUser, useVizuEvent.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,17 +23,21 @@
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "test": "bun test"
   },
   "peerDependencies": {
     "react": ">=18"
   },
   "dependencies": {
-    "@unhingged/vizu-core": "workspace:*"
+    "@unhingged/vizu-core": "0.1.21"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.9.0",
     "@types/react": "^18.3.0",
+    "happy-dom": "^20.9.0",
     "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3"
   },