@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/theme/syntax/defineSyntaxTheme.diff.test.ts

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it, vi} from 'vitest';
+import {
+  defineSyntaxTheme,
+  REQUIRED_SYNTAX_KEYS,
+  syntaxThemeStyle,
+  syntaxThemeToCSS,
+} from './defineSyntaxTheme';
+import {syntaxTokenDefaults} from './tokens';
+import {dracula} from './presets';
+
+const base = Object.fromEntries(
+  REQUIRED_SYNTAX_KEYS.map(key => [key, '#123456']),
+) as Parameters<typeof defineSyntaxTheme>[0]['tokens'];
+
+describe('diff row slots in a syntax theme', () => {
+  it('are optional: a theme that sets none keeps the semantic defaults', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const theme = defineSyntaxTheme({name: 't', tokens: base});
+    expect(warn).not.toHaveBeenCalled();
+    expect(theme.tokens.added).toBe(
+      syntaxTokenDefaults['--color-syntax-added'],
+    );
+    expect(theme.tokens.removed).toBe(
+      syntaxTokenDefaults['--color-syntax-removed'],
+    );
+    // A defined theme that sets no header paint gets none: the header row
+    // sits on the theme's own background with punctuation text.
+    expect(theme.tokens['diff-header']).toBe('transparent');
+    // A theme that sets no marker colour keeps its own line-number colour.
+    expect(theme.tokens['added-marker']).toBe(
+      'var(--color-syntax-punctuation)',
+    );
+    expect(theme.tokens['removed-marker']).toBe(
+      'var(--color-syntax-punctuation)',
+    );
+    warn.mockRestore();
+  });
+
+  it('may be overridden to harmonize with the theme', () => {
+    const theme = defineSyntaxTheme({
+      name: 't',
+      tokens: {...base, added: ['#e6ffed', '#1b3a24'], removed: '#ffeef0'},
+    });
+    expect(theme.tokens.added).toBe('light-dark(#e6ffed, #1b3a24)');
+    expect(theme.tokens.removed).toBe('#ffeef0');
+    expect(theme.tokens['diff-header']).toBe('transparent');
+  });
+
+  it('skips unset diff slots in the CSS and style output of a hand-built definition', () => {
+    const tokens = {...dracula.tokens};
+    delete (tokens as Partial<typeof tokens>).added;
+    delete (tokens as Partial<typeof tokens>)['added-marker'];
+    const theme = {...dracula, tokens};
+    expect(syntaxThemeToCSS(theme)).not.toContain('undefined');
+    expect(syntaxThemeToCSS(theme)).not.toContain('--color-syntax-added:');
+    expect(syntaxThemeStyle(theme)).not.toHaveProperty('--color-syntax-added');
+    expect(syntaxThemeStyle(theme)).toHaveProperty('--color-syntax-removed');
+  });
+
+  it('leaves the shipped presets valid without them: row paints default, markers follow punctuation', () => {
+    expect(dracula.tokens.added).toBe(
+      syntaxTokenDefaults['--color-syntax-added'],
+    );
+    expect(dracula.tokens['added-marker']).toBe(
+      'var(--color-syntax-punctuation)',
+    );
+    expect(dracula.tokens['removed-marker']).toBe(
+      'var(--color-syntax-punctuation)',
+    );
+  });
+
+  it('defaults derive from the semantic tokens, never a literal colour', () => {
+    expect(syntaxTokenDefaults['--color-syntax-added']).toBe(
+      'color-mix(in srgb, var(--color-success-muted) 25%, transparent)',
+    );
+    expect(syntaxTokenDefaults['--color-syntax-removed']).toBe(
+      'color-mix(in srgb, var(--color-error-muted) 25%, transparent)',
+    );
+    expect(syntaxTokenDefaults['--color-syntax-diff-header']).toBe(
+      'var(--color-background-muted)',
+    );
+    expect(syntaxTokenDefaults['--color-syntax-added-marker']).toBe(
+      'var(--color-text-green)',
+    );
+    expect(syntaxTokenDefaults['--color-syntax-removed-marker']).toBe(
+      'var(--color-text-red)',
+    );
+  });
+});

package/src/theme/syntax/defineSyntaxTheme.ts

@@ -11,7 +11,11 @@
  * @see https://github.com/facebook/astryx/issues/1148
  */
 
-import {syntaxTokenDefaults, type SyntaxTokenName} from './tokens';
+import {
+  syntaxTokenDefaults,
+  DIFF_SYNTAX_TOKEN_NAMES,
+  type SyntaxTokenName,
+} from './tokens';
 import {devWarn} from '../../utils/devWarning';
 
 // =============================================================================
@@ -33,7 +37,12 @@ export type SyntaxThemeTokenKey =
   | 'attribute'
   | 'property'
   | 'punctuation'
-  | 'background';
+  | 'background'
+  | DiffSyntaxThemeTokenKey;
+
+/** The diff row slots a syntax theme MAY set; unset ones keep their defaults. */
+export type DiffSyntaxThemeTokenKey =
+  'added' | 'removed' | 'diff-header' | 'added-marker' | 'removed-marker';
 
 /**
  * Token value — either a single string or a [light, dark] tuple.
@@ -41,14 +50,28 @@ export type SyntaxThemeTokenKey =
  */
 export type SyntaxTokenValue = string | [light: string, dark: string];
 
-/** Token map for defineSyntaxTheme input — values can be strings or tuples. */
+/**
+ * Token map for defineSyntaxTheme input — values can be strings or tuples.
+ * The diff row slots are optional: a theme that sets none keeps the defaults
+ * (semantic success/error muted tints and the muted surface).
+ */
 export type SyntaxThemeTokenInput = Record<
-  SyntaxThemeTokenKey,
+  Exclude<SyntaxThemeTokenKey, DiffSyntaxThemeTokenKey>,
   SyntaxTokenValue
->;
+> &
+  Partial<Record<DiffSyntaxThemeTokenKey, SyntaxTokenValue>>;
 
-/** Resolved token map — all values are CSS strings (tuples resolved to light-dark()). */
-export type SyntaxThemeTokenMap = Record<SyntaxThemeTokenKey, string>;
+/**
+ * Resolved token map — all values are CSS strings (tuples resolved to
+ * light-dark()). The diff row slots are optional here as in the input, so a
+ * map written before they existed still type-checks; an unset slot renders
+ * its default.
+ */
+export type SyntaxThemeTokenMap = Record<
+  Exclude<SyntaxThemeTokenKey, DiffSyntaxThemeTokenKey>,
+  string
+> &
+  Partial<Record<DiffSyntaxThemeTokenKey, string>>;
 
 /** Input to defineSyntaxTheme. */
 export interface SyntaxThemeInput {
@@ -81,6 +104,22 @@ export const ALL_SYNTAX_KEYS: SyntaxThemeTokenKey[] = Object.keys(
   syntaxTokenDefaults,
 ).map(k => k.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey);
 
+const DIFF_KEYS = new Set<SyntaxThemeTokenKey>(
+  DIFF_SYNTAX_TOKEN_NAMES.map(
+    name => name.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey,
+  ),
+);
+
+/** The marker slots: unset in a theme, they follow that theme's punctuation. */
+const MARKER_KEYS = new Set<SyntaxThemeTokenKey>([
+  'added-marker',
+  'removed-marker',
+]);
+
+/** The keys every syntax theme must set: everything but the diff rows. */
+export const REQUIRED_SYNTAX_KEYS: SyntaxThemeTokenKey[] =
+  ALL_SYNTAX_KEYS.filter(key => !DIFF_KEYS.has(key));
+
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -138,19 +177,37 @@ export function resolveSyntaxTokenForMode(
 export function defineSyntaxTheme(
   input: SyntaxThemeInput,
 ): SyntaxThemeDefinition {
-  const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));
+  const missing = REQUIRED_SYNTAX_KEYS.filter(key => !(key in input.tokens));
   if (missing.length > 0) {
     devWarn(
       'defineSyntaxTheme',
       `"${input.name}": missing tokens: ${missing.join(', ')}. ` +
-        `All 14 syntax tokens are required.`,
+        `All ${REQUIRED_SYNTAX_KEYS.length} syntax colour tokens are required; ` +
+        `the diff row slots (added, removed, diff-header, added-marker, removed-marker) are optional.`,
     );
   }
 
-  // Resolve tuples to light-dark() CSS strings
+  // Resolve tuples to light-dark() CSS strings. An unset diff row paint keeps
+  // its default so every existing theme renders a readable diff unchanged; an
+  // unset marker slot takes this theme's own line-number colour (its
+  // punctuation token) rather than the page theme's green and red, and an
+  // unset header paint is none at all (the header row sits on this theme's
+  // own background with punctuation text), so number, glyph, and header
+  // text stay legible on this theme's background in every page mode — the
+  // glyph's shape carries the meaning where the colour does not.
   const resolved: Partial<SyntaxThemeTokenMap> = {};
   for (const key of ALL_SYNTAX_KEYS) {
-    resolved[key] = resolveTokenValue(input.tokens[key]);
+    const value = (
+      input.tokens as Partial<Record<SyntaxThemeTokenKey, SyntaxTokenValue>>
+    )[key];
+    resolved[key] =
+      value !== undefined
+        ? resolveTokenValue(value)
+        : MARKER_KEYS.has(key)
+          ? 'var(--color-syntax-punctuation)'
+          : key === 'diff-header'
+            ? 'transparent'
+            : syntaxTokenDefaults[toCSSProperty(key)];
   }
 
   return {
@@ -170,14 +227,17 @@ export function syntaxThemeStyle(
 ): Record<string, string> {
   const vars: Record<string, string> = {};
   for (const key of ALL_SYNTAX_KEYS) {
-    vars[toCSSProperty(key)] = theme.tokens[key];
+    // An unset diff slot is left to its default rather than written empty.
+    const value = theme.tokens[key];
+    if (value !== undefined) vars[toCSSProperty(key)] = value;
   }
   return vars;
 }
 
 /** Convert a syntax theme to CSS declarations (no selector wrapper). */
 export function syntaxThemeToCSS(theme: SyntaxThemeDefinition): string {
-  return ALL_SYNTAX_KEYS.map(
-    key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';',
-  ).join('\n  ');
+  // An unset diff slot is left to its default rather than written `undefined`.
+  return ALL_SYNTAX_KEYS.filter(key => theme.tokens[key] !== undefined)
+    .map(key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';')
+    .join('\n  ');
 }

package/src/theme/syntax/index.ts

@@ -14,7 +14,11 @@
 export {syntaxTokenDefaults} from './tokens';
 export type {SyntaxTokenName} from './tokens';
 
-export {defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS} from './defineSyntaxTheme';
+export {
+  defineSyntaxTheme,
+  syntaxThemeStyle,
+  syntaxThemeToCSS,
+} from './defineSyntaxTheme';
 export type {
   SyntaxThemeDefinition,
   SyntaxThemeInput,

package/src/theme/syntax/tokens.ts

@@ -13,8 +13,11 @@
  * colors automatically adapt to any theme's color system. Themes can also
  * set an explicit syntax theme via defineTheme({ syntax: dracula }).
  *
- * 14-token architecture validated against 11 community code themes.
- * All themes map cleanly to these 14 slots.
+ * 14 token colours and the code background, validated against 11 community
+ * code themes — all of them map cleanly to those slots — plus five diff row
+ * slots (added, removed, header paints; added and removed markers) that default
+ * to semantic tokens, so a syntax theme that does not set them keeps a
+ * readable diff.
  *
  * @see https://github.com/facebook/astryx/issues/1148
  */
@@ -51,6 +54,33 @@ export const syntaxTokenDefaults = {
   '--color-syntax-punctuation': 'var(--color-text-secondary)',
   // background -> muted surface
   '--color-syntax-background': 'var(--color-background-muted)',
+  // Diff rows (CodeBlock isDiff): whole-row tints behind unchanged syntax
+  // colours. Added/removed derive from the semantic success/error muted
+  // tokens at 25% strength: at full strength the secondary-grey syntax
+  // tokens (operator, punctuation, comment) fall under 4.5:1 on the tints
+  // in light; at 25% every default token clears it on both schemes with
+  // margin while the tint still reads against the plain row. Header rows
+  // (@@, and ---/+++ before the first hunk) sit on the muted surface.
+  '--color-syntax-added':
+    'color-mix(in srgb, var(--color-success-muted) 25%, transparent)',
+  '--color-syntax-removed':
+    'color-mix(in srgb, var(--color-error-muted) 25%, transparent)',
+  '--color-syntax-diff-header': 'var(--color-background-muted)',
+  // The margin of a changed row — its line number and +/- glyph — in the
+  // default theme's tinted-text tokens, made for tinted surfaces; a defined
+  // syntax theme that leaves them unset follows its own punctuation colour
+  // (see defineSyntaxTheme). Code text keeps the syntax theme's colours.
+  '--color-syntax-added-marker': 'var(--color-text-green)',
+  '--color-syntax-removed-marker': 'var(--color-text-red)',
 } as const;
 
 export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;
+
+/** The five diff row slots: optional in a syntax theme, defaulted when unset. */
+export const DIFF_SYNTAX_TOKEN_NAMES = [
+  '--color-syntax-added',
+  '--color-syntax-removed',
+  '--color-syntax-diff-header',
+  '--color-syntax-added-marker',
+  '--color-syntax-removed-marker',
+] as const satisfies ReadonlyArray<SyntaxTokenName>;

package/src/theme/syntax/useSyntaxTheme.diff.test.tsx

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useSyntaxTheme.diff.test.tsx
+ * @input A SyntaxTheme provider with a preset that sets no diff slots
+ * @output The hook hands a canvas consumer paintable colours for every slot
+ * @position Diff slot resolution for the imperative (canvas) path
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {SyntaxTheme, useSyntaxTheme} from './SyntaxTheme';
+import {dracula} from './presets';
+import {parseColor} from '../../utils/color';
+
+function Probe({onTokens}: {onTokens: (t: Record<string, string>) => void}) {
+  const syntax = useSyntaxTheme();
+  if (syntax) onTokens(syntax.tokens);
+  return null;
+}
+
+describe('useSyntaxTheme diff slots', () => {
+  it("resolves unset marker slots to the theme's own punctuation colour", () => {
+    let tokens: Record<string, string> = {};
+    render(
+      <SyntaxTheme theme={dracula}>
+        <Probe onTokens={t => (tokens = t)} />
+      </SyntaxTheme>,
+    );
+    expect(tokens.punctuation).toMatch(/^#|^rgb/);
+    expect(tokens['added-marker']).toBe(tokens.punctuation);
+    expect(tokens['removed-marker']).toBe(tokens.punctuation);
+    // The row paints derive from the page theme's resolved muted tokens at
+    // the default strength, as rgba() a canvas can paint.
+    expect(tokens.added).toMatch(/^rgba\(\d+, \d+, \d+, 0\.\d+\)$/);
+    expect(tokens.removed).toMatch(/^rgba\(\d+, \d+, \d+, 0\.\d+\)$/);
+    expect(parseColor(tokens.added)?.a).toBeCloseTo(0.2 * 0.25, 3);
+    expect(tokens['diff-header']).toBe('transparent');
+  });
+});

package/src/utils/plainDate.test.ts

@@ -30,6 +30,7 @@ import {
   formatSharedDate,
   DATE_FORMAT_WITH_WEEKDAY,
   DATE_FORMAT_MONTH_YEAR,
+  plainDateWeekFieldName,
 } from './plainDate';
 import type {ISODateString} from './dateTypes';
 
@@ -149,6 +150,14 @@ describe('plainDateToDate / plainDateFromDate', () => {
     expect(d.getDate()).toBe(15);
     expect(plainDateFromDate(d)).toEqual(pd);
   });
+
+  it('keeps years 1-99 instead of mapping them to 1900-1999', () => {
+    const pd: PlainDate = {year: 1, month: 1, day: 15};
+    const d = plainDateToDate(pd);
+    expect(d.getFullYear()).toBe(1);
+    expect(d.getDay()).toBe(1); // 0001-01-15 is a Monday
+    expect(plainDateFromDate(d)).toEqual(pd);
+  });
 });
 
 describe('plainDateToday', () => {
@@ -361,6 +370,15 @@ describe('plainDateDiffDays', () => {
       ),
     ).toBe(2);
   });
+
+  it('counts across the year 99 to 100 boundary', () => {
+    expect(
+      plainDateDiffDays(
+        {year: 99, month: 12, day: 31},
+        {year: 100, month: 1, day: 1},
+      ),
+    ).toBe(1);
+  });
 });
 
 describe('plainDateToInstant / plainDateFromInstant', () => {
@@ -393,6 +411,119 @@ describe('plainDateToInstant / plainDateFromInstant', () => {
       ),
     ).toBe(Date.UTC(2026, 4, 13, 16, 30));
   });
+
+  it.each([
+    // Both spring forward from a negative offset at local midnight.
+    [
+      'America/Santiago',
+      {year: 2026, month: 9, day: 6},
+      Date.UTC(2026, 8, 6, 4),
+    ],
+    ['America/Havana', {year: 2026, month: 3, day: 8}, Date.UTC(2026, 2, 8, 5)],
+    // A positive offset already resolved forward; it must not move.
+    ['Asia/Beirut', {year: 2026, month: 3, day: 29}, Date.UTC(2026, 2, 28, 22)],
+  ] as const)(
+    'starts a day whose midnight daylight saving skips at its first instant (%s)',
+    (timezoneID, date, firstInstant) => {
+      const instant = plainDateToInstant(date, timezoneID);
+      expect(instant).toBe(firstInstant);
+      expect(plainDateFromInstant(instant, timezoneID)).toEqual(date);
+      expect(plainDateFromInstant(instant - 1, timezoneID)).not.toEqual(date);
+    },
+  );
+
+  it('resolves any wall time inside a daylight-saving gap forward', () => {
+    // 2:30 AM does not happen on March 8, 2026 in Los Angeles: 3:30 AM PDT.
+    expect(
+      plainDateToInstant(
+        {year: 2026, month: 3, day: 8},
+        'America/Los_Angeles',
+        2,
+        30,
+      ),
+    ).toBe(Date.UTC(2026, 2, 8, 10, 30));
+  });
+
+  it('keeps the earlier instant of a wall time that happens twice', () => {
+    // Havana falls back at 1:00 AM on November 1, 2026: midnight once, then
+    // 12:00–1:00 AM twice; the first 12:30 AM is still daylight time.
+    expect(
+      plainDateToInstant(
+        {year: 2026, month: 11, day: 1},
+        'America/Havana',
+        0,
+        30,
+      ),
+    ).toBe(Date.UTC(2026, 10, 1, 4, 30));
+  });
+
+  it.each([
+    // Berlin falls back at 3:00 AM CEST on October 25, 2026: 2:00–3:00 AM
+    // happens twice, first at +2, then at +1.
+    [
+      'Europe/Berlin',
+      {year: 2026, month: 10, day: 25},
+      2,
+      30,
+      Date.UTC(2026, 9, 25, 0, 30),
+    ],
+    // Sydney falls back at 3:00 AM AEDT on April 5, 2026: first at +11.
+    [
+      'Australia/Sydney',
+      {year: 2026, month: 4, day: 5},
+      2,
+      30,
+      Date.UTC(2026, 3, 4, 15, 30),
+    ],
+  ] as const)(
+    'keeps the earlier instant of a repeated wall time in a positive-offset zone (%s)',
+    (timezoneID, date, hour, minute, earlier) => {
+      expect(plainDateToInstant(date, timezoneID, hour, minute)).toBe(earlier);
+    },
+  );
+
+  it('starts a date the zone skips at the first instant after the gap', () => {
+    // Samoa moved across the date line after December 29, 2011: December 30
+    // never happened in Pacific/Apia, so it resolves to 00:00 on December 31
+    // (+14), the next date.
+    const instant = plainDateToInstant(
+      {year: 2011, month: 12, day: 30},
+      'Pacific/Apia',
+    );
+    expect(instant).toBe(Date.UTC(2011, 11, 30, 10));
+    expect(plainDateFromInstant(instant, 'Pacific/Apia')).toEqual({
+      year: 2011,
+      month: 12,
+      day: 31,
+    });
+  });
+
+  it('moves a wall time in a 30-minute gap forward by 30 minutes', () => {
+    // Lord Howe Island jumps from 2:00 to 2:30 AM on October 4, 2026, from
+    // +10:30 to +11: 2:15 AM does not happen and reads as 2:45 AM.
+    expect(
+      plainDateToInstant(
+        {year: 2026, month: 10, day: 4},
+        'Australia/Lord_Howe',
+        2,
+        15,
+      ),
+    ).toBe(Date.UTC(2026, 9, 3, 15, 45));
+  });
+
+  it('keeps years 1-99 instead of mapping them to 1900-1999', () => {
+    const date: PlainDate = {year: 1, month: 1, day: 15};
+    // 0001-01-01T00:00:00Z is -62135596800000
+    expect(plainDateToInstant(date, 'UTC', 9, 30)).toBe(
+      -62135596800000 + (14 * 24 + 9) * 3600000 + 30 * 60000,
+    );
+    expect(
+      plainDateFromInstant(
+        plainDateToInstant(date, 'America/Los_Angeles'),
+        'America/Los_Angeles',
+      ),
+    ).toEqual(date);
+  });
 });
 
 describe('plainDateIsBefore / plainDateIsAfter', () => {
@@ -579,6 +710,11 @@ describe('plainDateGetWeekNumber', () => {
   it('returns week 1 for Jan 4 (always in ISO week 1)', () => {
     expect(plainDateGetWeekNumber({year: 2026, month: 1, day: 4})).toBe(1);
   });
+
+  it('keeps years 1-99 instead of mapping them to 1900-1999', () => {
+    // 0004-01-01 is a Thursday (ISO week 1); 1904-01-01 was a Friday.
+    expect(plainDateGetWeekNumber({year: 4, month: 1, day: 1})).toBe(1);
+  });
 });
 
 describe('plainDateFormat', () => {
@@ -663,3 +799,14 @@ describe('formatSharedDate', () => {
     );
   });
 });
+
+describe('plainDateWeekFieldName', () => {
+  it("returns the locale's CLDR name for the week field", () => {
+    expect(plainDateWeekFieldName('en-US')).toBe('week');
+    expect(plainDateWeekFieldName('de-DE')).toBe('Woche');
+  });
+
+  it('never returns an empty name', () => {
+    expect(plainDateWeekFieldName('zxx').length).toBeGreaterThan(0);
+  });
+});

package/src/utils/plainDate.ts

@@ -45,7 +45,11 @@ export function plainDateToISO(pd: PlainDate): ISODateString {
 }
 
 export function plainDateToDate(pd: PlainDate): Date {
-  return new Date(pd.year, pd.month - 1, pd.day);
+  // Unlike the Date constructor, setFullYear keeps years 0-99 as given
+  // instead of reading them as 1900-1999.
+  const d = new Date(0, 0, 1);
+  d.setFullYear(pd.year, pd.month - 1, pd.day);
+  return d;
 }
 
 export function plainDateFromDate(d: Date): PlainDate {
@@ -89,6 +93,24 @@ export function plainDateAddDays(pd: PlainDate, n: number): PlainDate {
   return plainDateFromDate(d);
 }
 
+/**
+ * `Date.UTC` with years 0-99 kept as given; `Date.UTC` itself reads them as
+ * 1900-1999.
+ */
+function utcTime(
+  year: number,
+  monthIndex: number,
+  day: number,
+  hour = 0,
+  minute = 0,
+  second = 0,
+): number {
+  const d = new Date(0);
+  d.setUTCFullYear(year, monthIndex, day);
+  d.setUTCHours(hour, minute, second);
+  return d.getTime();
+}
+
 /**
  * Whole calendar days from `a` to `b`, ignoring time of day. Positive when
  * `b` is after `a`, negative when before. Uses UTC midnight so DST shifts
@@ -96,8 +118,8 @@ export function plainDateAddDays(pd: PlainDate, n: number): PlainDate {
  */
 export function plainDateDiffDays(a: PlainDate, b: PlainDate): number {
   const msPerDay = 24 * 60 * 60 * 1000;
-  const aUTC = Date.UTC(a.year, a.month - 1, a.day);
-  const bUTC = Date.UTC(b.year, b.month - 1, b.day);
+  const aUTC = utcTime(a.year, a.month - 1, a.day);
+  const bUTC = utcTime(b.year, b.month - 1, b.day);
   return Math.round((bUTC - aUTC) / msPerDay);
 }
 
@@ -152,7 +174,7 @@ export function getTimeZoneParts(
 function getTimezoneOffsetMS(timezoneID: string, instant: number): number {
   const parts = getTimeZoneParts(instant, timezoneID);
   return (
-    Date.UTC(
+    utcTime(
       parts.year,
       parts.month - 1,
       parts.day,
@@ -163,17 +185,35 @@ function getTimezoneOffsetMS(timezoneID: string, instant: number): number {
   );
 }
 
+const DAY_MS = 24 * 60 * 60 * 1000;
+
 export function plainDateToInstant(
   date: PlainDate,
   timezoneID: string,
   hour = 0,
   minute = 0,
 ): number {
-  const utcGuess = Date.UTC(date.year, date.month - 1, date.day, hour, minute);
-  const firstOffset = getTimezoneOffsetMS(timezoneID, utcGuess);
-  const firstInstant = utcGuess - firstOffset;
-  const secondOffset = getTimezoneOffsetMS(timezoneID, firstInstant);
-  return utcGuess - secondOffset;
+  // The wall time read as if it were UTC; subtracting an offset gives a
+  // candidate instant.
+  const wallTime = utcTime(date.year, date.month - 1, date.day, hour, minute);
+  // The offsets in effect a day either side cover any transition that can make
+  // this wall time skipped or repeated.
+  const offsetBefore = getTimezoneOffsetMS(timezoneID, wallTime - DAY_MS);
+  const offsetAfter = getTimezoneOffsetMS(timezoneID, wallTime + DAY_MS);
+  // AST-067 (Temporal's "compatible" disambiguation): a wall time that happens
+  // twice resolves to its earlier occurrence, and one that never happens is
+  // read in the offset before the transition, which moves it forward by the
+  // length of the gap.
+  const candidates = [offsetBefore, offsetAfter]
+    .map(offset => wallTime - offset)
+    .filter(
+      (instant, index) =>
+        getTimezoneOffsetMS(timezoneID, instant) ===
+        (index === 0 ? offsetBefore : offsetAfter),
+    );
+  return candidates.length > 0
+    ? Math.min(...candidates)
+    : wallTime - offsetBefore;
 }
 
 export function plainDateFromInstant(
@@ -245,7 +285,7 @@ export function plainDateGetWeekNumber(pd: PlainDate): number {
   const d = plainDateToDate(pd);
   const dayNum = d.getDay() || 7;
   d.setDate(d.getDate() + 4 - dayNum);
-  const yearStart = new Date(d.getFullYear(), 0, 1);
+  const yearStart = plainDateToDate({year: d.getFullYear(), month: 1, day: 1});
   return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
 }
 
@@ -330,6 +370,31 @@ export function plainDateFormat(
   }).format(plainDateToDate(pd));
 }
 
+/**
+ * The locale's name for the "week of year" date field ("week", "Woche", "週"),
+ * from CLDR through `Intl.DisplayNames`. Calendar names its week-number
+ * column header with it, so no catalog string is needed for a word the
+ * platform already carries in every locale.
+ *
+ * `Intl.DisplayNames` with `type: 'dateTimeField'` is inside the Baseline − 2
+ * support tier (Chrome 106, Safari 15.4, Firefox 110). Should a host lack it
+ * or return nothing, the field's English CLDR name stands in rather than an
+ * empty header.
+ */
+export function plainDateWeekFieldName(locale: Locale = 'en'): string {
+  try {
+    const name = new Intl.DisplayNames(locale, {type: 'dateTimeField'}).of(
+      'weekOfYear',
+    );
+    if (name != null && name !== '') {
+      return name;
+    }
+  } catch {
+    // Fall through to the English CLDR value.
+  }
+  return 'week';
+}
+
 // =============================================================================
 // Shared date-only format vocabulary
 // =============================================================================