Add ping-adjusted controller hoster time

[justinfernald]

Fixes #308

What changed

• retain the hoster's raw timestamp from each completed controller ping exchange
• expose a half-round-trip-adjusted host timestamp in PingData
• add getHosterTime() to advance the latest adjusted sample using elapsed controller time
• return null until the controller has received its first hoster pong
• add deterministic fake-clock coverage for the pre-ping and advancing-clock contracts
• keep the focused test compatible with the workflow's Node 20 runtime using a test-local Promise.withResolvers shim

Root cause and impact

PONG_HOSTER already carried hosterTime, but ControllerCommunicator discarded it while constructing PingData. Controllers therefore had no supported way to estimate the hoster's current wall-clock time. This preserves the protocol value and exposes both the raw and latency-adjusted forms.

Verification

• Red-first: the new focused tests failed before implementation because getHosterTime() and the host timestamp fields did not exist
• npx -y node@20.10.0 node_modules/vitest/vitest.mjs run test/src/controller-time.test.ts — 2 tests passed under the hosted workflow's Node version
• node_modules/.bin/vitest run — 6 files, 24 tests passed
• corepack yarn coverage — 6 files, 24 tests passed
• node_modules/.bin/eslint src/controller/ControllerCommunicator.ts test/src/controller-time.test.ts — passed (existing React-detection warning only)
• focused strict TypeScript config without the repository's broken project reference — passed
• corepack yarn build — passed and generated the expected public declaration
• git diff --check — passed

The first hosted run exposed that the existing communicator constructor uses Promise.withResolvers, unavailable on the workflow's Node 20.10 runtime. The test now installs and removes a local compatibility shim; the production implementation is unchanged by that follow-up.

corepack yarn type-check remains blocked by the repository's pre-existing TS6305 error: vite.config.d.ts has not been built from vite.config.ts. This same error reproduces on the unchanged baseline.

Demo

This is a non-visual library API change. Run node_modules/.bin/vitest run test/src/controller-time.test.ts; the second test demonstrates a 40 ms round trip producing a 20 ms host-clock adjustment, followed by live clock advancement as controller time moves forward.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c0e86ae424

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use a monotonic clock for elapsed time

If the controller's wall clock is corrected manually or by NTP after a pong is received, this Date.now() delta incorporates that clock adjustment and makes getHosterTime() jump forward or backward even though the hoster's clock did not. Store a monotonic receipt time (for example, from performance.now()) and use that to advance the host timestamp so the estimate remains stable between ping samples.

Useful? React with 👍 / 👎.