# View.watch
URL: https://lsd.tools/docs/api-view-watch
Updated: 2026-07-17

## Parameters

| name | type | default | description |
|---|---|---|---|
| `*targets` | `Entity \| str` | — | each target is an `Entity` or an entity **name** (sugar) whose output this view should hold |

## Example

```python
from lsdtools import Engine, views

engine = Engine("survey.lsd")
assays = my_entity(...); engine.add(assays)

v = views.table(title="Assays"); engine.add(v)
v.watch(assays)          # or v.watch("assays") by name — either order works
engine.run_all()         # v now holds the output; every re-run refreshes it
v.show()
```

## Notes

`watch` is the **one verb** that moves data from the run side to the show side. It returns `self`, so
`views.table().watch(assays)` reads as one phrase. Three behaviours make it feel instant:

- **Any order** — *add-then-watch* and *watch-then-add* (view or entity first) are all equivalent; a
  name with no entity yet is kept **pending** and resolves the moment one is added under it.
- **Auto-pull** — watching an entity that has *already run* delivers its output immediately, which is
  what makes drag-and-drop and reopened projects feel instant.
- **Survives rename & reload** — watches are stored by entity **id**, not name, so they hold through an
  in-session rename and a project reopen; removing the entity from the engine auto-unwatches it.

Delivery goes through [`on_output`](/docs/api-view) (default: `feed(output)`) on each successful run.
A failed run delivers nothing and keeps the prior data. This is the plumbing under the desktop's
drag-and-drop, the 3D-viewer checkbox, and the right-click **Show in ▸** — see
[Rendering & payloads](/docs/tools-rendering).

## See also

**API:** [View](/docs/api-view) · [Engine.show](/docs/api-engine-show) · [ViewerPayload](/docs/api-viewerpayload)

**Guides:** [Rendering & payloads](/docs/tools-rendering) · [How a package fits together](/docs/start-architecture)