@godxjp/ui 33.22.2 → 33.24.0

package/DESIGN.md

@@ -160,7 +160,7 @@ Each section is a Heading (plus one muted line if it adds a fact) over its conte
 
 ### Dashboard
 
-The only archetype with KPI tiles: at most four `StatCard`s, each with a comparison `delta` (use `inverse` when up is bad). Below, panels in `ResponsiveGrid`, each a Card with a title and one "view all" link: a work queue, a short table, a chart. Every number answers "compared to what".
+KPI tiles belong on pages whose job is monitoring — dashboards, report heads (a short count strip above a list or report is fine too). Keep the set small; around four `StatCard`s is a good default, not a limit. Give a tile a comparison `delta` when a meaningful baseline exists (previous period, target, plan), with `inverse` when up is bad; a count of work to do (pending, overdue, unread) instead links to the list already filtered to those items — never invent a comparison. Every tile states its label, unit, period and scope. Below, panels in `ResponsiveGrid`, each a Card with a title and one "view all" link: a work queue, a short table, a chart.
 
 ### Approval queue
 

package/README.md

@@ -18,7 +18,7 @@ npm i @godxjp/ui
 
 <!-- agent-catalog-counts:start -->
 
-The catalog — 210 components, 3184 tokens, 44 cardinal rules — is published in two forms from one
+The catalog — 212 components, 3198 tokens, 44 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
 <!-- agent-catalog-counts:end -->
 
@@ -53,10 +53,10 @@ static files straight from this public repo — no hosting, no deploy step:
 | [`agent/llms.txt`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/llms.txt) | 3 KB | the [llms.txt](https://llmstxt.org/) entry point |
 | [`agent/DESIGN.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md) | 18 KB | the visual spec: tokens, colour scarcity, admin screen anatomy, do/don't |
 | [`agent/index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json) | 3 KB | manifest: version, counts, every file's URL |
-| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 46 KB | all 210 as name + group + tagline — **fetch this first** |
+| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 47 KB | all 212 as name + group + tagline — **fetch this first** |
 | [`agent/components/<Name>.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json) | 1 KB–38 KB | one file per component, each with its `importPath` — **this is the route to take** |
-| [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.4 MB | all 210 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
-| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 1.4 MB | all 3184 design tokens, their values and why they exist |
+| [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.4 MB | all 212 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 1.4 MB | all 3198 design tokens, their values and why they exist |
 | [`agent/vocabulary.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json) | 7 KB | the controlled prop vocabulary |
 | [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 23 KB | the 44 cardinal rules |
 <!-- prettier-ignore-end -->

package/agent/DESIGN.md

@@ -160,7 +160,7 @@ Each section is a Heading (plus one muted line if it adds a fact) over its conte
 
 ### Dashboard
 
-The only archetype with KPI tiles: at most four `StatCard`s, each with a comparison `delta` (use `inverse` when up is bad). Below, panels in `ResponsiveGrid`, each a Card with a title and one "view all" link: a work queue, a short table, a chart. Every number answers "compared to what".
+KPI tiles belong on pages whose job is monitoring — dashboards, report heads (a short count strip above a list or report is fine too). Keep the set small; around four `StatCard`s is a good default, not a limit. Give a tile a comparison `delta` when a meaningful baseline exists (previous period, target, plan), with `inverse` when up is bad; a count of work to do (pending, overdue, unread) instead links to the list already filtered to those items — never invent a comparison. Every tile states its label, unit, period and scope. Below, panels in `ResponsiveGrid`, each a Card with a title and one "view all" link: a work queue, a short table, a chart.
 
 ### Approval queue
 

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` 33.22.2.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 33.24.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.
@@ -52,7 +52,7 @@ screen anatomy, the visual target the rules below do not give you. Then fetch in
    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 210 components as name + group +
+1. `components-index.json` — 47 KB, all 212 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
@@ -61,10 +61,10 @@ screen anatomy, the visual target the rules below do not give you. Then fetch in
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 44 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 3184 design tokens, each tagged with its `tier`. **If you were handed a
-   brand, read the 220 `foundation` entries first** — `--primary`, `--background`,
+4. `tokens.json` — 3198 design tokens, each tagged with its `tier`. **If you were handed a
+   brand, read the 223 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   2851 `component` entries are per-part knobs; reach for one only when a role is
+   2862 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 35 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.
@@ -148,9 +148,9 @@ has stopped following the brand.
 
 | `tier` | count | what it is | set it? |
 |---|---|---|---|
-| `foundation` | 220 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** The default `--primary` is a neutral placeholder: set it (`:root { --primary: <H> <S>% <L>%; }`, HSL components, no `hsl()` wrapper) or import a theme preset such as `@godxjp/ui/themes/godx.css` |
+| `foundation` | 223 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** The default `--primary` is a neutral placeholder: set it (`:root { --primary: <H> <S>% <L>%; }`, HSL components, no `hsl()` wrapper) or import a theme preset such as `@godxjp/ui/themes/godx.css` |
 | `semantic` | 113 | 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` | 2851 | 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` | 2862 | 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/AgentBadge.json

@@ -0,0 +1,43 @@
+{
+  "example": "import { AgentBadge, Avatar, AvatarFallback, AvatarImage } from \"@godxjp/ui/data-display\";\nimport { Text } from \"@godxjp/ui/general\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n<Flex align=\"center\" gap=\"sm\">\n  <Avatar kind=\"agent\">\n    <AvatarImage src={agent.avatarUrl} alt=\"\" />\n    <AvatarFallback>ハ</AvatarFallback>\n  </Avatar>\n  <Text>ハルカ</Text>\n  <AgentBadge />\n</Flex>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "AgentBadge",
+  "props": [
+    {
+      "defaultValue": "\"span\"",
+      "description": "Render element. `span` (default) because the label sits in a name's text line, often inside a link or a <button>.",
+      "name": "as",
+      "type": "\"div\" | \"span\""
+    },
+    {
+      "description": "Overrides the localized default label (`dataDisplay.avatar.agent`: ja \"AIエージェント\", en \"AI agent\", vi \"Tác tử AI\"). Omit it — the default follows the locale.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Extra classes on the label root.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Avatar — `kind=\"agent\"` puts the \"AI\" tag on the mark itself; use it everywhere an agent's mark appears, and add AgentBadge where its name is printed.",
+    "Badge — the general chip; AgentBadge is a fixed-meaning label built on the same chip geometry."
+  ],
+  "rules": [
+    35
+  ],
+  "storyPath": "data-display/avatar.tsx",
+  "tagline": "The \"AI agent\" label beside a NAME — violet outline on a transparent ground, pill, never wraps. The text-row half of telling an AI agent apart from a person; `Avatar kind=\"agent\"` is the mark half. A list that shows names uses BOTH; a place with only a mark (assignee icon column, dense cell) uses the Avatar alone.",
+  "usage": [
+    "DO put it right after the agent's name, in the same text line: `<Flex align=\"center\" gap=\"xs\"><Text>{name}</Text><AgentBadge /></Flex>`, and pair it with `<Avatar kind=\"agent\">` on the same row.",
+    "DO leave `children` empty so the label follows the locale; it is real text, so it is announced as written and never colour-only (WCAG 1.4.1).",
+    "DON'T hand-roll it as `<Badge variant=\"outline\" className=\"text-violet-600\">AI</Badge>` — the colour reads the `--agent` role through `--badge-agent-border` / `--badge-agent-foreground`, which a theme retunes once.",
+    "DON'T add it where there is no name (an icon-only column, a 24px cell) — there the Avatar's own AI tag is the marker."
+  ],
+  "useCases": [
+    "A member list, a people picker, an assignee dropdown option — any row that prints a principal's name.",
+    "A comment, an activity entry or a chat message authored by an AI agent."
+  ]
+}

package/agent/components/AppShell.json

@@ -25,6 +25,12 @@
       "required": true,
       "type": "ReactNode"
     },
+    {
+      "defaultValue": "true",
+      "description": "Page-level error boundary around `children` (gh#1494). A page that throws while rendering is replaced by an application ErrorSurface inside <main> (localized title + one Reload action); the sidebar, topbar and breadcrumb stay, so the user can navigate away. It resets when the URL changes, so the next visit — or Back — draws the page again. Pass PageErrorBoundary's props as an object to configure it, or `false` when the app already wraps pages in its own boundary.",
+      "name": "errorBoundary",
+      "type": "boolean | { fallback?; resetKey?; onError? }"
+    },
     {
       "description": "Full topbar override; else a rail is built from topbarLeft/topbarRight/logo. Omit ALL FOUR bar slots (topbar, topbarLeft, topbarRight, logo) and there is NO `<header class=\"app-topbar\">` in the DOM at all: the shell publishes `data-topbar=\"none\"` on its root and the bar's grid row collapses to zero, for a shell whose PAGE owns the top row. The one exception is the AppShell-owned drawer trigger — at or below 900px the header comes back carrying the hamburger alone, so navigation is never unreachable.",
       "name": "topbar",

package/agent/components/Avatar.json

@@ -32,6 +32,12 @@
       "name": "presenceLabel",
       "type": "string"
     },
+    {
+      "defaultValue": "\"person\"",
+      "description": "Who the mark stands for. `person` (inert default) emits no attribute and no node. `agent` marks an AI AGENT wherever a person could be mistaken for one — a member list, an assignee picker, a comment author: a white-on-violet \"AI\" pill at the TOP/inline-end corner, spilling slightly past the mark behind a --background ring (presence owns the bottom corner, so the two compose), legible at every size xs..lg, plus a localized sr-only \"AI agent\" (t(\"dataDisplay.avatar.agent\")), so the difference is never the colour alone (WCAG 1.4.1). Same two values as OrgChart `variant`. Retune with --avatar-agent-* (colour from the --agent role). Where the NAME is printed too, add `<AgentBadge />` beside it; where only the mark appears (icon column, dense cell), the Avatar alone.",
+      "name": "kind",
+      "type": "\"person\" | \"agent\""
+    },
     {
       "description": "Compose AvatarImage and AvatarFallback.",
       "name": "children",
@@ -59,6 +65,7 @@
   "tagline": "Avatar mark with image and fallback slots for users, teams, and entities.",
   "usage": [
     "DO compose Avatar > AvatarImage + AvatarFallback so broken or missing images still show a readable fallback.",
+    "DO mark an AI agent with `kind=\"agent\"` everywhere its mark appears. A list that shows NAMES uses BOTH `<Avatar kind=\"agent\">` and `<AgentBadge />` beside the name; a place with only the mark (an assignee icon column, a dense 24px cell) uses the Avatar alone — its AI tag is the marker there.",
     "DO pass `fit=\"contain\"` on AvatarImage for a logo or app icon that is wide, transparent or off-centre — the default `cover` crops to fill, right for a face (gh#1176). A full-bleed square icon (the GoDX service icon set) keeps the default.",
     "DO use `presence` for who is reachable RIGHT NOW — a chat member list, a DM row, a message-stream author, the topbar account mark. It is the only supported way to put a status dot on an avatar: the dot's inset is a function of the mark's own --avatar-* radius/size and of the root's clip, neither of which a page can read, which is why the hand-rolled `<span className=\"relative\"><Avatar/><span className=\"absolute -end-0.5 -bottom-0.5 size-2.5 rounded-full bg-green-500 ring-2 ring-background\"/></span>` wrapper can never be got right from outside (and fails the DS audit on the raw palette).",
     "DON'T announce a presence CHANGE from the avatar — it carries no aria-live on purpose. A roster of 40 marks resyncing over a socket would flood a screen reader; announce the change in the consumer's own live region if the product wants it.",

package/agent/components/PageContainer.json

@@ -45,6 +45,11 @@
       "name": "extra",
       "type": "ReactNode | { start?: ReactNode; end?: ReactNode }"
     },
+    {
+      "description": "The page's Help control (gh#1494) — a ghost Button opening a help Sheet, or a link to the manual. ONE fixed place on every page: the last item at the header row's inline end, after the `extra` actions, and still flush with that end when the actions wrap or are absent (measured 1440/768/390, 0/1/5 actions). A page passing only `help` still renders a header. Do not put Help in `extra`, in the body, or in a second header band.",
+      "name": "help",
+      "type": "ReactNode"
+    },
     {
       "description": "FIXED chrome band between the page header and the body — a filter strip, a status bar, a \"channel workflow\" rail. It is a SIBLING of the body, not content inside it: with `fill` the body is the scroll viewport, so the band is `flex: none` OUTSIDE the scroller and never scrolls away or gets slid under. Shares the page gutters and the `measure` cap with the header and the body (the three bands line up on both edges), goes full-bleed under variant=\"flush\" (wrap padded strips in PageContainer.Inset), and renders NOTHING when omitted — no wrapper, no gap. Its BOX sits FLUSH against the header above and the body below (chrome is attached, not a third page section floating between two voids, so the band cancels the container gap from itself), and by default its inset gives the band's CONTENT that gap back: a plain filter strip (a Segmented, a row of filters) sits one band gap from the header and from the body (gh#1323 — it used to touch both, 0px). A theme that paints or rules the band sets a tighter inset with `--page-toolbar-pad-block`.",
       "name": "toolbar",

package/agent/components/PageErrorBoundary.json

@@ -0,0 +1,48 @@
+{
+  "example": "import { AppShell, PageErrorBoundary } from \"@godxjp/ui/layout\";\n\n// Inside AppShell nothing is needed: a throwing page keeps the shell.\n<AppShell sidebar={sidebar} topbar={topbar} errorBoundary={{ onError: report }}>\n  {page}\n</AppShell>;\n\n// Outside AppShell, wrap the page yourself.\n<PageErrorBoundary onError={report}>{page}</PageErrorBoundary>;",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "PageErrorBoundary",
+  "props": [
+    {
+      "description": "The page.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "description": "What replaces the page that threw. Default: <ErrorSurface mode=\"application\" status={500} titleLevel={1}> with the kit's localized title/description and ONE 'Reload page' action. The function form gets the error and a `reset()` that draws the page again without a reload.",
+      "name": "fallback",
+      "type": "ReactNode | ({ error, reset }) => ReactNode"
+    },
+    {
+      "description": "Draw the page again when this value changes (Object.is). The boundary ALREADY resets when the URL changes — it records the URL it failed on and resets on the next render under a different one, so it needs no router integration; pass a key only for a change the URL does not show.",
+      "name": "resetKey",
+      "type": "unknown"
+    },
+    {
+      "description": "Report the error (an error tracker). Replaces the development-time console.error.",
+      "name": "onError",
+      "type": "(error: unknown, info: React.ErrorInfo) => void"
+    }
+  ],
+  "related": [
+    "AppShell — wraps its children in a PageErrorBoundary by default (`errorBoundary`).",
+    "ErrorSurface — the default fallback; use it directly for an HTTP 400/403/404/500/503 page the server reports."
+  ],
+  "rules": [
+    23,
+    24
+  ],
+  "storyPath": "layout/page-error-boundary.tsx",
+  "tagline": "Page-level React error boundary (gh#1494): a page that throws while rendering is replaced by an application ErrorSurface and the shell around it stays. AppShell wraps its children in one by default; use this directly only around a page outside AppShell.",
+  "usage": [
+    "DO rely on AppShell's built-in boundary: every page inside AppShell is already covered. Configure it with AppShell `errorBoundary={{ onError: report }}`.",
+    "DO wrap a page that renders OUTSIDE AppShell (a CenteredShell page, an embedded view) in <PageErrorBoundary> yourself.",
+    "DO NOT wrap every Card in a boundary: it is PAGE-level. An in-page query failure is DataState / Alert.QueryError, not a render error.",
+    "DO NOT key the boundary on the URL yourself to make it reset — it already resets on navigation."
+  ],
+  "useCases": [
+    "A list page whose row renderer hits an unexpected null: the page area shows the ErrorSurface, the sidebar still works, and navigating to another page draws that page normally.",
+    "Error reporting: <AppShell errorBoundary={{ onError: (error) => Sentry.captureException(error) }} …>."
+  ]
+}

package/agent/components/Toaster.json

@@ -17,7 +17,7 @@
     },
     {
       "defaultValue": "true",
-      "description": "Draw every visible toast whole, stacked with a gap. Default `true` (gh#1387): Sonner's collapsed deck (`expand={false}`) keeps earlier toasts as cards peeking behind the front one with their text hidden, which reads as an empty box. Pass `expand={false}` to opt back into the deck.",
+      "description": "Draw every visible toast whole, stacked with a gap. Default `true` (gh#1387): Sonner's collapsed deck (`expand={false}`) keeps earlier toasts as cards peeking behind the front one with their text hidden, which reads as an empty box. Pass `expand={false}` to opt back into the deck. While a MODAL Dialog or Sheet is open the toaster takes no pointer events (gh#1477): a toast drawn over the modal's footer stays visible and announced, and the click reaches the footer action — do not work around an overlap with `expand={false}`.",
       "name": "expand",
       "type": "boolean"
     },

package/agent/components/Toolbar.json

@@ -34,7 +34,7 @@
       "type": "FilterBarSearchProp"
     },
     {
-      "description": "Typed model — labelled domain-neutral Select filters rendered after the search slot in array order. Each: { value (stable identity), label (rendered as the control's REAL <label htmlFor> — WCAG 2.5.3), options, selected/defaultSelected/onSelectedChange, placeholder, disabled }. Width is token-owned (--filter-bar-filter-width).",
+      "description": "Typed model — labelled domain-neutral Select filters rendered after the search slot in array order. Each: { value (stable identity), label (rendered as the control's REAL <label htmlFor> — WCAG 2.5.3), options, selected/defaultSelected/onSelectedChange, placeholder, disabled, required, allowClear }. Width is token-owned (--filter-bar-filter-width). A filter shows a ✕ by default (no filter is its resting state); a SCOPE filter that is never empty (branch, month) passes `required` — no ✕ and `aria-required` on the control — and `allowClear: false` hides the ✕ alone (gh#1495). Never rebuild a filter by hand on the bar's internal class to drop the ✕.",
       "name": "filters",
       "type": "FilterBarFilterProp[]"
     },

package/agent/components/Topbar.json

@@ -39,7 +39,7 @@
     },
     {
       "defaultValue": "\"scroll\"",
-      "description": "What a bar that does not fit does with the cells that do not fit (gh#728). scroll (default) lets the BAR scroll on the inline axis while the start and end clusters keep their cells whole — every cell stays in the DOM and in the accessibility tree, Tab reaches each one in order, and the browser scrolls a focused cell into view; the scrollbar is suppressed (a horizontal bar inside a 48px chrome row would eat the height that caused the deficit), so the pointer affordance is drag/wheel. clip is the pre-gh#728 behaviour: a cell past the cluster's edge is simply not painted — still focusable, still announced, invisible and unreachable by pointer. Independent of TopbarItem hideBelow, which REMOVES a cell at a step; this is only about what happens once there is no budget left.",
+      "description": "What a bar that does not fit does with the cells that do not fit (gh#728). scroll (default) lets the BAR scroll on the inline axis while the start and end clusters keep their cells whole — every cell stays in the DOM and in the accessibility tree, Tab reaches each one in order, and the browser scrolls a focused cell into view; the scrollbar is suppressed (a horizontal bar inside a 48px chrome row would eat the height that caused the deficit), so the pointer affordance is drag/wheel. clip is the pre-gh#728 behaviour: a cell past the cluster's edge is simply not painted — still focusable, still announced, invisible and unreachable by pointer. Independent of TopbarItem hideBelow, which REMOVES a cell at a step; this is only about what happens once there is no budget left. menu (gh#914) folds every cluster into ONE \"more\" cell when the bar does not fit; folding MOVES the controls (into the open menu, or a hidden holder while it is closed) and never unmounts them, so a CommandPalette in `start` keeps its ⌘K shortcut and a control keeps its state across folds (gh#1478).",
       "name": "overflow",
       "type": "\"scroll\" | \"clip\" | \"menu\""
     },

package/agent/components-index.json

@@ -329,6 +329,11 @@
     "name": "ErrorSurface",
     "tagline": "Package-owned semantic exception surface for 400 / 403 / 404 / 500 / 503."
   },
+  {
+    "group": "layout",
+    "name": "PageErrorBoundary",
+    "tagline": "Page-level React error boundary (gh#1494): a page that throws while rendering is replaced by an application ErrorSurface and the shell around it stays."
+  },
   {
     "group": "layout",
     "name": "LegalDocumentShell",
@@ -437,6 +442,11 @@
     "name": "Badge",
     "tagline": "Plain or lifecycle badge."
   },
+  {
+    "group": "data-display",
+    "name": "AgentBadge",
+    "tagline": "The \"AI agent\" label beside a NAME — violet outline on a transparent ground, pill, never wraps."
+  },
   {
     "group": "data-display",
     "name": "Legend",

package/agent/components.json

@@ -692,6 +692,11 @@
         "name": "extra",
         "type": "ReactNode | { start?: ReactNode; end?: ReactNode }"
       },
+      {
+        "description": "The page's Help control (gh#1494) — a ghost Button opening a help Sheet, or a link to the manual. ONE fixed place on every page: the last item at the header row's inline end, after the `extra` actions, and still flush with that end when the actions wrap or are absent (measured 1440/768/390, 0/1/5 actions). A page passing only `help` still renders a header. Do not put Help in `extra`, in the body, or in a second header band.",
+        "name": "help",
+        "type": "ReactNode"
+      },
       {
         "description": "FIXED chrome band between the page header and the body — a filter strip, a status bar, a \"channel workflow\" rail. It is a SIBLING of the body, not content inside it: with `fill` the body is the scroll viewport, so the band is `flex: none` OUTSIDE the scroller and never scrolls away or gets slid under. Shares the page gutters and the `measure` cap with the header and the body (the three bands line up on both edges), goes full-bleed under variant=\"flush\" (wrap padded strips in PageContainer.Inset), and renders NOTHING when omitted — no wrapper, no gap. Its BOX sits FLUSH against the header above and the body below (chrome is attached, not a third page section floating between two voids, so the band cancels the container gap from itself), and by default its inset gives the band's CONTENT that gap back: a plain filter strip (a Segmented, a row of filters) sits one band gap from the header and from the body (gh#1323 — it used to touch both, 0px). A theme that paints or rules the band sets a tighter inset with `--page-toolbar-pad-block`.",
         "name": "toolbar",
@@ -3244,6 +3249,12 @@
         "required": true,
         "type": "ReactNode"
       },
+      {
+        "defaultValue": "true",
+        "description": "Page-level error boundary around `children` (gh#1494). A page that throws while rendering is replaced by an application ErrorSurface inside <main> (localized title + one Reload action); the sidebar, topbar and breadcrumb stay, so the user can navigate away. It resets when the URL changes, so the next visit — or Back — draws the page again. Pass PageErrorBoundary's props as an object to configure it, or `false` when the app already wraps pages in its own boundary.",
+        "name": "errorBoundary",
+        "type": "boolean | { fallback?; resetKey?; onError? }"
+      },
       {
         "description": "Full topbar override; else a rail is built from topbarLeft/topbarRight/logo. Omit ALL FOUR bar slots (topbar, topbarLeft, topbarRight, logo) and there is NO `<header class=\"app-topbar\">` in the DOM at all: the shell publishes `data-topbar=\"none\"` on its root and the bar's grid row collapses to zero, for a shell whose PAGE owns the top row. The one exception is the AppShell-owned drawer trigger — at or below 900px the header comes back carrying the hamburger alone, so navigation is never unreachable.",
         "name": "topbar",
@@ -3767,7 +3778,7 @@
       },
       {
         "defaultValue": "\"scroll\"",
-        "description": "What a bar that does not fit does with the cells that do not fit (gh#728). scroll (default) lets the BAR scroll on the inline axis while the start and end clusters keep their cells whole — every cell stays in the DOM and in the accessibility tree, Tab reaches each one in order, and the browser scrolls a focused cell into view; the scrollbar is suppressed (a horizontal bar inside a 48px chrome row would eat the height that caused the deficit), so the pointer affordance is drag/wheel. clip is the pre-gh#728 behaviour: a cell past the cluster's edge is simply not painted — still focusable, still announced, invisible and unreachable by pointer. Independent of TopbarItem hideBelow, which REMOVES a cell at a step; this is only about what happens once there is no budget left.",
+        "description": "What a bar that does not fit does with the cells that do not fit (gh#728). scroll (default) lets the BAR scroll on the inline axis while the start and end clusters keep their cells whole — every cell stays in the DOM and in the accessibility tree, Tab reaches each one in order, and the browser scrolls a focused cell into view; the scrollbar is suppressed (a horizontal bar inside a 48px chrome row would eat the height that caused the deficit), so the pointer affordance is drag/wheel. clip is the pre-gh#728 behaviour: a cell past the cluster's edge is simply not painted — still focusable, still announced, invisible and unreachable by pointer. Independent of TopbarItem hideBelow, which REMOVES a cell at a step; this is only about what happens once there is no budget left. menu (gh#914) folds every cluster into ONE \"more\" cell when the bar does not fit; folding MOVES the controls (into the open menu, or a hidden holder while it is closed) and never unmounts them, so a CommandPalette in `start` keeps its ⌘K shortcut and a control keeps its state across folds (gh#1478).",
         "name": "overflow",
         "type": "\"scroll\" | \"clip\" | \"menu\""
       },
@@ -4426,6 +4437,54 @@
       "Unexpected failure with a support correlation id: <ErrorSurface mode=\"system\" status={500} requestId=\"01J9Z0…\" action={<Button onClick={reload}>Reload</Button>} />."
     ]
   },
+  {
+    "example": "import { AppShell, PageErrorBoundary } from \"@godxjp/ui/layout\";\n\n// Inside AppShell nothing is needed: a throwing page keeps the shell.\n<AppShell sidebar={sidebar} topbar={topbar} errorBoundary={{ onError: report }}>\n  {page}\n</AppShell>;\n\n// Outside AppShell, wrap the page yourself.\n<PageErrorBoundary onError={report}>{page}</PageErrorBoundary>;",
+    "group": "layout",
+    "importPath": "@godxjp/ui/layout",
+    "name": "PageErrorBoundary",
+    "props": [
+      {
+        "description": "The page.",
+        "name": "children",
+        "type": "ReactNode"
+      },
+      {
+        "description": "What replaces the page that threw. Default: <ErrorSurface mode=\"application\" status={500} titleLevel={1}> with the kit's localized title/description and ONE 'Reload page' action. The function form gets the error and a `reset()` that draws the page again without a reload.",
+        "name": "fallback",
+        "type": "ReactNode | ({ error, reset }) => ReactNode"
+      },
+      {
+        "description": "Draw the page again when this value changes (Object.is). The boundary ALREADY resets when the URL changes — it records the URL it failed on and resets on the next render under a different one, so it needs no router integration; pass a key only for a change the URL does not show.",
+        "name": "resetKey",
+        "type": "unknown"
+      },
+      {
+        "description": "Report the error (an error tracker). Replaces the development-time console.error.",
+        "name": "onError",
+        "type": "(error: unknown, info: React.ErrorInfo) => void"
+      }
+    ],
+    "related": [
+      "AppShell — wraps its children in a PageErrorBoundary by default (`errorBoundary`).",
+      "ErrorSurface — the default fallback; use it directly for an HTTP 400/403/404/500/503 page the server reports."
+    ],
+    "rules": [
+      23,
+      24
+    ],
+    "storyPath": "layout/page-error-boundary.tsx",
+    "tagline": "Page-level React error boundary (gh#1494): a page that throws while rendering is replaced by an application ErrorSurface and the shell around it stays. AppShell wraps its children in one by default; use this directly only around a page outside AppShell.",
+    "usage": [
+      "DO rely on AppShell's built-in boundary: every page inside AppShell is already covered. Configure it with AppShell `errorBoundary={{ onError: report }}`.",
+      "DO wrap a page that renders OUTSIDE AppShell (a CenteredShell page, an embedded view) in <PageErrorBoundary> yourself.",
+      "DO NOT wrap every Card in a boundary: it is PAGE-level. An in-page query failure is DataState / Alert.QueryError, not a render error.",
+      "DO NOT key the boundary on the URL yourself to make it reset — it already resets on navigation."
+    ],
+    "useCases": [
+      "A list page whose row renderer hits an unexpected null: the page area shows the ErrorSurface, the sidebar still works, and navigating to another page draws that page normally.",
+      "Error reporting: <AppShell errorBoundary={{ onError: (error) => Sentry.captureException(error) }} …>."
+    ]
+  },
   {
     "example": "import { CenteredShell, Flex, Topbar } from \"@godxjp/ui/layout\";\nimport { LegalDocumentShell } from \"@godxjp/ui/lab\";\nimport { Button, Text } from \"@godxjp/ui/general\";\nimport { useState } from \"react\";\n\nexport function TermsPage() {\n  const [activeSection, setActiveSection] = useState(\"acceptance\");\n\n  return (\n    <CenteredShell width=\"lg\" topbar={<Topbar start={<Brand />} />}>\n      <LegalDocumentShell\n        title=\"利用規約\"\n        version=\"2.4\"\n        effectiveDate=\"2026-04-01\"\n        summary=\"本規約は、当社が提供するサービスの利用条件を定めるものです。\"\n        contentsLabel=\"目次\"\n        activeSection={activeSection}\n        onActiveSectionChange={setActiveSection}\n        sections={[\n          { id: \"acceptance\", title: \"第1条(本規約への同意)\", content: <Text as=\"p\">…</Text> },\n          { id: \"accounts\", title: \"第2条(アカウントの管理)\", content: <Text as=\"p\">…</Text> },\n        ]}\n        documentNavigation={\n          <Flex direction=\"col\" gap=\"xs\" role=\"group\" aria-label=\"法的文書\">\n            <Button variant=\"secondary\" size=\"sm\" fullWidth aria-current=\"page\">利用規約</Button>\n            <Button variant=\"ghost\" size=\"sm\" fullWidth>プライバシーポリシー</Button>\n          </Flex>\n        }\n        footerAction={<Button size=\"sm\">同意する</Button>}\n      />\n    </CenteredShell>\n  );\n}",
     "group": "layout",
@@ -6195,6 +6254,49 @@
       "A status or category an administrator coloured themselves, in an issue tracker or a CRM — `<Badge shape=\"pill\" color={status.color}>{status.name}</Badge>`. The colour comes out of a picker and is stored on the row, so it cannot be mapped to a tone."
     ]
   },
+  {
+    "example": "import { AgentBadge, Avatar, AvatarFallback, AvatarImage } from \"@godxjp/ui/data-display\";\nimport { Text } from \"@godxjp/ui/general\";\nimport { Flex } from \"@godxjp/ui/layout\";\n\n<Flex align=\"center\" gap=\"sm\">\n  <Avatar kind=\"agent\">\n    <AvatarImage src={agent.avatarUrl} alt=\"\" />\n    <AvatarFallback>ハ</AvatarFallback>\n  </Avatar>\n  <Text>ハルカ</Text>\n  <AgentBadge />\n</Flex>",
+    "group": "data-display",
+    "importPath": "@godxjp/ui/data-display",
+    "name": "AgentBadge",
+    "props": [
+      {
+        "defaultValue": "\"span\"",
+        "description": "Render element. `span` (default) because the label sits in a name's text line, often inside a link or a <button>.",
+        "name": "as",
+        "type": "\"div\" | \"span\""
+      },
+      {
+        "description": "Overrides the localized default label (`dataDisplay.avatar.agent`: ja \"AIエージェント\", en \"AI agent\", vi \"Tác tử AI\"). Omit it — the default follows the locale.",
+        "name": "children",
+        "type": "ReactNode"
+      },
+      {
+        "description": "Extra classes on the label root.",
+        "name": "className",
+        "type": "string"
+      }
+    ],
+    "related": [
+      "Avatar — `kind=\"agent\"` puts the \"AI\" tag on the mark itself; use it everywhere an agent's mark appears, and add AgentBadge where its name is printed.",
+      "Badge — the general chip; AgentBadge is a fixed-meaning label built on the same chip geometry."
+    ],
+    "rules": [
+      35
+    ],
+    "storyPath": "data-display/avatar.tsx",
+    "tagline": "The \"AI agent\" label beside a NAME — violet outline on a transparent ground, pill, never wraps. The text-row half of telling an AI agent apart from a person; `Avatar kind=\"agent\"` is the mark half. A list that shows names uses BOTH; a place with only a mark (assignee icon column, dense cell) uses the Avatar alone.",
+    "usage": [
+      "DO put it right after the agent's name, in the same text line: `<Flex align=\"center\" gap=\"xs\"><Text>{name}</Text><AgentBadge /></Flex>`, and pair it with `<Avatar kind=\"agent\">` on the same row.",
+      "DO leave `children` empty so the label follows the locale; it is real text, so it is announced as written and never colour-only (WCAG 1.4.1).",
+      "DON'T hand-roll it as `<Badge variant=\"outline\" className=\"text-violet-600\">AI</Badge>` — the colour reads the `--agent` role through `--badge-agent-border` / `--badge-agent-foreground`, which a theme retunes once.",
+      "DON'T add it where there is no name (an icon-only column, a 24px cell) — there the Avatar's own AI tag is the marker."
+    ],
+    "useCases": [
+      "A member list, a people picker, an assignee dropdown option — any row that prints a principal's name.",
+      "A comment, an activity entry or a chat message authored by an AI agent."
+    ]
+  },
   {
     "example": "import { Legend } from \"@godxjp/ui/data-display\";\n\n<CardAction>\n  <Legend\n    items={[\n      { tone: \"destructive\", label: \"期限超過\" },\n      { tone: \"warning\", label: \"期限間近\" },\n      { tone: \"success\", label: \"対応済\" },\n    ]}\n  />\n</CardAction>",
     "group": "data-display",
@@ -10578,7 +10680,7 @@
       },
       {
         "defaultValue": "true",
-        "description": "Draw every visible toast whole, stacked with a gap. Default `true` (gh#1387): Sonner's collapsed deck (`expand={false}`) keeps earlier toasts as cards peeking behind the front one with their text hidden, which reads as an empty box. Pass `expand={false}` to opt back into the deck.",
+        "description": "Draw every visible toast whole, stacked with a gap. Default `true` (gh#1387): Sonner's collapsed deck (`expand={false}`) keeps earlier toasts as cards peeking behind the front one with their text hidden, which reads as an empty box. Pass `expand={false}` to opt back into the deck. While a MODAL Dialog or Sheet is open the toaster takes no pointer events (gh#1477): a toast drawn over the modal's footer stays visible and announced, and the click reaches the footer action — do not work around an overlap with `expand={false}`.",
         "name": "expand",
         "type": "boolean"
       },
@@ -11174,7 +11276,7 @@
         "type": "FilterBarSearchProp"
       },
       {
-        "description": "Typed model — labelled domain-neutral Select filters rendered after the search slot in array order. Each: { value (stable identity), label (rendered as the control's REAL <label htmlFor> — WCAG 2.5.3), options, selected/defaultSelected/onSelectedChange, placeholder, disabled }. Width is token-owned (--filter-bar-filter-width).",
+        "description": "Typed model — labelled domain-neutral Select filters rendered after the search slot in array order. Each: { value (stable identity), label (rendered as the control's REAL <label htmlFor> — WCAG 2.5.3), options, selected/defaultSelected/onSelectedChange, placeholder, disabled, required, allowClear }. Width is token-owned (--filter-bar-filter-width). A filter shows a ✕ by default (no filter is its resting state); a SCOPE filter that is never empty (branch, month) passes `required` — no ✕ and `aria-required` on the control — and `allowClear: false` hides the ✕ alone (gh#1495). Never rebuild a filter by hand on the bar's internal class to drop the ✕.",
         "name": "filters",
         "type": "FilterBarFilterProp[]"
       },
@@ -14378,6 +14480,12 @@
         "name": "presenceLabel",
         "type": "string"
       },
+      {
+        "defaultValue": "\"person\"",
+        "description": "Who the mark stands for. `person` (inert default) emits no attribute and no node. `agent` marks an AI AGENT wherever a person could be mistaken for one — a member list, an assignee picker, a comment author: a white-on-violet \"AI\" pill at the TOP/inline-end corner, spilling slightly past the mark behind a --background ring (presence owns the bottom corner, so the two compose), legible at every size xs..lg, plus a localized sr-only \"AI agent\" (t(\"dataDisplay.avatar.agent\")), so the difference is never the colour alone (WCAG 1.4.1). Same two values as OrgChart `variant`. Retune with --avatar-agent-* (colour from the --agent role). Where the NAME is printed too, add `<AgentBadge />` beside it; where only the mark appears (icon column, dense cell), the Avatar alone.",
+        "name": "kind",
+        "type": "\"person\" | \"agent\""
+      },
       {
         "description": "Compose AvatarImage and AvatarFallback.",
         "name": "children",
@@ -14405,6 +14513,7 @@
     "tagline": "Avatar mark with image and fallback slots for users, teams, and entities.",
     "usage": [
       "DO compose Avatar > AvatarImage + AvatarFallback so broken or missing images still show a readable fallback.",
+      "DO mark an AI agent with `kind=\"agent\"` everywhere its mark appears. A list that shows NAMES uses BOTH `<Avatar kind=\"agent\">` and `<AgentBadge />` beside the name; a place with only the mark (an assignee icon column, a dense 24px cell) uses the Avatar alone — its AI tag is the marker there.",
       "DO pass `fit=\"contain\"` on AvatarImage for a logo or app icon that is wide, transparent or off-centre — the default `cover` crops to fill, right for a face (gh#1176). A full-bleed square icon (the GoDX service icon set) keeps the default.",
       "DO use `presence` for who is reachable RIGHT NOW — a chat member list, a DM row, a message-stream author, the topbar account mark. It is the only supported way to put a status dot on an avatar: the dot's inset is a function of the mark's own --avatar-* radius/size and of the root's clip, neither of which a page can read, which is why the hand-rolled `<span className=\"relative\"><Avatar/><span className=\"absolute -end-0.5 -bottom-0.5 size-2.5 rounded-full bg-green-500 ring-2 ring-background\"/></span>` wrapper can never be got right from outside (and fails the DS audit on the raw palette).",
       "DON'T announce a presence CHANGE from the avatar — it carries no aria-live on purpose. A roster of 40 marks resyncing over a socket would flood a screen reader; announce the change in the consumer's own live region if the product wants it.",

package/agent/index.json

@@ -1,10 +1,10 @@
 {
   "counts": {
     "anti-ai-tells": 35,
-    "components": 210,
+    "components": 212,
     "patterns": 28,
     "rules": 44,
-    "tokens": 3184,
+    "tokens": 3198,
     "vocabulary": 16
   },
   "design": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md",
@@ -16,7 +16,7 @@
     },
     {
       "file": "components-index.json",
-      "note": "46 KB — name + group + tagline for all 210. FETCH THIS FIRST, then fetch only the components you chose.",
+      "note": "47 KB — name + group + tagline for all 212. FETCH THIS FIRST, then fetch only the components you chose.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json"
     },
     {
@@ -54,19 +54,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/v33.22.2/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.24.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": 2851,
-      "foundation": 220,
+      "component": 2862,
+      "foundation": 223,
       "semantic": 113
     },
     "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": "33.22.2"
+  "version": "33.24.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 210 components, 3184 design tokens,
-> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.22.2.
+> A Japanese-enterprise React design system: 212 components, 3198 design tokens,
+> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.24.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@33.22.2`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@33.24.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -16,10 +16,10 @@ that can only fetch URLs.
 ## Catalog
 
 - [patterns-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/patterns-index.json): 28 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 210 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): 47 KB — all 212 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–38 KB, median 5 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.4 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` — 220 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 2851 `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` — 223 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 2862 `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): 44 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 35 shapes that make generated UI look generated, each with its fix.
@@ -27,7 +27,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/v33.22.2/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v33.24.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.