@webability/core 1.1.3 → 1.1.4

package/dist/index.d.cts

@@ -52,6 +52,11 @@ interface DetectedIssue {
 interface FixDetector {
     name: string;
     detect(page: PageLike): Promise<DetectedIssue[]>;
+    /** Per-page emission cap, when the detector has one. When a run returns
+     *  >= cap findings the results are TRUNCATED (DOM-order biased) and the
+     *  scan reports it via ScanResult.truncated — silent truncation reads as
+     *  "covered everything" when it didn't (loop iter8 / honesty infra). */
+    cap?: number;
 }
 /**
  * Browser-runtime detector signature.
@@ -116,6 +121,21 @@ interface ScanResult {
     timestamp: string;
     /** High-confidence violations. Safe to surface as bugs. */
     issues: ScanIssue[];
+    /** Detectors that hit their per-page cap this run — their counts are lower
+     *  bounds, not a census. Additive field; absent = nothing truncated. */
+    truncated?: Array<{
+        detector: string;
+        cap: number;
+    }>;
+    /**
+     * Non-fatal engine subsystem failures that silently disable a category of
+     * checks. Consumers MUST surface these to the user — a result with
+     * `engineWarnings` is NOT a full scan. Currently: `'color:kernel-injection-failed'`
+     * disables all contrast checks for the page. Absent = all subsystems healthy.
+     */
+    engineWarnings?: string[];
+    /** Engine (core package) version that produced this result — provenance */
+    engine?: string;
     /**
      * Findings the classifier or axe-core flagged as ambiguous. Show to the user
      * for review — never auto-fix. Empty array (not omitted) when no incompletes,
@@ -160,11 +180,27 @@ interface ScanOptions {
     enableScreenshots?: boolean;
     /** Scan content inside iframes. Default: false. */
     includeIframes?: boolean;
+    /**
+     * Wait for entrance animations to finish before scanning (prevents false
+     * contrast failures on mid-fade text). `false` disables, a number sets the
+     * wait cap in ms. Default: enabled with a 4000ms cap.
+     */
+    settle?: boolean | number;
 }
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
-declare function runDetectors(page: PageLike): Promise<DetectedIssue[]>;
+type TruncationEntry = {
+    detector: string;
+    cap: number;
+};
+/**
+ * `outTruncated` collects which detectors hit their per-page cap THIS call.
+ * `outWarnings` collects non-fatal engine subsystem failures (e.g. kernel
+ * injection blocked by CSP) that silently disable a category of checks.
+ * Both arrays are per-invocation (caller-owned), never module state.
+ */
+declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[]): Promise<DetectedIssue[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
 interface AxeViolation {

package/dist/index.d.ts

@@ -52,6 +52,11 @@ interface DetectedIssue {
 interface FixDetector {
     name: string;
     detect(page: PageLike): Promise<DetectedIssue[]>;
+    /** Per-page emission cap, when the detector has one. When a run returns
+     *  >= cap findings the results are TRUNCATED (DOM-order biased) and the
+     *  scan reports it via ScanResult.truncated — silent truncation reads as
+     *  "covered everything" when it didn't (loop iter8 / honesty infra). */
+    cap?: number;
 }
 /**
  * Browser-runtime detector signature.
@@ -116,6 +121,21 @@ interface ScanResult {
     timestamp: string;
     /** High-confidence violations. Safe to surface as bugs. */
     issues: ScanIssue[];
+    /** Detectors that hit their per-page cap this run — their counts are lower
+     *  bounds, not a census. Additive field; absent = nothing truncated. */
+    truncated?: Array<{
+        detector: string;
+        cap: number;
+    }>;
+    /**
+     * Non-fatal engine subsystem failures that silently disable a category of
+     * checks. Consumers MUST surface these to the user — a result with
+     * `engineWarnings` is NOT a full scan. Currently: `'color:kernel-injection-failed'`
+     * disables all contrast checks for the page. Absent = all subsystems healthy.
+     */
+    engineWarnings?: string[];
+    /** Engine (core package) version that produced this result — provenance */
+    engine?: string;
     /**
      * Findings the classifier or axe-core flagged as ambiguous. Show to the user
      * for review — never auto-fix. Empty array (not omitted) when no incompletes,
@@ -160,11 +180,27 @@ interface ScanOptions {
     enableScreenshots?: boolean;
     /** Scan content inside iframes. Default: false. */
     includeIframes?: boolean;
+    /**
+     * Wait for entrance animations to finish before scanning (prevents false
+     * contrast failures on mid-fade text). `false` disables, a number sets the
+     * wait cap in ms. Default: enabled with a 4000ms cap.
+     */
+    settle?: boolean | number;
 }
 
 declare function scan(target: string | PageLike, options?: ScanOptions): Promise<ScanResult>;
 
-declare function runDetectors(page: PageLike): Promise<DetectedIssue[]>;
+type TruncationEntry = {
+    detector: string;
+    cap: number;
+};
+/**
+ * `outTruncated` collects which detectors hit their per-page cap THIS call.
+ * `outWarnings` collects non-fatal engine subsystem failures (e.g. kernel
+ * injection blocked by CSP) that silently disable a category of checks.
+ * Both arrays are per-invocation (caller-owned), never module state.
+ */
+declare function runDetectors(page: PageLike, outTruncated?: TruncationEntry[], outWarnings?: string[]): Promise<DetectedIssue[]>;
 declare function extractSiteTheme(page: PageLike): Promise<SiteTheme>;
 
 interface AxeViolation {