# Browser lab

> Canonical HTML: [https://station.dterminal.net/docs/examples/browser](https://station.dterminal.net/docs/examples/browser)

`examples/17-browser` runs all three Station primitives locally in Web Workers and service workers. The static file server does not run the jobs. Start here before adapting the [browser runtime guide](https://station.dterminal.net/docs/browser.md) to your own application.

```
pnpm install
pnpm dev:browser
# Open http://127.0.0.1:4317
```

## Exercise the execution contract

1.  Queue a local report in Web Worker mode. After a step is saved, interrupt the worker and resume. Its seven-second lease must expire before a new attempt reuses the saved steps.
2.  Try a temporary failure and reload the page. Observe persisted checkpoints and the attempt count.
3.  Run text analysis: word and character counts fan out, join into a report, and conditionally highlight longer text. Simulate a branch failure to see dependent nodes skipped.
4.  Start pulse and recovering client. Inspect heartbeat, incarnation, desired state, and logs. The recovering client deliberately fails on its first incarnation.
5.  Switch to service-worker mode. Signals and DAGs run on wakes; beacons run bounded slices and suspend between them. Stop a beacon and reload to verify it stays stopped.
6.  After the offline shell is cached, stop the static server and reload. Local demo work can execute offline; application handlers that fetch remote data still need connectivity.

## Run browser checks

Stop manually started demo beacons, then use the Run browser checks link to navigate to `/tests.html`. Close other demo tabs so their executors do not claim integration-test work. Checks use real IndexedDB, worker termination, service-worker execution, ownership fencing, DAG recovery, and beacon lifecycle behavior. The suite also runs in isolated headless Chromium through `pnpm test`. Run `pnpm test:browser:install` once before local testing; the release command installs it automatically. These checks do not certify all browsers or execution after browser exit.

## Files to adapt

| File | Purpose |
| --- | --- |
| src/signals.ts, src/workloads.ts | Shared definitions and registry. |
| src/worker.ts | Independent job drains and beacon ticks. |
| src/sw.ts | Bounded wake handling, optional Background Sync, and demo-only shell caching. |
| src/app.ts | Enqueueing, mode controls, and persisted activity views. |
| build.mjs, serve.mjs | Browser bundles and a localhost static server. No hot reload; rebuild after source changes. |

[Browse the source](https://github.com/porkytheblack/station/tree/main/examples/17-browser). The lab is experimental: it promises recoverable local state, not continuous polling after a PWA closes. Read the guide's configuration guidance and storage/versioning limits before using custom definitions.