@unhingged/vizu-core 0.1.23 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -168,8 +168,8 @@ interface VizuComment {
168
168
  fingerprintsRefreshedAt?: number | null;
169
169
  }
170
170
  /**
171
- * Storage event emitted by adapters that support push (cloud adapters).
172
- * Local / memory adapters never emit these.
171
+ * Storage event emitted by adapters that support push notifications of
172
+ * remote changes.
173
173
  */
174
174
  type StorageEvent = {
175
175
  type: 'added';
@@ -198,13 +198,14 @@ interface AuthContext {
198
198
  expiresAt?: string;
199
199
  }
200
200
  /**
201
- * Storage contract v2. Per-comment operations replace v1's full-array
202
- * `save(comments[])`. Cloud-friendly: each mutation is one network call,
203
- * the adapter can do optimistic-concurrency / conflict resolution
204
- * without re-shipping the whole list.
201
+ * Storage contract implemented by {@link CloudStorageAdapter} the only
202
+ * adapter Vizu constructs. The type stays exported because it is
203
+ * load-bearing for CloudStorageAdapter's public typing; the interface is
204
+ * per-comment so each mutation is one network call and the adapter can do
205
+ * optimistic-concurrency without re-shipping the whole list.
205
206
  *
206
- * Hosts that wrote against v1 (`load / save / clear`) are still accepted —
207
- * see `wrapV1Adapter` in `storage.ts` for the back-compat shim.
207
+ * The `namespace` parameter is the workspace slug (Vizu passes
208
+ * `options.workspace` through).
208
209
  *
209
210
  * Reply ops (`addReply` / `removeReply`) are optional: adapters that don't
210
211
  * implement them fall back to `updateComment` with a manually-patched
@@ -239,16 +240,6 @@ interface StorageAdapter {
239
240
  /** Optional auth context (cloud adapters). */
240
241
  getAuthContext?(): AuthContext | null;
241
242
  }
242
- /**
243
- * Legacy v1 adapter shape. Kept exported so hosts can still type their
244
- * existing adapters; the resolver wraps them automatically.
245
- */
246
- interface StorageAdapterV1 {
247
- load(namespace: string): Promise<VizuComment[]>;
248
- save(namespace: string, comments: VizuComment[]): Promise<void>;
249
- clear(namespace: string): Promise<void>;
250
- }
251
- type StorageOption = 'local' | 'memory' | 'none' | StorageAdapter | StorageAdapterV1;
252
243
  /** Context handed to every action's onClick. Has the data and the side-effect helpers. */
253
244
  interface ActionContext {
254
245
  comments: VizuComment[];
@@ -276,14 +267,12 @@ interface VizuAction {
276
267
  commentsCount: number;
277
268
  }) => boolean;
278
269
  }
279
- /**
280
- * Cloud connection options. When set, the resolver constructs the built-in
281
- * CloudStorageAdapter (Phase 3) and uses it instead of `storage`. If both
282
- * `cloud` and `storage` are provided, `cloud` wins and a `console.warn`
283
- * is emitted at construction time.
284
- */
285
- interface VizuCloudOptions {
286
- /** Workspace slug. Required. Created in the Vizu dashboard. */
270
+ interface VizuOptions {
271
+ /**
272
+ * Workspace slug, created in the Vizu dashboard. Required every Vizu
273
+ * instance connects to a cloud workspace; comments are private to it and
274
+ * readable/writable by its members after sign-in.
275
+ */
287
276
  workspace: string;
288
277
  /** Override the API base URL. Defaults to `'https://vizu.unhingged.com'`. */
289
278
  apiUrl?: string;
@@ -292,21 +281,8 @@ interface VizuCloudOptions {
292
281
  * unauthenticated user. Defaults to `true`.
293
282
  */
294
283
  autoSignIn?: boolean;
295
- }
296
- interface VizuOptions {
297
284
  shortcut?: string;
298
- namespace?: string;
299
285
  pageVersion?: string;
300
- /**
301
- * Storage strategy. Default behavior:
302
- * - **Programmatic** (`new Vizu()`): defaults to `'memory'`; host should listen to events to persist.
303
- * - **Script-tag auto-init**: defaults to `'local'` for zero-config drop-in (override via `data-storage="memory"` or `data-storage="none"`).
304
- *
305
- * When `cloud` is set this option is ignored.
306
- */
307
- storage?: StorageOption;
308
- /** Cloud workspace connection. Overrides `storage`. See {@link VizuCloudOptions}. */
309
- cloud?: VizuCloudOptions;
310
286
  ignoreSelectors?: string[];
311
287
  accent?: string;
312
288
  startEnabled?: boolean;
@@ -322,9 +298,8 @@ interface VizuOptions {
322
298
  /**
323
299
  * Optional override for the @ mention picker's member list. When set,
324
300
  * the popover dropdown calls this instead of going to the cloud
325
- * `/api/workspaces/[slug]/mentionable` route. Useful for non-cloud
326
- * hosts (local / memory storage) that still want @-mentions, and for
327
- * tests / playgrounds that need a static teammate list.
301
+ * `/api/workspaces/[slug]/mentionable` route. Useful for tests and
302
+ * playgrounds that need a static teammate list.
328
303
  *
329
304
  * Return an empty array to suppress the dropdown.
330
305
  */
@@ -385,53 +360,6 @@ interface VizuEventMap {
385
360
  type VizuEventName = keyof VizuEventMap;
386
361
  type VizuEventHandler<E extends VizuEventName> = (payload: VizuEventMap[E]) => void;
387
362
 
388
- /**
389
- * Persist comments to the host page's localStorage. One JSON document per
390
- * namespace. Migrations are applied on read.
391
- *
392
- * v2 per-comment ops are emulated via read-modify-write of the underlying
393
- * array — fine for localStorage's <1ms cost. Cloud adapters do real
394
- * single-document writes.
395
- */
396
- declare class LocalStorageAdapter implements StorageAdapter {
397
- load(namespace: string): Promise<VizuComment[]>;
398
- addComment(namespace: string, comment: VizuComment): Promise<void>;
399
- updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
400
- removeComment(namespace: string, id: string): Promise<void>;
401
- setAll(namespace: string, comments: VizuComment[]): Promise<void>;
402
- clear(namespace: string): Promise<void>;
403
- addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
404
- removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
405
- }
406
- /**
407
- * Stores comments in RAM only — wipes on reload. Useful when the host owns
408
- * persistence via events (the integrator listens to `comment:added` and
409
- * forwards to its own backend).
410
- */
411
- declare class InMemoryStorageAdapter implements StorageAdapter {
412
- private store;
413
- load(namespace: string): Promise<VizuComment[]>;
414
- addComment(namespace: string, comment: VizuComment): Promise<void>;
415
- updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
416
- removeComment(namespace: string, id: string): Promise<void>;
417
- setAll(namespace: string, comments: VizuComment[]): Promise<void>;
418
- clear(namespace: string): Promise<void>;
419
- addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
420
- removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
421
- }
422
- /**
423
- * No-op adapter — never persists. The host hydrates via `setComments` and
424
- * listens to events to drive its own storage.
425
- */
426
- declare class NullStorageAdapter implements StorageAdapter {
427
- load(): Promise<VizuComment[]>;
428
- addComment(): Promise<void>;
429
- updateComment(): Promise<VizuComment | null>;
430
- removeComment(): Promise<void>;
431
- setAll(): Promise<void>;
432
- clear(): Promise<void>;
433
- }
434
-
435
363
  /**
436
364
  * CloudStorageAdapter — talks to the Vizu hosted backend.
437
365
  *
@@ -631,6 +559,15 @@ declare class Vizu {
631
559
  private opts;
632
560
  private parsedShortcut;
633
561
  private storage;
562
+ /**
563
+ * The cloud adapter when this instance runs in the normal cloud mode;
564
+ * null only under the internal storage override (tests / storybook).
565
+ * Auth-gated behavior (mount gate, write gate, sign-in kicks) branches
566
+ * on this instead of `instanceof` checks against `this.storage`.
567
+ */
568
+ private cloud;
569
+ /** Workspace slug passed to the storage adapter as its namespace argument. */
570
+ private ns;
634
571
  private root;
635
572
  private highlighter;
636
573
  private popover;
@@ -690,7 +627,7 @@ declare class Vizu {
690
627
  private multiSelectMode;
691
628
  private pendingFingerprints;
692
629
  private pendingTargets;
693
- constructor(options?: VizuOptions, _defaultStorage?: 'memory' | 'local');
630
+ constructor(options: VizuOptions, /** @internal tests/storybook only */ storageOverride?: StorageAdapter);
694
631
  on<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): () => void;
695
632
  off<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
696
633
  setUser(user: VizuUser | null): void;
@@ -703,26 +640,26 @@ declare class Vizu {
703
640
  * Resolution order:
704
641
  * 1. `options.mentionable` if provided — host-supplied static or
705
642
  * custom resolver. Wins over everything else.
706
- * 2. Cloud adapter's API call if running cloud mode.
707
- * 3. Empty array (non-cloud, no override).
643
+ * 2. The workspace's mentionable-members API.
644
+ * 3. Empty array (internal storage override, no override).
708
645
  */
709
646
  searchMentionable(): Promise<MentionableUser[]>;
710
647
  /**
711
648
  * Whether the full Vizu UI (pill, highlighter, markers, popover) can
712
- * be mounted right now. Cloud-mode workspaces hold off until the
713
- * user is signed in; non-cloud usage (local / memory storage) has no
714
- * auth concept and mounts immediately. Re-checked from `enable()`
715
- * and from `setUser()` so that the moment auth resolves, the UI
716
- * appears without the user needing to press the shortcut again.
649
+ * be mounted right now: not until the user is signed in to the
650
+ * workspace. Re-checked from `enable()` and from `setUser()` so that
651
+ * the moment auth resolves, the UI appears without the user needing
652
+ * to press the shortcut again. (Under the internal storage override
653
+ * there is no auth concept and the UI mounts immediately.)
717
654
  */
718
655
  private shouldMount;
719
656
  /**
720
- * Cloud-mode write gate. Every entry point that creates or modifies a
721
- * comment first checks that we have a known user. Without one, the
722
- * write would land as Anonymous (or 401 on the backend) — neither is
723
- * the right UX. So we re-trigger the sign-in popup and refuse the
724
- * action. The user signs in, this.user gets set via onAuthChanged,
725
- * then they can retry the click themselves.
657
+ * Write gate. Every entry point that creates or modifies a comment
658
+ * first checks that we have a known user. Without one, the write
659
+ * would land as Anonymous (or 401 on the backend) — neither is the
660
+ * right UX. So we re-trigger the sign-in popup and refuse the action.
661
+ * The user signs in, this.user gets set via onAuthChanged, then they
662
+ * can retry the click themselves.
726
663
  *
727
664
  * Returns true when the caller may proceed.
728
665
  */
@@ -732,12 +669,12 @@ declare class Vizu {
732
669
  toggle(): void;
733
670
  isEnabled(): boolean;
734
671
  /**
735
- * Kick the cloud sign-in flow. Call this alongside `enable()` from an
672
+ * Kick the sign-in flow. Call this alongside `enable()` from an
736
673
  * explicit user gesture — a host-rendered launcher button, a menu item —
737
- * so cloud-mode users get the sign-in popup immediately instead of only
738
- * after clicking an element. The keyboard shortcut goes through this
739
- * same path. No-op outside cloud mode, when already signed in, or when
740
- * the workspace has already denied access this session.
674
+ * so users get the sign-in popup immediately instead of only after
675
+ * clicking an element. The keyboard shortcut goes through this same
676
+ * path. No-op when already signed in, when the workspace has already
677
+ * denied access this session, or under the internal storage override.
741
678
  */
742
679
  requestAuth(): void;
743
680
  destroy(): void;
@@ -780,8 +717,8 @@ declare class Vizu {
780
717
  getResolvedConfidence(): Map<string, MatchConfidence>;
781
718
  /**
782
719
  * True iff the active storage adapter implements `uploadAttachment`.
783
- * The popover hides its upload UI when this returns false (local /
784
- * memory modes don't support attachments today).
720
+ * The popover hides its upload UI when this returns false (only the
721
+ * internal offline adapters lack uploads).
785
722
  */
786
723
  canUploadAttachments(): boolean;
787
724
  /**
@@ -813,8 +750,8 @@ declare class Vizu {
813
750
  private loadComments;
814
751
  /**
815
752
  * Subscribe to remote-change notifications from the active storage
816
- * adapter (cloud adapters only). Local adapters never emit. The
817
- * subscription is torn down on `destroy()`.
753
+ * adapter, when it implements `subscribe` (none do today — kept as
754
+ * the hook realtime lands on). Torn down on `destroy()`.
818
755
  */
819
756
  private unsubscribeStorage;
820
757
  private subscribeStorage;
@@ -858,4 +795,4 @@ declare class Vizu {
858
795
  private copyToClipboard;
859
796
  }
860
797
 
861
- 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 };
798
+ export { type ActionContext, type Attachment, type AuthContext, type CloudError, CloudStorageAdapter, type ElementFingerprint, type MatchConfidence, type Reply, SCHEMA_VERSION, type StorageAdapter, Vizu, type VizuAction, type VizuComment, type VizuEventHandler, type VizuEventName, type VizuOptions, type VizuUser, findByFingerprint, findElementByFingerprint, fingerprint, fingerprintKey, fingerprintLabel };
package/dist/index.d.ts CHANGED
@@ -168,8 +168,8 @@ interface VizuComment {
168
168
  fingerprintsRefreshedAt?: number | null;
169
169
  }
170
170
  /**
171
- * Storage event emitted by adapters that support push (cloud adapters).
172
- * Local / memory adapters never emit these.
171
+ * Storage event emitted by adapters that support push notifications of
172
+ * remote changes.
173
173
  */
174
174
  type StorageEvent = {
175
175
  type: 'added';
@@ -198,13 +198,14 @@ interface AuthContext {
198
198
  expiresAt?: string;
199
199
  }
200
200
  /**
201
- * Storage contract v2. Per-comment operations replace v1's full-array
202
- * `save(comments[])`. Cloud-friendly: each mutation is one network call,
203
- * the adapter can do optimistic-concurrency / conflict resolution
204
- * without re-shipping the whole list.
201
+ * Storage contract implemented by {@link CloudStorageAdapter} the only
202
+ * adapter Vizu constructs. The type stays exported because it is
203
+ * load-bearing for CloudStorageAdapter's public typing; the interface is
204
+ * per-comment so each mutation is one network call and the adapter can do
205
+ * optimistic-concurrency without re-shipping the whole list.
205
206
  *
206
- * Hosts that wrote against v1 (`load / save / clear`) are still accepted —
207
- * see `wrapV1Adapter` in `storage.ts` for the back-compat shim.
207
+ * The `namespace` parameter is the workspace slug (Vizu passes
208
+ * `options.workspace` through).
208
209
  *
209
210
  * Reply ops (`addReply` / `removeReply`) are optional: adapters that don't
210
211
  * implement them fall back to `updateComment` with a manually-patched
@@ -239,16 +240,6 @@ interface StorageAdapter {
239
240
  /** Optional auth context (cloud adapters). */
240
241
  getAuthContext?(): AuthContext | null;
241
242
  }
242
- /**
243
- * Legacy v1 adapter shape. Kept exported so hosts can still type their
244
- * existing adapters; the resolver wraps them automatically.
245
- */
246
- interface StorageAdapterV1 {
247
- load(namespace: string): Promise<VizuComment[]>;
248
- save(namespace: string, comments: VizuComment[]): Promise<void>;
249
- clear(namespace: string): Promise<void>;
250
- }
251
- type StorageOption = 'local' | 'memory' | 'none' | StorageAdapter | StorageAdapterV1;
252
243
  /** Context handed to every action's onClick. Has the data and the side-effect helpers. */
253
244
  interface ActionContext {
254
245
  comments: VizuComment[];
@@ -276,14 +267,12 @@ interface VizuAction {
276
267
  commentsCount: number;
277
268
  }) => boolean;
278
269
  }
279
- /**
280
- * Cloud connection options. When set, the resolver constructs the built-in
281
- * CloudStorageAdapter (Phase 3) and uses it instead of `storage`. If both
282
- * `cloud` and `storage` are provided, `cloud` wins and a `console.warn`
283
- * is emitted at construction time.
284
- */
285
- interface VizuCloudOptions {
286
- /** Workspace slug. Required. Created in the Vizu dashboard. */
270
+ interface VizuOptions {
271
+ /**
272
+ * Workspace slug, created in the Vizu dashboard. Required every Vizu
273
+ * instance connects to a cloud workspace; comments are private to it and
274
+ * readable/writable by its members after sign-in.
275
+ */
287
276
  workspace: string;
288
277
  /** Override the API base URL. Defaults to `'https://vizu.unhingged.com'`. */
289
278
  apiUrl?: string;
@@ -292,21 +281,8 @@ interface VizuCloudOptions {
292
281
  * unauthenticated user. Defaults to `true`.
293
282
  */
294
283
  autoSignIn?: boolean;
295
- }
296
- interface VizuOptions {
297
284
  shortcut?: string;
298
- namespace?: string;
299
285
  pageVersion?: string;
300
- /**
301
- * Storage strategy. Default behavior:
302
- * - **Programmatic** (`new Vizu()`): defaults to `'memory'`; host should listen to events to persist.
303
- * - **Script-tag auto-init**: defaults to `'local'` for zero-config drop-in (override via `data-storage="memory"` or `data-storage="none"`).
304
- *
305
- * When `cloud` is set this option is ignored.
306
- */
307
- storage?: StorageOption;
308
- /** Cloud workspace connection. Overrides `storage`. See {@link VizuCloudOptions}. */
309
- cloud?: VizuCloudOptions;
310
286
  ignoreSelectors?: string[];
311
287
  accent?: string;
312
288
  startEnabled?: boolean;
@@ -322,9 +298,8 @@ interface VizuOptions {
322
298
  /**
323
299
  * Optional override for the @ mention picker's member list. When set,
324
300
  * the popover dropdown calls this instead of going to the cloud
325
- * `/api/workspaces/[slug]/mentionable` route. Useful for non-cloud
326
- * hosts (local / memory storage) that still want @-mentions, and for
327
- * tests / playgrounds that need a static teammate list.
301
+ * `/api/workspaces/[slug]/mentionable` route. Useful for tests and
302
+ * playgrounds that need a static teammate list.
328
303
  *
329
304
  * Return an empty array to suppress the dropdown.
330
305
  */
@@ -385,53 +360,6 @@ interface VizuEventMap {
385
360
  type VizuEventName = keyof VizuEventMap;
386
361
  type VizuEventHandler<E extends VizuEventName> = (payload: VizuEventMap[E]) => void;
387
362
 
388
- /**
389
- * Persist comments to the host page's localStorage. One JSON document per
390
- * namespace. Migrations are applied on read.
391
- *
392
- * v2 per-comment ops are emulated via read-modify-write of the underlying
393
- * array — fine for localStorage's <1ms cost. Cloud adapters do real
394
- * single-document writes.
395
- */
396
- declare class LocalStorageAdapter implements StorageAdapter {
397
- load(namespace: string): Promise<VizuComment[]>;
398
- addComment(namespace: string, comment: VizuComment): Promise<void>;
399
- updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
400
- removeComment(namespace: string, id: string): Promise<void>;
401
- setAll(namespace: string, comments: VizuComment[]): Promise<void>;
402
- clear(namespace: string): Promise<void>;
403
- addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
404
- removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
405
- }
406
- /**
407
- * Stores comments in RAM only — wipes on reload. Useful when the host owns
408
- * persistence via events (the integrator listens to `comment:added` and
409
- * forwards to its own backend).
410
- */
411
- declare class InMemoryStorageAdapter implements StorageAdapter {
412
- private store;
413
- load(namespace: string): Promise<VizuComment[]>;
414
- addComment(namespace: string, comment: VizuComment): Promise<void>;
415
- updateComment(namespace: string, id: string, patch: Partial<VizuComment>): Promise<VizuComment | null>;
416
- removeComment(namespace: string, id: string): Promise<void>;
417
- setAll(namespace: string, comments: VizuComment[]): Promise<void>;
418
- clear(namespace: string): Promise<void>;
419
- addReply(namespace: string, commentId: string, reply: Reply): Promise<VizuComment | null>;
420
- removeReply(namespace: string, commentId: string, replyId: string): Promise<VizuComment | null>;
421
- }
422
- /**
423
- * No-op adapter — never persists. The host hydrates via `setComments` and
424
- * listens to events to drive its own storage.
425
- */
426
- declare class NullStorageAdapter implements StorageAdapter {
427
- load(): Promise<VizuComment[]>;
428
- addComment(): Promise<void>;
429
- updateComment(): Promise<VizuComment | null>;
430
- removeComment(): Promise<void>;
431
- setAll(): Promise<void>;
432
- clear(): Promise<void>;
433
- }
434
-
435
363
  /**
436
364
  * CloudStorageAdapter — talks to the Vizu hosted backend.
437
365
  *
@@ -631,6 +559,15 @@ declare class Vizu {
631
559
  private opts;
632
560
  private parsedShortcut;
633
561
  private storage;
562
+ /**
563
+ * The cloud adapter when this instance runs in the normal cloud mode;
564
+ * null only under the internal storage override (tests / storybook).
565
+ * Auth-gated behavior (mount gate, write gate, sign-in kicks) branches
566
+ * on this instead of `instanceof` checks against `this.storage`.
567
+ */
568
+ private cloud;
569
+ /** Workspace slug passed to the storage adapter as its namespace argument. */
570
+ private ns;
634
571
  private root;
635
572
  private highlighter;
636
573
  private popover;
@@ -690,7 +627,7 @@ declare class Vizu {
690
627
  private multiSelectMode;
691
628
  private pendingFingerprints;
692
629
  private pendingTargets;
693
- constructor(options?: VizuOptions, _defaultStorage?: 'memory' | 'local');
630
+ constructor(options: VizuOptions, /** @internal tests/storybook only */ storageOverride?: StorageAdapter);
694
631
  on<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): () => void;
695
632
  off<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
696
633
  setUser(user: VizuUser | null): void;
@@ -703,26 +640,26 @@ declare class Vizu {
703
640
  * Resolution order:
704
641
  * 1. `options.mentionable` if provided — host-supplied static or
705
642
  * custom resolver. Wins over everything else.
706
- * 2. Cloud adapter's API call if running cloud mode.
707
- * 3. Empty array (non-cloud, no override).
643
+ * 2. The workspace's mentionable-members API.
644
+ * 3. Empty array (internal storage override, no override).
708
645
  */
709
646
  searchMentionable(): Promise<MentionableUser[]>;
710
647
  /**
711
648
  * Whether the full Vizu UI (pill, highlighter, markers, popover) can
712
- * be mounted right now. Cloud-mode workspaces hold off until the
713
- * user is signed in; non-cloud usage (local / memory storage) has no
714
- * auth concept and mounts immediately. Re-checked from `enable()`
715
- * and from `setUser()` so that the moment auth resolves, the UI
716
- * appears without the user needing to press the shortcut again.
649
+ * be mounted right now: not until the user is signed in to the
650
+ * workspace. Re-checked from `enable()` and from `setUser()` so that
651
+ * the moment auth resolves, the UI appears without the user needing
652
+ * to press the shortcut again. (Under the internal storage override
653
+ * there is no auth concept and the UI mounts immediately.)
717
654
  */
718
655
  private shouldMount;
719
656
  /**
720
- * Cloud-mode write gate. Every entry point that creates or modifies a
721
- * comment first checks that we have a known user. Without one, the
722
- * write would land as Anonymous (or 401 on the backend) — neither is
723
- * the right UX. So we re-trigger the sign-in popup and refuse the
724
- * action. The user signs in, this.user gets set via onAuthChanged,
725
- * then they can retry the click themselves.
657
+ * Write gate. Every entry point that creates or modifies a comment
658
+ * first checks that we have a known user. Without one, the write
659
+ * would land as Anonymous (or 401 on the backend) — neither is the
660
+ * right UX. So we re-trigger the sign-in popup and refuse the action.
661
+ * The user signs in, this.user gets set via onAuthChanged, then they
662
+ * can retry the click themselves.
726
663
  *
727
664
  * Returns true when the caller may proceed.
728
665
  */
@@ -732,12 +669,12 @@ declare class Vizu {
732
669
  toggle(): void;
733
670
  isEnabled(): boolean;
734
671
  /**
735
- * Kick the cloud sign-in flow. Call this alongside `enable()` from an
672
+ * Kick the sign-in flow. Call this alongside `enable()` from an
736
673
  * explicit user gesture — a host-rendered launcher button, a menu item —
737
- * so cloud-mode users get the sign-in popup immediately instead of only
738
- * after clicking an element. The keyboard shortcut goes through this
739
- * same path. No-op outside cloud mode, when already signed in, or when
740
- * the workspace has already denied access this session.
674
+ * so users get the sign-in popup immediately instead of only after
675
+ * clicking an element. The keyboard shortcut goes through this same
676
+ * path. No-op when already signed in, when the workspace has already
677
+ * denied access this session, or under the internal storage override.
741
678
  */
742
679
  requestAuth(): void;
743
680
  destroy(): void;
@@ -780,8 +717,8 @@ declare class Vizu {
780
717
  getResolvedConfidence(): Map<string, MatchConfidence>;
781
718
  /**
782
719
  * True iff the active storage adapter implements `uploadAttachment`.
783
- * The popover hides its upload UI when this returns false (local /
784
- * memory modes don't support attachments today).
720
+ * The popover hides its upload UI when this returns false (only the
721
+ * internal offline adapters lack uploads).
785
722
  */
786
723
  canUploadAttachments(): boolean;
787
724
  /**
@@ -813,8 +750,8 @@ declare class Vizu {
813
750
  private loadComments;
814
751
  /**
815
752
  * Subscribe to remote-change notifications from the active storage
816
- * adapter (cloud adapters only). Local adapters never emit. The
817
- * subscription is torn down on `destroy()`.
753
+ * adapter, when it implements `subscribe` (none do today — kept as
754
+ * the hook realtime lands on). Torn down on `destroy()`.
818
755
  */
819
756
  private unsubscribeStorage;
820
757
  private subscribeStorage;
@@ -858,4 +795,4 @@ declare class Vizu {
858
795
  private copyToClipboard;
859
796
  }
860
797
 
861
- 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 };
798
+ export { type ActionContext, type Attachment, type AuthContext, type CloudError, CloudStorageAdapter, type ElementFingerprint, type MatchConfidence, type Reply, SCHEMA_VERSION, type StorageAdapter, Vizu, type VizuAction, type VizuComment, type VizuEventHandler, type VizuEventName, type VizuOptions, type VizuUser, findByFingerprint, findElementByFingerprint, fingerprint, fingerprintKey, fingerprintLabel };