@godxjp/ui 23.2.1 → 23.3.0

package/dist/app/timezones.js

@@ -1,4 +1,5 @@
 import { translate } from "../i18n/translate.js";
+import { dateTimeFormat } from "../lib/intl-cache.js";
 const APP_TIMEZONE_PRESET = [
   "UTC",
   "Asia/Ho_Chi_Minh",
@@ -113,7 +114,7 @@ function getTimezoneCityName(timezone) {
 function getTimezoneOffsetLabel(timezone, locale = "en") {
   if (timezone === "UTC") return "UTC";
   try {
-    const parts = new Intl.DateTimeFormat(locale, {
+    const parts = dateTimeFormat(locale, {
       timeZone: resolveTimezoneForIntl(timezone),
       timeZoneName: "shortOffset"
     }).formatToParts(/* @__PURE__ */ new Date());

package/dist/components/charts/chart-cartesian.js

@@ -22,6 +22,7 @@ import { useTranslation } from "../../i18n/use-translation.js";
 import { ChartFrame, chartColor, chartHeight, useChartNumberFormat } from "./chart-frame.js";
 import { buildCartesianSummary } from "./chart-summary.js";
 import { useCategoryAxisMetrics } from "./chart-category-axis.js";
+import { listFormat } from "../../lib/intl-cache.js";
 function CartesianChart({
   kind,
   data,
@@ -45,10 +46,7 @@ function CartesianChart({
   assertRechartsPeer();
   const { t, locale } = useTranslation();
   const fmt = useChartNumberFormat(numberFormat);
-  const list = React.useMemo(
-    () => new Intl.ListFormat(locale, { style: "narrow", type: "unit" }),
-    [locale]
-  );
+  const list = React.useMemo(() => listFormat(locale, { style: "narrow", type: "unit" }), [locale]);
   const hasData = data.length > 0 && series.length > 0;
   const summary = buildCartesianSummary(
     data,

package/dist/components/charts/chart-frame.js

@@ -3,6 +3,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
 import { useTranslation } from "../../i18n/use-translation.js";
+import { numberFormat } from "../../lib/intl-cache.js";
 const CHART_COLORS = [
   "var(--chart-1)",
   "var(--chart-2)",
@@ -25,7 +26,7 @@ function chartHeight(size = "md", height) {
 }
 function useChartNumberFormat(options) {
   const { locale } = useTranslation();
-  return React.useMemo(() => new Intl.NumberFormat(locale, options), [locale, options]);
+  return React.useMemo(() => numberFormat(locale, options), [locale, options]);
 }
 function ChartFrame({
   label,

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

@@ -22,6 +22,7 @@ import { CONTROL_STATUS_CHROME_CLASS, CONTROL_VARIANT_CHROME_CLASS } from "./con
 import { Input } from "./input.js";
 import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "../data-display/popover.js";
 import { Calendar } from "./calendar.js";
+import { dateTimeFormat, numberFormat } from "../../lib/intl-cache.js";
 const ISO_HINT = "yyyy-mm-dd";
 const PERIOD_PICKERS = /* @__PURE__ */ new Set(["month", "quarter", "year"]);
 const PERIOD_COLUMNS = 3;
@@ -49,6 +50,7 @@ function DatePicker(props) {
     disabledDate,
     cellRender,
     allowClear,
+    triggerLabel,
     format: formatProp,
     parseFormat,
     minDate,
@@ -296,13 +298,9 @@ function DatePicker(props) {
     (index) => index < periodCells
   );
   const pageStep = picker === "year" ? periodCells : 1;
-  const prevDisabled = !pickerDateAllowed(
-    periodPage(viewYear - pageStep)[periodCells - 1],
-    minimum,
-    void 0
-  );
-  const nextDisabled = !pickerDateAllowed(periodPage(viewYear + pageStep)[0], void 0, maximum);
-  const periodLabel = (date, index) => picker === "year" ? new Intl.DateTimeFormat(locale, { year: "numeric" }).format(date) : picker === "quarter" ? t("dataEntry.datePicker.quarter", { quarter: index + 1 }) ?? `Q${index + 1}` : new Intl.DateTimeFormat(locale, { month: "short" }).format(date);
+  const prevDisabled = () => !pickerDateAllowed(periodPage(viewYear - pageStep)[periodCells - 1], minimum, void 0);
+  const nextDisabled = () => !pickerDateAllowed(periodPage(viewYear + pageStep)[0], void 0, maximum);
+  const periodLabel = (date, index) => picker === "year" ? dateTimeFormat(locale, { year: "numeric" }).format(date) : picker === "quarter" ? t("dataEntry.datePicker.quarter", { quarter: index + 1 }) ?? `Q${index + 1}` : dateTimeFormat(locale, { month: "short" }).format(date);
   const periodPick = (date) => {
     if (!range) {
       choose(date);
@@ -318,7 +316,7 @@ function DatePicker(props) {
     choose({ from: pendingFrom, to: date });
     if (!needConfirm) setOpen(false);
   };
-  const periodPanel = /* @__PURE__ */ jsxs("div", { className: "ui-month-picker-panel", children: [
+  const renderPeriodPanel = () => /* @__PURE__ */ jsxs("div", { className: "ui-month-picker-panel", children: [
     /* @__PURE__ */ jsxs("div", { className: "ui-month-picker-nav", children: [
       /* @__PURE__ */ jsx(
         Button,
@@ -326,21 +324,21 @@ function DatePicker(props) {
           type: "button",
           variant: "outline",
           size: "icon-sm",
-          disabled: prevDisabled,
+          disabled: prevDisabled(),
           "aria-label": t("dataEntry.monthPicker.previousYear") ?? "Previous year",
           className: "ui-month-picker-nav-button",
           onClick: () => setViewYear(viewYear - pageStep),
           children: /* @__PURE__ */ jsx(ChevronLeft, { className: "ui-month-picker-icon", "aria-hidden": "true" })
         }
       ),
-      /* @__PURE__ */ jsx("span", { className: "ui-month-picker-nav-label", "aria-live": "polite", children: new Intl.NumberFormat(locale, { useGrouping: false }).format(viewYear) }),
+      /* @__PURE__ */ jsx("span", { className: "ui-month-picker-nav-label", "aria-live": "polite", children: numberFormat(locale, { useGrouping: false }).format(viewYear) }),
       /* @__PURE__ */ jsx(
         Button,
         {
           type: "button",
           variant: "outline",
           size: "icon-sm",
-          disabled: nextDisabled,
+          disabled: nextDisabled(),
           "aria-label": t("dataEntry.monthPicker.nextYear") ?? "Next year",
           className: "ui-month-picker-nav-button",
           onClick: () => setViewYear(viewYear + pageStep),
@@ -390,7 +388,7 @@ function DatePicker(props) {
     showClose,
     onClose: () => setOpen(false)
   };
-  const dayPanel = range ? /* @__PURE__ */ jsx(
+  const renderDayPanel = () => range ? /* @__PURE__ */ jsx(
     Calendar,
     {
       mode: "range",
@@ -458,7 +456,7 @@ function DatePicker(props) {
       type: "button",
       disabled: allDisabled,
       tabIndex: -1,
-      "aria-label": (isPeriod ? t("dataEntry.monthPicker.openGrid") : range ? t("dataEntry.dateRangePicker.openCalendar") : t("dataEntry.datePicker.openCalendar")) ?? "Open calendar",
+      "aria-label": triggerLabel ?? (isPeriod ? t("dataEntry.monthPicker.openGrid") : range ? t("dataEntry.dateRangePicker.openCalendar") : t("dataEntry.datePicker.openCalendar")) ?? "Open calendar",
       className: range ? "text-muted-foreground hover:text-foreground shrink-0" : "ui-control-inline-affix-action",
       children: /* @__PURE__ */ jsx(
         CalendarIcon,
@@ -502,7 +500,7 @@ function DatePicker(props) {
           },
           index
         )) }) : null,
-        isPeriod ? periodPanel : dayPanel,
+        isPeriod ? renderPeriodPanel() : renderDayPanel(),
         showTime ? /* @__PURE__ */ jsx(Flex, { pad: "sm", children: /* @__PURE__ */ jsx(
           TimePicker,
           {

package/dist/components/data-entry/number-input.js

@@ -7,6 +7,7 @@ import { cn } from "../../lib/utils.js";
 import { pickFieldA11y } from "../../lib/field-a11y.js";
 import { Button } from "../general/button.js";
 import { Input } from "./input.js";
+import { numberFormat } from "../../lib/intl-cache.js";
 function decimalsOf(n) {
   if (!Number.isFinite(n)) return 0;
   const s = String(n);
@@ -77,7 +78,7 @@ const NumberInput = React.forwardRef(
     const numericValue = isControlled ? controlledValue ?? null : internal;
     const effectivePrecision = precision ?? decimalsOf(step);
     const intlFormatter = React.useMemo(
-      () => new Intl.NumberFormat(locale, {
+      () => numberFormat(locale, {
         minimumFractionDigits: 0,
         maximumFractionDigits: Math.max(effectivePrecision, 0),
         useGrouping: false

package/dist/components/feedback/index.d.ts

@@ -6,8 +6,8 @@ export { TwoFactorSetup } from "./two-factor-setup.js";
 export type { TwoFactorSetupLabels, TwoFactorSetupProps } from "./two-factor-setup.js";
 export { Toaster } from "./sonner.js";
 export { toast } from "./use-toast.js";
-export { Skeleton, SkeletonRows, SkeletonTable, SkeletonDetail, SkeletonStat, SkeletonArticle, SkeletonAvatar, SkeletonButton, SkeletonInput, SkeletonNode, SkeletonImage, } from "./skeleton.js";
-export type { SkeletonProp, SkeletonProps, SkeletonWidth, SkeletonArticleProp, SkeletonArticleProps, SkeletonAvatarProp, SkeletonAvatarProps, SkeletonButtonProp, SkeletonButtonProps, SkeletonInputProp, SkeletonInputProps, SkeletonNodeProp, SkeletonNodeProps, SkeletonImageProp, SkeletonImageProps, } from "./skeleton.js";
+export { Skeleton, SkeletonForm, SkeletonRows, SkeletonTable, SkeletonDetail, SkeletonStat, SkeletonArticle, SkeletonAvatar, SkeletonButton, SkeletonInput, SkeletonNode, SkeletonImage, } from "./skeleton.js";
+export type { SkeletonProp, SkeletonProps, SkeletonWidth, SkeletonArticleProp, SkeletonArticleProps, SkeletonAvatarProp, SkeletonAvatarProps, SkeletonButtonProp, SkeletonButtonProps, SkeletonFormProp, SkeletonFormProps, SkeletonInputProp, SkeletonInputProps, SkeletonNodeProp, SkeletonNodeProps, SkeletonImageProp, SkeletonImageProps, } from "./skeleton.js";
 export { Banner } from "./banner.js";
 export type { BannerProp, BannerProps } from "./banner.js";
 export { Alert, AlertTitle, AlertContent, AlertDescription, AlertActions, AlertQueryError, } from "./alert.js";

package/dist/components/feedback/index.js

@@ -44,6 +44,7 @@ import { Toaster } from "./sonner.js";
 import { toast } from "./use-toast.js";
 import {
   Skeleton,
+  SkeletonForm,
   SkeletonRows,
   SkeletonTable,
   SkeletonDetail,
@@ -114,6 +115,7 @@ export {
   SkeletonAvatar,
   SkeletonButton,
   SkeletonDetail,
+  SkeletonForm,
   SkeletonImage,
   SkeletonInput,
   SkeletonNode,

package/dist/components/feedback/skeleton.d.ts

@@ -1,6 +1,6 @@
 import * as React from "react";
-import type { SkeletonArticleProp, SkeletonAvatarProp, SkeletonButtonProp, SkeletonImageProp, SkeletonInputProp, SkeletonNodeProp, SkeletonProp } from "../../props/components/feedback.prop.js";
-export type { SkeletonProp, SkeletonProp as SkeletonProps, SkeletonWidth, SkeletonArticleProp, SkeletonArticleProp as SkeletonArticleProps, SkeletonAvatarProp, SkeletonAvatarProp as SkeletonAvatarProps, SkeletonButtonProp, SkeletonButtonProp as SkeletonButtonProps, SkeletonInputProp, SkeletonInputProp as SkeletonInputProps, SkeletonNodeProp, SkeletonNodeProp as SkeletonNodeProps, SkeletonImageProp, SkeletonImageProp as SkeletonImageProps, } from "../../props/components/feedback.prop.js";
+import type { SkeletonArticleProp, SkeletonAvatarProp, SkeletonButtonProp, SkeletonFormProp, SkeletonImageProp, SkeletonInputProp, SkeletonNodeProp, SkeletonProp } from "../../props/components/feedback.prop.js";
+export type { SkeletonProp, SkeletonProp as SkeletonProps, SkeletonFormProp, SkeletonFormProp as SkeletonFormProps, SkeletonWidth, SkeletonArticleProp, SkeletonArticleProp as SkeletonArticleProps, SkeletonAvatarProp, SkeletonAvatarProp as SkeletonAvatarProps, SkeletonButtonProp, SkeletonButtonProp as SkeletonButtonProps, SkeletonInputProp, SkeletonInputProp as SkeletonInputProps, SkeletonNodeProp, SkeletonNodeProp as SkeletonNodeProps, SkeletonImageProp, SkeletonImageProp as SkeletonImageProps, } from "../../props/components/feedback.prop.js";
 declare function SkeletonBlock({ active, loading, className, children, ...props }: SkeletonProp): React.JSX.Element;
 /** Stands in for an `Avatar` — circle for a person, square for an entity mark. */
 export declare function SkeletonAvatar({ size, shape, active, className }: SkeletonAvatarProp): React.JSX.Element;
@@ -39,6 +39,15 @@ interface SkeletonRowsProps {
 }
 /** Skeleton for a flat list of rows (use inside a Card or section). */
 export declare function SkeletonRows({ rows, columns, className }: SkeletonRowsProps): React.JSX.Element;
+/**
+ * Skeleton of a `Form columns={N}` — label + control PAIRS on the form's own grid (gh#552).
+ *
+ * It renders through `ResponsiveGrid` with the SAME `columns` value the form takes, so the two
+ * share one breakpoint ladder rather than two that agree today. `SkeletonRows` could get the column
+ * count right and never the inside of a cell: a form field is a short label stacked on a full-width
+ * control, and a flat line list is neither.
+ */
+export declare function SkeletonForm({ columns, fields, active, className }: SkeletonFormProp): React.JSX.Element;
 /** Skeleton matching the DataTable layout — header row + N body rows. */
 export declare function SkeletonTable({ rows, columns }: SkeletonRowsProps): React.JSX.Element;
 /** Skeleton matching a Card detail layout — title + 6 metadata rows. */

package/dist/components/feedback/skeleton.js

@@ -1,5 +1,6 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { ImageIcon } from "lucide-react";
+import { ResponsiveGrid } from "../layout/responsive-grid.js";
 import { cn } from "../../lib/utils.js";
 import { tableCellPaddingClass, tableRowHeightClass } from "../../lib/control-styles.js";
 function measureStyle(width) {
@@ -169,6 +170,12 @@ function SkeletonRows({ rows = 6, columns = 4, className }) {
     j
   )) }, i)) });
 }
+function SkeletonForm({ columns = 1, fields = 6, active, className }) {
+  return /* @__PURE__ */ jsx("div", { className: cn("ui-skeleton-form", className), "aria-busy": "true", children: /* @__PURE__ */ jsx(ResponsiveGrid, { columns, children: Array.from({ length: fields }).map((_, i) => /* @__PURE__ */ jsxs("div", { className: "ui-skeleton-form-field", children: [
+    /* @__PURE__ */ jsx(Skeleton, { active, className: "ui-skeleton-form-label" }),
+    /* @__PURE__ */ jsx(Skeleton, { active, className: "ui-skeleton-form-control" })
+  ] }, i)) }) });
+}
 function SkeletonTable({ rows = 8, columns = 5 }) {
   return /* @__PURE__ */ jsxs("div", { className: "ui-skeleton-table", "aria-busy": "true", children: [
     /* @__PURE__ */ jsx("div", { className: cn("ui-skeleton-table-head", tableCellPaddingClass, tableRowHeightClass), children: Array.from({ length: columns }).map((_, j) => /* @__PURE__ */ jsx(Skeleton, { className: cn("ui-skeleton-caption", j === 0 ? "w-1/5" : "flex-1") }, j)) }),
@@ -205,6 +212,7 @@ export {
   SkeletonAvatar,
   SkeletonButton,
   SkeletonDetail,
+  SkeletonForm,
   SkeletonImage,
   SkeletonInput,
   SkeletonNode,

package/dist/components/general/button.js

@@ -6,6 +6,7 @@ import { cva } from "class-variance-authority";
 import { Loader2 } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { useTranslation } from "../../i18n/use-translation.js";
+import { numberFormat } from "../../lib/intl-cache.js";
 const buttonVariants = cva("ui-button", {
   variants: {
     variant: {
@@ -78,7 +79,7 @@ const Button = React.forwardRef(
       loadingText ?? children
     ] }) : children;
     const showCount = !asChild && count != null && (count !== 0 || showZero);
-    const countLabel = showCount && count != null && count > overflowCount ? `${new Intl.NumberFormat(locale).format(overflowCount)}+` : count != null ? new Intl.NumberFormat(locale).format(count) : "";
+    const countLabel = showCount && count != null && count > overflowCount ? `${numberFormat(locale).format(overflowCount)}+` : count != null ? numberFormat(locale).format(count) : "";
     const countNode = showCount ? /* @__PURE__ */ jsx("span", { "data-slot": "button-count", className: "ui-button-count", children: countLabel }) : null;
     return /* @__PURE__ */ jsx(
       Comp,

package/dist/components/layout/error-surface.js

@@ -8,6 +8,7 @@ import { EmptyState } from "../data-display/empty-state.js";
 import { Progress } from "../data-display/progress.js";
 import { Text } from "../general/typography.js";
 import { CenteredShell } from "./centered-shell.js";
+import { dateTimeFormat, numberFormat } from "../../lib/intl-cache.js";
 const STATUS_META = {
   400: { icon: TriangleAlert, tone: "warning" },
   403: { icon: ShieldAlert, tone: "warning" },
@@ -37,7 +38,7 @@ function formatMaintenanceWindow(maintenance, locale) {
   };
   const start = new Date(maintenance.start);
   if (Number.isNaN(start.getTime())) return maintenance.start;
-  const formatter = new Intl.DateTimeFormat(locale, options);
+  const formatter = dateTimeFormat(locale, options);
   if (maintenance.end === void 0) return formatter.format(start);
   const end = new Date(maintenance.end);
   if (Number.isNaN(end.getTime())) return formatter.format(start);
@@ -72,7 +73,7 @@ const ErrorSurface = React.forwardRef(
     const maintenanceProgress = maintenance?.progress;
     const hasProgress = typeof maintenanceProgress === "number" && Number.isFinite(maintenanceProgress);
     const progressLabel = hasProgress ? t("layout.errorSurface.maintenanceProgress", {
-      percent: new Intl.NumberFormat(locale, {
+      percent: numberFormat(locale, {
         style: "percent",
         maximumFractionDigits: 0
       }).format(Math.max(0, Math.min(100, maintenanceProgress)) / 100)

package/dist/components/ui/toggle.js

@@ -5,6 +5,7 @@ import { ToggleButton } from "react-aria-components";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
 import { useTranslation } from "../../i18n/use-translation.js";
+import { numberFormat } from "../../lib/intl-cache.js";
 const toggleVariants = cva("ui-toggle", {
   variants: {
     variant: {
@@ -33,7 +34,7 @@ function useCounterPill({
   const visible = count != null && (count !== 0 || showZero);
   const formatted = React.useMemo(() => {
     if (count == null) return "";
-    const format = new Intl.NumberFormat(locale);
+    const format = numberFormat(locale);
     return count > overflowCount ? `${format.format(overflowCount)}+` : format.format(count);
   }, [count, locale, overflowCount]);
   if (!visible) {

package/dist/i18n/translate.js

@@ -1,6 +1,7 @@
 import en from "./messages/en.json" with { type: "json" };
 import ja from "./messages/ja.json" with { type: "json" };
 import vi from "./messages/vi.json" with { type: "json" };
+import { numberFormat, pluralRules } from "../lib/intl-cache.js";
 const MESSAGE_CATALOG = {
   vi,
   en,
@@ -56,7 +57,7 @@ function selectPlural(value, locale, params) {
   if (count === void 0) {
     return value.other ?? Object.values(value)[0] ?? "";
   }
-  const category = new Intl.PluralRules(locale).select(count);
+  const category = pluralRules(locale).select(count);
   return value[category] ?? value.other ?? Object.values(value)[0] ?? "";
 }
 function interpolate(template, locale, params) {
@@ -64,7 +65,7 @@ function interpolate(template, locale, params) {
   return Object.entries(params).reduce(
     (text, [key, value]) => text.replaceAll(
       `{${key}}`,
-      typeof value === "number" ? new Intl.NumberFormat(locale).format(value) : String(value)
+      typeof value === "number" ? numberFormat(locale).format(value) : String(value)
     ),
     template
   );

package/dist/lib/datetime/picker-format.js

@@ -9,10 +9,11 @@ import {
   startOfYear
 } from "date-fns";
 import { parseDateInput, toIsoDate } from "./parse.js";
+import { dateTimeFormat } from "../intl-cache.js";
 function formatPickerDate(date, format, locale, withTime = false) {
   if (!date || !isValid(date)) return "";
   if (typeof format === "function") return format(date);
-  if (typeof format === "object") return new Intl.DateTimeFormat(locale, format).format(date);
+  if (typeof format === "object") return dateTimeFormat(locale, format).format(date);
   if (typeof format === "string") return formatDate(date, format);
   return withTime ? formatDate(date, "yyyy-MM-dd HH:mm") : toIsoDate(date);
 }

package/dist/lib/format.js

@@ -1,7 +1,8 @@
 import { getSyncedLocale, translateCurrent } from "../i18n/translate.js";
+import { numberFormat } from "./intl-cache.js";
 function formatBytes(n, locale = getSyncedLocale()) {
   if (n == null) return "\u2014";
-  const num = (digits, scaled) => new Intl.NumberFormat(locale, {
+  const num = (digits, scaled) => numberFormat(locale, {
     minimumFractionDigits: digits,
     maximumFractionDigits: digits
   }).format(scaled);
@@ -12,7 +13,7 @@ function formatBytes(n, locale = getSyncedLocale()) {
 }
 function formatCurrency(amountMinor, currency, locale = getSyncedLocale()) {
   if (amountMinor == null || !currency) return "\u2014";
-  const formatter = new Intl.NumberFormat(locale, { style: "currency", currency });
+  const formatter = numberFormat(locale, { style: "currency", currency });
   const minorUnitDigits = formatter.resolvedOptions().maximumFractionDigits ?? 2;
   const major = amountMinor / Math.pow(10, minorUnitDigits);
   return formatter.format(major);

package/dist/lib/intl-cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Memoised `Intl` formatters, keyed by locale + options.
+ *
+ * WHY THIS EXISTS, AS A MEASUREMENT (gh#557). A consumer ported a legacy CakePHP grid that keeps
+ * every row in the DOM — 8,262 rows, no virtualisation available — and measured 27-30s against
+ * 2.3s for the same markup built from native `<input>` / `<select>`. They had already ruled out
+ * the obvious suspect: deleting `Popover` / `PopoverContent` from `DatePicker` entirely changed
+ * nothing.
+ *
+ * Rendered here through `react-dom/server`, 2,000 rows at a time, one CLOSED `DatePicker` costs
+ * **412.6us** against **4.2us** for `<input type="date">` — 98x. Counting constructor calls during
+ * that render, each closed instance built:
+ *
+ *     12 x new Intl.DateTimeFormat
+ *      1 x new Intl.NumberFormat
+ *
+ * Constructing an `Intl` formatter is one of the most expensive things a JS engine does: it
+ * resolves locale data and compiles a pattern. Routing those same constructions through this
+ * cache, changing nothing else, took the instance from **412.6us to 178us — a 57% cut**. For the
+ * reporter's grid that is roughly 99,000 formatter constructions that no longer happen.
+ *
+ * WHY A SHARED MODULE AND NOT A `useMemo` AT EACH CALL SITE. `useMemo` memoises per INSTANCE, and
+ * the instance is exactly what there are 8,262 of. Two rows formatting dates in the same locale
+ * want the same formatter object, and nothing below module scope can give them one.
+ *
+ * SAFETY. `Intl` formatters are immutable and stateless — `format()` mutates nothing — so a single
+ * instance is safely shared across every caller and every React tree, concurrent SSR included.
+ */
+export declare function dateTimeFormat(locale: string, options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+export declare function numberFormat(locale: string, options?: Intl.NumberFormatOptions): Intl.NumberFormat;
+export declare function pluralRules(locale: string, options?: Intl.PluralRulesOptions): Intl.PluralRules;
+export declare function listFormat(locale: string, options?: Intl.ListFormatOptions): Intl.ListFormat;

package/dist/lib/intl-cache.js

@@ -0,0 +1,29 @@
+const MAX_ENTRIES = 256;
+const cache = /* @__PURE__ */ new Map();
+function memoise(kind, locale, options, make) {
+  const key = `${kind} ${locale} ${options === void 0 ? "" : JSON.stringify(options)}`;
+  const hit = cache.get(key);
+  if (hit !== void 0) return hit;
+  const made = make();
+  if (cache.size >= MAX_ENTRIES) cache.delete(cache.keys().next().value);
+  cache.set(key, made);
+  return made;
+}
+function dateTimeFormat(locale, options) {
+  return memoise("dtf", locale, options, () => new Intl.DateTimeFormat(locale, options));
+}
+function numberFormat(locale, options) {
+  return memoise("nf", locale, options, () => new Intl.NumberFormat(locale, options));
+}
+function pluralRules(locale, options) {
+  return memoise("pr", locale, options, () => new Intl.PluralRules(locale, options));
+}
+function listFormat(locale, options) {
+  return memoise("lf", locale, options, () => new Intl.ListFormat(locale, options));
+}
+export {
+  dateTimeFormat,
+  listFormat,
+  numberFormat,
+  pluralRules
+};

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

@@ -778,6 +778,17 @@ export type PickerDateFormatProp = string | Intl.DateTimeFormatOptions | ((date:
  * `value`/`defaultValue`/`onValueChange` rather than antd's `onChange`.
  */
 export type DatePickerBaseProp = FieldA11yProps & PickerChromeProp & {
+    /**
+     * The accessible NAME of the button that opens the calendar, for a screen where more than one
+     * date field exists. Default 「カレンダーを開く」 / "Open calendar" — correct for one picker on a
+     * page, and useless for three: a reader hears the same sentence three times with nothing to
+     * say which field each button belongs to (WCAG 2.2 SC 2.4.6, gh#551).
+     *
+     * Same axis, same shape, same reason as Select's `clearLabel`: name the control after the
+     * FIELD it serves — `開始日のカレンダーを開く`. The default is unchanged, so nothing moves until
+     * a caller says something.
+     */
+    triggerLabel?: string;
     /** Display format; native submission remains ISO. */
     format?: PickerDateFormatProp;
     /** Parser for a custom display function or Intl era display; ISO always remains accepted. */

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

@@ -83,6 +83,25 @@ export type SkeletonRowsProp = {
     rows?: number;
     columns?: number;
 };
+/**
+ * The skeleton of a `Form columns={N}` — label + control PAIRS on the same grid the form uses,
+ * not the flat line list `SkeletonRows` draws (gh#552).
+ *
+ * Why it is its own component rather than `SkeletonRows` with better defaults: `SkeletonRows` has
+ * no idea a form field is two stacked things, so a consumer approximating one got the column count
+ * right and the inside of every cell wrong. Worse, "close enough" is a thing that DRIFTS — change
+ * the form's `columns` and forget the skeleton and the layout jumps again on load, with nothing
+ * red to say so. Sharing `ResponsiveGrid` is what stops that: one `columns` value, one ladder.
+ */
+export type SkeletonFormProp = {
+    /** Columns of the form this stands in for — passed straight to `ResponsiveGrid`. */
+    columns?: number;
+    /** How many label+control pairs to draw. */
+    fields?: number;
+    /** Shimmer, matching the rest of the family. */
+    active?: boolean;
+    className?: string;
+};
 /**
  * A skeleton line's MEASURE. `number` is read as pixels, matching antd's
  * `SkeletonParagraphProps["width"]` (components/skeleton/Paragraph.tsx); a string is any CSS length

package/dist/props/registry.d.ts

@@ -1955,6 +1955,11 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/feedback.prop.ts";
         readonly vocabulary: readonly ["SizeProp", "ShapeProp", "ClassNameProp"];
     };
+    readonly SkeletonFormProp: {
+        readonly group: "feedback";
+        readonly file: "components/feedback.prop.ts";
+        readonly vocabulary: readonly ["ClassNameProp"];
+    };
     readonly SkeletonInputProp: {
         readonly group: "feedback";
         readonly file: "components/feedback.prop.ts";

package/dist/props/registry.js

@@ -2254,6 +2254,11 @@ const COMPONENT_PROP_REGISTRY = {
     file: "components/feedback.prop.ts",
     vocabulary: ["SizeProp", "ShapeProp", "ClassNameProp"]
   },
+  SkeletonFormProp: {
+    group: "feedback",
+    file: "components/feedback.prop.ts",
+    vocabulary: ["ClassNameProp"]
+  },
   SkeletonInputProp: {
     group: "feedback",
     file: "components/feedback.prop.ts",

package/dist/styles/alert-layout.css

@@ -216,6 +216,28 @@
     gap: var(--skeleton-cell-gap);
   }
 
+  .ui-skeleton-form-field {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--space-stack-xs);
+    min-inline-size: 0;
+  }
+
+  .ui-skeleton-form-label {
+    block-size: var(--skeleton-caption-height);
+    inline-size: var(--skeleton-label-width);
+    max-inline-size: 100%;
+    border-radius: var(--skeleton-radius);
+    background: var(--skeleton-background, hsl(var(--muted)));
+  }
+
+  .ui-skeleton-form-control {
+    block-size: var(--control-height);
+    inline-size: 100%;
+    border-radius: var(--skeleton-element-radius);
+    background: var(--skeleton-background, hsl(var(--muted)));
+  }
+
   .ui-skeleton-table {
     overflow: hidden;
     border: 1px solid hsl(var(--border));

package/dist/styles/card-layout.css

@@ -329,6 +329,10 @@
     padding: var(--card-space-body-y) var(--card-space-inset);
   }
 
+  [data-slot="card-content"][data-flush] [data-slot="tabs-panel"] {
+    padding-inline: 0;
+  }
+
   [data-slot="card-footer"] {
     display: flex;
     flex-wrap: wrap;

package/dist/styles/form-layout.css

@@ -39,7 +39,17 @@
 
   @container responsive-grid (min-width: 40rem) {
     .ui-responsive-grid > .ui-form-field {
-      grid-column: span var(--form-field-col-span, 1);
+      grid-column: span min(var(--responsive-grid-sm, 1), var(--form-field-col-span, 1));
+    }
+  }
+  @container responsive-grid (min-width: 48rem) {
+    .ui-responsive-grid > .ui-form-field {
+      grid-column: span min(var(--responsive-grid-md, 1), var(--form-field-col-span, 1));
+    }
+  }
+  @container responsive-grid (min-width: 64rem) {
+    .ui-responsive-grid > .ui-form-field {
+      grid-column: span min(var(--responsive-grid-lg, 1), var(--form-field-col-span, 1));
     }
   }
 

package/dist/tokens/axes.css

@@ -66,3 +66,8 @@
   --focus-field-shadow: 0 0 0 var(--focus-ring-glow-width)
     hsl(var(--focus-ring-glow-color) / var(--focus-ring-glow-alpha));
 }
+
+:root[data-focus-outline="off"] {
+  --focus-outline: 0;
+  --focus-field-shadow: none;
+}

package/dist/tokens/foundation.css

@@ -108,9 +108,10 @@
     transparent 70%
   );
 
-  --focus-outline: 0;
+  --focus-outline: 1;
   --focus-outline-weight: var(--stroke-hairline);
   --focus-outline-color: var(--focus-ring-color, var(--ring));
+
   --control-outline-width: calc(var(--stroke-md) * var(--focus-outline));
   --focus-outline-offset: 0px;
 
@@ -125,7 +126,8 @@
   --focus-ring-glow-color: var(--control-outline);
   --focus-ring-glow-alpha: var(--control-outline-alpha);
 
-  --focus-field-shadow: none;
+  --focus-field-shadow: 0 0 0 var(--focus-ring-glow-width)
+    hsl(var(--focus-ring-glow-color) / var(--focus-ring-glow-alpha));
 
   --focus-ring-offset: var(--focus-outline-offset);
 
@@ -255,7 +257,6 @@
   --activity-interval: var(--duration-loop);
 
   --activity-stagger-step: 160ms;
-
 }
 
 .ui-scale-fixed {
@@ -306,7 +307,6 @@
   --space-chrome-y: var(--space-4);
   --space-chrome-gap: var(--space-2);
   --field-label-gap: var(--space-2);
-
 }
 
 .dark,

package/docs/DESIGN-AUTHORITY.md

@@ -12,17 +12,17 @@ It changes no code by itself. It is the tie-breaker a reviewer points at.
 
 ## The layers, and who owns each
 
-| Layer                                                              | Authority                                     | Status in this repo                                                                                                               |
-| ------------------------------------------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                              | already followed — 33 references in `src/`                                                                                        |
-| Behaviour primitives                                               | **Radix**                                     | already the implementation — 193 references                                                                                       |
-| Component composition shape                                        | **shadcn**                                    | already the structural convention — 23 references                                                                                 |
-| Component taxonomy / grouping                                      | **Ant Design** groups                         | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed |
-| Colour foundation                                                  | **SmartHR**                                   | already the palette source — `--primary` = SmartHR MAIN `#0071bd`, `--foreground` = TEXT_BLACK, `--border` = BORDER               |
-| **Derived colour — the interaction states hanging off each seed**    | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold — see below |
-| **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                   | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves |
-| **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency) | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                       |
-| **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                | **NEW — this decision**                                                                                                           |
+| Layer                                                              | Authority                                       | Status in this repo                                                                                                                                  |
+| ------------------------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                                | already followed — 33 references in `src/`                                                                                                           |
+| Behaviour primitives                                               | **Radix**                                       | already the implementation — 193 references                                                                                                          |
+| Component composition shape                                        | **shadcn**                                      | already the structural convention — 23 references                                                                                                    |
+| Component taxonomy / grouping                                      | **Ant Design** groups                           | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed    |
+| Colour foundation                                                  | **SmartHR**                                     | already the palette source — `--primary` = SmartHR MAIN `#0071bd`, `--foreground` = TEXT_BLACK, `--border` = BORDER                                  |
+| **Derived colour — the interaction states hanging off each seed**  | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold — see below |
+| **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                     | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves                    |
+| **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency)   | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                                          |
+| **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                  | **NEW — this decision**                                                                                                                              |
 
 The first five were already true and merely unwritten. The last three are the choices being made
 here. Carbon fills the one layer that had no outside answer at all: page rhythm, table density, form layout,
@@ -197,10 +197,34 @@ rows or a totals row — which is how a consumer ends up hand-rolling a `<tfoot>
 in page CSS.
 
 **The rule: where antd names a capability, this library takes antd's name and antd's semantics.**
-The gap is read out of the INSTALLED types (`antd/es/table/interface.d.ts`,
-`antd/es/table/InternalTable.d.ts` and the `@rc-component/table` interface they extend) — never
-from memory, because antd's own names move between majors (`fixed: 'left'` is deprecated in favour
-of `start` inside rc-table itself).
+
+> **Restated and widened by the repo owner on 2026-09-12, because the rule above was being read as
+> advice rather than as the standard it is: Ant Design IS the standard. A missing capability is
+> ported from antd 100% FIRST — its names, its props, its semantics — and improved afterwards.
+> Not redesigned first, and not half-ported.**
+>
+> Two things forced the restatement, both measured rather than felt:
+>
+> - `Dialog` + `AlertDialog` ship **26** exports with **12 name-for-name pairs and 0 parts unique
+>   to `AlertDialog`**, whose entire difference is `role="alertdialog"` plus `isDismissable={false}`
+>   — two props the shell already takes. antd has exactly one `Modal`, where danger is `okType`
+>   and `Modal.confirm()`. The shape here came from Radix, silently, against this very rule
+>   (gh#567). A package-wide sweep over all 272 public exports found this is the ONLY such pair:
+>   `Skeleton.Avatar/Button/Input/Image/Node` looks identical in shape but is antd's own naming,
+>   so it is compliance, not drift.
+> - Whole families arrived half-ported: Ant Design X without `Conversations`, `Attachments`,
+>   `ThoughtChain`, `Welcome` or `Actions` (gh#559); `FloatButton` never at all (gh#558);
+>   `Typography` reduced to `Text` + `Heading`, with `Paragraph`, `Link`, `copyable`, `editable`,
+>   `mark`, `keyboard` and `italic` simply absent.
+>
+> A deviation from antd is still allowed — the three below are — but it must be WRITTEN DOWN at
+> the point of deviation. An undocumented deviation is a bug, and gh#567 is what that bug costs:
+> a consumer forced to pick between the right ARIA role and a form it needs, and an accessibility
+> decision pushed onto the party least able to make it.
+> The gap is read out of the INSTALLED types (`antd/es/table/interface.d.ts`,
+> `antd/es/table/InternalTable.d.ts` and the `@rc-component/table` interface they extend) — never
+> from memory, because antd's own names move between majors (`fixed: 'left'` is deprecated in favour
+> of `start` inside rc-table itself).
 
 > Đọc sau 20.0.0: bản major ấy đã **gỡ `antd` khỏi devDependencies** cùng máy sinh màu của nó, và
 > `check:no-antd-runtime` canh cho nó không quay lại. Câu trên mô tả cách bề mặt prop này ĐƯỢC ĐỌC
@@ -240,12 +264,12 @@ to trust them had to.
 **The authority is now the measurement, not the derivation.** Four suites read `derived.css`
 directly and hold every value in it to a threshold this repo has already committed to:
 
-| suite                                                   | what it holds                                                                                                                                                        |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| suite                                                    | what it holds                                                                                                                                                          |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `src/tokens/__tests__/focus-ring-contrast.test.ts`       | the focus mark in both switch positions — ≥3:1 (WCAG 2.2 SC 1.4.11) on every surface a control sits on, and the halo proven to be decoration rather than the indicator |
-| `src/tokens/__tests__/interactive-fill-contrast.test.ts` | an interactive fill must clear **4.5:1** against the label sitting on it                                                                                              |
-| `src/tokens/__tests__/destructive-contrast.test.ts`      | `--destructive-hover` / `--destructive-active` against the same bar                                                                                                  |
-| `src/lib/__tests__/theme-tokens-css.test.ts`             | the tier is actually loaded, and complete in both themes                                                                                                             |
+| `src/tokens/__tests__/interactive-fill-contrast.test.ts` | an interactive fill must clear **4.5:1** against the label sitting on it                                                                                               |
+| `src/tokens/__tests__/destructive-contrast.test.ts`      | `--destructive-hover` / `--destructive-active` against the same bar                                                                                                    |
+| `src/lib/__tests__/theme-tokens-css.test.ts`             | the tier is actually loaded, and complete in both themes                                                                                                               |
 
 The first three also pin each value as a literal, so an edit to `derived.css` alone turns CI red
 rather than quietly retinting the library. **That is a stronger claim than the generator made, not

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "23.2.1",
-  "godxUiMcp": "23.2.1",
+  "version": "23.3.0",
+  "godxUiMcp": "23.3.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     }
   },
   "sideEffects": false,
-  "description": "@godxjp/ui — shared React UI framework (shadcn + Radix + Tailwind v4).",
+  "description": "@godxjp/ui \u2014 shared React UI framework (shadcn + Radix + Tailwind v4).",
   "files": [
     "LICENSE",
     "dist",
@@ -397,7 +397,8 @@
     "check:number-input-step-target": "node scripts/check-number-input-step-target.mjs",
     "check:mcp-token-sync": "node scripts/gen-component-tokens.mjs --check",
     "check:email-token-sync": "node scripts/gen-email-tokens.mjs --check",
-    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs"
+    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs",
+    "typecheck:mcp": "node node_modules/typescript-7/bin/tsc --noEmit -p mcp/tsconfig.json"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.0",
@@ -412,11 +413,26 @@
     "zod": "^4.4.0"
   },
   "peerDependenciesMeta": {
-    "recharts": {
+    "@hookform/resolvers": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
       "optional": true
     },
     "playwright": {
       "optional": true
+    },
+    "react-hook-form": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "dependencies": {

package/scripts/_agent-setup.mjs

@@ -10,8 +10,17 @@
  * The guarantee is now structural: a file that exists but cannot be read, parsed, or recognised is
  * NEVER written to. We leave a `.godxjp-ui-suggested` sidecar next to it and say so.
  */
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -205,9 +214,31 @@ function readJson(path) {
  * write manufactured the precondition for the overwrite.
  */
 function writeFileAtomic(path, data) {
-  const tmp = `${path}.godxjp-ui-tmp`;
-  writeFileSync(tmp, data);
-  renameSync(tmp, path);
+  // UNIQUE temp name. A fixed `${path}.godxjp-ui-tmp` is a shared mutable file: two installs
+  // running at once — a workspace installing packages in parallel is enough — write over each
+  // other's temp and `rename` whichever finished last.
+  const tmp = `${path}.godxjp-ui-tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    writeFileSync(tmp, data);
+    // `rename` does NOT carry the target's permissions: the new file is born under the process
+    // umask. A `.mcp.json` the consumer had chmod 600 would come back 644 after the first sync,
+    // silently, because the CONTENT would be right. This happens on every write, not only under
+    // contention, which makes it the worse half of the two.
+    try {
+      chmodSync(tmp, statSync(path).mode & 0o7777);
+    } catch {
+      // No existing file (a create), or a filesystem that will not report/set the mode. Either
+      // way the default is correct and this must not abort the write.
+    }
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // Nothing to clean up.
+    }
+    throw error;
+  }
 }
 
 /**

package/scripts/guinea-pig-skill.md

@@ -131,6 +131,20 @@ những thứ ấy trên PR. **Tới được bước này KHÔNG phải là đ
 một câu hỏi, không phải một chướng ngại. Nếu bạn tin cổng ấy sai thì nói ra và
 đưa số đo, đừng lặng lẽ sửa nó.
 
+**VÀ ĐỪNG NGỒI CHỜ CI.** Đẩy nhánh, mở PR, rồi đi làm việc khác. Không có vòng lặp
+`until … gh pr checks … sleep` nào cả. CI chạy là việc của CI; nếu cần theo dõi thì
+mở một agent nền, đừng chặn người đang điều phối. Đo được ngày 12/09/2026: một lượt
+ngồi poll bốn shard đã ăn hơn một tiếng đồng hồ của chủ dự án để nhìn một thanh tiến
+trình, trong khi có việc khác đang xếp hàng.
+
+**Và full suite thì chạy theo LỊCH, không nằm trong vòng lặp sửa code của ai.** Cùng
+ngày, tôi thêm bốn shard vitest vào làn PR của kho DS và đặt chúng thành required
+check, để bịt một khoảng trống có thật (hai commit vào `main` đỏ qua một làn nhanh
+xanh). Khoảng trống là thật và phép đo trung thực — nhưng nó chỉ định giá **máy**.
+Máy chưa bao giờ là phần đắt. Từ lúc ấy mọi PR phải chờ bốn shard mới merge được.
+Đã hoàn nguyên. Một hàng rào làm người điều phối phải chờ không rẻ hơn một `main`
+đỏ; nó chỉ dời chi phí sang con đường duy nhất không song song hoá được.
+
 ### Bước 6 — Khép vòng
 
 Phát hành → nâng gói ở consumer → **gỡ vá tạm** → **gỡ mọi chú thích "chờ

package/scripts/ui-audit.mjs

@@ -891,16 +891,47 @@ function staleOwnedRules() {
   const target = join(CWD, ".ai", "rules", "godxjp-ui.md");
   if (!existsSync(target)) return null;
 
-  const stamped = /<!-- godxjp-ui:version ([^\s]+) -->/.exec(readFileSync(target, "utf8"))?.[1];
+  // FOUR states, not two. `!stamped || !installed || stamped === installed` collapsed three very
+  // different situations into one silence, and only ONE of them is genuinely fine:
+  //
+  //   no rule file, consumer never opted into the agent kit  -> silent, and it MUST stay silent.
+  //     Turning this into a finding would make a UI audit into a tool that nags every consumer to
+  //     install an agent kit they did not ask for. (Handled by the existsSync above.)
+  //   rule file present but carrying NO stamp                -> compatibility UNKNOWN, say so.
+  //   installed version unreadable                           -> compatibility UNKNOWN, say so.
+  //   stamp != installed                                     -> stale, the original finding.
+  const contents = readFileSync(target, "utf8");
+  const stamped = /<!-- godxjp-ui:version ([^\s]+) -->/.exec(contents)?.[1];
+
   let installed;
   try {
     installed = JSON.parse(
       readFileSync(join(CWD, "node_modules", "@godxjp", "ui", "package.json"), "utf8"),
     ).version;
   } catch {
-    return null;
+    installed = undefined;
   }
-  if (!stamped || !installed || stamped === installed) return null;
+
+  if (!stamped || !installed) {
+    // A file the package OWNS, whose provenance cannot be established. That is not the same as
+    // "up to date", and reporting it as such is the whole class of bug this function exists for.
+    return {
+      file: ".ai/rules/godxjp-ui.md",
+      line: 1,
+      rule: "owned-rules-unknown",
+      severity: "warn",
+      message:
+        `This file is written by @godxjp/ui, but its version cannot be established ` +
+        `(${!stamped ? "the file carries no `<!-- godxjp-ui:version … -->` stamp" : "the installed package version could not be read"}). ` +
+        `An agent may be reading guidance from a different major. Refresh it with ` +
+        `\`npx @godxjp/ui init-agent\`, or delete the file if this project does not use the agent kit.`,
+      replacement: null,
+      standard: null,
+      snippet: (stamped ?? "(no stamp)") + " vs " + (installed ?? "(package version unreadable)"),
+    };
+  }
+
+  if (stamped === installed) return null;
 
   return {
     file: ".ai/rules/godxjp-ui.md",
@@ -1112,11 +1143,37 @@ const warnings = findings.filter((f) => f.severity === "warn");
 // "✓ No UI-standardization violations found." and exited 0 having read nothing at all.
 // …except under `--changed`, where "this branch touched no .tsx" is a clean run, not a
 // misconfigured path. Failing there would make the gate unusable on every backend-only commit.
-if (filesScanned === 0 && CHANGED) {
-  if (!quiet && !asJson) console.log("✓ ui-audit --changed: no .tsx/.jsx changed on this branch.");
+// "This branch touched no UI file" is a clean run — but ONLY if there is nothing else to say.
+//
+// `staleOwnedRules()` runs before the scan loop and pushes its finding into `findings`, and this
+// branch used to exit 0 regardless: a consumer whose package-owned rules were four majors out of
+// date got "✓ no .tsx/.jsx changed" and a clean exit on any commit that happened not to touch a
+// component. Under `--format json` it was worse — the exit came BEFORE anything was written, so
+// stdout was EMPTY and a CI step reading it could not tell that from a pass.
+//
+// Reproduced: rules stamped 19.6.0 against an installed 23.3.0, one README.md changed →
+// `✓ no .tsx/.jsx changed`, exit 0, empty JSON, while `ui-audit src --format json` on the same
+// tree at the same moment reported `owned-rules-stale`.
+//
+// Same defect as the `.jsx` one this file just fixed, one screen further down: a gate declaring
+// itself clean while holding a finding.
+/** `--changed` legitimately opened no file. NOT the same thing as a misconfigured scan path. */
+const changedNoFiles = CHANGED && filesScanned === 0;
+
+if (changedNoFiles && findings.length === 0) {
+  if (asJson) {
+    // ALWAYS emit a valid document on the JSON path. This branch used to exit before writing
+    // anything, so a CI step parsing stdout got an empty string and a zero exit.
+    process.stdout.write(
+      JSON.stringify({ summary: { errors: 0, warnings: 0 }, findings: [] }, null, 2) + "\n",
+    );
+  } else if (!quiet) {
+    console.log("✓ ui-audit --changed: no .tsx/.jsx changed on this branch.");
+  }
   process.exit(0);
 }
-if (filesScanned === 0) {
+
+if (filesScanned === 0 && !CHANGED) {
   const message =
     `ui-audit scanned 0 files — none of [${SCAN_DIRS.join(", ")}] exists (or all were filtered). ` +
     `Pass the directories to scan, e.g. \`node scripts/ui-audit.mjs src docs\`. ` +
@@ -1131,7 +1188,7 @@ if (filesScanned === 0) {
   process.exitCode = 2;
 }
 
-if (filesScanned === 0) {
+if (filesScanned === 0 && !changedNoFiles) {
   // already reported above
 } else if (asJson) {
   process.stdout.write(
@@ -1161,7 +1218,10 @@ if (filesScanned === 0) {
     console.log(`      ${C.dim}${f.snippet}${C.reset}`);
   }
   console.log(
-    `\ngodxjp-ui audit: ${C.red}${errors.length} error(s)${C.reset}, ${C.yellow}${warnings.length} warning(s)${C.reset} across ${scannedFiles.join(", ")}.`,
+    `\ngodxjp-ui audit: ${C.red}${errors.length} error(s)${C.reset}, ${C.yellow}${warnings.length} warning(s)${C.reset}` +
+      (scannedFiles.length > 0
+        ? ` across ${scannedFiles.join(", ")}.`
+        : " — no UI file changed on this branch, but the findings above are not about a file."),
   );
   if (errors.length === 0 && warnings.length === 0) {
     console.log("✓ No UI-standardization violations found.");
@@ -1169,4 +1229,4 @@ if (filesScanned === 0) {
 }
 
 // See the note above --rules: exitCode, so a large JSON report drains fully.
-if (filesScanned > 0) process.exitCode = errors.length > 0 ? 1 : 0;
+if (filesScanned > 0 || changedNoFiles) process.exitCode = errors.length > 0 ? 1 : 0;