@pageloop/client 0.5.0

package/dist/PageLoop.js

@@ -0,0 +1,1092 @@
+import { ERROR_CODES } from '@pageloop/shared';
+import { errorCode } from './errorCode.js';
+import { ApiClient } from './ApiClient.js';
+import { CommentEngine } from './CommentEngine.js';
+import { PageTracker } from './PageTracker.js';
+import { EventBus } from './EventBus.js';
+import { IdbCache } from './IdbCache.js';
+import { resolveInitialToken, SESSION_TOKEN_KEY } from './auth/resolveInitialToken.js';
+import { BrowserNotifications } from './notifications/BrowserNotifications.js';
+import { safeStorage } from './safeStorage.js';
+/**
+ * localStorage key for the cached `ProjectSettings` blob. Keyed per
+ * project so multiple PageLoop widgets on the same origin don't
+ * stomp each other. The cache is read synchronously on init — that's
+ * the whole point: we paint the toolbar + sidebar in their final
+ * position before bootstrap returns.
+ */
+const SETTINGS_CACHE_PREFIX = 'pl_config:';
+const PROJECT_CACHE_PREFIX = 'pl_project:';
+const USER_SESSION_CACHE_PREFIX = 'pl_widget_user:';
+/** Min gap between focus-driven session re-resolves (see `onVisible`). */
+const SESSION_REFRESH_THROTTLE_MS = 60_000;
+function readCachedSettings(projectId) {
+    // safeStorage swallows SecurityError / private-mode throws + falls back
+    // to an in-memory map; the try/catch here is purely for the JSON.parse.
+    const raw = safeStorage.getItem(SETTINGS_CACHE_PREFIX + projectId);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedSettings(projectId, settings) {
+    safeStorage.setItem(SETTINGS_CACHE_PREFIX + projectId, JSON.stringify(settings));
+}
+/**
+ * Cache the full Project object so the renderer can mount on first
+ * paint without waiting for the bootstrap round-trip. Validated on
+ * read — a partial / malformed cache returns null so we fall back to
+ * the slow-path mount-after-bootstrap.
+ *
+ * Separate from the settings cache because settings get reconciled
+ * key-by-key (and emit `config:changed` for hot reload), whereas the
+ * Project object is a static identity blob — name, slug, ids — that
+ * the renderer reads through the `project()` getter.
+ */
+function readCachedProject(projectId) {
+    const raw = safeStorage.getItem(PROJECT_CACHE_PREFIX + projectId);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        // Defensive: a malformed cache (truncated, schema-drift) would
+        // crash the renderer's getters on optimistic paint. Require the
+        // minimum keys the mount path reads before trusting it.
+        if (!parsed.id || !parsed.slug)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedProject(projectId, project) {
+    safeStorage.setItem(PROJECT_CACHE_PREFIX + projectId, JSON.stringify(project));
+}
+function readCachedUserSession(projectId) {
+    const raw = safeStorage.getItem(USER_SESSION_CACHE_PREFIX + projectId);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        // Defensive: require the role to be set; a malformed blob (truncated
+        // JSON, schema drift) returns null so the constructor falls back to
+        // the anonymous default rather than rendering with garbage.
+        if (!parsed || typeof parsed.role !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedUserSession(projectId, value) {
+    safeStorage.setItem(USER_SESSION_CACHE_PREFIX + projectId, JSON.stringify(value));
+}
+function clearCachedUserSession(projectId) {
+    safeStorage.removeItem(USER_SESSION_CACHE_PREFIX + projectId);
+}
+/**
+ * Public entry point. Composes ApiClient + PageTracker + CommentEngine + the
+ * provided UIRenderer, and runs the bootstrap → mount → subscribe lifecycle.
+ *
+ * Each framework wrapper (vanilla, react, preact, solid) instantiates this
+ * class internally and wires its own renderer into `deps.renderer`.
+ */
+export class PageLoop {
+    config;
+    bus;
+    api;
+    tracker;
+    comments;
+    cache;
+    /** OS-level notification surface — listens for server-pushed
+     *  `notification.show` events and surfaces them via the standard
+     *  Web Notification API when the user has granted permission.
+     *  Permission is requested explicitly from the settings UI; this
+     *  manager never prompts silently. */
+    notifications;
+    renderer;
+    project = null;
+    currentPage = null;
+    /** Currently authenticated user, populated from bootstrap. */
+    currentUser = null;
+    /** Current user's role in the project; bootstrap doesn't return this directly,
+     *  so we infer from `user.platformRole === 'superadmin'` || comment-create
+     *  succeeded. For v1 we ask the server explicitly only when needed; the
+     *  conservative default for new users is 'commenter' (most common case). */
+    currentRole = 'anonymous';
+    /** Signed-in user's preferred bubble colour (`#rrggbb`), resolved by the
+     *  server at bootstrap from their account `appearance` settings. Null when
+     *  anonymous or unset. Surfaced to the renderer via the `bubbleColor()`
+     *  dep + kept fresh when the user recolours from the widget settings
+     *  panel (the `bubbles:recolor` bus subscription below). */
+    currentBubbleColor = null;
+    /** Wall-clock of the last successful bootstrap — throttles the
+     *  focus-driven session auto-refresh (`onVisible`). */
+    lastBootstrapAt = 0;
+    /** Guard so the visibilitychange listener is wired exactly once. */
+    visibilityWired = false;
+    /** Phase 2 subscriptions — wired by `runPhase2()`, dropped by
+     *  `tearDownPhase2()`. The always-on `projects.updated` listener
+     *  lives separately on `offProjectUpdated` so it survives transitions. */
+    offHandlers = [];
+    /** Always-on subscription to `projects.updated`. Survives phase 2
+     *  teardown so a disabled-then-enabled cycle can wake back up. */
+    offProjectUpdated = null;
+    /** Always-on subscription to `bubbles:recolor` (widget settings panel).
+     *  Keeps `currentBubbleColor` in sync so the renderer's `bubbleColor()`
+     *  dep — and thus the colour picker on reopen — reflects the live value
+     *  rather than the stale bootstrap one. */
+    offBubbleRecolor = null;
+    /**
+     * Tracks whether the user-facing widget (Phase 2) is currently
+     * mounted. The master kill-switch `behavior.enabled` (default true)
+     * gates this — when false, Phase 2 stays down: no renderer, no
+     * WebSocket, no event subscriptions, no DOM listeners on the host
+     * page. Phase 1 (bootstrap + cache reconcile) still runs so a
+     * subsequent flip-on via `config:changed` can transition us up
+     * without a page reload.
+     */
+    phase2Active = false;
+    /**
+     * Set by `dismiss()` — the user hid all PageLoop UI (e.g. for a
+     * screenshot). Keeps `reEvaluatePhase2()` from silently re-mounting on
+     * the next settings reconcile / tab-refocus. Not persisted, so a real
+     * page reload starts fresh with the widget visible again.
+     */
+    dismissed = false;
+    /** Captured from the renderer's `mount` return so deep-link
+     *  handlers (`?pl-comment=<id>`) can call `focusComment` after the
+     *  sidebar is up. Stays null when the renderer hasn't mounted yet
+     *  (e.g. during a stop/restart). */
+    sidebarHandle = null;
+    /** Same idea for the toolbar handle — needed so refreshBubbles()
+     *  can push the live comment count to the docked toolbar / mini
+     *  widget bubble. Was previously discarded from the mount return,
+     *  which is why the mini bubble's centered count stuck at 0. */
+    toolbarHandle = null;
+    /** Latest set of comment ids whose anchor couldn't resolve in the
+     *  current DOM. Updated by the `bubbles:dangling` event the bubble
+     *  layer emits at the end of every repaint. Threaded into
+     *  SidebarState on the next refreshSidebar() so the comments tab
+     *  can mark those rows as "no anchor". */
+    danglingCommentIds = new Set();
+    /**
+     * Server-provided settings, hydrated synchronously from localStorage on
+     * boot and revalidated by bootstrap. Snippet config still wins per-key
+     * via `effectiveUi()` — this is just the fallback set.
+     */
+    serverSettings;
+    constructor(config, deps) {
+        this.config = config;
+        this.bus = new EventBus();
+        this.notifications = new BrowserNotifications({
+            bus: this.bus,
+            debug: (...args) => this.debug(...args),
+        });
+        this.notifications.start();
+        // Hydrate settings + project synchronously from localStorage so
+        // the toolbar can mount in its final position on the first
+        // frame, before any network round-trip. Revalidation may emit
+        // `config:changed` afterwards if the server sent something
+        // different; the project metadata changes silently (renderer
+        // reads via the `project()` getter on each event).
+        this.serverSettings = readCachedSettings(config.projectId) ?? {};
+        this.project = readCachedProject(config.projectId);
+        const cachedBehavior = this.serverSettings.behavior ?? {};
+        // Pick up the post-OAuth bearer token from the URL fragment +
+        // persist it to localStorage, OR re-read a saved token from a
+        // prior session. Falls back to whatever the embedder passed in.
+        // See resolveInitialToken() for the priority order + URL-cleanup
+        // semantics.
+        const initialToken = resolveInitialToken(config.token);
+        // Hydrate the cached user identity + role so the toolbar paints
+        // the signed-in pill on first frame, before bootstrap returns.
+        // ONLY trust the cache when a token also exists — without a
+        // token we have nothing to authenticate the cached identity
+        // against, so we have to start anonymous and let bootstrap
+        // figure it out. Sign-out also clears this cache below
+        // (`bootstrap returns anonymous` and the in-cleanup paths), so
+        // a deliberate sign-out can't be undone by a stale cache hit.
+        if (initialToken) {
+            const cachedSession = readCachedUserSession(config.projectId);
+            if (cachedSession) {
+                this.currentUser = cachedSession.user;
+                this.currentRole = cachedSession.role;
+            }
+        }
+        this.api = new ApiClient({
+            endpoint: config.endpoint,
+            projectId: config.projectId,
+            token: initialToken,
+            transport: config.transport ?? cachedBehavior.transport,
+        }, this.bus);
+        this.tracker = new PageTracker(this.bus);
+        this.comments = new CommentEngine(this.api, this.bus);
+        this.cache = new IdbCache(config.projectId);
+        this.renderer = deps.renderer;
+    }
+    /**
+     * Effective UI config. Server wins per-key — admin is the source of
+     * truth for these knobs. Snippet values act as initial fallbacks for
+     * the synchronous first paint (before bootstrap returns); once
+     * reconciled, the server values overwrite. Identity / security keys
+     * (endpoint, projectId, token, debug) are snippet-only and live on
+     * `this.config` directly — they're never reachable from here.
+     */
+    effectiveUi() {
+        const snippet = this.config.ui ?? {};
+        const server = this.serverSettings.ui ?? {};
+        // sidebarPosition rolls up the legacy sidebarSide on either side
+        // when the new field is missing. Renderer reads sidebarPosition
+        // exclusively; sidebarSide is preserved on the merged shape so
+        // older renderers in flight don't break.
+        const sidebarPosition = server.sidebarPosition ??
+            snippet.sidebarPosition ??
+            server.sidebarSide ??
+            snippet.sidebarSide;
+        return {
+            toolbarPosition: server.toolbarPosition ?? snippet.toolbarPosition,
+            widgetMode: server.widgetMode ?? snippet.widgetMode,
+            widgetCorner: server.widgetCorner ?? snippet.widgetCorner,
+            sidebarPosition,
+            sidebarSide: server.sidebarSide ?? snippet.sidebarSide,
+            sidebarDisplayMode: server.sidebarDisplayMode ?? snippet.sidebarDisplayMode,
+            theme: server.theme ?? snippet.theme,
+            allowInlineCommenting: server.allowInlineCommenting ?? snippet.allowInlineCommenting,
+            tooltipDelayMs: server.tooltipDelayMs ?? snippet.tooltipDelayMs,
+            bubbleFollowAnimations: server.bubbleFollowAnimations ?? snippet.bubbleFollowAnimations,
+            bubbleZIndex: server.bubbleZIndex ?? snippet.bubbleZIndex,
+            signInMode: server.signInMode ?? snippet.signInMode,
+        };
+    }
+    /** Same precedence rule for behaviour knobs — server wins. */
+    effectiveBehavior() {
+        const server = this.serverSettings.behavior ?? {};
+        return {
+            enabled: server.enabled,
+            autoDiscover: server.autoDiscover ?? this.config.autoDiscover,
+            transport: server.transport ?? this.config.transport,
+        };
+    }
+    /**
+     * Master kill-switch reader. Defaults to true when the admin has
+     * never set the value (backward compat — existing projects keep
+     * working). Phase-2 mount is gated on this; on a live flip via
+     * `config:changed` the same getter drives the up/down transition.
+     */
+    isWidgetEnabled() {
+        return this.effectiveBehavior().enabled !== false;
+    }
+    /**
+     * Reconcile server settings into the cache + emit `config:changed` if
+     * any visible knob actually moved. Called once after bootstrap; cheap
+     * enough to JSON.stringify-compare since the blob is tiny.
+     */
+    reconcileSettings(next) {
+        const incoming = next ?? {};
+        const before = JSON.stringify(this.serverSettings);
+        const after = JSON.stringify(incoming);
+        if (before === after)
+            return;
+        this.serverSettings = incoming;
+        writeCachedSettings(this.config.projectId, incoming);
+        this.bus.emit('config:changed', { settings: incoming, ui: this.effectiveUi() });
+    }
+    /**
+     * Mount the renderer with the standard dep-getter set. Factored out
+     * of `start()` so both the optimistic-paint path (cached project,
+     * before bootstrap) and the slow path (no cache, after bootstrap)
+     * share one mount call site. Captures the sidebar handle + replays
+     * the connection state so the toolbar's "online" badge picks up
+     * any already-completed `api.connect()` resolution.
+     */
+    async mountRenderer() {
+        const mounted = await this.renderer.mount({
+            bus: this.bus,
+            api: this.api,
+            comments: this.comments,
+            notifications: this.notifications,
+            page: () => this.currentPage,
+            project: () => this.project,
+            user: () => this.currentUser,
+            role: () => this.currentRole,
+            bubbleColor: () => this.currentBubbleColor,
+            applyToken: (token) => this.applyToken(token),
+            dismiss: () => {
+                void this.dismiss();
+            },
+            ui: () => this.effectiveUi(),
+            registerCurrentPage: () => this.registerCurrentPage().catch((err) => {
+                console.warn('[PageLoop] registerCurrentPage failed:', err);
+                return null;
+            }),
+            pageKey: () => this.tracker.pageKey(),
+            debug: (...args) => this.debug(...args),
+            release: () => ({
+                version: this.config.version,
+                notesUrl: this.config.releaseNotesUrl,
+            }),
+        });
+        this.sidebarHandle = mounted.sidebar;
+        this.toolbarHandle = mounted.toolbar;
+        // Re-emit connection state — the renderer just registered its
+        // listener, and `api.connect()` may have already resolved before
+        // this mount call.
+        this.api.replayConnectionState();
+    }
+    async start() {
+        this.debug('start: config', {
+            endpoint: this.config.endpoint,
+            projectId: this.config.projectId,
+            hasToken: !!this.config.token,
+        });
+        // Optimistic paint from IDB while the network call is in flight. The
+        // bootstrap call below reconciles afterward and emits events that update
+        // both UI and cache. This means a cold reload of a known page renders
+        // comments immediately without waiting for a round-trip.
+        const cachedKey = this.tracker.pageKey();
+        this.debug('start: pageKey', cachedKey);
+        const cachedPage = await this.cache.getPage(cachedKey);
+        if (cachedPage) {
+            this.debug('start: idb cache hit, optimistic paint', { pageId: cachedPage.id });
+            this.currentPage = cachedPage;
+            const cachedComments = await this.cache.getComments(cachedPage.id);
+            if (cachedComments)
+                this.comments.prime(cachedPage.id, cachedComments);
+        }
+        // Phase-2 gate: master kill-switch. When the admin has flipped
+        // `behavior.enabled` to false the widget renders nothing and
+        // opens no connections; we still let bootstrap run below so a
+        // future flip-on (next page load) sees the latest server value.
+        const cachedEnabled = this.isWidgetEnabled();
+        // If we have a cached Project (constructor hydrated `this.project`
+        // from localStorage) AND the cache says the widget is enabled,
+        // mount the renderer + open the WS NOW — before bootstrap —
+        // so the toolbar appears on the first frame instead of waiting
+        // for the network round-trip. The deps' getters return live
+        // values, so updates from bootstrap flow through naturally
+        // (`config:changed` + `auth:changed` events trigger re-render).
+        //
+        // First-visit users (no cached project) OR projects whose
+        // cached settings say enabled=false take the slow path below —
+        // toolbar stays hidden until bootstrap returns; if bootstrap
+        // confirms the widget is enabled the post-reconcile re-eval
+        // flips on Phase 2 then. If bootstrap says disabled, we stay
+        // inert.
+        if (cachedEnabled && this.project) {
+            this.debug('start: optimistic Phase 2 from cached project + enabled', {
+                slug: this.project.slug,
+            });
+            try {
+                await this.runPhase2();
+            }
+            catch (err) {
+                this.debug('start: optimistic Phase 2 failed, will retry post-bootstrap', err);
+            }
+        }
+        else if (!cachedEnabled) {
+            this.debug('start: widget disabled in cache, deferring Phase 2');
+        }
+        // Bootstrap: project + (maybe) page + comments + me + prefs in one round-trip.
+        // Resilience principle: PageLoop must never block the host page. A
+        // stale/foreign-secret token in localStorage (common when a user has
+        // hit multiple PageLoop servers — local + prod — from the same
+        // origin) used to leave the widget unmounted. Now we recover:
+        //   1. If bootstrap throws UNAUTHORIZED *and* we sent a token, clear
+        //      it and retry anonymous. Project publicRead determines whether
+        //      the retry succeeds.
+        //   2. If the retry (or any other failure) still throws, log + bail
+        //      gracefully — no UI mounted, no thrown promise, host page is
+        //      untouched.
+        let initial = null;
+        let lastError = null;
+        try {
+            initial = await this.api.call('bootstrap', {
+                projectId: this.config.projectId,
+                pageKey: cachedKey,
+            });
+        }
+        catch (err) {
+            lastError = err;
+            const isUnauthorized = errorCode(err) === ERROR_CODES.UNAUTHORIZED;
+            if (isUnauthorized && this.api.getToken()) {
+                // The widget can't authenticate to this project — could be a
+                // stale dev token, a real session that lacks membership, or
+                // a token minted under a different `PAGELOOP_JWT_SECRET`.
+                //
+                // Critically: DO NOT clear localStorage here. The widget and
+                // the host page (admin SPA, an embedder app) share the same
+                // `pl_token` key by design — wiping it would sign the user
+                // out of the admin or any other PageLoop surface that's open
+                // in the same browser. Drop the widget's in-memory token so
+                // THIS bootstrap retry runs anonymously, but leave the
+                // persisted token alone. If the token is genuinely stale, the
+                // admin's own session-resolution path (`me`) will detect that
+                // and clear it cleanly through the proper signed-out flow.
+                this.debug('start: bootstrap UNAUTHORIZED — dropping in-memory token, retrying anon');
+                this.api.setToken(null);
+                // Cached user identity is now stale — the server rejected
+                // the token that authenticated it. Clear so the next cold
+                // load doesn't paint the old user pill while bootstrap
+                // re-resolves as anonymous.
+                clearCachedUserSession(this.config.projectId);
+                this.currentUser = null;
+                this.currentRole = 'anonymous';
+                try {
+                    initial = await this.api.call('bootstrap', {
+                        projectId: this.config.projectId,
+                        pageKey: cachedKey,
+                    });
+                    lastError = null;
+                }
+                catch (err2) {
+                    lastError = err2;
+                    this.debug('start: anonymous bootstrap also failed', err2);
+                }
+            }
+            else {
+                this.debug('start: bootstrap failed', err);
+            }
+        }
+        if (!initial) {
+            // Final fallback — the widget can't mount, but the host page is
+            // untouched. Surface enough detail that an embedder can debug
+            // without enabling debug=true.
+            const errMsg = lastError instanceof Error ? lastError.message : String(lastError);
+            const code = errorCode(lastError);
+            const hint = errMsg.includes('requires a project scope')
+                ? `Project "${this.config.projectId}" not found at ${this.config.endpoint}. Check projectId or confirm the server hosting this project is the one running on that endpoint.`
+                : code === ERROR_CODES.UNAUTHORIZED
+                    ? `Server rejected the request (UNAUTHORIZED) and anonymous fallback also failed. The project likely requires sign-in (publicRead is off).`
+                    : code === ERROR_CODES.FORBIDDEN
+                        ? `Anonymous access denied. Either sign in, or enable publicRead in the project settings.`
+                        : `Could not reach ${this.config.endpoint}: ${errMsg}`;
+            console.warn(`[PageLoop] widget will not mount — ${hint}`);
+            return;
+        }
+        this.project = initial.project;
+        this.currentPage = initial.page;
+        this.currentUser = initial.user;
+        this.currentRole = initial.role;
+        this.currentBubbleColor = initial.bubbleColor ?? null;
+        // Persist the fresh Project blob so the NEXT cold load can mount
+        // optimistically. Done BEFORE reconcileSettings so a partial
+        // failure mid-reconcile still leaves us with cache consistency.
+        writeCachedProject(this.config.projectId, initial.project);
+        // Persist the user + role so the NEXT cold load can paint the
+        // signed-in toolbar pill on first frame instead of flashing
+        // "Sign in" until bootstrap returns. Clears the cache when the
+        // server resolved this token as anonymous (token expired,
+        // revoked, or DB-deleted user) so the cached identity can't
+        // resurrect a session that the server no longer honors.
+        if (initial.user) {
+            writeCachedUserSession(this.config.projectId, {
+                user: initial.user,
+                role: initial.role,
+            });
+        }
+        else {
+            clearCachedUserSession(this.config.projectId);
+        }
+        // Reconcile server-driven config + persist for the next cold load.
+        // Emits `config:changed` if anything visible moved.
+        this.reconcileSettings(initial.project.settings);
+        // Surface auth state to wrappers so React/Preact/Solid hooks can
+        // re-render without polling. Anonymous → role='anonymous', user=null.
+        this.bus.emit('auth:changed', { user: this.currentUser, role: this.currentRole });
+        this.lastBootstrapAt = Date.now();
+        // Re-resolve the session when the user returns to the tab (throttled),
+        // so an org/role change made while they were away is picked up without
+        // a manual reload. Wired once, dropped in stop().
+        if (!this.visibilityWired && typeof document !== 'undefined') {
+            this.visibilityWired = true;
+            document.addEventListener('visibilitychange', this.onVisible);
+        }
+        this.debug('start: bootstrap', {
+            project: initial.project.slug,
+            page: initial.page?.id ?? null,
+            comments: initial.comments.length,
+            user: initial.user?.email ?? null,
+            role: initial.role,
+        });
+        if (initial.page) {
+            this.comments.prime(initial.page.id, initial.comments);
+            await this.cache.putPage(initial.page);
+            await this.cache.putComments(initial.page.id, initial.comments);
+        }
+        // Project metadata can change at runtime (rename, settings
+        // toggle, master kill-switch flip). Wire this UNCONDITIONALLY
+        // — even when Phase 2 is currently down — because this is the
+        // signal the disabled-at-boot widget uses to wake up when the
+        // admin flips it back on. Lives on its own slot so phase 2
+        // teardown doesn't drop it.
+        if (!this.offProjectUpdated) {
+            this.offProjectUpdated = this.bus.on('projects.updated', (event) => {
+                if (!this.project || event?.project?.id !== this.project.id)
+                    return;
+                this.project = event.project;
+                this.reconcileSettings(event.project.settings);
+                this.bus.emit('project:updated', event.project);
+                void this.reEvaluatePhase2();
+                if (this.phase2Active)
+                    this.refreshSidebar();
+            });
+        }
+        // Keep the cached bubble colour fresh when the user recolours from
+        // the widget settings panel (the renderer persists to the server +
+        // re-tints live; we just track the value so `bubbleColor()` stays
+        // current for a settings-panel reopen). Own slot, wired once.
+        if (!this.offBubbleRecolor) {
+            this.offBubbleRecolor = this.bus.on('bubbles:recolor', (event) => {
+                this.currentBubbleColor = (event?.color ?? null);
+            });
+        }
+        // Reconcile complete. Re-evaluate the Phase 2 gate against the
+        // freshly-merged server settings:
+        //   - cached said disabled, server says enabled → mount now
+        //   - cached said enabled (we already mounted optimistically),
+        //     server says disabled → tear down
+        //   - both agree → no-op
+        await this.reEvaluatePhase2();
+    }
+    /**
+     * Phase 2 — the user-facing widget. Mounts the renderer, opens the
+     * WebSocket, starts the page tracker, and subscribes the bus to
+     * comment/page events. Idempotent: subsequent calls while
+     * `phase2Active === true` are no-ops.
+     *
+     * Kept separate from `start()` so the master kill-switch
+     * (`behavior.enabled`) can gate this whole surface without
+     * threading branches through every step. Cold-boot enters here
+     * once when enabled; live admin flips re-enter via
+     * `reEvaluatePhase2()`.
+     */
+    async runPhase2() {
+        if (this.phase2Active)
+            return;
+        this.phase2Active = true;
+        this.debug('phase2: starting');
+        // WebSocket dial — scheduled via requestIdleCallback so it
+        // yields to host-page first-paint / interactivity work. End
+        // state flips to online via the existing `connection:open`
+        // event.
+        this.scheduleIdle(() => {
+            this.api.connect().catch((err) => {
+                this.debug('phase2: connect failed', err);
+            });
+        });
+        await this.mountRenderer();
+        // Auto-discover: if no tracked page exists for this URL and the
+        // config permits it, register the page so visitors can
+        // immediately comment.
+        if (!this.currentPage && (this.effectiveBehavior().autoDiscover ?? true)) {
+            this.debug('phase2: auto-discovering current page');
+            try {
+                await this.registerCurrentPage();
+            }
+            catch (err) {
+                this.debug('phase2: auto-discover failed', err);
+                // FORBIDDEN / UNAUTHORIZED is the EXPECTED outcome on a private
+                // project viewed anonymously — the widget stays mounted in its
+                // anonymous state (Sign-in still available), so stay quiet. Any
+                // other failure (network, 5xx, …) is unexpected: surface a toast
+                // so the visitor/operator knows the page didn't get tracked and
+                // comments may be unavailable. (Errors arrive as `CODE: message`.)
+                const message = err instanceof Error ? err.message : String(err);
+                const isAuthError = /^(FORBIDDEN|UNAUTHORIZED)\b/.test(message);
+                if (!isAuthError) {
+                    this.notify("Couldn't set up PageLoop on this page — comments may be unavailable. Try reloading.", { kind: 'error', durationMs: 6000 });
+                }
+            }
+        }
+        this.refreshSidebar();
+        this.refreshBubbles();
+        // Deep-link: `?pl-comment=<commentId>` on the current URL means
+        // "open the page focused on that comment".
+        this.maybeFocusFromUrl();
+        // Start tracking SPA navigation; resolve a tracked page on every change.
+        this.tracker.start();
+        const offChange = this.bus.on('page:change', async ({ key }) => {
+            await this.resolvePage(key);
+        });
+        // Live updates: re-render bubbles + sidebar when comments change.
+        const offCreated = this.bus.on('comment:created', () => this.refreshAfterChange());
+        const offUpdated = this.bus.on('comment:updated', () => this.refreshAfterChange());
+        const offDeleted = this.bus.on('comment:deleted', () => this.refreshAfterChange());
+        const offBulkDeleted = this.bus.on('comment:bulkDeleted', () => this.refreshAfterChange());
+        // Bubble layer emits the dangling set at the end of every
+        // anchor-resolve pass. Cache it + refresh the sidebar so the
+        // "no anchor" indicator flips on/off without waiting for the
+        // next user action.
+        const offDangling = this.bus.on('bubbles:dangling', (event) => {
+            const ids = event?.ids instanceof Set ? event.ids : new Set();
+            const changed = ids.size !== this.danglingCommentIds.size ||
+                [...ids].some((id) => !this.danglingCommentIds.has(id));
+            this.danglingCommentIds = ids;
+            if (changed)
+                this.refreshSidebar();
+        });
+        this.offHandlers.push(offChange, offCreated, offUpdated, offDeleted, offBulkDeleted, offDangling);
+    }
+    /**
+     * Phase 2 teardown — symmetric inverse of `runPhase2()`. Unmounts
+     * the renderer, stops the tracker, disconnects the WS, drops every
+     * Phase 2 subscription. The always-on `projects.updated` listener
+     * lives on `offProjectUpdated` and is untouched here so it can
+     * wake us back up when the admin flips the kill-switch on.
+     */
+    async tearDownPhase2() {
+        if (!this.phase2Active)
+            return;
+        this.debug('phase2: tearing down');
+        this.phase2Active = false;
+        this.tracker.stop();
+        for (const off of this.offHandlers)
+            off();
+        this.offHandlers = [];
+        await this.renderer.unmount();
+        this.sidebarHandle = null;
+        this.toolbarHandle = null;
+        this.api.disconnect();
+    }
+    /**
+     * Remove ALL PageLoop UI from the page — toolbar/mini, sidebar, bubbles,
+     * tooltips, chat, toasts — and disconnect the socket, until the next page
+     * load. Nothing is persisted: a refresh re-initializes the widget
+     * normally. Intended for screenshots / temporarily clearing the page; the
+     * toolbar + mini both expose an "X" that calls this. Idempotent.
+     */
+    async dismiss() {
+        this.dismissed = true;
+        await this.tearDownPhase2();
+    }
+    /**
+     * Drive Phase 2 to whatever state the latest effective
+     * `behavior.enabled` value implies. Called after every
+     * reconcileSettings so a live admin flip transitions us up or
+     * down without a page reload.
+     */
+    async reEvaluatePhase2() {
+        // `dismissed` wins until the next reload — a settings reconcile or
+        // tab-refocus must not resurrect the UI the user explicitly cleared.
+        const want = this.isWidgetEnabled() && !this.dismissed;
+        if (want && !this.phase2Active) {
+            await this.runPhase2();
+        }
+        else if (!want && this.phase2Active) {
+            await this.tearDownPhase2();
+        }
+    }
+    async stop() {
+        this.notifications.stop();
+        if (this.offProjectUpdated) {
+            this.offProjectUpdated();
+            this.offProjectUpdated = null;
+        }
+        if (this.offBubbleRecolor) {
+            this.offBubbleRecolor();
+            this.offBubbleRecolor = null;
+        }
+        if (this.visibilityWired && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.onVisible);
+            this.visibilityWired = false;
+        }
+        // `tearDownPhase2` drops Phase 2 subscriptions, stops the
+        // tracker, unmounts the renderer, and disconnects the WS. When
+        // Phase 2 was never started (widget disabled at boot) this
+        // no-ops cleanly.
+        if (this.phase2Active) {
+            await this.tearDownPhase2();
+        }
+    }
+    getCurrentPage() {
+        return this.currentPage;
+    }
+    /** Project this PageLoop instance is bound to (null until bootstrap). */
+    getProject() {
+        return this.project;
+    }
+    /** Authenticated user — null when anonymous. Updated after bootstrap. */
+    getCurrentUser() {
+        return this.currentUser;
+    }
+    /** Caller's role in the project — `'anonymous'` when not signed in. */
+    getCurrentRole() {
+        return this.currentRole;
+    }
+    /**
+     * Apply a freshly-obtained session token (sign-in modal, email/password
+     * login, etc.) WITHOUT reloading the host page: set the bearer, persist
+     * it, then re-resolve identity + comments via bootstrap and repaint.
+     * Emits `auth:changed` so the toolbar/mini swap to the signed-in state.
+     * Pass null to sign out. Because the server's JWT is identity-only
+     * (`{sub}`) and resolves org/role per-request from the DB, this also
+     * picks up any membership/role change the user has accrued since their
+     * last bootstrap — no special token-refresh dance required.
+     */
+    async applyToken(token) {
+        this.api.setToken(token);
+        try {
+            if (token)
+                localStorage.setItem(SESSION_TOKEN_KEY, token);
+            else
+                localStorage.removeItem(SESSION_TOKEN_KEY);
+        }
+        catch {
+            /* private mode — in-memory token still works for this tab */
+        }
+        await this.reBootstrap();
+    }
+    /**
+     * Re-run bootstrap under the CURRENT token and fold the result into live
+     * state (identity, role, project settings, comments) without remounting.
+     * Powers both `applyToken` (after a sign-in) and the focus-driven
+     * auto-refresh below. Because the JWT is identity-only and the server
+     * resolves org/role per-request, this is also how a user picks up a
+     * membership/role change (e.g. an admin adding them to an org) — no token
+     * reissue needed; the next bootstrap simply resolves the new permissions.
+     */
+    async reBootstrap() {
+        try {
+            const initial = await this.api.call('bootstrap', {
+                projectId: this.config.projectId,
+                pageKey: this.tracker.pageKey(),
+            });
+            this.lastBootstrapAt = Date.now();
+            this.project = initial.project;
+            this.currentPage = initial.page;
+            this.currentUser = initial.user;
+            this.currentRole = initial.role;
+            this.currentBubbleColor = initial.bubbleColor ?? null;
+            writeCachedProject(this.config.projectId, initial.project);
+            if (initial.user) {
+                writeCachedUserSession(this.config.projectId, {
+                    user: initial.user,
+                    role: initial.role,
+                });
+            }
+            else {
+                clearCachedUserSession(this.config.projectId);
+            }
+            this.reconcileSettings(initial.project.settings);
+            if (initial.page) {
+                this.comments.prime(initial.page.id, initial.comments);
+                await this.cache.putPage(initial.page);
+                await this.cache.putComments(initial.page.id, initial.comments);
+            }
+            this.bus.emit('auth:changed', { user: this.currentUser, role: this.currentRole });
+            await this.reEvaluatePhase2();
+            if (this.phase2Active) {
+                this.refreshSidebar();
+                this.refreshBubbles();
+            }
+        }
+        catch (err) {
+            this.debug('reBootstrap failed', err);
+            // Still surface the current auth identity best-effort.
+            this.bus.emit('auth:changed', { user: this.currentUser, role: this.currentRole });
+        }
+    }
+    /**
+     * Tab-focus auto-refresh. When a signed-in user returns to the tab and
+     * it's been a while since the last bootstrap, re-resolve their session so
+     * any org/role change an admin made while they were away (e.g. adding a
+     * just-registered user to an organization) is picked up without a manual
+     * reload. Throttled so routine tab-switching doesn't spam the server.
+     */
+    onVisible = () => {
+        if (typeof document === 'undefined' || document.visibilityState !== 'visible')
+            return;
+        if (!this.currentUser)
+            return; // anonymous → nothing to re-resolve
+        if (Date.now() - this.lastBootstrapAt < SESSION_REFRESH_THROTTLE_MS)
+            return;
+        void this.reBootstrap();
+    };
+    /** Auto-register the current URL as a tracked page (for autoDiscover mode). */
+    async registerCurrentPage(title) {
+        if (!this.project)
+            throw new Error('PageLoop not started');
+        const key = this.tracker.pageKey();
+        const page = await this.api.call('pages.register', {
+            projectId: this.project.id,
+            sourceKind: 'live',
+            // For live URLs without an Endpoint, source_id == projectId — flat-mode default.
+            sourceId: this.project.id,
+            key,
+            title: title ?? document.title,
+        });
+        this.currentPage = page;
+        await this.comments.loadFromServer(page.id);
+        this.refreshSidebar();
+        this.refreshBubbles();
+        return page;
+    }
+    // --- internals ---
+    async resolvePage(key) {
+        if (!this.project)
+            return;
+        // Optimistic paint from cache, then reconcile.
+        const cached = await this.cache.getPage(key);
+        if (cached) {
+            this.currentPage = cached;
+            const cachedComments = await this.cache.getComments(cached.id);
+            if (cachedComments)
+                this.comments.prime(cached.id, cachedComments);
+            this.refreshSidebar();
+            this.refreshBubbles();
+        }
+        const page = await this.api.call('pages.byKey', { projectId: this.project.id, key });
+        // `displayVisibility === 'disabled'` is a hard refuse-to-mount. The
+        // widget treats the page as if it doesn't exist — no bubbles, no
+        // sidebar, no compose. Server still rejects `comments.create` for
+        // disabled pages; the client mirror keeps the offline-after-load
+        // state honest.
+        if (page && page.settings.displayVisibility === 'disabled') {
+            this.currentPage = null;
+            this.refreshSidebar();
+            this.refreshBubbles();
+            return;
+        }
+        this.currentPage = page;
+        if (page) {
+            const list = await this.comments.loadFromServer(page.id);
+            await this.cache.putPage(page);
+            await this.cache.putComments(page.id, list);
+        }
+        this.refreshSidebar();
+        this.refreshBubbles();
+    }
+    debug(...args) {
+        if (this.config.debug)
+            console.debug('[PageLoop]', ...args);
+    }
+    /**
+     * Schedule non-critical work for after the host page has settled.
+     * Uses `requestIdleCallback` where available (most modern browsers
+     * outside Safari pre-17), `setTimeout(0)` as a fallback. The
+     * timeout cap ensures the callback eventually runs even if the
+     * host stays busy — we don't want widget features to silently
+     * never activate.
+     */
+    scheduleIdle(fn) {
+        if (typeof window === 'undefined')
+            return;
+        const ric = window.requestIdleCallback;
+        if (typeof ric === 'function') {
+            ric(fn, { timeout: 3000 });
+            return;
+        }
+        setTimeout(fn, 50);
+    }
+    /**
+     * Consume `?pl-comment=<id>` (and optional `?pl-reply=<id>`) on
+     * the current URL: open the sidebar focused on that comment +
+     * animate the bubble. When `pl-reply` is also present, expand
+     * the comment's replies thread and scroll to the specific reply.
+     * Strips the params from the URL on success so a refresh doesn't
+     * re-focus.
+     *
+     * No-op when params are missing, the renderer isn't mounted, or
+     * the comment id isn't part of the currently-loaded page's set —
+     * the latter case means a stale deep-link; we silently drop it
+     * rather than confuse the user with an error toast.
+     */
+    maybeFocusFromUrl() {
+        if (typeof window === 'undefined')
+            return;
+        const params = new URLSearchParams(window.location.search);
+        const commentId = params.get('pl-comment');
+        const replyId = params.get('pl-reply');
+        if (!commentId)
+            return;
+        if (!this.sidebarHandle)
+            return;
+        // The bubble layer's `focusComment` / `focusReply` walk the
+        // cached anchor map, so we only need to ensure the comment is
+        // loaded. The optimistic IDB paint above usually has it; if
+        // the server hasn't returned yet, a subsequent comment-list
+        // repaint won't auto-focus — but the first attempt covers the
+        // common case (warm cache or fast network).
+        try {
+            if (replyId)
+                this.sidebarHandle.focusReply(commentId, replyId);
+            else
+                this.sidebarHandle.focusComment(commentId);
+        }
+        catch (err) {
+            this.debug('maybeFocusFromUrl: focus failed', err);
+        }
+        // Strip the params so a refresh stays where the user landed.
+        try {
+            params.delete('pl-comment');
+            params.delete('pl-reply');
+            const next = `${window.location.pathname}${params.toString() ? `?${params.toString()}` : ''}${window.location.hash}`;
+            window.history.replaceState({}, '', next);
+        }
+        catch {
+            /* replaceState unavailable (SSR, sandboxed iframe) — fine */
+        }
+    }
+    /**
+     * Programmatic entry point matching the URL deep-link semantics.
+     * Hosts that own their own routing can call this instead of (or
+     * after) appending `?pl-comment=<id>` to the URL — same end-state:
+     * sidebar opens, comment scrolls into view, bubble flashes. When
+     * `replyId` is set, also expands the replies thread + scrolls.
+     *
+     * No-op until `start()` resolves and the renderer is mounted.
+     */
+    focusComment(commentId, replyId) {
+        if (!this.sidebarHandle)
+            return;
+        try {
+            if (replyId)
+                this.sidebarHandle.focusReply(commentId, replyId);
+            else
+                this.sidebarHandle.focusComment(commentId);
+        }
+        catch (err) {
+            this.debug('focusComment: failed', err);
+        }
+    }
+    /**
+     * Build a same-page deep-link URL pointing at a specific comment
+     * (and optionally a reply within it). Hosts use this to construct
+     * notification links / "permalink" buttons / cross-page navigation
+     * targets without re-deriving the param convention each time.
+     *
+     * Returns a same-origin URL with the existing path/hash preserved
+     * and `pl-comment` / `pl-reply` query params appended.
+     */
+    static buildDeepLink(input) {
+        const baseStr = input.url ??
+            (typeof window === 'undefined'
+                ? (() => {
+                    throw new Error('PageLoop.buildDeepLink: no `url` in non-browser context');
+                })()
+                : window.location.href);
+        // `URL` accepts relative inputs when given a base; fall back to
+        // the current origin so callers can pass `/foo/bar`.
+        const base = typeof window === 'undefined'
+            ? new URL(baseStr)
+            : new URL(baseStr, window.location.href);
+        base.searchParams.set('pl-comment', input.commentId);
+        if (input.replyId)
+            base.searchParams.set('pl-reply', input.replyId);
+        else
+            base.searchParams.delete('pl-reply');
+        return base.toString();
+    }
+    refreshAfterChange() {
+        this.refreshSidebar();
+        this.refreshBubbles();
+        // Sync the updated comment set back to cache so the next cold reload
+        // shows the right state without a round-trip.
+        if (this.currentPage) {
+            void this.cache.putComments(this.currentPage.id, this.comments.load(this.currentPage.id));
+        }
+    }
+    refreshSidebar() {
+        const list = this.currentPage ? this.comments.load(this.currentPage.id) : [];
+        this.renderer.renderSidebar({
+            page: this.currentPage,
+            comments: list,
+            danglingCommentIds: this.danglingCommentIds,
+        });
+    }
+    refreshBubbles() {
+        const list = this.currentPage ? this.comments.load(this.currentPage.id) : [];
+        this.renderer.renderBubbles(list);
+        // Push the live count to the toolbar handle. Comments are plain by
+        // default now (no open/resolved issue status), so the badge counts
+        // every comment EXCEPT completed tasks (a resolved task is done —
+        // no "pressure"). The mini widget paints this in the center of the
+        // corner bubble; the docked Toolbar is a no-op. The handle is null
+        // until the renderer's first mount completes, so guard accordingly.
+        const count = list.reduce((n, c) => (c.isTask && c.status === 'resolved' ? n : n + 1), 0);
+        this.toolbarHandle?.setUnreadCount(count);
+    }
+    /**
+     * Public hook for hosts that have just performed a layout change
+     * the widget can't observe on its own (SPA route swap, accordion
+     * open, a custom width-toggle on an admin shell, anything that
+     * shifts anchored elements without firing scroll/resize/CSS-
+     * transition events). Re-runs the bubble positioning routine
+     * without rebuilding the bubble DOM. Safe to call before mount
+     * — no-op until the renderer is up.
+     *
+     * Background work the widget runs anyway:
+     *  - A `ResizeObserver` on `<body>` + a 3s baseline poll catch
+     *    most cases without needing this call.
+     *  - The `bubbleFollowAnimations` project setting layers a rAF
+     *    loop on top during CSS transitions for sub-frame precision.
+     *  This API is for the cases neither of the above covers — when
+     *  you definitively know a layout shift just happened.
+     */
+    reflowBubbles() {
+        this.renderer.reflowBubbles?.();
+    }
+    /**
+     * Re-resolve every bubble's anchor against the current DOM and
+     * re-render. Use this AFTER a page-level content change (saved
+     * edit, in-place rewrite, etc.) where the cached anchor ranges
+     * are now stale — `reflowBubbles()` only re-measures positions of
+     * the EXISTING anchors and would leave them clustered at wherever
+     * the disappeared element used to be.
+     *
+     * Pushes the current comment list back through the renderer's
+     * `renderBubbles` + `renderSidebar` pipeline; the bubble layer's
+     * repaint re-runs anchor resolution from scratch and emits the
+     * `bubbles:dangling` event so the sidebar can mark unresolved
+     * comments.
+     */
+    repositionBubbles() {
+        this.refreshBubbles();
+        this.refreshSidebar();
+    }
+    /**
+     * Programmatically hide or show the bubble overlay. Orthogonal to
+     * the user's toolbar toggle — both have to be "shown" for bubbles
+     * to appear. Use this when the host puts the page into a state
+     * where anchors can't resolve (admin's raw textarea editor mode,
+     * a lazy viewer hydrating), then pair the un-hide with
+     * `repositionBubbles()` so the layer reseats against the new DOM.
+     *
+     * `animationMs` overrides the fade duration for this transition
+     * (default 150ms). Pass `0` to hide/show instantly — handy when
+     * the host page is mid-animation and a cross-fade would visually
+     * compete (e.g. width toggles that re-flow anchored content).
+     *
+     * No-op for renderers that don't implement an overlay layer.
+     */
+    setBubblesHidden(hidden, animationMs) {
+        this.renderer.setBubblesHidden?.(hidden, animationMs);
+    }
+    /**
+     * Show a transient notification in the bottom-right corner.
+     * Stacks with other in-flight messages and auto-dismisses after
+     * `durationMs` (default 2000; pass 0 to pin until the user
+     * clicks). `kind` colors the left-edge stripe (info/success/error).
+     *
+     * The underlying surface is the renderer's Toaster, driven by the
+     * `toast:show` bus channel. This method is the canonical entry
+     * point for widget code that wants to fire a notification; both
+     * vanilla calls and framework-wrapper consumers reach the same
+     * stack.
+     */
+    notify(message, opts) {
+        this.bus.emit('toast:show', {
+            kind: opts?.kind ?? 'info',
+            message,
+            duration: opts?.durationMs,
+        });
+    }
+}
+//# sourceMappingURL=PageLoop.js.map