@3xhaust/oh-my-design 0.16.1

package/core/design/interaction-states.ts

@@ -0,0 +1,189 @@
+import type { Ir, Node, Violation } from '../types.ts';
+
+/**
+ * Deterministic interaction-state rules over the IR.
+ *
+ * ── What the IR can measure ──────────────────────────────────────────────────
+ *
+ * The DOM IR captures, per node:
+ *   - node.name       tagname + first CSS class, e.g. "input.email-field", "div.error-msg"
+ *   - node.path       full ancestor path, e.g. "form.contact/div.field/input"
+ *   - node.interactive  true for INPUT, SELECT, TEXTAREA, BUTTON, A, SUMMARY, role=button
+ *   - node.text       own text content (trimmed, ≤200 chars)
+ *
+ * It does NOT capture: aria-* attributes, data-* attributes, full class lists
+ * beyond the first class, JS event handlers, or CSS :hover/:focus pseudo-classes.
+ *
+ * ── What becomes a deterministic rule ────────────────────────────────────────
+ *
+ * DESIGN-FORM-NO-ERROR
+ *   When the IR contains at least one form-input node (INPUT/TEXTAREA/SELECT that
+ *   is interactive) AND no node on the page carries a class name or text pattern
+ *   associated with an error state, the form has no visible error affordance.
+ *
+ *   Detection signals for error affordance (OR — any one suffices):
+ *     - A node whose name contains ".error" or ".invalid" (class name evidence)
+ *     - A text node whose text contains "error" / "오류" / "잘못" (copy evidence)
+ *     - A node with role="alert" (ARIA error container — the canonical accessible pattern)
+ *     - A node with aria-invalid="true" (ARIA field-level error signal)
+ *
+ *   False-positive mitigation: the rule fires only when form inputs are present AND
+ *   no error affordance exists at all — not when an affordance exists but looks wrong.
+ *   A div.error-state with empty text still counts as present; we are checking
+ *   structure, not copy quality.
+ *
+ *   The ARIA signals (role=alert, aria-invalid) improve precision over class-name-only
+ *   detection: a page that correctly implements ARIA error patterns without ".error"
+ *   class names no longer produces a false positive.
+ *
+ * ── What stays prompt-only and why ───────────────────────────────────────────
+ *
+ * LOADING state
+ *   Skeleton, spinner, and shimmer elements are commonly built with libraries
+ *   (react-loading-skeleton, Tailwind's animate-pulse) and inlined at runtime.
+ *   Static IR captures the resting DOM; any loading overlay is usually hidden
+ *   (display:none or opacity:0) and therefore invisible to the IR extractor
+ *   (dom.ts skips elements with zero dimensions or display:none). Cannot detect
+ *   without runtime JavaScript interaction simulation.
+ *   → Covered by hand.agent.yaml and finish-pass.md rules.
+ *
+ * EMPTY state
+ *   Empty states are rendered conditionally by the application — they are absent
+ *   from the DOM when there is data. The IR captures the rendered page, which
+ *   typically has data. Detecting "this list has an empty state" from the static
+ *   DOM would require knowing which lists are data-driven vs. static (nav, footer,
+ *   feature-list), which requires full application context.
+ *   Furthermore, the false-positive rate would be unacceptably high: every <ul>,
+ *   <ol>, and .list container would need to be evaluated, and most would fire on
+ *   purely static lists (navigation, feature bullets, footer links).
+ *   → Covered by hand.agent.yaml and finish-pass.md rules.
+ *
+ * SUCCESS state
+ *   Success confirmation UIs (toast, inline text, page transition) are triggered
+ *   by user actions (form submit, button click) and are absent from the resting DOM.
+ *   No IR measurement can confirm they exist without simulating user actions.
+ *   → Covered by hand.agent.yaml rules.
+ *
+ * DISABLED state quality
+ *   Detecting whether disabled elements communicate why they are disabled requires
+ *   reading the associated explanatory copy and its proximity to the disabled element
+ *   — a layout and semantic reasoning task, not a structural one.
+ *   The IR does capture `interactive` (which covers BUTTON/INPUT), but the disabled
+ *   attribute is not captured, and reasoning about adjacent copy context requires
+ *   the full DOM tree with aria relationships, which the IR does not store.
+ *   → Covered by hand.agent.yaml rules.
+ *
+ * OFFLINE state
+ *   Offline detection requires a service worker or navigator.onLine event handler.
+ *   Neither is visible in the static DOM IR.
+ *   → Covered by hand.agent.yaml rules.
+ */
+
+// ── DESIGN-FORM-NO-ERROR ─────────────────────────────────────────────────────
+
+/**
+ * Returns true when a node is a form-input element that users can type into or
+ * select from. Buttons are excluded: they do not receive inline validation.
+ */
+function isFormInput(name: string, interactive: boolean): boolean {
+  if (!interactive) return false;
+  return name.startsWith('input') || name.startsWith('textarea') || name.startsWith('select');
+}
+
+/**
+ * Returns true when a node carries a structural signal that an error state exists:
+ *   - Class name contains "error" or "invalid" (structural evidence)
+ *   - Text content contains common error vocabulary (copy evidence)
+ *   - node.role === 'alert' (ARIA error container — the canonical accessible pattern)
+ *   - node.ariaInvalid === true (ARIA field-level error signal)
+ *
+ * This is an OR check — any one signal suffices to suppress the violation.
+ * The ARIA signals were added to reduce false positives: pages that correctly use
+ * role=alert or aria-invalid without ".error" class names no longer trigger.
+ */
+function hasErrorAffordance(node: Node): boolean {
+  const { name, text, role, ariaInvalid } = node;
+
+  // ARIA evidence: role=alert is the canonical container for live error messages;
+  // aria-invalid=true is the field-level signal that a value failed validation.
+  if (role === 'alert' || role === 'alertdialog') return true;
+  if (ariaInvalid === true) return true;
+
+  // Class-name evidence: "div.error", "span.invalid", "p.error-message", "input.is-invalid"
+  const lower = name.toLowerCase();
+  if (
+    lower.includes('.error') ||
+    lower.includes('.invalid') ||
+    lower.includes('error-') ||
+    lower.includes('-error') ||
+    lower.includes('invalid-') ||
+    lower.includes('-invalid')
+  ) return true;
+
+  // Text-content evidence: the rendered page shows an error message
+  if (text) {
+    const t = text.toLowerCase();
+    if (
+      t.includes('error') ||
+      t.includes('오류') ||
+      t.includes('잘못') ||
+      t.includes('올바르지') ||
+      t.includes('invalid') ||
+      t.includes('required') ||
+      t.includes('필수')
+    ) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Run deterministic interaction-state checks over the IR.
+ *
+ * Currently implements one deterministic rule (DESIGN-FORM-NO-ERROR).
+ * All other interaction states are prompt-only; see the file-level comment above.
+ *
+ * Only call this from `omd check` when the page has interactive elements —
+ * it is always safe to call regardless, but pages with no inputs will produce
+ * no findings (the form-input guard suppresses the rule).
+ */
+export function checkInteractionStates(ir: Ir): Violation[] {
+  const violations: Violation[] = [];
+
+  // ── DESIGN-FORM-NO-ERROR ──────────────────────────────────────────────────
+  //
+  // Fires when: at least one form-input node is present AND no node on the page
+  // carries an error-state affordance (class or text pattern).
+  //
+  // The rule fires once at the page level, not once per input — a form design
+  // either has error states or it does not. Firing once per input would produce
+  // redundant noise on multi-field forms.
+
+  const formInputs = ir.nodes.filter((n) => isFormInput(n.name, n.interactive === true));
+
+  if (formInputs.length > 0) {
+    const anyError = ir.nodes.some((n) => hasErrorAffordance(n));
+
+    if (!anyError) {
+      // Report against the first input node's path for location context.
+      const representative = formInputs[0]!;
+      violations.push({
+        id: 'DESIGN-FORM-NO-ERROR',
+        severity: 'warn',
+        layer: 1,
+        category: 'system',
+        nodeId: representative.id,
+        path: representative.path,
+        value: `${formInputs.length} form input${formInputs.length === 1 ? '' : 's'}, 0 error affordances`,
+        message:
+          `This page has ${formInputs.length} form input${formInputs.length === 1 ? '' : 's'} but no visible error-state affordance. `
+          + 'Add error-styled elements (class names containing "error" or "invalid") and error message copy. '
+          + 'Every field that can fail validation must show what went wrong and what to fix — '
+          + 'role=alert on the error container, aria-invalid on the failed field. '
+          + 'A form without an error state is an unfinished interface.',
+      });
+    }
+  }
+
+  return violations;
+}

package/core/eval-harness/index.ts

@@ -0,0 +1,225 @@
+/**
+ * Phase 0 eval harness — pure decision core.
+ *
+ * Pairwise before/after blind-choose is the ONLY gating signal. Quantitative metrics
+ * (non-text carrier density, motion presence, image-diff score/threshold/pass — see
+ * `DiffResult` in core/figma/diff.ts for that shape) and Awwwards-style category
+ * scores (design/usability/creativity/content) are advisory: they may explain or
+ * corroborate a verdict, but they can never flip `gate` from what blindChoose decided.
+ *
+ * NOT implemented here: a live render+blind-choose capture adapter (rendering both
+ * variants and recording a human/model's blind pick) is a Phase 2 dependency — it
+ * needs a browser/render runtime (see core/render/index.ts's Playwright-backed
+ * `withPage`). This module is the pure decision core that consumes pre-captured
+ * blindChoose signals; it does not render or capture anything itself. Follow the
+ * pure-core/adapter split used by core/composition-contract/index.ts
+ * (validateCompositionContractSource = pure, validateCompositionContract = adapter):
+ * a future `captureBlindChoose(...)` adapter would live alongside this file once the
+ * render runtime is available, calling into `evaluateOutput` below for the decision.
+ */
+
+export type BlindChooseWinner = 'after' | 'before' | 'tie';
+
+export interface BlindChooseSignal {
+  winner: BlindChooseWinner;
+  /** Confidence in [0, 1], when the capture method can report one. */
+  confidence?: number;
+}
+
+export type Register = 'quiet' | 'confident' | 'showpiece';
+
+export interface QuantitativeSignals {
+  /** 0–1 fraction of the layout carried by non-text elements (imagery, shape, color). */
+  nonTextCarrierDensity?: number | undefined;
+  motionPresent?: boolean | undefined;
+  /** Reserved for image-diff-style signals (score/threshold/pass) or other numeric/boolean metrics. */
+  [key: string]: number | boolean | undefined;
+}
+
+export interface AwwwardsSignals {
+  design?: number | undefined;
+  usability?: number | undefined;
+  creativity?: number | undefined;
+  content?: number | undefined;
+}
+
+export interface EvalHarnessInputs {
+  blindChoose: BlindChooseSignal;
+  register?: Register;
+  quantitative?: QuantitativeSignals;
+  awwwards?: AwwwardsSignals;
+}
+
+export interface EvalAdvisory {
+  source: 'quantitative' | 'awwwards';
+  message: string;
+  gating: false;
+}
+
+export interface EvalVerdict {
+  gate: 'pass' | 'fail';
+  gatingSignal: 'blind-choose';
+  reason: string;
+  advisories: EvalAdvisory[];
+}
+
+/** Showpiece register requires a stronger blind-choose confidence to pass the gate. */
+const SHOWPIECE_CONFIDENCE_THRESHOLD = 0.6;
+
+/**
+ * Determines the gate from blindChoose alone. Quiet/confident/showpiece registers only
+ * adjust how blindChoose itself is interpreted (e.g. a showpiece needs a confident win,
+ * a quiet output is satisfied by any non-"before" verdict) — they never let quantitative
+ * or Awwwards signals override the blind-choose outcome.
+ */
+function gateFromBlindChoose(blindChoose: BlindChooseSignal, register: Register): { pass: boolean; reason: string } {
+  const { winner, confidence } = blindChoose;
+
+  if (winner === 'before') {
+    return { pass: false, reason: 'blind-choose winner was "before": the after variant did not improve on the baseline' };
+  }
+
+  if (winner === 'tie') {
+    if (register === 'quiet' && confidence === undefined) {
+      // Quiet register: a tie with no reported confidence is treated as "no regression",
+      // which is the bar quiet output is held to. Still requires an explicit tie, never
+      // inferred from quantitative/Awwwards data.
+      return { pass: true, reason: 'blind-choose was a tie and register is "quiet": no regression is sufficient' };
+    }
+    return { pass: false, reason: 'blind-choose winner was "tie": no clear preference for the after variant' };
+  }
+
+  // winner === 'after'
+  if (register === 'showpiece') {
+    if (confidence === undefined || !Number.isFinite(confidence) || confidence < SHOWPIECE_CONFIDENCE_THRESHOLD) {
+      return {
+        pass: false,
+        reason: `register is "showpiece" and requires blind-choose confidence >= ${SHOWPIECE_CONFIDENCE_THRESHOLD}, got ${confidence ?? 'undefined'}`,
+      };
+    }
+    return { pass: true, reason: `blind-choose winner was "after" with confidence ${confidence} meeting the showpiece threshold` };
+  }
+
+  return { pass: true, reason: 'blind-choose winner was "after"' };
+}
+
+function quantitativeAdvisories(quantitative: QuantitativeSignals | undefined): EvalAdvisory[] {
+  if (!quantitative) return [];
+  const advisories: EvalAdvisory[] = [];
+  for (const [key, value] of Object.entries(quantitative)) {
+    if (value === undefined) continue;
+    advisories.push({ source: 'quantitative', message: `${key}: ${value}`, gating: false });
+  }
+  return advisories;
+}
+
+function awwwardsAdvisories(awwwards: AwwwardsSignals | undefined): EvalAdvisory[] {
+  if (!awwwards) return [];
+  const advisories: EvalAdvisory[] = [];
+  for (const [key, value] of Object.entries(awwwards)) {
+    if (value === undefined) continue;
+    advisories.push({ source: 'awwwards', message: `${key}: ${value}`, gating: false });
+  }
+  return advisories;
+}
+
+/**
+ * Pure evaluation core: blind-choose is the sole gating signal (see gateFromBlindChoose).
+ * Quantitative metrics and Awwwards category scores are folded into `advisories` only,
+ * each explicitly marked `gating: false` — no code path lets them alter `gate`.
+ */
+export function evaluateOutput(inputs: EvalHarnessInputs): EvalVerdict {
+  const register = inputs.register ?? 'confident';
+  const { pass, reason } = gateFromBlindChoose(inputs.blindChoose, register);
+
+  const advisories: EvalAdvisory[] = [
+    ...quantitativeAdvisories(inputs.quantitative),
+    ...awwwardsAdvisories(inputs.awwwards),
+  ];
+
+  return {
+    gate: pass ? 'pass' : 'fail',
+    gatingSignal: 'blind-choose',
+    reason,
+    advisories,
+  };
+}
+
+/**
+ * One completed refinement round in the RED/GREEN loop. `redCriteria` are the acceptance
+ * criteria still failing after this round (empty = GREEN, all met). `evidence` is the durable
+ * proof this round actually happened — render paths, verdict artifacts, `omd decision` ids — and
+ * is REQUIRED: a round with no evidence does not count. `blindChoose` compares this round's after
+ * against its own before, giving the improvement direction.
+ */
+export interface RefinementRound {
+  round: number;
+  blindChoose: BlindChooseWinner;
+  redCriteria: string[];
+  evidence: string[];
+}
+
+export interface RefinementLoopInputs {
+  rounds: RefinementRound[];
+  /** Hard upper bound on rounds — the loop is never unbounded. Default 3. */
+  maxRounds?: number;
+  /** Rounds to run before a plateau/GREEN stop is honored. Default 1. */
+  minRounds?: number;
+}
+
+export type RefinementLoopStatus =
+  | 'run-first-round'
+  | 'continue'
+  | 'green'
+  | 'regressed'
+  | 'plateaued'
+  | 'budget-exhausted'
+  | 'missing-evidence';
+
+export interface RefinementLoopDecision {
+  status: RefinementLoopStatus;
+  continueLoop: boolean;
+  converged: boolean;
+  reason: string;
+  roundsRun: number;
+  /** The top unmet (RED) criterion to target next when continuing; null otherwise. */
+  nextTarget: string | null;
+}
+
+/**
+ * Bounded RED/GREEN refinement-loop controller. It is NOT an automatic retry loop. Each round
+ * MUST leave evidence; the loop continues only while the build is still RED (acceptance criteria
+ * unmet) AND blind-choose shows the latest round genuinely improved it AND the round budget
+ * remains. It stops on the first of — GREEN (all criteria met = done), a regression (revert), a
+ * plateau (tie while still RED), a budget exhaustion, or missing evidence. This is the deliberate,
+ * evidence-driven convergence loop `protocol/human-design-loop.md` permits.
+ */
+export function evaluateRefinementLoop(inputs: RefinementLoopInputs): RefinementLoopDecision {
+  const maxRounds = inputs.maxRounds ?? 3;
+  const minRounds = inputs.minRounds ?? 1;
+  const rounds = inputs.rounds;
+  const n = rounds.length;
+
+  if (n === 0) {
+    return { status: 'run-first-round', continueLoop: true, converged: false, reason: 'no refinement round run yet — run the first round and record its evidence', roundsRun: 0, nextTarget: null };
+  }
+
+  const last = rounds[n - 1]!;
+
+  if (last.evidence.length === 0) {
+    return { status: 'missing-evidence', continueLoop: false, converged: false, reason: `round ${last.round} recorded no evidence — a refinement round without evidence (renders + blind-choose verdict) does not count; record it before deciding`, roundsRun: n, nextTarget: null };
+  }
+  if (last.blindChoose === 'before') {
+    return { status: 'regressed', continueLoop: false, converged: false, reason: `round ${last.round} regressed (blind-choose favored the before) — revert to the previous build and stop`, roundsRun: n, nextTarget: null };
+  }
+  if (last.redCriteria.length === 0 && n >= minRounds) {
+    return { status: 'green', continueLoop: false, converged: true, reason: `round ${last.round} is GREEN — every acceptance criterion is met; stop`, roundsRun: n, nextTarget: null };
+  }
+  if (n >= maxRounds) {
+    return { status: 'budget-exhausted', continueLoop: false, converged: false, reason: `round budget reached (${maxRounds}) — stop with the best build so far; still RED: ${last.redCriteria.join(', ') || '(none reported)'}`, roundsRun: n, nextTarget: null };
+  }
+  if (last.blindChoose === 'tie' && n >= minRounds) {
+    return { status: 'plateaued', continueLoop: false, converged: false, reason: `round ${last.round} plateaued (blind-choose tie) while still RED — no further improvement available; stop and report remaining: ${last.redCriteria.join(', ')}`, roundsRun: n, nextTarget: null };
+  }
+  return { status: 'continue', continueLoop: true, converged: false, reason: `round ${last.round} improved (blind-choose favored the after) and is still RED — run another round`, roundsRun: n, nextTarget: last.redCriteria[0] ?? null };
+}