Temporal.ZonedDateTime.prototype.add(): incorrect example for offset ambiguity resolution during fall-back DST transition

[teppeis]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/add

What specific section or headline is this issue about?

Description

What information was incorrect, unhelpful, or incomplete?

The Description section says that when the date portion of add()/subtract() lands on an ambiguous (fall-back/overlap) local time, the ambiguity is resolved using offset: "prefer" behavior — i.e. the original ZonedDateTime's offset is retained if still valid for the new local time. The second worked example given for this claim is incorrect:

2024-11-04T01:00:00-05:00[America/New_York] minus one day is 2024-11-03T01:00:00-05:00[America/New_York]

I verified this in some implementations (Chrome, Firefox and @js-temporal/polyfill) and all agree that the actual result is:

2024-11-03T01:00:00-04:00[America/New_York]

(offset -04:00, not -05:00 as stated in the doc).

What did you expect to see?

Per the actual spec algorithm (AddZonedDateTime, https://tc39.es/proposal-temporal/#sec-temporal-addzoneddatetime), the date-portion addition resolves ambiguity using:

Let intermediateNs be ! GetEpochNanosecondsFor(timeZone, intermediateDateTime, "compatible").

This is disambiguation: "compatible" only — there's no step anywhere in this algorithm that references or preserves the original ZonedDateTime's offset. offset: "prefer" semantics apply to with()/from() (via InterpretISODateTimeOffset), which add()/subtract() never calls.

Suggested fix:
Remove the offset: "prefer" claim for add()/subtract() and instead describe ambiguous date-portion results as resolved via disambiguation: "compatible" (same mechanism as the invalid/skipped-time case described in the bullet just above this one).

Do you have any supporting links, references, or citations?

https://tc39.es/proposal-temporal/#sec-temporal-addzoneddatetime

Do you have anything more you want to share?

Reproduction:

const a = Temporal.ZonedDateTime.from("2024-11-02T01:00:00-04:00[America/New_York]");
console.log(a.add({ days: 1 }).toString());
// "2024-11-03T01:00:00-04:00[America/New_York]"  (matches current doc)

const b = Temporal.ZonedDateTime.from("2024-11-04T01:00:00-05:00[America/New_York]");
console.log(b.subtract({ days: 1 }).toString());
// "2024-11-03T01:00:00-04:00[America/New_York]"  (doc says -05:00; actual/spec-correct is -04:00)

MDN metadata

Page report details

• Folder: en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/add
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/add
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/add/index.md
• Last commit: 7e14795
• Document last modified: 2025-12-08T17:29:19.000Z

[Josh-Cena]

My brain may be fried but I think the offset option does not matter once you already have a ZDT instance—it only matters when you are constructing a ZDT instance from an offset string. In any case the current docs definitely needs fixing.