Agents

This page is for coding agents using Watchstop in an app. Public names and adapter constraints for changing this repo are on Spec. Behavior is defined on Core, Runtimes, and Frameworks.

Machine indexes: /llms.txt, /llms-full.txt.

Packages

Use @watchstop/core in vanilla, Node, Bun, Deno, and tests. Use a framework adapter only inside that framework.

Adapters are thin get / subscribe / destroy bridges. Do not put clocks or elapsed math in adapter-using code when core already owns that.

Exact names

Use Clock, Store, Stopwatch, createBrowserClock, createTimerClock, createMockClock, and detectClock. Do not invent elapsed as a core method, onTick, or addEventListener.

Core usage

import { Stopwatch, createMockClock, detectClock } from '@watchstop/core'

const live = new Stopwatch()
const explicit = new Stopwatch(detectClock())
const clock = createMockClock()
const underTest = new Stopwatch(clock)

live.start()
live.get()
live.stop()
live.reset()
const unsubscribe = live.subscribe((elapsed) => {
  void elapsed
})
unsubscribe()
live.destroy()

• Construction is stopped at 0. Call start() to run.
• get() is live elapsed. subscribe notifies on ticks and mutating controls.
• Tests: inject createMockClock() and advance(ms). See Testing.
• Share one Clock object across stopwatches when you want a shared schedule. Bare new Stopwatch() / detectClock() each allocate a fresh clock.

See Clock, Store, Stopwatch, Options.

Adapter usage

Hooks and factories return elapsed, running, start, stop, reset, and stopwatch. They do not auto-start.

Omit options to own an instance (clock and precisionMs are forwarded to Stopwatch). Pass { stopwatch } to borrow an existing instance; the adapter must not destroy it.

import { useStopwatch } from '@watchstop/react'

const { elapsed, running, start, stop, reset, stopwatch } = useStopwatch()

Per-framework binding: React, Vue, Solid, Svelte, Angular, Qwik, Alpine.

Changing Watchstop itself: Spec and repo-root CONTRIBUTING.md.