# Reference

`Diff` is an alias for generated `SpadayDiff`. Both render `<spaday-diff>`.
`package` registers the `diffs` component package, CSS, JavaScript, and served upstream version.

## Properties

| Property           | Description                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `old_file`         | Original {name, contents, lang?} file. Null represents an added file.                                                                                        |
| `new_file`         | Updated {name, contents, lang?} file. Null represents a deleted file.                                                                                        |
| `patch`            | Unified patch text. When non-null, takes precedence over old_file and new_file.                                                                              |
| `patch_file`       | Zero-based file index across all commits in a patch. Defaults to 0.                                                                                          |
| `selected_lines`   | Selection {start, end, side?, endSide?}, using one-based lines and additions/deletions sides; null clears. Programmatic writes do not emit selection-change. |
| `annotations`      | Plain-text annotations [{side, line, text}], using one-based lines or 0 for a file-level note.                                                               |
| `diff_style`       | Diff layout; split by default.                                                                                                                               |
| `theme`            | Shiki theme name or {light, dark} theme names. Defaults to Pierre's themes.                                                                                  |
| `theme_type`       | Color mode; system by default.                                                                                                                               |
| `overflow`         | Code overflow; scroll by default.                                                                                                                            |
| `line_numbers`     | Show line numbers; true by default.                                                                                                                          |
| `header`           | Show the filename header; true by default.                                                                                                                   |
| `indicators`       | Change markers; bars by default.                                                                                                                             |
| `line_diff`        | Inline highlighting granularity; word-alt by default.                                                                                                        |
| `expand_unchanged` | Expand unchanged context when full file contents are available; false by default.                                                                            |
| `collapsed`        | Collapse code beneath the filename header; false by default.                                                                                                 |
| `selectable`       | Enable line selection by click and drag; true by default.                                                                                                    |

File objects contain `name` and `contents`, with optional `lang`. Bindings may supply null for one side to represent an added or deleted file. With direct Python construction, use an empty file on the missing side: constructor null values are omitted by spaday.

## Events

| Event              | Detail                                                       |
| ------------------ | ------------------------------------------------------------ |
| `selection-change` | `{range: {start, end, side?, endSide?}}`, or `{range: null}` |
| `line-click`       | `{line, side}`                                               |
| `render-error`     | `{message}`                                                  |

Line numbers are one-based. Sides are `"additions"` or `"deletions"`.
Events bubble across shadow boundaries. Only user selection changes emit `selection-change`.

## Styling tokens

`TOKENS` maps Python `css()` keyword names to spaday `Token` objects.

| Keyword                 | Controls                     | Shell fallback  |
| ----------------------- | ---------------------------- | --------------- |
| `spa_diffs_surface`     | viewer background            | `--spa-surface` |
| `spa_diffs_text`        | default text and filenames   | `--spa-text`    |
| `spa_diffs_muted`       | line numbers                 | `--spa-muted`   |
| `spa_diffs_added`       | added lines                  | `--spa-success` |
| `spa_diffs_deleted`     | deleted lines                | `--spa-danger`  |
| `spa_diffs_accent`      | selection and modified files | `--spa-accent`  |
| `spa_diffs_font_size`   | code font size               | None            |
| `spa_diffs_line_height` | code line height             | None            |

CSS spellings use hyphens, for example `--spa-diffs-surface`.
Tokens control viewer chrome and diff colors; syntax colors come from the selected Shiki theme.

## Runtime requirements

Python 3.11+, spaday 0.12+, and a modern browser with CSS `light-dark()` support.
The wheel includes Pierre Diffs 1.5.2 and its browser assets. The example additionally uses transports, Pydantic, Starlette, and Uvicorn.