@antelopejs/dms 0.8.2 → 0.9.0

package/frontend-vue/layers/dms-ui/app/build/composables/form/formRecordLoad.ts

@@ -1,4 +1,4 @@
-import { type Ref, ref } from "vue";
+import { type Ref, ref, watch } from "vue";
 import { apiErrorStatus } from "#dms-core/app/composables/useFieldErrors";
 import { HTTP_FORBIDDEN } from "#dms-core/app/utils/http-status";
 
@@ -27,9 +27,7 @@ export function missingRecordFailure(
   address: FormRecordAddress,
 ): FormLoadFailure | null {
   const isMissing =
-    !!address.requiresRecord &&
-    !!address.fetchUrl &&
-    !address.resolvedFetchUrl;
+    !!address.requiresRecord && !!address.fetchUrl && !address.resolvedFetchUrl;
   return isMissing ? "missing" : null;
 }
 
@@ -56,15 +54,31 @@ export function formLoadFailure(error: unknown): FormLoadFailure | null {
   return apiErrorStatus(error) === HTTP_FORBIDDEN ? "forbidden" : "error";
 }
 
+/** How a form takes the answers of its record's later reads. */
+export interface FormRecordLoadOptions {
+  /**
+   * Whether the user holds edits a later read must not replace: the read is
+   * then left for the next opening (a save reads the record again).
+   */
+  isEditing?: () => boolean;
+  /** Called once a later read was applied: its values are the saved ones. */
+  onReloaded?: () => void;
+}
+
 /**
  * Follow a form's record load: `apply` receives the record once it loaded,
  * and only then. A failed load is never applied, not even the values a
  * previous opening left in the cache: a form showing them, or its defaults,
  * would read as the record and save over it.
+ *
+ * The record is read again in the background each time the form mounts on a
+ * cached one, and when the page refreshes its data: the form opens on the
+ * cached values, then takes the new ones, unless the user started editing.
  */
 export function trackFormRecordLoad<T>(
   load: FormLoadSource<T>,
   apply: (payload: T) => void,
+  options: FormRecordLoadOptions = {},
 ): FormRecordLoad {
   const failure = ref<FormLoadFailure | null>(null);
   const retrying = ref(false);
@@ -74,6 +88,11 @@ export function trackFormRecordLoad<T>(
     if (!failure.value && payload) apply(payload);
   };
   settle();
+  watch([load.data, load.error], () => {
+    if (options.isEditing?.()) return;
+    settle();
+    if (!failure.value) options.onReloaded?.();
+  });
   return {
     failure,
     retrying,

package/frontend-vue/layers/dms-ui/app/build/composables/live/usePageDataRefresh.ts

@@ -0,0 +1,101 @@
+import { onScopeDispose, type Ref, watch } from "vue";
+import { refreshDmsPageData } from "#dms/frontend-module";
+import type { RealtimeTopicHandler } from "../../../../../dms-core/app/composables/realtime/useUserRealtime";
+import {
+  onPageBlocksRefresh,
+  waitForPageBlocksRefresh,
+} from "../../../utils/blockRefresh";
+import { useRefreshTriggers } from "../blocks/useRefreshTriggers";
+
+// One frame: the events of one burst (a bulk edit) read the data once.
+const BURST_WINDOW_MS = 16;
+
+/** What the page's data refresh listens to. */
+export interface PageDataRefreshSource {
+  /** The page's realtime topics, once its session is subscribed to it. */
+  pageTopics: Ref<string[]>;
+  subscribe(topic: string, handler: RealtimeTopicHandler): () => void;
+}
+
+/**
+ * Reads again the data the page's components show through `useApiData` (and
+ * `useDmsAsyncData`), with `refreshDmsPageData()`: on each
+ * `refreshPageBlocks()`, an action of the user, at once; on each event of one
+ * of the page's realtime topics and each `refreshLivePageBlocks()`, through
+ * the page's live gate, like a built-in block. A read opts out with
+ * `refreshOnPageRefresh: false`, as the built-in blocks that refresh on their
+ * own triggers do. The page renderer calls it once, from its setup;
+ * `refreshPageBlocks()` resolves once the refresh it asked for is done.
+ */
+export function usePageDataRefresh(source: PageDataRefreshSource): void {
+  const { refresh, cancel } = burstRefresh();
+  const gate = useRefreshTriggers(undefined, () => void refresh());
+  // The gate's own listener reads at once on the same event: this call joins
+  // the same burst, and hands its promise to the caller.
+  const stopWaiting = onPageBlocksRefresh((event) =>
+    waitForPageBlocksRefresh(event, refresh()),
+  );
+  // Presence snapshots ride the same topics: they carry no `type`.
+  const onEvent: RealtimeTopicHandler = (event) => {
+    if ("type" in event) gate.trigger(event);
+  };
+  let unsubscribes: Array<() => void> = [];
+  const unsubscribeAll = () => {
+    for (const unsubscribe of unsubscribes) unsubscribe();
+    unsubscribes = [];
+  };
+  watch(
+    source.pageTopics,
+    (topics) => {
+      unsubscribeAll();
+      unsubscribes = topics.map((topic) => source.subscribe(topic, onEvent));
+    },
+    { immediate: true },
+  );
+  onScopeDispose(() => {
+    unsubscribeAll();
+    stopWaiting();
+    cancel();
+  });
+}
+
+interface BurstRefresh {
+  /** Joins the burst under way, or starts one; resolves once it is read. */
+  refresh(): Promise<void>;
+  cancel(): void;
+}
+
+interface Burst {
+  promise: Promise<void>;
+  done(): void;
+}
+
+function startBurst(): Burst {
+  let done!: () => void;
+  const promise = new Promise<void>((resolve) => {
+    done = resolve;
+  });
+  return { promise, done };
+}
+
+/** `refreshDmsPageData()`, once for the calls of one burst. */
+function burstRefresh(): BurstRefresh {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let burst: Burst | undefined;
+  return {
+    refresh() {
+      clearTimeout(timer);
+      const current = (burst ??= startBurst());
+      timer = setTimeout(() => {
+        burst = undefined;
+        refreshDmsPageData().then(current.done, current.done);
+      }, BURST_WINDOW_MS);
+      return current.promise;
+    },
+    cancel() {
+      clearTimeout(timer);
+      burst?.done();
+      burst = undefined;
+    },
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/navigation/useNavBadges.ts

@@ -10,17 +10,25 @@ export interface NavBadge {
 /** A menu entry as the server serves it, as far as its badge goes. */
 export interface ServedNavBadge {
   fullId?: string;
+  /** A static badge the page declares. */
   badge?: string;
-  /** The tone of a counted badge; neutral when absent. */
   badgeTone?: Tone;
 }
 
+/** A badge a page visit carries (`navBadges`), counted for this visit. */
+export interface CountedNavBadge {
+  badge: string;
+  /** Neutral when absent. */
+  tone?: Tone;
+}
+
 /**
- * Fresh counts a page publishes for its navigation entry, by page full id
+ * The counts of the navigation entries, by page full id
  * (`settings.workspace.members` → `{ label: "7" }`, `""` for none), with
- * their tone. The server counts a table view tab declared with `navBadge`
- * when the menu loads; the table publishes its own counter here once shown,
- * which navigation surfaces draw over the server's badge.
+ * their tone. Each page visit brings the ones the server counted for it
+ * (`navBadges`, a page prop: the site layout a browser keeps for minutes
+ * holds none), and a table view tab declared with `navBadge` publishes its
+ * own counter once shown; navigation surfaces draw them over a static badge.
  *
  * Shared state, so a count published on one page stays shown on the others.
  */
@@ -29,6 +37,7 @@ export const useNavBadges = () => {
     "dms-nav-badges",
     () => ({}),
   );
+  const servedIds = useDmsState<string[]>("dms-served-nav-badges", () => []);
 
   /** Sets, or with `undefined` clears, the badge of a page. */
   function setNavBadge(
@@ -61,5 +70,23 @@ export const useNavBadges = () => {
     return badge?.label ? badge : undefined;
   }
 
-  return { badges, setNavBadge, navBadgeOf };
+  /**
+   * Takes the counts a page visit carries: each one replaces the entry's
+   * badge, and an entry the previous visit counted that this one does not
+   * (its count fell to zero) loses its badge.
+   */
+  function applyCountedNavBadges(
+    counted: Record<string, CountedNavBadge> | undefined,
+  ): void {
+    if (!counted) return;
+    for (const fullId of servedIds.value) {
+      if (!(fullId in counted)) setNavBadge(fullId, "");
+    }
+    for (const [fullId, { badge, tone }] of Object.entries(counted)) {
+      setNavBadge(fullId, badge, tone);
+    }
+    servedIds.value = Object.keys(counted);
+  }
+
+  return { badges, setNavBadge, navBadgeOf, applyCountedNavBadges };
 };

package/frontend-vue/layers/dms-ui/app/build/composables/period/periodDisplay.ts

@@ -14,6 +14,7 @@ import {
   type PeriodRange,
 } from "#dms-core/app/composables/period/types";
 import { regionalDateTimeFormat } from "#dms-core/app/utils/regional";
+import { readerClock } from "#dms-core/app/composables/period/periodClock";
 
 /** A day range as the range calendar reads and writes it. */
 export interface CalendarRange {
@@ -102,20 +103,16 @@ export function isBeyondMaxDays(
   return Math.abs(date.compare(pickedDay)) >= maxDays;
 }
 
+// A period's days are the reader's calendar days (`readerClock`), on the
+// server as in the browser.
 function isStartOfDay(date: Date): boolean {
-  return (
-    date.getHours() === 0 &&
-    date.getMinutes() === 0 &&
-    date.getSeconds() === 0 &&
-    date.getMilliseconds() === 0
-  );
+  const { hours, minutes, seconds, milliseconds } = readerClock().wall(date);
+  return hours === 0 && minutes === 0 && seconds === 0 && milliseconds === 0;
 }
 
 function isEndOfDay(date: Date): boolean {
-  return (
-    date.getHours() === END_OF_DAY_HOURS &&
-    date.getMinutes() === END_OF_DAY_MINUTES
-  );
+  const { hours, minutes } = readerClock().wall(date);
+  return hours === END_OF_DAY_HOURS && minutes === END_OF_DAY_MINUTES;
 }
 
 // Up to a day and an hour: `last-24h` plus slack for a DST shift.
@@ -207,11 +204,16 @@ const YESTERDAY_OFFSET = -1;
 const WEEKDAY_FORMAT: FormatOptions = { weekday: "short" };
 
 function localDayStart(date: Date): number {
-  return new Date(
-    date.getFullYear(),
-    date.getMonth(),
-    date.getDate(),
-  ).getTime();
+  const clock = readerClock();
+  return clock
+    .instant({
+      ...clock.wall(date),
+      hours: 0,
+      minutes: 0,
+      seconds: 0,
+      milliseconds: 0,
+    })
+    .getTime();
 }
 
 function daysBefore(date: Date, now: Date): number {
@@ -235,7 +237,8 @@ function relativeDayPrefix(date: Date, now: Date, locale: string): string {
   if (days < DAYS_PER_WEEK) {
     return `${formatWith(date, locale, WEEKDAY_FORMAT)} `;
   }
-  const sameYear = date.getFullYear() === now.getFullYear();
+  const clock = readerClock();
+  const sameYear = clock.wall(date).year === clock.wall(now).year;
   const day: FormatOptions = sameYear
     ? DAY_FORMAT
     : { ...DAY_FORMAT, year: "numeric" };

package/frontend-vue/layers/dms-ui/app/build/composables/period/periodQuery.ts

@@ -8,6 +8,10 @@ import {
   type PeriodRange,
 } from "#dms-core/app/composables/period/types";
 import type { PeriodQueryKeys } from "#dms-core/app/composables/period/periodLink";
+import {
+  readerClock,
+  type WallTime,
+} from "#dms-core/app/composables/period/periodClock";
 
 export {
   type PeriodQueryKeys,
@@ -67,27 +71,41 @@ function readText(query: PeriodQuery, key: string): string | undefined {
 
 type DayBoundary = "start" | "end";
 
-function dayBoundary(day: Date, boundary: DayBoundary): Date {
-  if (boundary === "end") {
-    day.setHours(
-      END_OF_DAY_HOURS,
-      END_OF_DAY_MINUTES,
-      END_OF_DAY_SECONDS,
-      END_OF_DAY_MS,
-    );
-  }
-  return day;
+const DAY_BOUNDARY_TIMES: Record<
+  DayBoundary,
+  Pick<WallTime, "hours" | "minutes" | "seconds" | "milliseconds">
+> = {
+  start: { hours: 0, minutes: 0, seconds: 0, milliseconds: 0 },
+  end: {
+    hours: END_OF_DAY_HOURS,
+    minutes: END_OF_DAY_MINUTES,
+    seconds: END_OF_DAY_SECONDS,
+    milliseconds: END_OF_DAY_MS,
+  },
+};
+
+// Days are the reader's calendar days (`readerClock`): the browser's zone,
+// on the server as in the browser.
+function dayBoundary(
+  wall: Pick<WallTime, "year" | "month" | "day">,
+  boundary: DayBoundary,
+): Date {
+  return readerClock().instant({ ...wall, ...DAY_BOUNDARY_TIMES[boundary] });
 }
 
 /** A local calendar day, refused when it does not exist (`2026-02-30`). */
 function parseIsoDay(match: RegExpExecArray, boundary: DayBoundary) {
   const [year, month, day] = match.slice(1).map(Number);
-  const date = new Date(year!, month! - MONTH_OFFSET, day);
+  const date = dayBoundary(
+    { year: year!, month: month! - MONTH_OFFSET, day: day! },
+    boundary,
+  );
+  const wall = readerClock().wall(date);
   const exists =
-    date.getFullYear() === year &&
-    date.getMonth() === month! - MONTH_OFFSET &&
-    date.getDate() === day;
-  return exists ? dayBoundary(date, boundary) : null;
+    wall.year === year &&
+    wall.month === month! - MONTH_OFFSET &&
+    wall.day === day;
+  return exists ? date : null;
 }
 
 /**
@@ -112,8 +130,9 @@ function pad(value: number, length = DATE_PART_LENGTH): string {
 }
 
 function isDayBoundary(date: Date, boundary: DayBoundary): boolean {
-  const day = new Date(date.getFullYear(), date.getMonth(), date.getDate());
-  return dayBoundary(day, boundary).getTime() === date.getTime();
+  return (
+    dayBoundary(readerClock().wall(date), boundary).getTime() === date.getTime()
+  );
 }
 
 /**
@@ -122,10 +141,11 @@ function isDayBoundary(date: Date, boundary: DayBoundary): boolean {
  */
 export function formatPeriodDate(date: Date, boundary: DayBoundary): string {
   if (!isDayBoundary(date, boundary)) return date.toISOString();
+  const { year, month, day } = readerClock().wall(date);
   return [
-    pad(date.getFullYear(), YEAR_PART_LENGTH),
-    pad(date.getMonth() + MONTH_OFFSET),
-    pad(date.getDate()),
+    pad(year, YEAR_PART_LENGTH),
+    pad(month + MONTH_OFFSET),
+    pad(day),
   ].join("-");
 }
 

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useTableFooter.ts

@@ -4,7 +4,6 @@ import type {
   TableViewFooter,
   TableViewFooterSummaryConfig,
 } from "../../../composables/table-view/types";
-import { useServerRenderedAsyncData } from "./useServerRenderedAsyncData";
 import type {
   TableFooterLegendItem,
   TableFooterTexts,
@@ -35,10 +34,9 @@ const UNSORTED_KEYS = new Set(["sortKey", "sortDirection"]);
  * route computes over every listed row — a sum read like its column's cells
  * unless a `format` is given — and the legend of a select column.
  */
-export async function useTableFooter(options: TableFooterOptions) {
+export function useTableFooter(options: TableFooterOptions) {
   const { footer, columns, location } = options;
   const summaries = footer?.summary ?? [];
-  const { $authFetch } = useAuthFetch();
   const { locale } = useI18n();
   const { processI18n } = useTranslation();
   const { renderValue } = useColumnValueRenderer();
@@ -52,17 +50,17 @@ export async function useTableFooter(options: TableFooterOptions) {
     ids: summaries.map((summary) => summary.id),
   }));
 
-  const { data: values, refresh } = await useServerRenderedAsyncData<
-    Record<string, number>
-  >(
+  const { data: values, refresh } = useApiData<Record<string, number>>(
     `${options.dataKey}-summary`,
-    () =>
+    ({ $authFetch, signal }) =>
       summaries.length === 0
         ? Promise.resolve({})
         : $authFetch<Record<string, number>>(`${location}/summary`, {
             query: summaryQuery.value,
+            signal,
           }),
-    { watch: [summaryQuery] },
+    // Read again with the table's rows, on the table's own triggers.
+    { lazy: true, watch: [summaryQuery], refreshOnPageRefresh: false },
   );
 
   const formatSummary = (

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useTableListData.ts

@@ -1,6 +1,5 @@
-import type { ComputedRef } from "vue";
+import { computed, type ComputedRef } from "vue";
 import type { TableViewListResponse } from "../../../composables/table-view/types";
-import { useServerRenderedAsyncData } from "./useServerRenderedAsyncData";
 import type { useTableRows } from "./useTableRows";
 import { buildTableDataKey } from "./utils/tableQuery";
 
@@ -43,6 +42,14 @@ export interface TableCountsDataOptions<T extends Record<string, unknown>> {
 
 const NO_HELD_QUERY = (): Query => ({});
 
+/**
+ * A watch source following `source` by value: a query rebuilt equal (its
+ * inputs recomputed to the same values, a period re-resolved to the same
+ * bounds) must not read the rows again.
+ */
+const byValue = (source: ComputedRef<unknown>): ComputedRef<string> =>
+  computed(() => JSON.stringify(source.value));
+
 const EMPTY_LIST_RESULT: TableViewListResponse<never> = {
   results: [],
   total: 0,
@@ -51,7 +58,10 @@ const EMPTY_LIST_RESULT: TableViewListResponse<never> = {
 };
 
 /**
- * The page of rows a table view shows. The key names the source URL: a
+ * The page of rows a table view shows: awaited by a server render, which
+ * transfers it, but not by a client navigation, which paints the list chrome
+ * and its skeleton at once (`lazy`). Read the loading state from `data`
+ * (`null` until the first result). The key names the source URL: a
  * navigation that remounts the page while the previous one is still on screen
  * binds to the cached entry of its key, so another URL needs another key to be
  * requested at all, and the watch covers a page kept mounted.
@@ -69,14 +79,27 @@ export function useTableListData<T extends Record<string, unknown>>(
     isSelfManaged: isSelfManaged.value,
     sourceUrl: rows.sourceUrl.value,
   });
-  return useServerRenderedAsyncData(
+  return useDmsAsyncData(
     key,
     // `null` while a source waits on its period scope: the table's skeleton.
-    (): Promise<TableViewListResponse<T> | null> =>
+    ({ signal }): Promise<TableViewListResponse<T> | null> =>
       isSelfManaged.value
         ? Promise.resolve(EMPTY_LIST_RESULT)
-        : rows.list({ ...query.value, ...archiveQuery.value, ...heldQuery() }),
-    { watch: [query, archiveQuery, isSelfManaged, rows.sourceUrl] },
+        : rows.list(
+            { ...query.value, ...archiveQuery.value, ...heldQuery() },
+            signal,
+          ),
+    {
+      watch: [
+        byValue(query),
+        byValue(archiveQuery),
+        isSelfManaged,
+        rows.sourceUrl,
+      ],
+      lazy: true,
+      // The table reads again on its own triggers, through its live hold.
+      refreshOnPageRefresh: false,
+    },
   );
 }
 
@@ -84,10 +107,10 @@ export function useTableListData<T extends Record<string, unknown>>(
  * The counters of a table view's tabs and views, keyed by id; `null` until
  * they arrive. Keyed by source URL like the list (see useTableListData).
  *
- * A source waiting on its period scope answers `null` too, like its list:
- * the scope never registers during the server render, so the server and the
- * browser (whose key carries the period, and has no payload yet) both draw
- * the counters' skeleton, and hydration matches.
+ * A source waiting on its period scope answers `null` too, like its list: a
+ * server render that cannot resolve the period as the browser will (see
+ * `usePeriodScope`) draws the counters' skeleton, as the browser does until
+ * its own request answers, and hydration matches.
  */
 export function useTableCountsData<T extends Record<string, unknown>>(
   options: TableCountsDataOptions<T>,
@@ -95,9 +118,9 @@ export function useTableCountsData<T extends Record<string, unknown>>(
   const { rows, queries, archiveQuery } = options;
   const heldQuery = options.heldQuery ?? NO_HELD_QUERY;
   const sourceSuffix = rows.sourceUrl.value ? `-${rows.sourceUrl.value}` : "";
-  return useServerRenderedAsyncData<Record<string, number> | null>(
+  return useDmsAsyncData<Record<string, number> | null>(
     `table-view-${options.componentId}-${options.pageId}-tab-counts${sourceSuffix}`,
-    async () => {
+    async ({ signal }) => {
       if (rows.isPeriodPending.value) return null;
       if (queries.value.length === 0) return {};
       return await rows.countBatch(
@@ -105,8 +128,13 @@ export function useTableCountsData<T extends Record<string, unknown>>(
           id,
           query: { ...query, ...archiveQuery.value, ...heldQuery() },
         })),
+        signal,
       );
     },
-    { watch: [queries, archiveQuery, rows.sourceUrl] },
+    {
+      watch: [byValue(queries), byValue(archiveQuery), rows.sourceUrl],
+      lazy: true,
+      refreshOnPageRefresh: false,
+    },
   );
 }

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useTableRows.ts

@@ -185,6 +185,7 @@ export function useTableRows<T extends Record<string, unknown>>(
   const listFromSource = async (
     sourceConfig: TableViewSourceConfig,
     query: Query,
+    signal?: AbortSignal,
   ): Promise<TableViewListResponse<T> | null> => {
     if (isPeriodPending.value) return null;
     const url = sourceUrl.value;
@@ -192,6 +193,7 @@ export function useTableRows<T extends Record<string, unknown>>(
     const { capabilities } = sourceConfig;
     const response = await api<{ results: T[]; total: number }>(url, {
       query: sourceRouteQuery(query, capabilities),
+      signal,
     });
     if (capabilities.paginate) {
       return {
@@ -214,30 +216,39 @@ export function useTableRows<T extends Record<string, unknown>>(
   ): TableViewListResponse<T> | null =>
     page && { ...page, results: pinRows(page.results, options.pinnedRows?.()) };
 
-  const list = async (query: Query): Promise<TableViewListResponse<T> | null> =>
+  // `signal` aborts the request once its answer is no longer wanted.
+  const list = async (
+    query: Query,
+    signal?: AbortSignal,
+  ): Promise<TableViewListResponse<T> | null> =>
     withPinnedRows(
       source
-        ? await listFromSource(source, query)
-        : await api<TableViewListResponse<T>>(`${location}/list`, { query }),
+        ? await listFromSource(source, query, signal)
+        : await api<TableViewListResponse<T>>(`${location}/list`, {
+            query,
+            signal,
+          }),
     );
 
   // A source answers its totals one list at a time.
   const countBatch = async (
     queries: TableCountQuery[],
+    signal?: AbortSignal,
   ): Promise<Record<string, number>> => {
     if (!source) {
       return api<Record<string, number>>(`${location}/count/batch`, {
         method: "POST",
         body: { queries },
+        signal,
       });
     }
     const totals = await Promise.all(
       queries.map(async ({ id, query }) => {
-        const page = await listFromSource(source, {
-          ...query,
-          offset: 0,
-          limit: 1,
-        });
+        const page = await listFromSource(
+          source,
+          { ...query, offset: 0, limit: 1 },
+          signal,
+        );
         return page ? [[id, page.total] as const] : [];
       }),
     );

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useTableViews.ts

@@ -64,7 +64,7 @@ const VIEW_NAME_FIELD = "label";
  */
 export function useTableViews(options: TableViewsOptions) {
   const { views, defaults, state, preferences, urlScope } = options;
-  const { user } = useUserSession();
+  const { user } = useDmsUserSession();
   const { t } = useI18n();
   const { processI18n } = useTranslation();
   const toast = useToast();

package/frontend-vue/layers/dms-ui/app/components/chart/ChartCard.vue

@@ -42,7 +42,8 @@ interface Props extends DefaultComponentProps {
 }
 
 // The comparison series takes palette step 2 (v2 violet), re-resolved on
-// theme changes via useThemeRevision so it tracks light/dark mode.
+// theme changes via useThemeRevision so it tracks light/dark mode. Its legend
+// key reads the same token in CSS.
 const COMPARISON_COLOR_TOKEN = "--dms-chart-2";
 const themeRevision = useThemeRevision();
 const comparisonColor = computed(() => {
@@ -236,9 +237,11 @@ const hasMeta = computed(
           {{ primaryLegendLabel }}
         </span>
         <span class="flex items-center gap-1.5">
+          <!-- The token itself, not its resolved value: a server render
+            cannot read the theme, and must draw what the browser draws. -->
           <span
             :class="LEGEND_KEY_CLASS"
-            :style="{ background: comparisonColor }"
+            class="bg-(--dms-chart-2)"
             aria-hidden="true"
           />
           {{ comparisonLegendLabel }}