@godxjp/ui 30.7.0 → 30.8.0

package/README.md

@@ -160,9 +160,22 @@ The framework ships colors, the type scale, the wa-iro palette, and (opt-in) bun
 @source "../views";
 ```
 
-### Slim build — ship only the CSS you use
-
-`@godxjp/ui/styles` is the zero-config all-in-one (every component's CSS + bundled fonts). Managing fonts yourself (next/font, a system stack, an extension that must not ship font files)? Load the same layers without the faces:
+### Where the CSS weight actually is — the font faces, not the components
+
+`@godxjp/ui/styles` is the zero-config all-in-one: every component's layers **plus 729 `@font-face`
+declarations** for the bundled CJK faces. Those declarations are render-blocking CSS on every page,
+separate from the font FILES (which load lazily, per glyph range). Measured on a fresh Vite 8 +
+Tailwind v4 app using 15 components (gh#971):
+
+| entry                    | CSS emitted | gzip       |
+| ------------------------ | ----------- | ---------- |
+| `@godxjp/ui/styles`      | 1,303,803 B | **367 KB** |
+| `@godxjp/ui/styles/core` | 581,210 B   | **86 KB**  |
+
+So if CSS weight matters, **the one change that moves it is the import line** — 77% of it is the face
+declarations. `core` is not a per-component slice: it still carries every component's layers (about
+64 KB gzip for all ~165), it only drops the faces. Load fonts another way (next/font, a system stack,
+your own `@font-face`) and take the same layers without them:
 
 ```css
 @import "@godxjp/ui/styles/core"; /* every component layer, no @font-face */

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 30.7.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 30.8.0.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.

package/agent/components/Affix.json

@@ -21,7 +21,7 @@
       "type": "number"
     },
     {
-      "description": "antd `target`, default `() => window` — the scroll box to pin against, which need not be the nearest scrolling ancestor. Same lazy-getter shape `FloatButton.BackTop.target` uses here, and for the same reason: the element does not exist on the render that declares it.",
+      "description": "antd `target` — the scroll box to pin against, which need not be the nearest scrolling ancestor. Omitted, it IS the nearest block-axis scroller (`position: sticky`'s rule), else the viewport (gh#984); `() => window` is the viewport. Same lazy-getter shape `FloatButton.BackTop.target` uses here, and for the same reason: the element does not exist on the render that declares it.",
       "name": "target",
       "type": "() => Window | HTMLElement | null"
     },

package/agent/components/Anchor.json

@@ -46,12 +46,12 @@
       "type": "number"
     },
     {
-      "description": "gh#890. The scroll box the sections are measured in AND `Affix` pins the nav against — one function, both halves. `Affix`'s own name and shape (`AffixTargetProp`), the same lazy getter `FloatButton.BackTop.target` already spells here. `null`, or an absent `target`, means the viewport. Wins over `getContainer` when both are given.",
+      "description": "gh#890. The scroll box the sections are measured in AND `Affix` pins the nav against — one function, both halves. `Affix`'s own name and shape (`AffixTargetProp`), the same lazy getter `FloatButton.BackTop.target` already spells here. `null` means the viewport; absent (with no `getContainer`), the nearest block-axis scroller, else the viewport — `Affix`'s default (gh#984). Wins over `getContainer` when both are given.",
       "name": "target",
       "type": "() => Window | HTMLElement | null"
     },
     {
-      "description": "antd `getContainer`, default `() => window` — the scroll box holding the sections. Superseded by `target` (gh#890), which mirrors `Affix`'s own spelling for the identical idea; kept live for a call site written before `target` existed.",
+      "description": "antd `getContainer` — the scroll box holding the sections; omitted → the nearest block-axis scroller, else the viewport (gh#984). Superseded by `target` (gh#890), which mirrors `Affix`'s own spelling for the identical idea; kept live for a call site written before `target` existed.",
       "name": "getContainer",
       "type": "() => HTMLElement | Window"
     },

package/agent/components/RecordPicker.json

@@ -33,7 +33,7 @@
       "type": "(SearchSelectOptionProp | SelectOptionGroupProp)[]"
     },
     {
-      "description": "Server fetcher, debounced, and it runs on BOTH branches — a picker whose `count` is small still fetches from the server rather than showing an empty dropdown (gh#942). `filters` carries YOUR OWN vocabulary back (the `name` of each declared filter), so the server reads the keys it already understands instead of a shape this component invented; the dropdown branch draws no filters, so it passes an empty object. Return `nextCursor` to page: the dialog shows a Load more button and APPENDS, so nothing the user already scrolled past is lost.",
+      "description": "Server fetcher, debounced, and it runs on BOTH branches — a picker whose `count` is small still fetches from the server rather than showing an empty dropdown (gh#942). `filters` carries YOUR OWN vocabulary back (the `name` of each declared filter), so the server reads the keys it already understands instead of a shape this component invented; the dropdown branch draws no filters, so it passes an empty object. Return `nextCursor` to page: the dialog shows a Load more button and APPENDS, so nothing the user already scrolled past is lost. `cursor` is EXACTLY the `nextCursor` your previous response returned for the same `query` (undefined on the first page) — the same in all three shapes, dropdown included; an offset or an opaque token both work. Before gh#964 the dropdown sent the page NUMBER instead, so an offset server read \"2\" as offset 2 and returned duplicate rows; if you worked around that, remove the workaround.",
       "name": "loadOptions",
       "type": "(params: { query: string; filters: Record<string, string>; cursor?: string }) => Promise<{ options: SearchSelectOptionProp[]; count?: number; nextCursor?: string }>"
     },

package/agent/components.json

@@ -6019,7 +6019,7 @@
         "type": "(SearchSelectOptionProp | SelectOptionGroupProp)[]"
       },
       {
-        "description": "Server fetcher, debounced, and it runs on BOTH branches — a picker whose `count` is small still fetches from the server rather than showing an empty dropdown (gh#942). `filters` carries YOUR OWN vocabulary back (the `name` of each declared filter), so the server reads the keys it already understands instead of a shape this component invented; the dropdown branch draws no filters, so it passes an empty object. Return `nextCursor` to page: the dialog shows a Load more button and APPENDS, so nothing the user already scrolled past is lost.",
+        "description": "Server fetcher, debounced, and it runs on BOTH branches — a picker whose `count` is small still fetches from the server rather than showing an empty dropdown (gh#942). `filters` carries YOUR OWN vocabulary back (the `name` of each declared filter), so the server reads the keys it already understands instead of a shape this component invented; the dropdown branch draws no filters, so it passes an empty object. Return `nextCursor` to page: the dialog shows a Load more button and APPENDS, so nothing the user already scrolled past is lost. `cursor` is EXACTLY the `nextCursor` your previous response returned for the same `query` (undefined on the first page) — the same in all three shapes, dropdown included; an offset or an opaque token both work. Before gh#964 the dropdown sent the page NUMBER instead, so an offset server read \"2\" as offset 2 and returned duplicate rows; if you worked around that, remove the workaround.",
         "name": "loadOptions",
         "type": "(params: { query: string; filters: Record<string, string>; cursor?: string }) => Promise<{ options: SearchSelectOptionProp[]; count?: number; nextCursor?: string }>"
       },
@@ -15858,7 +15858,7 @@
         "type": "number"
       },
       {
-        "description": "antd `target`, default `() => window` — the scroll box to pin against, which need not be the nearest scrolling ancestor. Same lazy-getter shape `FloatButton.BackTop.target` uses here, and for the same reason: the element does not exist on the render that declares it.",
+        "description": "antd `target` — the scroll box to pin against, which need not be the nearest scrolling ancestor. Omitted, it IS the nearest block-axis scroller (`position: sticky`'s rule), else the viewport (gh#984); `() => window` is the viewport. Same lazy-getter shape `FloatButton.BackTop.target` uses here, and for the same reason: the element does not exist on the render that declares it.",
         "name": "target",
         "type": "() => Window | HTMLElement | null"
       },
@@ -15961,12 +15961,12 @@
         "type": "number"
       },
       {
-        "description": "gh#890. The scroll box the sections are measured in AND `Affix` pins the nav against — one function, both halves. `Affix`'s own name and shape (`AffixTargetProp`), the same lazy getter `FloatButton.BackTop.target` already spells here. `null`, or an absent `target`, means the viewport. Wins over `getContainer` when both are given.",
+        "description": "gh#890. The scroll box the sections are measured in AND `Affix` pins the nav against — one function, both halves. `Affix`'s own name and shape (`AffixTargetProp`), the same lazy getter `FloatButton.BackTop.target` already spells here. `null` means the viewport; absent (with no `getContainer`), the nearest block-axis scroller, else the viewport — `Affix`'s default (gh#984). Wins over `getContainer` when both are given.",
         "name": "target",
         "type": "() => Window | HTMLElement | null"
       },
       {
-        "description": "antd `getContainer`, default `() => window` — the scroll box holding the sections. Superseded by `target` (gh#890), which mirrors `Affix`'s own spelling for the identical idea; kept live for a call site written before `target` existed.",
+        "description": "antd `getContainer` — the scroll box holding the sections; omitted → the nearest block-axis scroller, else the viewport (gh#984). Superseded by `target` (gh#890), which mirrors `Affix`'s own spelling for the identical idea; kept live for a call site written before `target` existed.",
         "name": "getContainer",
         "type": "() => HTMLElement | Window"
       },

package/agent/index.json

@@ -48,7 +48,7 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v30.7.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v30.8.0/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
@@ -62,5 +62,5 @@
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "30.7.0"
+  "version": "30.8.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
 > A Japanese-enterprise React design system: 175 components, 2074 design tokens,
-> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 30.7.0.
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 30.8.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@30.7.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@30.8.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -26,7 +26,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v30.7.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v30.8.0/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/rules.json

@@ -195,7 +195,7 @@
     "title": "Long text columns get an explicit width"
   },
   {
-    "body": "Author and verify every page at 320–390px FIRST. Page sections are spaced by `PageContainer` itself (`--page-body-gap` between its direct children). Inside a section spacing comes only from `Flex` `gap` (vertical rhythm = `Flex direction=\"col\"`, control rows = the default `direction=\"row\"`) + `ResponsiveGrid columns={2|3|4}` (which collapse to a single column on narrow screens) — never raw `p-*` / `gap-*` / `space-*` utilities for page layout (the static audit rejects them). Styles are loaded whole: `@godxjp/ui/styles` or `styles/core`, never a hand-picked set of layers.",
+    "body": "Author and verify every page at 320–390px FIRST. Page sections are spaced by `PageContainer` itself (`--page-body-gap` between its direct children). Inside a section spacing comes only from `Flex` `gap` (vertical rhythm = `Flex direction=\"col\"`, control rows = the default `direction=\"row\"`) + `ResponsiveGrid columns={2|3|4}` (which collapse to a single column on narrow screens) — never raw `p-*` / `gap-*` / `space-*` utilities for page layout (the static audit rejects them). Styles are loaded whole: `@godxjp/ui/styles` or `styles/core`, never a hand-picked set of layers. They differ ONLY in the 729 bundled CJK `@font-face` declarations, and that difference is most of the CSS: 367 KB vs 86 KB gzip for a 15-component app (gh#971) — pick `styles/core` whenever the app loads fonts another way.",
     "number": 40,
     "title": "Pages are mobile-first"
   },

package/dist/app/app-provider.js

@@ -27,7 +27,7 @@ import {
   PREFERS_DARK_SCHEME_QUERY
 } from "./theme-axes.js";
 import { resolveDefaultTimeFormat } from "./time-format-labels.js";
-import { resolveDefaultTimezone } from "./timezones.js";
+import { resolveDefaultTimezone, resolveHydrationSafeTimezone } from "./timezones.js";
 import {
   APP_REQUEST_HEADER_DATE_FORMAT,
   APP_REQUEST_HEADER_LOCALE,
@@ -53,10 +53,6 @@ function buildRequestHeaders(locale, timezone, timeFormat, dateFormat) {
     [APP_REQUEST_HEADER_DATE_FORMAT]: dateFormat
   };
 }
-function resolveHydrationSafeTimezone(defaultTimezone, systemTimezone) {
-  if (defaultTimezone === "browser") return systemTimezone ?? "UTC";
-  return resolveDefaultTimezone(defaultTimezone, systemTimezone);
-}
 function AppProvider({
   children,
   defaultLocale = "vi",

package/dist/app/timezones.d.ts

@@ -24,5 +24,20 @@ export declare function getTimezoneOffsetLabel(timezone: string, locale?: AppLoc
 export declare function formatTimezoneDisplayLabel(timezone: string, locale?: AppLocale): string;
 export declare function getTimezoneLabel(timezone: string, locale: AppLocale, fallbackLocale?: AppLocale): string;
 export declare function resolveDefaultTimezone(defaultTimezone: "browser" | "system" | (string & {}), systemTimezone?: string): string;
+/**
+ * The timezone to use BEFORE the browser's is known — the first render, and anything that formats
+ * before AppProvider has synced (gh#968).
+ *
+ * `"browser"` answers UTC here, not the browser's zone: a server cannot know the browser's zone, so
+ * resolving it on the first render would render one time on the server and another on the client.
+ * AppProvider settles to the real browser zone in an effect afterwards.
+ *
+ * It lives here, not inside AppProvider, so the module-level datetime fallback (`lib/datetime/sync`)
+ * can call the SAME function. Before gh#968 that fallback hard-coded `Asia/Ho_Chi_Minh` while this
+ * answered UTC — two different answers to "nothing is configured yet". The Vietnamese one was the
+ * worse of the two because it looks right: a JST attendance timestamp read 2 hours off, and nothing
+ * about `01/05/2026 14:30` says so. UTC is at least visibly not the user's local time.
+ */
+export declare function resolveHydrationSafeTimezone(defaultTimezone: "browser" | "system" | (string & {}), systemTimezone?: string): string;
 /** Vitest only — reset cached IANA list between cases. */
 export declare function resetIanaTimezoneCacheForTests(): void;

package/dist/app/timezones.js

@@ -141,6 +141,10 @@ function resolveDefaultTimezone(defaultTimezone, systemTimezone) {
   if (defaultTimezone === "system") return systemTimezone ?? "UTC";
   return defaultTimezone;
 }
+function resolveHydrationSafeTimezone(defaultTimezone, systemTimezone) {
+  if (defaultTimezone === "browser") return systemTimezone ?? "UTC";
+  return resolveDefaultTimezone(defaultTimezone, systemTimezone);
+}
 function resetIanaTimezoneCacheForTests() {
   cachedAllTimezones = null;
   cachedTimezoneSet = null;
@@ -157,6 +161,7 @@ export {
   isValidIanaTimezone,
   resetIanaTimezoneCacheForTests,
   resolveDefaultTimezone,
+  resolveHydrationSafeTimezone,
   resolveTimezoneForIntl,
   resolveTimezonePickerOptions
 };

package/dist/components/data-display/marquee-reveal.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Bring a focused item of a Marquee track back into view by SEEKING the lap, not by scrolling
+ * (gh#983).
+ *
+ * The track travels by `transform` towards the inline start, so an item that has left the viewport
+ * on that side sits in NEGATIVE overflow — which is not scrollable overflow. The browser's own
+ * "scroll the focused element into view" therefore does nothing for it, and Tab through the track
+ * landed on links that were partly or wholly invisible: measured 8 of 18 tab stops at 375px, one
+ * at -149..-65 against a 75..1321 viewport at 1440px (WCAG 2.2 SC 2.4.11).
+ *
+ * The lap is seamless by construction, so any offset within it is a legitimate position: moving the
+ * animation's `currentTime` moves the whole strip to where the item is visible, and resuming later
+ * continues from there exactly as a pause would (G4).
+ */
+/** Inline-axis interval, in viewport pixels. */
+export type MarqueeSpan = {
+    start: number;
+    end: number;
+};
+/**
+ * The animation time at which the item sits fully inside the box, or `null` when it already does
+ * (so tabbing across visible items never jolts the strip).
+ *
+ * It aims to CENTRE the item — clear of the `fade` mask at both edges — and settles for any fully
+ * visible position when the centre is out of reach.
+ *
+ * It NEVER wraps into another lap. The copies look identical, but only the first holds the real,
+ * focusable item; the clones are `inert`. Seeking by a whole lap therefore moves the focused item a
+ * whole copy away while the strip looks unchanged — measured, the first attempt at this fix put
+ * every item at exactly `centre − lap` (-139 against a 698 centre, lap 837) at 1440px. So the
+ * answer stays inside the iteration the animation is in.
+ *
+ * `step` is how far the item moved when time advanced by a hundredth of a lap — measured rather
+ * than derived, so `direction="end"` (a reversed animation) and the RTL keyframes need no case of their
+ * own. A probe that crossed an iteration boundary shows a jump of nearly a whole copy the OTHER
+ * way; `lap` (one copy, in px) is what tells the two apart. Only its SIGN is used. It is a hundredth
+ * of a lap and not a millisecond because a slow track (99.6s a lap on the logo wall at 320px) moves
+ * 0.008px in a millisecond, which measured as 0 — and a zero step meant no seek at all.
+ */
+export declare function marqueeRevealTime({ item, box, time, duration, lap, step, }: {
+    item: MarqueeSpan;
+    box: MarqueeSpan;
+    time: number;
+    duration: number;
+    lap: number;
+    step: number;
+}): number | null;
+/** Wire it to the live DOM. A no-op where there is no running animation (reduced motion, jsdom). */
+export declare function revealInMarquee(viewport: HTMLElement, track: HTMLElement, item: Element): void;

package/dist/components/data-display/marquee-reveal.js

@@ -0,0 +1,55 @@
+function marqueeRevealTime({
+  item,
+  box,
+  time,
+  duration,
+  lap,
+  step
+}) {
+  if (item.start >= box.start - 1 && item.end <= box.end + 1) return null;
+  if (!(duration > 0) || !(lap > 0) || step === 0) return null;
+  const sign = Math.abs(step) < lap / 2 ? Math.sign(step) : -Math.sign(step);
+  const pxPerMs = sign * lap / duration;
+  const local = (time % duration + duration) % duration;
+  const iteration = time - local;
+  const low = box.start - item.start;
+  const high = box.end - item.end;
+  const centre = (box.start + box.end) / 2 - (item.start + item.end) / 2;
+  const at = (d) => local + d / pxPerMs;
+  const [a, b] = [at(low), at(high)].sort((x, y) => x - y);
+  const from = Math.max(0, low <= high ? a : at(centre));
+  const to = Math.min(duration, low <= high ? b : at(centre));
+  const clamp = (t, lo, hi) => Math.min(hi, Math.max(lo, t));
+  const chosen = from <= to ? clamp(at(centre), from, to) : clamp(at(centre), 0, duration);
+  return iteration + chosen;
+}
+function revealInMarquee(viewport, track, item) {
+  const animation = track.getAnimations?.()[0];
+  const copy = track.firstElementChild;
+  if (!animation || !copy) return;
+  viewport.scrollLeft = 0;
+  const span = () => {
+    const r = item.getBoundingClientRect();
+    return { start: r.left, end: r.right };
+  };
+  const box = viewport.getBoundingClientRect();
+  const time = Number(animation.currentTime ?? 0);
+  const duration = Number(animation.effect?.getComputedTiming().duration ?? 0);
+  const before = span();
+  animation.currentTime = time + duration / 100;
+  const step = span().start - before.start;
+  animation.currentTime = time;
+  const next = marqueeRevealTime({
+    item: before,
+    box: { start: box.left, end: box.right },
+    time,
+    duration,
+    lap: copy.offsetWidth,
+    step
+  });
+  if (next !== null) animation.currentTime = next;
+}
+export {
+  marqueeRevealTime,
+  revealInMarquee
+};

package/dist/components/data-display/marquee.js

@@ -6,6 +6,7 @@ import { useTranslation } from "../../i18n/use-translation.js";
 import { useMediaQuery } from "../../lib/hooks.js";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../general/button.js";
+import { revealInMarquee } from "./marquee-reveal.js";
 import { ScrollArea } from "./scroll-area.js";
 function gapToken(step) {
   if (step === "none" || step === 0) return "0px";
@@ -33,6 +34,7 @@ const Marquee = React.forwardRef(function Marquee2({
   const trackId = React.useId();
   const viewportRef = React.useRef(null);
   const copyRef = React.useRef(null);
+  const trackRef = React.useRef(null);
   const [uncontrolledPlay, setUncontrolledPlay] = React.useState(defaultPlay);
   const playing = play ?? uncontrolledPlay;
   const [measurement, setMeasurement] = React.useState({ copies: 2, cycleScale: 1 });
@@ -111,25 +113,41 @@ const Marquee = React.forwardRef(function Marquee2({
       style: animatedStyle,
       ...props,
       children: [
-        /* @__PURE__ */ jsx("div", { ref: viewportRef, "data-slot": "marquee-viewport", className: "ui-marquee-viewport", children: /* @__PURE__ */ jsxs("div", { id: trackId, "data-slot": "marquee-track", className: "ui-marquee-track", children: [
-          /* @__PURE__ */ jsx("div", { ref: copyRef, "data-slot": "marquee-copy", className: "ui-marquee-copy", children }),
-          Array.from({ length: measurement.copies - 1 }, (_, index) => (
-            // Decorative by construction: `aria-hidden` keeps the duplicate out of the
-            // accessibility tree and `inert` keeps it out of the tab order. The prior art has
-            // neither, which is why its content is announced once per screenful of width.
-            /* @__PURE__ */ jsx(
-              "div",
-              {
-                "data-slot": "marquee-clone",
-                className: "ui-marquee-copy",
-                "aria-hidden": "true",
-                inert: true,
-                children
-              },
-              index
-            )
-          ))
-        ] }) }),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            ref: viewportRef,
+            "data-slot": "marquee-viewport",
+            className: "ui-marquee-viewport",
+            onFocus: (event) => {
+              const item = event.target;
+              requestAnimationFrame(() => {
+                if (viewportRef.current && trackRef.current) {
+                  revealInMarquee(viewportRef.current, trackRef.current, item);
+                }
+              });
+            },
+            children: /* @__PURE__ */ jsxs("div", { ref: trackRef, id: trackId, "data-slot": "marquee-track", className: "ui-marquee-track", children: [
+              /* @__PURE__ */ jsx("div", { ref: copyRef, "data-slot": "marquee-copy", className: "ui-marquee-copy", children }),
+              Array.from({ length: measurement.copies - 1 }, (_, index) => (
+                // Decorative by construction: `aria-hidden` keeps the duplicate out of the
+                // accessibility tree and `inert` keeps it out of the tab order. The prior art has
+                // neither, which is why its content is announced once per screenful of width.
+                /* @__PURE__ */ jsx(
+                  "div",
+                  {
+                    "data-slot": "marquee-clone",
+                    className: "ui-marquee-copy",
+                    "aria-hidden": "true",
+                    inert: true,
+                    children
+                  },
+                  index
+                )
+              ))
+            ] })
+          }
+        ),
         /* @__PURE__ */ jsx(
           Button,
           {

package/dist/components/data-entry/record-picker.d.ts

@@ -33,6 +33,32 @@ export type { RecordPickerProp, RecordPickerProp as RecordPickerProps };
  * hands over the labels it already has, and it is merged ahead of whatever loads later, so a chip
  * never renders as a raw id and never disappears when the query changes.
  */
+/**
+ * Adapt RecordPicker's cursor contract to Select's page-numbered loader (gh#964).
+ *
+ * `loadOptions` is typed to receive the `nextCursor` the server returned last time — an offset, an
+ * opaque token, whatever the server minted. The inline and dialog shapes pass it straight back.
+ * This adapter used to pass `String(page)` instead, so page 2 reached the server as "2" and a
+ * consumer implementing the type as written read it as offset 2: duplicated and missing rows, with
+ * no error. The server's `nextCursor` was used only as a has-more flag.
+ *
+ * Select asks for pages by number, so the adapter remembers, per query, which cursor fetches which
+ * page: page 1 has none, and page N+1 is whatever page N's response said. A new query starts its
+ * own chain, so one query's cursor can never be sent with another's text — a user typing,
+ * deleting and retyping can make Select ask for page 2 of an earlier query after a later one began.
+ *
+ * The chains live in this closure, so they are discarded whenever `loadOptions` itself changes
+ * (the caller memoises on it): a cursor minted by one data source is meaningless to the next.
+ *
+ * @internal Exported for tests only; the package barrel re-exports RecordPicker by name, not this.
+ */
+export declare function selectLoadOptionsFor(loadOptions: RecordPickerProp["loadOptions"]): (({ query, page }: {
+    query: string;
+    page: number;
+}) => Promise<{
+    options: SearchSelectOptionProp[];
+    hasMore: boolean;
+}>) | undefined;
 export declare const RecordPicker: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "defaultValue" | "onChange" | "value"> & {
     mode?: "single" | "multiple";
     shape?: "auto" | "inline";

package/dist/components/data-entry/record-picker.js

@@ -21,6 +21,19 @@ import {
 import { Command, CommandGroup } from "./command.js";
 import { Input } from "./input.js";
 import { Select } from "./select.js";
+function selectLoadOptionsFor(loadOptions) {
+  if (!loadOptions) return void 0;
+  const chains = /* @__PURE__ */ new Map();
+  return async ({ query, page }) => {
+    if (page === 1) chains.set(query, /* @__PURE__ */ new Map());
+    const chain = chains.get(query);
+    const cursor = page === 1 ? void 0 : chain?.get(page);
+    if (page > 1 && cursor === void 0) return { options: [], hasMore: false };
+    const r = await loadOptions({ query, filters: {}, cursor });
+    if (r.nextCursor !== void 0) chains.get(query)?.set(page + 1, r.nextCursor);
+    return { options: r.options, hasMore: r.nextCursor !== void 0 };
+  };
+}
 const RecordPicker = React.forwardRef(
   function RecordPicker2({
     mode = "single",
@@ -57,17 +70,7 @@ const RecordPicker = React.forwardRef(
       },
       [controlled, isMultiple, onValueChange]
     );
-    const selectLoadOptions = React.useMemo(
-      () => loadOptions ? async ({ query, page }) => {
-        const r = await loadOptions({
-          query,
-          filters: {},
-          cursor: page > 1 ? String(page) : void 0
-        });
-        return { options: r.options, hasMore: r.nextCursor !== void 0 };
-      } : void 0,
-      [loadOptions]
-    );
+    const selectLoadOptions = React.useMemo(() => selectLoadOptionsFor(loadOptions), [loadOptions]);
     const staticOptions = React.useMemo(
       () => options ? normalizeSelectOptions(options) : [],
       [options]
@@ -542,5 +545,6 @@ const DialogPicker = React.forwardRef(function DialogPicker2({
   ] });
 });
 export {
-  RecordPicker
+  RecordPicker,
+  selectLoadOptionsFor
 };

package/dist/components/layout/affix.js

@@ -2,17 +2,23 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { isDevelopment } from "../../lib/dev.js";
-import { useInView } from "../../lib/hooks.js";
+import { scrollBoxOf, useInView } from "../../lib/hooks.js";
 import { cn } from "../../lib/utils.js";
 const OVERSHOOT_MARGIN = "1000000px";
 const ROOT_MARGIN_BLOCK_START = `0px 0px ${OVERSHOOT_MARGIN} 0px`;
 const ROOT_MARGIN_BLOCK_END = `${OVERSHOOT_MARGIN} 0px 0px 0px`;
-function resolveTarget(target) {
-  if (!target) return null;
+function resolveTarget(target, from) {
+  if (!target) return scrollBoxOf(from);
   const node = target();
   if (!node || typeof window === "undefined" || node === window) return null;
   return node;
 }
+function isRendered(node) {
+  for (let p = node; p; p = p.parentElement) {
+    if (window.getComputedStyle(p).display === "none") return false;
+  }
+  return true;
+}
 function fixedContainingBlock(node) {
   if (typeof window === "undefined") return null;
   for (let n = node?.parentElement ?? null; n && n !== document.documentElement; n = n.parentElement) {
@@ -53,20 +59,22 @@ const Affix = React.forwardRef(function Affix2({
   const pinToEnd = offsetBlockStart === void 0 && offsetBlockEnd !== void 0;
   const [targetElement, setTargetElement] = React.useState(null);
   React.useEffect(() => {
-    setTargetElement(resolveTarget(target));
+    setTargetElement(resolveTarget(target, rootRef.current));
   }, [target]);
   const inView = useInView(sentinelRef, {
     root: targetElement,
     rootMargin: pinToEnd ? ROOT_MARGIN_BLOCK_END : ROOT_MARGIN_BLOCK_START,
     assumeInView: true
   });
-  const affixed = !inView;
+  const [rendered, setRendered] = React.useState(true);
+  const affixed = !inView && rendered;
   const [box, setBox] = React.useState(null);
   const [targetInset, setTargetInset] = React.useState(0);
   const measure = React.useCallback(() => {
     const root = rootRef.current;
     const content = contentRef.current;
     if (!root || !content) return;
+    setRendered(isRendered(root));
     const rootRect = root.getBoundingClientRect();
     const contentRect = content.getBoundingClientRect();
     setBox(
@@ -177,7 +185,7 @@ const Affix = React.forwardRef(function Affix2({
             "data-slot": "affix-placeholder",
             "aria-hidden": "true",
             className: "ui-affix-placeholder",
-            style: { blockSize: box.block }
+            style: { blockSize: box.block, inlineSize: box.inline }
           }
         ) : null,
         /* @__PURE__ */ jsx(

package/dist/components/navigation/anchor.js

@@ -3,7 +3,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { isDevelopment } from "../../lib/dev.js";
-import { useControlledLatch } from "../../lib/hooks.js";
+import { scrollBoxOf, useControlledLatch } from "../../lib/hooks.js";
 import { cn, prefersReducedMotion } from "../../lib/utils.js";
 import { Affix } from "../layout/affix.js";
 const SHARP_MATCHER = /#([^\t\r\n\f\v]+)$/;
@@ -120,7 +120,7 @@ function Anchor({
   }, []);
   const container = React.useCallback(() => {
     if (target) return target() ?? window;
-    return getContainer?.() ?? window;
+    return getContainer?.() ?? scrollBoxOf(navRef.current) ?? window;
   }, [target, getContainer]);
   const line = targetOffsetBlockStart ?? offsetBlockStart ?? 0;
   const resolveFromScroll = React.useCallback(() => {

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "30.7.0",
+  "version": "30.8.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/lib/datetime/sync.d.ts

@@ -8,7 +8,7 @@ export type DatetimeContext = {
     dateFormat: AppDateFormat;
 };
 /** Sync module-level datetime prefs from AppProvider (mirrors syncI18nLocale). */
-export declare function syncDatetimeContext(partial: Pick<DatetimeContext, "locale" | "timezone" | "timeFormat" | "dateFormat"> & {
+export declare function syncDatetimeContext(prefs: Pick<DatetimeContext, "locale" | "timezone" | "timeFormat" | "dateFormat"> & {
     dateFnsLocale?: Locale;
 }): void;
 export declare function getDatetimeContext(): Readonly<DatetimeContext>;

package/dist/lib/datetime/sync.js

@@ -1,22 +1,23 @@
 import { getDateFnsLocale } from "../../app/locales.js";
 import { resolveDefaultDateFormat } from "../../app/date-format-labels.js";
+import { resolveHydrationSafeTimezone } from "../../app/timezones.js";
 const DEFAULT_LOCALE = "vi";
 const defaultContext = () => ({
   locale: DEFAULT_LOCALE,
   dateFnsLocale: getDateFnsLocale(DEFAULT_LOCALE),
-  timezone: "Asia/Ho_Chi_Minh",
+  timezone: resolveHydrationSafeTimezone("browser"),
   timeFormat: "24h",
   dateFormat: resolveDefaultDateFormat(DEFAULT_LOCALE)
 });
 let syncedContext = defaultContext();
 let liveRelativeFormattingEnabled = true;
-function syncDatetimeContext(partial) {
+function syncDatetimeContext(prefs) {
   syncedContext = {
-    locale: partial.locale,
-    timezone: partial.timezone,
-    timeFormat: partial.timeFormat,
-    dateFormat: partial.dateFormat,
-    dateFnsLocale: partial.dateFnsLocale ?? getDateFnsLocale(partial.locale)
+    locale: prefs.locale,
+    timezone: prefs.timezone,
+    timeFormat: prefs.timeFormat,
+    dateFormat: prefs.dateFormat,
+    dateFnsLocale: prefs.dateFnsLocale ?? getDateFnsLocale(prefs.locale)
   };
 }
 function getDatetimeContext() {

package/dist/lib/hooks.d.ts

@@ -70,6 +70,13 @@ export declare function useScrollsHorizontally(ref: RefObject<HTMLElement | null
  * them would otherwise write this walk again.
  */
 export declare function scrollParent(el: HTMLElement | null): HTMLElement | null;
+/**
+ * `scrollParent` for a caller that hands the answer to `IntersectionObserver` or a scroll listener:
+ * the root and body elements are the VIEWPORT by another name (a reset writing
+ * `html { overflow-y: scroll }` makes the root "scroll"), and the answer for them is `null`.
+ * Affix and Anchor use it as their default scroll box (gh#984).
+ */
+export declare function scrollBoxOf(el: HTMLElement | null): HTMLElement | null;
 /**
  * Has this element entered the viewport (or `root`) yet?
  *

package/dist/lib/hooks.js

@@ -151,6 +151,11 @@ function scrollParent(el) {
   }
   return null;
 }
+function scrollBoxOf(el) {
+  if (typeof document === "undefined") return null;
+  const box = scrollParent(el);
+  return box === document.documentElement || box === document.body ? null : box;
+}
 function useInView(ref, {
   enabled = true,
   once = false,
@@ -192,6 +197,7 @@ function useInView(ref, {
   return !enabled || inView;
 }
 export {
+  scrollBoxOf,
   scrollParent,
   useControlledLatch,
   useDebouncedValue,

package/dist/props/components/data-entry.prop.d.ts

@@ -1170,7 +1170,15 @@ export type RecordPickerProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement
     onValueChange?: (value: string | string[] | null) => void;
     /** Static rows, client-filtered. Provide this OR `loadOptions`. */
     options?: (SearchSelectOptionProp | SelectOptionGroupProp)[];
-    /** Server fetcher. `filters` carries the consumer's own filter vocabulary. */
+    /**
+     * Server fetcher. `filters` carries the consumer's own filter vocabulary.
+     *
+     * `cursor` is EXACTLY the `nextCursor` your previous response returned for the same `query` —
+     * an offset, an opaque token, whatever your server minted — and `undefined` for the first page.
+     * The same in every shape: under `threshold` (dropdown), `inline`, and the dialog. Return no
+     * `nextCursor` when the list is finished; that is what ends paging. (Before gh#964 the dropdown
+     * sent the page NUMBER here instead, so an offset-based server read "2" as offset 2.)
+     */
     loadOptions?: (params: {
         query: string;
         filters: Record<string, string>;

package/dist/props/components/layout.prop.d.ts

@@ -1876,7 +1876,8 @@ export type MasonryProp<TData = unknown> = {
  *
  * It is a FUNCTION and not an element because the element does not exist on the render that
  * declares it: the caller writes `target={() => scrollRef.current}` and the component calls it
- * after mount. `window` (the default) means the document viewport.
+ * after mount. `() => window` means the document viewport. Omitted, it is the nearest ancestor
+ * that scrolls on the block axis (`position: sticky`'s rule), and the viewport only when none does.
  * @see Affix
  */
 export type AffixTargetProp = () => Window | HTMLElement | null;
@@ -1931,7 +1932,7 @@ export type AffixProp = {
      * @deprecated Ant Design spells this `offsetBottom`; in `@godxjp/ui` it is `offsetBlockEnd`.
      */
     offsetBottom?: never;
-    /** The scroll box to pin against. Ant Design `target`, default `() => window`. */
+    /** The scroll box to pin against. Ant Design `target`; omitted → the nearest block-axis scroller, else the viewport. */
     target?: AffixTargetProp;
     /**
      * Fires when the pinned state FLIPS, and only then — never on a scroll frame that did not

package/dist/props/components/navigation.prop.d.ts

@@ -867,12 +867,14 @@ export type AnchorProp = {
      * The scroll box the sections are measured in AND the box `Affix` pins the nav against — one
      * function, both halves (gh#890). `AffixTargetProp`, the same lazy-getter shape and the same
      * name `Affix.target` / `FloatButton.BackTop.target` already spell here, so a consumer who has
-     * scoped one scrolling component already knows this one. `null` (or an absent `target`) means
-     * the viewport, matching `Affix`. Wins over `getContainer` when both are given.
+     * scoped one scrolling component already knows this one. `null` means the viewport. Absent (with
+     * no `getContainer`), it is the nearest ancestor that scrolls on the block axis, else the
+     * viewport — `Affix`'s own default (gh#984). Wins over `getContainer` when both are given.
      */
     target?: AffixTargetProp;
     /**
-     * The scroll box holding the sections. Ant Design `getContainer`, default `() => window`.
+     * The scroll box holding the sections. Ant Design `getContainer`; omitted → the nearest
+     * block-axis scroller, else the viewport (gh#984).
      *
      * Superseded by `target`, which mirrors `Affix`'s own spelling for the identical idea; kept,
      * still live, for a call site written before `target` existed.

package/dist/styles/navigation-layout.css

@@ -52,6 +52,16 @@
     border-width: var(--stroke-hairline);
   }
 
+  [data-slot="tabs-list"][data-variant="line"] {
+    position: relative;
+    z-index: 1;
+  }
+
+  [data-slot="tabs"]:has([data-slot="tabs-list"][data-variant="line"])
+    > :is([data-slot="tabs-panel"], [data-slot="tabs-content"]) {
+    isolation: isolate;
+  }
+
   [data-slot="tabs-list"][data-variant="line"] [data-slot="tabs-trigger"]::after {
     content: "";
     position: absolute;

package/dist/styles/table-layout.css

@@ -60,7 +60,8 @@
   }
 
   .ui-table-row[data-tone] {
-    background-image: linear-gradient(
+
+    --table-row-tone-layer: linear-gradient(
       var(
         --table-row-tone-surface,
         hsl(var(--table-row-tone-color) / var(--table-row-tone-wash-alpha))
@@ -70,6 +71,7 @@
         hsl(var(--table-row-tone-color) / var(--table-row-tone-wash-alpha))
       )
     );
+    background-image: var(--table-row-tone-layer);
   }
 
   :where([data-slot="table"] > tbody > tr:nth-child(even of :not([data-expanded-row]))) {
@@ -440,48 +442,60 @@
     box-shadow: 6px 0 6px -5px hsl(var(--foreground) / 0.12);
   }
 
+  :where(.ui-table-row[data-tone]) > :is(.ui-data-table-pin-end, .ui-data-table-pin-start) {
+    background-image: var(--table-row-tone-layer);
+  }
+
   :where([data-slot="table"] > tbody > tr:nth-child(even of :not([data-expanded-row])))
     > :is(.ui-data-table-pin-end, .ui-data-table-pin-start) {
-    background-image: linear-gradient(
-      color-mix(
-        in srgb,
-        var(--table-row-striped-background, hsl(var(--muted) / 0.8)) var(--table-row-striped-alpha),
-        transparent
-      ),
-      color-mix(
-        in srgb,
-        var(--table-row-striped-background, hsl(var(--muted) / 0.8)) var(--table-row-striped-alpha),
-        transparent
-      )
-    );
+    background-image:
+      var(--table-row-tone-layer, none),
+      linear-gradient(
+        color-mix(
+          in srgb,
+          var(--table-row-striped-background, hsl(var(--muted) / 0.8))
+            var(--table-row-striped-alpha),
+          transparent
+        ),
+        color-mix(
+          in srgb,
+          var(--table-row-striped-background, hsl(var(--muted) / 0.8))
+            var(--table-row-striped-alpha),
+          transparent
+        )
+      );
   }
 
   .ui-data-table-surface tbody tr:hover > .ui-data-table-pin-end,
   .ui-data-table-surface tbody tr:hover > .ui-data-table-pin-start {
-    background-image: linear-gradient(
-      var(
-        --table-row-hover-background,
-        hsl(var(--accent) / var(--table-row-hover-background-alpha, 0.7))
-      ),
-      var(
-        --table-row-hover-background,
-        hsl(var(--accent) / var(--table-row-hover-background-alpha, 0.7))
-      )
-    );
+    background-image:
+      var(--table-row-tone-layer, none),
+      linear-gradient(
+        var(
+          --table-row-hover-background,
+          hsl(var(--accent) / var(--table-row-hover-background-alpha, 0.7))
+        ),
+        var(
+          --table-row-hover-background,
+          hsl(var(--accent) / var(--table-row-hover-background-alpha, 0.7))
+        )
+      );
   }
 
   .ui-data-table-surface tbody tr[data-state="selected"] > .ui-data-table-pin-end,
   .ui-data-table-surface tbody tr[data-state="selected"] > .ui-data-table-pin-start {
-    background-image: linear-gradient(
-      var(
-        --table-row-selected-background,
-        hsl(var(--muted) / var(--table-row-selected-background-alpha, 0.3))
-      ),
-      var(
-        --table-row-selected-background,
-        hsl(var(--muted) / var(--table-row-selected-background-alpha, 0.3))
-      )
-    );
+    background-image:
+      var(--table-row-tone-layer, none),
+      linear-gradient(
+        var(
+          --table-row-selected-background,
+          hsl(var(--muted) / var(--table-row-selected-background-alpha, 0.3))
+        ),
+        var(
+          --table-row-selected-background,
+          hsl(var(--muted) / var(--table-row-selected-background-alpha, 0.3))
+        )
+      );
   }
 
   .ui-data-table-ellipsis {

package/docs/TOKEN-RESOLUTION.md

@@ -109,6 +109,14 @@ selector, its value, and whether it is a freeze; then every read and whether tha
 call-site fallback. If two components move together, run it on the token they share and the shared
 declaration is on the screen.
 
+**Before you rely on a token, read its `published:` line.** `yes` is the contract; `NO` is an
+internal variable that can change or vanish in any release — `--text-xs` looks like the obvious
+name for the small size, but it is Tailwind's inlined `0.75rem` (12px), while the published
+`--font-size-xs` resolves to 12.4699px. A consumer who patched with the first shipped a 0.47px shift
+no gate caught (gh#988). For an `initial` knob the tool also prints `read it as: var(--x, …)` — the
+fallback the package itself uses at its read sites. Copy that line; a bare `var(--x)` on an
+`initial` knob is unset.
+
 **It does not compute a winner, and says so.** The first version ranked selectors into four
 "cascade" buckets by regex and printed them strongest-last. Codex found that `@theme inline` and
 `[dir="rtl"] .ui-actions[data-fade-in-inline]` both scored top precedence on the substring

package/docs/data-entry/form.tsx

@@ -356,39 +356,43 @@ export default function Demo() {
           <CardContent>
             <Form layout="horizontal" labelWidth="9rem">
               <FormField id="cmp-tel" label="電話番号" helper="市外局番から">
-                <Flex direction="row" gap="sm" align="center">
-                  <Flex width="5rem" shrink={false}>
-                    <Input
-                      id="cmp-tel-area"
-                      aria-label="市外局番"
-                      inputMode="numeric"
-                      maxLength={4}
-                      defaultValue="03"
-                    />
-                  </Flex>
-                  <Text aria-hidden tone="muted">
-                    -
-                  </Text>
-                  <Flex width="5rem" shrink={false}>
-                    <Input
-                      id="cmp-tel-city"
-                      aria-label="市内局番"
-                      inputMode="numeric"
-                      maxLength={4}
-                      defaultValue="6273"
-                    />
-                  </Flex>
-                  <Text aria-hidden tone="muted">
-                    -
-                  </Text>
-                  <Flex width="5rem" shrink={false}>
-                    <Input
-                      id="cmp-tel-line"
-                      aria-label="加入者番号"
-                      inputMode="numeric"
-                      maxLength={4}
-                      defaultValue="0001"
-                    />
+                {/* The three parts never split across lines — "03 -" alone on a row reads as a
+                    whole number. The extension is a separate value, so it is what wraps on a phone. */}
+                <Flex direction="row" gap="sm" align="center" wrap>
+                  <Flex direction="row" gap="sm" align="center" shrink={false}>
+                    <Flex width="4rem" shrink={false}>
+                      <Input
+                        id="cmp-tel-area"
+                        aria-label="市外局番"
+                        inputMode="numeric"
+                        maxLength={4}
+                        defaultValue="03"
+                      />
+                    </Flex>
+                    <Text aria-hidden tone="muted">
+                      -
+                    </Text>
+                    <Flex width="4rem" shrink={false}>
+                      <Input
+                        id="cmp-tel-city"
+                        aria-label="市内局番"
+                        inputMode="numeric"
+                        maxLength={4}
+                        defaultValue="6273"
+                      />
+                    </Flex>
+                    <Text aria-hidden tone="muted">
+                      -
+                    </Text>
+                    <Flex width="4rem" shrink={false}>
+                      <Input
+                        id="cmp-tel-line"
+                        aria-label="加入者番号"
+                        inputMode="numeric"
+                        maxLength={4}
+                        defaultValue="0001"
+                      />
+                    </Flex>
                   </Flex>
                   <Flex width="6rem" shrink={false}>
                     <NumberInput
@@ -499,19 +503,19 @@ export default function Demo() {
               </FormField>
               <FormField id="cmp-ok-tel" label="電話番号" validateStatus="success" hasFeedback>
                 <Flex direction="row" gap="sm" align="center">
-                  <Flex width="5rem" shrink={false}>
+                  <Flex width="4rem" shrink={false}>
                     <Input id="cmp-ok-tel-area" aria-label="市外局番" defaultValue="03" />
                   </Flex>
                   <Text aria-hidden tone="muted">
                     -
                   </Text>
-                  <Flex width="5rem" shrink={false}>
+                  <Flex width="4rem" shrink={false}>
                     <Input id="cmp-ok-tel-city" aria-label="市内局番" defaultValue="6273" />
                   </Flex>
                   <Text aria-hidden tone="muted">
                     -
                   </Text>
-                  <Flex width="5rem" shrink={false}>
+                  <Flex width="4rem" shrink={false}>
                     <Input id="cmp-ok-tel-line" aria-label="加入者番号" defaultValue="0001" />
                   </Flex>
                 </Flex>
@@ -1111,7 +1115,7 @@ export default function Demo() {
           </CardHeader>
           <CardContent>
             <Flex direction="col" gap="lg">
-              <Form layout="horizontal" labelWidth="14rem" labelAlign="end" collapseBelow={false}>
+              <Form layout="horizontal" labelWidth="14rem" labelAlign="end">
                 <FormField id="len-e-name" label="氏名" required>
                   <Input id="len-e-name" defaultValue="山田 太郎" />
                 </FormField>
@@ -1127,7 +1131,7 @@ export default function Demo() {
                   <Input id="len-e-note" defaultValue="ゴドー商事" />
                 </FormField>
               </Form>
-              <Form layout="horizontal" labelWidth="14rem" labelAlign="start" collapseBelow={false}>
+              <Form layout="horizontal" labelWidth="14rem" labelAlign="start">
                 <FormField id="len-s-name" label="氏名" required>
                   <Input id="len-s-name" defaultValue="山田 太郎" />
                 </FormField>

package/docs/layout/nav-list.tsx

@@ -395,8 +395,8 @@ export default function Demo() {
           </CardDescription>
         </CardHeader>
         <CardContent>
-          <Flex direction={{ base: "col", md: "row" }} gap="xl" align="start">
-            <Flex direction="col" gap="sm" grow>
+          <Flex direction={{ base: "col", md: "row" }} gap="xl">
+            <Flex direction="col" gap="sm" fill>
               <Text size="sm" weight="medium">
                 レール幅（compact · 18.75rem）
               </Text>

package/docs/navigation/anchor.tsx

@@ -182,8 +182,10 @@ export default function Demo() {
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Flex gap="lg" align="start">
-              <ScrollArea className="h-96 w-64 shrink-0" label="Contents">
+            {/* Side by side from md; on a phone the rail stacks above the text it indexes. A 256px
+                rail beside a 244px card left the chapters a column one glyph wide (gh#965). */}
+            <Flex direction={{ base: "col", md: "row" }} gap="lg" align="start">
+              <ScrollArea className="h-48 w-full shrink-0 md:h-96 md:w-64" label="Contents">
                 <Anchor
                   affix={false}
                   showInkInFixed
@@ -192,7 +194,11 @@ export default function Demo() {
                   getContainer={() => chaptersRef.current ?? window}
                 />
               </ScrollArea>
-              <ScrollArea viewportRef={chaptersRef} className="h-96 flex-1" label="Agreement">
+              <ScrollArea
+                viewportRef={chaptersRef}
+                className="h-96 w-full md:w-auto md:flex-1"
+                label="Agreement"
+              >
                 <Flex direction="col" gap="md">
                   {CHAPTERS.map((chapter) => (
                     <Chapter
@@ -251,24 +257,28 @@ export default function Demo() {
           </CardHeader>
           <CardContent>
             <Flex gap="lg" align="start">
-              <Anchor
-                offsetBlockStart={16}
-                targetOffsetBlockStart={24}
-                label="On this page"
-                items={[
-                  { key: "page-a", href: "#page-alpha", title: "Alpha · 第一章" },
-                  {
-                    key: "page-b",
-                    href: "#page-beta",
-                    title: "Beta · 第二章",
-                    children: [
-                      { key: "page-b1", href: "#page-beta-one", title: "Beta, part one" },
-                      { key: "page-b2", href: "#page-beta-two", title: "Beta, part two" },
-                    ],
-                  },
-                  { key: "page-c", href: "#page-gamma", title: "Gamma · 第三章" },
-                ]}
-              />
+              {/* A pinned side rail has no room on a phone: at 320px it was squeezed to 58px and
+                  broke "Gamma" mid-word. Documentation sites drop the in-page rail below md. */}
+              <Flex hideBelow="md">
+                <Anchor
+                  offsetBlockStart={16}
+                  targetOffsetBlockStart={24}
+                  label="On this page"
+                  items={[
+                    { key: "page-a", href: "#page-alpha", title: "Alpha · 第一章" },
+                    {
+                      key: "page-b",
+                      href: "#page-beta",
+                      title: "Beta · 第二章",
+                      children: [
+                        { key: "page-b1", href: "#page-beta-one", title: "Beta, part one" },
+                        { key: "page-b2", href: "#page-beta-two", title: "Beta, part two" },
+                      ],
+                    },
+                    { key: "page-c", href: "#page-gamma", title: "Gamma · 第三章" },
+                  ]}
+                />
+              </Flex>
               <Flex direction="col" gap="md" className="flex-1">
                 <Chapter id="page-alpha" title="Alpha · 第一章" lines={6} />
                 <Chapter id="page-beta" title="Beta · 第二章" lines={2} />

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "30.7.0",
-  "godxUiMcp": "30.7.0",
+  "version": "30.8.0",
+  "godxUiMcp": "30.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/explain-token.mjs

@@ -39,9 +39,15 @@
  *   node scripts/explain-token.mjs --json <name>           machine-readable, for a gate
  */
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const ROOT = process.cwd();
+/* The PACKAGE root, from this file's own location — never `process.cwd()` (gh#980). The documented
+ * call is `node node_modules/@godxjp/ui/scripts/explain-token.mjs` from the consumer's directory, and
+ * with cwd as the root every read below looked in the consumer's tree: no catalog, no CSS, and a
+ * confident "no token matches" for every token that exists. In this checkout the two roots coincide,
+ * which is why the defect was invisible here. */
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
 /** Source of truth for what a CONSUMER can set: the published catalog, not the stylesheets. */
 function publishedTokens() {
@@ -139,11 +145,37 @@ function parse(file) {
         .slice(m.index, m.index + 400)
         .replace(/\s+/g, " ")
         .includes(`${m[1]},`),
+      fallback: fallbackAt(blank, m.index),
     });
   }
   return { decls, reads };
 }
 
+/**
+ * The fallback text of the `var(` that opens at `at`, or null. Balanced on parentheses, because the
+ * fallbacks this package writes are formulas — `calc(var(--font-size-base) / var(--font-size-ratio))`
+ * — and stopping at the first `)` would print half of one.
+ */
+function fallbackAt(blank, at) {
+  let depth = 0;
+  let comma = -1;
+  for (let i = at; i < blank.length; i += 1) {
+    const ch = blank[i];
+    if (ch === "(") depth += 1;
+    else if (ch === ")") {
+      depth -= 1;
+      if (depth === 0)
+        return comma < 0
+          ? null
+          : blank
+              .slice(comma + 1, i)
+              .trim()
+              .replace(/\s+/g, " ");
+    } else if (ch === "," && depth === 1 && comma < 0) comma = i;
+  }
+  return null;
+}
+
 /** The selector chain enclosing a byte offset, outermost first. */
 function contextAt(blank, at) {
   const chain = [];
@@ -282,6 +314,27 @@ function trace(name, { decls, reads }, published, scopedNames) {
     );
   }
   if (myReads.length > 12) console.log(`    … and ${myReads.length - 12} more`);
+
+  /* THE PATCH SHAPE, printed rather than left to be inferred (gh#988). An `initial` knob read bare
+   * is unset, so a consumer migrating a rule has to copy the package's own fallback — and without
+   * this line they went looking for a shorter token instead, picked `--text-xs` (unpublished,
+   * Tailwind-inlined to 12px) over `--font-size-xs` (12.4699px), and shipped a 0.47px shift no
+   * gate caught. The most common fallback wins; the count says how settled it is. */
+  if (mine.some((d) => d.value === "initial")) {
+    const counts = new Map();
+    for (const r of myReads)
+      if (r.fallback) counts.set(r.fallback, (counts.get(r.fallback) ?? 0) + 1);
+    const [best, n] = [...counts].sort((a, b) => b[1] - a[1])[0] ?? [];
+    if (best) {
+      console.log(`  read it as: var(${name}, ${best})`);
+      console.log(
+        `             ${n} of ${myReads.length} read(s) use this fallback — the knob is \`initial\`, so a bare read is unset.`,
+      );
+    }
+  }
+  if (!tier && myReads.length === 0) {
+    console.log("  → not part of the contract: read a published token instead.");
+  }
   return { name, tier, decls: mine, reads: myReads };
 }