@n-dx/core 0.1.0

package/packages/web/dist/viewer/response-buffer-gate.js

@@ -0,0 +1,170 @@
+/**
+ * Response buffer gate — suspends message pipeline during tab inactivity.
+ *
+ * Sits at the front of the WebSocket message pipeline to prevent memory
+ * buildup from accumulating response data while the browser tab is hidden.
+ * When the tab becomes inactive:
+ *
+ *   1. Flushes all pending data from downstream buffers (throttle, coalescer,
+ *      batcher) so they release references immediately.
+ *   2. Drops all subsequent incoming messages silently — no accumulation.
+ *   3. Tracks that messages were dropped during suspension.
+ *
+ * When the tab becomes visible again:
+ *
+ *   1. Opens the gate to accept new messages normally.
+ *   2. If any messages were dropped, calls `onResume` so the consumer can
+ *      trigger a single full reconciliation (e.g. fetchPRDData + fetchTaskUsage)
+ *      to restore data integrity.
+ *
+ * This module complements the polling-manager (which suspends fetch intervals)
+ * by also stopping the *response processing* side. Without this, WebSocket
+ * messages arriving during a background tab would still accumulate in the
+ * message-throttle pending arrays, coalescer batch, and update-batcher queue.
+ *
+ * Pipeline position:
+ *
+ *   raw WebSocket → **response-buffer-gate** → throttle → coalescer → batcher → render
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+import { onVisibilityChange, isTabVisible, } from "./tab-visibility.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_RESUME_DEBOUNCE_MS = 100;
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new response buffer gate.
+ *
+ * Usage:
+ * ```ts
+ * const gate = createResponseBufferGate({
+ *   flushDownstream: [
+ *     () => throttle.flush(),
+ *     () => coalescer.flush(),
+ *     () => batcher.flush(),
+ *   ],
+ *   onResume: () => {
+ *     fetchPRDData();
+ *     fetchTaskUsage();
+ *   },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   if (!gate.accept()) return; // Dropped — tab is hidden
+ *   throttle.push(msg);
+ * };
+ * ```
+ */
+export function createResponseBufferGate(config) {
+    const flushDownstream = config.flushDownstream;
+    const onResume = config.onResume;
+    const resumeDebounceMs = config.resumeDebounceMs ?? DEFAULT_RESUME_DEBOUNCE_MS;
+    // Start as visible; the initial-state check below may immediately suspend.
+    let open = true;
+    let droppedCount = 0;
+    let totalDropped = 0;
+    let suspensionCount = 0;
+    let resumeTimer = null;
+    let disposed = false;
+    function clearResumeTimer() {
+        if (resumeTimer !== null) {
+            clearTimeout(resumeTimer);
+            resumeTimer = null;
+        }
+    }
+    /** Flush all downstream buffers to release buffered data from memory. */
+    function flushAllDownstream() {
+        for (const flush of flushDownstream) {
+            try {
+                flush();
+            }
+            catch {
+                // Swallow errors from individual flushes.
+            }
+        }
+    }
+    /** Close the gate: flush downstream buffers and start dropping. */
+    function suspend() {
+        if (!open)
+            return;
+        open = false;
+        droppedCount = 0;
+        suspensionCount++;
+        // Flush downstream buffers to release buffered data from memory.
+        // This ensures the throttle's pending arrays, the coalescer's batch,
+        // and the batcher's queue are all cleared immediately.
+        flushAllDownstream();
+    }
+    /** Re-open the gate and trigger reconciliation if data was dropped. */
+    function resume() {
+        if (open)
+            return;
+        const hadDrops = droppedCount > 0;
+        open = true;
+        // Trigger reconciliation if any messages were lost during suspension.
+        // This ensures the UI shows the latest state from the server.
+        if (hadDrops) {
+            try {
+                onResume();
+            }
+            catch {
+                // Swallow errors from the resume callback.
+            }
+        }
+    }
+    function handleVisibilityChange(snapshot) {
+        if (disposed)
+            return;
+        if (snapshot.isVisible) {
+            // Tab became visible — resume with debounce to prevent thrash.
+            clearResumeTimer();
+            resumeTimer = setTimeout(() => {
+                resumeTimer = null;
+                resume();
+            }, resumeDebounceMs);
+        }
+        else {
+            // Tab became hidden — suspend immediately.
+            clearResumeTimer();
+            suspend();
+        }
+    }
+    // Subscribe to tab visibility changes.
+    const unsubVisibility = onVisibilityChange(handleVisibilityChange);
+    // If the tab is currently hidden, suspend immediately. This runs the
+    // full suspend path (flush + mark closed) even on initial creation.
+    if (!isTabVisible()) {
+        suspend();
+    }
+    // ─── Public methods ─────────────────────────────────────────────────
+    function accept() {
+        if (disposed)
+            return false;
+        if (!open) {
+            droppedCount++;
+            totalDropped++;
+            return false;
+        }
+        return true;
+    }
+    function isOpenFn() {
+        return open;
+    }
+    function getSnapshot() {
+        return {
+            isOpen: open,
+            droppedCount,
+            totalDropped,
+            suspensionCount,
+        };
+    }
+    function dispose() {
+        disposed = true;
+        clearResumeTimer();
+        unsubVisibility();
+    }
+    return { accept, isOpen: isOpenFn, getSnapshot, dispose };
+}
+//# sourceMappingURL=response-buffer-gate.js.map

package/packages/web/dist/viewer/response-buffer-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-buffer-gate.js","sourceRoot":"","sources":["../../src/viewer/response-buffer-gate.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/viewer/route-state.d.ts

@@ -0,0 +1,8 @@
+import type { ViewId } from "./types.js";
+export interface ParsedRoute {
+    view: ViewId;
+    subId: string | null;
+}
+export declare function parsePathnameRoute(pathname: string, validViews: Set<ViewId>): ParsedRoute | null;
+export declare function parseLegacyHashRoute(hash: string, validViews: Set<ViewId>): ParsedRoute | null;
+export declare function resolveLocationRoute(pathname: string, hash: string, validViews: Set<ViewId>): ParsedRoute | null;

package/packages/web/dist/viewer/route-state.js

@@ -0,0 +1,77 @@
+const DEEP_LINK_VIEWS = new Set(["prd", "hench-runs"]);
+function resolveLegacyViewAlias(base, sub) {
+    const normalizedBase = base.trim().toLowerCase();
+    const normalizedSub = (sub ?? "").trim().toLowerCase();
+    if ((normalizedBase === "rex-dashboard" || normalizedBase === "rex")
+        && (normalizedSub === "token-usage" || normalizedSub === "token_usage" || normalizedSub === "llm-utilization")) {
+        return "token-usage";
+    }
+    return null;
+}
+function normalizeHashRoute(hash) {
+    const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+    let decoded = raw.trim();
+    try {
+        decoded = decodeURIComponent(decoded);
+    }
+    catch {
+        // Keep raw hash text when decoding fails.
+    }
+    decoded = decoded.replace(/^\/+/, "");
+    if (decoded.startsWith("sourcevision/"))
+        decoded = decoded.slice("sourcevision/".length);
+    if (decoded.startsWith("sourcevision:"))
+        decoded = decoded.slice("sourcevision:".length);
+    const queryIdx = decoded.search(/[?&]/);
+    if (queryIdx >= 0)
+        decoded = decoded.slice(0, queryIdx);
+    return decoded.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function normalizeHashView(base) {
+    const normalized = base.trim().toLowerCase();
+    if (normalized === "prmarkdown" || normalized === "pr_markdown")
+        return "pr-markdown";
+    return normalized;
+}
+export function parsePathnameRoute(pathname, validViews) {
+    const raw = pathname.slice(1).replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!raw)
+        return null;
+    const slashIdx = raw.indexOf("/");
+    const base = slashIdx > 0 ? raw.slice(0, slashIdx) : raw;
+    const sub = slashIdx > 0 ? raw.slice(slashIdx + 1) : "";
+    const legacyAlias = resolveLegacyViewAlias(base, sub || null);
+    if (legacyAlias && validViews.has(legacyAlias))
+        return { view: legacyAlias, subId: null };
+    if (validViews.has(raw))
+        return { view: raw, subId: null };
+    if (slashIdx > 0) {
+        const view = base;
+        if (validViews.has(view) && sub && DEEP_LINK_VIEWS.has(view))
+            return { view, subId: sub };
+    }
+    return null;
+}
+export function parseLegacyHashRoute(hash, validViews) {
+    if (!hash)
+        return null;
+    const normalized = normalizeHashRoute(hash);
+    if (!normalized)
+        return null;
+    const slashIdx = normalized.indexOf("/");
+    const base = slashIdx > 0 ? normalized.slice(0, slashIdx) : normalized;
+    const sub = slashIdx > 0 ? normalized.slice(slashIdx + 1) : "";
+    const legacyAlias = resolveLegacyViewAlias(base, sub || null);
+    if (legacyAlias && validViews.has(legacyAlias))
+        return { view: legacyAlias, subId: null };
+    const normalizedBase = normalizeHashView(base);
+    const normalizedPath = sub ? `/${normalizedBase}/${sub}` : `/${normalizedBase}`;
+    const parsed = parsePathnameRoute(normalizedPath, validViews);
+    if (!parsed)
+        return null;
+    return parsed;
+}
+export function resolveLocationRoute(pathname, hash, validViews) {
+    return parseLegacyHashRoute(hash, validViews) ?? parsePathnameRoute(pathname, validViews);
+}
+//# sourceMappingURL=route-state.js.map

package/packages/web/dist/viewer/route-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-state.js","sourceRoot":"","sources":["../../src/viewer/route-state.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/viewer/schema-compat.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Schema version migrations.
+ * Ensures older output formats can be rendered by newer viewers.
+ */
+import type { LoadedData } from "./types.js";
+type ModuleKey = keyof LoadedData;
+/**
+ * Apply any needed migrations to bring data up to the current schema version.
+ * Returns the migrated data (or the original if no migrations needed).
+ */
+export declare function migrateData(module: string, data: unknown): unknown;
+/**
+ * Register a migration for a module.
+ * Used for future schema updates.
+ */
+export declare function registerMigration(module: ModuleKey, from: string, to: string, migrate: (data: unknown) => unknown): void;
+export {};

package/packages/web/dist/viewer/schema-compat.js

@@ -0,0 +1,49 @@
+/**
+ * Schema version migrations.
+ * Ensures older output formats can be rendered by newer viewers.
+ */
+/** Current schema version. Inlined to avoid runtime import from schema/. */
+const SCHEMA_VERSION = "1.0.0";
+const migrations = {
+    manifest: [],
+    inventory: [],
+    imports: [],
+    zones: [],
+    components: [],
+    callGraph: [],
+};
+/**
+ * Apply any needed migrations to bring data up to the current schema version.
+ * Returns the migrated data (or the original if no migrations needed).
+ */
+export function migrateData(module, data) {
+    if (!data || typeof data !== "object")
+        return data;
+    const record = data;
+    const dataVersion = module === "manifest"
+        ? record.schemaVersion
+        : undefined;
+    // If version matches current, no migration needed
+    if (dataVersion === SCHEMA_VERSION)
+        return data;
+    const moduleMigrations = migrations[module];
+    if (!moduleMigrations?.length)
+        return data;
+    let current = data;
+    let currentVersion = dataVersion || "0.0.0";
+    for (const migration of moduleMigrations) {
+        if (currentVersion === migration.from) {
+            current = migration.migrate(current);
+            currentVersion = migration.to;
+        }
+    }
+    return current;
+}
+/**
+ * Register a migration for a module.
+ * Used for future schema updates.
+ */
+export function registerMigration(module, from, to, migrate) {
+    migrations[module].push({ from, to, migrate });
+}
+//# sourceMappingURL=schema-compat.js.map

package/packages/web/dist/viewer/schema-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compat.js","sourceRoot":"","sources":["../../src/viewer/schema-compat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,MAAM,cAAc,GAAG,OAAO,CAAC;AAW/B,MAAM,UAAU,GAAmC;IACjD,QAAQ,EAAE,EAAE;IACZ,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,EAAE;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAa;IACvD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,MAAM,GAAG,IAAwC,CAAC;IACxD,MAAM,WAAW,GACf,MAAM,KAAK,UAAU;QACnB,CAAC,CAAE,MAAM,CAAC,aAAoC;QAC9C,CAAC,CAAC,SAAS,CAAC;IAEhB,kDAAkD;IAClD,IAAI,WAAW,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAmB,CAAC,CAAC;IACzD,IAAI,CAAC,gBAAgB,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,OAAO,GAAY,IAAI,CAAC;IAC5B,IAAI,cAAc,GAAG,WAAW,IAAI,OAAO,CAAC;IAE5C,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;QACzC,IAAI,cAAc,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YACtC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACrC,cAAc,GAAG,SAAS,CAAC,EAAE,CAAC;QAChC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAiB,EACjB,IAAY,EACZ,EAAU,EACV,OAAmC;IAEnC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACjD,CAAC"}

package/packages/web/dist/viewer/sourcevision-tabs.d.ts

@@ -0,0 +1,10 @@
+import type { ViewId } from "./types.js";
+export type SourceVisionTabId = Extract<ViewId, "overview" | "graph" | "zones" | "files" | "routes" | "architecture" | "problems" | "suggestions" | "pr-markdown">;
+export interface SourceVisionTab {
+    id: SourceVisionTabId;
+    icon: string;
+    label: string;
+    minPass: number;
+}
+export declare const SOURCEVISION_TABS: readonly SourceVisionTab[];
+export declare const SOURCEVISION_TAB_IDS: SourceVisionTabId[];

package/packages/web/dist/viewer/sourcevision-tabs.js

@@ -0,0 +1,14 @@
+import { ENRICHMENT_THRESHOLDS } from "./components/constants.js";
+export const SOURCEVISION_TABS = [
+    { id: "overview", icon: "\u25A3", label: "Overview", minPass: 0 },
+    { id: "graph", icon: "\u2B95", label: "Import Graph", minPass: 0 },
+    { id: "zones", icon: "\u2B22", label: "Zones", minPass: 0 },
+    { id: "files", icon: "\u2630", label: "Files", minPass: 0 },
+    { id: "routes", icon: "\u25C7", label: "Routes", minPass: 0 },
+    { id: "architecture", icon: "\u25E8", label: "Architecture", minPass: ENRICHMENT_THRESHOLDS.architecture },
+    { id: "problems", icon: "\u26A0", label: "Problems", minPass: ENRICHMENT_THRESHOLDS.problems },
+    { id: "suggestions", icon: "\u2728", label: "Suggestions", minPass: ENRICHMENT_THRESHOLDS.suggestions },
+    { id: "pr-markdown", icon: "\u270D", label: "PR Markdown", minPass: 0 },
+];
+export const SOURCEVISION_TAB_IDS = SOURCEVISION_TABS.map((tab) => tab.id);
+//# sourceMappingURL=sourcevision-tabs.js.map

package/packages/web/dist/viewer/sourcevision-tabs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourcevision-tabs.js","sourceRoot":"","sources":["../../src/viewer/sourcevision-tabs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAclE,MAAM,CAAC,MAAM,iBAAiB,GAA+B;IAC3D,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE;IACjE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,EAAE;IAClE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE;IAC3D,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE;IAC3D,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE;IAC7D,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,qBAAqB,CAAC,YAAY,EAAE;IAC1G,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAC9F,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,EAAE;IACvG,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE;CACxE,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAwB,iBAAiB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC"}

package/packages/web/dist/viewer/tab-visibility.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Centralized tab visibility state manager.
+ *
+ * Wraps the Page Visibility API to provide a single source of truth for
+ * browser tab visibility state. All polling components subscribe to this
+ * module instead of independently listening for visibility changes.
+ *
+ * Browser compatibility:
+ *
+ *   1. Standard API    — `document.visibilityState` + `visibilitychange`
+ *   2. Webkit prefix   — `document.webkitVisibilityState` + `webkitvisibilitychange`
+ *   3. MS prefix       — `document.msVisibilityState` + `msvisibilitychange`
+ *   4. Focus/blur      — `window.focus` / `window.blur` (fallback when no API)
+ *
+ * State transitions:
+ *
+ *   visible -> hidden   Tab is backgrounded, minimized, or screen-locked.
+ *   hidden  -> visible  Tab regains focus or is foregrounded.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useTabVisibility`) is provided separately.
+ */
+/** Tab visibility state, mirrors `document.visibilityState`. */
+export type TabVisibilityState = "visible" | "hidden";
+/** Snapshot of the current tab visibility state at a point in time. */
+export interface TabVisibilitySnapshot {
+    /** Current visibility state. */
+    readonly state: TabVisibilityState;
+    /** Whether the tab is currently visible (convenience boolean). */
+    readonly isVisible: boolean;
+    /** ISO timestamp of when the current state began. */
+    readonly since: string;
+    /** Milliseconds spent in the current state. */
+    readonly durationMs: number;
+    /** ISO timestamp of when this snapshot was taken. */
+    readonly timestamp: string;
+}
+/** Callback invoked when tab visibility changes. */
+export type VisibilityChangeHandler = (snapshot: TabVisibilitySnapshot, previousState: TabVisibilityState) => void;
+/** Configuration for the tab visibility monitor. */
+export interface TabVisibilityConfig {
+    /** Called when tab visibility changes. */
+    onChange: VisibilityChangeHandler | null;
+}
+/** Detection method used for tab visibility tracking. */
+export type VisibilityDetectionMethod = "standard" | "webkit" | "ms" | "focus-blur" | "none";
+/** Browser capability report for the Page Visibility API. */
+export interface VisibilityAPICapabilities {
+    /** Whether any visibility detection method is available. */
+    readonly supported: boolean;
+    /** Which detection method is in use. */
+    readonly method: VisibilityDetectionMethod;
+    /** Whether the native Page Visibility API is available (standard or prefixed). */
+    readonly nativeAPI: boolean;
+    /** Whether using the focus/blur fallback instead of the native API. */
+    readonly usingFallback: boolean;
+    /** The event name being listened to (e.g. "visibilitychange", "webkitvisibilitychange"). */
+    readonly eventName: string | null;
+}
+/** A single state transition record for history tracking. */
+export interface VisibilityTransition {
+    /** The state that was entered. */
+    readonly state: TabVisibilityState;
+    /** The state that was left. */
+    readonly from: TabVisibilityState;
+    /** ISO timestamp of the transition. */
+    readonly timestamp: string;
+}
+/**
+ * Probe the runtime environment for the best available Page Visibility API
+ * variant. Called once on first use, result is cached.
+ *
+ * Priority:
+ *   1. Standard API (`document.visibilityState`)
+ *   2. Webkit prefix (`document.webkitVisibilityState`)
+ *   3. MS prefix (`document.msVisibilityState`)
+ *   4. Focus/blur fallback (window events)
+ *   5. None (SSR or non-browser environment)
+ */
+export declare function detectVisibilityAPI(): {
+    method: VisibilityDetectionMethod;
+    eventName: string | null;
+};
+/**
+ * Start the tab visibility monitor. Detects the best available browser API
+ * and begins listening for state changes.
+ *
+ * Safe to call multiple times — restarts with new config.
+ */
+export declare function startTabVisibilityMonitor(overrides?: Partial<TabVisibilityConfig>): void;
+/** Stop the tab visibility monitor and remove all event listeners. */
+export declare function stopTabVisibilityMonitor(): void;
+/** Subscribe to visibility change events. Returns an unsubscribe function. */
+export declare function onVisibilityChange(listener: (snapshot: TabVisibilitySnapshot) => void): () => void;
+/** Get the current tab visibility state. */
+export declare function getTabVisibility(): TabVisibilityState;
+/** Get a full snapshot of the current tab visibility state. */
+export declare function getTabVisibilitySnapshot(): TabVisibilitySnapshot;
+/** Convenience check: is the tab currently visible? */
+export declare function isTabVisible(): boolean;
+/**
+ * Get the browser's Page Visibility API capabilities.
+ * Reports which detection method is in use and whether fallbacks are active.
+ */
+export declare function getVisibilityCapabilities(): VisibilityAPICapabilities;
+/**
+ * Get the recent transition history (up to 50 entries).
+ * Useful for debugging visibility state patterns.
+ */
+export declare function getTransitionHistory(): readonly VisibilityTransition[];
+/** Reset all module state (for testing). */
+export declare function resetTabVisibility(): void;