The `timeout` option doesn't make sense for watchPosition

[saschanaz]

Here's what the current spec says:

1. The watchPosition() algorithm just passes the whole options to "request a position" steps.

2. The "request a position" steps says it should wait for a change at step 7.5.1:

   Wait for a significant change of geographic position. What constitutes a significant change of geographic position is left to the implementation. User agents MAY impose a rate limit on how frequently position changes are reported.

3. But before that, at step 7.3 it calls "acquire a position" again with the whole options.

4. And "acquire a position" creates the timeout task regardless of the existence of watchId.

And in the description of timeout it has a non-normative note that says:

An options.timeout value 0 can cause immediate failures.

And browsers work differently:

1. With timeout: 0:
   • Safari halts immediately
   • Chrome immediately triggers error callback and still calls success callback
   • Firefox silently does nothing.
2. With timeout: 1:
   • Safari errors immediately and still proceeds to call success callback
   • Chrome behaves similar to Safari, but on Windows the initial call succeeds without any error
   • Firefox keeps triggers the error callback as if it's `setInterval(errorCallback, 1);
3. With timeout: 1000:
   • The initial call succeeds without any error for both Safari and Chrome. The following calls still trigger the error callback after 1 sec. The success callback is triggered later in any case.
   • Firefox still repeatedly triggers the error callback.

Certainly Firefox is bugged here, but I'm not sure the point to time out for watchPosition when it's still expected to proceed after that. We are getting webcompat reports where websites consider the error callback as a full error instead of just "taking time to get the initial position". (See the "Blocks" references in https://bugzilla.mozilla.org/show_bug.cgi?id=1920302)

Should we consider removing timeout from watchPosition, or is there a known real-world use case for the initial timeout?

[reillyeon]

Thinking out loud, the reason for a timeout parameter to getCurrentPosition() or watchPosition() is to have a built-in setTimeout() that informs the site when a location isn't available. This is useful as otherwise the success callback might never be called and that too could cause issues. If we were designing this today we'd probably avoid this parameter and integrate an AbortSignal instead.

From a compat perspective, aside from bugs and corner cases, I think the issue is that under different conditions it simply takes more or less time to acquire a position and so any value of timeout is probably "wrong" sometimes and will result in unexpected site behavior. For watchPosition() this is particularly bad because the time between position updates can be quite long and it's unclear whether it's correct to generate a timeout simply if there hasn't been a significant change within the timeout, even if the previous result is perfectly accurate.

I suspect it's more robust for sites to implement their own timeouts (if they want them) and only have the browser invoke the error callback if there's an actual error condition which would prevent the site from getting a new location (e.g. a failure of the geolocation hardware, if the browser depends on GPS, or a change in the user's permission choices).

[marcoscaceres]

Yeah, what @reillyeon said is my understanding too... I also don't disagree with what what @saschanaz is suggesting, in that it doesn't make sense for watchPosition().

We should nonetheless get agreement on what timeout 0 means in both cases.

For watchPosition(), I think the challenge is that watchPosition() is possibly being semantically to means "get me the current position and continue watching the position". In which case, it makes sense in the developers mind for the first call that if you can't get the position in a reasonable amount of time time, it should error out.

Here's a suggestion, again... thinking out loud:

• If the is the initial call to watchPosition(), respect the timeout and call timeout error... but continue to watch.
• Subsequently watching the position, ignore the timeout.

That gives developers option to stop watching should the first call take too long. But then doesn't disrupt watching and making a mess of constant errors.

We then recommend in the spec that "best practice" is:

• call getCurrentPosition() first, optionally with the timeout.
• Then, once you have a position, call watchPosition(), without the timeout.

[marcoscaceres]

Bounced ideas with Chatty... this is what we came up with trying to minimize web compatibility issues and coming up with predicable behavior.

Plan of Action: watchPosition() timeout semantics (first-fix only, no default)

This plan addresses Kagami’s concern in #184 about recurring TIMEOUT errors in watches, and also folds in their proposal in #185 to drop the default timeout value.

Summary

• Treat timeout as a deadline to obtain the first position only (for both getCurrentPosition() and watchPosition()).
• After the first successful position in a watch, do not surface TIMEOUT purely due to lack of subsequent updates.
• Change the IDL so timeout has no default value. If timeout is missing, the UA MUST treat it as “no deadline” and MUST NOT schedule a timeout task at all.

Goals

• Stop spurious TIMEOUT errors during ongoing watches.
• Simplify the model by removing the magic sentinel 0xFFFFFFFF.
• Preserve web compatibility for sites relying on first-fix semantics.
• Clarify interaction with maximumAge and provider dropouts.

Normative Changes (spec text direction)

1. IDL change

   • Update PositionOptions so [Clamp] unsigned long timeout has no default value.
   • If timeout is missing, do not schedule any timeout task (equivalent to infinite wait).

2. getCurrentPosition():

   • If timeout is present and nonzero: schedule a timer for that duration.
   • If timeout is present and equals 0:
     • If a cached position satisfies maximumAge, deliver it immediately.
     • Otherwise, immediately queue one TIMEOUT error.
   • If timeout is missing: no timer at all.

3. watchPosition():

   • Maintain [[hasReportedPosition]] (initially false).
   • If timeout is present and [[hasReportedPosition]] is false:
     • Arm a single timer for that duration.
   • On success (first fix):
     • Deliver the position, set [[hasReportedPosition]] = true, and cancel the timer.
   • On timeout before first success:
     • Queue one TIMEOUT error and keep the watch alive.
   • After first success:
     • Do not schedule any further timeout tasks.
     • If the provider becomes unavailable, report POSITION_UNAVAILABLE.

4. timeout: 0 semantics (when present)

   • If a cached position satisfies maximumAge, deliver it immediately (success) and set [[hasReportedPosition]] = true.
   • Otherwise, immediately queue one TIMEOUT error and keep the watch active.
   • Rationale: timeout: 0 means “cached or fail fast” — not a heartbeat.

5. maximumAge interaction

   • If the cache satisfies maximumAge, it can fulfill the first fix immediately and the timeout need not be scheduled at all.

6. Non-normative authoring note

   • For watchPosition(), timeout is a first-fix deadline only.
     Apps needing a liveness heartbeat should implement their own timers; repeated TIMEOUT errors are not emitted after the first success.
   • Authors should omit timeout to indicate “no deadline.” Passing Infinity will clamp to 0xFFFFFFFF, which still schedules a (very long) timer.

Lifecycle & Cleanup

• watchPosition() creates a watch record with [[hasReportedPosition]] = false.
• clearWatch(id) cancels any pending first-fix timeout and discards the record.

Web-Compat & Rationale

• Compat:
  • Pages that omit timeout already experienced effectively infinite wait. Now it’s explicit (no timer at all).
  • getCurrentPosition() still enforces deadlines when timeout is provided.
• Fixes Kagami’s issue (The timeout option doesn't make sense for watchPosition #184):
  • Prevents recurring TIMEOUT after first success.
• Implements Kagami’s suggestion (Remove the default value of timeout in PositionOptions #185):
  • Removes the odd 0xFFFFFFFF sentinel default and simplifies implementation.
• Predictable:
  • Distinguishes “no new fix yet” (no error) from “cannot provide positions now” (POSITION_UNAVAILABLE).

WPT / Test Plan

1. Missing timeout → No timeout task ever fires (both getCurrentPosition() and first-fix in watchPosition()).
2. Finite timeout → Deadline enforced once (for first fix only in watches).
3. timeout: 0 with cached position → Immediate success.
4. timeout: 0 without cached position → Immediate single TIMEOUT, watch continues.
5. No periodic timeouts post-first-fix → Verify no errors over multiple timeout intervals after first success.
6. Provider loss after first success → Expect POSITION_UNAVAILABLE, not TIMEOUT.
7. clearWatch cancels timeout → No callback after watch is cleared.

If folks are happy with this direction, I can prepare a PR that removes the default from PositionOptions, updates the algorithms accordingly, and adds the WPT coverage.

[reillyeon]

We should make [[hasReportedPosition]] per watch so that if multiple scripts on the page are accessing position or a watch is stopped and then started a long time later the site doesn't get into a weird state.

[marcoscaceres]

Right, yeah, it could be a map keyed on the id.

[marcoscaceres]

Another important thing I think we should do (see! I don't just have Chatty do all my thinking for me 🤖), is split the PositionOptions into two distinct dictionaries:

• one for watching
• one for requesting

That way, for things like #179, we would only add that to the watching dictionary (and we wouldn't have had the issue with timeout).

That will also allow us to more cleanly deprecate timeout on watching, as we can remove it eventually from the dictionary.

[marcoscaceres]

Noting (for myself) that the is already a [[WatchIds]] set... we can convert that to map.

[reillyeon]

Discussed at TPAC 2025. @marcoscaceres has agreed to make the above changes to spec.