# Evidence image

An image of evidence the app holds, such as a screenshot taken while checking the work: a thumbnail button with an enlarge mark, and a caption under it. Pressed, it opens a lightbox with the image large, and Previous and Next through `set` (the arrow keys too), "Image 3 of 8" as its title, focus kept in it, Escape to close, and focus back on the thumbnail after.

The image is the app's: `src` is the app's own stored copy, never an address from model output. `alt` is required, and is the app's description of what the image shows; left empty, the image is named by its place ("Image 3 of 8"). The caption's `shows` is the checking agent's description of the image, so it is drawn as theirs ("Described by …"), never as a fact; who it was taken signed in as, where and when are the app's facts, each drawn only when given, and "not recorded" when the app says so with `null`. When the image has no address or doesn't load, it says it isn't available, with the app's description, rather than showing an empty box.

- Registry name: `evidence-image` (`@candor/evidence-image`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/evidence-image

## Install

```bash
npx candor-ui@4 add evidence-image
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/evidence-image`.
It brings in: bidi, button, chat, dialog, locale, locked, tokens, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"use client"

import { EvidenceImage, type EvidenceImageData } from "@/components/candor/evidence-image"

const checker = { id: "check", name: "Checking agent", role: "reviewer" }

/*
 * Screenshots the app took while checking the work, served from its own store. `alt` is the app's description; `shows`
 * is the checking agent's, drawn as theirs. The third has no stored copy, so it says the image isn't available.
 */
const walkthrough: EvidenceImageData[] = [
  {
    id: "inbox",
    src: "/examples/screenshots/approvals-inbox-light-desktop.jpg",
    alt: "The approvals inbox with three requests waiting",
    shows: "The inbox lists the three waiting requests, newest first.",
    describedBy: checker,
    signedInAs: "Dana Whitfield",
    where: "The test copy",
    at: "2026-11-16T14:03:00Z",
  },
  {
    id: "console",
    src: "/examples/screenshots/agent-ops-console-light-desktop.jpg",
    alt: "The operations console after the approval",
    shows: "The run continues once the request is approved.",
    describedBy: checker,
    signedInAs: "Dana Whitfield",
    where: "The test copy",
    at: "2026-11-16T14:05:00Z",
  },
  { id: "receipt", src: null, alt: "The run's receipt", signedInAs: null, where: "The test copy", at: null },
]

export default function Example() {
  return (
    <div className="flex flex-wrap gap-4">
      {walkthrough.map((image) => (
        <EvidenceImage key={image.id} image={image} set={walkthrough} />
      ))}
    </div>
  )
}
```

## <EvidenceImage>

Props:

- `image: EvidenceImageData`: The image: the app's address for it, its description, and the caption's parts.
- `set?: EvidenceImageData[] | undefined`: The set the image is in, in order, this one among them: its lightbox walks it, and an image with an empty `alt` is named by its place in it. Left out, the lightbox shows this one alone.
- `onOpen?: ((image: EvidenceImageData) => void) | undefined`: Called when the thumbnail is pressed, in place of opening its own lightbox: for a set whose one lightbox the app (or EvidenceGallery) owns.
- `className?: string | undefined`: Classes for the figure, merged with Candor's.

## <EvidenceLightbox>

The lightbox for a set of evidence images: one image at a time, large, with its caption, "Image 3 of 8" as its title, and Previous and Next through the set. The arrow keys move too (mirrored right to left). At either end the button stays and says why it can't be used, and the arrow key says the same to a screen reader. Focus is kept in the window, Escape closes it, and focus goes back to where it was (or to `returnFocusTo`'s element).

EvidenceImage and EvidenceGallery draw it for you; use it directly for a set the app opens from its own controls.

Props:

- `images: EvidenceImageData[]`: The images, in the order Previous and Next walk them.
- `index: number`: Which image is shown, from 0.
- `onIndexChange: (index: number) => void`: Called with the image to show when the person moves.
- `open: boolean`: Whether the lightbox is open.
- `onOpenChange: (open: boolean) => void`: Called when the person closes it (Escape, the ×, a press outside).
- `returnFocusTo?: ((image: EvidenceImageData) => HTMLElement | null | undefined) | undefined`: The element to put focus on when it closes, from the image last shown. Left out or returning nothing, focus goes back where it was.
- `className?: string | undefined`: Classes for the window, merged with Candor's.

## Strings (`evidenceImage`)

The fixed words, English by default. Override any of them under `evidenceImage` in `<LocaleProvider strings={{ evidenceImage: { … } }}>`; the table is exported as `evidenceImageStrings`.

- `enlarge`: Enlarge: {alt}
- `missing`: The image isn’t available.
- `agentWords`: The checking agent’s description
- `describedBy`: Described by {agent}
- `signedInAs`: Signed in as {who}
- `signedInAsUnknown`: Signed in as: not recorded
- `whereUnknown`: Where: not recorded
- `atUnknown`: When: not recorded
- `title`: Image
- `titleOf`: Image {current} of {total}
- `moved`: Image {current} of {total}: {alt}
- `previous`: Previous image
- `next`: Next image
- `atStart`: This is the first image.
- `atEnd`: This is the last image.

## Types

### EvidenceImageData

One image of evidence, as the app holds it. The image and every fact about it come from the app; only `shows` is the checking agent's words, and it is drawn as theirs.

```ts
{
  /** Stable within the set. */
  id: string;
  /**
   * The address of the app's own copy of the image: one it captured or stored and serves. Never an address from model
   * output, which could point anywhere. Left out or `null`, or when it doesn't load, the image says it isn't available.
   */
  src?: string | null | undefined;
  /**
   * What the image shows, written by the app for screen readers and for when the image isn't available: make it
   * describe the image ("The account list with the new column"). Required; left empty, the image is named only by its
   * place, "Image 3 of 8".
   */
  alt: string;
  /** What the image shows, in the checking agent's words: drawn as their description, never as a fact. */
  shows?: string | undefined;
  /** The agent who wrote `shows`, named by the app. Left out, the description says it is the checking agent's. */
  describedBy?: AgentIdentity | undefined;
  /** Who the image was taken signed in as, in the app's words. `null` says it wasn't recorded; left out, it isn't drawn. */
  signedInAs?: string | null | undefined;
  /** Where the image was taken ("the test copy"), in the app's words. `null` says it wasn't recorded; left out, it isn't drawn. */
  where?: string | null | undefined;
  /** When the image was taken. `null` says it wasn't recorded; left out, it isn't drawn. */
  at?: Date | string | number | null | undefined;
  /** The app's group for the image ("Criterion 2", "Step 3"), which EvidenceGallery draws a heading for. */
  group?: string | undefined;
}
```

## Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

### AgentIdentity

Import: `import type { AgentIdentity } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

```ts
{
  id: string;
  /** The displayed name, e.g. "Architect agent". Never derived from model output. */
  name: string;
  role: AgentRole;
  specialty?: string | undefined;
}
```

### Criterion

Import: `import type { Criterion } from "@/lib/candor/ops"` (item `ops`, https://candor.themethodic.com/docs/ops.md)

```ts
{
  id: string;
  label: string;
  passed: number;
  failed: number;
  /** Pass rate of the baseline run, 0–1. */
  baseline: number | null;
}
```

### AgentRole

Import: `import type { AgentRole } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).

```ts
string
```

## Motion

- **tint** (tint): The thumbnail's border darkens when the pointer is over it, and a ring shows when it takes keyboard focus.

Set with `--cd-motion-evidence-image-<moment>-*` in your brand file; the families are in the design reference.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
