@unhingged/vizu-core 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,428 @@
+# @vizu/core
+
+A drop-in DOM commenting tool. Press a shortcut on any page → highlight any element → leave a comment → the host application handles persistence and downstream actions via events.
+
+**Vizu is a UI for collecting annotations, not a storage system or an LLM-prompt builder.** It emits events; you decide what to do with them.
+
+```bash
+npm install @vizu/core
+```
+
+## Install via `<script>`
+
+```html
+<script
+  src="https://unpkg.com/@vizu/core/dist/vizu.min.js"
+  data-shortcut="mod+shift+e"
+  data-namespace="my-site"
+  data-version="v1"
+  data-start-enabled="true"
+  data-user-name="Jane Doe"
+  data-user-avatar="https://example.com/jane.jpg">
+</script>
+<script>
+  // Vizu is at window.__vizu — register your actions here
+  window.__vizu.addAction({
+    id: 'copy',
+    label: 'Copy',
+    variant: 'primary',
+    onClick: (ctx) => ctx.copyToClipboard(JSON.stringify(ctx.comments, null, 2)),
+  });
+  window.__vizu.on('comment:added', ({ comment }) => {
+    fetch('/api/comments', { method: 'POST', body: JSON.stringify(comment) });
+  });
+</script>
+```
+
+Defaults in `<script>` mode: `data-storage="local"` (localStorage), no actions registered.
+
+## What it does — and what it doesn't
+
+| Vizu does | Vizu does NOT |
+|---|---|
+| Renders the highlight, marker, popover, sidebar, pill | Persist comments anywhere by default (you wire that) |
+| Captures DOM-anchored comments with fingerprints that survive edits | Format prompts / payloads (you build whatever shape you want) |
+| Emits typed events for everything | Send anything to a backend |
+| Exposes a `setUser` / `setComments` API for hydration | Manage auth or sessions |
+| Lets you register pill actions | Ship "Copy as prompt" / "JSON" / "Clear" buttons |
+
+---
+
+## Integration
+
+### Plain JS / Vanilla
+
+```ts
+import { Vizu } from '@vizu/core';
+
+const vizu = new Vizu({
+  namespace: 'my-site',
+  pageVersion: 'home-v1',
+  shortcut: 'mod+shift+e',
+  user: { id: '123', name: 'Jane Doe', avatarUrl: '/jane.jpg' },
+  // storage defaults to 'memory' in the programmatic API — host owns persistence
+});
+
+// 1. Listen for new comments → POST to your backend
+vizu.on('comment:added', async ({ comment }) => {
+  await fetch('/api/comments', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(comment),
+  });
+});
+
+vizu.on('comment:removed', async ({ id }) => {
+  await fetch(`/api/comments/${id}`, { method: 'DELETE' });
+});
+
+// 2. Hydrate from your backend on load
+const existing = await fetch('/api/comments?ns=my-site').then((r) => r.json());
+await vizu.setComments(existing, { persist: false });
+
+// 3. Register a pill action that builds your own prompt format
+vizu.addAction({
+  id: 'send-to-llm',
+  label: 'Send to LLM',
+  variant: 'primary',
+  onClick: async (ctx) => {
+    const res = await fetch('/api/iterate', {
+      method: 'POST',
+      body: JSON.stringify({
+        comments: ctx.comments,
+        pageHtml: ctx.pageHtml,
+        version: ctx.pageVersion,
+      }),
+    });
+    const { newHtml } = await res.json();
+    document.documentElement.innerHTML = newHtml;
+    ctx.toast('Page iterated');
+  },
+  visibleWhen: ({ commentsCount }) => commentsCount > 0,
+});
+
+vizu.enable();
+```
+
+### React (via [@vizu/react](../vizu-react))
+
+```tsx
+'use client';
+import {
+  VizuProvider, useVizu, useComments, useVizuUser,
+  useVizuEvent, useVizuAction,
+} from '@vizu/react';
+
+function App() {
+  return (
+    <VizuProvider options={{ namespace: 'my-app', startEnabled: true }}>
+      <Annotations />
+      <YourPage />
+    </VizuProvider>
+  );
+}
+
+function Annotations() {
+  const [, setUser] = useVizuUser();
+  const session = useSession();
+  useEffect(() => {
+    if (session) setUser({ id: session.userId, name: session.name, avatarUrl: session.avatar });
+  }, [session, setUser]);
+
+  useVizuEvent('comment:added', ({ comment }) =>
+    fetch('/api/comments', { method: 'POST', body: JSON.stringify(comment) }),
+  );
+
+  useVizuAction({
+    id: 'send',
+    label: 'Send to backend',
+    variant: 'primary',
+    onClick: (ctx) => fetch('/api/iterate', { method: 'POST', body: JSON.stringify(ctx) }),
+    visibleWhen: ({ commentsCount }) => commentsCount > 0,
+  });
+
+  const comments = useComments();
+  return <CommentsBadge count={comments.length} />;
+}
+```
+
+### Vue 3
+
+A thin composable is the cleanest shape. Until `@vizu/vue` ships, write your own:
+
+```ts
+// composables/useVizu.ts
+import { onMounted, onUnmounted, ref, type Ref } from 'vue';
+import { Vizu, type VizuOptions, type VizuComment } from '@vizu/core';
+
+export function useVizu(options: VizuOptions) {
+  const vizu = new Vizu(options);
+  const comments: Ref<VizuComment[]> = ref([]);
+
+  const refresh = () => { comments.value = vizu.getComments(); };
+  const offs: Array<() => void> = [];
+
+  onMounted(() => {
+    vizu.enable();
+    offs.push(
+      vizu.on('comment:added', refresh),
+      vizu.on('comment:removed', refresh),
+      vizu.on('comments:cleared', refresh),
+      vizu.on('comments:set', refresh),
+      vizu.on('comments:loaded', refresh),
+    );
+    refresh();
+  });
+  onUnmounted(() => {
+    offs.forEach((o) => o());
+    vizu.destroy();
+  });
+  return { vizu, comments };
+}
+```
+
+Use in a component:
+```vue
+<script setup lang="ts">
+import { useVizu } from './composables/useVizu';
+const { vizu, comments } = useVizu({ namespace: 'my-vue-app', startEnabled: true });
+vizu.on('comment:added', ({ comment }) => fetch('/api/comments', { method: 'POST', body: JSON.stringify(comment) }));
+</script>
+<template>
+  <div>{{ comments.length }} comments</div>
+</template>
+```
+
+### Angular
+
+Provide Vizu via a service so identity + listeners are global:
+
+```ts
+// vizu.service.ts
+import { Injectable, NgZone, OnDestroy } from '@angular/core';
+import { Vizu, type VizuOptions } from '@vizu/core';
+
+@Injectable({ providedIn: 'root' })
+export class VizuService implements OnDestroy {
+  readonly vizu: Vizu;
+  private offs: Array<() => void> = [];
+
+  constructor(private zone: NgZone) {
+    // Construct outside the zone so Vizu's own DOM listeners don't trigger CD on every mouse move
+    this.vizu = this.zone.runOutsideAngular(() => new Vizu({
+      namespace: 'my-ng-app',
+      startEnabled: true,
+    } satisfies VizuOptions));
+
+    // Pipe events back into the zone if your handlers update Angular state
+    this.offs.push(this.vizu.on('comment:added', (payload) =>
+      this.zone.run(() => fetch('/api/comments', { method: 'POST', body: JSON.stringify(payload.comment) })),
+    ));
+  }
+
+  setUser(name: string, avatarUrl?: string) {
+    this.vizu.setUser({ name, avatarUrl });
+  }
+
+  ngOnDestroy() {
+    this.offs.forEach((o) => o());
+    this.vizu.destroy();
+  }
+}
+```
+
+Use it in a component:
+```ts
+@Component({...})
+export class AppComponent {
+  constructor(private vizuService: VizuService) {
+    this.vizuService.vizu.addAction({
+      id: 'send',
+      label: 'Send to API',
+      variant: 'primary',
+      onClick: (ctx) => fetch('/api/iterate', { method: 'POST', body: JSON.stringify(ctx) }),
+    });
+  }
+}
+```
+
+### Other frameworks
+
+Anything with a DOM works. The package is framework-agnostic — `new Vizu(...)`, subscribe to events, call `setUser`/`setComments`/`addAction`. Lifecycle hook → `vizu.destroy()` on teardown.
+
+---
+
+## Events
+
+Fire-and-forget. Handlers throw silently (errors are logged but don't break Vizu's state). Every payload is an object so the shape stays forward-compatible.
+
+| Event | Payload | When it fires |
+|---|---|---|
+| `enabled` | `{}` | After `vizu.enable()` |
+| `disabled` | `{}` | After `vizu.disable()` |
+| `mounted` | `{}` | After the UI is in the DOM |
+| `unmounted` | `{}` | After the UI is removed |
+| `comment:added` | `{ comment: VizuComment }` | User saved a new comment |
+| `comment:removed` | `{ id: string, comment: VizuComment }` | User clicked delete |
+| `comments:cleared` | `{ previous: VizuComment[] }` | `clearAll()` resolved |
+| `comments:set` | `{ comments: VizuComment[] }` | `setComments(...)` resolved (hydration) |
+| `comments:loaded` | `{ comments: VizuComment[] }` | Storage adapter finished initial `load()` |
+| `element:selected` | `{ target: Element, fingerprint: ElementFingerprint }` | User clicked a commentable element |
+| `element:deselected` | `{}` | Popover closed |
+| `sidebar:opened` | `{}` | Sidebar drawer opened |
+| `sidebar:closed` | `{}` | Sidebar drawer closed |
+| `action:invoked` | `{ id: string }` | Pill action clicked (before its `onClick` runs) |
+| `user:changed` | `{ user: VizuUser \| null }` | `setUser(...)` called |
+
+### Subscription API
+
+```ts
+const off = vizu.on('comment:added', ({ comment }) => { /* ... */ });
+off();           // unsubscribe
+vizu.off('comment:added', handler); // alternative
+```
+
+`on()` returns an unsubscribe function. Use it in cleanup paths (React `useEffect` return, Vue `onUnmounted`, Angular `ngOnDestroy`).
+
+---
+
+## Supplying current user data
+
+Three ways:
+
+**1. At construction**
+```ts
+new Vizu({ user: { id: '123', name: 'Jane Doe', avatarUrl: '/jane.jpg' } });
+```
+
+**2. Imperatively (re-renders the pill chip + popover author line)**
+```ts
+vizu.setUser({ id: '123', name: 'Jane Doe', avatarUrl: '/jane.jpg' });
+// or clear
+vizu.setUser(null);
+```
+
+**3. Script-tag data attributes**
+```html
+<script src="vizu.min.js" data-user-name="Jane" data-user-id="123" data-user-avatar="/jane.jpg"></script>
+```
+
+The current user is captured into every new comment as `comment.author` — that snapshot is preserved even if the user logs out or changes name later.
+
+`VizuUser` shape:
+```ts
+{
+  id?: string;
+  name: string;
+  avatarUrl?: string;
+  email?: string;
+  meta?: Record<string, unknown>; // free-form host extras (team, role, etc.)
+}
+```
+
+---
+
+## Loading existing comments
+
+Vizu doesn't ship a server adapter — bring your own. Two patterns:
+
+### Listen + push (recommended for live apps)
+
+```ts
+// On load, hydrate from your API
+const initial = await fetch('/api/comments?ns=my-site').then(r => r.json());
+await vizu.setComments(initial, { persist: false });
+
+// Then mirror every change to the backend
+vizu.on('comment:added', ({ comment }) => fetch('/api/comments', { method: 'POST', body: JSON.stringify(comment) }));
+vizu.on('comment:removed', ({ id }) => fetch(`/api/comments/${id}`, { method: 'DELETE' }));
+vizu.on('comments:cleared', () => fetch('/api/comments?ns=my-site', { method: 'DELETE' }));
+```
+
+### Custom `StorageAdapter`
+
+```ts
+import { Vizu, type StorageAdapter, type VizuComment } from '@vizu/core';
+
+const remote: StorageAdapter = {
+  async load(ns)    { const r = await fetch(`/api/comments?ns=${ns}`); return r.json(); },
+  async save(ns, c) { await fetch(`/api/comments?ns=${ns}`, { method: 'PUT', body: JSON.stringify(c) }); },
+  async clear(ns)   { await fetch(`/api/comments?ns=${ns}`, { method: 'DELETE' }); },
+};
+
+new Vizu({ storage: remote, namespace: 'my-site' });
+```
+
+The adapter is called transparently on add/remove/clear and once at startup. Mix and match: built-in `'local'` adapter for fast iteration, custom one for production.
+
+---
+
+## Storage modes
+
+| `options.storage` | Behavior | Default in |
+|---|---|---|
+| `'local'` | Persist to `localStorage` | Script-tag mode |
+| `'memory'` | RAM-only — wipes on reload | Programmatic API (`new Vizu()`) |
+| `'none'` | No-op storage; host owns hydration via events + `setComments` | (opt-in) |
+| `StorageAdapter` | Your own load/save/clear | (opt-in) |
+
+---
+
+## API quick reference
+
+```ts
+// Lifecycle
+vizu.enable(); vizu.disable(); vizu.toggle(); vizu.isEnabled();
+vizu.destroy(); // full teardown + clear all listeners
+
+// Comments
+vizu.getComments(): VizuComment[];
+vizu.setComments(comments, { persist?: boolean }): Promise<void>;
+vizu.clearAll(): Promise<void>;
+
+// User
+vizu.setUser(user | null);
+vizu.getUser(): VizuUser | null;
+
+// Actions
+vizu.addAction({ id, label, onClick, variant?, title?, visibleWhen? });
+vizu.removeAction(id);
+vizu.invokeAction(id); // programmatically trigger
+vizu.getActions(): VizuAction[];
+
+// Events
+vizu.on(event, handler) → off();
+vizu.off(event, handler);
+
+// Helpers
+vizu.snapshotHtml(): string; // page HTML with Vizu's own UI stripped (for sending to LLMs)
+```
+
+---
+
+## Element fingerprints
+
+Each comment carries an `ElementFingerprint` that survives edits:
+
+```ts
+{
+  selector: string;          // CSS selector path
+  parentSelector: string;
+  tagName: string;
+  textSnippet: string;       // first 80 chars of innerText
+  siblingIndex: number;
+  attributes: {
+    id?: string;
+    classList?: string[];
+    role?: string;
+    ariaLabel?: string;
+    dataKey?: string;        // from data-vizu-key="…" — explicit pin
+  };
+}
+```
+
+Re-anchoring tries: `data-vizu-key` → `id` → full selector → parent + tag + sibling-index → fuzzy text match. Add `data-vizu-key="something-stable"` to elements you want pinned permanently — it wins all matching.
+
+## License
+
+MIT