@argus-design/protocol 2026.4.12

package/dist/index.d.ts

@@ -0,0 +1,468 @@
+type Result<T, E = ArgusError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+interface ArgusError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface Spacing {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface Point {
+    x: number;
+    y: number;
+}
+interface ElementSnapshot {
+    /** Unique CSS selector path for this element */
+    selector: string;
+    /** HTML tag name (lowercase) */
+    tagName: string;
+    /** Bounding box relative to viewport */
+    box: Box;
+    /** Computed margin values */
+    margin: Spacing;
+    /** Computed padding values */
+    padding: Spacing;
+    /** Visible text content (truncated to 200 chars) */
+    textContent: string;
+    /** Key computed styles */
+    computedStyles: ComputedStyleMap;
+    /** Accessibility properties */
+    accessibility: AccessibilityInfo;
+    /** Element attributes (filtered to meaningful ones) */
+    attributes: Record<string, string>;
+    /** Depth in DOM tree (0 = document.body) */
+    depth: number;
+    /** Number of direct children */
+    childCount: number;
+    /** Parent element selector (null for body) */
+    parentSelector: string | null;
+    /** Whether element is visible (not display:none, visibility:hidden, opacity:0) */
+    isVisible: boolean;
+    /** Whether element is interactive (button, link, input, etc.) */
+    isInteractive: boolean;
+    /** Z-index stacking context */
+    stackingContext: StackingContext | null;
+}
+interface ComputedStyleMap {
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string;
+    lineHeight: string;
+    letterSpacing: string;
+    textAlign: string;
+    textDecoration: string;
+    textTransform: string;
+    color: string;
+    backgroundColor: string;
+    borderColor: string;
+    opacity: string;
+    display: string;
+    position: string;
+    flexDirection: string;
+    flexWrap: string;
+    justifyContent: string;
+    alignItems: string;
+    gridTemplateColumns: string;
+    gridTemplateRows: string;
+    gap: string;
+    width: string;
+    height: string;
+    maxWidth: string;
+    minHeight: string;
+    borderRadius: string;
+    borderWidth: string;
+    borderStyle: string;
+    boxShadow: string;
+    overflow: string;
+    cursor: string;
+    transition: string;
+    transform: string;
+    customProperties: Record<string, string>;
+}
+interface AccessibilityInfo {
+    role: string | null;
+    ariaLabel: string | null;
+    ariaDescribedBy: string | null;
+    ariaHidden: boolean;
+    tabIndex: number | null;
+    hasAltText: boolean | null;
+    contrastRatio: number | null;
+    wcagLevel: "AAA" | "AA" | "fail" | null;
+}
+interface StackingContext {
+    zIndex: number;
+    isRoot: boolean;
+    reason: string;
+}
+interface PageSnapshot {
+    /** Page URL or identifier */
+    url: string;
+    /** Page title */
+    title: string;
+    /** Viewport dimensions */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Document language */
+    lang: string;
+    /** Timestamp of snapshot */
+    timestamp: number;
+    /** All inspected elements */
+    elements: ElementSnapshot[];
+    /** Page-level metadata */
+    meta: PageMeta;
+    /** Color palette extracted from the page */
+    colorPalette: ColorEntry[];
+    /** Typography scale found on the page */
+    typographyScale: TypographyEntry[];
+    /** Spacing values found on the page */
+    spacingValues: number[];
+}
+interface PageMeta {
+    /** Total number of DOM elements */
+    totalElements: number;
+    /** Number of visible elements */
+    visibleElements: number;
+    /** Number of interactive elements */
+    interactiveElements: number;
+    /** Number of images */
+    imageCount: number;
+    /** Number of links */
+    linkCount: number;
+    /** Number of headings (h1–h6) */
+    headingCount: number;
+    /** Whether page uses CSS Grid anywhere */
+    usesGrid: boolean;
+    /** Whether page uses Flexbox anywhere */
+    usesFlex: boolean;
+    /** Whether page uses CSS custom properties */
+    usesCustomProperties: boolean;
+    /** Document scroll height */
+    scrollHeight: number;
+    /** Number of distinct font families */
+    fontFamilyCount: number;
+    /** Number of distinct colors */
+    colorCount: number;
+}
+interface ColorEntry {
+    value: string;
+    count: number;
+    usage: "text" | "background" | "border" | "other";
+}
+interface TypographyEntry {
+    fontSize: string;
+    fontWeight: string;
+    fontFamily: string;
+    lineHeight: string;
+    count: number;
+    elements: string[];
+}
+type Severity = "error" | "warning" | "info" | "pass";
+type RuleCategory = "spacing" | "typography" | "color" | "hierarchy" | "accessibility" | "consistency";
+declare const RULE_CATEGORIES: RuleCategory[];
+interface Finding {
+    /** Rule that produced this finding */
+    ruleId: string;
+    /** Severity level */
+    severity: Severity;
+    /** Category this finding belongs to */
+    category: RuleCategory;
+    /** CSS selector of the affected element(s) */
+    selector: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** What was actually measured */
+    measured: string | number;
+    /** What was expected or recommended */
+    expected: string | number;
+    /** Specific fix suggestion */
+    suggestion: string;
+    /** Score impact (0–100, how many points this costs) */
+    impact: number;
+}
+interface ScoringRule {
+    /** Unique rule identifier */
+    id: string;
+    /** Human-readable rule name */
+    name: string;
+    /** Which category this rule belongs to */
+    category: RuleCategory;
+    /** What this rule checks */
+    description: string;
+    /** Rule weight in category score (0–1, default 1) */
+    weight?: number;
+    /** Evaluate the rule against a page snapshot */
+    evaluate: (snapshot: PageSnapshot) => Finding[];
+}
+interface CategoryScore {
+    category: RuleCategory;
+    score: number;
+    maxScore: number;
+    findings: Finding[];
+    ruleCount: number;
+    passCount: number;
+    warningCount: number;
+    errorCount: number;
+}
+interface ScoreReport {
+    /** Aggregate score across all categories (0–100) */
+    totalScore: number;
+    /** Per-category breakdown */
+    categories: CategoryScore[];
+    /** All findings sorted by impact (highest first) */
+    findings: Finding[];
+    /** Total number of elements analyzed */
+    elementsAnalyzed: number;
+    /** Total number of rules evaluated */
+    rulesEvaluated: number;
+    /** Timestamp */
+    timestamp: number;
+    /** Time taken in milliseconds */
+    durationMs: number;
+    /** Page URL or identifier */
+    source: string;
+}
+interface Suggestion {
+    /** Finding that triggered this suggestion */
+    findingId: string;
+    /** Element to modify */
+    selector: string;
+    /** CSS property changes to apply */
+    changes: CSSChange[];
+    /** Expected score improvement */
+    expectedImprovement: number;
+    /** Priority (1 = highest) */
+    priority: number;
+    /** Human-readable rationale */
+    rationale: string;
+}
+interface CSSChange {
+    property: string;
+    currentValue: string;
+    suggestedValue: string;
+}
+interface DiffReport {
+    /** Before state summary */
+    before: {
+        url: string;
+        totalScore: number;
+        timestamp: number;
+    };
+    /** After state summary */
+    after: {
+        url: string;
+        totalScore: number;
+        timestamp: number;
+    };
+    /** Score delta (positive = improved) */
+    scoreDelta: number;
+    /** Per-category deltas */
+    categoryDeltas: {
+        category: RuleCategory;
+        delta: number;
+    }[];
+    /** Structural changes detected */
+    structuralChanges: StructuralChange[];
+    /** New issues introduced */
+    regressions: Finding[];
+    /** Issues fixed */
+    fixes: Finding[];
+}
+interface StructuralChange {
+    type: "added" | "removed" | "moved" | "resized" | "restyled";
+    selector: string;
+    description: string;
+    before?: Partial<ElementSnapshot>;
+    after?: Partial<ElementSnapshot>;
+}
+interface DesignProfile {
+    /** Profile name */
+    name: string;
+    /** When this profile was created */
+    createdAt: number;
+    /** When this profile was last updated */
+    updatedAt: number;
+    /** Total number of decisions that informed this profile */
+    decisionCount: number;
+    /** Learned preferences by category */
+    preferences: DesignPreference[];
+    /** Category weights (which categories matter most to this user) */
+    categoryWeights: Record<RuleCategory, number>;
+    /** Specific rule overrides */
+    ruleOverrides: RuleOverride[];
+}
+interface DesignPreference {
+    /** Which category this preference belongs to */
+    category: RuleCategory;
+    /** The preference rule in natural language */
+    rule: string;
+    /** How strong this preference is (0–1) */
+    weight: number;
+    /** How many times this was reinforced */
+    reinforcements: number;
+    /** Prefix for structured output */
+    prefix: "ALWAYS" | "NEVER" | "PREFER" | "AVOID";
+}
+interface RuleOverride {
+    ruleId: string;
+    action: "disable" | "promote" | "demote";
+    reason: string;
+}
+interface Decision {
+    /** What was the context */
+    context: "approve" | "reject" | "modify";
+    /** Which element was involved */
+    selector: string;
+    /** What CSS properties were involved */
+    properties: string[];
+    /** What values were approved/rejected */
+    values: Record<string, {
+        from: string;
+        to: string;
+    }>;
+    /** Timestamp */
+    timestamp: number;
+}
+interface AuditReport {
+    /** Full score report */
+    scoreReport: ScoreReport;
+    /** Accessibility-specific violations */
+    accessibilityViolations: AccessibilityViolation[];
+    /** Prioritized fix list (ordered by impact) */
+    prioritizedFixes: Suggestion[];
+    /** Summary statistics */
+    summary: AuditSummary;
+}
+interface AccessibilityViolation {
+    /** WCAG criterion (e.g., "1.4.3") */
+    criterion: string;
+    /** Level: A, AA, AAA */
+    level: "A" | "AA" | "AAA";
+    /** What's wrong */
+    description: string;
+    /** Affected elements */
+    selectors: string[];
+    /** How to fix */
+    fix: string;
+}
+interface AuditSummary {
+    totalScore: number;
+    grade: "A+" | "A" | "B+" | "B" | "C+" | "C" | "D" | "F";
+    topIssue: string;
+    quickWins: number;
+    criticalIssues: number;
+}
+interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+declare const MCP_TOOLS: MCPToolDefinition[];
+declare const ARGUS_VERSION = "2026.4.12";
+declare const ARGUS_DIR = ".argus";
+declare const DEFAULT_MCP_PORT = 18790;
+declare const DEFAULT_GATEWAY_PORT = 18791;
+declare const MAX_ELEMENTS = 1000;
+declare const MAX_TEXT_LENGTH = 200;
+declare const DEFAULT_THRESHOLD = 70;
+/** Common spacing scale (8px grid) */
+declare const SPACING_SCALE: number[];
+/** Common typographic scale (major third — 1.25) */
+declare const TYPE_SCALE_RATIOS: {
+    readonly minorSecond: 1.067;
+    readonly majorSecond: 1.125;
+    readonly minorThird: 1.2;
+    readonly majorThird: 1.25;
+    readonly perfectFourth: 1.333;
+    readonly augmentedFourth: 1.414;
+    readonly perfectFifth: 1.5;
+    readonly goldenRatio: 1.618;
+};
+/** WCAG 2.1 contrast ratio thresholds */
+declare const CONTRAST_THRESHOLDS: {
+    readonly AALargeText: 3;
+    readonly AANormalText: 4.5;
+    readonly AAALargeText: 4.5;
+    readonly AAANormalText: 7;
+};
+/** Minimum touch target sizes (WCAG 2.5.8) */
+declare const TOUCH_TARGETS: {
+    readonly minimum: 24;
+    readonly recommended: 44;
+    readonly comfortable: 48;
+};
+/** Score grade boundaries */
+declare const GRADE_BOUNDARIES: {
+    readonly "A+": 95;
+    readonly A: 90;
+    readonly "B+": 85;
+    readonly B: 75;
+    readonly "C+": 65;
+    readonly C: 55;
+    readonly D: 40;
+    readonly F: 0;
+};
+declare function scoreToGrade(score: number): AuditSummary["grade"];
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+interface ArgusConfig {
+    /** Version of the config schema */
+    version: number;
+    /** MCP server configuration */
+    mcp: {
+        port: number;
+        bind: "loopback" | "all";
+        auth: {
+            mode: "none" | "token";
+            token?: string;
+        };
+    };
+    /** Gateway configuration */
+    gateway: {
+        port: number;
+        bind: "loopback" | "all";
+    };
+    /** Scoring configuration */
+    scoring: {
+        threshold: number;
+        enabledCategories: RuleCategory[];
+        customRulePaths: string[];
+    };
+    /** Memory configuration */
+    memory: {
+        profileName: string;
+        historyEnabled: boolean;
+        maxHistoryDays: number;
+    };
+    /** Inspector configuration */
+    inspector: {
+        maxElements: number;
+        includeHidden: boolean;
+        includeCustomProperties: boolean;
+    };
+}
+declare const DEFAULT_CONFIG: ArgusConfig;
+
+export { ARGUS_DIR, ARGUS_VERSION, type AccessibilityInfo, type AccessibilityViolation, type ArgusConfig, type ArgusError, type AuditReport, type AuditSummary, type Box, CONTRAST_THRESHOLDS, type CSSChange, type CategoryScore, type ColorEntry, type ComputedStyleMap, DEFAULT_CONFIG, DEFAULT_GATEWAY_PORT, DEFAULT_MCP_PORT, DEFAULT_THRESHOLD, type Decision, type DeepPartial, type DesignPreference, type DesignProfile, type DiffReport, type ElementSnapshot, type Finding, GRADE_BOUNDARIES, MAX_ELEMENTS, MAX_TEXT_LENGTH, type MCPToolDefinition, MCP_TOOLS, type PageMeta, type PageSnapshot, type Point, RULE_CATEGORIES, type RequireAtLeastOne, type Result, type RuleCategory, type RuleOverride, SPACING_SCALE, type ScoreReport, type ScoringRule, type Severity, type Spacing, type StackingContext, type StructuralChange, type Suggestion, TOUCH_TARGETS, TYPE_SCALE_RATIOS, type TypographyEntry, err, ok, scoreToGrade };