@detiq/crawler 1.1.13 → 1.1.15

package/types/crawl-session-manager.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Session management for authenticated crawl sessions.
+ * Detects auth expiry via HTTP status codes and login-page redirects,
+ * then attempts recovery via a token refresh endpoint or re-login flow.
+ * Designed to keep long-running crawls alive without manual intervention.
+ */
+import type { Page } from 'playwright';
+export interface SessionConfig {
+    loginUrl?: string;
+    email?: string;
+    password?: string;
+    healthCheckUrl?: string;
+    refreshEndpoint?: string;
+    tokenLocalStorageKey?: string;
+    maxRefreshAttempts?: number;
+}
+export type SessionEventType = 'HEALTHY' | 'EXPIRY_DETECTED' | 'REFRESH_ATTEMPT' | 'REFRESH_SUCCESS' | 'REFRESH_FAILED' | 'AUTH_FAILURE';
+export interface SessionEvent {
+    type: SessionEventType;
+    isoTimestamp: string;
+    url?: string;
+    strategy?: string;
+    attemptCount?: number;
+}
+export interface SessionManager {
+    onResponse(url: string, status: number): void;
+    onNavigation(url: string): void;
+    isHealthy(): boolean;
+    needsRefresh(): boolean;
+    markHealthy(isoTimestamp: string): void;
+    refresh(page: Page, isoTimestamp: string): Promise<boolean>;
+    getEvents(): SessionEvent[];
+    getStats(): {
+        healthy: boolean;
+        refreshAttempts: number;
+        authFailure: boolean;
+    };
+}
+export declare function createSessionManager(config: SessionConfig): SessionManager;
+/**
+ * Attaches a Playwright response listener to feed HTTP status codes into the
+ * session manager. Returns a cleanup function to remove the listener.
+ */
+export declare function attachSessionWatcher(page: Page, manager: SessionManager): () => void;

package/types/crawler.d.ts

@@ -164,6 +164,7 @@ export declare function crawlProject(opts: {
     segmentIndex: number;
     hasMoreSegments: boolean;
     domHashes: string[];
+    crawlWarnings?: undefined;
 } | {
     screensFound: number;
     screensErrored: number;
@@ -188,9 +189,10 @@ export declare function crawlProject(opts: {
     segmentIndex: number;
     hasMoreSegments: boolean;
     domHashes: string[];
+    crawlWarnings: string[] | undefined;
     discoveredUrls?: undefined;
 }>;
-export declare function domFallbackElements(page: any): Promise<Array<{
+export declare function domFallbackElements(page: any, rawPage?: any): Promise<Array<{
     meaning: string;
     role: string;
     expectedData?: string;

package/types/crud-interaction.d.ts

@@ -0,0 +1,31 @@
+import type { Page } from 'playwright';
+export type EditFlowType = 'inline' | 'modal' | 'navigation' | 'unknown';
+export interface CrudFlowCapture {
+    entityName: string;
+    createTrigger?: string;
+    editFlowType: EditFlowType;
+    editFields: Array<{
+        name: string;
+        type: string;
+        prefilledValue?: string;
+    }>;
+    deleteConfirmation?: {
+        message: string;
+        confirmLabel: string;
+        cancelLabel: string;
+    };
+    createSuccessToast?: string;
+    editSuccessToast?: string;
+    rowCount: number;
+    hasDeleteButton: boolean;
+    hasEditButton: boolean;
+}
+export interface CrudProbeResult {
+    flows: CrudFlowCapture[];
+    toastsObserved: Array<{
+        action: string;
+        text: string;
+        role: string;
+    }>;
+}
+export declare function probeCrudFlows(page: Page, entityName?: string): Promise<CrudProbeResult>;

package/types/dropdown-enumerator.d.ts

@@ -0,0 +1,20 @@
+import type { Page } from 'playwright';
+export interface DropdownOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface DropdownDef {
+    kind: 'native-select' | 'combobox' | 'listbox' | 'multiselect';
+    label: string;
+    locatorHint: string;
+    options: DropdownOption[];
+    defaultValue?: string;
+    cascadesFrom?: string;
+}
+export interface DropdownEnumerationResult {
+    dropdowns: DropdownDef[];
+    conditionalRevealMap: Record<string, string[]>;
+    totalOptionsFound: number;
+}
+export declare function enumerateDropdowns(page: Page): Promise<DropdownEnumerationResult>;

package/types/filter-pagination-crawler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Filter state crawling and pagination capture.
+ *
+ * Discovers filter controls (select, checkbox-group, radio-group, search),
+ * applies each meaningful option and records result counts and first-row
+ * values, then detects and walks pagination (numbered, load-more, infinite
+ * scroll). Also captures sort column behaviour.
+ *
+ * All per-filter / per-page errors are caught and skipped so one bad control
+ * never aborts the full crawl.
+ */
+import type { Page } from 'playwright';
+export interface FilterOption {
+    value: string;
+    label: string;
+}
+export interface FilterDef {
+    kind: 'select' | 'checkbox-group' | 'radio-group' | 'search';
+    label: string;
+    locatorHint: string;
+    options: FilterOption[];
+}
+export interface FilterState {
+    filterLabel: string;
+    filterValue: string;
+    resultCount: number | null;
+    firstRowValues: string[];
+}
+export interface PaginationCapture {
+    kind: 'numbered' | 'load-more' | 'infinite-scroll' | 'none';
+    totalPages?: number;
+    totalItems?: number;
+    pageSizes?: number[];
+    pages: Array<{
+        pageNum: number;
+        rowValues: string[];
+    }>;
+}
+export interface FilterPaginationResult {
+    filters: FilterDef[];
+    filterStates: FilterState[];
+    pagination: PaginationCapture;
+    sortColumns: Array<{
+        header: string;
+        ariaSortAfterClick: string | null;
+    }>;
+    searchCapture?: {
+        noResultsText: string | null;
+        sampleSuggestions: string[];
+    };
+}
+export declare function crawlFiltersAndPagination(page: Page): Promise<FilterPaginationResult>;

package/types/gap-pass.d.ts

@@ -26,6 +26,7 @@ interface LlmCfg {
     provider: string;
     model: string;
     apiKey?: string;
+    baseUrl?: string;
 }
 /**
  * Run LLM gap analysis + HEAD validation.

package/types/index.d.ts

@@ -35,5 +35,18 @@ export { startSpan, endSpan, withSpan, increment, flushMetrics } from './telemet
 export type { Span, FinishedSpan } from './telemetry.js';
 export { analyzeFailure } from './failure-analysis-agent.js';
 export type { FailureContext } from './failure-analysis-agent.js';
-export { elementToPlaywrightLocator, elementsToPlaywrightLocators, formatLocatorsForPrompt } from './locator-extractor.js';
+export { elementToPlaywrightLocator, elementsToPlaywrightLocators, formatLocatorsForPrompt, detectAuthWallLocators } from './locator-extractor.js';
 export type { PlaywrightLocator } from './locator-extractor.js';
+export * from './dropdown-enumerator.js';
+export * from './crud-interaction.js';
+export * from './filter-pagination-crawler.js';
+export * from './multi-context-handler.js';
+export * from './advanced-ui-probes.js';
+export * from './state-graph.js';
+export * from './nested-window-crawler.js';
+export * from './shadow-dom-crawler.js';
+export * from './network-action-correlator.js';
+export * from './crawl-session-manager.js';
+export * from './accessibility-tree-crawler.js';
+export * from './performance-metrics.js';
+export * from './service-worker-interceptor.js';

package/types/job-queue.d.ts

@@ -111,22 +111,24 @@ export declare function createTrackedJob(type: string, config: {
     projectId: string;
     [k: string]: any;
 }): Promise<string>;
-/** Mark a tracked job DONE or FAILED. Safe to call in finally — swallows errors. */
+/** Mark a tracked job DONE or FAILED. Safe to call in finally — swallows errors.
+ * Gap 30: When marking FAILED, sets nextRetryAt (1 min) so the retry worker picks it up promptly. */
 export declare function finishTrackedJob(tenantId: string, jobId: string, error?: string): Promise<void>;
 /** Enqueue a generic platform job — returns the job ID immediately. */
 export declare function enqueueJob(type: string, config: any): Promise<string>;
 /** Get the current state of a platform job. */
 export declare function getJob(tenantId: string, jobId: string): Promise<{
     progress: number;
-    error: string | null;
+    id: string;
+    name: string | null;
     type: string;
+    error: string | null;
+    result: import("@prisma/client/runtime/library").JsonValue | null;
     status: string;
     tenantId: string;
     projectId: string;
-    name: string | null;
-    result: import("@prisma/client/runtime/library").JsonValue | null;
-    id: string;
     config: import("@prisma/client/runtime/library").JsonValue;
+    retryCount: number;
     queuedAt: Date;
     startedAt: Date | null;
     finishedAt: Date | null;
@@ -137,19 +139,23 @@ export declare function getJob(tenantId: string, jobId: string): Promise<{
     totalCacheReadTokens: number | null;
     totalEstimatedCostUsd: number | null;
     llmCallCount: number;
+    nextRetryAt: Date | null;
+    dlq: boolean;
+    dlqReason: string | null;
 } | null>;
 /** List recent jobs for a project. */
 export declare function listJobs(tenantId: string, projectId: string): Promise<{
     progress: number;
-    error: string | null;
+    id: string;
+    name: string | null;
     type: string;
+    error: string | null;
+    result: import("@prisma/client/runtime/library").JsonValue | null;
     status: string;
     tenantId: string;
     projectId: string;
-    name: string | null;
-    result: import("@prisma/client/runtime/library").JsonValue | null;
-    id: string;
     config: import("@prisma/client/runtime/library").JsonValue;
+    retryCount: number;
     queuedAt: Date;
     startedAt: Date | null;
     finishedAt: Date | null;
@@ -160,6 +166,9 @@ export declare function listJobs(tenantId: string, projectId: string): Promise<{
     totalCacheReadTokens: number | null;
     totalEstimatedCostUsd: number | null;
     llmCallCount: number;
+    nextRetryAt: Date | null;
+    dlq: boolean;
+    dlqReason: string | null;
 }[]>;
 /** Cancel a RUNNING or QUEUED job. Aborts the in-process crawl and marks DB CANCELLED. */
 export declare function cancelJob(tenantId: string, jobId: string): Promise<void>;

package/types/locator-extractor.d.ts

@@ -22,6 +22,7 @@ export declare function elementToPlaywrightLocator(element: {
 /**
  * Convert an array of DB Element records to deduplicated Playwright locators.
  * Deduplicates by key — higher confidence wins.
+ * Filters out crawl-analysis meta-annotations and produces an auth-wall warning when applicable.
  */
 export declare function elementsToPlaywrightLocators(elements: Array<{
     role?: string | null;
@@ -32,6 +33,12 @@ export declare function elementsToPlaywrightLocators(elements: Array<{
     isInteractive?: boolean | null;
     ariaState?: Record<string, unknown> | null;
 }>): PlaywrightLocator[];
+/**
+ * Detect whether a set of locators was extracted from an auth-wall page.
+ * Returns a warning message if auth-wall detected, null otherwise.
+ * Heuristic: >50% of locators are low-confidence text matches AND at least one matches auth-wall pattern.
+ */
+export declare function detectAuthWallLocators(locators: PlaywrightLocator[]): string | null;
 /**
  * Format locators as a block for injection into LLM script generation prompts.
  * Returns empty string if no locators.

package/types/multi-context-handler.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Multi-context browser handling — detects and records new tabs, iframes,
+ * popups, and file downloads triggered during a page crawl.
+ * This lets ZeTa discover cross-origin flows, OAuth redirects, embedded
+ * third-party content, and downloadable resources that single-page HTTP
+ * crawlers would miss entirely.
+ */
+import type { Page, BrowserContext } from 'playwright';
+export interface NewTabRecord {
+    url: string;
+    linkText: string;
+    isInternal: boolean;
+    httpStatus?: number;
+}
+export interface IframeRecord {
+    src: string;
+    crossOrigin: boolean;
+    sandboxed: boolean;
+    sandboxValue: string | null;
+    accessible: boolean;
+    contentSample: string;
+    hasForm: boolean;
+}
+export interface PopupRecord {
+    url: string;
+    triggerLabel: string;
+    isOAuthLike: boolean;
+}
+export interface DownloadRecord {
+    filename: string;
+    downloadUrl: string;
+    triggerLabel: string;
+}
+export interface MultiContextResult {
+    newTabs: NewTabRecord[];
+    iframes: IframeRecord[];
+    popups: PopupRecord[];
+    downloads: DownloadRecord[];
+}
+/**
+ * Attaches a listener to the BrowserContext that records every new tab
+ * opened while the listener is active. Returns an unsubscribe function.
+ *
+ * Call this before navigating / clicking so that tabs opened during the
+ * crawl are captured, then call the returned function to stop listening.
+ */
+export declare function attachNewTabListener(context: BrowserContext, seedUrl: string, result: MultiContextResult): () => void;
+/**
+ * Probes the current page for multi-context browser events: iframes,
+ * popup windows, and file downloads.
+ *
+ * New-tab tracking is intentionally excluded here — it must be set up at
+ * the crawler level (before navigation) using `attachNewTabListener`.
+ */
+export declare function probeMultiContext(page: Page, context: BrowserContext, seedUrl: string): Promise<MultiContextResult>;

package/types/nested-window-crawler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Nested window / browsing-context crawler — discovers and records frames,
+ * embedded apps, and popup windows that are already open in the browser
+ * context at the time of a crawl step.
+ *
+ * Complements multi-context-handler.ts: that module handles proactive popup
+ * interception via context.on('page'); this module snapshots what is already
+ * present in the frame tree and context page list.
+ */
+import type { BrowserContext } from 'playwright';
+export type BrowsingContextType = 'page' | 'frame' | 'popup' | 'embedded-app';
+export interface BrowsingContextNode {
+    id: string;
+    type: BrowsingContextType;
+    url: string;
+    parentId: string | null;
+    depth: number;
+    title: string;
+    interactiveCount: number;
+    accessible: boolean;
+    isEmbeddedApp: boolean;
+}
+export interface NestedCrawlResult {
+    contextTree: BrowsingContextNode[];
+    totalContextsFound: number;
+    maxDepthReached: number;
+    inaccessibleCount: number;
+    frameUrls: string[];
+    embeddedAppUrls: string[];
+}
+/**
+ * Discovers all nested browsing contexts reachable from the current page:
+ * sub-frames, embedded applications, and already-open popup pages.
+ *
+ * All failures are non-fatal — errors are caught and an empty result is
+ * returned so the caller's crawl step can continue uninterrupted.
+ */
+export declare function crawlNestedContexts(page: any, context: BrowserContext | null, seedUrl: string, opts?: {
+    maxFrameDepth?: number;
+    maxPopupDepth?: number;
+}): Promise<NestedCrawlResult>;

package/types/network-action-correlator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Network-action correlator — captures XHR/fetch requests that occur during
+ * a named UI action (click, form submit, navigation) and maps them to API
+ * endpoint contracts.
+ *
+ * Usage:
+ *   const correlator = createCorrelator();
+ *   const detach = attachNetworkInterceptor(page, correlator);
+ *   correlator.startWindow('Submit login form');
+ *   await page.click('#login-btn');
+ *   const correlation = correlator.endWindow();
+ *   detach();
+ *   const result = correlator.getResult();
+ */
+import type { Page } from 'playwright';
+export interface NetworkRequestRecord {
+    url: string;
+    urlPattern: string;
+    method: string;
+    bodySchema: Record<string, string> | null;
+    status: number | null;
+    responseSchema: Record<string, string> | null;
+    isGraphQL: boolean;
+    graphQLOperation?: string;
+    resourceType: string;
+    correlatedActionLabel?: string;
+}
+export interface ActionCorrelation {
+    actionLabel: string;
+    requests: NetworkRequestRecord[];
+}
+export interface NetworkCorrelationResult {
+    correlations: ActionCorrelation[];
+    uniqueEndpoints: string[];
+    graphqlOperations: string[];
+    totalRequestsCaptured: number;
+    coverage: number;
+}
+interface NetworkCorrelator {
+    startWindow(actionLabel: string): void;
+    recordRequest(rec: NetworkRequestRecord): void;
+    endWindow(): ActionCorrelation;
+    getResult(): NetworkCorrelationResult;
+}
+export declare function createCorrelator(): NetworkCorrelator;
+export declare function attachNetworkInterceptor(page: Page, correlator: ReturnType<typeof createCorrelator>): () => void;
+export {};

package/types/performance-metrics-collector.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Performance metrics collector — captures Core Web Vitals and navigation timing
+ * for pages visited during crawl runs.
+ * Collects LCP, CLS, INP, TTFB, long tasks, and slow resources via PerformanceObserver
+ * and the Navigation/Resource Timing APIs.
+ */
+import type { Page } from 'playwright';
+export type CwvScore = 'good' | 'needs-improvement' | 'poor';
+export interface LcpMetric {
+    value: number;
+    score: CwvScore;
+    elementTag: string | null;
+    url: string | null;
+}
+export interface ClsMetric {
+    value: number;
+    score: CwvScore;
+    shiftCount: number;
+}
+export interface InpMetric {
+    p75: number;
+    score: CwvScore;
+    sampleCount: number;
+}
+export interface NavTimingMetric {
+    ttfb: number;
+    ttfbScore: CwvScore;
+    domContentLoaded: number;
+    domComplete: number;
+    loadComplete: number;
+    transferSizeBytes: number;
+    protocol: string;
+}
+export interface SlowResource {
+    path: string;
+    durationMs: number;
+    transferSizeBytes: number;
+    initiatorType: string;
+}
+export interface PerformanceMetricsResult {
+    lcp: LcpMetric | null;
+    cls: ClsMetric | null;
+    inp: InpMetric | null;
+    navTiming: NavTimingMetric | null;
+    slowResources: SlowResource[];
+    longTaskCount: number;
+    captureSuccess: boolean;
+}
+export declare function injectPerformanceObservers(page: Page): Promise<void>;
+export declare function collectPagePerformance(page: Page): Promise<PerformanceMetricsResult>;

package/types/performance-metrics.d.ts

@@ -11,7 +11,6 @@
  * - DOMContentLoaded — from navigation timing
  * - Resource count and size by type
  */
-import type { Page } from 'playwright';
 export interface CoreWebVitals {
     lcp?: number;
     cls?: number;
@@ -50,4 +49,4 @@ export interface PagePerfMetrics {
     requestCount: number;
     measuredAt: string;
 }
-export declare function collectPerfMetrics(page: Page, url: string): Promise<PagePerfMetrics>;
+export declare function collectPerfMetrics(page: any, url: string): Promise<PagePerfMetrics>;

package/types/screen-reader.d.ts

@@ -1,4 +1,3 @@
-import type { Page } from 'playwright';
 /**
  * Reads a page as a structured outline (cheap + reliable), the way
  * Playwright MCP / the accessibility tree works — NOT by sending pixels to a
@@ -13,4 +12,4 @@ export interface RawElement {
     selectorHint: string;
     expectedData?: string;
 }
-export declare function readScreen(page: Page): Promise<RawElement[]>;
+export declare function readScreen(page: any): Promise<RawElement[]>;

package/types/service-worker-interceptor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Service Worker detection — inspects SW registrations, cache storage, background
+ * sync queues, and PWA installability for a crawled page.
+ * Surfaces offline-first contracts and push-capable surfaces that HTTP-only
+ * crawlers cannot observe.
+ */
+export interface SwRegistration {
+    scope: string;
+    scriptURL: string | null;
+    state: 'active' | 'installing' | 'waiting' | 'none';
+    updateViaCache: string;
+}
+export interface SwCacheEntry {
+    cacheName: string;
+    entryCount: number;
+    sampleUrls: string[];
+}
+export interface BackgroundSyncInfo {
+    scope: string;
+    pendingTags: string[];
+}
+export interface PwaInfo {
+    isInstallable: boolean;
+    manifestUrl: string | null;
+    hasPushPermission: boolean;
+}
+export interface ServiceWorkerResult {
+    supported: boolean;
+    active: boolean;
+    registrations: SwRegistration[];
+    cacheStorages: SwCacheEntry[];
+    backgroundSync: BackgroundSyncInfo[];
+    pwa: PwaInfo;
+    totalCachedEntries: number;
+}
+export declare function inspectServiceWorker(page: any): Promise<ServiceWorkerResult>;

package/types/session-capture.d.ts

@@ -31,7 +31,7 @@ export declare function validateAndCaptureSession(appUrl: string, creds: {
 }, captchaOpts?: {
     apiKey?: string;
     provider?: '2captcha' | 'capsolver';
-}): Promise<{
+}, loginInstructions?: string): Promise<{
     storageState: string;
     cookies: number;
     localStorage: number;

package/types/shadow-dom-crawler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shadow DOM crawler — enumerate shadow hosts and detect web component libraries.
+ *
+ * Walks the live DOM recursively (up to depth 8) to find all open shadow roots
+ * and custom elements with closed shadow roots, then classifies the component
+ * framework in use. Results feed ZeTa's test generator so it can account for
+ * elements that are invisible to standard Playwright locators.
+ */
+export interface ShadowInteractiveEl {
+    role: string;
+    label: string;
+    type: string;
+    tagName: string;
+}
+export interface ShadowHostInfo {
+    tagName: string;
+    hostId: string;
+    shadowMode: 'open' | 'closed';
+    depth: number;
+    interactiveCount: number;
+    interactiveElements: ShadowInteractiveEl[];
+    slotNames: string[];
+    childShadowHosts: number;
+}
+export interface ShadowDomCrawlResult {
+    shadowHostCount: number;
+    openShadowCount: number;
+    closedShadowCount: number;
+    maxNestingDepth: number;
+    hosts: ShadowHostInfo[];
+    totalInteractiveInShadow: number;
+    detectedLibraries: string[];
+    blindSpots: string[];
+}
+export declare function crawlShadowDom(page: any): Promise<ShadowDomCrawlResult>;

package/types/sitemap.d.ts

@@ -10,7 +10,7 @@ export declare function sameSite(candidateUrl: string, siteOrigin: string): bool
  * and deduped. Pure function — no I/O — for direct unit testing without a
  * real HTTP fetch.
  */
-export declare function extractUrlsFromParsedSitemap(parsed: any, origin: string): {
+export declare function extractUrlsFromParsedSitemap(parsed: any, origin: string, maxUrls?: number): {
     pageUrls: string[];
     subSitemapUrls: string[];
 };
@@ -18,7 +18,7 @@ export declare function extractUrlsFromParsedSitemap(parsed: any, origin: string
  * Fetches and parses a sitemap (or sitemap index, recursed up to a small
  * depth) into a flat, deduped list of same-origin URLs.
  */
-export declare function fetchSitemapUrls(sitemapUrl: string, origin: string, depth?: number, dispatcher?: any): Promise<string[]>;
+export declare function fetchSitemapUrls(sitemapUrl: string, origin: string, depth?: number, dispatcher?: any, maxUrls?: number): Promise<string[]>;
 /**
  * Discovers a project's sitemap (default `${origin}/sitemap.xml`, or an
  * explicit override) and returns the URLs it lists. Never throws.

package/types/state-graph.d.ts

@@ -0,0 +1,59 @@
+import type { Page } from 'playwright';
+export declare function simHash32(text: string): number;
+export declare function hammingDistance32(a: number, b: number): number;
+export declare function normalizeUrl(raw: string): string;
+export declare function computeStateId(normalizedUrl: string, hash: number): string;
+export interface UIStateNode {
+    id: string;
+    url: string;
+    normalizedUrl: string;
+    title: string;
+    interactiveElementCount: number;
+    domFingerprint: string;
+    simHashValue: number;
+    visitedAt: string;
+}
+export interface StateTransition {
+    fromId: string;
+    toId: string;
+    action: string;
+    label: string;
+    triggeredAt: string;
+}
+export interface CoverageReport {
+    totalStates: number;
+    totalTransitions: number;
+    uniqueUrls: number;
+    interactiveElementsTotal: number;
+    estimatedCoveragePercent: number;
+}
+export declare function fingerprintPage(page: Page, visitedAt: string): Promise<{
+    fingerprint: string;
+    visibleText: string;
+    interactiveCount: number;
+    simHashValue: number;
+}>;
+export declare class ScreenTransitionGraph {
+    private states;
+    private transitions;
+    /** Maps simHash value → array of state ids with that hash (for near-dup lookup) */
+    private hashIndex;
+    addState(node: UIStateNode): {
+        added: boolean;
+        duplicateOf?: string;
+    };
+    addTransition(fromId: string, toId: string, action: string, label: string, triggeredAt: string): void;
+    isDuplicate(url: string, visibleText: string, threshold?: number): boolean;
+    getCoverageReport(): CoverageReport;
+    toJSON(): {
+        states: UIStateNode[];
+        transitions: StateTransition[];
+    };
+    static fromJSON(data: {
+        states: UIStateNode[];
+        transitions: StateTransition[];
+    }): ScreenTransitionGraph;
+    getState(id: string): UIStateNode | undefined;
+    getAllStates(): UIStateNode[];
+    getTransitionsFrom(id: string): StateTransition[];
+}