LAB/ Tanishk Interface Lab
AgenticstableReactTypeScript

Agent Review Surface

Proposed change, evidence, and a human decision — the step between.

Live preview

Review inbox

Proposals awaiting a human

1 open

Proposed change

Rename `total` columns to `amount` in orders.sql

The billing service already reads amount_cents, so renaming here removes a translation layer three call sites work around.

db/schema/orders.sql7 lines
  • CREATE TABLE orders (
  • removed: total_cents integer NOT NULL,
  • added: amount_cents integer NOT NULL,
  • currency char(3) NOT NULL,
  • removed: total_updated_at timestamptz,
  • added: amount_updated_at timestamptz,
  • );
  • Call sites3 updated
  • Schemav4 migration ready
  • Tests12 passing
Decisions in this preview are local to the sample — nothing is saved or sent.
ProposalDecisionEvidence stripKey hints

Try A / R / E keys while the surface has focus

01What it does

When an automated process wants to change something, this is the surface where a person decides. A titled proposal, a real diff, the evidence the system used, and three honest actions: accept, reject, revise. It works for code, documents and configuration alike because the diff is structured data, not a screenshot.

In this previewThree plausible proposals — a schema rename, a copy edit, a config change — with real diffs and evidence rows. Accept, reject or revise; the surface reports the decision inline.

02Install

Registry install

Works with the shadcn CLI in any project that has a components.json. The component lands in components/lab/agent-review/ with its stylesheet beside it.

npx shadcn@latest add <lab-origin>/r/agent-review.json

No npm packages are installed — the component is self-contained. Prefer manual copying? Every file is below under Source.

  • components/lab/agent-review/agent-review.tsxcomponent
  • components/lab/agent-review/agent-review.cssstyles

Machine-readable item: /r/agent-review.json ↗

03Usage

agent-review.usage.tsx
import { AgentReviewSurface } from "@/components/lab/agent-review/agent-review";

const change = {
  id: "c1",
  title: "Rename column `total` to `amount`",
  rationale: "Matches the billing schema and fixes three call sites.",
  files: [
    {
      path: "db/schema/orders.sql",
      hunks: [
        { kind: "context", text: "CREATE TABLE orders (", line: 12 },
        { kind: "remove", text: "  total_cents integer", line: 13 },
        { kind: "add", text: "  amount_cents integer", line: 13 },
        { kind: "context", text: ");", line: 14 },
      ],
    },
  ],
};

export function Review() {
  return <AgentReviewSurface change={change} onDecision={(d) => save(d)} />;
}

04Props

Props accepted by Agent Review Surface
PropTypeDefaultNotes
changeReviewChange—{ id, title, rationale, files: [{ path, hunks }] } — hunks are { kind, text, line? } rows.
evidence{ label, value }[]—Short evidence rows shown with the proposal.
decision"pending" | "accepted" | "rejected" | "revise""pending"Controlled decision; omit for the internal state.
onDecision(decision, note?) => void—Called with the reviewer’s choice.
shortcutsbooleantrueA / R / E key bindings, shown as hints.

05Accessibility

  • The diff is a real list of added/removed lines with sr-only prefixes, not colour alone.
  • Decision buttons are ordinary buttons with visible focus; shortcuts are additive, never required.
  • Deciding is announced politely (“Change accepted”) and the surface stays in place — no modal, no focus jump.
  • Rejecting with a note is fully reversible in the host’s own model; the surface never pretends a decision is final.

06Source

2 files, 752 lines. Nothing private, no configuration required.

components/lab/agent-review/agent-review.tsx— press enter to show or hide the source
tsx
"use client";

import {
  useEffect,
  useId,
  useRef,
  useState,
  type KeyboardEvent,
} from "react";
import "./agent-review.css";

export type DiffLineKind = "add" | "remove" | "context";

export type DiffLine = {
  kind: DiffLineKind;
  text: string;
  line?: number;
};

export type ReviewFile = {
  path: string;
  hunks: DiffLine[];
};

export type ReviewChange = {
  id: string;
  title: string;
  rationale: string;
  files: ReviewFile[];
};

export type ReviewDecision = "pending" | "accepted" | "rejected" | "revise";

export type ReviewEvidence = { label: string; value: string };

export type AgentReviewSurfaceProps = {
  /** The proposal: title, rationale, and one or more files of diff rows. */
  change: ReviewChange;
  /** Short evidence rows shown with the proposal. */
  evidence?: ReviewEvidence[];
  /** Controlled decision; omit to let the surface own the state. */
  decision?: ReviewDecision;
  /** Called with the reviewer's choice. */
  onDecision?: (decision: ReviewDecision, note?: string) => void;
  /** A / R / E key bindings, shown as hints. */
  shortcuts?: boolean;
  className?: string;
};

const SIGNS: Record<DiffLineKind, string> = {
  add: "+",
  remove: "−",
  context: " ",
};

const RESOLVED_TITLE: Record<Exclude<ReviewDecision, "pending">, string> = {
  accepted: "Change accepted",
  rejected: "Change rejected",
  revise: "Revision requested",
};

const RESOLVED_NOTE: Record<Exclude<ReviewDecision, "pending">, string> = {
  accepted: "The diff stays in view, locked with this decision.",
  rejected: "No changes are applied to the files above.",
  revise: "The proposal goes back to its author with the note.",
};

/**
 * AGENT REVIEW SURFACE — the step between a proposed change and a person.
 *
 * A titled proposal, a structured diff, the evidence the process used,
 * and three honest actions: accept, reject, revise. The diff is data,
 * so it works for code, documents and configuration alike, and the
 * decision is announced politely instead of moved into a modal.
 */
export function AgentReviewSurface({
  change,
  evidence,
  decision,
  onDecision,
  shortcuts = true,
  className,
}: AgentReviewSurfaceProps) {
  const [internal, setInternal] = useState<ReviewDecision>(decision ?? "pending");
  const [lastDecision, setLastDecision] = useState(decision);
  const [revising, setRevising] = useState(false);
  const [note, setNote] = useState("");
  const [noteFor, setNoteFor] = useState<{
    decision: ReviewDecision;
    note: string;
  } | null>(null);
  const textareaRef = useRef<HTMLTextAreaElement>(null);
  const reviseRef = useRef<HTMLButtonElement>(null);
  const noteId = useId();

  // Keep the uncontrolled state following a controlled prop, per contract.
  if (decision !== lastDecision) {
    setLastDecision(decision);
    if (decision !== undefined) {
      setInternal(decision);
      // A host that resolves the decision externally also closes the note.
      if (decision !== "pending") {
        setRevising(false);
        setNote("");
      }
    }
  }

  const current = decision ?? internal;
  const resolved = current !== "pending";

  // Revise opens a note field: move focus in, and back on cancel.
  useEffect(() => {
    if (revising) textareaRef.current?.focus();
  }, [revising]);

  const decide = (next: ReviewDecision, withNote?: string) => {
    const trimmed = withNote?.trim();
    if (decision === undefined) setInternal(next);
    setRevising(false);
    setNote("");
    setNoteFor(trimmed ? { decision: next, note: trimmed } : null);
    onDecision?.(next, trimmed || undefined);
  };

  const cancelRevise = () => {
    setRevising(false);
    setNote("");
    reviseRef.current?.focus();
  };

  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    // Shortcuts stay out of the way while the note is being written.
    if (!shortcuts || resolved || revising) return;
    if (
      event.defaultPrevented ||
      event.metaKey ||
      event.ctrlKey ||
      event.altKey ||
      event.shiftKey
    ) {
      return;
    }
    const target = event.target instanceof HTMLElement ? event.target : null;
    if (
      target &&
      target.closest("textarea, input, select, [contenteditable='true']")
    ) {
      return;
    }
    const key = event.key.toLowerCase();
    if (key === "a") {
      event.preventDefault();
      decide("accepted");
    } else if (key === "r") {
      event.preventDefault();
      decide("rejected");
    } else if (key === "e") {
      event.preventDefault();
      setRevising(true);
    }
  };

  const statusTitle = current === "pending" ? null : RESOLVED_TITLE[current];
  const bannerNote =
    noteFor && noteFor.decision === current ? noteFor.note : null;
  const resolvedSub =
    current === "pending" ? null : bannerNote ?? RESOLVED_NOTE[current];

  return (
    <div
      className={`ar-root${className ? ` ${className}` : ""}`}
      data-decision={current}
      onKeyDown={handleKeyDown}
    >
      <span className="ar-sr-only sr-only" role="status" aria-live="polite">
        {statusTitle ?? ""}
      </span>

      <header className="ar-head">
        <p className="ar-eyebrow">Proposed change</p>
        <h3 className="ar-title">{change.title}</h3>
        <p className="ar-rationale">{change.rationale}</p>
      </header>

      <div className="ar-files" data-locked={resolved ? "true" : "false"}>
        {change.files.map((file, fileIndex) => (
          <div
            key={`${file.path}:${fileIndex}`}
            className="ar-file"
            role="group"
            aria-label={file.path}
          >
            <div className="ar-file-head">
              <span className="ar-file-path">{file.path}</span>
              <span className="ar-file-count">
                {file.hunks.length} {file.hunks.length === 1 ? "line" : "lines"}
              </span>
            </div>
            <ul className="ar-diff">
              {file.hunks.map((line, index) => (
                <li
                  key={`${file.path}:${index}`}
                  className="ar-diff-row"
                  data-kind={line.kind}
                >
                  <span className="ar-sign" aria-hidden="true">
                    {SIGNS[line.kind]}
                  </span>
                  <span className="ar-lineno" aria-hidden="true">
                    {line.line ?? ""}
                  </span>
                  <span className="ar-text">
                    {line.kind === "add" ? (
                      <span className="ar-sr-only sr-only">added: </span>
                    ) : null}
                    {line.kind === "remove" ? (
                      <span className="ar-sr-only sr-only">removed: </span>
                    ) : null}
                    {line.text}
                  </span>
                </li>
              ))}
            </ul>
          </div>
        ))}
      </div>

      {evidence && evidence.length > 0 ? (
        <ul className="ar-evidence" aria-label="Evidence">
          {evidence.map((item) => (
            <li key={`${item.label}:${item.value}`} className="ar-chip">
              <span className="ar-chip-label">{item.label}</span>
              <span className="ar-chip-value">{item.value}</span>
            </li>
          ))}
        </ul>
      ) : null}

      {resolved ? (
        <div className="ar-resolved">
          <div className="ar-banner" data-state={current}>
            <span className="ar-banner-dot" aria-hidden="true" />
            <div className="ar-banner-copy">
              <p className="ar-banner-text">{statusTitle}</p>
              <p className="ar-banner-note">{resolvedSub}</p>
            </div>
          </div>
        </div>
      ) : (
        <div className="ar-actions">
          <div className="ar-action-row">
            <button
              type="button"
              className="ar-btn ar-btn--primary"
              onClick={() => decide("accepted")}
            >
              Accept change
              {shortcuts ? (
                <kbd className="ar-key" aria-hidden="true">
                  A
                </kbd>
              ) : null}
            </button>
            <button
              type="button"
              className="ar-btn"
              onClick={() => decide("rejected")}
            >
              Reject
              {shortcuts ? (
                <kbd className="ar-key" aria-hidden="true">
                  R
                </kbd>
              ) : null}
            </button>
            <button
              type="button"
              className="ar-btn"
              ref={reviseRef}
              aria-expanded={revising}
              aria-controls={revising ? noteId : undefined}
              onClick={() => (revising ? cancelRevise() : setRevising(true))}
            >
              Revise
              {shortcuts ? (
                <kbd className="ar-key" aria-hidden="true">
                  E
                </kbd>
              ) : null}
            </button>
          </div>

          {revising ? (
            <div className="ar-revise">
              <label className="ar-note-label" htmlFor={noteId}>
                What should change?
              </label>
              <textarea
                id={noteId}
                ref={textareaRef}
                className="ar-note"
                rows={3}
                value={note}
                placeholder="Name the adjustment — the author receives this note."
                onChange={(event) => setNote(event.target.value)}
              />
              <div className="ar-revise-actions">
                <button
                  type="button"
                  className="ar-btn ar-btn--primary"
                  onClick={() => decide("revise", note)}
                >
                  Send revision
                </button>
                <button type="button" className="ar-btn" onClick={cancelRevise}>
                  Cancel
                </button>
              </div>
            </div>
          ) : null}
        </div>
      )}
    </div>
  );
}
components/lab/agent-review/agent-review.css— press enter to show or hide the source
css
/* ============================================================
   AGENT REVIEW SURFACE — self-contained styles.
   Every token is scoped to the root with a fallback, so the
   surface works in any host codebase. Neutral surfaces, thin
   rules, mono only where the diff is actually code.
   ============================================================ */

.ar-root {
  --ar-ink: #141418;
  --ar-ink-soft: #303038;
  --ar-muted: #5f5f68;
  --ar-faint: #8c8c94;
  --ar-surface: #ffffff;
  --ar-surface-soft: #f8f8f6;
  --ar-code: #fbfbfa;
  --ar-line: rgba(20, 20, 24, 0.12);
  --ar-line-soft: rgba(20, 20, 24, 0.07);
  --ar-accent: #4f27e0;
  --ar-accent-deep: #32119c;
  --ar-add-ink: #0f5c3c;
  --ar-add-wash: rgba(19, 122, 78, 0.09);
  --ar-remove-ink: #92201a;
  --ar-remove-wash: rgba(179, 38, 30, 0.07);
  --ar-warn: #8a5300;
  --ar-mono: ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;

  min-width: 0;
  overflow: hidden;
  border: 1px solid var(--ar-line);
  border-radius: 14px;
  background: var(--ar-surface);
  color: var(--ar-ink);
  font-size: 0.875rem;
  line-height: 1.55;
}

.ar-root :focus-visible {
  outline: 2px solid var(--ar-accent);
  outline-offset: 2px;
}

/* Visually hidden, in case the host has no utility class of its own. */
.ar-sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0 0 0 0);
  white-space: nowrap;
  border: 0;
}

/* ---- header ---- */

.ar-head {
  padding: 16px 16px 12px;
}

.ar-eyebrow {
  margin: 0;
  font-family: var(--ar-mono);
  font-size: 0.625rem;
  letter-spacing: 0.12em;
  text-transform: uppercase;
  color: var(--ar-faint);
}

.ar-title {
  margin: 6px 0 0;
  font-size: 1.0625rem;
  font-weight: 600;
  letter-spacing: -0.015em;
  line-height: 1.35;
  overflow-wrap: anywhere;
}

.ar-rationale {
  margin: 8px 0 0;
  max-width: 62ch;
  font-size: 0.8125rem;
  line-height: 1.6;
  color: var(--ar-muted);
}

/* ---- files and diff ---- */

.ar-files {
  display: grid;
  gap: 10px;
  padding: 0 16px 14px;
}

.ar-file {
  min-width: 0;
  overflow: hidden;
  border: 1px solid var(--ar-line-soft);
  border-radius: 10px;
  background: var(--ar-surface);
}

.ar-file-head {
  display: flex;
  align-items: baseline;
  justify-content: space-between;
  gap: 10px;
  padding: 8px 10px;
  border-bottom: 1px solid var(--ar-line-soft);
  background: var(--ar-surface-soft);
}

.ar-file-path {
  font-family: var(--ar-mono);
  font-size: 0.6875rem;
  color: var(--ar-ink-soft);
  overflow-wrap: anywhere;
}

.ar-file-count {
  flex: none;
  font-family: var(--ar-mono);
  font-size: 0.5625rem;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  color: var(--ar-faint);
  white-space: nowrap;
}

.ar-diff {
  margin: 0;
  padding: 6px 0;
  list-style: none;
  overflow-x: auto;
  background: var(--ar-code);
}

.ar-diff-row {
  display: grid;
  grid-template-columns: 1.25rem 2.25rem auto;
  align-items: baseline;
  width: max-content;
  min-width: 100%;
  min-height: 1.35rem;
  padding: 1px 10px 1px 4px;
  font-family: var(--ar-mono);
  font-size: 0.75rem;
  line-height: 1.5;
  white-space: pre;
}

.ar-diff-row[data-kind="add"] {
  background: var(--ar-add-wash);
}

.ar-diff-row[data-kind="remove"] {
  background: var(--ar-remove-wash);
}

.ar-sign {
  text-align: center;
  color: var(--ar-faint);
}

.ar-diff-row[data-kind="add"] .ar-sign {
  color: var(--ar-add-ink);
}

.ar-diff-row[data-kind="remove"] .ar-sign {
  color: var(--ar-remove-ink);
}

.ar-lineno {
  padding-right: 10px;
  text-align: right;
  font-size: 0.6875rem;
  color: var(--ar-faint);
  user-select: none;
}

.ar-text {
  color: var(--ar-ink-soft);
}

.ar-diff-row[data-kind="add"] .ar-text {
  color: var(--ar-add-ink);
}

.ar-diff-row[data-kind="remove"] .ar-text {
  color: var(--ar-remove-ink);
}

/* Once decided, the diff is reference material — quieter headers. */
.ar-files[data-locked="true"] .ar-file-head {
  background: var(--ar-surface);
}

/* ---- evidence strip ---- */

.ar-evidence {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin: 0;
  padding: 0 16px 14px;
  list-style: none;
}

.ar-chip {
  display: inline-flex;
  align-items: baseline;
  gap: 6px;
  border: 1px solid var(--ar-line-soft);
  border-radius: 999px;
  background: var(--ar-surface-soft);
  padding: 4px 10px;
  font-size: 0.6875rem;
}

.ar-chip-label {
  color: var(--ar-faint);
}

.ar-chip-value {
  color: var(--ar-ink-soft);
  font-weight: 500;
}

/* ---- actions ---- */

.ar-actions {
  display: grid;
  gap: 10px;
  padding: 12px 16px 16px;
  border-top: 1px solid var(--ar-line-soft);
}

.ar-action-row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.ar-btn {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  border: 1px solid var(--ar-line);
  border-radius: 999px;
  background: var(--ar-surface);
  padding: 8px 14px;
  font: inherit;
  font-size: 0.8125rem;
  font-weight: 500;
  color: var(--ar-ink);
  cursor: pointer;
}

.ar-btn:hover {
  background: var(--ar-surface-soft);
}

.ar-btn--primary {
  border-color: var(--ar-accent);
  background: var(--ar-accent);
  color: #ffffff;
}

.ar-btn--primary:hover {
  background: #3f1bc0;
}

.ar-key {
  font-family: var(--ar-mono);
  font-size: 0.625rem;
  line-height: 1;
  padding: 3px 5px;
  border: 1px solid currentColor;
  border-radius: 4px;
  opacity: 0.72;
}

/* ---- revise form ---- */

.ar-revise {
  display: grid;
  gap: 8px;
  padding: 12px;
  border: 1px solid var(--ar-line-soft);
  border-radius: 10px;
  background: var(--ar-surface-soft);
}

.ar-note-label {
  font-size: 0.75rem;
  font-weight: 600;
  color: var(--ar-ink-soft);
}

.ar-note {
  width: 100%;
  min-height: 72px;
  resize: vertical;
  border: 1px solid var(--ar-line);
  border-radius: 8px;
  background: var(--ar-surface);
  padding: 8px 10px;
  font: inherit;
  font-size: 0.8125rem;
  line-height: 1.5;
  color: var(--ar-ink);
}

.ar-note::placeholder {
  color: var(--ar-faint);
}

.ar-revise-actions {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

/* ---- resolved banner ---- */

.ar-resolved {
  padding: 12px 16px 16px;
  border-top: 1px solid var(--ar-line-soft);
}

.ar-banner {
  display: flex;
  align-items: flex-start;
  gap: 10px;
  padding: 10px 12px;
  border: 1px solid var(--ar-line-soft);
  border-radius: 10px;
  background: var(--ar-surface-soft);
}

.ar-banner-dot {
  flex: none;
  width: 8px;
  height: 8px;
  margin-top: 6px;
  border-radius: 50%;
  background: var(--ar-faint);
}

.ar-banner[data-state="accepted"] {
  border-color: rgba(19, 122, 78, 0.24);
  background: rgba(19, 122, 78, 0.06);
}

.ar-banner[data-state="accepted"] .ar-banner-dot {
  background: #147a4e;
}

.ar-banner[data-state="rejected"] {
  border-color: rgba(179, 38, 30, 0.22);
  background: rgba(179, 38, 30, 0.05);
}

.ar-banner[data-state="rejected"] .ar-banner-dot {
  background: var(--ar-remove-ink);
}

.ar-banner[data-state="revise"] {
  border-color: rgba(138, 83, 0, 0.22);
  background: rgba(138, 83, 0, 0.05);
}

.ar-banner[data-state="revise"] .ar-banner-dot {
  background: var(--ar-warn);
}

.ar-banner-copy {
  min-width: 0;
}

.ar-banner-text {
  margin: 0;
  font-size: 0.8125rem;
  font-weight: 600;
}

.ar-banner-note {
  margin: 4px 0 0;
  font-size: 0.75rem;
  line-height: 1.55;
  color: var(--ar-muted);
  overflow-wrap: anywhere;
}

/* ---- narrow screens ---- */

@media (max-width: 420px) {
  .ar-head {
    padding: 14px 12px 10px;
  }

  .ar-files {
    padding: 0 12px 12px;
  }

  .ar-evidence {
    padding: 0 12px 12px;
  }

  .ar-actions,
  .ar-resolved {
    padding: 12px;
  }

  .ar-btn {
    padding: 8px 12px;
  }
}

@media (prefers-reduced-motion: reduce) {
  .ar-root * {
    transition: none;
  }
}