@webability/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+/**
+ * @webability/core — type definitions
+ */
+/**
+ * Minimal page interface satisfied by both Playwright and Puppeteer.
+ * No runtime wrapper needed — both libraries implement these methods natively.
+ */
+interface PageLike {
+    evaluate<R>(pageFunction: string | ((...args: any[]) => R | Promise<R>), ...args: any[]): Promise<R>;
+    addScriptTag(options: {
+        content: string;
+    }): Promise<unknown>;
+    url(): string;
+}
+/** All fix issue types the pipeline can detect and fix. */
+type FixIssueType = 'weak_button_name' | 'weak_link_name' | 'weak_heading' | 'weak_iframe_title' | 'weak_page_title' | 'weak_svg_name' | 'weak_skip_link' | 'missing_button_role' | 'missing_semantic_role' | 'missing_landmark' | 'heading_skip' | 'svg_missing_name' | 'aria_hidden_focusable' | 'adjacent_redundant_link' | 'contrast_insufficient' | 'non_text_contrast_insufficient' | 'target_too_small' | 'focus_not_visible' | 'empty_link' | 'unlabeled_button' | 'missing_label' | 'decorative_icon' | 'skip_link' | 'aria_live' | 'missing_alt' | 'identify_input_purpose' | 'redundant_role' | 'duplicate_id' | 'new_window_link' | 'missing_fieldset_legend' | 'missing_table_header' | 'missing_table_caption' | 'missing_table_scope' | 'external_link_warning' | 'download_link_warning' | 'broken_anchor' | 'placeholder_link' | 'missing_aria_required' | 'missing_pattern_title' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'invalid_aria_role' | 'zoom_restriction' | 'missing_button_type' | 'link_consistency' | 'semantic_emphasis' | 'keyboard_trap' | 'focus_order_disruption' | 'missing_captions' | 'color_only_link' | 'label_in_name' | 'onfocus_context_change' | 'focus_obscured_by_sticky' | 'text_spacing_blocked' | 'nested_landmark' | 'combobox_name_missing' | 'landmark_duplicate_unlabeled' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'missing_h1' | 'multiple_h1' | 'empty_heading' | 'javascript_link' | 'broken_aria_reference' | 'main_content_hidden' | 'scrollable_not_focusable' | 'meaningful_sequence' | 'sensory_characteristic' | 'orientation_lock' | 'image_of_text' | 'reflow_overflow' | 'missing_audio_description' | 'missing_transcript' | 'character_key_shortcut' | 'on_input_change' | 'pointer_gesture' | 'pointer_cancellation' | 'motion_actuation' | 'error_prevention_missing' | 'insufficient_navigation' | 'inconsistent_navigation';
+/** WCAG criterion for each issue type. */
+declare const WCAG_BY_ISSUE: Record<FixIssueType, string>;
+/** A single accessibility issue detected on the page. */
+interface DetectedIssue {
+    /** Unique CSS selector targeting the element. */
+    selector: string;
+    /** HTML/ARIA attribute to set (alt, aria-label, role, tabindex, etc.) */
+    attribute: string;
+    /** What the element currently has (empty string if missing). */
+    currentValue: string;
+    /** Classification of the issue. */
+    issueType: FixIssueType;
+    /** WCAG success criterion reference. */
+    wcag: string;
+    /** Contextual info for Claude: nearby heading, parent tag, href, page section. */
+    context: string;
+    /** true = needs Claude to generate the fix value; false = rule already knows it. */
+    needsAI: boolean;
+    /** When needsAI is false, this is the known fix value. */
+    fixValue?: string;
+    /** Optional: image src for alt text generation via vision. */
+    imageSrc?: string;
+    /** Optional: outer HTML snippet (first 300 chars) for Claude context. */
+    outerHtml?: string;
+}
+/** Every fix detector must implement this interface. */
+interface FixDetector {
+    name: string;
+    detect(page: PageLike): Promise<DetectedIssue[]>;
+}
+/**
+ * Browser-runtime detector signature.
+ *
+ * Each detector exports a pure, zero-argument browser function that uses the
+ * `document` global directly and returns DetectedIssue[]. No Puppeteer, no
+ * Node imports, no closures over module-scope variables — so it both:
+ *   1. Survives serialization via `page.evaluate(fn)` on the server (puppeteer
+ *      stringifies and re-parses the function inside the browser context).
+ *   2. Bundles directly into the widget via webpack and runs against the
+ *      live customer DOM.
+ *
+ * Single source of truth — same rules run in both runtimes.
+ */
+type BrowserDetector = () => DetectedIssue[];
+interface SiteTheme {
+    cssVars: Record<string, string>;
+    topBgColors: Array<{
+        color: string;
+        count: number;
+    }>;
+    topTextColors: Array<{
+        color: string;
+        count: number;
+    }>;
+}
+type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
+type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
+type WcagLevel = 'A' | 'AA' | 'AAA';
+interface ScanIssue {
+    id: string;
+    source: IssueSource;
+    type: FixIssueType | string;
+    wcag: string;
+    level: WcagLevel;
+    impact: IssueImpact;
+    message: string;
+    selector: string;
+    html?: string;
+    fix?: {
+        attribute: string;
+        currentValue: string;
+        suggestedValue?: string;
+        needsManualReview: boolean;
+    };
+}
+interface ScanResult {
+    url: string;
+    timestamp: string;
+    issues: ScanIssue[];
+    summary: {
+        total: number;
+        critical: number;
+        serious: number;
+        moderate: number;
+        minor: number;
+    };
+    axeResults?: unknown;
+}
+type ViewportPreset = 'mobile' | 'tablet' | 'desktop';
+declare const VIEWPORT_SIZES: Record<ViewportPreset, {
+    width: number;
+    height: number;
+}>;
+interface ScanOptions {
+    wcagTags?: string[];
+    includeAxe?: boolean;
+    deep?: boolean;
+    deepApiUrl?: string;
+    deepApiKey?: string;
+    dismissModals?: boolean;
+    viewport?: ViewportPreset | {
+        width: number;
+        height: number;
+    };
+    browser?: {
+        headless?: boolean;
+        timeout?: number;
+    };
+    review?: boolean;
+    /** Limit scan to elements within this CSS selector. */
+    rootSelector?: string;
+    /** Include annotated screenshots of violations in results. */
+    enableScreenshots?: boolean;
+    /** Scan content inside iframes. Default: false. */
+    includeIframes?: boolean;
+}
+
+declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
+
+declare function runDetectors(page: PageLike): Promise<DetectedIssue[]>;
+declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
+
+interface AxeViolation {
+    id: string;
+    impact: string;
+    description: string;
+    help: string;
+    helpUrl: string;
+    tags: string[];
+    nodes: Array<{
+        html: string;
+        target: string[];
+        failureSummary?: string;
+    }>;
+}
+interface AxeRunResult {
+    violations: AxeViolation[];
+    incomplete: AxeViolation[];
+    passes: AxeViolation[];
+    inapplicable: AxeViolation[];
+}
+declare function runAxe(page: PageLike, tags: string[]): Promise<AxeRunResult>;
+
+declare function dismissModals(page: PageLike): Promise<void>;
+
+declare function toHtmlReport(result: ScanResult): string;
+
+export { type BrowserDetector, type DetectedIssue, type FixDetector, type FixIssueType, type IssueImpact, type IssueSource, type PageLike, type ScanIssue, type ScanOptions, type ScanResult, type SiteTheme, VIEWPORT_SIZES, type ViewportPreset, WCAG_BY_ISSUE, type WcagLevel, dismissModals, extractSiteTheme, runAxe, runDetectors, scan, toHtmlReport };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @webability/core — type definitions
+ */
+/**
+ * Minimal page interface satisfied by both Playwright and Puppeteer.
+ * No runtime wrapper needed — both libraries implement these methods natively.
+ */
+interface PageLike {
+    evaluate<R>(pageFunction: string | ((...args: any[]) => R | Promise<R>), ...args: any[]): Promise<R>;
+    addScriptTag(options: {
+        content: string;
+    }): Promise<unknown>;
+    url(): string;
+}
+/** All fix issue types the pipeline can detect and fix. */
+type FixIssueType = 'weak_button_name' | 'weak_link_name' | 'weak_heading' | 'weak_iframe_title' | 'weak_page_title' | 'weak_svg_name' | 'weak_skip_link' | 'missing_button_role' | 'missing_semantic_role' | 'missing_landmark' | 'heading_skip' | 'svg_missing_name' | 'aria_hidden_focusable' | 'adjacent_redundant_link' | 'contrast_insufficient' | 'non_text_contrast_insufficient' | 'target_too_small' | 'focus_not_visible' | 'empty_link' | 'unlabeled_button' | 'missing_label' | 'decorative_icon' | 'skip_link' | 'aria_live' | 'missing_alt' | 'identify_input_purpose' | 'redundant_role' | 'duplicate_id' | 'new_window_link' | 'missing_fieldset_legend' | 'missing_table_header' | 'missing_table_caption' | 'missing_table_scope' | 'external_link_warning' | 'download_link_warning' | 'broken_anchor' | 'placeholder_link' | 'missing_aria_required' | 'missing_pattern_title' | 'missing_autocomplete' | 'missing_media_controls' | 'unsafe_autoplay' | 'invalid_aria_role' | 'zoom_restriction' | 'missing_button_type' | 'link_consistency' | 'semantic_emphasis' | 'keyboard_trap' | 'focus_order_disruption' | 'missing_captions' | 'color_only_link' | 'label_in_name' | 'onfocus_context_change' | 'focus_obscured_by_sticky' | 'text_spacing_blocked' | 'nested_landmark' | 'combobox_name_missing' | 'landmark_duplicate_unlabeled' | 'motion_uncontrollable' | 'auto_refresh' | 'motion_without_reduced_motion' | 'flashing_content' | 'animated_gif_no_pause' | 'missing_required_indicator' | 'background_image_unlabeled' | 'missing_h1' | 'multiple_h1' | 'empty_heading' | 'javascript_link' | 'broken_aria_reference' | 'main_content_hidden' | 'scrollable_not_focusable' | 'meaningful_sequence' | 'sensory_characteristic' | 'orientation_lock' | 'image_of_text' | 'reflow_overflow' | 'missing_audio_description' | 'missing_transcript' | 'character_key_shortcut' | 'on_input_change' | 'pointer_gesture' | 'pointer_cancellation' | 'motion_actuation' | 'error_prevention_missing' | 'insufficient_navigation' | 'inconsistent_navigation';
+/** WCAG criterion for each issue type. */
+declare const WCAG_BY_ISSUE: Record<FixIssueType, string>;
+/** A single accessibility issue detected on the page. */
+interface DetectedIssue {
+    /** Unique CSS selector targeting the element. */
+    selector: string;
+    /** HTML/ARIA attribute to set (alt, aria-label, role, tabindex, etc.) */
+    attribute: string;
+    /** What the element currently has (empty string if missing). */
+    currentValue: string;
+    /** Classification of the issue. */
+    issueType: FixIssueType;
+    /** WCAG success criterion reference. */
+    wcag: string;
+    /** Contextual info for Claude: nearby heading, parent tag, href, page section. */
+    context: string;
+    /** true = needs Claude to generate the fix value; false = rule already knows it. */
+    needsAI: boolean;
+    /** When needsAI is false, this is the known fix value. */
+    fixValue?: string;
+    /** Optional: image src for alt text generation via vision. */
+    imageSrc?: string;
+    /** Optional: outer HTML snippet (first 300 chars) for Claude context. */
+    outerHtml?: string;
+}
+/** Every fix detector must implement this interface. */
+interface FixDetector {
+    name: string;
+    detect(page: PageLike): Promise<DetectedIssue[]>;
+}
+/**
+ * Browser-runtime detector signature.
+ *
+ * Each detector exports a pure, zero-argument browser function that uses the
+ * `document` global directly and returns DetectedIssue[]. No Puppeteer, no
+ * Node imports, no closures over module-scope variables — so it both:
+ *   1. Survives serialization via `page.evaluate(fn)` on the server (puppeteer
+ *      stringifies and re-parses the function inside the browser context).
+ *   2. Bundles directly into the widget via webpack and runs against the
+ *      live customer DOM.
+ *
+ * Single source of truth — same rules run in both runtimes.
+ */
+type BrowserDetector = () => DetectedIssue[];
+interface SiteTheme {
+    cssVars: Record<string, string>;
+    topBgColors: Array<{
+        color: string;
+        count: number;
+    }>;
+    topTextColors: Array<{
+        color: string;
+        count: number;
+    }>;
+}
+type IssueSource = 'webability' | 'axe-core' | 'deep-analysis';
+type IssueImpact = 'critical' | 'serious' | 'moderate' | 'minor';
+type WcagLevel = 'A' | 'AA' | 'AAA';
+interface ScanIssue {
+    id: string;
+    source: IssueSource;
+    type: FixIssueType | string;
+    wcag: string;
+    level: WcagLevel;
+    impact: IssueImpact;
+    message: string;
+    selector: string;
+    html?: string;
+    fix?: {
+        attribute: string;
+        currentValue: string;
+        suggestedValue?: string;
+        needsManualReview: boolean;
+    };
+}
+interface ScanResult {
+    url: string;
+    timestamp: string;
+    issues: ScanIssue[];
+    summary: {
+        total: number;
+        critical: number;
+        serious: number;
+        moderate: number;
+        minor: number;
+    };
+    axeResults?: unknown;
+}
+type ViewportPreset = 'mobile' | 'tablet' | 'desktop';
+declare const VIEWPORT_SIZES: Record<ViewportPreset, {
+    width: number;
+    height: number;
+}>;
+interface ScanOptions {
+    wcagTags?: string[];
+    includeAxe?: boolean;
+    deep?: boolean;
+    deepApiUrl?: string;
+    deepApiKey?: string;
+    dismissModals?: boolean;
+    viewport?: ViewportPreset | {
+        width: number;
+        height: number;
+    };
+    browser?: {
+        headless?: boolean;
+        timeout?: number;
+    };
+    review?: boolean;
+    /** Limit scan to elements within this CSS selector. */
+    rootSelector?: string;
+    /** Include annotated screenshots of violations in results. */
+    enableScreenshots?: boolean;
+    /** Scan content inside iframes. Default: false. */
+    includeIframes?: boolean;
+}
+
+declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
+
+declare function runDetectors(page: PageLike): Promise<DetectedIssue[]>;
+declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
+
+interface AxeViolation {
+    id: string;
+    impact: string;
+    description: string;
+    help: string;
+    helpUrl: string;
+    tags: string[];
+    nodes: Array<{
+        html: string;
+        target: string[];
+        failureSummary?: string;
+    }>;
+}
+interface AxeRunResult {
+    violations: AxeViolation[];
+    incomplete: AxeViolation[];
+    passes: AxeViolation[];
+    inapplicable: AxeViolation[];
+}
+declare function runAxe(page: PageLike, tags: string[]): Promise<AxeRunResult>;
+
+declare function dismissModals(page: PageLike): Promise<void>;
+
+declare function toHtmlReport(result: ScanResult): string;
+
+export { type BrowserDetector, type DetectedIssue, type FixDetector, type FixIssueType, type IssueImpact, type IssueSource, type PageLike, type ScanIssue, type ScanOptions, type ScanResult, type SiteTheme, VIEWPORT_SIZES, type ViewportPreset, WCAG_BY_ISSUE, type WcagLevel, dismissModals, extractSiteTheme, runAxe, runDetectors, scan, toHtmlReport };