harnery 0.32.0 → 0.34.0

package/dist/lib/browser/geometry.js

@@ -312,6 +312,53 @@ export function buildLayoutLintCheck() {
             const clips = new Set(["hidden", "clip", "auto", "scroll"]);
             return { x: clips.has(style.overflowX), y: clips.has(style.overflowY) };
         };
+        // The visually-hidden idiom (Tailwind `sr-only`, Bootstrap
+        // `visually-hidden`): a ~1px absolutely-positioned box whose content is
+        // clipped ON PURPOSE so it exists for assistive tech only. Its box is 1x1
+        // (not zero-area, so the zero-area exclusion misses it) and the legacy
+        // `clip: rect(0,0,0,0)` it relies on is not an overflow style, so nothing
+        // above recognizes it. Reporting it would flag every accessible page.
+        const isVisuallyHidden = (element) => {
+            const style = getComputedStyle(element);
+            if (style.position !== "absolute" && style.position !== "fixed")
+                return false;
+            if (style.clip && style.clip !== "auto")
+                return true;
+            const rect = element.getBoundingClientRect();
+            return rect.width <= 1 && rect.height <= 1 && style.overflow === "hidden";
+        };
+        const hasVisuallyHiddenAncestor = (start, scope) => {
+            let current = start;
+            while (current && scope.contains(current)) {
+                if (isVisuallyHidden(current))
+                    return true;
+                if (current === scope)
+                    break;
+                current = current.parentElement;
+            }
+            return false;
+        };
+        // Deliberate single-line truncation (`text-overflow: ellipsis` + nowrap +
+        // hidden overflow, the `truncate` utility): cutting the text is the
+        // design, and the dedicated truncation check owns auditing it. Only text
+        // under such an ancestor is exempt; element boxes still have to fit.
+        const ellipsizes = (element) => {
+            const style = getComputedStyle(element);
+            return (style.textOverflow === "ellipsis" &&
+                style.whiteSpace === "nowrap" &&
+                (style.overflowX === "hidden" || style.overflowX === "clip"));
+        };
+        const hasEllipsizingAncestor = (start, scope) => {
+            let current = start;
+            while (current && scope.contains(current)) {
+                if (ellipsizes(current))
+                    return true;
+                if (current === scope)
+                    break;
+                current = current.parentElement;
+            }
+            return false;
+        };
         // A scroller hides content the same way a clip does, but the reader can
         // reach it. Content below the fold of a capped table or right of a wide
         // code block is not a layout defect, so an axis stops being checked at the
@@ -323,6 +370,17 @@ export function buildLayoutLintCheck() {
             const scrolls = new Set(["auto", "scroll"]);
             return { x: scrolls.has(style.overflowX), y: scrolls.has(style.overflowY) };
         };
+        const scrollsBeforeScope = (start, scope, axis) => {
+            let current = start;
+            while (current && scope.contains(current)) {
+                if (scrollingStyle(current)[axis])
+                    return true;
+                if (current === scope)
+                    break;
+                current = current.parentElement;
+            }
+            return false;
+        };
         const unbounded = () => ({
             x: Number.NEGATIVE_INFINITY,
             y: Number.NEGATIVE_INFINITY,
@@ -381,7 +439,14 @@ export function buildLayoutLintCheck() {
                 };
                 const maxOverrunPx = Math.max(overrun.top, overrun.right, overrun.bottom, overrun.left);
                 if (maxOverrunPx > tolerancePx + SUBPIXEL_EPSILON && issues.length < ISSUE_LIMIT) {
-                    issues.push({ element, clippedBy, overrun, maxOverrunPx });
+                    const horizontalOverrun = Math.max(overrun.left, overrun.right);
+                    const verticalOverrun = Math.max(overrun.top, overrun.bottom);
+                    issues.push({
+                        element,
+                        clippedBy: horizontalOverrun >= verticalOverrun ? clippedBy.x : clippedBy.y,
+                        overrun,
+                        maxOverrunPx,
+                    });
                 }
             };
             // Walk from `start` up to `container`, intersecting the allowed rect with
@@ -391,7 +456,7 @@ export function buildLayoutLintCheck() {
             // are reachable and so are exempt.
             const clipChain = (start, container, seed, seedLabel) => {
                 let allowed = { ...seed };
-                let clippedBy = seedLabel;
+                const clippedBy = { x: seedLabel, y: seedLabel };
                 const free = { x: false, y: false };
                 let current = start;
                 while (current && container.contains(current)) {
@@ -412,6 +477,12 @@ export function buildLayoutLintCheck() {
                     };
                     if (clips.x || clips.y) {
                         const candidate = paddingRect(current);
+                        const tightensX = clips.x &&
+                            (candidate.left > allowed.left + SUBPIXEL_EPSILON ||
+                                candidate.right < allowed.right - SUBPIXEL_EPSILON);
+                        const tightensY = clips.y &&
+                            (candidate.top > allowed.top + SUBPIXEL_EPSILON ||
+                                candidate.bottom < allowed.bottom - SUBPIXEL_EPSILON);
                         allowed = {
                             x: clips.x ? Math.max(allowed.left, candidate.left) : allowed.left,
                             y: clips.y ? Math.max(allowed.top, candidate.top) : allowed.top,
@@ -424,7 +495,13 @@ export function buildLayoutLintCheck() {
                         };
                         allowed.width = Math.max(0, allowed.right - allowed.left);
                         allowed.height = Math.max(0, allowed.bottom - allowed.top);
-                        clippedBy = labelOf(current);
+                        // Keep the label of the boundary that actually made each axis
+                        // smaller. A wider outer scope should not hide the nearer parent
+                        // responsible for a horizontal overrun.
+                        if (tightensX)
+                            clippedBy.x = labelOf(current);
+                        if (tightensY)
+                            clippedBy.y = labelOf(current);
                     }
                     if (scrolls.x)
                         free.x = true;
@@ -436,7 +513,7 @@ export function buildLayoutLintCheck() {
                 }
                 return { allowed, clippedBy };
             };
-            const textContainer = (node, scope) => {
+            const nearestBlockOwner = (node, scope) => {
                 let current = node.parentElement;
                 while (current && scope.contains(current)) {
                     if (current instanceof SVGElement)
@@ -460,12 +537,36 @@ export function buildLayoutLintCheck() {
                         excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "hidden" });
                         return;
                     }
+                    if (hasVisuallyHiddenAncestor(element, container)) {
+                        excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "visually-hidden" });
+                        return;
+                    }
                     const rect = element.getBoundingClientRect();
                     if (rect.width <= 0 || rect.height <= 0) {
                         excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "zero-area" });
                         return;
                     }
-                    const chain = clipChain(element.parentElement, container, unbounded(), labelOf(container));
+                    // CSS overflow defaults to visible, so a child can escape a grid or
+                    // flex cell without any clipping ancestor noticing. Constrain
+                    // in-flow boxes horizontally to their nearest block owner. Vertical
+                    // parent containment is intentionally left to real CSS clips because
+                    // normal margin collapse can paint outside a parent's vertical box.
+                    const owner = nearestBlockOwner(element, container);
+                    const seed = unbounded();
+                    let seedLabel = labelOf(container);
+                    const position = getComputedStyle(element).position;
+                    if (owner &&
+                        position !== "absolute" &&
+                        position !== "fixed" &&
+                        !scrollsBeforeScope(owner, container, "x")) {
+                        const ownerRect = paddingRect(owner);
+                        seed.left = ownerRect.left;
+                        seed.right = ownerRect.right;
+                        seed.x = seed.left;
+                        seed.width = Math.max(0, seed.right - seed.left);
+                        seedLabel = labelOf(owner);
+                    }
+                    const chain = clipChain(element.parentElement, container, seed, seedLabel);
                     recordIssue(measure(element, index, false), chain.allowed, chain.clippedBy);
                 });
                 const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
@@ -484,9 +585,25 @@ export function buildLayoutLintCheck() {
                         isHidden(parent)) {
                         continue;
                     }
-                    const owner = textContainer(node, container);
+                    const owner = nearestBlockOwner(node, container);
                     if (!owner)
                         continue;
+                    if (hasVisuallyHiddenAncestor(parent, container)) {
+                        excluded.push({
+                            index: measurementIndex++,
+                            tag: parent.tagName.toLowerCase(),
+                            reason: "visually-hidden",
+                        });
+                        continue;
+                    }
+                    if (hasEllipsizingAncestor(parent, container)) {
+                        excluded.push({
+                            index: measurementIndex++,
+                            tag: parent.tagName.toLowerCase(),
+                            reason: "ellipsis-truncation",
+                        });
+                        continue;
+                    }
                     let transformed = false;
                     let current = owner;
                     while (current && container.contains(current)) {
@@ -645,6 +762,11 @@ export function buildLayoutLintCheck() {
             "COL",
             "COLGROUP",
         ]);
+        // Code-family chips are inline controls, not layout cards, but the
+        // radius-vs-size pill test misses them (a code chip's radius is modest)
+        // and a flex/grid tag row blockifies their computed display, defeating
+        // the inline-display exclusion. Exclude them by tag.
+        const CONTROL_TAGS = new Set(["CODE", "KBD", "SAMP", "VAR", "OUTPUT"]);
         const maxCornerRadiusPx = (style, minDim) => {
             const corners = [
                 "border-top-left-radius",
@@ -666,6 +788,8 @@ export function buildLayoutLintCheck() {
         const isPanel = (element) => {
             if (STRUCTURAL_TAGS.has(element.tagName))
                 return false;
+            if (CONTROL_TAGS.has(element.tagName))
+                return false;
             const style = getComputedStyle(element);
             if (style.display.startsWith("table") || style.display.startsWith("inline"))
                 return false;

package/dist/lib/browser/index.d.ts

@@ -9,8 +9,11 @@ export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export type { OverflowElement, OverflowResult, WidthResult, } from "./layout.js";
 export { serializeNetscapeCookies, writeNetscapeCookieFile, } from "./netscape-cookies.js";
 export { type BrowserProxy, type BrowserProxyGate, browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
+export { buildQaManifest, type ChangeClass, type ClassifyOptions, classifySignatures, fnv1a32, type ManifestOptions, type QaClassification, type QaContext, type QaManifest, type QaNodeSignature, type QaScope, type QaSignature, type QaStylesheetSignature, } from "./qa-plan.js";
+export { listQaSnapshotTargets, loadQaSnapshot, QA_SNAPSHOT_DIR, type QaSnapshotStoreOptions, qaSnapshotKey, type ResolvedQaBaseline, resolveQaBaseline, type StoredQaSnapshot, saveQaSnapshot, } from "./qa-snapshot.js";
 export type { RuntHit, RuntsResult, } from "./runts.js";
 export { BROWSER_SESSION_MAX_FILL_BYTES, BROWSER_SESSION_MAX_FRAME_BYTES, BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES, BROWSER_SESSION_PROTOCOL_VERSION, type BrowserSessionDescriptor, BrowserSessionError, type BrowserSessionRequest, type BrowserSessionResponse, type BrowserSessionResult, type BrowserSessionServer, type BrowserSessionTarget, browserSessionTransport, readBrowserSessionDescriptor, sendBrowserSessionRequest, startBrowserSessionServer, } from "./session-control.js";
 export type { TargetSizeNode, TargetSizeOutcome, TargetSizeProfile, TargetSizeResult, } from "./target-size.js";
+export { bandOversizedRect, cutCost, type SnapOptions, type SnapSeam, snappedBandRects, type VisualAtom, } from "./tiling.js";
 export type { CheckVisibilityOptions, VisibilityResult, VisibilitySample, } from "./visibility.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,OAAO,EACP,SAAS,EACT,UAAU,EACV,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,yCAAyC,EACzC,gCAAgC,EAChC,KAAK,wBAAwB,EAC7B,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/index.js

@@ -6,4 +6,7 @@ export { buildLayoutLintCheck } from "./geometry.js";
 export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export { serializeNetscapeCookies, writeNetscapeCookieFile, } from "./netscape-cookies.js";
 export { browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
+export { buildQaManifest, classifySignatures, fnv1a32, } from "./qa-plan.js";
+export { listQaSnapshotTargets, loadQaSnapshot, QA_SNAPSHOT_DIR, qaSnapshotKey, resolveQaBaseline, saveQaSnapshot, } from "./qa-snapshot.js";
 export { BROWSER_SESSION_MAX_FILL_BYTES, BROWSER_SESSION_MAX_FRAME_BYTES, BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES, BROWSER_SESSION_PROTOCOL_VERSION, BrowserSessionError, browserSessionTransport, readBrowserSessionDescriptor, sendBrowserSessionRequest, startBrowserSessionServer, } from "./session-control.js";
+export { bandOversizedRect, cutCost, snappedBandRects, } from "./tiling.js";

package/dist/lib/browser/qa-plan.d.ts

@@ -0,0 +1,174 @@
+/** FNV-1a 32-bit over a string, hex-encoded, with a length suffix so the
+ * (tiny) collision surface also has to match on length. Used for text and
+ * stylesheet digests — a comparison fingerprint, not a security hash. */
+export declare function fnv1a32(text: string): string;
+/** One element's structural fingerprint inside a captured page. */
+export interface QaNodeSignature {
+    /** Structural path from body: `body>div:0>table:1>tr:4>td:2` (index among
+     * element siblings). Position-sensitive by design — reordering IS a
+     * structural change. */
+    path: string;
+    tag: string;
+    /** Canonical attribute string: sorted `name=value` pairs joined with \x1f.
+     * Raw (not digested) so a reviewer can see WHICH attribute changed. */
+    attrs: string;
+    /** Digest of the element's direct text-node content (whitespace-normalized),
+     * absent when the element has no direct text. */
+    text?: string;
+    /** Digest of opaque rendered content whose pixels can change without a DOM
+     * structure or attribute change (for example SVG descendants or a canvas
+     * bitmap). `unavailable` widens to unknown because text-only cannot be
+     * proven without this evidence. */
+    visual?: string;
+    /** Nearest strict-ancestor stable anchor (unique `#id` or
+     * `[data-qa-scope="…"]`), with the anchor element's own path so nested
+     * anchors can be deduped to the outermost root. Absent for nodes with no
+     * anchored ancestor (e.g. direct children of body on an anchor-free page). */
+    anchor?: {
+        selector: string;
+        path: string;
+    };
+}
+export interface QaStylesheetSignature {
+    /** External sheet href, or `inline:<index>` for a `<style>` block. */
+    key: string;
+    kind: "external" | "inline";
+    /** Content digest, or the literal `"unavailable"` when the sheet's text
+     * could not be read (cross-origin without CORS). Unavailable digests widen
+     * classification to `unknown` — style stability can't be proven. */
+    digest: string;
+}
+/** A captured page signature: everything the classifier needs, nothing the
+ * critique engine does. Produced by the browser client, persisted by the
+ * snapshot store. */
+export interface QaSignature {
+    url: string;
+    /** ISO capture time. */
+    capturedAt: string;
+    nodes: QaNodeSignature[];
+    stylesheets: QaStylesheetSignature[];
+    /** True when the capture hit its node cap. A truncated signature cannot
+     * prove absence of change — the classifier widens to `unknown`. */
+    truncated?: boolean;
+}
+export type ChangeClass = "text-data-only" | "local-visual" | "interaction-state" | "large-structural" | "unknown";
+export interface QaScope {
+    selector: string;
+    reason: string;
+    /** How many elements the selector matched at capture time (1 for anchors —
+     * uniqueness is verified during capture; explicit selectors carry the
+     * caller-counted value). */
+    matches: number;
+}
+export interface QaClassification {
+    /** `interaction-state` is never inferred from signatures — it is declared
+     * by explicit state inputs at manifest time. */
+    change_class: Exclude<ChangeClass, "interaction-state">;
+    reasons: string[];
+    /** Paths whose direct text content changed (structure + attrs identical). */
+    text_changed_paths: string[];
+    /** Paths added, removed, or with changed attributes. */
+    structural_changed_paths: string[];
+    /** Stylesheet keys whose digest changed, appeared, or disappeared. */
+    stylesheets_changed: string[];
+    /** Stable scope roots covering every structural change (local-visual only). */
+    scopes: QaScope[];
+    /** True when baseline and current are indistinguishable. */
+    identical: boolean;
+}
+export interface ClassifyOptions {
+    /** More distinct scope roots than this widens to large-structural: a change
+     * that touches many independent regions is a page-level change no matter
+     * how well-anchored each region is. Default 4. */
+    maxScopes?: number;
+}
+/**
+ * Classify current against baseline. Pure: no browser, no filesystem. The
+ * bias is stated in the plan and enforced here — ambiguity widens (to
+ * `unknown`/`large-structural`), never narrows. A `null` baseline is the
+ * "no baseline available" case and is always `unknown`.
+ */
+export declare function classifySignatures(baseline: QaSignature | null, current: QaSignature, opts?: ClassifyOptions): QaClassification;
+export interface QaContext {
+    viewport: string;
+    theme: "light" | "dark";
+    state: string;
+}
+export interface QaManifest {
+    schema_version: 1;
+    change_class: ChangeClass;
+    classification_reasons: string[];
+    source_revision?: string;
+    baseline_revision?: string;
+    /** Which resolution-order source produced the baseline:
+     * `qa-snapshot:<capturedAt>`, `production-render:<capturedAt>`,
+     * `revision-render:<rev>`, or `none`. */
+    baseline_source: string;
+    scopes: QaScope[];
+    contexts: QaContext[];
+    checks: {
+        deterministic: string[];
+        /** Assertions that prove named interaction states behaved correctly. */
+        interaction: string[];
+        visual: "none" | "scoped" | "full-page";
+    };
+    concurrency: {
+        headless: number;
+        metered: number;
+    };
+    reuse: {
+        mode: "none" | "exact-digest" | "band-diff";
+        cache: boolean;
+    };
+    /** Provider-call ceiling for the plan, so cost is visible before execution.
+     * Full-page tile counts need a rendered page; callers pass an estimate. */
+    predicted: {
+        tiles_ceiling: number;
+        model_calls_ceiling: number;
+    };
+    /** Present when the run cannot produce a trustworthy verdict (e.g. unknown
+     * class without permission to widen). An incomplete run is never a pass. */
+    incomplete?: {
+        reason: string;
+    };
+}
+export interface ManifestOptions {
+    baselineSource: string;
+    sourceRevision?: string;
+    baselineRevision?: string;
+    /** Explicit scope selectors from the producing task — resolution order rung
+     * 1; they override lifted anchors entirely. */
+    explicitScopes?: QaScope[];
+    /** Named interaction states to review (before/after pairs, etc.). Any
+     * non-empty list promotes a text/local classification to
+     * `interaction-state` and appends one context per state. */
+    states?: string[];
+    /** Viewports for the full matrix (default ["desktop", "mobile"]). */
+    viewports?: string[];
+    /** Estimated full-page tile count per context, from the caller's render
+     * knowledge (page height / band step, capped). Default 24 (the tile cap). */
+    estimatedFullPageTiles?: number;
+    concurrency?: {
+        headless: number;
+        metered: number;
+    };
+    reuse?: {
+        mode: "none" | "exact-digest" | "band-diff";
+        cache: boolean;
+    };
+    deterministicChecks?: string[];
+    /** Value/behavior assertions paired with explicit interaction states. */
+    outcomeAssertions?: string[];
+    /** When false (default), an `unknown` classification widens to full
+     * large-structural coverage. When true, the manifest instead marks itself
+     * incomplete with zero contexts — the caller wants a hard stop. */
+    stopOnUnknown?: boolean;
+}
+/**
+ * Turn a classification into an executable review manifest. Pure: rendering,
+ * baseline acquisition, and critique execution stay in the caller. The
+ * separation is the point — the manifest can be printed by a dry run,
+ * reviewed, and overridden before expensive work starts.
+ */
+export declare function buildQaManifest(classification: QaClassification, opts: ManifestOptions): QaManifest;
+//# sourceMappingURL=qa-plan.d.ts.map

package/dist/lib/browser/qa-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qa-plan.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-plan.ts"],"names":[],"mappings":"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"}