@godxjp/ui 33.22.2 → 33.24.0

package/dist/components/layout/page-error-boundary.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+import type { PageErrorBoundaryProp } from "../../props/components/layout.prop.js";
+export type { PageErrorBoundaryFallbackProp, PageErrorBoundaryProp, PageErrorBoundaryProp as PageErrorBoundaryProps, } from "../../props/components/layout.prop.js";
+type BoundaryState = {
+    error: unknown;
+    failedAt: string | undefined;
+} | null;
+/**
+ * PageErrorBoundary — catches a render error thrown by ONE page and draws the failure in its
+ * place, so the shell around it (sidebar, topbar, breadcrumb) stays up and the user can go
+ * somewhere else (gh#1494). `AppShell` wraps its `children` in one by default.
+ *
+ * It RESETS ON NAVIGATION without knowing the router: a failed boundary records the URL it failed
+ * on, and the next render under a different URL (the router re-renders the shell's children on
+ * every visit) draws the page again. `resetKey` is the explicit form, for a change the URL does
+ * not show. Without a reset, Back through history stayed on the error surface — the symptom a
+ * consumer measured before it wrote its own boundary.
+ */
+export declare class PageErrorBoundary extends React.Component<PageErrorBoundaryProp, {
+    failure: BoundaryState;
+}> {
+    state: {
+        failure: BoundaryState;
+    };
+    static getDerivedStateFromError(error: unknown): {
+        failure: BoundaryState;
+    };
+    componentDidCatch(error: unknown, info: React.ErrorInfo): void;
+    componentDidUpdate(previous: PageErrorBoundaryProp): void;
+    reset: () => void;
+    render(): React.ReactNode;
+}

package/dist/components/layout/page-error-boundary.js

@@ -0,0 +1,57 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { isDevelopment } from "../../lib/dev.js";
+import { Button } from "../general/button.js";
+import { ErrorSurface } from "./error-surface.js";
+function DefaultPageErrorFallback() {
+  const { t } = useTranslation();
+  return /* @__PURE__ */ jsx(
+    ErrorSurface,
+    {
+      mode: "application",
+      status: 500,
+      titleLevel: 1,
+      title: t("layout.pageErrorBoundary.title"),
+      description: t("layout.pageErrorBoundary.description"),
+      action: /* @__PURE__ */ jsx(Button, { type: "button", onClick: () => window.location.reload(), children: t("layout.pageErrorBoundary.reload") })
+    }
+  );
+}
+const currentLocation = () => typeof window === "undefined" ? void 0 : window.location.href;
+class PageErrorBoundary extends React.Component {
+  state = { failure: null };
+  static getDerivedStateFromError(error) {
+    return { failure: { error, failedAt: currentLocation() } };
+  }
+  componentDidCatch(error, info) {
+    if (this.props.onError) {
+      this.props.onError(error, info);
+    } else if (isDevelopment()) {
+      console.error("[@godxjp/ui] PageErrorBoundary caught a page render error:", error);
+    }
+  }
+  componentDidUpdate(previous) {
+    const { failure } = this.state;
+    if (!failure) return;
+    const keyChanged = !Object.is(previous.resetKey, this.props.resetKey);
+    const moved = failure.failedAt !== void 0 && failure.failedAt !== currentLocation();
+    if (keyChanged || moved) this.reset();
+  }
+  reset = () => {
+    this.setState({ failure: null });
+  };
+  render() {
+    const { failure } = this.state;
+    if (!failure) return this.props.children;
+    const { fallback } = this.props;
+    if (typeof fallback === "function")
+      return fallback({ error: failure.error, reset: this.reset });
+    if (fallback !== void 0) return fallback;
+    return /* @__PURE__ */ jsx(DefaultPageErrorFallback, {});
+  }
+}
+export {
+  PageErrorBoundary
+};

package/dist/components/layout/sidebar.d.ts

@@ -41,7 +41,7 @@ type RowProps = {
  * only within `src/components/layout`) so `NavList` renders nested items through the SAME group as
  * the rail instead of dropping `item.children` on the floor (gh#815).
  */
-export declare function NavGroup({ item, activeId, onSelect, linkComponent, renderItem }: RowProps): React.JSX.Element;
+export declare function NavGroup({ item, activeId, onSelect, sub, linkComponent, renderItem, }: RowProps): React.JSX.Element;
 export { createSidebarLink } from "./sidebar-link.js";
 /**
  * Sidebar — data-driven vertical nav rail. Use {@link createSidebarLink} to adapt a router `Link`,

package/dist/components/layout/sidebar.js

@@ -33,6 +33,30 @@ function SidebarTrailingIcon({
 }) {
   return /* @__PURE__ */ jsx("span", { className: "sb-trailing-icon", children: /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) });
 }
+function SidebarLabel({ children }) {
+  const ref = React.useRef(null);
+  React.useLayoutEffect(() => {
+    const label = ref.current;
+    if (!label) return;
+    const sync = () => {
+      const cut = label.scrollWidth - label.clientWidth > 1;
+      if (cut) {
+        const text = (label.textContent ?? "").replace(/\s+/g, " ").trim();
+        if (label.title !== text) label.title = text;
+        label.dataset.truncated = "";
+      } else if (label.dataset.truncated !== void 0) {
+        label.removeAttribute("title");
+        delete label.dataset.truncated;
+      }
+    };
+    sync();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(sync);
+    observer.observe(label);
+    return () => observer.disconnect();
+  });
+  return /* @__PURE__ */ jsx("span", { ref, className: "sb-label", children });
+}
 function SidebarRowContent({
   item,
   sub = false,
@@ -42,7 +66,7 @@ function SidebarRowContent({
   const showBadge = item.badge !== void 0 && item.badge !== "";
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     !sub ? /* @__PURE__ */ jsx(SidebarIcon, { icon: item.icon }) : null,
-    /* @__PURE__ */ jsx("span", { className: "sb-label", children: item.label }),
+    /* @__PURE__ */ jsx(SidebarLabel, { children: item.label }),
     showBadge ? (
       // absent-when-off), so a rail that never sets `badgeTone` renders the exact same node it
       // always did and no consumer selector has to out-specify a marker meaning "unchanged".
@@ -147,20 +171,40 @@ function NavLeafsInGroup({
   linkComponent,
   renderItem
 }) {
-  return children.map((child) => /* @__PURE__ */ jsx(
-    NavLeaf,
-    {
-      item: child,
-      activeId,
-      onSelect,
-      sub: true,
-      linkComponent,
-      renderItem
-    },
-    child.id
-  ));
+  return children.map(
+    (child) => child.children && child.children.length > 0 ? /* @__PURE__ */ jsx(
+      NavGroup,
+      {
+        item: child,
+        activeId,
+        onSelect,
+        sub: true,
+        linkComponent,
+        renderItem
+      },
+      child.id
+    ) : /* @__PURE__ */ jsx(
+      NavLeaf,
+      {
+        item: child,
+        activeId,
+        onSelect,
+        sub: true,
+        linkComponent,
+        renderItem
+      },
+      child.id
+    )
+  );
 }
-function NavGroup({ item, activeId, onSelect, linkComponent, renderItem }) {
+function NavGroup({
+  item,
+  activeId,
+  onSelect,
+  sub = false,
+  linkComponent,
+  renderItem
+}) {
   const active = isItemActive(item, activeId);
   const children = item.children ?? [];
   const [open, setOpen] = React.useState(active);
@@ -171,10 +215,10 @@ function NavGroup({ item, activeId, onSelect, linkComponent, renderItem }) {
     /* @__PURE__ */ jsxs(
       CollapsibleTrigger,
       {
-        className: "sb-nav-item sb-nav-group-trigger",
+        className: cn("sb-nav-item sb-nav-group-trigger", sub && "sb-nav-item--sub"),
         "data-active": active ? "true" : void 0,
         children: [
-          /* @__PURE__ */ jsx(SidebarRowContent, { item }),
+          /* @__PURE__ */ jsx(SidebarRowContent, { item, sub }),
           /* @__PURE__ */ jsx(ChevronDown, { className: "sb-chevron", "aria-hidden": "true" })
         ]
       }
@@ -232,6 +276,45 @@ function CollapsedRow({ item, activeId, onSelect, linkComponent: LinkComponent }
       children: /* @__PURE__ */ jsx(SidebarRowContent, { item, iconOnly: true })
     }
   ) : null;
+  const renderFlyoutEntries = (entries) => entries.map((child) => {
+    if (child.children && child.children.length > 0) {
+      return /* @__PURE__ */ jsxs("div", { role: "group", "aria-label": child.label, className: "sb-flyout-group", children: [
+        /* @__PURE__ */ jsx("div", { className: "sb-flyout-title", "aria-hidden": "true", children: child.label }),
+        renderFlyoutEntries(child.children)
+      ] }, child.id);
+    }
+    const childActive = child.id === activeId;
+    const select = (event) => {
+      setMenuOpen(false);
+      if (child.disabled) {
+        event.preventDefault();
+        return;
+      }
+      onSelect?.(child.id);
+    };
+    const flyoutState = {
+      role: "menuitem",
+      className: "sb-nav-item",
+      "data-active": childActive ? "true" : void 0,
+      "aria-current": childActive ? "page" : void 0,
+      "aria-disabled": child.disabled || void 0
+    };
+    return LinkComponent && child.href ? /* @__PURE__ */ jsx(
+      LinkComponent,
+      {
+        ...flyoutState,
+        href: child.disabled ? void 0 : child.href,
+        onClick: select,
+        children: /* @__PURE__ */ jsx(SidebarRowContent, { item: child, sub: true })
+      },
+      child.id
+    ) : (
+      // A collapsed-rail flyout entry is a `menuitem`-styled nav row owning `.sb-nav-item`
+      // composition, not a <Button> — same contract as the leaf row above.
+      // ui-audit-disable-next-line no-raw-button
+      /* @__PURE__ */ jsx("button", { type: "button", ...flyoutState, onClick: select, children: /* @__PURE__ */ jsx(SidebarRowContent, { item: child, sub: true }) }, child.id)
+    );
+  });
   if (!hasChildren) {
     return /* @__PURE__ */ jsxs(Tooltip, { children: [
       /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: iconLink ?? iconButton }),
@@ -253,39 +336,7 @@ function CollapsedRow({ item, activeId, onSelect, linkComponent: LinkComponent }
         className: "sb-flyout-pop",
         children: [
           /* @__PURE__ */ jsx("div", { className: "sb-flyout-title", children: item.label }),
-          children.map((child) => {
-            const childActive = child.id === activeId;
-            const select = (event) => {
-              setMenuOpen(false);
-              if (child.disabled) {
-                event.preventDefault();
-                return;
-              }
-              onSelect?.(child.id);
-            };
-            const flyoutState = {
-              role: "menuitem",
-              className: "sb-nav-item",
-              "data-active": childActive ? "true" : void 0,
-              "aria-current": childActive ? "page" : void 0,
-              "aria-disabled": child.disabled || void 0
-            };
-            return LinkComponent && child.href ? /* @__PURE__ */ jsx(
-              LinkComponent,
-              {
-                ...flyoutState,
-                href: child.disabled ? void 0 : child.href,
-                onClick: select,
-                children: /* @__PURE__ */ jsx(SidebarRowContent, { item: child, sub: true })
-              },
-              child.id
-            ) : (
-              // A collapsed-rail flyout entry is a `menuitem`-styled nav row owning `.sb-nav-item`
-              // composition, not a <Button> — same contract as the leaf row above.
-              // ui-audit-disable-next-line no-raw-button
-              /* @__PURE__ */ jsx("button", { type: "button", ...flyoutState, onClick: select, children: /* @__PURE__ */ jsx(SidebarRowContent, { item: child, sub: true }) }, child.id)
-            );
-          })
+          renderFlyoutEntries(children)
         ]
       }
     )

package/dist/components/layout/topbar.js

@@ -3,6 +3,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { revealKeyboardFocus } from "../../lib/focus-reveal.js";
 import { MoreHorizontal } from "lucide-react";
 import * as React from "react";
+import { createPortal } from "react-dom";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { padStyle } from "../../lib/variants.js";
 import { cn } from "../../lib/utils.js";
@@ -26,13 +27,54 @@ function Topbar({
   const controlsRef = React.useRef(null);
   const hasIdentity = identity != null && children == null;
   const foldable = overflow === "menu" && children == null;
-  const collapsed = useCollapsesToMenu(hasIdentity ? controlsRef : barRef, foldable);
-  const clusters = /* @__PURE__ */ jsxs(Fragment, { children: [
+  const hosts = useFoldHosts(foldable);
+  const present = { start: start != null, center: center != null, end: end != null };
+  const holderRef = React.useRef(null);
+  const overflowRef = React.useRef(null);
+  const placeClusters = React.useCallback(
+    (isCollapsed) => {
+      if (!hosts) return;
+      const target = !isCollapsed ? hasIdentity ? controlsRef.current : barRef.current : overflowRef.current ?? holderRef.current;
+      if (!target) return;
+      for (const key of CLUSTER_ORDER) {
+        const node = hosts[key];
+        if (!present[key]) node.remove();
+        else if (node.parentNode !== target || node !== target.lastElementChild) {
+          target.appendChild(node);
+        }
+      }
+    },
+    // `present` is derived from the three slots on every render; its booleans are what matter.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [hosts, hasIdentity, present.start, present.center, present.end]
+  );
+  const collapsed = useCollapsesToMenu(
+    hasIdentity ? controlsRef : barRef,
+    foldable,
+    hosts ? placeClusters : void 0
+  );
+  const overflowNode = React.useCallback(
+    (node) => {
+      overflowRef.current = node;
+      placeClusters(true);
+    },
+    [placeClusters]
+  );
+  const clusters = hosts ? (
+    // Kept mounted in ONE place, whatever the bar is showing; `placeClusters` moves the elements.
+    /* @__PURE__ */ jsx(TopbarClusterHolder, { ref: holderRef, visible: collapsed })
+  ) : /* @__PURE__ */ jsxs(Fragment, { children: [
     start != null ? /* @__PURE__ */ jsx("div", { "data-slot": "topbar-start", className: "ui-topbar-start", children: start }) : null,
     center != null ? /* @__PURE__ */ jsx("div", { "data-slot": "topbar-center", className: "ui-topbar-center", children: center }) : null,
     end != null ? /* @__PURE__ */ jsx("div", { "data-slot": "topbar-end", className: "ui-topbar-end", children: end }) : null
   ] });
-  return /* @__PURE__ */ jsx(
+  const portals = hosts ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    start != null ? createPortal(start, hosts.start) : null,
+    center != null ? createPortal(center, hosts.center) : null,
+    end != null ? createPortal(end, hosts.end) : null
+  ] }) : null;
+  const overflowMenu = /* @__PURE__ */ jsx(TopbarOverflowMenu, { contentRef: hosts ? overflowNode : void 0, children: hosts ? null : clusters });
+  return /* @__PURE__ */ jsxs(
     "div",
     {
       ref: barRef,
@@ -48,36 +90,81 @@ function Topbar({
       "data-slot": "topbar",
       className: cn("ui-topbar", className),
       ...props,
-      children: children ?? (hasIdentity ? /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(
-          "div",
-          {
-            ref: controlsRef,
-            onFocusCapture: revealKeyboardFocus,
-            "data-slot": "topbar-controls",
-            "data-overflow": overflow,
-            className: "ui-topbar ui-topbar-controls",
-            children: collapsed ? /* @__PURE__ */ jsx(TopbarOverflowMenu, { children: clusters }) : clusters
-          }
-        ),
-        /* @__PURE__ */ jsx("div", { "data-slot": "topbar-identity", className: "ui-topbar-identity", children: identity })
-      ] }) : collapsed ? /* @__PURE__ */ jsx(TopbarOverflowMenu, { children: clusters }) : clusters)
+      children: [
+        children ?? (hasIdentity ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsxs(
+            "div",
+            {
+              ref: controlsRef,
+              onFocusCapture: revealKeyboardFocus,
+              "data-slot": "topbar-controls",
+              "data-overflow": overflow,
+              className: "ui-topbar ui-topbar-controls",
+              children: [
+                collapsed ? overflowMenu : null,
+                collapsed && !hosts ? null : clusters
+              ]
+            }
+          ),
+          /* @__PURE__ */ jsx("div", { "data-slot": "topbar-identity", className: "ui-topbar-identity", children: identity })
+        ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          collapsed ? overflowMenu : null,
+          collapsed && !hosts ? null : clusters
+        ] })),
+        portals
+      ]
     }
   );
 }
-function TopbarOverflowMenu({ children }) {
+const CLUSTER_ORDER = ["start", "center", "end"];
+const subscribeNothing = () => () => {
+};
+function useFoldHosts(enabled) {
+  const isClient = React.useSyncExternalStore(
+    subscribeNothing,
+    () => true,
+    () => false
+  );
+  const [hosts] = React.useState(() => {
+    if (typeof document === "undefined") return null;
+    const make = (key) => {
+      const node = document.createElement("div");
+      node.dataset.slot = `topbar-${key}`;
+      node.className = `ui-topbar-${key}`;
+      return node;
+    };
+    return { start: make("start"), center: make("center"), end: make("end") };
+  });
+  React.useEffect(
+    () => () => {
+      if (hosts) for (const key of CLUSTER_ORDER) hosts[key].remove();
+    },
+    [hosts]
+  );
+  return enabled && isClient ? hosts : null;
+}
+const TopbarClusterHolder = React.forwardRef(
+  function TopbarClusterHolder2({ visible }, ref) {
+    return visible ? /* @__PURE__ */ jsx("div", { ref, hidden: true, "data-slot": "topbar-fold-holder" }) : null;
+  }
+);
+function TopbarOverflowMenu({
+  children,
+  contentRef
+}) {
   const { t } = useTranslation();
   return /* @__PURE__ */ jsxs(Popover, { children: [
     /* @__PURE__ */ jsx(PopoverTrigger, { asChild: true, children: /* @__PURE__ */ jsx(TopbarItem, { "data-topbar-overflow-trigger": "", "aria-label": t("layout.topbar.more"), children: /* @__PURE__ */ jsx(MoreHorizontal, { "aria-hidden": "true" }) }) }),
-    /* @__PURE__ */ jsx(PopoverContent, { align: "end", width: "auto", children: /* @__PURE__ */ jsx("div", { "data-slot": "topbar-overflow", className: "ui-topbar-overflow", children }) })
+    /* @__PURE__ */ jsx(PopoverContent, { align: "end", width: "auto", children: /* @__PURE__ */ jsx("div", { ref: contentRef, "data-slot": "topbar-overflow", className: "ui-topbar-overflow", children }) })
   ] });
 }
-function useCollapsesToMenu(ref, enabled) {
+function useCollapsesToMenu(ref, enabled, place) {
   const [collapsed, setCollapsed] = React.useState(false);
   const needed = React.useRef(0);
   React.useLayoutEffect(() => {
     const bar = ref.current;
     if (!enabled || !bar) return void 0;
+    place?.(collapsed);
     const update = () => {
       if (!collapsed) {
         if (bar.clientWidth > 0 && bar.scrollWidth - bar.clientWidth > 1) {
@@ -100,7 +187,7 @@ function useCollapsesToMenu(ref, enabled) {
         }
       }
     return () => observer.disconnect();
-  }, [ref, enabled, collapsed]);
+  }, [ref, enabled, collapsed, place]);
   return enabled && collapsed;
 }
 export {

package/dist/components/navigation/toolbar.js

@@ -132,7 +132,8 @@ function Toolbar({
                         onValueChange: (selected) => filter.onSelectedChange?.(selected),
                         placeholder: filter.placeholder,
                         disabled: disabled || filter.disabled,
-                        allowClear: true,
+                        allowClear: filter.required ? false : filter.allowClear ?? true,
+                        "aria-required": filter.required || void 0,
                         clearLabel: typeof filter.label === "string" ? t("navigation.filterBar.clearFilter", { label: filter.label }) : void 0
                       }
                     )

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": "33.22.2",
+  "version": "33.24.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

@@ -382,10 +382,16 @@
       "position": "Cover position",
       "hint": "Drag the image, or use the arrow keys, to reposition it",
       "valueText": "{value}% from the top"
+    },
+    "pageErrorBoundary": {
+      "title": "This page could not be displayed",
+      "description": "Something went wrong while showing this page. The rest of the app still works: reload the page, or go to another page from the menu.",
+      "reload": "Reload page"
     }
   },
   "dataDisplay": {
     "avatar": {
+      "agent": "AI agent",
       "presence": {
         "online": "Online",
         "away": "Away",

package/dist/i18n/messages/ja.json

@@ -374,10 +374,16 @@
       "position": "カバー画像の位置",
       "hint": "画像をドラッグするか矢印キーで位置を調整",
       "valueText": "上から {value}%"
+    },
+    "pageErrorBoundary": {
+      "title": "このページを表示できませんでした",
+      "description": "ページの表示中に問題が発生しました。アプリの他の部分は使えます。ページを再読み込みするか、メニューから別のページに移動してください。",
+      "reload": "ページを再読み込み"
     }
   },
   "dataDisplay": {
     "avatar": {
+      "agent": "AIエージェント",
       "presence": {
         "online": "オンライン",
         "away": "離席中",

package/dist/i18n/messages/vi.json

@@ -375,10 +375,16 @@
       "position": "Vị trí ảnh bìa",
       "hint": "Kéo ảnh hoặc dùng phím mũi tên để chỉnh vị trí",
       "valueText": "{value}% tính từ trên"
+    },
+    "pageErrorBoundary": {
+      "title": "Không thể hiển thị trang này",
+      "description": "Đã xảy ra lỗi khi hiển thị trang này. Các phần khác của ứng dụng vẫn hoạt động: hãy tải lại trang, hoặc chuyển sang trang khác từ menu.",
+      "reload": "Tải lại trang"
     }
   },
   "dataDisplay": {
     "avatar": {
+      "agent": "Tác tử AI",
       "presence": {
         "online": "Trực tuyến",
         "away": "Vắng mặt",

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

@@ -261,9 +261,25 @@ export type AvatarProp = React.ComponentPropsWithoutRef<"span"> & {
      * a presence dot never carries visible text; that is `Badge status`.
      */
     presenceLabel?: LabelProp;
+    /**
+     * Who the mark stands for. `person` (default) is inert — no attribute, no node. `agent` marks an
+     * AI agent: a small "AI" tag at the block-start/inline-end corner (the corner `presence` does not
+     * use) plus a localized visually hidden "AI agent" folded into the avatar's accessible text, so the
+     * difference is never carried by the tag's colour alone (WCAG 1.4.1). Same vocabulary as
+     * `OrgChartNode.variant`.
+     */
+    kind?: AvatarKindProp;
     className?: ClassNameProp;
     children?: ChildrenProp;
 };
+/**
+ * Who an Avatar stands for — a person or an AI agent. Deliberately the same two values as
+ * `OrgChartNodeVariantProp`, so an app that already knows a principal's kind passes it unchanged
+ * to both. Retune the agent tag with `--avatar-agent-*`.
+ *
+ * @see Avatar
+ */
+export type AvatarKindProp = "person" | "agent";
 /**
  * Avatar presence status — a person's realtime reachability.
  *
@@ -307,6 +323,17 @@ export type AvatarAppearanceProp = "default" | "tinted";
  */
 export type AvatarImageFitProp = "cover" | "contain";
 /** @see Badge */
+/**
+ * @see AgentBadge — the "AI agent" label beside a name (violet outline, pill, never wraps). The
+ * text-row half of telling an agent apart from a person; `Avatar kind="agent"` is the mark half.
+ */
+export type AgentBadgeProp = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
+    /** Render element — `span` (default; the label sits in a name's text line) or `div`. */
+    as?: "div" | "span";
+    /** Overrides the localized default label (`dataDisplay.avatar.agent`). */
+    children?: ChildrenProp;
+    className?: ClassNameProp;
+};
 export type BadgeProp = {
     /**
      * Render element — `div` (default) or `span` when the chip sits in a phrasing context where a

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

@@ -73,6 +73,13 @@ export type PageContainerProp = {
     titleRef?: React.Ref<HTMLHeadingElement>;
     /** @see PageContainerExtraProp */
     extra?: PageContainerExtraProp;
+    /**
+     * The page's Help control (gh#1494) — a `Button` that opens a help Sheet, or a link to the
+     * manual. It has ONE fixed place on every page: the inline end of the header row, after the
+     * `extra` actions, and still the last item at the inline end when those actions wrap. A page
+     * passing only `help` still gets a header. Pass one control; it is not a second action cluster.
+     */
+    help?: ReactNode;
     /**
      * FIXED chrome band between the page header and the scrolling body — a filter strip, a status
      * bar, a "channel workflow" rail. It is a first-class page-chrome slot precisely because the
@@ -454,6 +461,33 @@ export type PageInsetProp = React.HTMLAttributes<HTMLDivElement> & {
     children?: ChildrenProp;
     className?: ClassNameProp;
 };
+/** @see PageErrorBoundary — the render-prop form of `fallback`. */
+export type PageErrorBoundaryFallbackProp = (failure: {
+    /** What the page threw. */
+    error: unknown;
+    /** Draws the page again (e.g. a "Try again" button that re-renders without a reload). */
+    reset: () => void;
+}) => ReactNode;
+/**
+ * @see PageErrorBoundary — a page-level error boundary (gh#1494). A page that throws while
+ * rendering is replaced by an `ErrorSurface`; the shell around it stays.
+ */
+export type PageErrorBoundaryProp = {
+    children?: ChildrenProp;
+    /**
+     * What to draw instead of the page. Default: an `application` `ErrorSurface` (status 500,
+     * localized title and description, one "Reload page" action). A function receives
+     * `{ error, reset }`.
+     */
+    fallback?: ReactNode | PageErrorBoundaryFallbackProp;
+    /**
+     * Draw the page again whenever this value changes (compared with `Object.is`). The boundary
+     * already resets when the URL changes; pass a key for a change the URL does not show.
+     */
+    resetKey?: unknown;
+    /** Report the error (Sentry, a log endpoint). Replaces the development-time `console.error`. */
+    onError?: (error: unknown, info: React.ErrorInfo) => void;
+};
 /** @see AppShell */
 export type AppShellProp = {
     /** Phone destinations, using MobileShell tabBar children (3–5 links or Buttons with aria-current="page"). Only rendered in drawer navigation mode. Main/footer reserve the measured safe-area-inclusive height. */
@@ -463,6 +497,14 @@ export type AppShellProp = {
     /** Omit or pass null/false for a shell without the sidebar landmark or grid track. */
     sidebar?: ReactNode;
     children: ReactNode;
+    /**
+     * The page-level error boundary around `children` (gh#1494). Default `true`: a page that throws
+     * while rendering is replaced by an `ErrorSurface` inside `<main>`, and the sidebar, topbar and
+     * breadcrumb stay, so the user can navigate away; the boundary resets when the URL changes.
+     * Pass props to configure it (`{ fallback, resetKey, onError }`), or `false` when the app
+     * already wraps its pages in its own boundary.
+     */
+    errorBoundary?: boolean | Omit<PageErrorBoundaryProp, "children">;
     topbar?: ReactNode;
     topbarLeft?: ReactNode;
     topbarRight?: ReactNode;
@@ -1149,6 +1191,9 @@ export type SidebarItemProp = {
      * Nested rows — renders a collapsible submenu group (the parent reads active when any child is).
      * Honoured by BOTH `Sidebar` and `NavList` (gh#815): `NavList` used to map `items` straight to a
      * row, so a nested group type-checked, rendered as one flat row and lost its children silently.
+     * A child may carry `children` of its own (gh#1493): the group nests one level further, so a
+     * section can hold work area → sub-area → page (three clickable levels), and the collapsed-rail
+     * flyout lists the grandchildren under a labelled group.
      */
     children?: SidebarItemProp[];
 };