@godxjp/ui 30.5.2 → 30.6.0

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.5.2.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 30.6.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.
@@ -56,10 +56,10 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 50 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2073 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2074 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1759 `component` entries are per-part knobs; reach for one only when a role is
+   1760 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
@@ -145,7 +145,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
 | `semantic` | 103 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1759 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `component` | 1760 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/RecordPicker.json

@@ -10,6 +10,12 @@
       "name": "mode",
       "type": "\"single\" | \"multiple\""
     },
+    {
+      "defaultValue": "\"auto\"",
+      "description": "TWO ENTRY POINTS AT ONCE, instead of \"dropdown OR dialog\" (gh#944). `auto` keeps the original behaviour: `threshold` picks one. `inline` opens both — a typeable field with suggestions REGARDLESS of `count`, and a 「検索」 button beside it that always shows and opens the dialog with filters + pagination; the half-typed text carries into the dialog as its initial query. Reach for it when `count > threshold` is almost always true: a consumer measured customer projects at hundreds-to-thousands of records, so the dialog-only branch was the one users met most, and there they lost the ability to type a key they already knew. The threshold answers \"is the set big\"; the real question is \"does this person already know what they want\" — `inline` stops forcing a choice. NOTE: the forwarded ref lands on the <input> under `inline` and on the trigger <button> otherwise.",
+      "name": "shape",
+      "type": "\"auto\" | \"inline\""
+    },
     {
       "defaultValue": "10",
       "description": "The dropdown/dialog switch. A dropdown is the right control for eight people and the wrong one for eight hundred; this is where that line is drawn, once, by a service rather than per screen.",
@@ -27,7 +33,7 @@
       "type": "(SearchSelectOptionProp | SelectOptionGroupProp)[]"
     },
     {
-      "description": "Server fetcher, debounced. `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.",
+      "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.",
       "name": "loadOptions",
       "type": "(params: { query: string; filters: Record<string, string>; cursor?: string }) => Promise<{ options: SearchSelectOptionProp[]; count?: number; nextCursor?: string }>"
     },
@@ -66,6 +72,11 @@
       "name": "placeholder",
       "type": "string"
     },
+    {
+      "description": "Field name, normally supplied by FormField. Declared explicitly because BOTH branches must keep it: a server's 422 is pinned to `data-field`, and a consumer measured the dropdown branch dropping it while the dialog branch kept it (gh#942).",
+      "name": "data-field",
+      "type": "string"
+    },
     {
       "description": "Dialog heading. Defaults to the localized `dataEntry.recordPicker.dialogTitle`.",
       "name": "dialogTitle",

package/agent/components.json

@@ -5996,6 +5996,12 @@
         "name": "mode",
         "type": "\"single\" | \"multiple\""
       },
+      {
+        "defaultValue": "\"auto\"",
+        "description": "TWO ENTRY POINTS AT ONCE, instead of \"dropdown OR dialog\" (gh#944). `auto` keeps the original behaviour: `threshold` picks one. `inline` opens both — a typeable field with suggestions REGARDLESS of `count`, and a 「検索」 button beside it that always shows and opens the dialog with filters + pagination; the half-typed text carries into the dialog as its initial query. Reach for it when `count > threshold` is almost always true: a consumer measured customer projects at hundreds-to-thousands of records, so the dialog-only branch was the one users met most, and there they lost the ability to type a key they already knew. The threshold answers \"is the set big\"; the real question is \"does this person already know what they want\" — `inline` stops forcing a choice. NOTE: the forwarded ref lands on the <input> under `inline` and on the trigger <button> otherwise.",
+        "name": "shape",
+        "type": "\"auto\" | \"inline\""
+      },
       {
         "defaultValue": "10",
         "description": "The dropdown/dialog switch. A dropdown is the right control for eight people and the wrong one for eight hundred; this is where that line is drawn, once, by a service rather than per screen.",
@@ -6013,7 +6019,7 @@
         "type": "(SearchSelectOptionProp | SelectOptionGroupProp)[]"
       },
       {
-        "description": "Server fetcher, debounced. `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.",
+        "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.",
         "name": "loadOptions",
         "type": "(params: { query: string; filters: Record<string, string>; cursor?: string }) => Promise<{ options: SearchSelectOptionProp[]; count?: number; nextCursor?: string }>"
       },
@@ -6052,6 +6058,11 @@
         "name": "placeholder",
         "type": "string"
       },
+      {
+        "description": "Field name, normally supplied by FormField. Declared explicitly because BOTH branches must keep it: a server's 422 is pinned to `data-field`, and a consumer measured the dropdown branch dropping it while the dialog branch kept it (gh#942).",
+        "name": "data-field",
+        "type": "string"
+      },
       {
         "description": "Dialog heading. Defaults to the localized `dataEntry.recordPicker.dialogTitle`.",
         "name": "dialogTitle",

package/agent/index.json

@@ -4,7 +4,7 @@
     "components": 173,
     "patterns": 21,
     "rules": 50,
-    "tokens": 2073,
+    "tokens": 2074,
     "vocabulary": 14
   },
   "files": [
@@ -48,19 +48,19 @@
   "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.5.2/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v30.6.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",
   "tokenTiers": {
     "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
     "counts": {
-      "component": 1759,
+      "component": 1760,
       "foundation": 211,
       "semantic": 103
     },
     "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.5.2"
+  "version": "30.6.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 173 components, 2073 design tokens,
-> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 30.5.2.
+> A Japanese-enterprise React design system: 173 components, 2074 design tokens,
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 30.6.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@30.5.2`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@30.6.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -18,7 +18,7 @@ that can only fetch URLs.
 - [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 46 KB — all 173 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/<Name>.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–34 KB, median 6 KB). Read the index, then fetch only the ones you chose — this is the selective route, and the reason you do not need the blob.
 - [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.2 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
-- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 103 `semantic` roles, 1759 `component` knobs.
+- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 103 `semantic` roles, 1760 `component` knobs.
 - [vocabulary.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json): the controlled prop vocabulary — which prop name means what, across every component.
 - [rules.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json): 50 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 26 shapes that make generated UI look generated, each with its fix.
@@ -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.5.2/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v30.6.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/tokens.json

@@ -5891,6 +5891,12 @@
     "tier": "component",
     "value": "22rem"
   },
+  {
+    "description": "Danh sách gợi ý dưới ô inline (gh#944) — ngắn hơn danh sách trong Dialog, vì nó nằm TRONG dòng chảy của form chứ không phải trong một lớp phủ riêng.",
+    "name": "--record-picker-suggest-max-block-size",
+    "tier": "component",
+    "value": "14rem"
+  },
   {
     "description": "Data-entry component tokens — small-by-design text knobs (rule #45/#46).",
     "name": "--password-strength-score-font-size",

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

@@ -35,6 +35,7 @@ export type { RecordPickerProp, RecordPickerProp as RecordPickerProps };
  */
 export declare const RecordPicker: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "defaultValue" | "onChange" | "value"> & {
     mode?: "single" | "multiple";
+    shape?: "auto" | "inline";
     value?: string | string[] | null;
     defaultValue?: string | string[] | null;
     onValueChange?: (value: string | string[] | null) => void;
@@ -59,4 +60,5 @@ export declare const RecordPicker: React.ForwardRefExoticComponent<Omit<React.Bu
     placeholder?: string;
     dialogTitle?: string;
     size?: "xs" | "sm" | "md" | "lg";
-} & React.RefAttributes<HTMLButtonElement>>;
+    "data-field"?: string;
+} & React.RefAttributes<HTMLButtonElement | HTMLInputElement>>;

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

@@ -1,6 +1,6 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Check, ChevronDown, X } from "lucide-react";
+import { Check, ChevronDown, Search, X } from "lucide-react";
 import * as React from "react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
@@ -24,6 +24,7 @@ import { Select } from "./select.js";
 const RecordPicker = React.forwardRef(
   function RecordPicker2({
     mode = "single",
+    shape = "auto",
     value,
     defaultValue,
     onValueChange,
@@ -39,6 +40,7 @@ const RecordPicker = React.forwardRef(
     disabled = false,
     size,
     className,
+    "data-field": fieldName,
     ...props
   }, ref) {
     const { t } = useTranslation();
@@ -55,10 +57,44 @@ 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 staticOptions = React.useMemo(
       () => options ? normalizeSelectOptions(options) : [],
       [options]
     );
+    if (shape === "inline") {
+      return /* @__PURE__ */ jsx(
+        InlinePicker,
+        {
+          ref,
+          isMultiple,
+          selected,
+          commit,
+          staticOptions,
+          loadOptions,
+          filters,
+          selectedOptions,
+          emptyOption,
+          placeholder,
+          dialogTitle,
+          disabled,
+          size,
+          className,
+          "data-field": fieldName,
+          ...props
+        }
+      );
+    }
     const total = count ?? (options ? staticOptions.length : void 0);
     const asDialog = total === void 0 ? Boolean(loadOptions) : total > threshold;
     if (!asDialog) {
@@ -66,6 +102,10 @@ const RecordPicker = React.forwardRef(
         Select,
         {
           mode: isMultiple ? "multiple" : void 0,
+          loadOptions: selectLoadOptions,
+          id: props.id,
+          "data-field": fieldName,
+          "aria-describedby": props["aria-describedby"],
           labelInValue: false,
           showSearch: true,
           options: withEmptyOption(options, emptyOption),
@@ -82,6 +122,7 @@ const RecordPicker = React.forwardRef(
       DialogPicker,
       {
         ref,
+        "data-field": fieldName,
         isMultiple,
         selected,
         commit,
@@ -100,6 +141,7 @@ const RecordPicker = React.forwardRef(
     );
   }
 );
+const INLINE_SUGGESTION_LIMIT = 8;
 function toArray(v) {
   if (v === null || v === void 0) return [];
   return Array.isArray(v) ? v : [v];
@@ -108,6 +150,155 @@ function withEmptyOption(options, emptyOption) {
   if (!emptyOption) return options;
   return [{ value: emptyOption.value, label: emptyOption.label }, ...options ?? []];
 }
+const InlinePicker = React.forwardRef(function InlinePicker2({
+  isMultiple,
+  selected,
+  commit,
+  staticOptions,
+  loadOptions,
+  filters,
+  selectedOptions,
+  emptyOption,
+  placeholder,
+  dialogTitle,
+  disabled,
+  size,
+  className,
+  id,
+  "data-field": fieldName,
+  "aria-describedby": describedBy
+}, ref) {
+  const { t } = useTranslation();
+  const [query, setQuery] = React.useState("");
+  const [rows, setRows] = React.useState(staticOptions);
+  const [openSuggest, setOpenSuggest] = React.useState(false);
+  const [dialogQuery, setDialogQuery] = React.useState(null);
+  const labelCache = React.useRef(/* @__PURE__ */ new Map());
+  for (const o of [...selectedOptions ?? [], ...staticOptions, ...rows]) {
+    labelCache.current.set(o.value, o);
+  }
+  React.useEffect(() => {
+    if (!loadOptions || query.trim() === "") return;
+    const id2 = setTimeout(() => {
+      void loadOptions({ query, filters: {} }).then((r) => setRows(r.options)).catch(() => void 0);
+    }, 250);
+    return () => clearTimeout(id2);
+  }, [query, loadOptions]);
+  const suggestions = React.useMemo(() => {
+    const q = query.trim().toLowerCase();
+    const base = loadOptions ? rows : staticOptions;
+    return (q ? base.filter((o) => (o.label + (o.sublabel ?? "")).toLowerCase().includes(q)) : base).slice(0, INLINE_SUGGESTION_LIMIT);
+  }, [query, rows, staticOptions, loadOptions]);
+  const chosen = selected.map((v) => labelCache.current.get(v) ?? { value: v, label: v });
+  const pick = (v) => {
+    commit(isMultiple ? [...selected, v] : [v]);
+    setQuery("");
+    setOpenSuggest(false);
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(Flex, { direction: "col", gap: 1, className: cn("ui-record-picker-inline", className), children: [
+      /* @__PURE__ */ jsxs(Flex, { direction: "row", gap: "xs", align: "center", children: [
+        /* @__PURE__ */ jsx(
+          Input,
+          {
+            ref,
+            type: "search",
+            value: query,
+            disabled,
+            placeholder: placeholder ?? t("dataEntry.recordPicker.placeholder"),
+            onChange: (e) => {
+              setQuery(e.target.value);
+              setOpenSuggest(true);
+            },
+            onFocus: () => setOpenSuggest(true),
+            className: "ui-record-picker-inline-input",
+            id,
+            "data-field": fieldName,
+            "aria-describedby": describedBy
+          }
+        ),
+        /* @__PURE__ */ jsxs(
+          Button,
+          {
+            type: "button",
+            variant: "outline",
+            size: size === "lg" ? "lg" : "default",
+            disabled,
+            "aria-haspopup": "dialog",
+            onClick: () => setDialogQuery(query),
+            children: [
+              /* @__PURE__ */ jsx(Search, { "aria-hidden": "true" }),
+              t("dataEntry.recordPicker.openSearch")
+            ]
+          }
+        ),
+        chosen.length > 0 && !disabled ? /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "ghost",
+            size: "icon-sm",
+            "aria-label": t("dataEntry.recordPicker.clear"),
+            onClick: () => commit([]),
+            children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
+          }
+        ) : null
+      ] }),
+      chosen.length > 0 ? /* @__PURE__ */ jsx(Flex, { direction: "row", gap: "xs", wrap: true, align: "center", children: chosen.map((c) => /* @__PURE__ */ jsxs(Badge, { variant: "secondary", as: "span", children: [
+        c.icon,
+        c.label,
+        c.sublabel ? ` ${c.sublabel}` : ""
+      ] }, c.value)) }) : null,
+      openSuggest && suggestions.length > 0 ? /* @__PURE__ */ jsx(
+        Command,
+        {
+          shouldFilter: false,
+          className: "ui-record-picker-suggest",
+          "aria-label": t("dataEntry.recordPicker.suggestions"),
+          children: suggestions.map((o) => /* @__PURE__ */ jsxs(
+            "button",
+            {
+              type: "button",
+              role: "option",
+              "aria-selected": selected.includes(o.value),
+              "data-picked": selected.includes(o.value) ? "" : void 0,
+              className: "ui-record-picker-option",
+              onClick: () => pick(o.value),
+              children: [
+                /* @__PURE__ */ jsx("span", { className: "ui-record-picker-tick", "aria-hidden": "true", children: selected.includes(o.value) ? /* @__PURE__ */ jsx(Check, {}) : null }),
+                /* @__PURE__ */ jsxs("span", { className: "ui-record-picker-option-label", children: [
+                  o.label,
+                  o.sublabel ? /* @__PURE__ */ jsx(Text, { as: "span", size: "2xs", tone: "muted", children: o.sublabel }) : null
+                ] })
+              ]
+            },
+            o.value
+          ))
+        }
+      ) : null
+    ] }),
+    dialogQuery !== null ? /* @__PURE__ */ jsx(
+      DialogPicker,
+      {
+        isMultiple,
+        selected,
+        commit: (next) => {
+          commit(next);
+          setDialogQuery(null);
+          setQuery("");
+        },
+        staticOptions,
+        loadOptions,
+        filters,
+        selectedOptions,
+        emptyOption,
+        dialogTitle,
+        initialQuery: dialogQuery,
+        autoOpen: true,
+        onDismiss: () => setDialogQuery(null)
+      }
+    ) : null
+  ] });
+});
 const DialogPicker = React.forwardRef(function DialogPicker2({
   isMultiple,
   selected,
@@ -122,31 +313,41 @@ const DialogPicker = React.forwardRef(function DialogPicker2({
   disabled,
   size,
   className,
+  initialQuery,
+  autoOpen = false,
+  onDismiss,
   ...props
 }, ref) {
   const { t } = useTranslation();
-  const [open, setOpen] = React.useState(false);
-  const [query, setQuery] = React.useState("");
+  const [open, setOpen] = React.useState(autoOpen);
+  const [query, setQuery] = React.useState(initialQuery ?? "");
   const [filterValues, setFilterValues] = React.useState({});
   const [rows, setRows] = React.useState(staticOptions);
   const [status, setStatus] = React.useState("idle");
+  const [cursor, setCursor] = React.useState(void 0);
   const [draft, setDraft] = React.useState(selected);
   React.useEffect(() => {
     if (open) setDraft(selected);
   }, [open, selected]);
-  const labels = React.useMemo(() => {
-    const map = /* @__PURE__ */ new Map();
-    for (const o of [...selectedOptions ?? [], ...staticOptions, ...rows]) map.set(o.value, o);
-    if (emptyOption) map.set(emptyOption.value, { value: emptyOption.value, label: emptyOption.label });
-    return map;
-  }, [selectedOptions, staticOptions, rows, emptyOption]);
+  const labelCache = React.useRef(/* @__PURE__ */ new Map());
+  for (const o of [...selectedOptions ?? [], ...staticOptions, ...rows]) {
+    labelCache.current.set(o.value, o);
+  }
+  if (emptyOption) {
+    labelCache.current.set(emptyOption.value, {
+      value: emptyOption.value,
+      label: emptyOption.label
+    });
+  }
+  const labels = labelCache.current;
   const load = React.useCallback(
-    async (q, f) => {
+    async (q, f, more) => {
       if (!loadOptions) return;
       setStatus("loading");
       try {
-        const result = await loadOptions({ query: q, filters: f });
-        setRows(result.options);
+        const result = await loadOptions({ query: q, filters: f, cursor: more });
+        setRows((prev) => more ? [...prev, ...result.options] : result.options);
+        setCursor(result.nextCursor);
         setStatus("idle");
       } catch {
         setStatus("error");
@@ -183,112 +384,161 @@ const DialogPicker = React.forwardRef(function DialogPicker2({
   };
   const chips = selected.map((v) => labels.get(v) ?? { value: v, label: v });
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsxs(
-      Button,
+    autoOpen ? null : /* @__PURE__ */ jsxs(Flex, { direction: "row", gap: "xs", align: "center", className: "ui-record-picker-row", children: [
+      /* @__PURE__ */ jsxs(
+        Button,
+        {
+          ref,
+          type: "button",
+          variant: "outline",
+          size,
+          disabled,
+          "aria-haspopup": "dialog",
+          onClick: () => setOpen(true),
+          className: cn("ui-record-picker-trigger", className),
+          ...props,
+          children: [
+            /* @__PURE__ */ jsx("span", { className: "ui-record-picker-trigger-label", children: chips.length === 0 ? /* @__PURE__ */ jsx(Text, { as: "span", size: "sm", tone: "muted", children: placeholder ?? t("dataEntry.recordPicker.placeholder") }) : /* @__PURE__ */ jsx(Flex, { direction: "row", gap: "xs", wrap: true, align: "center", children: chips.map((c) => /* @__PURE__ */ jsxs(Badge, { variant: "secondary", as: "span", children: [
+              c.icon,
+              c.label
+            ] }, c.value)) }) }),
+            /* @__PURE__ */ jsx(ChevronDown, { "aria-hidden": "true" })
+          ]
+        }
+      ),
+      !isMultiple && selected.length > 0 && !disabled ? /* @__PURE__ */ jsx(
+        Button,
+        {
+          variant: "ghost",
+          size: "icon-sm",
+          "aria-label": t("dataEntry.recordPicker.clear"),
+          onClick: () => commit([]),
+          children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
+        }
+      ) : null
+    ] }),
+    /* @__PURE__ */ jsx(
+      Dialog,
       {
-        ref,
-        type: "button",
-        variant: "outline",
-        size,
-        disabled,
-        "aria-haspopup": "dialog",
-        onClick: () => setOpen(true),
-        className: cn("ui-record-picker-trigger", className),
-        ...props,
-        children: [
-          /* @__PURE__ */ jsx("span", { className: "ui-record-picker-trigger-label", children: chips.length === 0 ? /* @__PURE__ */ jsx(Text, { as: "span", size: "sm", tone: "muted", children: placeholder ?? t("dataEntry.recordPicker.placeholder") }) : /* @__PURE__ */ jsx(Flex, { direction: "row", gap: "xs", wrap: true, align: "center", children: chips.map((c) => /* @__PURE__ */ jsxs(Badge, { variant: "secondary", as: "span", children: [
-            c.icon,
-            c.label
-          ] }, c.value)) }) }),
-          /* @__PURE__ */ jsx(ChevronDown, { "aria-hidden": "true" })
-        ]
-      }
-    ),
-    /* @__PURE__ */ jsx(Dialog, { open, onOpenChange: setOpen, children: /* @__PURE__ */ jsxs(DialogContent, { className: "ui-record-picker-dialog", children: [
-      /* @__PURE__ */ jsx(DialogHeader, { children: /* @__PURE__ */ jsx(DialogTitle, { children: dialogTitle ?? t("dataEntry.recordPicker.dialogTitle") }) }),
-      /* @__PURE__ */ jsx(DialogBody, { children: /* @__PURE__ */ jsxs(Flex, { direction: "col", gap: "md", children: [
-        /* @__PURE__ */ jsx(
-          Input,
-          {
-            autoFocus: true,
-            type: "search",
-            value: query,
-            onChange: (e) => setQuery(e.target.value),
-            "aria-label": t("dataEntry.recordPicker.search"),
-            placeholder: t("dataEntry.recordPicker.searchPlaceholder")
-          }
-        ),
-        filters?.length ? /* @__PURE__ */ jsx(Flex, { direction: "row", gap: "sm", wrap: true, role: "group", "aria-label": t("dataEntry.recordPicker.filters"), children: filters.map((f) => /* @__PURE__ */ jsx(
-          Select,
-          {
-            size: "sm",
-            "aria-label": f.label,
-            placeholder: f.label,
-            value: filterValues[f.name] ?? "",
-            onValueChange: (next) => setFilterValues((prev) => ({ ...prev, [f.name]: next })),
-            options: [
-              { value: "", label: t("dataEntry.recordPicker.allFilter") },
-              ...f.options
-            ]
-          },
-          f.name
-        )) }) : null,
-        /* @__PURE__ */ jsx(Command, { shouldFilter: false, split: isMultiple, className: "ui-record-picker-list", children: status === "error" ? /* @__PURE__ */ jsx(
-          EmptyState,
-          {
-            variant: "compact",
-            tone: "destructive",
-            title: t("dataEntry.recordPicker.error"),
-            action: /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", onClick: () => void load(query, filterValues), children: t("dataEntry.recordPicker.more") })
-          }
-        ) : status === "loading" ? /* @__PURE__ */ jsx("div", { role: "status", className: "ui-record-picker-status", children: t("dataEntry.recordPicker.loading") }) : visible.length === 0 ? /* @__PURE__ */ jsx(EmptyState, { variant: "compact", title: t("dataEntry.recordPicker.empty") }) : groups.map(([heading, items]) => {
-          const rendered = items.map((o) => {
-            const picked = (isMultiple ? draft : selected).includes(o.value);
-            return /* @__PURE__ */ jsxs(
-              "button",
+        open,
+        onOpenChange: (next) => {
+          setOpen(next);
+          if (!next) onDismiss?.();
+        },
+        children: /* @__PURE__ */ jsxs(DialogContent, { className: "ui-record-picker-dialog", children: [
+          /* @__PURE__ */ jsx(DialogHeader, { children: /* @__PURE__ */ jsx(DialogTitle, { children: dialogTitle ?? t("dataEntry.recordPicker.dialogTitle") }) }),
+          /* @__PURE__ */ jsx(DialogBody, { children: /* @__PURE__ */ jsxs(Flex, { direction: "col", gap: "md", children: [
+            /* @__PURE__ */ jsx(
+              Input,
               {
-                type: "button",
-                role: "option",
-                "aria-selected": picked,
-                "data-picked": picked ? "" : void 0,
-                disabled: o.disabled,
-                className: "ui-record-picker-option",
-                onClick: () => toggle(o.value),
-                children: [
-                  /* @__PURE__ */ jsx("span", { className: "ui-record-picker-tick", "aria-hidden": "true", children: picked ? /* @__PURE__ */ jsx(Check, {}) : null }),
-                  o.icon,
-                  /* @__PURE__ */ jsxs("span", { className: "ui-record-picker-option-label", children: [
-                    o.label,
-                    o.sublabel ? /* @__PURE__ */ jsx(Text, { as: "span", size: "2xs", tone: "muted", children: o.sublabel }) : null
-                  ] })
-                ]
-              },
-              o.value
-            );
-          });
-          return heading ? /* @__PURE__ */ jsx(CommandGroup, { heading, children: rendered }, heading) : /* @__PURE__ */ jsx(React.Fragment, { children: rendered }, "__ungrouped");
-        }) })
-      ] }) }),
-      isMultiple ? /* @__PURE__ */ jsxs(DialogFooter, { children: [
-        /* @__PURE__ */ jsx(Text, { as: "span", size: "xs", tone: "muted", className: "me-auto", children: t("dataEntry.recordPicker.selected", { count: draft.length }) }),
-        /* @__PURE__ */ jsxs(Button, { variant: "ghost", size: "sm", onClick: () => setDraft([]), children: [
-          /* @__PURE__ */ jsx(X, { "aria-hidden": "true" }),
-          t("dataEntry.recordPicker.clear")
-        ] }),
-        /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", onClick: () => setOpen(false), children: t("dataEntry.recordPicker.cancel") }),
-        /* @__PURE__ */ jsx(
-          Button,
-          {
-            size: "sm",
-            onClick: () => {
-              commit(draft);
-              setOpen(false);
-            },
-            children: t("dataEntry.recordPicker.confirm")
-          }
-        )
-      ] }) : null
-    ] }) })
+                autoFocus: true,
+                type: "search",
+                value: query,
+                onChange: (e) => setQuery(e.target.value),
+                "aria-label": t("dataEntry.recordPicker.search"),
+                placeholder: t("dataEntry.recordPicker.searchPlaceholder")
+              }
+            ),
+            filters?.length ? /* @__PURE__ */ jsx(
+              Flex,
+              {
+                direction: "row",
+                gap: "sm",
+                wrap: true,
+                role: "group",
+                "aria-label": t("dataEntry.recordPicker.filters"),
+                children: filters.map((f) => /* @__PURE__ */ jsx(
+                  Select,
+                  {
+                    size: "sm",
+                    "aria-label": f.label,
+                    placeholder: f.label,
+                    value: filterValues[f.name] ?? "",
+                    onValueChange: (next) => setFilterValues((prev) => ({ ...prev, [f.name]: next })),
+                    options: [
+                      { value: "", label: t("dataEntry.recordPicker.allFilter") },
+                      ...f.options
+                    ]
+                  },
+                  f.name
+                ))
+              }
+            ) : null,
+            /* @__PURE__ */ jsx(Command, { shouldFilter: false, split: isMultiple, className: "ui-record-picker-list", children: status === "error" ? /* @__PURE__ */ jsx(
+              EmptyState,
+              {
+                variant: "compact",
+                tone: "destructive",
+                title: t("dataEntry.recordPicker.error"),
+                action: /* @__PURE__ */ jsx(
+                  Button,
+                  {
+                    variant: "outline",
+                    size: "sm",
+                    onClick: () => void load(query, filterValues),
+                    children: t("dataEntry.recordPicker.more")
+                  }
+                )
+              }
+            ) : status === "loading" ? /* @__PURE__ */ jsx("div", { role: "status", className: "ui-record-picker-status", children: t("dataEntry.recordPicker.loading") }) : visible.length === 0 ? /* @__PURE__ */ jsx(EmptyState, { variant: "compact", title: t("dataEntry.recordPicker.empty") }) : groups.map(([heading, items]) => {
+              const rendered = items.map((o) => {
+                const picked = (isMultiple ? draft : selected).includes(o.value);
+                return /* @__PURE__ */ jsxs(
+                  "button",
+                  {
+                    type: "button",
+                    role: "option",
+                    "aria-selected": picked,
+                    "data-picked": picked ? "" : void 0,
+                    disabled: o.disabled,
+                    className: "ui-record-picker-option",
+                    onClick: () => toggle(o.value),
+                    children: [
+                      /* @__PURE__ */ jsx("span", { className: "ui-record-picker-tick", "aria-hidden": "true", children: picked ? /* @__PURE__ */ jsx(Check, {}) : null }),
+                      o.icon,
+                      /* @__PURE__ */ jsxs("span", { className: "ui-record-picker-option-label", children: [
+                        o.label,
+                        o.sublabel ? /* @__PURE__ */ jsx(Text, { as: "span", size: "2xs", tone: "muted", children: o.sublabel }) : null
+                      ] })
+                    ]
+                  },
+                  o.value
+                );
+              });
+              return heading ? /* @__PURE__ */ jsx(CommandGroup, { heading, children: rendered }, heading) : /* @__PURE__ */ jsx(React.Fragment, { children: rendered }, "__ungrouped");
+            }) }),
+            cursor !== void 0 && status !== "loading" ? /* @__PURE__ */ jsx(
+              Button,
+              {
+                variant: "outline",
+                size: "sm",
+                onClick: () => void load(query, filterValues, cursor),
+                children: t("dataEntry.recordPicker.more")
+              }
+            ) : null
+          ] }) }),
+          isMultiple ? /* @__PURE__ */ jsxs(DialogFooter, { children: [
+            /* @__PURE__ */ jsx(Text, { as: "span", size: "xs", tone: "muted", className: "me-auto", children: t("dataEntry.recordPicker.selected", { count: draft.length }) }),
+            /* @__PURE__ */ jsxs(Button, { variant: "ghost", size: "sm", onClick: () => setDraft([]), children: [
+              /* @__PURE__ */ jsx(X, { "aria-hidden": "true" }),
+              t("dataEntry.recordPicker.clear")
+            ] }),
+            /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", onClick: () => setOpen(false), children: t("dataEntry.recordPicker.cancel") }),
+            /* @__PURE__ */ jsx(
+              Button,
+              {
+                size: "sm",
+                onClick: () => {
+                  commit(draft);
+                  setOpen(false);
+                },
+                children: t("dataEntry.recordPicker.confirm")
+              }
+            )
+          ] }) : null
+        ] })
+      }
+    )
   ] });
 });
 export {

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.5.2",
+  "version": "30.6.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -206,7 +206,9 @@
       "cancel": "Cancel",
       "clear": "Clear selection",
       "more": "Load more",
-      "openDialog": "Choose from list"
+      "openDialog": "Choose from list",
+      "openSearch": "Search",
+      "suggestions": "Suggestions"
     }
   },
   "feedback": {

package/dist/i18n/messages/ja.json

@@ -202,7 +202,9 @@
       "cancel": "キャンセル",
       "clear": "選択を解除",
       "more": "さらに読み込む",
-      "openDialog": "一覧から選択"
+      "openDialog": "一覧から選択",
+      "openSearch": "検索",
+      "suggestions": "候補"
     }
   },
   "feedback": {

package/dist/i18n/messages/vi.json

@@ -203,7 +203,9 @@
       "cancel": "Huỷ",
       "clear": "Bỏ chọn",
       "more": "Tải thêm",
-      "openDialog": "Chọn từ danh sách"
+      "openDialog": "Chọn từ danh sách",
+      "openSearch": "Tìm kiếm",
+      "suggestions": "Gợi ý"
     }
   },
   "feedback": {

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

@@ -1148,6 +1148,22 @@ export type RecordPickerFilterProp = {
 export type RecordPickerProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "defaultValue" | "onChange"> & {
     /** `single` (default) or `multiple`. Decides the value shape AND whether the dialog confirms. */
     mode?: "single" | "multiple";
+    /**
+     * HAI LỐI VÀO CÙNG LÚC, thay vì "dropdown HOẶC Dialog" (gh#944).
+     *
+     * `auto` (mặc định) giữ nguyên hành vi cũ: `threshold` quyết một trong hai.
+     *
+     * `inline` mở cả hai cùng lúc — ô gõ được có gợi ý ngay bên dưới BẤT KỂ `count`, và một nút
+     * 「検索」 luôn hiện bên cạnh mở Dialog có filter + phân trang. Chữ đang gõ dở mang sang Dialog
+     * làm từ khoá ban đầu.
+     *
+     * Vì sao nó tồn tại: consumer đo được dự án khách có vài trăm tới vài nghìn bản ghi, nên
+     * `count > threshold` gần như LUÔN đúng — tức nhánh "chỉ Dialog" là nhánh người dùng gặp
+     * thường xuyên nhất, và ở đó họ mất hẳn khả năng gõ. Ngưỡng trả lời đúng câu hỏi "tập lớn hay
+     * nhỏ" nhưng câu hỏi thật là "người này đã biết mình tìm gì chưa": biết rồi thì gõ nhanh hơn
+     * mở modal, chưa biết thì cần filter. `inline` không bắt chọn.
+     */
+    shape?: "auto" | "inline";
     value?: string | string[] | null;
     defaultValue?: string | string[] | null;
     /** Receives the shape you passed in: an array for `multiple`, a single value (or null) else. */
@@ -1186,6 +1202,12 @@ export type RecordPickerProp = Omit<React.ButtonHTMLAttributes<HTMLButtonElement
     placeholder?: string;
     dialogTitle?: string;
     size?: "xs" | "sm" | "md" | "lg";
+    /**
+     * Tên trường, do `FormField` truyền xuống. Khai tường minh vì CẢ HAI nhánh phải giữ nó: một
+     * lỗi 422 của server bám theo `data-field`, và consumer đo được nhánh dropdown đánh rơi nó
+     * trong khi nhánh Dialog thì giữ (gh#942).
+     */
+    "data-field"?: string;
 };
 export type SearchSelectLoadParamsProp = {
     query: string;

package/dist/styles/data-entry-layout.css

@@ -835,3 +835,32 @@
     font-size: var(--font-size-sm);
   }
 }
+
+@layer components {
+
+  .ui-record-picker-row {
+    inline-size: 100%;
+  }
+  .ui-record-picker-row > .ui-record-picker-trigger {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+  }
+}
+
+@layer components {
+
+  .ui-record-picker-inline {
+    inline-size: 100%;
+  }
+  .ui-record-picker-inline-input {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+  }
+
+  .ui-record-picker-suggest {
+    max-block-size: var(--record-picker-suggest-max-block-size);
+    overflow-y: auto;
+    border: var(--stroke-hairline) solid hsl(var(--border));
+    border-radius: var(--radius-md);
+  }
+}

package/dist/tokens/components/data-entry.css

@@ -4,6 +4,8 @@
 
   --record-picker-list-max-block-size: 22rem;
 
+  --record-picker-suggest-max-block-size: 14rem;
+
   --password-strength-score-font-size: var(
     --font-size-xs,
     calc(var(--font-size-base) / var(--font-size-ratio))

package/package.json

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

package/scripts/ui-audit.mjs

@@ -40,17 +40,53 @@ function changedFiles() {
     return r.status === 0 ? (r.stdout ?? "") : null;
   };
 
-  const mergeBase = run(["merge-base", "HEAD", "origin/main"]);
+  /*
+   * `origin/main` WAS HARD-CODED, AND MOST REPOS THAT RUN THIS DO NOT DEFAULT TO main (gh#948).
+   *
+   * In a repo whose default branch is `dev`, `origin/main` usually still EXISTS — stale, or
+   * forked long ago — so `merge-base` resolves happily to an ancient commit and the "what this
+   * branch changed" set quietly becomes "everything since that commit". Measured in
+   * godx-corebooks: a fresh branch off `origin/dev` with ZERO edits audited ~200 files and
+   * reported 1114 errors. Nothing was wrong with the branch; the question was.
+   *
+   * That is the worst shape a scope bug can take — not a crash, a plausible number. It blocked
+   * corebooks#114 (the ratchet gate) and #86, because a ratchet cannot start from a baseline
+   * nobody believes.
+   *
+   * Order: an explicit `--base=<ref>` wins; otherwise `origin/HEAD`, which is the symbolic ref
+   * git keeps for the remote's OWN default branch and is therefore right in every repo without
+   * naming one; `origin/main` stays last so nothing that works today stops working.
+   *
+   * Fail-closed is unchanged (gh#542): if no candidate resolves, this returns an error rather
+   * than an empty file list. "Could not work out the base" must never read as "nothing changed".
+   */
+  const explicitBase = args.find((a) => a.startsWith("--base="))?.slice("--base=".length);
+  const candidates = explicitBase ? [explicitBase] : ["origin/HEAD", "origin/main"];
+
+  let mergeBase = null;
+  let baseUsed = null;
+  for (const candidate of candidates) {
+    const out = run(["merge-base", "HEAD", candidate]);
+    if (out !== null) {
+      mergeBase = out;
+      baseUsed = candidate;
+      break;
+    }
+  }
+
   if (mergeBase === null) {
     return {
       error:
-        "ui-audit --changed could not resolve `git merge-base HEAD origin/main`. " +
+        `ui-audit --changed could not resolve a base (tried: ${candidates.join(", ")}). ` +
         "Without a base there is no such thing as \u201cwhat this branch changed\u201d, and reporting a " +
-        "clean audit from that is not a result. Fetch origin/main (a shallow clone may need " +
-        "`git fetch --unshallow`), or pass the directories to scan instead of `--changed`.",
+        "clean audit from that is not a result. Fetch the default branch (a shallow clone may need " +
+        "`git fetch --unshallow`), pass `--base=<ref>`, or pass the directories to scan instead of " +
+        "`--changed`.",
     };
   }
 
+
+
   const parts = [
     run(["diff", "--name-only", "--diff-filter=ACMR", mergeBase.trim(), "--"]),
     run(["diff", "--name-only", "--diff-filter=ACMR", "--cached"]),
@@ -64,6 +100,10 @@ function changedFiles() {
   }
 
   return {
+    // Đi kèm danh sách file, và được in ra: một base SAI không làm chương trình chết, nó cho ra
+    // một con số hợp lý (1114 lỗi trên nhánh chưa sửa gì). Cách duy nhất để người đọc phát hiện
+    // là thấy nó đã so với cái gì.
+    base: baseUsed,
     files: [
       ...new Set(
         parts
@@ -96,13 +136,55 @@ if (changed?.error) {
   }
   process.exit(2);
 }
+/*
+ * ONE TERRITORY, READ BY BOTH PATHS (gh#949).
+ *
+ * The scan roots used to be spelled inline here, so only the DEFAULT path knew them and
+ * `--changed` scanned whatever git happened to name. On the same commit, same working tree:
+ *
+ *     pnpm run audit                       -> 0 error
+ *     node scripts/ui-audit.mjs --changed  -> 3 error
+ *
+ * All three were in `mcp/src/data/components.ts`, and all three were the catalog's own PROSE —
+ * `Text`'s description quotes `<span className="text-[13px]">` as the anti-example the component
+ * exists to replace. A guard that reports its own teaching material is a guard people switch off.
+ *
+ * The fix is NOT to strip backtick spans from the corpus, which was the first idea: in a `.tsx`
+ * a backtick is a TEMPLATE LITERAL, i.e. real code — `className={`text-[13px]`}` appears in this
+ * repo today, and blinding the audit to it would trade three false positives for real misses.
+ *
+ * Nor is it a per-directory exclusion. The audit's subject is UI CODE, and in SELF mode this
+ * repo's UI code is `src/` and `docs/` — `mcp/src/data` renders nothing and holds no JSX (0 `.tsx`
+ * files, measured). So the roots are the territory, and `--changed` now narrows to it rather than
+ * having its own opinion. Add a root here and BOTH paths gain it; that is the property the split
+ * spelling could not have.
+ *
+ * CONSUMER mode is deliberately NOT narrowed. There the roots are a GUESS at a Laravel layout,
+ * and an app keeping its components somewhere else would get "nothing scanned" from a filter that
+ * is only right about this repo. `--changed` seeing the real files is strictly better there.
+ */
+const SELF_SCAN_ROOTS = ["src", "docs"];
+const CONSUMER_SCAN_ROOTS = [
+  "resources/js/components",
+  "resources/js/pages",
+  "resources/js/layouts",
+];
+const withinSelfRoots = (file) =>
+  SELF_SCAN_ROOTS.some((root) => file === root || file.startsWith(`${root}/`));
+
+/** Named so the summary can say how many files `--changed` handed over and the roots declined. */
+const changedOutsideRoots =
+  CHANGED && SELF && !dirArgs.length ? changed.files.filter((f) => !withinSelfRoots(f)) : [];
+
 const SCAN_DIRS = CHANGED
-  ? changed.files
+  ? SELF && !dirArgs.length
+    ? changed.files.filter(withinSelfRoots)
+    : changed.files
   : dirArgs.length
     ? dirArgs
     : SELF
-      ? ["src", "docs"]
-      : ["resources/js/components", "resources/js/pages", "resources/js/layouts"];
+      ? SELF_SCAN_ROOTS
+      : CONSUMER_SCAN_ROOTS;
 
 const PALETTE =
   "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|gray|grey|slate|zinc|neutral|stone";
@@ -1850,7 +1932,15 @@ if (changedNoFiles && findings.length === 0) {
       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.");
+    // "Nothing changed" and "everything that changed is outside the territory" are two
+    // different facts, and reading the first when the second is true is how someone concludes
+    // their file was audited (gh#949).
+    console.log(
+      changedOutsideRoots.length > 0
+        ? `✓ ui-audit --changed: nhánh này không đổi file .tsx/.jsx nào trong ` +
+            `[${SELF_SCAN_ROOTS.join(", ")}] (${changedOutsideRoots.length} file đổi ở ngoài đó).`
+        : "✓ ui-audit --changed: no .tsx/.jsx changed on this branch.",
+    );
   }
   process.exit(0);
 }
@@ -1899,6 +1989,19 @@ if (filesScanned === 0 && !changedNoFiles) {
     if (f.standard) console.log(`      ${C.dim}standard: ${f.standard}${C.reset}`);
     console.log(`      ${C.dim}${f.snippet}${C.reset}`);
   }
+  // Dưới `--changed`, NÓI RA base đã so. Một base sai không làm chương trình chết — nó cho ra một
+  // con số hợp lý, và đó là thứ duy nhất người đọc có thể dùng để nghi ngờ (gh#948).
+  if (CHANGED && changed?.base) {
+    console.log(`${C.dim}so với: ${changed.base}${C.reset}`);
+  }
+  // Bỏ file trong im lặng là cách một gate thu hẹp dần mà không ai thấy (cùng lý do với dòng
+  // `so với:` ngay trên). Nói ra số file và lãnh thổ đã dùng.
+  if (changedOutsideRoots.length > 0 && !quiet) {
+    console.log(
+      `${C.dim}ngoài lãnh thổ [${SELF_SCAN_ROOTS.join(", ")}], không quét: ` +
+        `${changedOutsideRoots.length} file${C.reset}`,
+    );
+  }
   console.log(
     `\ngodxjp-ui audit: ${C.red}${errors.length} error(s)${C.reset}, ${C.yellow}${warnings.length} warning(s)${C.reset}` +
       (scannedFiles.length > 0