Starts a watch session: builds once, runs once, then re-runs on every save until closed.

Resolves as soon as that first run has finished and the watchers are armed, so there is no window in which a save could be missed. The process then stays alive because the session holds a browser and a bound port — close() is what releases both.

Unlike the CLI's --watch, nothing is bound to stdin: no keyboard shortcuts are installed and the host's terminal is left alone. The behaviours behind those shortcuts are still here as WatchSession.runAll, WatchSession.runFailed and WatchSession.abort — the CLI binds keys to the same methods, so a terminal UI built on this API is not reimplementing them.

import { watch } from './watch.ts';

// Defined, not invoked: launches a browser and leaves it watching.
async function watchCart() {
  const session = await watch({ inputs: ['test/'] });
  await session.close();
  return session.initial.counts.total;
}

The same session, with the target named positionally: watch('test/', { filter: 'Cart' }).

The positional target wins over any inputs in the options object.