@@ -0,0 +1,9 @@
+---
+'@object-ui/plugin-timeline': patch
+'@object-ui/core': patch
+---
+
+fix(plugin-timeline,core): the timeline's gantt axis draws a stored date-only day on that day in every viewer zone, and the formula date functions do their day arithmetic on the UTC calendar, as the server does (objectui#10866, slice 3)
+
+- **Timeline, gantt variant.** Every date string the gantt branch reads now goes through `toDisplayDate` from `@object-ui/core`, the step its bar tooltip already takes: in the axis headers, the extent computed from the rows, the bar positions, the validity check and the check that the start is not after the end. A date-only value is local midnight of the day it names, and a value with a time part keeps its instant, which the axis places at its local hour in the viewer's day. A number or a `Date` is an instant and is read as before. West of UTC the headers no longer read the day before: a day axis over October 5th to 7th reads Oct 5, Oct 6, Oct 7, and the schema catalog's `gantt-style-timeline.json` reads Jan 2024 to Apr 2024, where it read Dec 2023, Jan 2024, Mar 2024, Apr 2024 in Los Angeles. So the axis now agrees with the bar tooltip. The computed extent is printed as the viewer's calendar day. An empty plan's one-day axis is the viewer's today, where it was the UTC day. A bar date naming a day its month does not have, such as `2026-02-30`, is now refused by the render-time "not a valid date" message, where it was rolled into March and drawn there. `generateTimeScaleHeaders`, which the package exports, reads a date-only `minDate` / `maxDate` the same way.
+- **Formula date functions.** `DATEADD`, `DATEDIFF` and `DATEFORMAT` in `@object-ui/core` now do a calendar day's arithmetic on the UTC calendar. A date-only value naming a day its month has is read as UTC midnight of that day, as before, and is now moved and read with UTC setters and getters, so what the three answer for a day no longer depends on the viewer's zone. `DATEADD` hands such a day moved by days, months or years back as `YYYY-MM-DD`, where it gave an instant string. Its months clamp to the target month's last day, as the server's `addMonths` does: `DATEADD('2026-01-31', 1, 'month')` is `2026-02-28`, where it was `2026-03-03T00:00:00.000Z` in every zone, and a year from February 29th is February 28th. West of UTC, `DATEFORMAT('2026-09-01', 'YYYY-MM-DD')` no longer prints `2026-08-31`, `DATEDIFF` in months or years counts between the stored days rather than the days before them (`DATEDIFF('2026-08-31', '2026-09-01', 'month')` read 0), and a day added across a DST change no longer lands an hour off midnight. A value with a time part is unchanged: it is still moved and read in the viewer's zone and comes back as an instant, so `DATEFORMAT` still prints an instant's clock in the viewer's zone. So is a date-only value naming a day its month does not have, which the engine rolls forward as before. `TODAY()` is unchanged.
@@ -340,6 +340,8 @@ const mediumProject: TimelineSchema['scale'] = 'week'  // medium projects
 const longProject: TimelineSchema['scale'] = 'month'   // long projects
 ```
 
+A date-only bar date, `minDate` or `maxDate` (`2024-01-15`) names a calendar day, so the axis headers, the bar positions and the bar tooltips all place it on that day in every viewer's time zone. A value with a time part is an instant and sits at its hour in the viewer's day. A plan with no bar dates and no pinned range shows a one-day axis on the viewer's today.
+
 ## Customization
 
 ### Custom Icons
 
@@ -17,11 +17,124 @@
  * @packageDocumentation
  */
 
+import { isRealCalendarDate } from '../utils/date-display.js';
+
 /**
  * A formula function that can be registered with the expression evaluator
  */
 export type FormulaFunction = (...args: any[]) => any;
 
+/**
+ * One argument of `DATEADD` / `DATEDIFF` / `DATEFORMAT` (objectui#10866,
+ * slice 3).
+ *
+ * `date` is the engine's own parse, as it always was: a date-only
+ * `YYYY-MM-DD` is UTC midnight of the day it names, and a value with a time
+ * part is its instant. `day` says the argument IS a calendar day: a date-only
+ * string naming a day its month has, by the shared judgement
+ * `isRealCalendarDate`. Only a day takes the UTC calendar. Anything else (an
+ * instant, or a date-only string naming a day its month does not have, which
+ * the engine rolls forward) keeps the path every argument took before: local
+ * setters and getters, in the zone the formula runs in, and an instant out.
+ */
+interface FormulaDate {
+  date: Date;
+  day: boolean;
+}
+
+/** Read one date argument, or throw the function's named error. */
+function readFormulaDate(fn: string, value: string | number | Date): FormulaDate {
+  const date = new Date(value);
+  if (isNaN(date.getTime())) {
+    throw new Error(`${fn}: Invalid date "${value}"`);
+  }
+  return { date, day: typeof value === 'string' && isRealCalendarDate(value) };
+}
+
+/**
+ * The calendar fields of one argument. A day's are read with UTC getters,
+ * which read back the day it names in every zone; an instant's are read with
+ * local getters, in the zone the formula runs in, as they always were.
+ */
+function calendarFields({ date, day }: FormulaDate): {
+  year: number;
+  month: number;
+  date: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+} {
+  return day
+    ? {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth(),
+        date: date.getUTCDate(),
+        hours: date.getUTCHours(),
+        minutes: date.getUTCMinutes(),
+        seconds: date.getUTCSeconds(),
+      }
+    : {
+        year: date.getFullYear(),
+        month: date.getMonth(),
+        date: date.getDate(),
+        hours: date.getHours(),
+        minutes: date.getMinutes(),
+        seconds: date.getSeconds(),
+      };
+}
+
+/**
+ * Move `date` by `months` calendar months on the UTC calendar, clamping the
+ * day to the target month's last day: January 31st plus one month is February
+ * 28th (29th in a leap year), never an overflow into March.
+ *
+ * This is the server's rule, objectstack `@objectstack/formula`'s stdlib
+ * `addMonthsUtc` behind CEL `addMonths(d, n)`, written the same way: step to
+ * the 1st, move the month, then clamp the day. Only a calendar day is moved
+ * with it; an instant keeps `setMonth`, which it always had.
+ */
+function addMonthsUtc(date: Date, months: number): void {
+  const day = date.getUTCDate();
+  date.setUTCDate(1);
+  date.setUTCMonth(date.getUTCMonth() + months);
+  const lastDay = new Date(date.getTime());
+  lastDay.setUTCMonth(lastDay.getUTCMonth() + 1, 0);
+  date.setUTCDate(Math.min(day, lastDay.getUTCDate()));
+}
+
+/**
+ * `DATEADD` on a calendar day, on the UTC calendar: days, months and years
+ * hand the day back as `YYYY-MM-DD`; hours and minutes give an instant, UTC
+ * midnight of the day moved. `undefined` for a unit `DATEADD` does not know.
+ */
+function addToDay(date: Date, amount: number, normalizedUnit: string): string | undefined {
+  switch (normalizedUnit) {
+    case 'day':
+    case 'days':
+      date.setUTCDate(date.getUTCDate() + amount);
+      break;
+    case 'month':
+    case 'months':
+      addMonthsUtc(date, amount);
+      break;
+    case 'year':
+    case 'years':
+      addMonthsUtc(date, amount * 12);
+      break;
+    case 'hour':
+    case 'hours':
+      date.setUTCHours(date.getUTCHours() + amount);
+      return date.toISOString();
+    case 'minute':
+    case 'minutes':
+      date.setUTCMinutes(date.getUTCMinutes() + amount);
+      return date.toISOString();
+    default:
+      return undefined;
+  }
+  return date.toISOString().slice(0, 10);
+}
+
 /**
  * Registry of built-in formula functions
  */
@@ -149,12 +262,43 @@ export class FormulaFunctions {
       return new Date().toISOString();
     });
 
+    /**
+     * `DATEADD`, `DATEDIFF` and `DATEFORMAT` do a calendar DAY's arithmetic on
+     * the UTC calendar, the server's (objectstack ADR-0053 D1: a calendar day
+     * is UTC midnight of that day), with UTC setters and getters, so what they
+     * answer for a day does not depend on the zone the formula runs in
+     * (objectui#10866, slice 3). A day is a date-only argument naming a day
+     * its month has.
+     *
+     * - A day is read as UTC midnight of that day. `DATEADD` hands a day moved
+     *   by days, months or years back as `YYYY-MM-DD`; hours and minutes on a
+     *   day give an instant, UTC midnight of the day moved.
+     * - A day's months clamp to the target month's last day, as the server's
+     *   `addMonths` does; a year is twelve months on the same rule, so
+     *   February 29th plus a year is February 28th.
+     * - `DATEFORMAT` prints a day as itself, and `DATEDIFF` counts months and
+     *   years between two days' own months and years.
+     * - Anything else, a value with a time part included, is unchanged: it is
+     *   moved and read with local setters and getters, in the zone the formula
+     *   runs in, and `DATEADD` hands it back as an instant (`toISOString()`).
+     *
+     * A day used to take that same local path: west of UTC `DATEFORMAT`
+     * printed a date-only value as the day before, `DATEDIFF` in months from
+     * August 31st to September 1st read 0, and a `DATEADD` of a day across a
+     * DST change moved an hour off midnight; and a month from January 31st
+     * overflowed into March in every zone. Pinned in both directions by
+     * `__tests__/FormulaFunctions.dateOnlyZone-10866.test.ts`.
+     */
     this.register('DATEADD', (dateStr: string, amount: number, unit: string): string => {
-      const date = new Date(dateStr);
-      if (isNaN(date.getTime())) {
-        throw new Error(`DATEADD: Invalid date "${dateStr}"`);
-      }
+      const { date, day } = readFormulaDate('DATEADD', dateStr);
       const normalizedUnit = String(unit).toLowerCase();
+      if (day) {
+        const moved = addToDay(date, amount, normalizedUnit);
+        if (moved === undefined) {
+          throw new Error(`DATEADD: Unsupported unit "${unit}"`);
+        }
+        return moved;
+      }
       switch (normalizedUnit) {
         case 'day':
         case 'days':
@@ -183,26 +327,23 @@ export class FormulaFunctions {
     });
 
     this.register('DATEDIFF', (dateStr1: string, dateStr2: string, unit: string): number => {
-      const date1 = new Date(dateStr1);
-      const date2 = new Date(dateStr2);
-      if (isNaN(date1.getTime())) {
-        throw new Error(`DATEDIFF: Invalid date "${dateStr1}"`);
-      }
-      if (isNaN(date2.getTime())) {
-        throw new Error(`DATEDIFF: Invalid date "${dateStr2}"`);
-      }
-      const diffMs = date2.getTime() - date1.getTime();
+      const first = readFormulaDate('DATEDIFF', dateStr1);
+      const second = readFormulaDate('DATEDIFF', dateStr2);
+      const diffMs = second.date.getTime() - first.date.getTime();
       const normalizedUnit = String(unit).toLowerCase();
       switch (normalizedUnit) {
         case 'day':
         case 'days':
           return Math.floor(diffMs / (1000 * 60 * 60 * 24));
         case 'month':
-        case 'months':
-          return (date2.getFullYear() - date1.getFullYear()) * 12 + (date2.getMonth() - date1.getMonth());
+        case 'months': {
+          const a = calendarFields(first);
+          const b = calendarFields(second);
+          return (b.year - a.year) * 12 + (b.month - a.month);
+        }
         case 'year':
         case 'years':
-          return date2.getFullYear() - date1.getFullYear();
+          return calendarFields(second).year - calendarFields(first).year;
         case 'hour':
         case 'hours':
           return Math.floor(diffMs / (1000 * 60 * 60));
@@ -215,19 +356,16 @@ export class FormulaFunctions {
     });
 
     this.register('DATEFORMAT', (dateStr: string, format: string): string => {
-      const date = new Date(dateStr);
-      if (isNaN(date.getTime())) {
-        throw new Error(`DATEFORMAT: Invalid date "${dateStr}"`);
-      }
+      const fields = calendarFields(readFormulaDate('DATEFORMAT', dateStr));
       const pad = (n: number, len = 2) => String(n).padStart(len, '0');
       return format
-        .replace('YYYY', String(date.getFullYear()))
-        .replace('YY', String(date.getFullYear()).slice(-2))
-        .replace('MM', pad(date.getMonth() + 1))
-        .replace('DD', pad(date.getDate()))
-        .replace('HH', pad(date.getHours()))
-        .replace('mm', pad(date.getMinutes()))
-        .replace('ss', pad(date.getSeconds()));
+        .replace('YYYY', String(fields.year))
+        .replace('YY', String(fields.year).slice(-2))
+        .replace('MM', pad(fields.month + 1))
+        .replace('DD', pad(fields.date))
+        .replace('HH', pad(fields.hours))
+        .replace('mm', pad(fields.minutes))
+        .replace('ss', pad(fields.seconds));
     });
   }