@godxjp/ui 30.5.3 → 30.7.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.3.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 30.7.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.
@@ -47,7 +47,7 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
    filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
    copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
-1. `components-index.json` — 46 KB, all 173 components as name + group +
+1. `components-index.json` — 46 KB, all 175 components as name + group +
    tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
    names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
    `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
@@ -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.",

package/agent/components/Skeleton.json

@@ -38,10 +38,6 @@
     31
   ],
   "storyPath": "feedback/Skeleton.stories.tsx",
-  "subParts": [
-    "SkeletonDetail",
-    "SkeletonStat"
-  ],
   "tagline": "Base pulsing skeleton block, and the namespace the shaped presets hang off (Skeleton.Avatar / .Button / .Input / .Node / .Image / .Article).",
   "usage": [
     "DO use Skeleton for a custom block when SkeletonRows/Table/Stat/Article do not match the final layout.",

package/agent/components/SkeletonDetail.json

@@ -0,0 +1,31 @@
+{
+  "example": "import { SkeletonDetail } from \"@godxjp/ui/feedback\";\n\n<SkeletonDetail />",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "SkeletonDetail",
+  "props": [],
+  "related": [
+    "SkeletonStat — the same propless treatment for a KPI tile.",
+    "SkeletonRows — flat list lines, not label/value pairs.",
+    "SkeletonTable — tabular placeholder with a header band.",
+    "Skeleton — the bare block this preset is built from; reach for it when you need a shape this one does not draw.",
+    "Descriptions — the component this placeholder is standing in for."
+  ],
+  "rules": [
+    3,
+    31
+  ],
+  "storyPath": "feedback/Skeleton.stories.tsx",
+  "tagline": "Fixed-shape placeholder for a RECORD page — title, subtitle, then a bordered box of six label/value pairs. Takes no props: the shape IS the contract, so every detail screen loads identically.",
+  "usage": [
+    "DO use it while a single record's data resolves — a detail page, a drawer showing one entity, a Descriptions block.",
+    "DO leave it propless. It has no `rows` knob on purpose: a record page that loads with a different number of lines each time reads as a layout bug, and `Skeleton` is there for a bespoke shape.",
+    "DON'T use it for a list or a table — SkeletonRows draws flat lines, SkeletonTable draws a header band.",
+    "Import from `@godxjp/ui/feedback` (canonical). `@godxjp/ui/admin` re-exports it for admin pages."
+  ],
+  "useCases": [
+    "Detail page body before the record arrives",
+    "Drawer or sheet opened on a row while its full entity loads",
+    "Descriptions block placeholder"
+  ]
+}

package/agent/components/SkeletonStat.json

@@ -0,0 +1,30 @@
+{
+  "example": "import { SkeletonStat } from \"@godxjp/ui/feedback\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n<ResponsiveGrid columns={{ base: 1, sm: 2, lg: 4 }} gap=\"md\">\n  {Array.from({ length: 4 }).map((_, i) => (\n    <SkeletonStat key={i} />\n  ))}\n</ResponsiveGrid>",
+  "group": "feedback",
+  "importPath": "@godxjp/ui/feedback",
+  "name": "SkeletonStat",
+  "props": [],
+  "related": [
+    "StatCard — the loaded component this stands in for; match the grid, not just the size.",
+    "SkeletonDetail — the same propless treatment for a record page.",
+    "SkeletonRows — flat list lines.",
+    "Skeleton — the bare block this preset is built from."
+  ],
+  "rules": [
+    3,
+    31
+  ],
+  "storyPath": "feedback/Skeleton.stories.tsx",
+  "tagline": "Fixed-shape placeholder for ONE KPI tile — label, big value, caption. Takes no props, so a row of tiles loads at a uniform height and nothing reflows when the numbers arrive.",
+  "usage": [
+    "DO render one per StatCard while the figures load, inside the same grid the loaded tiles use.",
+    "DO leave it propless — it mirrors StatCard's three-line rhythm exactly, which is what stops the row jumping on hydration.",
+    "DON'T wrap it in a Card yourself if the loaded state uses StatCard; put it where the StatCard goes so the surface is identical.",
+    "Import from `@godxjp/ui/feedback` (canonical). `@godxjp/ui/admin` re-exports it for admin pages."
+  ],
+  "useCases": [
+    "Dashboard KPI row before the metrics query resolves",
+    "A single figure on a detail page loading separately from the record",
+    "Placeholder inside a ResponsiveGrid of StatCards"
+  ]
+}

package/agent/components-index.json

@@ -607,6 +607,16 @@
     "name": "Skeleton",
     "tagline": "Base pulsing skeleton block, and the namespace the shaped presets hang off (Skeleton.Avatar / .Button / .Input / .Node / .Image / .Article)."
   },
+  {
+    "group": "feedback",
+    "name": "SkeletonDetail",
+    "tagline": "Fixed-shape placeholder for a RECORD page — title, subtitle, then a bordered box of six label/value pairs. Takes no props: the shape IS the contract, so every detail screen loads identically."
+  },
+  {
+    "group": "feedback",
+    "name": "SkeletonStat",
+    "tagline": "Fixed-shape placeholder for ONE KPI tile — label, big value, caption. Takes no props, so a row of tiles loads at a uniform height and nothing reflows when the numbers arrive."
+  },
   {
     "group": "feedback",
     "name": "SkeletonArticle",

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.",
@@ -11474,10 +11480,6 @@
       31
     ],
     "storyPath": "feedback/Skeleton.stories.tsx",
-    "subParts": [
-      "SkeletonDetail",
-      "SkeletonStat"
-    ],
     "tagline": "Base pulsing skeleton block, and the namespace the shaped presets hang off (Skeleton.Avatar / .Button / .Input / .Node / .Image / .Article).",
     "usage": [
       "DO use Skeleton for a custom block when SkeletonRows/Table/Stat/Article do not match the final layout.",
@@ -11491,6 +11493,67 @@
       "Inline metadata placeholder"
     ]
   },
+  {
+    "example": "import { SkeletonDetail } from \"@godxjp/ui/feedback\";\n\n<SkeletonDetail />",
+    "group": "feedback",
+    "importPath": "@godxjp/ui/feedback",
+    "name": "SkeletonDetail",
+    "props": [],
+    "related": [
+      "SkeletonStat — the same propless treatment for a KPI tile.",
+      "SkeletonRows — flat list lines, not label/value pairs.",
+      "SkeletonTable — tabular placeholder with a header band.",
+      "Skeleton — the bare block this preset is built from; reach for it when you need a shape this one does not draw.",
+      "Descriptions — the component this placeholder is standing in for."
+    ],
+    "rules": [
+      3,
+      31
+    ],
+    "storyPath": "feedback/Skeleton.stories.tsx",
+    "tagline": "Fixed-shape placeholder for a RECORD page — title, subtitle, then a bordered box of six label/value pairs. Takes no props: the shape IS the contract, so every detail screen loads identically.",
+    "usage": [
+      "DO use it while a single record's data resolves — a detail page, a drawer showing one entity, a Descriptions block.",
+      "DO leave it propless. It has no `rows` knob on purpose: a record page that loads with a different number of lines each time reads as a layout bug, and `Skeleton` is there for a bespoke shape.",
+      "DON'T use it for a list or a table — SkeletonRows draws flat lines, SkeletonTable draws a header band.",
+      "Import from `@godxjp/ui/feedback` (canonical). `@godxjp/ui/admin` re-exports it for admin pages."
+    ],
+    "useCases": [
+      "Detail page body before the record arrives",
+      "Drawer or sheet opened on a row while its full entity loads",
+      "Descriptions block placeholder"
+    ]
+  },
+  {
+    "example": "import { SkeletonStat } from \"@godxjp/ui/feedback\";\nimport { ResponsiveGrid } from \"@godxjp/ui/layout\";\n\n<ResponsiveGrid columns={{ base: 1, sm: 2, lg: 4 }} gap=\"md\">\n  {Array.from({ length: 4 }).map((_, i) => (\n    <SkeletonStat key={i} />\n  ))}\n</ResponsiveGrid>",
+    "group": "feedback",
+    "importPath": "@godxjp/ui/feedback",
+    "name": "SkeletonStat",
+    "props": [],
+    "related": [
+      "StatCard — the loaded component this stands in for; match the grid, not just the size.",
+      "SkeletonDetail — the same propless treatment for a record page.",
+      "SkeletonRows — flat list lines.",
+      "Skeleton — the bare block this preset is built from."
+    ],
+    "rules": [
+      3,
+      31
+    ],
+    "storyPath": "feedback/Skeleton.stories.tsx",
+    "tagline": "Fixed-shape placeholder for ONE KPI tile — label, big value, caption. Takes no props, so a row of tiles loads at a uniform height and nothing reflows when the numbers arrive.",
+    "usage": [
+      "DO render one per StatCard while the figures load, inside the same grid the loaded tiles use.",
+      "DO leave it propless — it mirrors StatCard's three-line rhythm exactly, which is what stops the row jumping on hydration.",
+      "DON'T wrap it in a Card yourself if the loaded state uses StatCard; put it where the StatCard goes so the surface is identical.",
+      "Import from `@godxjp/ui/feedback` (canonical). `@godxjp/ui/admin` re-exports it for admin pages."
+    ],
+    "useCases": [
+      "Dashboard KPI row before the metrics query resolves",
+      "A single figure on a detail page loading separately from the record",
+      "Placeholder inside a ResponsiveGrid of StatCards"
+    ]
+  },
   {
     "example": "import { SkeletonArticle } from \"@godxjp/ui/feedback\";\n\n<SkeletonArticle avatar active paragraph={{ rows: 3 }} />",
     "group": "feedback",

package/agent/index.json

@@ -1,16 +1,16 @@
 {
   "counts": {
     "anti-ai-tells": 26,
-    "components": 173,
+    "components": 175,
     "patterns": 21,
     "rules": 50,
-    "tokens": 2073,
+    "tokens": 2074,
     "vocabulary": 14
   },
   "files": [
     {
       "file": "components-index.json",
-      "note": "46 KB — name + group + tagline for all 173. FETCH THIS FIRST, then fetch only the components you chose.",
+      "note": "46 KB — name + group + tagline for all 175. FETCH THIS FIRST, then fetch only the components you chose.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json"
     },
     {
@@ -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.3/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v30.7.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.3"
+  "version": "30.7.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.3.
+> A Japanese-enterprise React design system: 175 components, 2074 design tokens,
+> 50 cardinal rules. This file is the entry point for AI agents. Catalog version 30.7.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@30.5.3`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@30.7.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -15,10 +15,10 @@ that can only fetch URLs.
 ## Catalog
 
 - [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 21 whole-task patterns (name, tagline, tags). Start here when the task is a TASK — "build a settings page" — then fetch `patterns/<name>.json` for complete code.
-- [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-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 46 KB — all 175 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/&lt;Name&gt;.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.3/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v30.7.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;
@@ -60,4 +61,4 @@ export declare const RecordPicker: React.ForwardRefExoticComponent<Omit<React.Bu
     dialogTitle?: string;
     size?: "xs" | "sm" | "md" | "lg";
     "data-field"?: string;
-} & React.RefAttributes<HTMLButtonElement>>;
+} & 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,
@@ -71,6 +72,29 @@ const RecordPicker = React.forwardRef(
       () => 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) {
@@ -117,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];
@@ -125,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,
@@ -139,11 +313,14 @@ 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");
@@ -207,7 +384,7 @@ 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(Flex, { direction: "row", gap: "xs", align: "center", className: "ui-record-picker-row", children: [
+    autoOpen ? null : /* @__PURE__ */ jsxs(Flex, { direction: "row", gap: "xs", align: "center", className: "ui-record-picker-row", children: [
       /* @__PURE__ */ jsxs(
         Button,
         {
@@ -240,118 +417,128 @@ const DialogPicker = React.forwardRef(function DialogPicker2({
         }
       ) : null
     ] }),
-    /* @__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,
+    /* @__PURE__ */ jsx(
+      Dialog,
+      {
+        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,
               {
-                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(
+                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),
+                onClick: () => void load(query, filterValues, cursor),
                 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",
+            ) : 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,
               {
-                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
-    ] }) })
+                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.3",
+  "version": "30.7.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. */

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

@@ -846,3 +846,21 @@
     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/docs/FRAME-COVERAGE-REPORT.md

@@ -3,8 +3,8 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **173**
-- With ≥1 frame: **152** · zero-frame: **21**
+- Public components: **175**
+- With ≥1 frame: **152** · zero-frame: **23**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -22,6 +22,8 @@
 - [ ] `ServiceCatalogCta`
 - [ ] `SkeletonRows`
 - [ ] `OverlayPortalProvider`
+- [ ] `SkeletonDetail`
+- [ ] `SkeletonStat`
 - [ ] `SkeletonArticle`
 - [ ] `SkeletonAvatar`
 - [ ] `SkeletonButton`
@@ -154,6 +156,8 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | Avatar | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
 | Separator | ✓ | · | N/A | N/A | · | · | · | · | · | · |
 | Skeleton | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| SkeletonDetail | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
+| SkeletonStat | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
 | SkeletonArticle | **✗** | N/A | · | N/A | · | · | · | · | · | · |
 | SkeletonAvatar | **✗** | ✓ | N/A | N/A | · | · | · | · | · | · |
 | SkeletonButton | **✗** | ✓ | N/A | N/A | · | · | · | · | · | · |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "30.5.3",
-  "godxUiMcp": "30.5.3",
+  "version": "30.7.0",
+  "godxUiMcp": "30.7.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