@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/web/version/update-checker.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Update-Awareness — default an, kein Flag. Ein offener Tab erfährt sonst
+// nie von einem neuen Deploy (SPA bleibt geladen, index.html wird nicht neu
+// geholt → "muss hart reloaden"). Statt Service-Worker (der ist die *Ursache*
+// von "hängt auf alter Version") pollt diese Komponente die statische
+// build-info.json beim Tab-Fokus und zeigt ein Reload-Banner bei Drift.
+//
+// Versionsquelle ist build-info.json (Hash über die Asset-URLs, vom Prod-Build
+// geschrieben) — NICHT /api/version (live leer/404, Env-/Dockerfile-Falle).
+// Banner-Strings über kumikoDefaultTranslations (kumiko.version.*, de/en).
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { useEffect, useState } from "react";
+import { useTranslation } from "../../index.js";
+import { cn } from "../lib/cn.js";
+export function readLoadedBuild() {
+    if (typeof document === "undefined")
+        return undefined;
+    const meta = document.querySelector('meta[name="kumiko-build"]');
+    const id = meta?.getAttribute("content");
+    if (!id)
+        return undefined;
+    return { id, builtAt: meta?.getAttribute("data-built-at") ?? "" };
+}
+// Korrektheitsgrenze der Update-Erkennung: ein Banner NUR bei echtem
+// ID-Drift. Kein geladener Stand (Dev/altes Bundle) oder kein Server-Stand
+// (Fetch-Fehler/kaputtes JSON → null) → nie ein Fake-Banner.
+export function shouldShowUpdate(loadedId, server) {
+    if (!loadedId || !server)
+        return false;
+    return server.id !== loadedId;
+}
+export function isKumikoBuild(v) {
+    return (typeof v === "object" && v !== null && "id" in v && typeof v.id === "string" && v.id !== "");
+}
+async function fetchServerBuild() {
+    try {
+        const res = await fetch("/build-info.json", { cache: "no-store" });
+        if (!res.ok)
+            return null;
+        const raw = await res.json();
+        if (!isKumikoBuild(raw))
+            return null;
+        const builtAt = propertyOf(raw, "builtAt");
+        return { id: raw.id, builtAt: typeof builtAt === "string" ? builtAt : "" };
+    }
+    catch {
+        // Netzwerkfehler / kaputtes JSON → kein Banner. Nie ein Fake-Update zeigen.
+        return null;
+    }
+}
+export function UpdateChecker() {
+    const t = useTranslation();
+    const loaded = readLoadedBuild();
+    const [hasUpdate, setHasUpdate] = useState(false);
+    useEffect(() => {
+        const loadedId = loaded?.id;
+        if (!loadedId)
+            return; // Dev / altes Bundle → keine Awareness.
+        let cancelled = false;
+        const checking = { current: false };
+        const check = async () => {
+            if (document.visibilityState !== "visible")
+                return;
+            if (checking.current)
+                return; // visibilitychange + focus fire together on tab-return
+            checking.current = true;
+            try {
+                const server = await fetchServerBuild();
+                if (!cancelled && shouldShowUpdate(loadedId, server))
+                    setHasUpdate(true);
+            }
+            finally {
+                checking.current = false;
+            }
+        };
+        document.addEventListener("visibilitychange", check);
+        window.addEventListener("focus", check);
+        void check();
+        return () => {
+            cancelled = true;
+            document.removeEventListener("visibilitychange", check);
+            window.removeEventListener("focus", check);
+        };
+    }, [loaded?.id]);
+    if (!hasUpdate)
+        return null;
+    return (_jsxs("div", { role: "status", className: cn("fixed inset-x-0 top-0 z-[200] flex items-center justify-center gap-3", "border-b bg-background px-4 py-2 text-sm text-foreground shadow-md"), children: [_jsx("span", { children: t("kumiko.version.update-available") }), _jsx("button", { type: "button", onClick: () => window.location.reload(), className: cn("rounded-md bg-primary px-3 py-1 text-xs font-medium text-primary-foreground", "hover:opacity-90 focus:outline-none focus:ring-2 focus:ring-ring"), children: t("kumiko.actions.reload") })] }));
+}

package/dist/web/widgets/ai-text-field.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from "react";
+type AiTextAction = "correct" | "translate" | "rewrite";
+interface AiTextFieldBaseProps {
+    readonly label: string;
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly required?: boolean;
+    readonly disabled?: boolean;
+    readonly placeholder?: string;
+    readonly testId?: string;
+    readonly hideLabel?: boolean;
+    /** Ghost-text completion on/off. Default true. */
+    readonly completion?: boolean;
+    /** Debounce for ghost-text requests, ms. Default 500 — kept low in
+     *  tests, tuned for real typing in production. */
+    readonly completionDebounceMs?: number;
+    /** Toolbar actions to expose. Default all three. */
+    readonly actions?: readonly AiTextAction[];
+    /** Target languages the translate action offers. First is preselected.
+     *  Default `["en", "de", "fr", "es"]`. */
+    readonly translateLanguages?: readonly string[];
+}
+export interface AiTextFieldProps extends AiTextFieldBaseProps {
+}
+export interface AiTextAreaProps extends AiTextFieldBaseProps {
+    readonly rows?: number;
+}
+/** Single-line AI text field — ghost-text completion + correct/translate/
+ *  rewrite toolbar. Degrades to a plain text field when `ai-text` isn't
+ *  mounted server-side. */
+export declare function AiTextField(props: AiTextFieldProps): ReactNode;
+/** Multi-line variant of {@link AiTextField}. */
+export declare function AiTextArea(props: AiTextAreaProps): ReactNode;
+export {};

package/dist/web/widgets/ai-text-field.js

@@ -0,0 +1,137 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// AiTextField / AiTextArea — Drop-in replacement for TextField/TextareaField
+// with AI-augmented actions (ai-text-primitive plan doc, Phase 3).
+//
+// Built on raw <input>/<textarea> (not the generic Input primitive) because
+// ghost-text needs a keydown handler (Tab/Esc) and an overlay that the
+// discriminated-union Input contract doesn't expose. Same pattern as
+// MoneyInput — a hand-built control wrapped in Field.
+//
+// Graceful degradation: `useAiTextAction`/`useCompletion` surface
+// "unavailable" when the server feature isn't mounted (`feature_disabled`)
+// — the toolbar hides and the field behaves like a plain text field, no
+// error shown to the end-user.
+//
+// Ghost-text simplification: the overlay only ever appends after the
+// current value (no mid-text ghost) — matches the server prompt design
+// (ai-text's `complete` mode only ever continues forward from the given
+// text). Two-layer overlay trick: an aria-hidden div behind the real
+// input renders `value` (invisible, same font/box so it reserves space)
+// followed by the suggestion in muted color; the real input sits on top
+// with a transparent background so the suggestion shows through past the
+// typed text. Both elements MUST share identical typography/box classes
+// or the suggestion won't align with the caret.
+import { Check, Languages, Wand2 } from "lucide-react";
+import { useLayoutEffect, useRef, useState } from "react";
+import { useAiTextAction, useCompletion, usePrimitives, useTranslation } from "../../index.js";
+import { cn } from "../lib/cn.js";
+import { ModeSwitch } from "./mode-switch.js";
+const DEFAULT_LANGUAGES = ["en", "de", "fr", "es"];
+const DEFAULT_ACTIONS = ["correct", "translate", "rewrite"];
+const REWRITE_STYLES = ["formal", "casual", "concise", "expand"];
+const sharedTextClass = "w-full rounded-md border border-input px-3 py-2 text-sm shadow-sm leading-6 " +
+    "placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 " +
+    "focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50";
+// Overlay and real control must share identical wrap/overflow behavior or the
+// ghost suggestion drifts from the caret: <input> never wraps and scrolls
+// horizontally, <textarea> soft-wraps and scrolls vertically.
+const singleLineWrapClass = "whitespace-pre overflow-hidden";
+const multilineWrapClass = "whitespace-pre-wrap break-words overflow-hidden";
+function AiTextCore({ multiline, label, id, name, value, onChange, required, disabled, placeholder, testId, hideLabel, rows, completion = true, completionDebounceMs = 500, actions = DEFAULT_ACTIONS, translateLanguages = DEFAULT_LANGUAGES, }) {
+    const { Field, Button, Dialog, Text } = usePrimitives();
+    const t = useTranslation();
+    const { suggestion, state: completionState, requestCompletion, clear: clearCompletion, } = useCompletion(completionDebounceMs);
+    const { run: runAction, state: actionState, result: actionResult, reset: resetAction, } = useAiTextAction();
+    const [dialogMode, setDialogMode] = useState(null);
+    const [targetLanguage, setTargetLanguage] = useState(translateLanguages[0] ?? "en");
+    const [rewriteStyle, setRewriteStyle] = useState("concise");
+    const overlayRef = useRef(null);
+    const controlRef = useRef(null);
+    const unavailable = completionState === "unavailable" || actionState === "unavailable";
+    const capExceeded = completionState === "cap-exceeded" || actionState === "cap-exceeded";
+    const showToolbar = !unavailable && actions.length > 0;
+    const showGhost = completion && !unavailable && suggestion !== null && suggestion.length > 0;
+    // ponytail: a manually `resize-y`-shrunk textarea can end up a few px
+    // shorter than the overlay div (which has no resize handle), so the
+    // synced scrollTop clamps slightly early — sub-line drift, invisible at
+    // normal line-height. Upgrade if it ever becomes visually noticeable.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: value/suggestion are trigger-only, effect reads refs not props
+    useLayoutEffect(() => {
+        if (overlayRef.current === null || controlRef.current === null)
+            return;
+        overlayRef.current.scrollLeft = controlRef.current.scrollLeft;
+        overlayRef.current.scrollTop = controlRef.current.scrollTop;
+    }, [value, suggestion]);
+    function handleChange(next) {
+        onChange(next);
+        if (completion && !unavailable) {
+            requestCompletion(next);
+        }
+    }
+    function handleKeyDown(e) {
+        if (suggestion === null)
+            return;
+        if (e.key === "Tab" && e.currentTarget.selectionStart === value.length) {
+            e.preventDefault();
+            onChange(value + suggestion);
+            clearCompletion();
+        }
+        else if (e.key === "Escape") {
+            e.preventDefault();
+            clearCompletion();
+        }
+    }
+    function openDialog(mode) {
+        resetAction();
+        setDialogMode(mode);
+        if (mode === "correct") {
+            void runAction({ mode: "correct", text: value });
+        }
+    }
+    function closeDialog() {
+        setDialogMode(null);
+        resetAction();
+    }
+    function runConfiguredAction() {
+        if (dialogMode === "translate") {
+            void runAction({ mode: "translate", text: value, targetLanguage });
+        }
+        else if (dialogMode === "rewrite") {
+            void runAction({ mode: "rewrite", text: value, style: rewriteStyle });
+        }
+    }
+    function applyResult() {
+        if (actionResult?.type === "text")
+            onChange(actionResult.text);
+    }
+    const needsConfig = (dialogMode === "translate" || dialogMode === "rewrite") &&
+        actionState !== "loading" &&
+        actionState !== "success";
+    return (_jsxs(_Fragment, { children: [_jsxs(Field, { id: id, label: label, required: required, hideLabel: hideLabel, testId: testId, children: [_jsxs("div", { className: "relative w-full", children: [showGhost && (_jsxs("div", { ref: overlayRef, "aria-hidden": "true", className: cn(sharedTextClass, multiline ? multilineWrapClass : singleLineWrapClass, "pointer-events-none absolute inset-0 select-none border-transparent shadow-none"), children: [_jsx("span", { className: "invisible", children: value }), _jsx("span", { className: "text-muted-foreground", children: suggestion })] })), multiline ? (_jsx("textarea", { ref: (el) => {
+                                    controlRef.current = el;
+                                }, id: id, name: name, value: value, required: required, disabled: disabled === true || unavailable, placeholder: placeholder, rows: rows ?? 4, onChange: (e) => handleChange(e.target.value), onKeyDown: handleKeyDown, onBlur: clearCompletion, onScroll: (e) => {
+                                    if (overlayRef.current)
+                                        overlayRef.current.scrollTop = e.currentTarget.scrollTop;
+                                }, className: cn(sharedTextClass, multilineWrapClass, "relative resize-y bg-transparent"), "data-testid": testId !== undefined ? `${testId}-input` : undefined })) : (_jsx("input", { ref: (el) => {
+                                    controlRef.current = el;
+                                }, id: id, name: name, type: "text", value: value, required: required, disabled: disabled === true || unavailable, placeholder: placeholder, onChange: (e) => handleChange(e.target.value), onKeyDown: handleKeyDown, onBlur: clearCompletion, onScroll: (e) => {
+                                    if (overlayRef.current)
+                                        overlayRef.current.scrollLeft = e.currentTarget.scrollLeft;
+                                }, className: cn(sharedTextClass, singleLineWrapClass, "relative bg-transparent"), "data-testid": testId !== undefined ? `${testId}-input` : undefined }))] }), showGhost && _jsx(Text, { variant: "muted", children: t("kumiko.aiText.acceptHint") }), capExceeded && _jsx(Text, { variant: "muted", children: t("kumiko.aiText.capExceeded") }), showToolbar && (_jsxs("div", { className: "mt-1 flex gap-1", children: [actions.includes("correct") && (_jsx(Button, { variant: "secondary", size: "sm", disabled: value.length === 0, ariaLabel: t("kumiko.aiText.correct"), onClick: () => openDialog("correct"), children: _jsx(Check, { className: "size-3.5", "aria-hidden": "true" }) })), actions.includes("translate") && (_jsx(Button, { variant: "secondary", size: "sm", disabled: value.length === 0, ariaLabel: t("kumiko.aiText.translate"), onClick: () => openDialog("translate"), children: _jsx(Languages, { className: "size-3.5", "aria-hidden": "true" }) })), actions.includes("rewrite") && (_jsx(Button, { variant: "secondary", size: "sm", disabled: value.length === 0, ariaLabel: t("kumiko.aiText.rewrite"), onClick: () => openDialog("rewrite"), children: _jsx(Wand2, { className: "size-3.5", "aria-hidden": "true" }) }))] }))] }), _jsxs(Dialog, { open: dialogMode !== null, onOpenChange: (open) => {
+                    if (!open)
+                        closeDialog();
+                }, title: dialogMode !== null ? t(`kumiko.aiText.${dialogMode}`) : "", onConfirm: applyResult, testId: testId !== undefined ? `${testId}-dialog` : undefined, children: [dialogMode === "translate" && needsConfig && (_jsxs("div", { className: "mb-3 flex flex-col gap-2", children: [_jsx(ModeSwitch, { value: targetLanguage, options: translateLanguages.map((l) => ({ value: l, label: l.toUpperCase() })), onChange: setTargetLanguage }), _jsx(Button, { variant: "primary", size: "sm", onClick: runConfiguredAction, children: t(`kumiko.aiText.${dialogMode}`) })] })), dialogMode === "rewrite" && needsConfig && (_jsxs("div", { className: "mb-3 flex flex-col gap-2", children: [_jsx(ModeSwitch, { value: rewriteStyle, options: REWRITE_STYLES.map((s) => ({
+                                    value: s,
+                                    label: t(`kumiko.aiText.style.${s}`),
+                                })), onChange: setRewriteStyle }), _jsx(Button, { variant: "primary", size: "sm", onClick: runConfiguredAction, children: t(`kumiko.aiText.${dialogMode}`) })] })), actionState === "loading" && (_jsx(Text, { variant: "muted", children: t("kumiko.aiText.diff.generating") })), actionState === "success" && actionResult?.type === "text" && (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsxs("div", { children: [_jsx(Text, { variant: "small", children: t("kumiko.aiText.diff.before") }), _jsx("p", { className: "whitespace-pre-wrap rounded-md border border-input bg-muted/40 p-2 text-sm", children: value })] }), _jsxs("div", { children: [_jsx(Text, { variant: "small", children: t("kumiko.aiText.diff.after") }), _jsx("p", { className: "whitespace-pre-wrap rounded-md border border-input p-2 text-sm", children: actionResult.text })] })] }))] })] }));
+}
+/** Single-line AI text field — ghost-text completion + correct/translate/
+ *  rewrite toolbar. Degrades to a plain text field when `ai-text` isn't
+ *  mounted server-side. */
+export function AiTextField(props) {
+    return _jsx(AiTextCore, { ...props, multiline: false });
+}
+/** Multi-line variant of {@link AiTextField}. */
+export function AiTextArea(props) {
+    return _jsx(AiTextCore, { ...props, multiline: true });
+}

package/dist/web/widgets/chart-window.d.ts

@@ -0,0 +1,58 @@
+export type ChartWindow = {
+    readonly startMs: number;
+    readonly endMs: number;
+};
+export type StackedAreaRangeOption = {
+    readonly value: string;
+    /** Translated by the caller. */
+    readonly label: string;
+    /** Window length in months; omitted shows the full window. */
+    readonly months?: number;
+};
+export type StackedAreaRanges = {
+    readonly options: readonly StackedAreaRangeOption[];
+    readonly default: string;
+};
+export type StackedAreaWindowSelection = {
+    readonly kind: "range";
+    readonly value: string;
+} | {
+    readonly kind: "brush";
+    readonly startMs: number;
+    readonly endMs: number;
+} | {
+    readonly kind: "from-today";
+};
+export type StackedAreaInitialWindow = "default-range" | "from-today";
+export type StackedAreaDateFormat = "day" | "month";
+export declare function stackedAreaDateFormatFor(window: ChartWindow): StackedAreaDateFormat;
+export declare function addUtcMonths(atMs: number, months: number): number;
+export declare function rangeWindow(months: number, anchorMs: number, firstMs: number, lastMs: number): ChartWindow;
+export declare function pointsWithin<T extends {
+    readonly atMs: number;
+}>(points: readonly T[], window: ChartWindow): readonly T[];
+export declare function initialWindowSelection(ranges: StackedAreaRanges | undefined, initialWindow?: StackedAreaInitialWindow): StackedAreaWindowSelection | undefined;
+export declare function resolveStackedAreaWindow({ selection, ranges, brush, todayMs, bucketTimes, fullWindow, }: {
+    readonly selection: StackedAreaWindowSelection | undefined;
+    readonly ranges: StackedAreaRanges | undefined;
+    readonly brush: boolean;
+    readonly todayMs: number | undefined;
+    /** Sorted ascending. */
+    readonly bucketTimes: readonly number[];
+    readonly fullWindow: ChartWindow;
+}): ChartWindow;
+/** Bucket closest to a horizontal position given as a 0..1 fraction of the window. */
+export declare function bucketIndexAtFraction(times: readonly number[], window: ChartWindow, fraction: number): number;
+export declare function nearestIndex(times: readonly number[], atMs: number): number;
+/** Snaps a brush drag to bucket times, keeping start < end by at least one
+ *  bucket; `anchor` is the edge the user holds and therefore stays put. */
+export declare function snapBrushWindow(times: readonly number[], startMs: number, endMs: number, anchor?: "start" | "end"): ChartWindow;
+/** Moves a snapped window by `shiftMs`: only the start snaps, the width in
+ *  bucket indices stays constant so uneven bucket gaps cannot resize it. */
+export declare function snapMovedBrushWindow(times: readonly number[], originStartMs: number, originEndMs: number, shiftMs: number): ChartWindow;
+/** Calendar-aligned tick times (month/day starts in `timeZone`, default UTC)
+ *  strictly inside the window: the smallest
+ *  step whose inner ticks fit `maxLabels - 2`, keep one label slot
+ *  (`span / maxLabels`) between inner neighbours and `EDGE_GAP_SLOTS` to the
+ *  start/end labels. If no step fits, the coarsest one is thinned greedily. */
+export declare function stackedAreaAxisTicks(window: ChartWindow, maxLabels: number, format: StackedAreaDateFormat, timeZone?: string): readonly number[];

package/dist/web/widgets/chart-window.js

@@ -0,0 +1,190 @@
+// Pure window math for StackedAreaChart: range presets anchored at today and
+// brush selections snapped to bucket times.
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+const MONTH_FORMAT_MIN_SPAN_MONTHS = 18;
+export function stackedAreaDateFormatFor(window) {
+    return window.endMs >= addUtcMonths(window.startMs, MONTH_FORMAT_MIN_SPAN_MONTHS)
+        ? "month"
+        : "day";
+}
+export function addUtcMonths(atMs, months) {
+    return Temporal.Instant.fromEpochMilliseconds(atMs).toZonedDateTimeISO("UTC").add({ months })
+        .epochMilliseconds;
+}
+// Same window as a "1/3/5 years" switch over a plan: `months` ahead of today,
+// pulled back when the data ends earlier, never before the first bucket.
+// An anchor so far before the data that the window ends ahead of the first
+// bucket falls back to the full window instead of an inverted one.
+export function rangeWindow(months, anchorMs, firstMs, lastMs) {
+    const endMs = Math.min(lastMs, addUtcMonths(anchorMs, months));
+    if (endMs < firstMs)
+        return { startMs: firstMs, endMs: lastMs };
+    return { startMs: Math.max(firstMs, addUtcMonths(endMs, -months)), endMs };
+}
+export function pointsWithin(points, window) {
+    return points.filter((p) => p.atMs >= window.startMs && p.atMs <= window.endMs);
+}
+export function initialWindowSelection(ranges, initialWindow = "default-range") {
+    if (initialWindow === "from-today")
+        return { kind: "from-today" };
+    return ranges === undefined ? undefined : { kind: "range", value: ranges.default };
+}
+function clampMs(value, minMs, maxMs) {
+    return Math.max(minMs, Math.min(maxMs, value));
+}
+function windowFromToday(todayMs, firstMs, lastMs, fullWindow) {
+    if (todayMs === undefined || todayMs >= lastMs)
+        return fullWindow;
+    return { startMs: clampMs(todayMs, firstMs, lastMs), endMs: lastMs };
+}
+export function resolveStackedAreaWindow({ selection, ranges, brush, todayMs, bucketTimes, fullWindow, }) {
+    const firstMs = bucketTimes[0];
+    const lastMs = bucketTimes[bucketTimes.length - 1];
+    if (firstMs === undefined || lastMs === undefined)
+        return fullWindow;
+    if (selection?.kind === "brush") {
+        const startMs = clampMs(Math.min(selection.startMs, selection.endMs), firstMs, lastMs);
+        const endMs = clampMs(Math.max(selection.startMs, selection.endMs), firstMs, lastMs);
+        return { startMs, endMs };
+    }
+    if (selection?.kind === "range") {
+        const months = ranges?.options.find((option) => option.value === selection.value)?.months;
+        if (months === undefined)
+            return fullWindow;
+        return rangeWindow(months, todayMs ?? lastMs, firstMs, lastMs);
+    }
+    if (selection?.kind === "from-today" || (brush && ranges === undefined)) {
+        return windowFromToday(todayMs, firstMs, lastMs, fullWindow);
+    }
+    return fullWindow;
+}
+/** Bucket closest to a horizontal position given as a 0..1 fraction of the window. */
+export function bucketIndexAtFraction(times, window, fraction) {
+    const clamped = Math.max(0, Math.min(1, fraction));
+    return nearestIndex(times, window.startMs + clamped * (window.endMs - window.startMs));
+}
+export function nearestIndex(times, atMs) {
+    let best = 0;
+    for (let i = 1; i < times.length; i++) {
+        const current = times[i];
+        const bestTime = times[best];
+        if (current === undefined || bestTime === undefined)
+            continue;
+        if (Math.abs(current - atMs) < Math.abs(bestTime - atMs))
+            best = i;
+    }
+    return best;
+}
+/** Snaps a brush drag to bucket times, keeping start < end by at least one
+ *  bucket; `anchor` is the edge the user holds and therefore stays put. */
+export function snapBrushWindow(times, startMs, endMs, anchor = "start") {
+    const lastIndex = times.length - 1;
+    if (lastIndex < 1)
+        return { startMs, endMs };
+    let startIndex = nearestIndex(times, Math.min(startMs, endMs));
+    let endIndex = nearestIndex(times, Math.max(startMs, endMs));
+    if (endIndex <= startIndex) {
+        if (anchor === "start") {
+            endIndex = Math.min(lastIndex, startIndex + 1);
+            startIndex = endIndex - 1;
+        }
+        else {
+            startIndex = Math.max(0, endIndex - 1);
+            endIndex = startIndex + 1;
+        }
+    }
+    return { startMs: times[startIndex] ?? startMs, endMs: times[endIndex] ?? endMs };
+}
+/** Moves a snapped window by `shiftMs`: only the start snaps, the width in
+ *  bucket indices stays constant so uneven bucket gaps cannot resize it. */
+export function snapMovedBrushWindow(times, originStartMs, originEndMs, shiftMs) {
+    const lastIndex = times.length - 1;
+    if (lastIndex < 1)
+        return { startMs: originStartMs + shiftMs, endMs: originEndMs + shiftMs };
+    const widthInBuckets = nearestIndex(times, originEndMs) - nearestIndex(times, originStartMs);
+    const startIndex = Math.min(nearestIndex(times, originStartMs + shiftMs), Math.max(0, lastIndex - widthInBuckets));
+    const endIndex = Math.min(lastIndex, startIndex + widthInBuckets);
+    return {
+        startMs: times[startIndex] ?? originStartMs + shiftMs,
+        endMs: times[endIndex] ?? originEndMs + shiftMs,
+    };
+}
+const MONTH_TICK_STEPS = [1, 2, 3, 6, 12, 24, 36, 60, 120];
+const DAY_TICK_STEPS = [1, 2, 7, 14];
+const DAY_MS = 86_400_000;
+function monthTicks(window, step, timeZone) {
+    const startOfMonth = Temporal.Instant.fromEpochMilliseconds(window.startMs)
+        .toZonedDateTimeISO(timeZone)
+        .startOfDay()
+        .with({ day: 1 });
+    const ticks = [];
+    for (let cursor = startOfMonth;; cursor = cursor.add({ months: 1 })) {
+        const atMs = cursor.epochMilliseconds;
+        if (atMs >= window.endMs)
+            break;
+        if (atMs > window.startMs && (cursor.year * 12 + cursor.month - 1) % step === 0) {
+            ticks.push(atMs);
+        }
+    }
+    return ticks;
+}
+// Local day starts: DST days are not 24h, so the cursor advances by calendar
+// day. The step phase uses the local day number, not epoch-ms modulo.
+function dayTicks(window, step, timeZone) {
+    const ticks = [];
+    const localDayNumberOf = (day) => Math.round((day.epochMilliseconds + day.offsetNanoseconds / 1e6) / DAY_MS);
+    let cursor = Temporal.Instant.fromEpochMilliseconds(window.startMs)
+        .toZonedDateTimeISO(timeZone)
+        .startOfDay();
+    while (localDayNumberOf(cursor) % step !== 0)
+        cursor = cursor.add({ days: 1 }).startOfDay();
+    for (; cursor.epochMilliseconds < window.endMs; cursor = cursor.add({ days: step }).startOfDay()) {
+        if (cursor.epochMilliseconds > window.startMs)
+            ticks.push(cursor.epochMilliseconds);
+    }
+    return ticks;
+}
+function hasRoomBetweenLabels(window, ticks, slotMs) {
+    const positions = [window.startMs, ...ticks, window.endMs];
+    return positions.every((atMs, i) => i === 0 || atMs - (positions[i - 1] ?? atMs) >= slotMs);
+}
+function thinToSlots(window, ticks, slotMs) {
+    const kept = [];
+    let previous = window.startMs;
+    for (const atMs of ticks) {
+        if (atMs - previous >= slotMs && window.endMs - atMs >= slotMs) {
+            kept.push(atMs);
+            previous = atMs;
+        }
+    }
+    return kept;
+}
+// Start/end labels are edge-aligned (a full label width inward) while inner
+// ticks are centred, so the edge gap needs 1.5 slots for the same clearance.
+const EDGE_GAP_SLOTS = 1.5;
+/** Calendar-aligned tick times (month/day starts in `timeZone`, default UTC)
+ *  strictly inside the window: the smallest
+ *  step whose inner ticks fit `maxLabels - 2`, keep one label slot
+ *  (`span / maxLabels`) between inner neighbours and `EDGE_GAP_SLOTS` to the
+ *  start/end labels. If no step fits, the coarsest one is thinned greedily. */
+export function stackedAreaAxisTicks(window, maxLabels, format, timeZone = "UTC") {
+    const span = window.endMs - window.startMs;
+    if (span <= 0)
+        return [];
+    const slotMs = span / maxLabels;
+    const edgeGapMs = slotMs * EDGE_GAP_SLOTS;
+    const innerBudget = Math.max(0, maxLabels - 2);
+    const candidates = [
+        ...(format === "day"
+            ? DAY_TICK_STEPS.map((step) => () => dayTicks(window, step, timeZone))
+            : []),
+        ...MONTH_TICK_STEPS.map((step) => () => monthTicks(window, step, timeZone)),
+    ];
+    let ticks = [];
+    for (const candidate of candidates) {
+        ticks = candidate().filter((atMs) => atMs - window.startMs >= edgeGapMs && window.endMs - atMs >= edgeGapMs);
+        if (ticks.length <= innerBudget && hasRoomBetweenLabels(window, ticks, slotMs))
+            return ticks;
+    }
+    return thinToSlots(window, ticks, slotMs).slice(0, innerBudget);
+}