raven-mcp 1.6.1 → 1.7.0

package/README.md

@@ -18,6 +18,7 @@ Raven gives Claude access to a comprehensive design knowledge base:
 - **Brand & visual** — Logo usage (clear space, min sizes, variants, placement, restraint), gradient usage (hierarchy, palette, contrast, trend vs signature), imagery (consistency, representation, purpose), visual hierarchy, brand-as-system, and current (2026) visual-design trends
 - **Business** — Monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks
 - **Tokens** — Design system tokens for Stripe, Linear, and more
+- **Creative studio** — Local-first brand profiles, asset references, character reference profiles, provider-agnostic image/video/3D/audio generation jobs, campaign plans, and transparent creative scoring. Raven does not ship media-provider credentials; set `RAVEN_CREATIVE_RUNNER` to route jobs to your own renderer.
 
 ## Install
 
@@ -54,7 +55,7 @@ cd raven-mcp && npm install && npm run build
 | `get_principles` | Get design principles relevant to a UI context |
 | `get_pattern` | Get proven patterns for a specific UI type |
 | `get_business_strategy` | Get business/monetization strategies |
-| `evaluate_design` | Evaluate a design description against principles |
+| `evaluate_design` | Evaluate a design description against principles. Pass base64 PNG screenshots (`before_screenshot`/`after_screenshot`) for a structured before/after pixel diff with `fix_confirmed`, `changed_ratio`, and changed region. |
 | `search_knowledge` | Search across all principles, patterns, and strategies |
 | `get_checklist` | Get a pre-publish checklist for a UI type |
 | `get_d4d_framework` | Get Design for Delight framework templates |
@@ -62,8 +63,10 @@ cd raven-mcp && npm install && npm run build
 | `get_design_system` | Get tokens for a specific design system |
 | `compose_system` | Mix tokens from different systems |
 | `get_brand_system` | Get a full system styled like a well-known brand |
-| `audit_page` | Audit HTML/CSS against Raven's quality standards |
+| `audit_page` | Audit HTML/CSS against Raven's quality standards — pass `html` for static audit, or `url` to render headless with optional `scroll_settle` (scroll to bottom + settle reveals) and `viewport` parameters; `containerMaxWidth` makes container checks token-aware |
 | `audit_layout` | Evaluate visual rhythm, alignment, and optical balance |
+| `audit_responsive_visibility` | Render a URL at multiple breakpoints and flag content elements that are visible on desktop but hidden on mobile (display:none/opacity:0/zero-size) — categorises each as likely-oversight (content vanishing on mobile) vs intentional (decorative) |
+| `audit_contrast` | Compute WCAG contrast ratios for every text element on a rendered page and report AA (4.5:1 / 3:1 large) and AAA pass-fail per element, with delta-to-pass for failures |
 | `audit_swiftui` | Audit SwiftUI source against Apple HIG — Dynamic Type, semantic colors, 44pt targets, 4/8pt spacing, AccentColor |
 | `audit_ios_screen` | Score a rendered iOS screen from an accessibility/view-hierarchy snapshot — 44pt targets + contrast + rhythm, in points |
 | `audit_ios_privacy` | Audit Info.plist (or Expo app.json) /PRIVACY.md/entitlements/source — usage-string honesty, ATS, Android permissions, bundled secrets, undisclosed default data-egress |
@@ -80,8 +83,33 @@ cd raven-mcp && npm install && npm run build
 | `generate_service_blueprint` | Render a service blueprint as HTML — current state, or current vs. ideal side-by-side |
 | `get_brand_principles` | Get brand/visual principles — logo, gradient, imagery, hierarchy, brand-as-system |
 | `get_brand_trends` | Get current (2026) brand and visual-design trends with usage guidance |
+| `list_creative_models` | Browse provider-agnostic creative model slots for image, video, 3D, audio, character consistency, and analysis |
+| `list_creative_presets` | Browse creative presets: product photoshoot, marketplace cards, UGC ads, TV spots, social packs, storyboards, infographics |
+| `create_brand_profile` | Create or update a local brand profile for brand-aware creative jobs |
+| `get_brand_profile` | Read a local creative brand profile |
+| `list_brand_profiles` | List local creative brand profiles |
+| `register_creative_asset` | Register a local path or URL as a creative asset reference — no file bytes are uploaded by Raven |
+| `create_character_profile` | Create a local character/identity reference profile from registered assets |
+| `create_generation_job` | Create a provider-agnostic image, video, audio, 3D, campaign, or analysis job payload; optionally execute via `RAVEN_CREATIVE_RUNNER` |
+| `get_generation_job` | Read a creative generation job and its provider payload/output state |
+| `list_generation_jobs` | List local creative generation jobs |
+| `plan_creative_campaign` | Plan a multi-asset campaign and optionally create draft generation jobs |
+| `score_creative` | Score a prompt/script/concept for hook, benefit clarity, product signal, CTA, channel fit, audience fit, and brand fit |
 | `raven_reflect` | Summarize your local Raven usage log to find patterns + gaps |
 
+## Creative studio
+
+Raven now covers the creative-production workflow around media generation without copying or depending on any closed vendor. The tools are orchestration primitives:
+
+- Store brand kits locally with `create_brand_profile`.
+- Register product photos, logos, references, or URLs with `register_creative_asset`.
+- Create character/identity reference sets with `create_character_profile`.
+- Generate provider-ready payloads with `create_generation_job`.
+- Build full campaign shot lists with `plan_creative_campaign`.
+- Score creative concepts with `score_creative`.
+
+By default, jobs are saved as local draft payloads under `~/.raven/creative` (override with `RAVEN_CREATIVE_HOME`). To run real media generation, set `RAVEN_CREATIVE_RUNNER` to an executable that reads one job JSON object from stdin and returns JSON on stdout. That runner can call any provider you choose; Raven never stores API keys in source.
+
 ## iOS / SwiftUI audits
 
 Raven audits native iOS apps against the **Apple Human Interface Guidelines**, not web/CSS conventions. None of the web-only rules (`lang`, `title`, `flex-wrap`, `clamp`, `max-width`, CSS custom properties, bare hex) run on iOS input — and `get_checklist`/`get_principles` take `platform: "ios"` to return HIG items (Dynamic Type, 44pt targets, SF Symbols, safe areas, dark-mode parity, App Review privacy) instead of the web set.
@@ -103,6 +131,63 @@ Anyone building a React Native or Expo app gets the same treatment. RN renders t
 
 **One command:** `node scripts/rn-audit.mjs <app-dir> [--snapshot snap.json] [--md report.md]` discovers screens + `app.json` (reading `userInterfaceStyle` so dark-only apps aren't false-flagged) and runs everything.
 
+## Responsive visibility audits
+
+`audit_responsive_visibility` renders a page at multiple breakpoints (default: 390px mobile, 768px tablet, 1440px desktop, 2160px ultra-wide) and flags content elements that are visible on desktop but hidden on mobile — catching the "vanishes on mobile" bug class. Each flagged element is categorised as **likely-oversight** (content that shouldn't be hidden) or **intentional** (decorative elements). Detects hiding via CSS (`hidden`, `display:none`, `opacity:0`, `visibility:hidden`) and responsive Tailwind classes (`hidden md:block`, etc.).
+
+**Usage:**
+- `audit_responsive_visibility(url)` — render at default breakpoints and flag mismatches.
+- `audit_responsive_visibility(url, [390, 768, 1440])` — custom breakpoints.
+- Optional `viewportHeight` (default: 900px) for tall content.
+
+Returns flagged elements with selector, hiding class, visibility at each breakpoint, and category.
+
+## Contrast audits
+
+`audit_contrast` computes WCAG contrast ratios for every text element on a rendered page, reporting AA (4.5:1 normal text, 3:1 large) and AAA (7:1 normal, 4.5:1 large) pass-fail. Useful for catching small-text / low-contrast pairs that a screenshot eyedropper would catch manually — Raven replaces the math.
+
+**Usage:**
+- `audit_contrast(url)` — render a live page and audit all text.
+- `audit_contrast(dom_snapshot: [{ selector, color, bgColor, fontPx?, bold?, text? }])` — audit a pre-captured snapshot (useful for dynamic or cookie-protected pages).
+
+Returns all text elements scored, failures highlighted with delta-to-pass, and a summary of AA/AAA failure count.
+
+**WCAG math:** Contrast ratio uses linearised luminance (WCAG 2.1 § 1.4.3) — black-on-white is exactly 21, white-on-black is exactly 21. Large text (18.66pt+ bold or 24pt+) needs only 3:1 / 4.5:1 AAA; regular text needs 4.5:1 / 7:1.
+
+## Headless browser audits
+
+`audit_page` can render a live URL in headless Chromium, scroll to settle reveal-on-scroll elements, and play preload=none videos before capturing — preventing false "blank section" reports caused by whileInView states that haven't fired yet.
+
+**Usage:**
+- **Static HTML mode** — pass `html` string for immediate static analysis (existing behavior, no change).
+- **Rendered URL mode** — pass `url` (full HTTP/HTTPS URL). Raven launches Chromium, renders the page, optionally scrolls, and audits the live DOM.
+  - `scroll_settle: true` — scroll from top to bottom in viewport-height steps, then wait 300ms for `IntersectionObserver` / whileInView reveals to fire. Unloaded videos (preload="none") are played to detect if they render blank. This surfaces the real rendered state and avoids false positives on reveal-on-scroll or lazy-loaded content.
+  - `viewport: { w, h }` — set the render viewport (default: `{ w: 1440, h: 900 }`).
+
+**Video artifacts detection:** If any `<video>` with `preload="none"` (or missing preload) renders with `readyState < 2` (i.e. would show a black box in a screenshot), Raven flags it as an `unloaded-video-artifact` in the result. This is **informational** — not a pass/fail — since preload=none is often intentional. On cookie-protected hosts, video requests may fail because iOS/Android media daemons don't send cookies; Raven notes this to help you troubleshoot (e.g. disable deployment protection, use a token-based bypass).
+
+**Adversarial verification:** Set `adversarial_verify: true` to independently re-check each finding against the live DOM using a different method. Findings are tagged:
+- `confirmed` — the finding is real on the live page (e.g. missing `<title>` in the rendered DOM)
+- `likely-artifact` — the finding is an artifact of the static audit method (e.g. a `<video preload="none">` rendered blank, which is expected behavior, not a missing resource)
+- `inconclusive` — the finding cannot be independently verified (e.g. aggregate rules like color-palette size)
+
+The result includes `adversarial_verification: { debunked_count, confirmed_count, inconclusive_count }`, where debunked_count is the number of likely-artifacts. This surfaces false positives so you only fix real issues. Backwards-compatible: when `adversarial_verify` is absent or false, the output is identical to prior versions.
+
+**Setup:** First time only, run `npx playwright install chromium` to download the browser binary. If the binary is missing when you call audit_page with `url`, you'll see a clear instruction to run the install command.
+
+## Before/after design diffs
+
+`evaluate_design` can now accept base64-encoded PNG screenshots to measure whether a fix actually changed the rendered output.
+
+**Usage:**
+- Pass `before_screenshot` and `after_screenshot` (both base64 PNGs, with or without the `data:image/png;base64,` prefix).
+- Raven returns `fix_confirmed: true` if the images differ by > 0.1% of pixels (accounting for jpeg/PNG decode variance).
+- `changed_ratio` — exact fraction of pixels that changed (0–1).
+- `changed_region` — bounding box `{ x, y, w, h }` of the changed pixels (null if no changes detected).
+- `dimensions` — image-derived measurements (canvas size, brightness, color shift) as context, with the caveat that these are pixel-level proxies, not Raven principle scores.
+
+When before/after screenshots are provided alongside a `description`, `evaluate_design` returns both the principle-based evaluation and the pixel diff. When screenshots are provided without a description, the evaluation gracefully skips the principle search and returns the diff only. Backwards-compatible: without screenshots, the tool behaves identically to prior versions.
+
 ## Release updates
 
 Raven ships new principles, patterns, and brand systems regularly. For one email per minor/major release (patches stay quiet):

package/dist/asset-integrity.d.ts

@@ -0,0 +1,13 @@
+export type AssetIntegrityResult = {
+    path: string;
+    bottom_variance: number;
+    verdict: "clean" | "likely-sliced";
+    confidence: number;
+    warnings: string[];
+};
+export type AssetIntegrityOptions = {
+    bottomFraction?: number;
+    minRows?: number;
+    varianceThreshold?: number;
+};
+export declare function auditAssetIntegrity(imagePaths: string[], opts?: AssetIntegrityOptions): Promise<AssetIntegrityResult[]>;

package/dist/asset-integrity.js

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+const DATA_URL_PREFIX = /^data:image\/png;base64,/i;
+export async function auditAssetIntegrity(imagePaths, opts = {}) {
+    // @ts-ignore pngjs is intentionally optional; absence falls back to clean-with-warning.
+    const pngMod = (await import("pngjs").catch(() => null));
+    const PNG = pngMod?.PNG;
+    const readPng = PNG?.sync?.read;
+    return imagePaths.map(function (imagePath) {
+        let buffer;
+        try {
+            buffer = readFileSync(imagePath);
+        }
+        catch (error) {
+            return fallbackResult(imagePath, [
+                "Could not read file: " + errorMessage(error)
+            ]);
+        }
+        if (!readPng) {
+            return fallbackResult(imagePath, [
+                "pngjs not installed — cannot analyze asset integrity"
+            ]);
+        }
+        try {
+            return auditPng(imagePath, readPng(buffer), opts);
+        }
+        catch (error) {
+            return fallbackResult(imagePath, [
+                "Failed to decode PNG: " + errorMessage(error)
+            ]);
+        }
+    });
+}
+function stripPngPrefix(base64) {
+    return base64.replace(DATA_URL_PREFIX, "");
+}
+function fallbackResult(path, warnings) {
+    return {
+        path,
+        bottom_variance: 0,
+        verdict: "clean",
+        confidence: 0,
+        warnings
+    };
+}
+function auditPng(path, png, opts) {
+    const threshold = opts.varianceThreshold ?? 100;
+    const bottomFraction = opts.bottomFraction ?? 0.05;
+    const minRows = opts.minRows ?? 20;
+    const stripHeight = Math.min(png.height, Math.max(minRows, Math.round(png.height * bottomFraction)));
+    const bottomVariance = bottomLuminanceVariance(png, stripHeight);
+    const verdict = bottomVariance > threshold ? "likely-sliced" : "clean";
+    // Confidence is monotonic around the variance threshold: clean approaches 1 as
+    // variance approaches 0; likely-sliced starts at 0.5 and approaches 1 by 4x threshold.
+    const confidence = verdict === "clean"
+        ? clamp(1 - bottomVariance / threshold, 0, 1)
+        : Math.max(0.5, clamp(bottomVariance / (threshold * 4), 0, 1));
+    return {
+        path,
+        bottom_variance: bottomVariance,
+        verdict,
+        confidence,
+        warnings: []
+    };
+}
+function bottomLuminanceVariance(png, stripHeight) {
+    const startY = png.height - stripHeight;
+    const pixelCount = png.width * stripHeight;
+    if (pixelCount <= 0) {
+        return 0;
+    }
+    let lumaTotal = 0;
+    const luminances = [];
+    for (let y = startY; y < png.height; y += 1) {
+        for (let x = 0; x < png.width; x += 1) {
+            const index = (y * png.width + x) * 4;
+            const r = png.data[index];
+            const g = png.data[index + 1];
+            const b = png.data[index + 2];
+            const luminance = pixelLuminance(r, g, b);
+            luminances.push(luminance);
+            lumaTotal += luminance;
+        }
+    }
+    const mean = lumaTotal / pixelCount;
+    let squaredDeltaTotal = 0;
+    for (let i = 0; i < luminances.length; i += 1) {
+        const delta = luminances[i] - mean;
+        squaredDeltaTotal += delta * delta;
+    }
+    return squaredDeltaTotal / pixelCount;
+}
+function pixelLuminance(r, g, b) {
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=asset-integrity.js.map

package/dist/asset-integrity.js.map

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

package/dist/audit-container.d.ts

@@ -0,0 +1,13 @@
+export type AuditIssue = {
+    severity: "error" | "warning";
+    rule: string;
+    message: string;
+    fix: string;
+};
+export type ContainerAuditResult = {
+    pass?: string;
+    issue?: AuditIssue;
+};
+export declare function extractDeclaredMaxWidths(html: string): number[];
+export declare function containerScaleWidths(html: string): number[];
+export declare function auditContainerWidth(html: string, expectedPx?: number): ContainerAuditResult;

package/dist/audit-container.js

@@ -0,0 +1,129 @@
+// ── Container-width auditing ────────────────────────────────────────
+//
+// The `responsive/max-width` check used to hardcode ~1200px: it passed if the
+// HTML contained `max-width: 11xx/12xx px` and warned otherwise. That has two
+// blind spots, both reported in issue #9:
+//
+//   1. It rewards *any* ~1200px max-width and is blind to a project's own
+//      canonical container token. A page throttled to 768px while the rest of
+//      the design system sits on, say, 1152px is not flagged — the divergence
+//      that actually breaks cross-page alignment is invisible.
+//   2. `responsive/max-width` is the single most-fired warning in practice, yet
+//      it only ever nudges *toward* adding a max-width, never toward matching
+//      the system.
+//
+// When the caller passes `containerMaxWidth` (their canonical container token),
+// this module reframes the rule to flag *divergence from that token* — too
+// narrow OR too wide — instead of a generic 1200px heuristic. With no token
+// passed, the original heuristic is preserved exactly, so existing callers are
+// unaffected.
+//
+// Limitation (shared with the rest of audit_page): this reads *declared* CSS
+// (`max-width: Npx` in <style>/inline). Utility-class-only markup (e.g. a
+// Tailwind `max-w-3xl` with no compiled CSS in the blob) carries no declared
+// max-width to read; pass the compiled stylesheet for those.
+// Pull every *declared* `max-width: Npx` out of the markup. Media-query
+// preludes (`@media (max-width: 768px) {`) are stripped first so a responsive
+// breakpoint condition is never mistaken for a container constraint.
+export function extractDeclaredMaxWidths(html) {
+    var stripped = html.replace(/@media[^{]*\{/g, "{");
+    var out = [];
+    var re = /max-width\s*:\s*(\d+(?:\.\d+)?)\s*px/g;
+    var m;
+    while ((m = re.exec(stripped)) !== null) {
+        var n = parseFloat(m[1]);
+        if (!isNaN(n) && n > 0)
+            out.push(n);
+    }
+    return out;
+}
+// Container-scale widths only. Floor at 700px so legitimate nested prose/
+// reading measures (Tailwind max-w-2xl ≈ 672, max-w-prose ≈ 65ch, etc.) — which
+// are correctly narrower than the page container by design — aren't mistaken
+// for an off-system container throttle. The defect this catches is a *content
+// container* (≥700px tier) that diverges from the system token.
+var CONTAINER_FLOOR_PX = 700;
+export function containerScaleWidths(html) {
+    return extractDeclaredMaxWidths(html).filter(function (w) {
+        return w >= CONTAINER_FLOOR_PX;
+    });
+}
+// Token tolerance: 5% of the token, floored at 16px, so 1152px ± ~58px still
+// reads as "on token" but 768 vs 1152 does not.
+function tokenTolerance(expectedPx) {
+    return Math.max(16, expectedPx * 0.05);
+}
+// Audit a page's content-container width. Token-aware when `expectedPx` is
+// given; otherwise falls back to the original 1200px heuristic verbatim.
+export function auditContainerWidth(html, expectedPx) {
+    if (typeof expectedPx === "number" && expectedPx > 0) {
+        var containers = containerScaleWidths(html);
+        var tol = tokenTolerance(expectedPx);
+        // Worst offender first: any container-scale width outside tolerance is a
+        // divergence, even when the token width ALSO appears elsewhere in the
+        // markup (e.g. a shared stylesheet defines the token, but the page itself
+        // overrides to an off-system width — exactly the issue-#9 case).
+        var divergent = containers
+            .filter(function (w) {
+            return Math.abs(w - expectedPx) > tol;
+        })
+            .sort(function (a, b) {
+            return Math.abs(b - expectedPx) - Math.abs(a - expectedPx);
+        });
+        if (divergent.length > 0) {
+            var worst = divergent[0];
+            var dir = worst < expectedPx ? "narrower" : "wider";
+            var deltaPx = Math.round(Math.abs(worst - expectedPx));
+            return {
+                issue: {
+                    severity: "warning",
+                    rule: "responsive/max-width",
+                    message: "Content container max-width " +
+                        worst +
+                        "px diverges from your " +
+                        expectedPx +
+                        "px container token (" +
+                        dir +
+                        " by " +
+                        deltaPx +
+                        "px). Off-system container widths break cross-page alignment.",
+                    fix: "Use the project's canonical container token (" +
+                        expectedPx +
+                        "px) for top-level content. If the content should read narrower, nest it inside the " +
+                        expectedPx +
+                        "px container rather than replacing the container's max-width."
+                }
+            };
+        }
+        var onToken = containers.filter(function (w) {
+            return Math.abs(w - expectedPx) <= tol;
+        });
+        if (onToken.length > 0) {
+            return { pass: "Content container matches the " + expectedPx + "px container token" };
+        }
+        return {
+            issue: {
+                severity: "warning",
+                rule: "responsive/max-width",
+                message: "No content container max-width detected — expected your " +
+                    expectedPx +
+                    "px container token.",
+                fix: "Add max-width: " + expectedPx + "px; margin: 0 auto to top-level content containers."
+            }
+        };
+    }
+    // ── No token passed: preserve the original heuristic exactly.
+    var hasMaxWidth = /max-width\s*:\s*(1[12]\d{2}|1200)\s*px/.test(html);
+    if (hasMaxWidth)
+        return { pass: "Content has max-width constraint" };
+    return {
+        issue: {
+            severity: "warning",
+            rule: "responsive/max-width",
+            message: "No 1200px max-width constraint detected on content containers",
+            fix: "Add max-width: 1200px; margin: 0 auto to content containers. " +
+                "Pass containerMaxWidth to audit_page to check against your design system's own container token instead."
+        }
+    };
+}
+//# sourceMappingURL=audit-container.js.map

package/dist/audit-container.js.map

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

package/dist/capture.d.ts

@@ -0,0 +1,61 @@
+export declare class CaptureUnavailableError extends Error {
+    constructor(message?: string);
+}
+export type VideoArtifact = {
+    selector: string;
+    preload: string;
+    renderedBlank: boolean;
+    reason: "unloaded-video-artifact";
+};
+export type CaptureResult = {
+    url: string;
+    renderedHtml: string;
+    screenshotBase64: string;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    scrolledToBottom: boolean;
+    videoArtifacts: VideoArtifact[];
+    warnings: string[];
+};
+export type Interaction = {
+    selector: string;
+    event: "hover" | "click" | "focus";
+    delay_ms: number;
+};
+export type CaptureOptions = {
+    interactions?: Interaction[];
+    scroll_settle?: boolean;
+    viewport?: {
+        w: number;
+        h: number;
+    };
+    timeoutMs?: number;
+};
+export declare function capturePage(url: string, opts?: CaptureOptions): Promise<CaptureResult>;
+export declare function annotateVideoArtifacts(elements: any[]): VideoArtifact[];
+export type Verdict = "confirmed" | "likely-artifact" | "inconclusive";
+export type VerifiableFinding = {
+    key: string;
+    rule: string;
+    message: string;
+    kind: "issue" | "video-artifact";
+    selector?: string;
+};
+export type FindingVerdict = {
+    key: string;
+    verdict: Verdict;
+    evidence: string;
+};
+export type VerifyTarget = {
+    url?: string;
+    html?: string;
+};
+export declare function verifyFindings(target: VerifyTarget, findings: VerifiableFinding[], opts?: {
+    viewport?: {
+        w: number;
+        h: number;
+    };
+    timeoutMs?: number;
+}): Promise<FindingVerdict[]>;