# Agent run
> Simulated agent run: steps show a spinning arc while running and a carved check when done, with elapsed time and tokens on top.
- Element: `<hf-run>`
- React: `import { HfRun } from "@/components/lumesec/hf-run"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-run.json
- Page: https://elements.lumesec.ai/components/pixel-hd/run



Live preview: https://elements.lumesec.ai/view/hf-run

```html
<hf-run autoplay></hf-run>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-run
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-run.json
```

## Usage

React:

```tsx
import { HfRun } from "@/components/lumesec/hf-run";

export function Example() {
  return (
    <HfRun autoplay />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-run.js"></script>

<hf-run autoplay></hf-run>
```

## Behaviour

Steps with a spinning arc while running, a check carved out of a disc when done, and light flowing down the connector into the next step. Header shows elapsed time and tokens.

## API reference

### Attributes

| Attribute  | React prop | Type      | Default                                                                             | Description                                                                                              |
| ---------- | ---------- | --------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `steps`    | `steps`    | `string`  | `Plan the approach\|Read 14 files\|Edit src/auth.ts\|Run test suite\|Write summary` | Step labels separated by `\|`. Re-read at the start of each run.                                         |
| `label`    | `label`    | `string`  | `Agent run`                                                                         | Title in the header. Read once on connect.                                                               |
| `autoplay` | `autoplay` | `boolean` | `false`                                                                             | Presence attribute. Starts a run 0.7 s after the element first connects.                                 |
| `fail`     | `fail`     | `number`  | —                                                                                   | Zero-based index of the step that fails; the run stops there. Without the attribute every step succeeds. |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event  | React prop | Detail                                                                    | Description                                                                           |
| ------ | ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `step` | `onStep`   | `{ index: number, label: string, status: "running" \| "done" \| "fail" }` | Fires when a step starts and when it finishes.                                        |
| `done` | `onDone`   | `{ ok: boolean, elapsed: number }`                                        | Fires when the run ends. `ok` is `false` when a step failed; `elapsed` is in seconds. |

### Methods

Call them on the element, for example through a React ref.

| Method                 | Description                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| `run(): Promise<void>` | Resets the list and plays the simulated run. Ignored while a run is in progress. Same as the Run button. |
| `reset()`              | Rebuilds the step list from `steps` and clears the header counters.                                      |

### Properties

| Property            | Type       | Description                            |
| ------------------- | ---------- | -------------------------------------- |
| `steps` (read-only) | `string[]` | Step labels parsed from the attribute. |

## Accessibility

* The step list is an `aria-live="polite"` region; each finished step adds its duration or `failed` as text.
* Status icons are drawn on an `aria-hidden` canvas; pending and failed steps are also shown by text colour.
* The Run button is a native button, disabled while running and relabelled `Running…`, `Run again` or `Retry`.
* Reduced motion: each simulated step lasts 0.15 s, the spinner, connector flow and label shimmer stand still, finished icons do not pop, and durations appear without rolling.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--border`, `--destructive`, `--foreground`, `--lumesec`, `--muted` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-border`, `--ui-danger`, `--ui-fg`, `--ui-font`, `--ui-mono`, `--ui-muted` and `--ui-raised`.

## Notes

* Runs are simulated: each step lasts a random 0.6 to 1.7 s and the token count is generated. There is no API for reporting real progress.
* `elapsed` in `done`, the final header time and the token count are derived from the clock when the run ends, so they are correct even if the element was off screen during the run.