@unhingged/vizu-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,736 @@
+/**
+ * Single rung of the ancestor chain: the element's tag and its
+ * `nth-of-type` index inside its parent (1-indexed). Captured root-near
+ * → closer-to-target so the matcher can shift-search through wrapper
+ * additions.
+ */
+interface AncestorStep {
+    tag: string;
+    nthOfType: number;
+}
+interface ElementFingerprint {
+    selector: string;
+    parentSelector: string;
+    tagName: string;
+    textSnippet: string;
+    siblingIndex: number;
+    attributes: {
+        id?: string;
+        classList?: string[];
+        role?: string;
+        ariaLabel?: string;
+        dataKey?: string;
+    };
+    /**
+     * 3-step ancestor chain. Added in algorithm v2 (Phase 11.4.2). Order:
+     * immediate parent first, then grandparent, then great-grandparent.
+     * Legacy fingerprints written before this field lack it; the matcher
+     * falls back to the parent+sibling-index+tag heuristic for those.
+     */
+    ancestorChain?: {
+        steps: AncestorStep[];
+    };
+    /**
+     * Algorithm version that produced this fingerprint. Absent (or `1`) on
+     * legacy captures; new captures stamp `2` (Phase 11.4 hardened matcher
+     * — class-signature rung, multi-ancestor chain, Levenshtein text scan).
+     * The matcher routes on the presence of {@link ancestorChain} today, so
+     * this field is informational; it gives us a stable handle to migrate
+     * data when v3 ships without re-introspecting fingerprint shape.
+     */
+    algorithmVersion?: 1 | 2;
+}
+interface VizuUser {
+    id?: string;
+    name: string;
+    avatarUrl?: string;
+    email?: string;
+    /** Free-form host-defined extras (team, role, etc.) preserved on each comment. */
+    meta?: Record<string, unknown>;
+}
+/** Current schema version. Bump + add a migration when the shape changes. */
+declare const SCHEMA_VERSION: 2;
+type SchemaVersion = typeof SCHEMA_VERSION;
+/**
+ * Triage state. Cloud workspaces use this for filtering;
+ * the local sidebar treats `resolved` / `wontfix` as "dim".
+ */
+type CommentStatus = 'open' | 'resolved' | 'wontfix';
+/**
+ * Outcome of resolving a comment's fingerprint against the current DOM.
+ *
+ *   - `exact`    : `data-vizu-key` or `id` matched. We trust this 100%.
+ *   - `likely`   : The full CSS selector path matched. Probably the right
+ *                  element but not guaranteed if the page has dynamic
+ *                  duplicates.
+ *   - `drifted`  : Only the structural fallback (parent + sibling-index)
+ *                  or the page-wide text snippet matched. The page has
+ *                  changed since the comment was written. Render with a
+ *                  visible warning so visitors don't act on a stale match.
+ *   - `orphaned` : Nothing matched. The element is gone. Comment is shown
+ *                  in a separate sidebar section.
+ *
+ * Returned by `findByFingerprint`; emitted via the `anchor:resolved` event.
+ */
+type MatchConfidence = 'exact' | 'likely' | 'drifted' | 'orphaned';
+/** Result of a fingerprint resolution. `element` is null iff `confidence === 'orphaned'`. */
+interface FingerprintMatch {
+    element: Element | null;
+    confidence: MatchConfidence;
+}
+/**
+ * Embedded reply in a comment thread. Threading UI ships in v1.1 — the
+ * shape is stamped in v2 so writes are already future-correct.
+ */
+interface Reply {
+    id: string;
+    text: string;
+    createdAt: number;
+    author?: VizuUser;
+    /** Identity provider's user id (Clerk, etc.) when known. */
+    authorId?: string;
+    /** Clerk user ids mentioned in this reply. */
+    mentions?: string[];
+}
+/**
+ * File attachment metadata. Storage backend (Vercel Blob, S3, …) is
+ * decided by the host / cloud adapter; the comment only carries the
+ * resolved URL.
+ */
+interface Attachment {
+    id: string;
+    url: string;
+    mimeType: string;
+    sizeBytes: number;
+    uploadedAt: number;
+    /** Original filename the user uploaded. */
+    filename?: string;
+}
+interface VizuComment {
+    id: string;
+    /** Schema version. Set to {@link SCHEMA_VERSION} on every new write. */
+    schemaVersion: SchemaVersion;
+    /**
+     * One or more elements this comment is anchored to. Length 1 = single-anchor
+     * (the common case); >1 = "grouped" comment that applies to multiple
+     * elements together (e.g., "align these three CTAs to the same baseline").
+     *
+     * Always has length ≥ 1. Legacy v1 comments (with a singular `fingerprint`
+     * field) are auto-migrated to `[fingerprint]` on load — see `migrateComment`.
+     */
+    fingerprints: ElementFingerprint[];
+    /** @deprecated v1 only — kept on the type so older payloads parse cleanly; migrated at load time. */
+    fingerprint?: ElementFingerprint;
+    text: string;
+    createdAt: number;
+    pageVersion?: string;
+    /** @deprecated use `pageUrl` — kept for backwards-compat read of v1 payloads. */
+    url?: string;
+    /** Page URL where the comment was anchored. Cloud reads filter on this. */
+    pageUrl?: string;
+    /** Captured from `Vizu.setUser` / `options.user` at the moment the comment was created. */
+    author?: VizuUser;
+    /** Identity provider's user id (Clerk, etc.) when known. Cloud writes set this from the session. */
+    authorId?: string;
+    /**
+     * Element references the user inserted via `#` mentions. Keyed by short refId.
+     * The comment text contains tokens like `[#label](vizu-ref:refId)` that resolve
+     * to these fingerprints; clicking a rendered reference jumps to the element.
+     */
+    references?: Record<string, ElementFingerprint>;
+    /** Triage state. Defaults to `'open'` on new comments. */
+    status: CommentStatus;
+    /** Threaded replies. UI ships in v1.1; the array is always present. */
+    replies: Reply[];
+    /** File attachments. UI ships in v1.2; the array is always present. */
+    attachments: Attachment[];
+    /** Clerk user ids mentioned in this comment. */
+    mentions: string[];
+    /**
+     * Timestamp (ms) of the last self-healing re-fingerprint pass. Set by
+     * the Vizu class when a `drifted` resolution lands on an existing
+     * element and the fingerprint is rewritten in place. Reads as null
+     * for comments that have never drifted. Surface in the dashboard if
+     * you want to flag "auto-healed" rows; ignore otherwise.
+     */
+    fingerprintsRefreshedAt?: number | null;
+}
+/**
+ * Storage event emitted by adapters that support push (cloud adapters).
+ * Local / memory adapters never emit these.
+ */
+type StorageEvent = {
+    type: 'added';
+    comment: VizuComment;
+} | {
+    type: 'updated';
+    comment: VizuComment;
+} | {
+    type: 'removed';
+    id: string;
+} | {
+    type: 'cleared';
+};
+/**
+ * Optional authorization context an adapter may surface to the host.
+ * Cloud adapters set this after the user signs in; the Vizu class
+ * forwards it via `vizu.getAuthContext()` for hosts that need to call
+ * the same backend with the same session.
+ */
+interface AuthContext {
+    /** Identity provider's user id (e.g. Clerk user id). */
+    userId: string;
+    /** Short-lived bearer token. Adapter is responsible for refresh. */
+    token: string;
+    /** ISO timestamp the token expires; informational. */
+    expiresAt?: string;
+}
+/**
+ * Storage contract v2. Per-comment operations replace v1's full-array
+ * `save(comments[])`. Cloud-friendly: each mutation is one network call,
+ * the adapter can do optimistic-concurrency / conflict resolution
+ * without re-shipping the whole list.
+ *
+ * Hosts that wrote against v1 (`load / save / clear`) are still accepted —
+ * see `wrapV1Adapter` in `storage.ts` for the back-compat shim.
+ *
+ * Reply ops (`addReply` / `removeReply`) are optional: adapters that don't
+ * implement them fall back to `updateComment` with a manually-patched
+ * `replies` array. Wrapping logic lives in the Vizu class, not here.
+ */
+interface StorageAdapter {
+    /** Load all comments for this namespace. Called once at boot, plus on `setComments`. */
+    load(namespace: string): Promise<VizuComment[]>;
+    /** Persist a new comment. */
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    /** Patch an existing comment by id. Adapter returns the updated doc or `null` if not found. */
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    /** Remove a comment by id. */
+    removeComment(namespace: string, id: string): Promise<void>;
+    /** Replace the entire list (used by hosts that hydrate from their own backend). */
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    /** Wipe the namespace. */
+    clear(namespace: string): Promise<void>;
+    /** Append a reply to a comment. Adapter returns the parent or null if not found. */
+    addReply?(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    /** Remove a reply by id from a comment. Adapter returns the parent or null if not found. */
+    removeReply?(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+    /**
+     * Upload a file attachment. Returns the resolved {@link Attachment} with
+     * a public URL the host can persist on a comment. Adapters that don't
+     * implement this surface report `vizu.canUploadAttachments() === false`
+     * and the popover hides the upload UI.
+     */
+    uploadAttachment?(namespace: string, file: File): Promise<Attachment>;
+    /** Optional remote-change subscription. Returns an unsubscribe function. */
+    subscribe?(namespace: string, handler: (event: StorageEvent) => void): () => void;
+    /** Optional auth context (cloud adapters). */
+    getAuthContext?(): AuthContext | null;
+}
+/**
+ * Legacy v1 adapter shape. Kept exported so hosts can still type their
+ * existing adapters; the resolver wraps them automatically.
+ */
+interface StorageAdapterV1 {
+    load(namespace: string): Promise<VizuComment[]>;
+    save(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+}
+type StorageOption = 'local' | 'memory' | 'none' | StorageAdapter | StorageAdapterV1;
+/** Context handed to every action's onClick. Has the data and the side-effect helpers. */
+interface ActionContext {
+    comments: VizuComment[];
+    pageHtml: string;
+    pageUrl?: string;
+    pageVersion?: string;
+    user?: VizuUser;
+    timestamp: number;
+    /** Quick copy-to-clipboard helper. */
+    copyToClipboard: (text: string) => void;
+    /** Briefly show a toast above the pill. */
+    toast: (message: string) => void;
+}
+interface VizuAction {
+    id: string;
+    label: string;
+    /** Tooltip / aria-label */
+    title?: string;
+    variant?: 'primary' | 'default' | 'ghost';
+    /** Placement in the pill. Defaults to 'main'. */
+    position?: 'main';
+    onClick: (ctx: ActionContext) => void | Promise<void>;
+    /** Only render the action when this returns true. */
+    visibleWhen?: (ctx: {
+        commentsCount: number;
+    }) => boolean;
+}
+/**
+ * Cloud connection options. When set, the resolver constructs the built-in
+ * CloudStorageAdapter (Phase 3) and uses it instead of `storage`. If both
+ * `cloud` and `storage` are provided, `cloud` wins and a `console.warn`
+ * is emitted at construction time.
+ */
+interface VizuCloudOptions {
+    /** Workspace slug. Required. Created in the Vizu dashboard. */
+    workspace: string;
+    /** Override the API base URL. Defaults to `'https://vizu.unhingged.com'`. */
+    apiUrl?: string;
+    /**
+     * Auto-open the popup sign-in window when a write is attempted by an
+     * unauthenticated user. Defaults to `true`.
+     */
+    autoSignIn?: boolean;
+}
+/**
+ * Live collaboration config. Both keys are needed — the public key
+ * identifies the Liveblocks project to the browser SDK; the auth
+ * endpoint mints scoped tokens that gate room access against the
+ * workspace's role + plan.
+ *
+ * Wired in Slice 1 of plans/live-collab.md; cursor + follow rendering
+ * arrives in Slice 2+.
+ */
+interface VizuLiveblocksOptions {
+    /** Liveblocks public key from the dashboard (pk_dev_… / pk_prod_…). */
+    publicKey: string;
+    /**
+     * URL of the auth endpoint that mints room tokens. Same-origin path
+     * (`/api/liveblocks-auth`) for dashboard usage; full URL for hosts
+     * embedding @vizu/core cross-origin.
+     */
+    authEndpoint: string;
+}
+interface VizuOptions {
+    shortcut?: string;
+    namespace?: string;
+    pageVersion?: string;
+    /**
+     * Storage strategy. Default behavior:
+     * - **Programmatic** (`new Vizu()`): defaults to `'memory'`; host should listen to events to persist.
+     * - **Script-tag auto-init**: defaults to `'local'` for zero-config drop-in (override via `data-storage="memory"` or `data-storage="none"`).
+     *
+     * When `cloud` is set this option is ignored.
+     */
+    storage?: StorageOption;
+    /** Cloud workspace connection. Overrides `storage`. See {@link VizuCloudOptions}. */
+    cloud?: VizuCloudOptions;
+    /**
+     * Optional live collaboration config. When set AND the workspace's
+     * plan carries the `live_collab` feature, @vizu/core opens a
+     * Liveblocks room scoped to (workspaceSlug, pageUrl) and renders
+     * presence + cursors + follow mode. Without this, all live-collab
+     * machinery stays inert — standalone usage is unaffected.
+     *
+     * See plans/live-collab.md.
+     */
+    liveblocks?: VizuLiveblocksOptions;
+    ignoreSelectors?: string[];
+    accent?: string;
+    startEnabled?: boolean;
+    user?: VizuUser;
+    /** Actions to register on construction. You can also call `vizu.addAction(...)` later. */
+    actions?: VizuAction[];
+    /**
+     * Convenience callbacks. These are aliases for `.on('comment:added', ...)` etc.
+     * The event API is preferred for new code.
+     */
+    onCommentAdded?: (c: VizuComment) => void;
+    onCommentRemoved?: (id: string) => void;
+}
+/**
+ * Typed event map. Every event payload is an object (never bare values) so the
+ * shape is forward-compatible.
+ */
+interface VizuEventMap {
+    'enabled': Record<string, never>;
+    'disabled': Record<string, never>;
+    'mounted': Record<string, never>;
+    'unmounted': Record<string, never>;
+    'comment:added': {
+        comment: VizuComment;
+    };
+    'comment:removed': {
+        id: string;
+        comment: VizuComment;
+    };
+    'comment:updated': {
+        comment: VizuComment;
+    };
+    'comments:cleared': {
+        previous: VizuComment[];
+    };
+    'comments:set': {
+        comments: VizuComment[];
+    };
+    'comments:loaded': {
+        comments: VizuComment[];
+    };
+    'element:selected': {
+        target: Element;
+        fingerprint: ElementFingerprint;
+    };
+    'element:deselected': Record<string, never>;
+    'sidebar:opened': Record<string, never>;
+    'sidebar:closed': Record<string, never>;
+    'action:invoked': {
+        id: string;
+    };
+    'user:changed': {
+        user: VizuUser | null;
+    };
+    /**
+     * Emitted once per comment when the lib resolves (or fails to resolve)
+     * its fingerprint against the current DOM. `confidence: 'orphaned'`
+     * means the comment is in the sidebar's orphaned section.
+     */
+    'anchor:resolved': {
+        comment: VizuComment;
+        confidence: MatchConfidence;
+        element: Element | null;
+    };
+}
+type VizuEventName = keyof VizuEventMap;
+type VizuEventHandler<E extends VizuEventName> = (payload: VizuEventMap[E]) => void;
+
+/**
+ * Persist comments to the host page's localStorage. One JSON document per
+ * namespace. Migrations are applied on read.
+ *
+ * v2 per-comment ops are emulated via read-modify-write of the underlying
+ * array — fine for localStorage's <1ms cost. Cloud adapters do real
+ * single-document writes.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    load(namespace: string): Promise<VizuComment[]>;
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+    addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+}
+/**
+ * Stores comments in RAM only — wipes on reload. Useful when the host owns
+ * persistence via events (the integrator listens to `comment:added` and
+ * forwards to its own backend).
+ */
+declare class InMemoryStorageAdapter implements StorageAdapter {
+    private store;
+    load(namespace: string): Promise<VizuComment[]>;
+    addComment(namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+    addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+}
+/**
+ * No-op adapter — never persists. The host hydrates via `setComments` and
+ * listens to events to drive its own storage.
+ */
+declare class NullStorageAdapter implements StorageAdapter {
+    load(): Promise<VizuComment[]>;
+    addComment(): Promise<void>;
+    updateComment(): Promise<VizuComment | null>;
+    removeComment(): Promise<void>;
+    setAll(): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * CloudStorageAdapter — talks to the Vizu hosted backend.
+ *
+ * Lifecycle:
+ *   - Reads are unauthenticated-attempted first (the dashboard's own
+ *     reads are same-origin Clerk session). If the backend says 401, we
+ *     open the popup once and retry.
+ *   - Writes require a host-token. First write opens the popup; the
+ *     resulting JWT is stored in sessionStorage keyed by workspace slug
+ *     and reused for the tab's lifetime (or until `exp` lapses).
+ *
+ * Token storage = sessionStorage (per-tab). Cross-tab is intentional:
+ * a stolen token from one tab can't leak to another via storage events.
+ * The cost is one popup per tab; cheap for the safety win.
+ *
+ * The popup is hosted at `${apiUrl}/connect?workspace=&origin=`. It
+ * handles the Clerk sign-in handshake and posts the token back via
+ * `postMessage` targeted at the host origin (never `*`).
+ */
+interface CloudStorageOptions {
+    /** Workspace slug — required. */
+    workspace: string;
+    /** API base URL (defaults to https://vizu.unhingged.com). */
+    apiUrl?: string;
+    /** Open the sign-in popup automatically on the first auth-needed write. Defaults to true. */
+    autoSignIn?: boolean;
+}
+declare class CloudStorageAdapter implements StorageAdapter {
+    private readonly apiUrl;
+    private readonly workspace;
+    private readonly autoSignIn;
+    /** Cached current-tab token. Mirrored to sessionStorage. */
+    private cachedToken;
+    /** Single-flight: at most one popup at a time. Subsequent requests await this. */
+    private pendingAuth;
+    constructor(opts: CloudStorageOptions);
+    load(_namespace: string): Promise<VizuComment[]>;
+    addComment(_namespace: string, comment: VizuComment): Promise<void>;
+    updateComment(_namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    removeComment(_namespace: string, id: string): Promise<void>;
+    setAll(namespace: string, comments: VizuComment[]): Promise<void>;
+    clear(_namespace: string): Promise<void>;
+    addReply(_namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
+    removeReply(_namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
+    /**
+     * Upload a file as multipart/form-data to the host backend, which
+     * forwards to Vercel Blob server-side. Stays under the 4.5 MB Vercel
+     * function body cap (our own 5 MB attachment cap will be enforced
+     * server-side before that's hit).
+     *
+     * Deliberately doesn't use `@vercel/blob/client`'s direct-upload flow:
+     *   - keeps `@vizu/core` free of any `@vercel/blob` dependency
+     *     (script-tag and local-only consumers don't pull blob code)
+     *   - the multipart path is one round-trip; the direct-upload flow
+     *     is two (signed URL + upload). For attachments capped at 5 MB,
+     *     the savings don't justify the dep cost.
+     */
+    uploadAttachment(_namespace: string, file: File): Promise<Attachment>;
+    getAuthContext(): AuthContext | null;
+    private isExpired;
+    private readStoredToken;
+    private writeStoredToken;
+    private clearStoredToken;
+    private sessionKey;
+    /**
+     * Resolve a valid token, opening the popup if needed.
+     *
+     * Single-flight: simultaneous requests await one popup, not N.
+     * Caller-friendly: throws a Error with `.code === 'auth_canceled'`
+     * if the user closes the popup; hosts can catch this and present
+     * a friendly message instead of a blank failure.
+     */
+    private resolveToken;
+    private openSignInPopup;
+    /**
+     * Perform an authenticated fetch with one-shot retry on 401 (re-opens
+     * the popup if the token expired during the request). 4xx other than
+     * 401 / 404 throw; 5xx throws; 2xx returns.
+     */
+    private fetchAuthed;
+    private parseJson;
+}
+type CloudErrorCode = 'auth_required' | 'auth_canceled' | 'auth_unavailable' | 'popup_blocked' | 'origin_not_allowed' | 'workspace_not_found' | 'http_error';
+interface CloudError extends Error {
+    code: CloudErrorCode;
+    status?: number;
+    body?: unknown;
+}
+
+declare function fingerprint(el: Element): ElementFingerprint;
+/**
+ * Resolve a fingerprint to a live DOM element with a confidence tag.
+ *
+ * Two-phase ladder:
+ *
+ *   **Strong identifiers (short-circuit).** `data-vizu-key` and `#id`
+ *   are host-explicit anchors — if the captured key exists in the DOM
+ *   we trust it 100% and return **exact**. For `data-vizu-key`, the
+ *   *absence* of the captured key is itself evidence: the host marked
+ *   that element explicitly and the mark is gone, so we **orphan**
+ *   without consulting weaker rungs. `id` gets the gentler treatment
+ *   (fall through on miss) because ids get renamed without the element
+ *   itself going away.
+ *
+ *   **Fuzzy rungs vote (Phase 11.4.4 / #135).** When no strong
+ *   identifier resolves, every fuzzy rung (class signature, CSS selector,
+ *   ancestor chain, text snippet) returns its best candidate. We tally
+ *   votes per element and require ≥ 2 rungs to agree on the same target
+ *   before returning a match. 3+ votes → **likely**, 2 votes → **drifted**,
+ *   ≤ 1 vote → **orphaned**.
+ *
+ *   The vote requirement is what catches `element_deleted`: the actual
+ *   element is gone, so each fuzzy rung finds a *different* nearby
+ *   element. Votes scatter, no consensus, orphan. Before this, the
+ *   matcher returned the first rung's hit and confidently mis-anchored
+ *   the comment to a similar element nearby — the false-positive
+ *   surfaced by the Phase 11.4.3 stress harness.
+ */
+declare function findByFingerprint(fp: ElementFingerprint, root?: ParentNode): FingerprintMatch;
+/** Backwards-compat: callers that only need the element. */
+declare function findElementByFingerprint(fp: ElementFingerprint, root?: ParentNode): Element | null;
+declare function fingerprintKey(fp: ElementFingerprint): string;
+/** Short human-readable label for an element, used in `#` reference chips. */
+declare function fingerprintLabel(fp: ElementFingerprint): string;
+
+declare class Vizu {
+    private opts;
+    private parsedShortcut;
+    private storage;
+    private root;
+    private highlighter;
+    private popover;
+    private pill;
+    private sidebar;
+    /** Saved-comment markers: keyed by `${commentId}:${anchorIndex}` */
+    private markers;
+    /** Persistent outlines for commented elements: keyed by fingerprintKey */
+    private outlines;
+    /** Temporary "active anchor" outlines shown while popover is open OR
+     *  while a multi-select session is pending. Stores the fp so we can
+     *  reposition without needing to consult popover/pending state. */
+    private activeAnchorOutlines;
+    /** Transient spotlights rendered on jump (click sidebar item / anchor chip / # ref). */
+    private spotlights;
+    private comments;
+    /**
+     * Best confidence each comment was resolved at on the most recent
+     * marker render. Used by the sidebar to surface orphaned + drifted
+     * comments separately, and exposed publicly via {@link getCommentConfidence}.
+     */
+    private resolvedConfidence;
+    /**
+     * Comment ids the matcher has already re-fingerprinted in this session.
+     * Phase 11.4.4.3 self-healing: when a comment lands as `drifted` and
+     * we have a live element to re-fingerprint, we rewrite the stored
+     * fingerprint so the next load resolves as exact/likely. Tracked
+     * here so the same render loop doesn't re-heal on every redraw.
+     * Cleared on `destroy()`; survives `disable()`/`enable()`.
+     */
+    private selfHealedThisSession;
+    private actions;
+    private user;
+    /** Live-collab module — non-null only when `opts.liveblocks` and `opts.cloud` are both set AND the plan carries `live_collab`. Stays null otherwise. */
+    private liveCollab;
+    private enabled;
+    private rafScheduled;
+    private bus;
+    /** Picker: next element click is consumed as a reference instead of opening a popover. */
+    private picking;
+    private pickingBanner;
+    /** Multi-select state — pending selection NOT yet attached to a popover. */
+    private multiSelectMode;
+    private pendingFingerprints;
+    private pendingTargets;
+    constructor(options?: VizuOptions, _defaultStorage?: 'memory' | 'local');
+    on<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): () => void;
+    off<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
+    setUser(user: VizuUser | null): void;
+    getUser(): VizuUser | null;
+    enable(): void;
+    disable(): void;
+    toggle(): void;
+    isEnabled(): boolean;
+    destroy(): void;
+    addAction(action: VizuAction): void;
+    removeAction(id: string): void;
+    getActions(): VizuAction[];
+    invokeAction(id: string): void;
+    getComments(): VizuComment[];
+    setComments(comments: VizuComment[], opts?: {
+        persist?: boolean;
+    }): Promise<void>;
+    /**
+     * Patch a single comment. Used by status changes (resolve / reopen),
+     * future threading mutations, etc. Returns the updated comment or
+     * `null` if no comment with that id exists.
+     */
+    updateComment(id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
+    /** Auth context surfaced by the active storage adapter, if any (cloud adapters set this). */
+    getAuthContext(): AuthContext | null;
+    /**
+     * Re-fingerprint a comment's anchors against the live DOM and persist.
+     * Called from the render loop when a comment lands `drifted` with a
+     * matched element — rewriting the fingerprint here makes the next
+     * load resolve via a cleaner rung (data-vizu-key / id / class) instead
+     * of falling back to fuzzy text.
+     *
+     * Marks the comment as healed for this session so the same render
+     * doesn't kick the same write twice. Failures are logged; the next
+     * page load gets another chance.
+     */
+    private selfHealComment;
+    /**
+     * Resolution confidence for a comment as of the last marker render.
+     * `'orphaned'` means the comment's fingerprints didn't resolve to any
+     * live DOM element — the sidebar surfaces it in the orphaned section.
+     * Returns `undefined` for unknown comment ids.
+     */
+    getCommentConfidence(commentId: string): MatchConfidence | undefined;
+    /** Returns the full Map of comment id → confidence. Useful for the dashboard. */
+    getResolvedConfidence(): Map<string, MatchConfidence>;
+    /**
+     * True iff the active storage adapter implements `uploadAttachment`.
+     * The popover hides its upload UI when this returns false (local /
+     * memory modes don't support attachments today).
+     */
+    canUploadAttachments(): boolean;
+    /**
+     * Upload an attachment via the active storage adapter. Throws if the
+     * adapter doesn't implement uploads. Caller is responsible for adding
+     * the returned Attachment to a comment (popover does this automatically).
+     */
+    uploadAttachment(file: File): Promise<Attachment>;
+    /**
+     * Append a reply to a comment. Returns the parent comment or null if
+     * the comment id doesn't exist. Routes through the storage adapter's
+     * native `addReply` when available, falling back to an updateComment
+     * patch for adapters that don't implement reply ops.
+     */
+    addReply(commentId: string, text: string, mentions?: string[]): Promise<VizuComment | null>;
+    /**
+     * Remove a reply from a comment. Returns the parent comment or null
+     * if either id is unknown.
+     */
+    removeReply(commentId: string, replyId: string): Promise<VizuComment | null>;
+    clearAll(): Promise<void>;
+    /** Toggle multi-select mode. When on, plain clicks accumulate into the selection. */
+    toggleMultiSelectMode(): void;
+    /** Discard the in-progress selection AND exit multi-select mode. */
+    clearSelection(): void;
+    /** Open the popover anchored to the current pending selection so the user can write the comment. */
+    commitSelection(): void;
+    getSelection(): ElementFingerprint[];
+    private loadComments;
+    /**
+     * Subscribe to remote-change notifications from the active storage
+     * adapter (cloud adapters only). Local adapters never emit. The
+     * subscription is torn down on `destroy()`.
+     */
+    private unsubscribeStorage;
+    private subscribeStorage;
+    private deferred;
+    private onKeyDown;
+    private mount;
+    private unmount;
+    private onElementClick;
+    private openPopoverFor;
+    private closePopover;
+    private addToSelection;
+    private commentsForElement;
+    private addCommentFromPopover;
+    private removeComment;
+    private refreshUi;
+    private toggleSidebar;
+    private closeSidebar;
+    startPicking(onSelect: (fp: ElementFingerprint) => void, onCancel: () => void): void;
+    cancelPicking(): void;
+    private showPickingBanner;
+    private hidePickingBanner;
+    private jumpToReference;
+    jumpToFingerprint(fp: ElementFingerprint): void;
+    private renderAllMarkers;
+    /** Pulse outlines of OTHER elements that share a multi-anchor comment with this one. */
+    private pulseRelatedElements;
+    private positionOutline;
+    private positionMarker;
+    private syncActiveAnchorOutlines;
+    private clearActiveAnchorOutlines;
+    private scheduleReposition;
+    private actionContext;
+    snapshotHtml(): string;
+    private copyToClipboard;
+}
+
+export { type ActionContext, type Attachment, type AuthContext, type CloudError, CloudStorageAdapter, type ElementFingerprint, InMemoryStorageAdapter, LocalStorageAdapter, type MatchConfidence, NullStorageAdapter, type Reply, SCHEMA_VERSION, type StorageAdapter, type StorageOption, Vizu, type VizuAction, type VizuCloudOptions, type VizuComment, type VizuEventHandler, type VizuEventName, type VizuOptions, type VizuUser, findByFingerprint, findElementByFingerprint, fingerprint, fingerprintKey, fingerprintLabel };