From 9eab0c6f17cfdd26aa3c428cf8bcf454742bc98f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 02:01:18 +0000
Subject: [PATCH 01/12] feat(app-shell): Studio item header keeps the item name
 readable

The title keeps its first twelve characters readable; on a narrower row the
identity chips and the item tools fold into the item's more menu (the
pillar's own, or one the header draws), so the menu trigger stays inside the
column. The pillar rails draw the customization mark as its glyph alone.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 .../src/views/item-tools/StudioItemTools.tsx  |  75 ++++--
 .../views/studio-design/CustomizationMark.tsx |  33 +++
 .../views/studio-design/FlowItemMoreMenu.tsx  |   3 +
 .../studio-design/StudioDesignSurface.tsx     |  20 +-
 .../views/studio-design/StudioItemHeader.tsx  | 250 +++++++++++++++++-
 .../StudioRailCustomizations.tsx              |   7 +-
 6 files changed, 358 insertions(+), 30 deletions(-)

diff --git a/ui/packages/app-shell/src/views/item-tools/StudioItemTools.tsx b/ui/packages/app-shell/src/views/item-tools/StudioItemTools.tsx
index 001639c3984..d1cca5cfe41 100644
--- a/ui/packages/app-shell/src/views/item-tools/StudioItemTools.tsx
+++ b/ui/packages/app-shell/src/views/item-tools/StudioItemTools.tsx
@@ -22,6 +22,10 @@
  * (`source.onChange`) and the item is not read-only, so an edit there is
  * saved by the pillar's autosave like any other. Without a buffer it shows
  * the item's effective body, read-only.
+ *
+ * objectstack#29693 — when the item header folds (the title would drop below
+ * its readable width), the five buttons leave the row and the same tools read
+ * as items of the header's ⋯ menu, opening the same sheets.
  */
 
 import * as React from 'react';
@@ -44,6 +48,7 @@ import { ReferencesPanel, useReferencesScan } from './ReferencesPanel.js';
 import { HistoryPanel } from './ResourceHistoryPage.js';
 import { AuditPanel } from './AuditPanel.js';
 import { JsonSourceEditor } from './JsonSourceEditor.js';
+import { useStudioItemHeaderFold, type StudioFoldedTool } from '../studio-design/StudioItemHeader.js';
 
 /** The tool a sheet holds. */
 export type StudioItemTool = 'layers' | 'references' | 'history' | 'audit' | 'source';
@@ -123,6 +128,31 @@ function StudioItemToolsFor({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open]);
 
+  // objectstack#29693 — the tools' menu form, handed to the header's fold.
+  const fold = useStudioItemHeaderFold();
+  const setFoldedTools = fold?.setTools;
+  const refsCount = refs.state.status === 'loaded' ? refs.state.items.length : undefined;
+  React.useEffect(() => {
+    if (!setFoldedTools) return;
+    const tool = (id: StudioItemTool, label: string, icon: React.ElementType, count?: number): StudioFoldedTool => ({
+      id,
+      label,
+      icon,
+      count,
+      onSelect: () => setOpen(id),
+    });
+    setFoldedTools([
+      tool('layers', t('engine.edit.layers', locale), Layers3),
+      tool('references', t('engine.edit.references', locale), Link2, refsCount),
+      ...(canReadTrail
+        ? [tool('history', t('engine.edit.history', locale), History), tool('audit', t('engine.edit.auditTab', locale), ShieldCheck)]
+        : []),
+      tool('source', t('engine.edit.inspector.source', locale), FileCode2),
+    ]);
+    return () => setFoldedTools(null);
+  }, [setFoldedTools, canReadTrail, refsCount, locale]);
+  const folded = fold?.folded ?? false;
+
   const canRollback = !readOnly && canAuthor;
   const sourceEditable = !readOnly && !!source?.onChange;
   const close = (o: boolean) => {
@@ -181,27 +211,30 @@ function StudioItemToolsFor({
 
   return (
     <>
-      <div
-        role="group"
-        aria-label={t('engine.studio.itemTools.group', locale)}
-        data-testid="studio-item-tools"
-        className="flex shrink-0 items-center rounded-md border bg-background p-0.5"
-      >
-        {toolButton('layers', t('engine.edit.layers', locale), Layers3)}
-        {toolButton(
-          'references',
-          t('engine.edit.references', locale),
-          Link2,
-          refs.state.status === 'loaded' && refs.state.items.length > 0 ? (
-            <span className="absolute -top-1 -right-1 min-w-[14px] h-[14px] px-1 rounded-full bg-muted text-foreground text-[9px] leading-[14px] text-center font-medium border">
-              {refs.state.items.length}
-            </span>
-          ) : undefined,
-        )}
-        {canReadTrail && toolButton('history', t('engine.edit.history', locale), History)}
-        {canReadTrail && toolButton('audit', t('engine.edit.auditTab', locale), ShieldCheck)}
-        {toolButton('source', t('engine.edit.inspector.source', locale), FileCode2)}
-      </div>
+      {!folded && (
+        <div
+          role="group"
+          aria-label={t('engine.studio.itemTools.group', locale)}
+          data-testid="studio-item-tools"
+          data-studio-fold="tools"
+          className="flex shrink-0 items-center rounded-md border bg-background p-0.5"
+        >
+          {toolButton('layers', t('engine.edit.layers', locale), Layers3)}
+          {toolButton(
+            'references',
+            t('engine.edit.references', locale),
+            Link2,
+            refs.state.status === 'loaded' && refs.state.items.length > 0 ? (
+              <span className="absolute -top-1 -right-1 min-w-[14px] h-[14px] px-1 rounded-full bg-muted text-foreground text-[9px] leading-[14px] text-center font-medium border">
+                {refs.state.items.length}
+              </span>
+            ) : undefined,
+          )}
+          {canReadTrail && toolButton('history', t('engine.edit.history', locale), History)}
+          {canReadTrail && toolButton('audit', t('engine.edit.auditTab', locale), ShieldCheck)}
+          {toolButton('source', t('engine.edit.inspector.source', locale), FileCode2)}
+        </div>
+      )}
 
       {sheet('layers', t('engine.edit.layers', locale), <div className="flex-1 min-h-0 overflow-auto p-4">{layersBody}</div>)}
 
diff --git a/ui/packages/app-shell/src/views/studio-design/CustomizationMark.tsx b/ui/packages/app-shell/src/views/studio-design/CustomizationMark.tsx
index de7f2baede2..81a44c74c20 100644
--- a/ui/packages/app-shell/src/views/studio-design/CustomizationMark.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/CustomizationMark.tsx
@@ -15,6 +15,7 @@
  */
 
 import * as React from 'react';
+import { Layers3, PencilRuler, Plus } from 'lucide-react';
 import { cn } from '@object-ui/components';
 import { customizationPackageId } from '@objectstack/spec/kernel';
 import { t, tFormat } from '../metadata-admin/i18n.js';
@@ -35,12 +36,26 @@ const KIND_CLASS: Record<CustomizationMarkChipKind, string> = {
   customizationOf: 'bg-muted text-muted-foreground',
 };
 
+/** objectstack#29693 — the glyph the compact mark draws in place of its text. */
+const KIND_ICON: Record<CustomizationMarkChipKind, React.ElementType> = {
+  customized: PencilRuler,
+  added: Plus,
+  customizationOf: Layers3,
+};
+
+/**
+ * objectstack#29693 — `compact` (the pillar rails): the mark is its glyph
+ * alone, so it never takes a row's name ("已定制（ObjectStack Showcase）" left a
+ * selected flow row no room for its label). Its text is its accessible name
+ * and leads its tooltip, before the sentence naming the pair.
+ */
 export function CustomizationMark({
   kind,
   baseName,
   pairId,
   locale,
   className,
+  compact = false,
 }: {
   kind: CustomizationMarkChipKind;
   /** The base's display name ("customized (HotCRM)"); needed by `customized` and `customizationOf`. */
@@ -49,6 +64,8 @@ export function CustomizationMark({
   pairId?: string;
   locale: string;
   className?: string;
+  /** Draw the glyph alone, the text in its accessible name and tooltip. */
+  compact?: boolean;
 }): React.ReactElement {
   const base = baseName ?? '';
   const label =
@@ -58,6 +75,22 @@ export function CustomizationMark({
   const title = pairId
     ? tFormat(`engine.customizationMark.${kind}Title`, locale, { baseName: base, pair: pairId })
     : undefined;
+  if (compact) {
+    const Icon = KIND_ICON[kind];
+    return (
+      <span
+        data-testid="customization-mark"
+        data-kind={kind}
+        data-compact=""
+        role="img"
+        aria-label={label}
+        title={title ? `${label}\n${title}` : label}
+        className={cn('inline-flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-[5px]', KIND_CLASS[kind], className)}
+      >
+        <Icon className="h-3 w-3" aria-hidden="true" />
+      </span>
+    );
+  }
   return (
     <span
       data-testid="customization-mark"
diff --git a/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx b/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx
index 9bd5160d550..99a1b4beef2 100644
--- a/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx
@@ -50,6 +50,7 @@ import {
   Label,
 } from '@object-ui/components';
 import { actionErrorDetail } from '@object-ui/core';
+import { StudioItemHeaderFoldedItems } from './StudioItemHeader.js';
 import { Copy, Loader2, MoreHorizontal, Trash2 } from 'lucide-react';
 import { t, tFormat, translateMetadataType } from '../metadata-admin/i18n.js';
 import { envelopeData, envelopeRefused } from '../setup/packagedFlows.js';
@@ -193,6 +194,8 @@ export function FlowItemMoreMenu({ name, label, locale, disabled, onDelete, newS
           </button>
         </DropdownMenuTrigger>
         <DropdownMenuContent align="end" className="w-52">
+          {/* objectstack#29693 — what the flow header's title row folded away, on a narrow row. */}
+          <StudioItemHeaderFoldedItems />
           {newSimilar && (
             <DropdownMenuItem
               data-testid="auto-item-new-similar"
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
index 81bc45d5f58..0015b0185b1 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
@@ -68,6 +68,7 @@ import { StudioInspector } from './StudioInspector.js';
 import { agentDraftMarkOf, DraftChip, DraftSourceLine } from './StudioDraftMark.js';
 import {
   StudioItemHeader,
+  StudioItemHeaderFoldedItems,
   StudioStatusChip,
   StudioTab,
   useStudioTabRowFold,
@@ -6228,7 +6229,9 @@ export function InterfacesPillar({
             <MoreHorizontal className="h-4 w-4" />
           </button>
         </DropdownMenuTrigger>
-        <DropdownMenuContent align="end" className="w-44">
+        <DropdownMenuContent align="end" className="w-52">
+          {/* objectstack#29693 — what the title row folded away, on a narrow row. */}
+          <StudioItemHeaderFoldedItems />
           <DropdownMenuItem data-testid="if-item-view-definition" onSelect={() => setDefinitionOpen(true)}>
             <Code2 className="mr-2 h-3.5 w-3.5" aria-hidden="true" />
             {t('engine.studio.if.viewDefinition', locale)}
@@ -6290,6 +6293,9 @@ export function InterfacesPillar({
   const ifHeaderEl = (
     <StudioItemHeader
       testId="if-item-header"
+      // objectstack#29693 — on a narrow row the chips and the item tools fold
+      // into the ⋯ menu before the title drops below its readable width.
+      foldMenu={itemMoreEl ? 'pillar' : { label: t('engine.studio.if.more', locale), testId: 'if-item-header-more' }}
       leading={
         <button
           type="button"
@@ -8933,6 +8939,9 @@ export function DataPillar({
               over the thing it names, instead of spanning the rail. */}
           <StudioItemHeader
             testId="data-object-header"
+            // objectstack#29693 — the header has no ⋯ of its own (objectui#12511),
+            // so on a narrow row it draws one for the chips and the item tools.
+            foldMenu={{ label: t('engine.studio.if.more', locale), testId: 'data-object-header-more' }}
             leading={
               <button
                 type="button"
@@ -11053,6 +11062,8 @@ export function AutomationsPillar({
     editLocked && packageId !== null ? (
       <StudioReadOnlyLink item={current} title={t('engine.studio.pkg.readonlyHint', locale)} locale={locale} />
     ) : null;
+  /** The flow's ⋯ menu is drawn (objectstack#28567): the header folds into it (objectstack#29693). */
+  const flowMoreShown = !!current && flowLoaded && packageId !== null;
   const flowTabsEl =
     flowOpen ? (
       <>
@@ -11215,6 +11226,11 @@ export function AutomationsPillar({
               label that resolves to nothing falls back to the name. */}
           <StudioItemHeader
             testId="auto-flow-header"
+            // objectstack#29693 — the chips and the item tools fold into the
+            // flow's ⋯ menu (or the header's own, where the flow has none).
+            foldMenu={
+              flowMoreShown ? 'pillar' : { label: t('engine.studio.if.more', locale), testId: 'auto-flow-header-more' }
+            }
             leading={
               <button
                 type="button"
@@ -11314,7 +11330,7 @@ export function AutomationsPillar({
                     a read-only base; a writable package is the target);
                     Delete on a writable package's flow only. The
                     package-less scope has no pair and no package to name. */}
-                {current && flowLoaded && packageId !== null && (
+                {flowMoreShown && current && (
                   <FlowItemMoreMenu
                     name={current.name}
                     label={current.label}
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
index 3475e82d034..969b0b76924 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
@@ -46,13 +46,36 @@
  * that folds by `useStudioTabRowFold` folds to its icon when the title would
  * otherwise be cut, so it gives way before the title does. A title that is
  * still cut says its whole text in its tooltip.
+ *
+ * objectstack#29693 — the title keeps a readable width: its first twelve
+ * characters (its whole text when shorter). When the row cannot give it that,
+ * the identity chips (the api-name chip and the pillar's `chips`) and the item
+ * tools fold into the ⋯ menu, so the title is not the first thing to go. The
+ * pillar says where they go (`foldMenu`): into its own ⋯ menu, which mounts
+ * `StudioItemHeaderFoldedItems`, or into a ⋯ the header draws at the end of
+ * the actions. The status chip stays in the row (its text already folds, and
+ * its icon says a draft is there). Folded, the row's boxes fit the row, so
+ * the ⋯ trigger stays inside the column, not under the right panel. Like
+ * every rule here, it measures the header's own row, never the viewport.
  */
 
 import * as React from 'react';
-import { PencilLine } from 'lucide-react';
-import { cn, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@object-ui/components';
+import { MoreHorizontal, PencilLine } from 'lucide-react';
+import {
+  cn,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@object-ui/components';
 import {
   STUDIO_API_CHIP,
+  STUDIO_HEADER_ICON_BUTTON,
   STUDIO_ICON_TILE,
   STUDIO_ITEM_HEADER,
   STUDIO_ITEM_META_FOLD,
@@ -297,6 +320,178 @@ function useCutTitle(ref: React.RefObject<HTMLElement | null>): string | null {
   return cut;
 }
 
+/** objectstack#29693 — how many of the title's characters it keeps readable. */
+export const STUDIO_TITLE_READABLE_CHARS = 12;
+
+/**
+ * objectstack#29693 — the width of the title's first
+ * {@link STUDIO_TITLE_READABLE_CHARS} visible characters (a reader-only span
+ * is not counted), capped at its whole text; 0 where the page cannot measure
+ * a text range (no layout).
+ */
+function readableTitleWidth(title: HTMLElement): number {
+  if (typeof document.createRange !== 'function') return 0;
+  const walker = document.createTreeWalker(title, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) =>
+      node.parentElement?.closest('.sr-only') ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT,
+  });
+  let first: Node | null = null;
+  let last: Node | null = null;
+  let lastOffset = 0;
+  let count = 0;
+  for (let node = walker.nextNode(); node && count < STUDIO_TITLE_READABLE_CHARS; node = walker.nextNode()) {
+    const chars = Array.from(node.textContent ?? '');
+    if (chars.length === 0) continue;
+    const take = Math.min(chars.length, STUDIO_TITLE_READABLE_CHARS - count);
+    first ??= node;
+    last = node;
+    // Code points, so a character outside the BMP is one character, not two.
+    lastOffset = chars.slice(0, take).join('').length;
+    count += take;
+  }
+  if (!first || !last) return 0;
+  const range = document.createRange();
+  range.setStart(first, 0);
+  range.setEnd(last, lastOffset);
+  const width = typeof range.getBoundingClientRect === 'function' ? range.getBoundingClientRect().width : 0;
+  return Math.min(width, title.scrollWidth);
+}
+
+/** The gap a box takes in the flex row that lays it out (a `contents` box's own parent does not). */
+function gapBeside(el: Element): number {
+  let parent = el.parentElement;
+  while (parent && getComputedStyle(parent).display === 'contents') parent = parent.parentElement;
+  return parent ? parseFloat(getComputedStyle(parent).columnGap) || 0 : 0;
+}
+
+/** The width the title row's foldable boxes take, each with its gap. */
+function foldableWidth(row: HTMLElement): number {
+  const boxes = [
+    ...Array.from(row.querySelector('[data-slot="identity-chips"]')?.children ?? []),
+    ...Array.from(row.querySelectorAll('[data-studio-fold]')),
+  ];
+  let width = 0;
+  for (const el of boxes) {
+    if (getComputedStyle(el).display === 'none') continue;
+    width += el.getBoundingClientRect().width + gapBeside(el);
+  }
+  return width;
+}
+
+/** objectstack#29693 — one item tool, as it reads in the ⋯ menu while the header is folded. */
+export interface StudioFoldedTool {
+  /** The tool's id: the menu item's test id is `studio-item-tool-<id>`, the button's. */
+  id: string;
+  label: string;
+  icon: React.ElementType;
+  /** A count the button shows as a badge (references). */
+  count?: number;
+  onSelect: () => void;
+}
+
+interface StudioItemHeaderFoldValue {
+  /** The identity chips and the item tools are in the ⋯ menu, not in the row. */
+  folded: boolean;
+  /** What the row folds away: the api name and the pillar's chips. */
+  apiName?: string;
+  chips?: React.ReactNode;
+  tools: StudioFoldedTool[];
+  /** The item tools hand over their menu form; `null` takes it back. */
+  setTools: (tools: StudioFoldedTool[] | null) => void;
+}
+const StudioItemHeaderFoldContext = React.createContext<StudioItemHeaderFoldValue | null>(null);
+
+/**
+ * objectstack#29693 — the header's fold, for the item tools: whether they are
+ * folded into the ⋯ menu, and where they hand over their menu form. `null`
+ * outside a header, or in a header whose pillar names no `foldMenu`.
+ */
+export function useStudioItemHeaderFold(): Pick<StudioItemHeaderFoldValue, 'folded' | 'setTools'> | null {
+  return React.useContext(StudioItemHeaderFoldContext);
+}
+
+/**
+ * objectstack#29693 — what the title row folded away, at the top of a ⋯
+ * menu: the identity chips as they read in the row, then the item tools as
+ * menu items, then a separator before the menu's own items. Nothing while the
+ * row holds them. A pillar whose actions end with its own ⋯ menu mounts this
+ * in that menu's content and passes `foldMenu="pillar"`.
+ */
+export function StudioItemHeaderFoldedItems({ separator = true }: { separator?: boolean }): React.ReactElement | null {
+  const fold = React.useContext(StudioItemHeaderFoldContext);
+  if (!fold?.folded) return null;
+  const hasChips = !!fold.apiName || !!fold.chips;
+  if (!hasChips && fold.tools.length === 0) return null;
+  return (
+    <>
+      {hasChips && (
+        <div data-testid="studio-item-header-folded-chips" className="flex flex-wrap items-center gap-1.5 px-2 py-1.5">
+          {fold.apiName && <StudioApiChip apiName={fold.apiName} />}
+          {fold.chips}
+        </div>
+      )}
+      {fold.tools.map(({ id, label, icon: Icon, count, onSelect }) => (
+        <DropdownMenuItem key={id} data-testid={`studio-item-tool-${id}`} onSelect={onSelect}>
+          <Icon className="mr-2 h-3.5 w-3.5" aria-hidden="true" />
+          <span className="min-w-0 flex-1 truncate">{label}</span>
+          {count !== undefined && count > 0 && <span className="ml-2 text-[11px] text-muted-foreground">{count}</span>}
+        </DropdownMenuItem>
+      ))}
+      {separator && <DropdownMenuSeparator />}
+    </>
+  );
+}
+
+/**
+ * objectstack#29693 — whether the title row folds its identity chips and item
+ * tools into the ⋯ menu: when the room it leaves the title, with them shown,
+ * is less than the title's readable width. Folded, it remembers how wide they
+ * were, and shows them again once the title would keep that width beside
+ * them (`ownTrigger`: the header's own ⋯, which goes when they come back).
+ */
+function useTitleRowFold(
+  enabled: boolean,
+  row: React.RefObject<HTMLElement | null>,
+  title: React.RefObject<HTMLElement | null>,
+  ownTrigger: React.RefObject<HTMLElement | null>,
+): boolean {
+  const [folded, setFolded] = React.useState(false);
+  /** The foldable boxes' width, read while they were shown. */
+  const shown = React.useRef(0);
+  const measureRef = React.useRef<() => void>(() => {});
+  // Every render: the chips and the actions can change without the row resizing.
+  React.useLayoutEffect(() => {
+    const measure = () => {
+      const rowEl = row.current;
+      const titleEl = title.current;
+      if (!enabled) return setFolded(false);
+      if (!rowEl || !titleEl) return;
+      const readable = readableTitleWidth(titleEl);
+      if (readable <= 0) return;
+      const room = titleRoom(rowEl, titleEl);
+      if (!folded) {
+        shown.current = foldableWidth(rowEl);
+        if (shown.current <= 0) return;
+        return setFolded(room + 0.5 < readable);
+      }
+      const trigger = ownTrigger.current;
+      const freed = trigger ? trigger.getBoundingClientRect().width + gapBeside(trigger) : 0;
+      setFolded(room - shown.current + freed + 0.5 < readable);
+    };
+    measureRef.current = measure;
+    measure();
+  });
+  React.useEffect(() => {
+    const rowEl = row.current;
+    if (!rowEl || typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(() => measureRef.current());
+    observer.observe(rowEl);
+    if (title.current) observer.observe(title.current);
+    return () => observer.disconnect();
+  }, [row, title]);
+  return enabled && folded;
+}
+
 export interface StudioItemHeaderProps {
   /** The icon component for the tile; omitted when the pillar has nothing open. */
   icon?: React.ElementType;
@@ -318,6 +513,15 @@ export interface StudioItemHeaderProps {
   tabs?: React.ReactNode;
   /** A leading control before the tile (the mobile rail toggle). */
   leading?: React.ReactNode;
+  /**
+   * objectstack#29693 — where the identity chips and the item tools go when
+   * the title would drop below its readable width. `'pillar'`: the pillar's
+   * own ⋯ menu, the last of its `actions`, which mounts
+   * `StudioItemHeaderFoldedItems`. An object: a ⋯ the header draws at the end
+   * of the actions while they are folded, with this accessible name and test
+   * id. Omitted: nothing folds.
+   */
+  foldMenu?: 'pillar' | { label: string; testId?: string };
   testId?: string;
   className?: string;
 }
@@ -333,6 +537,7 @@ export function StudioItemHeader({
   actions,
   tabs,
   leading,
+  foldMenu,
   testId,
   className,
 }: StudioItemHeaderProps): React.ReactElement {
@@ -347,6 +552,18 @@ export function StudioItemHeader({
   // objectui#12897 — a cut title says its whole text in its tooltip, before
   // the tooltip the pillar gives it (the machine name).
   const titleTooltip = cutTitle ? [cutTitle, titleProps?.title].filter(Boolean).join('\n') : titleProps?.title;
+  // objectstack#29693 — the identity chips and the item tools fold into the
+  // ⋯ menu before the title drops below its readable width.
+  const ownTriggerRef = React.useRef<HTMLButtonElement | null>(null);
+  const folded = useTitleRowFold(foldMenu !== undefined, titleRowRef, titleRef, ownTriggerRef);
+  const [tools, setToolsState] = React.useState<StudioFoldedTool[]>([]);
+  const setTools = React.useCallback((next: StudioFoldedTool[] | null) => setToolsState(next ?? []), []);
+  const foldValue = React.useMemo<StudioItemHeaderFoldValue | null>(
+    () => (foldMenu === undefined ? null : { folded, apiName, chips, tools, setTools }),
+    [foldMenu, folded, apiName, chips, tools, setTools],
+  );
+  const ownMenu = typeof foldMenu === 'object' ? foldMenu : null;
+  const hasFolded = folded && (!!apiName || !!chips || tools.length > 0);
   return (
     <div data-testid={testId} className={cn(STUDIO_ITEM_HEADER, !tabs && 'pb-3', className)}>
       <div ref={titleRowRef} className={STUDIO_ITEM_ROW}>
@@ -360,8 +577,8 @@ export function StudioItemHeader({
           {title}
         </h1>
         <span className="contents" data-slot="identity-chips">
-          {apiName && <StudioApiChip apiName={apiName} />}
-          {chips}
+          {!folded && apiName && <StudioApiChip apiName={apiName} />}
+          {!folded && chips}
         </span>
         {status && <StudioStatusChip {...status} fold />}
         {meta && (
@@ -369,9 +586,30 @@ export function StudioItemHeader({
             {meta}
           </span>
         )}
-        {actions && (
+        {(actions || (ownMenu && hasFolded)) && (
           <div className="ml-auto flex shrink-0 items-center gap-2">
-            <StudioFoldRowContext.Provider value={titleFold}>{actions}</StudioFoldRowContext.Provider>
+            <StudioItemHeaderFoldContext.Provider value={foldValue}>
+              <StudioFoldRowContext.Provider value={titleFold}>{actions}</StudioFoldRowContext.Provider>
+              {ownMenu && hasFolded && (
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <button
+                      ref={ownTriggerRef}
+                      type="button"
+                      data-testid={ownMenu.testId}
+                      aria-label={ownMenu.label}
+                      title={ownMenu.label}
+                      className={STUDIO_HEADER_ICON_BUTTON}
+                    >
+                      <MoreHorizontal className="h-4 w-4" />
+                    </button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end" className="w-52">
+                    <StudioItemHeaderFoldedItems separator={false} />
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              )}
+            </StudioItemHeaderFoldContext.Provider>
           </div>
         )}
       </div>
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioRailCustomizations.tsx b/ui/packages/app-shell/src/views/studio-design/StudioRailCustomizations.tsx
index d4eecbd4a03..0afb5a79b4b 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioRailCustomizations.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioRailCustomizations.tsx
@@ -100,7 +100,11 @@ export function railCustomizationsOf(
   };
 }
 
-/** A row's mark in the rail's trailing slot, or nothing. */
+/**
+ * A row's mark in the rail's trailing slot, or nothing. objectstack#29693 —
+ * compact (its glyph, the text in its name and tooltip), so it never takes the
+ * row's label.
+ */
 export function RailCustomizationMark({
   row,
   marks,
@@ -119,6 +123,7 @@ export function RailCustomizationMark({
       pairId={marks.pairId}
       locale={locale}
       className="ml-1"
+      compact
     />
   );
 }

From 511875eebe91cd7a6bb3cf43b6556ab8b45d842e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 02:05:16 +0000
Subject: [PATCH 02/12] test(app-shell): pin the item header fold and the
 compact rail mark

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 ...dioDesignSurface.oneSurface-28572.test.tsx |  19 +++
 ...udioItemHeader.titleRowFold-12897.test.tsx | 156 +++++++++++++++++-
 2 files changed, 171 insertions(+), 4 deletions(-)

diff --git a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.oneSurface-28572.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.oneSurface-28572.test.tsx
index 084f557aae0..1223eb6a51d 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.oneSurface-28572.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.oneSurface-28572.test.tsx
@@ -360,6 +360,25 @@ describe('the Interfaces rail lists a base and its pair as one list (objectstack
   });
 });
 
+describe('the rail mark never takes the row’s name (objectstack#29693)', () => {
+  it('is its glyph alone: the row prints only its label, and the mark’s text is its name and leads its tooltip', async () => {
+    renderAt(`/studio/${BASE}/interfaces`);
+    await interfacesReady();
+    const row = rowOf(ifRail(), 'dashboard', 'pipeline')!;
+    await waitFor(() => expect(markOf(row)).toBe('customized'), { timeout: 8000 });
+    const mark = within(row).getByTestId('customization-mark');
+    const label = tFormat('engine.customizationMark.customized', 'en', { baseName: 'HotCRM' });
+    expect(mark).toHaveAttribute('data-compact');
+    expect(mark).toHaveAccessibleName(label);
+    expect(mark.getAttribute('title')?.split('\n')[0]).toBe(label);
+    expect(mark.textContent).toBe('');
+    expect(within(row).queryByText(label)).toBeNull();
+    const added = within(rowOf(ifRail(), 'dashboard', 'wins')!).getByTestId('customization-mark');
+    expect(added).toHaveAccessibleName(t('engine.customizationMark.added', 'en'));
+    expect(added.textContent).toBe('');
+  });
+});
+
 describe('the Data rail lists the pair’s objects with the base’s (objectstack#28572)', () => {
   it('marks the pair’s object "added"; the base’s objects carry no mark; opening it names the pair', async () => {
     renderAt(`/studio/${BASE}/data`);
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
index b9c798027bb..6245c75513a 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
@@ -13,14 +13,21 @@
  * the other actions are fixed, the chip is as wide as its form, and the
  * title's box is the room the row leaves it, capped at its text. Gaps read 0
  * (no stylesheet).
+ *
+ * objectstack#29693 (the last describe block) — the title keeps a readable
+ * width: when the row would leave it less than its first twelve characters,
+ * the identity chips and the item tools fold into the ⋯ menu. The same stubbed
+ * row, with the tools (the header's fold contract, as `StudioItemTools` keeps
+ * it) and the header's own ⋯ as boxes of their own, and the twelve
+ * characters' width stubbed on the text range.
  */
 
 import '@testing-library/jest-dom/vitest';
 import * as React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { act, cleanup, render, screen } from '@testing-library/react';
+import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react';
 import { Workflow } from 'lucide-react';
-import { StudioItemHeader, useStudioTabRowFold } from './StudioItemHeader';
+import { StudioItemHeader, useStudioItemHeaderFold, useStudioTabRowFold, type StudioFoldedTool } from './StudioItemHeader';
 import { STUDIO_KIND_CHIP } from './studio-tokens';
 
 const TITLE = 'Task board (kanban view)';
@@ -33,6 +40,9 @@ const OPEN_IN_DATA = 137;
 const CHIP_FULL = 132;
 const CHIP_FOLDED = 28;
 const TITLE_TEXT = 178;
+/** objectstack#29693 — the item tools' button group, and the header's own ⋯. */
+const TOOLS = 146;
+const OWN_MORE = 32;
 const layout = { row: 632 };
 
 const resizeCallbacks = new Set<() => void>();
@@ -46,9 +56,16 @@ const chipWidth = () => {
   const chip = screen.queryByTestId('probe-chip');
   return chip ? (chip.hasAttribute('data-folded') ? CHIP_FOLDED : CHIP_FULL) : 0;
 };
-const actionsWidth = () => chipWidth() + OPEN_IN_DATA;
+const toolsWidth = () => (screen.queryByTestId('probe-tools') ? TOOLS : 0);
+const ownMoreWidth = () => (screen.queryByTestId('hdr-more') ? OWN_MORE : 0);
+const actionsWidth = () => chipWidth() + OPEN_IN_DATA + toolsWidth() + ownMoreWidth();
+/** The kind chip, while the row holds it (objectstack#29693: it can fold into the menu). */
+const kindChipWidth = () => {
+  const chip = screen.queryByTestId('hdr-kind-chip');
+  return chip && !chip.closest('[role="menu"]') ? KIND_CHIP : 0;
+};
 /** The title's box: what the row leaves it, capped at its text. */
-const titleBox = () => Math.max(0, Math.min(TITLE_TEXT, layout.row - ICON - KIND_CHIP - actionsWidth()));
+const titleBox = () => Math.max(0, Math.min(TITLE_TEXT, layout.row - ICON - kindChipWidth() - actionsWidth()));
 
 beforeEach(() => {
   layout.row = 632;
@@ -72,8 +89,13 @@ beforeEach(() => {
       if (isRow(this)) return rect(layout.row);
       if (this.dataset.testid === 'probe-chip') return rect(chipWidth());
       if (this.dataset.testid === 'hdr-kind-chip') return rect(KIND_CHIP);
+      if (this.dataset.testid === 'probe-tools') return rect(TOOLS);
+      if (this.dataset.testid === 'hdr-more') return rect(OWN_MORE);
       if (this.dataset.testid === 'hdr-title') return rect(titleBox());
       if (this.parentElement && isRow(this.parentElement)) {
+        // The identity chips' wrapper is a `contents` box in the console;
+        // with no stylesheet here it is a box as wide as the chips it holds.
+        if (this.dataset.slot === 'identity-chips') return rect(kindChipWidth());
         if (this.tagName === 'SPAN') return rect(ICON);
         if (this.tagName === 'DIV') return rect(actionsWidth());
       }
@@ -179,3 +201,129 @@ describe('a foldable chip in the title row gives way before the title (objectui#
     expect(screen.getByTestId('hdr-title')).toHaveAttribute('title', `${TITLE}\n${INTERNAL_ID}`);
   });
 });
+
+/** objectstack#29693 — the twelve characters' width the text range answers. */
+const READABLE = 120;
+
+/**
+ * The item tools as `StudioItemTools` keeps the header's fold contract: the
+ * button group (`data-studio-fold`) leaves the row while the header is
+ * folded, and the tools are handed over as menu items.
+ */
+function ProbeTools({ onOpen }: { onOpen: (id: string) => void }) {
+  const fold = useStudioItemHeaderFold();
+  const setTools = fold?.setTools;
+  React.useEffect(() => {
+    if (!setTools) return;
+    const tools: StudioFoldedTool[] = [
+      { id: 'layers', label: 'Layers', icon: Workflow, onSelect: () => onOpen('layers') },
+      { id: 'references', label: 'References', icon: Workflow, count: 3, onSelect: () => onOpen('references') },
+    ];
+    setTools(tools);
+    return () => setTools(null);
+  }, [setTools, onOpen]);
+  if (fold?.folded) return null;
+  return <div data-testid="probe-tools" data-studio-fold="tools" />;
+}
+
+function FoldingLeaf({ onOpen = () => {}, foldMenu = true }: { onOpen?: (id: string) => void; foldMenu?: boolean }) {
+  return (
+    <StudioItemHeader
+      icon={Workflow}
+      title={TITLE}
+      titleProps={{ 'data-testid': 'hdr-title', title: INTERNAL_ID }}
+      chips={
+        <span className={STUDIO_KIND_CHIP} data-testid="hdr-kind-chip">
+          View
+        </span>
+      }
+      foldMenu={foldMenu ? { label: 'More', testId: 'hdr-more' } : undefined}
+      actions={
+        <>
+          <ProbeTools onOpen={onOpen} />
+          <button type="button">Open in Data</button>
+        </>
+      }
+    />
+  );
+}
+
+/** Open the header's own ⋯ (Radix opens a menu on pointer down). */
+function openOwnMore(): HTMLElement {
+  const trigger = screen.getByTestId('hdr-more');
+  fireEvent.pointerDown(trigger, { button: 0, ctrlKey: false, pointerType: 'mouse' });
+  return screen.getByRole('menu');
+}
+
+describe('the title keeps a readable width: chips and item tools fold into the ⋯ menu first (objectstack#29693)', () => {
+  let rangeSpy: { mockRestore: () => void } | null = null;
+  beforeEach(() => {
+    rangeSpy = vi.spyOn(Range.prototype, 'getBoundingClientRect').mockImplementation(() => rect(READABLE));
+  });
+  afterEach(() => {
+    rangeSpy?.mockRestore();
+    rangeSpy = null;
+  });
+
+  it('at a 330 px row the kind chip and the tools leave the row, a ⋯ holds them, and the title keeps its twelve characters', () => {
+    layout.row = 330;
+    render(<FoldingLeaf />);
+    // Shown, they would leave the title 330 − 32 − 38 − 146 − 137 = −23 px.
+    // Folded, 330 − 32 − 137 − 32 = 129 px: at least the 120 px of twelve characters.
+    expect(screen.queryByTestId('probe-tools')).toBeNull();
+    expect(screen.queryByTestId('hdr-kind-chip')).toBeNull();
+    expect(screen.getByTestId('hdr-more')).toHaveAccessibleName('More');
+    expect(titleBox()).toBeGreaterThanOrEqual(READABLE);
+  });
+
+  it('the ⋯ menu holds the folded chips and the tools, and a tool opens from it', () => {
+    layout.row = 330;
+    const onOpen = vi.fn();
+    render(<FoldingLeaf onOpen={onOpen} />);
+    const menu = openOwnMore();
+    expect(within(menu).getByTestId('studio-item-header-folded-chips')).toContainElement(within(menu).getByTestId('hdr-kind-chip'));
+    expect(within(menu).getAllByRole('menuitem').map((el) => el.getAttribute('data-testid'))).toEqual([
+      'studio-item-tool-layers',
+      'studio-item-tool-references',
+    ]);
+    expect(within(menu).getByTestId('studio-item-tool-references')).toHaveTextContent('References3');
+    fireEvent.click(within(menu).getByTestId('studio-item-tool-references'));
+    expect(onOpen).toHaveBeenCalledWith('references');
+  });
+
+  it('it follows the row: folds when the row narrows, comes back when the title would keep its width beside them', () => {
+    render(<FoldingLeaf />);
+    expect(screen.getByTestId('probe-tools')).toBeInTheDocument();
+    expect(screen.queryByTestId('hdr-more')).toBeNull();
+    resizeRow(330);
+    expect(screen.queryByTestId('probe-tools')).toBeNull();
+    // 480 − 32 − 38 − 146 − 137 = 127 px with them back: they come back.
+    resizeRow(480);
+    expect(screen.getByTestId('probe-tools')).toBeInTheDocument();
+    expect(screen.getByTestId('hdr-kind-chip')).toBeInTheDocument();
+    expect(screen.queryByTestId('hdr-more')).toBeNull();
+  });
+
+  it('CONTROL: at 470 px the title would keep only 117 px beside them: they stay folded', () => {
+    render(<FoldingLeaf />);
+    resizeRow(330);
+    resizeRow(470);
+    expect(screen.queryByTestId('probe-tools')).toBeNull();
+    expect(screen.getByTestId('hdr-more')).toBeInTheDocument();
+  });
+
+  it('CONTROL: at a 632 px row the title has its room: nothing folds and there is no ⋯ of the header’s own', () => {
+    render(<FoldingLeaf />);
+    expect(screen.getByTestId('probe-tools')).toBeInTheDocument();
+    expect(screen.getByTestId('hdr-kind-chip')).toBeInTheDocument();
+    expect(screen.queryByTestId('hdr-more')).toBeNull();
+  });
+
+  it('CONTROL: a header whose pillar names no fold menu folds nothing (the title is cut instead)', () => {
+    layout.row = 330;
+    render(<FoldingLeaf foldMenu={false} />);
+    expect(screen.getByTestId('probe-tools')).toBeInTheDocument();
+    expect(screen.getByTestId('hdr-kind-chip')).toBeInTheDocument();
+    expect(screen.getByTestId('hdr-title')).toHaveAttribute('title', `${TITLE}\n${INTERNAL_ID}`);
+  });
+});

From 9f0bf15bd3dc4ca543e7867fd33944fd74be32ed Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 02:29:54 +0000
Subject: [PATCH 03/12] feat(app-shell): a second fold stage turns the item
 header's labelled actions icon-only

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 .../29693-studio-item-header-readable-name.md |  12 ++
 .../views/studio-design/FlowLedgerSwitch.tsx  |  14 ++-
 .../studio-design/StudioCustomizeControls.tsx |   6 +-
 .../studio-design/StudioDesignSurface.tsx     |  15 ++-
 .../views/studio-design/StudioItemHeader.tsx  | 105 +++++++++++++-----
 .../src/views/studio-design/studio-tokens.ts  |  10 ++
 6 files changed, 126 insertions(+), 36 deletions(-)
 create mode 100644 .changeset/29693-studio-item-header-readable-name.md

diff --git a/.changeset/29693-studio-item-header-readable-name.md b/.changeset/29693-studio-item-header-readable-name.md
new file mode 100644
index 00000000000..c277627822e
--- /dev/null
+++ b/.changeset/29693-studio-item-header-readable-name.md
@@ -0,0 +1,12 @@
+---
+'@object-ui/app-shell': patch
+---
+
+feat(app-shell): a Studio item header keeps the item's name readable; its chips and item tools fold into the ⋯ menu first
+
+Clause-②: no
+Metadata-protocol: none
+
+On a narrow content column (a laptop window with the right panel open) the item header's title row no longer cuts the item's name to one character. The title keeps its first twelve characters (its whole name when shorter). When the row cannot give it that, the identity chips (the api-name chip, the kind chip, the override and pair chips) and the five item tools (Layers, References, History, Audit, Source) leave the row and read at the top of the item's ⋯ menu instead, the tools as menu items opening the same sheets. The Interfaces and Automations headers fold into their own ⋯ menu; the Data header, which has none, draws one for them while they are folded. With the row's boxes fitting the row again, the ⋯ trigger stays inside the column instead of under the right panel. The draft status chip stays in the row. `StudioItemHeader` takes this as a `foldMenu` prop and exports `StudioItemHeaderFoldedItems` for a pillar's own menu; a header without `foldMenu` is unchanged.
+
+The pillar rails draw the customization mark as its glyph alone ("Customized (BASE)" and "Added" are its accessible name and lead its tooltip), so a customized row keeps its label. The All metadata lists keep the mark's text.
diff --git a/ui/packages/app-shell/src/views/studio-design/FlowLedgerSwitch.tsx b/ui/packages/app-shell/src/views/studio-design/FlowLedgerSwitch.tsx
index d907dedeeb6..1d35dcf5066 100644
--- a/ui/packages/app-shell/src/views/studio-design/FlowLedgerSwitch.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/FlowLedgerSwitch.tsx
@@ -33,6 +33,7 @@ import * as React from 'react';
 import { Power } from 'lucide-react';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@object-ui/components';
 import { t } from '../metadata-admin/i18n.js';
+import { STUDIO_FOLD_LABEL } from './studio-tokens.js';
 import type { ActivationReading } from '../setup/packagedFlows.js';
 
 export function FlowLedgerSwitch({ checked, reading, notRunningReason, busy, walledReason, locale, onToggle }: {
@@ -99,11 +100,14 @@ export function FlowLedgerSwitch({ checked, reading, notRunningReason, busy, wal
         />
       </span>
       <Power className="h-3 w-3 shrink-0" aria-hidden="true" />
-      {reading === 'on'
-        ? t('engine.studio.auto.ledger.on', locale)
-        : notRunning
-          ? t('engine.studio.auto.ledger.notRunning', locale)
-          : t('engine.studio.auto.ledger.off', locale)}
+      {/* objectstack#29693 — on a narrow item header the switch keeps its track and glyph; the word stays its name. */}
+      <span data-studio-fold-label="" className={STUDIO_FOLD_LABEL}>
+        {reading === 'on'
+          ? t('engine.studio.auto.ledger.on', locale)
+          : notRunning
+            ? t('engine.studio.auto.ledger.notRunning', locale)
+            : t('engine.studio.auto.ledger.off', locale)}
+      </span>
     </button>
   );
   const hintLine = (
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
index ae232ba8712..858d0663ee9 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
@@ -58,6 +58,7 @@ import {
 import { Layers, Pencil, RotateCcw } from 'lucide-react';
 import { postureHasOrgWall, useTenancyPosture } from '../../hooks/useTenancyPosture.js';
 import { t, tFormat } from '../metadata-admin/i18n.js';
+import { STUDIO_FOLD_LABEL } from './studio-tokens.js';
 import { readFields, writeFields, type FieldEntry } from '../metadata-admin/previews/object-fields-io.js';
 
 /**
@@ -241,7 +242,10 @@ export function StudioCustomizeButton({
       )}
     >
       <Pencil className="h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true" />
-      {t('engine.studio.customize.action', locale)}
+      {/* objectstack#29693 — on a narrow item header the button keeps its glyph; the word stays its name. */}
+      <span data-studio-fold-label="" className={STUDIO_FOLD_LABEL}>
+        {t('engine.studio.customize.action', locale)}
+      </span>
     </button>
   );
   if (reason === null) return button;
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
index 0015b0185b1..f0200350129 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
@@ -56,6 +56,7 @@ import {
 } from '../../layout/chatDockState.js';
 import { AppMark, type AppMarkApp } from '../../layout/AppMark.js';
 import {
+  STUDIO_FOLD_LABEL,
   STUDIO_HEADER,
   STUDIO_HEADER_ICON_BUTTON,
   STUDIO_HEADER_PACKAGE_COLUMN,
@@ -5999,7 +6000,10 @@ export function InterfacesPillar({
         }
       >
         <Pencil className="h-3 w-3" aria-hidden="true" />
-        {t('engine.studio.if.modeDesign', locale)}
+        {/* objectstack#29693 — on a narrow header the modes keep their glyphs; the words stay their names. */}
+        <span data-studio-fold-label="" className={STUDIO_FOLD_LABEL}>
+          {t('engine.studio.if.modeDesign', locale)}
+        </span>
       </button>
       <button
         type="button"
@@ -6013,7 +6017,9 @@ export function InterfacesPillar({
         }
       >
         <Play className="h-3 w-3" aria-hidden="true" />
-        {t('engine.studio.if.modeRun', locale)}
+        <span data-studio-fold-label="" className={STUDIO_FOLD_LABEL}>
+          {t('engine.studio.if.modeRun', locale)}
+        </span>
       </button>
     </div>
   );
@@ -10939,7 +10945,10 @@ export function AutomationsPillar({
                 <span className={'inline-block h-4 w-4 rounded-full bg-white shadow-sm transition-transform ' + (flowEnabled ? 'translate-x-[18px]' : 'translate-x-0.5')} />
               </span>
               {readOnly && <Lock className="h-3 w-3 shrink-0" aria-hidden="true" />}
-              {flowEnabled ? t('engine.studio.auto.enabled', locale) : t('engine.studio.auto.disabled', locale)}
+              {/* objectstack#29693 — on a narrow header the switch keeps its track; the word stays its name. */}
+              <span data-studio-fold-label="" className={STUDIO_FOLD_LABEL}>
+                {flowEnabled ? t('engine.studio.auto.enabled', locale) : t('engine.studio.auto.disabled', locale)}
+              </span>
             </button>
           );
           const defaultOffLine = <span className="sr-only">{defaultOff}</span>;
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
index 969b0b76924..efd94077c9e 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
@@ -412,8 +412,8 @@ export function useStudioItemHeaderFold(): Pick<StudioItemHeaderFoldValue, 'fold
 
 /**
  * objectstack#29693 — what the title row folded away, at the top of a ⋯
- * menu: the identity chips as they read in the row, then the item tools as
- * menu items, then a separator before the menu's own items. Nothing while the
+ * menu: the identity chips as they read in the row (one entry), then the item
+ * tools as menu items, then a separator before the menu's own items. Nothing while the
  * row holds them. A pillar whose actions end with its own ⋯ menu mounts this
  * in that menu's content and passes `foldMenu="pillar"`.
  */
@@ -424,11 +424,18 @@ export function StudioItemHeaderFoldedItems({ separator = true }: { separator?:
   if (!hasChips && fold.tools.length === 0) return null;
   return (
     <>
+      {/* One menu entry, reachable by the keys like the others; choosing it
+          keeps the menu open, so a chip with its own control (the override
+          chip) is used from here as from the row. */}
       {hasChips && (
-        <div data-testid="studio-item-header-folded-chips" className="flex flex-wrap items-center gap-1.5 px-2 py-1.5">
+        <DropdownMenuItem
+          data-testid="studio-item-header-folded-chips"
+          onSelect={(event) => event.preventDefault()}
+          className="flex flex-wrap items-center gap-1.5"
+        >
           {fold.apiName && <StudioApiChip apiName={fold.apiName} />}
           {fold.chips}
-        </div>
+        </DropdownMenuItem>
       )}
       {fold.tools.map(({ id, label, icon: Icon, count, onSelect }) => (
         <DropdownMenuItem key={id} data-testid={`studio-item-tool-${id}`} onSelect={onSelect}>
@@ -443,40 +450,82 @@ export function StudioItemHeaderFoldedItems({ separator = true }: { separator?:
 }
 
 /**
- * objectstack#29693 — whether the title row folds its identity chips and item
- * tools into the ⋯ menu: when the room it leaves the title, with them shown,
- * is less than the title's readable width. Folded, it remembers how wide they
- * were, and shows them again once the title would keep that width beside
- * them (`ownTrigger`: the header's own ⋯, which goes when they come back).
+ * objectstack#29693 — how far the title row has folded: `0` nothing; `1` the
+ * identity chips and the item tools are in the ⋯ menu; `2` the header's
+ * labelled actions show their icon alone too (`STUDIO_FOLD_LABEL`).
+ */
+type TitleRowFoldStage = 0 | 1 | 2;
+
+/** The width the labelled actions' labels take (`data-studio-fold-label`). */
+function foldLabelWidth(row: HTMLElement): number {
+  let width = 0;
+  for (const el of Array.from(row.querySelectorAll('[data-studio-fold-label]'))) width += el.getBoundingClientRect().width;
+  return width;
+}
+
+/**
+ * objectstack#29693 — how far the title row folds so the title keeps its
+ * readable width. Each stage is taken while the room the row leaves the title
+ * is less than that width: first the identity chips and the item tools leave
+ * for the ⋯ menu, then the labelled actions drop their labels. Each step reads
+ * the room it freed (the room after it, less the room before), so it is given
+ * back only once the title would keep its width without that room: the step
+ * never undoes itself the moment it is taken. A title still short after both
+ * is cut, its whole text in its tooltip (objectui#12897); the ⋯ stays in the
+ * row.
  */
 function useTitleRowFold(
   enabled: boolean,
   row: React.RefObject<HTMLElement | null>,
   title: React.RefObject<HTMLElement | null>,
-  ownTrigger: React.RefObject<HTMLElement | null>,
-): boolean {
-  const [folded, setFolded] = React.useState(false);
-  /** The foldable boxes' width, read while they were shown. */
-  const shown = React.useRef(0);
+): TitleRowFoldStage {
+  const [stage, setStage] = React.useState<TitleRowFoldStage>(0);
+  /**
+   * `freed[0]`: the room the first stage freed; `freed[1]`: the second's.
+   * `pending`: a step just taken, with the room before it, read on the next
+   * measure.
+   */
+  const memo = React.useRef<{ freed: [number, number]; pending: { step: 0 | 1; before: number } | null }>({
+    freed: [0, 0],
+    pending: null,
+  });
   const measureRef = React.useRef<() => void>(() => {});
   // Every render: the chips and the actions can change without the row resizing.
   React.useLayoutEffect(() => {
     const measure = () => {
       const rowEl = row.current;
       const titleEl = title.current;
-      if (!enabled) return setFolded(false);
+      if (!enabled) return setStage(0);
       if (!rowEl || !titleEl) return;
       const readable = readableTitleWidth(titleEl);
       if (readable <= 0) return;
       const room = titleRoom(rowEl, titleEl);
-      if (!folded) {
-        shown.current = foldableWidth(rowEl);
-        if (shown.current <= 0) return;
-        return setFolded(room + 0.5 < readable);
+      const m = memo.current;
+      if (m.pending) {
+        m.freed[m.pending.step] = Math.max(0, room - m.pending.before);
+        m.pending = null;
       }
-      const trigger = ownTrigger.current;
-      const freed = trigger ? trigger.getBoundingClientRect().width + gapBeside(trigger) : 0;
-      setFolded(room - shown.current + freed + 0.5 < readable);
+      const short = (width: number) => width + 0.5 < readable;
+      const fold = (next: 1 | 2) => {
+        m.pending = { step: next === 1 ? 0 : 1, before: room };
+        if (next === 2 && stage === 0) m.freed[0] = 0;
+        setStage(next);
+      };
+      if (stage === 0) {
+        if (!short(room)) return;
+        if (foldableWidth(rowEl) > 0) return fold(1);
+        if (foldLabelWidth(rowEl) > 0) return fold(2);
+        return;
+      }
+      if (stage === 1) {
+        // A pixel of margin, so a row exactly at the edge does not flip.
+        if (!short(room - m.freed[0] - 1)) return setStage(0);
+        if (short(room) && foldLabelWidth(rowEl) > 0) fold(2);
+        return;
+      }
+      if (short(room - m.freed[1] - 1)) return;
+      if (m.freed[0] > 0) return setStage(short(room - m.freed[1] - m.freed[0] - 1) ? 1 : 0);
+      setStage(0);
     };
     measureRef.current = measure;
     measure();
@@ -489,7 +538,7 @@ function useTitleRowFold(
     if (title.current) observer.observe(title.current);
     return () => observer.disconnect();
   }, [row, title]);
-  return enabled && folded;
+  return enabled ? stage : 0;
 }
 
 export interface StudioItemHeaderProps {
@@ -554,8 +603,8 @@ export function StudioItemHeader({
   const titleTooltip = cutTitle ? [cutTitle, titleProps?.title].filter(Boolean).join('\n') : titleProps?.title;
   // objectstack#29693 — the identity chips and the item tools fold into the
   // ⋯ menu before the title drops below its readable width.
-  const ownTriggerRef = React.useRef<HTMLButtonElement | null>(null);
-  const folded = useTitleRowFold(foldMenu !== undefined, titleRowRef, titleRef, ownTriggerRef);
+  const foldStage = useTitleRowFold(foldMenu !== undefined, titleRowRef, titleRef);
+  const folded = foldStage > 0;
   const [tools, setToolsState] = React.useState<StudioFoldedTool[]>([]);
   const setTools = React.useCallback((next: StudioFoldedTool[] | null) => setToolsState(next ?? []), []);
   const foldValue = React.useMemo<StudioItemHeaderFoldValue | null>(
@@ -587,14 +636,16 @@ export function StudioItemHeader({
           </span>
         )}
         {(actions || (ownMenu && hasFolded)) && (
-          <div className="ml-auto flex shrink-0 items-center gap-2">
+          <div
+            className="group/item-actions ml-auto flex shrink-0 items-center gap-2"
+            data-fold={foldStage === 2 ? 'labels' : undefined}
+          >
             <StudioItemHeaderFoldContext.Provider value={foldValue}>
               <StudioFoldRowContext.Provider value={titleFold}>{actions}</StudioFoldRowContext.Provider>
               {ownMenu && hasFolded && (
                 <DropdownMenu>
                   <DropdownMenuTrigger asChild>
                     <button
-                      ref={ownTriggerRef}
                       type="button"
                       data-testid={ownMenu.testId}
                       aria-label={ownMenu.label}
diff --git a/ui/packages/app-shell/src/views/studio-design/studio-tokens.ts b/ui/packages/app-shell/src/views/studio-design/studio-tokens.ts
index ae09248d64e..d6e0ba88979 100644
--- a/ui/packages/app-shell/src/views/studio-design/studio-tokens.ts
+++ b/ui/packages/app-shell/src/views/studio-design/studio-tokens.ts
@@ -93,6 +93,16 @@ export const STUDIO_ICON_TILE = 'inline-flex h-8 w-8 shrink-0 items-center justi
 export const STUDIO_API_CHIP =
   'block h-[22px] min-w-[5ch] max-w-max basis-[14ch] grow-[1000] shrink-[100000] truncate rounded-[5px] bg-muted px-2 font-mono text-[11px] leading-[22px] text-muted-foreground ' +
   'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring';
+/**
+ * objectstack#29693 — the label of a labelled action in the item header's
+ * actions slot (the Customize button, a flow's switch, the canvas mode
+ * buttons). On a row whose title would drop below its readable width, after
+ * the chips and the item tools have gone to the ⋯ menu, the header marks its
+ * actions `data-fold="labels"` and the label leaves the row: the action shows
+ * its icon, and the label stays its accessible name. The label's element
+ * carries `data-studio-fold-label` too, so the header can measure it.
+ */
+export const STUDIO_FOLD_LABEL = 'group-data-[fold=labels]/item-actions:sr-only';
 export const STUDIO_KIND_CHIP = 'inline-flex h-[22px] shrink-0 items-center rounded-[5px] bg-muted px-2 text-[11px] font-medium text-muted-foreground';
 export const STUDIO_META = 'min-w-0 truncate text-xs text-muted-foreground';
 /**

From 08039a0c5fb0ef0a7c4201dd3202330b4b1f732f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 02:35:00 +0000
Subject: [PATCH 04/12] test(app-shell): pin the fold order, icon-only names
 and the folded tools' sheets

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 ...udioDesignSurface.itemTools-28239.test.tsx |  77 ++++++++++++
 ...udioItemHeader.titleRowFold-12897.test.tsx | 117 +++++++++++++++++-
 2 files changed, 191 insertions(+), 3 deletions(-)

diff --git a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.itemTools-28239.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.itemTools-28239.test.tsx
index f3c070b66cf..aebd4326a8c 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.itemTools-28239.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.itemTools-28239.test.tsx
@@ -126,6 +126,8 @@ vi.mock('@monaco-editor/react', () => {
 vi.mock('@object-ui/plugin-editor', () => ({ configureBundledMonaco: () => Promise.resolve() }));
 
 import { AutomationsPillar, DataPillar, InterfacesPillar } from './StudioDesignSurface';
+import { StudioItemHeader } from './StudioItemHeader';
+import { StudioItemTools } from '../item-tools/StudioItemTools';
 import { MetadataResourceEditPage } from '../metadata-admin/ResourceEditPage';
 import '../../services/builtinComponents.js';
 import { t } from '../metadata-admin/i18n';
@@ -305,3 +307,78 @@ describe("CONTROL — Setup's item page still opens the five from the shared dir
     expect(await screen.findByRole('textbox', { name: 'JSON source' }, { timeout: 8000 })).toBeInTheDocument();
   });
 });
+
+/**
+ * objectstack#29693 — on a row too narrow for the title's twelve characters,
+ * the five tools fold into the header's ⋯ menu. Each menu entry opens the same
+ * sheet its button opens, reading the same door. The row's geometry is stubbed
+ * (no layout here): a 100 px row, the button group 146 px wide, the title's
+ * whole text 200 px and its first twelve characters 120 px.
+ */
+describe('Studio item toolbar — folded into the header’s ⋯ menu, each tool opens the same sheet (objectstack#29693)', () => {
+  const spies: Array<{ mockRestore: () => void }> = [];
+  const box = (width: number) => ({ left: 0, right: width, width, top: 0, bottom: 32, height: 32, x: 0, y: 0, toJSON: () => ({}) }) as DOMRect;
+  beforeEach(() => {
+    const realRect = HTMLElement.prototype.getBoundingClientRect;
+    spies.push(
+      vi.spyOn(Range.prototype, 'getBoundingClientRect').mockImplementation(() => box(120)),
+      vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockImplementation(function (this: HTMLElement) {
+        return this.classList.contains('@container') ? 100 : 0;
+      }),
+      vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+        return this.dataset.testid === 'studio-item-tools' ? box(146) : realRect.call(this);
+      }),
+      // The title's whole text, wider than its twelve characters.
+      vi.spyOn(HTMLElement.prototype, 'scrollWidth', 'get').mockImplementation(function (this: HTMLElement) {
+        return this.tagName === 'H1' ? 200 : 0;
+      }),
+    );
+  });
+  afterEach(() => {
+    for (const spy of spies.splice(0)) spy.mockRestore();
+  });
+
+  it('Layers, References, History, Audit and Source open from the menu on object/showcase_account', async () => {
+    render(
+      <MemoryRouter>
+        <StudioItemHeader
+          title="Account"
+          foldMenu={{ label: 'More', testId: 'hdr-more' }}
+          actions={<StudioItemTools type="object" name="showcase_account" packageId={PKG} locale="en" />}
+        />
+      </MemoryRouter>,
+    );
+    await waitFor(() => expect(screen.queryByTestId('studio-item-tools')).toBeNull());
+    const pick = async (tool: string) => {
+      fireEvent.pointerDown(screen.getByTestId('hdr-more'), { button: 0, ctrlKey: false, pointerType: 'mouse' });
+      fireEvent.click(within(await screen.findByRole('menu')).getByTestId(`studio-item-tool-${tool}`));
+      return screen.findByTestId(`studio-item-tool-sheet-${tool}`);
+    };
+    const close = async () => {
+      fireEvent.keyDown(document.activeElement ?? document.body, { key: 'Escape' });
+      await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+    };
+
+    const layers = await pick('layers');
+    expect(await within(layers).findByRole('tab', { name: t('engine.layers.diff', 'en') })).toBeInTheDocument();
+    expect(mockClient.layered).toHaveBeenCalledWith('object', 'showcase_account', { packageId: PKG });
+    await close();
+
+    const refs = await pick('references');
+    expect(await within(refs).findByText('all_accounts')).toBeInTheDocument();
+    expect(mockClient.references).toHaveBeenCalledWith('object', 'showcase_account');
+    await close();
+
+    const history = await pick('history');
+    expect(await within(history).findAllByTitle(ROLLBACK)).toHaveLength(2);
+    await close();
+
+    await pick('audit');
+    await waitFor(() => expect(mockClient.audit).toHaveBeenCalledWith('object', 'showcase_account', { limit: 100 }));
+    await close();
+
+    const source = await pick('source');
+    const editor = await within(source).findByRole('textbox', { name: 'JSON source' }, { timeout: 8000 });
+    expect((editor as HTMLTextAreaElement).value).toContain('"name": "showcase_account"');
+  });
+});
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
index 6245c75513a..73822c54fd6 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
@@ -28,7 +28,10 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react';
 import { Workflow } from 'lucide-react';
 import { StudioItemHeader, useStudioItemHeaderFold, useStudioTabRowFold, type StudioFoldedTool } from './StudioItemHeader';
-import { STUDIO_KIND_CHIP } from './studio-tokens';
+import { STUDIO_FOLD_LABEL, STUDIO_KIND_CHIP } from './studio-tokens';
+import { StudioCustomizeButton } from './StudioCustomizeControls';
+import { FlowLedgerSwitch } from './FlowLedgerSwitch';
+import { t } from '../metadata-admin/i18n';
 
 const TITLE = 'Task board (kanban view)';
 const INTERNAL_ID = 'Internal id: object · showcase_task';
@@ -43,6 +46,9 @@ const TITLE_TEXT = 178;
 /** objectstack#29693 — the item tools' button group, and the header's own ⋯. */
 const TOOLS = 146;
 const OWN_MORE = 32;
+/** objectstack#29693 — a labelled action: its glyph, and its label while the row shows labels. */
+const ACTION_GLYPH = 28;
+const ACTION_LABEL = 60;
 const layout = { row: 632 };
 
 const resizeCallbacks = new Set<() => void>();
@@ -58,7 +64,11 @@ const chipWidth = () => {
 };
 const toolsWidth = () => (screen.queryByTestId('probe-tools') ? TOOLS : 0);
 const ownMoreWidth = () => (screen.queryByTestId('hdr-more') ? OWN_MORE : 0);
-const actionsWidth = () => chipWidth() + OPEN_IN_DATA + toolsWidth() + ownMoreWidth();
+const labelsShown = () => !document.querySelector('[data-fold="labels"]');
+/** The labelled actions (the Customize button, the ledger switch): glyph, plus label while shown. */
+const labelledWidth = () =>
+  document.querySelectorAll('[data-studio-fold-label]').length * (ACTION_GLYPH + (labelsShown() ? ACTION_LABEL : 0));
+const actionsWidth = () => chipWidth() + OPEN_IN_DATA + toolsWidth() + ownMoreWidth() + labelledWidth();
 /** The kind chip, while the row holds it (objectstack#29693: it can fold into the menu). */
 const kindChipWidth = () => {
   const chip = screen.queryByTestId('hdr-kind-chip');
@@ -91,6 +101,7 @@ beforeEach(() => {
       if (this.dataset.testid === 'hdr-kind-chip') return rect(KIND_CHIP);
       if (this.dataset.testid === 'probe-tools') return rect(TOOLS);
       if (this.dataset.testid === 'hdr-more') return rect(OWN_MORE);
+      if (this.hasAttribute('data-studio-fold-label')) return rect(labelsShown() ? ACTION_LABEL : 1);
       if (this.dataset.testid === 'hdr-title') return rect(titleBox());
       if (this.parentElement && isRow(this.parentElement)) {
         // The identity chips' wrapper is a `contents` box in the console;
@@ -226,7 +237,20 @@ function ProbeTools({ onOpen }: { onOpen: (id: string) => void }) {
   return <div data-testid="probe-tools" data-studio-fold="tools" />;
 }
 
-function FoldingLeaf({ onOpen = () => {}, foldMenu = true }: { onOpen?: (id: string) => void; foldMenu?: boolean }) {
+function FoldingLeaf({
+  onOpen = () => {},
+  foldMenu = true,
+  labelled = false,
+  onCustomize = () => {},
+  onToggle = () => {},
+}: {
+  onOpen?: (id: string) => void;
+  foldMenu?: boolean;
+  /** The labelled actions a pillar draws: the Customize button and a flow's ledger switch. */
+  labelled?: boolean;
+  onCustomize?: () => void;
+  onToggle?: () => void;
+}) {
   return (
     <StudioItemHeader
       icon={Workflow}
@@ -240,6 +264,8 @@ function FoldingLeaf({ onOpen = () => {}, foldMenu = true }: { onOpen?: (id: str
       foldMenu={foldMenu ? { label: 'More', testId: 'hdr-more' } : undefined}
       actions={
         <>
+          {labelled && <StudioCustomizeButton block={null} baseLabel="HotCRM" locale="en" onCustomize={onCustomize} />}
+          {labelled && <FlowLedgerSwitch checked reading="on" locale="en" onToggle={onToggle} />}
           <ProbeTools onOpen={onOpen} />
           <button type="button">Open in Data</button>
         </>
@@ -283,6 +309,7 @@ describe('the title keeps a readable width: chips and item tools fold into the 
     const menu = openOwnMore();
     expect(within(menu).getByTestId('studio-item-header-folded-chips')).toContainElement(within(menu).getByTestId('hdr-kind-chip'));
     expect(within(menu).getAllByRole('menuitem').map((el) => el.getAttribute('data-testid'))).toEqual([
+      'studio-item-header-folded-chips',
       'studio-item-tool-layers',
       'studio-item-tool-references',
     ]);
@@ -327,3 +354,87 @@ describe('the title keeps a readable width: chips and item tools fold into the 
     expect(screen.getByTestId('hdr-title')).toHaveAttribute('title', `${TITLE}\n${INTERNAL_ID}`);
   });
 });
+
+describe('the fold order: chips and tools, then labels, then the title (objectstack#29693)', () => {
+  let rangeSpy: { mockRestore: () => void } | null = null;
+  beforeEach(() => {
+    rangeSpy = vi.spyOn(Range.prototype, 'getBoundingClientRect').mockImplementation(() => rect(READABLE));
+  });
+  afterEach(() => {
+    rangeSpy?.mockRestore();
+    rangeSpy = null;
+  });
+
+  const customize = () => screen.getByTestId('studio-customize');
+  const ledger = () => screen.getByTestId('auto-ledger-switch');
+  const actions = () => screen.getByTestId('hdr-title').parentElement!.lastElementChild as HTMLElement;
+
+  it('stage 1 first: at 560 px the chips and the tools fold, and the labelled actions keep their labels', () => {
+    layout.row = 560;
+    render(<FoldingLeaf labelled />);
+    // Shown: 560 − 32 − 38 − 2 × 88 − 146 − 137 = 31 px. Chips and tools folded: 560 − 32 − 176 − 137 − 32 = 183 px.
+    expect(screen.queryByTestId('probe-tools')).toBeNull();
+    expect(screen.queryByTestId('hdr-kind-chip')).toBeNull();
+    expect(actions()).not.toHaveAttribute('data-fold');
+    expect(titleBox()).toBe(TITLE_TEXT);
+  });
+
+  it('stage 2 next: at 420 px the labels leave too, and the title keeps its twelve characters', () => {
+    layout.row = 420;
+    render(<FoldingLeaf labelled />);
+    // Stage 1 leaves 420 − 32 − 176 − 137 − 32 = 43 px; without the labels, 163 px.
+    expect(screen.queryByTestId('probe-tools')).toBeNull();
+    expect(actions()).toHaveAttribute('data-fold', 'labels');
+    expect(titleBox()).toBeGreaterThanOrEqual(READABLE);
+  });
+
+  it('the title is cut last: at 300 px both stages are taken and the ⋯ stays in the row', () => {
+    layout.row = 300;
+    render(<FoldingLeaf labelled />);
+    expect(actions()).toHaveAttribute('data-fold', 'labels');
+    expect(screen.getByTestId('hdr-more')).toBeInTheDocument();
+    expect(titleBox()).toBeLessThan(READABLE);
+    expect(screen.getByTestId('hdr-title')).toHaveAttribute('title', `${TITLE}\n${INTERNAL_ID}`);
+  });
+
+  it('unfolds in reverse: the labels come back before the chips and the tools', () => {
+    layout.row = 420;
+    render(<FoldingLeaf labelled />);
+    expect(actions()).toHaveAttribute('data-fold', 'labels');
+    resizeRow(560);
+    expect(actions()).not.toHaveAttribute('data-fold');
+    expect(screen.queryByTestId('probe-tools')).toBeNull();
+    resizeRow(700);
+    expect(screen.getByTestId('probe-tools')).toBeInTheDocument();
+    expect(screen.getByTestId('hdr-kind-chip')).toBeInTheDocument();
+  });
+
+  it('icon-only, each labelled action keeps its label as its accessible name, and fires the same action', () => {
+    layout.row = 420;
+    const onCustomize = vi.fn();
+    const onToggle = vi.fn();
+    render(<FoldingLeaf labelled onCustomize={onCustomize} onToggle={onToggle} />);
+    expect(actions()).toHaveAttribute('data-fold', 'labels');
+    for (const label of document.querySelectorAll('[data-studio-fold-label]')) {
+      expect(label.className).toBe(STUDIO_FOLD_LABEL);
+    }
+    expect(customize()).toHaveAccessibleName(t('engine.studio.customize.action', 'en'));
+    expect(ledger()).toHaveAccessibleName(t('engine.studio.auto.ledger.on', 'en'));
+    // Customize keeps the first slot of the actions.
+    expect(actions().firstElementChild).toBe(customize());
+    fireEvent.click(customize());
+    fireEvent.click(ledger());
+    expect(onCustomize).toHaveBeenCalledTimes(1);
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('the folded chips are one menu entry, and choosing it keeps the menu open', () => {
+    layout.row = 330;
+    render(<FoldingLeaf />);
+    const menu = openOwnMore();
+    const entry = within(menu).getByTestId('studio-item-header-folded-chips');
+    expect(entry).toHaveAttribute('role', 'menuitem');
+    fireEvent.click(entry);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+  });
+});

From 00f95d97d459886ed0a1eb24701ed28ba3af8c32 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 03:00:22 +0000
Subject: [PATCH 05/12] chore: describe the second fold stage in the changeset

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 .changeset/29693-studio-item-header-readable-name.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.changeset/29693-studio-item-header-readable-name.md b/.changeset/29693-studio-item-header-readable-name.md
index c277627822e..e002c3f4d4f 100644
--- a/.changeset/29693-studio-item-header-readable-name.md
+++ b/.changeset/29693-studio-item-header-readable-name.md
@@ -2,11 +2,11 @@
 '@object-ui/app-shell': patch
 ---
 
-feat(app-shell): a Studio item header keeps the item's name readable; its chips and item tools fold into the ⋯ menu first
+feat(app-shell): a Studio item header keeps the item's name readable; its chips, item tools and action labels give way first
 
 Clause-②: no
 Metadata-protocol: none
 
-On a narrow content column (a laptop window with the right panel open) the item header's title row no longer cuts the item's name to one character. The title keeps its first twelve characters (its whole name when shorter). When the row cannot give it that, the identity chips (the api-name chip, the kind chip, the override and pair chips) and the five item tools (Layers, References, History, Audit, Source) leave the row and read at the top of the item's ⋯ menu instead, the tools as menu items opening the same sheets. The Interfaces and Automations headers fold into their own ⋯ menu; the Data header, which has none, draws one for them while they are folded. With the row's boxes fitting the row again, the ⋯ trigger stays inside the column instead of under the right panel. The draft status chip stays in the row. `StudioItemHeader` takes this as a `foldMenu` prop and exports `StudioItemHeaderFoldedItems` for a pillar's own menu; a header without `foldMenu` is unchanged.
+On a narrow content column (a laptop window with the right panel open) the item header's title row no longer cuts the item's name to nothing. The title keeps its first twelve characters (its whole name when shorter), and the row gives way in two steps before the title does. First the identity chips (the api-name chip, the kind chip, the override and pair chips) and the five item tools (Layers, References, History, Audit, Source) leave the row and read at the top of the item's ⋯ menu: the chips as one entry, the tools as menu items opening the same sheets. Then the labelled actions (Customize, a flow's on/off switches, the Design and Run buttons) show their icon alone, the label staying their accessible name. The Interfaces and Automations headers fold into their own ⋯ menu; the Data header, which has none, draws one while something is folded. With the row's boxes fitting the row again, the ⋯ trigger stays inside the column instead of under the right panel. The draft status chip stays in the row. `StudioItemHeader` takes this as a `foldMenu` prop and exports `StudioItemHeaderFoldedItems` for a pillar's own menu; a header without `foldMenu` is unchanged.
 
 The pillar rails draw the customization mark as its glyph alone ("Customized (BASE)" and "Added" are its accessible name and lead its tooltip), so a customized row keeps its label. The All metadata lists keep the mark's text.

From 9ee9fbd77f4c5fbc8fc917a6f2df1d8f912cf37c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 03:30:14 +0000
Subject: [PATCH 06/12] test(app-shell): pass the ledger switch its busy prop
 in the fold pin

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 .../studio-design/StudioItemHeader.titleRowFold-12897.test.tsx  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
index 73822c54fd6..3ccf9447d9e 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
@@ -265,7 +265,7 @@ function FoldingLeaf({
       actions={
         <>
           {labelled && <StudioCustomizeButton block={null} baseLabel="HotCRM" locale="en" onCustomize={onCustomize} />}
-          {labelled && <FlowLedgerSwitch checked reading="on" locale="en" onToggle={onToggle} />}
+          {labelled && <FlowLedgerSwitch checked reading="on" busy={false} locale="en" onToggle={onToggle} />}
           <ProbeTools onOpen={onOpen} />
           <button type="button">Open in Data</button>
         </>

From b0949a59bc7b56cc882f27bab77137b081cb7403 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 04:17:17 +0000
Subject: [PATCH 07/12] test(e2e): the customize journey finds the override
 chip in the row or in the item's folded menu

At the live job's 1280 px window with the Interfaces inspector open, the
item header folds its identity chips into the item's more menu so the
item's name stays readable, so the published pair's override chip is
looked for in the row first, then in the menu's chips entry, and the
menu is closed again before the next step.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUYXmZ6DQBWc6piyyF
---
 ui/e2e/live/studio-customize-journey.spec.ts | 25 +++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/ui/e2e/live/studio-customize-journey.spec.ts b/ui/e2e/live/studio-customize-journey.spec.ts
index 35d12dab4d7..f1cfceb4e81 100644
--- a/ui/e2e/live/studio-customize-journey.spec.ts
+++ b/ui/e2e/live/studio-customize-journey.spec.ts
@@ -95,6 +95,29 @@ async function publishPair(page: Page) {
   expect((await res.json()).data.outcome).toBe('published');
 }
 
+/**
+ * The override chip is reachable on the item header once the pair is published.
+ * When the row has room it is in the row. On a narrower content column (the
+ * job's 1280 px window with the inspector open) the header folds its identity
+ * chips into the item's ⋯ menu first, so the item's name stays readable
+ * (objectstack#29693), and there the chip sits in the menu's chips entry. The
+ * menu is closed again so the next step opens it fresh.
+ */
+async function expectOverrideChip(page: Page) {
+  const chip = page.getByTestId('studio-override-chip');
+  const entry = page.getByTestId('studio-item-header-folded-chips');
+  await expect(async () => {
+    if (await chip.isVisible()) return;
+    await page.getByTestId('if-item-more').click();
+    try {
+      await expect(entry.getByTestId('studio-override-chip')).toBeVisible({ timeout: 1_000 });
+    } finally {
+      await page.keyboard.press('Escape');
+    }
+  }).toPass({ timeout: 10_000 });
+  await expect(entry).toHaveCount(0);
+}
+
 test('a read-only base is customized, restored and extended through Studio, and its uninstall is refused', async ({ page, request }) => {
   const baseRes = await request.get(`${API}/api/v1/packages/${BASE}`);
   expect(baseRes.ok(), await baseRes.text()).toBeTruthy();
@@ -134,7 +157,7 @@ test('a read-only base is customized, restored and extended through Studio, and
 
       await publishPair(page);
       expect(await threeReads(request)).toEqual({ bare: customized, base: customized, list: customized });
-      await expect(page.getByTestId('studio-override-chip')).toBeVisible();
+      await expectOverrideChip(page);
     });
 
     await test.step('Restore package original: the pair\'s draft and row go, and the shipped columns are served again', async () => {

From 10d0e0a36f557906cef832fbb0c4b66b8d8879c2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 05:09:48 +0000
Subject: [PATCH 08/12] feat(studio): the override mark opens a popover with
 what it overrides, its version and Restore package original

Restore leaves the item's more menu (Interfaces, flow, bundle editor) for
the mark that names the customization; it still asks through the existing
confirmation dialog. Folded into the header's menu, the mark is pressed by
the keys through the folded entry.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUNJci3hxdpiN6RFQ1
---
 content/docs/build-without-code.mdx           |   2 +-
 .../views/studio-design/FlowItemMoreMenu.tsx  |  16 +--
 .../studio-design/StudioBundleItemEditor.tsx  |  17 ++-
 .../studio-design/StudioCustomizeControls.tsx | 111 +++++++++++-------
 .../studio-design/StudioDesignSurface.tsx     |  31 ++---
 .../views/studio-design/StudioItemHeader.tsx  |  12 +-
 6 files changed, 106 insertions(+), 83 deletions(-)

diff --git a/content/docs/build-without-code.mdx b/content/docs/build-without-code.mdx
index 94558478846..efab5103592 100644
--- a/content/docs/build-without-code.mdx
+++ b/content/docs/build-without-code.mdx
@@ -35,7 +35,7 @@ Two properties make Studio safe to hand to non-developers:
 
 ## Setup — where the platform is administered
 
-The **System Settings** app covers platform administration: user management and invitations, permission assignment, datasources (including federated external databases), diagnostics and audit logs, and the **Marketplace** — template apps such as HotCRM install with one click and appear alongside your own apps. Setup holds no metadata editor: its metadata pages open Studio, and an installed app is customized there. Open the app in Studio and every change lands in its paired customization package (`hotcrm.custom` for HotCRM), created on your first change and exported and deployed like any package, while what shipped stays the vendor's. **Customize** on a view, dashboard, report or flow saves your version as an override of the shipped one, marked with the app it overrides, and **Restore package original** removes it. **Add field** on a shipped object adds your own field, named with a `__c` suffix, and a shipped field's label, description, help text, placeholder and option labels can be changed, nothing else. A shipped flow's switch turns it off for this deployment, and **New similar** copies a flow or a permission set under a new name; a flow's copy starts switched off.
+The **System Settings** app covers platform administration: user management and invitations, permission assignment, datasources (including federated external databases), diagnostics and audit logs, and the **Marketplace** — template apps such as HotCRM install with one click and appear alongside your own apps. Setup holds no metadata editor: its metadata pages open Studio, and an installed app is customized there. Open the app in Studio and every change lands in its paired customization package (`hotcrm.custom` for HotCRM), created on your first change and exported and deployed like any package, while what shipped stays the vendor's. **Customize** on a view, dashboard, report or flow saves your version as an override of the shipped one, marked with the app it overrides. Press that mark to see which version it was taken from, and **Restore package original** there removes it. **Add field** on a shipped object adds your own field, named with a `__c` suffix, and a shipped field's label, description, help text, placeholder and option labels can be changed, nothing else. A shipped flow's switch turns it off for this deployment, and **New similar** copies a flow or a permission set under a new name; a flow's copy starts switched off.
 
 ## When to reach for code instead
 
diff --git a/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx b/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx
index 99a1b4beef2..ed89f6d6c09 100644
--- a/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/FlowItemMoreMenu.tsx
@@ -20,9 +20,9 @@
  *    `type/name` (objectui#13333). The pillar sends the delete itself. Reset
  *    overlay is not offered: it arrives with the overlay editing of the
  *    Studio / Setup boundary record's phase 2 (#28045).
- *  - **Restore package original** (objectstack#28570, ADR-0146 D2), a
- *    read-only base's flow that its pair overrides. The pillar decides it from
- *    the served declaration and holds the confirmation, outside this menu.
+ *
+ * Restore package original is not here: it is on the flow's override mark,
+ * where the customization is named (objectstack#29692).
  */
 
 import * as React from 'react';
@@ -56,7 +56,6 @@ import { t, tFormat, translateMetadataType } from '../metadata-admin/i18n.js';
 import { envelopeData, envelopeRefused } from '../setup/packagedFlows.js';
 import { apiBase } from '../../utils/apiBase.js';
 import { STUDIO_HEADER_ICON_BUTTON } from './studio-tokens.js';
-import { StudioRestoreOriginalItem } from './StudioCustomizeControls.js';
 
 /** What the clone door saved: the copy's name, the package it names, and its sentence. */
 export interface FlowCopied {
@@ -129,17 +128,15 @@ interface NewSimilarDraft {
 /**
  * `label` is the flow's display label; `disabled` holds the menu's actions
  * while a save is in flight. `onDelete` draws Delete flow (a writable
- * package's flow); `newSimilar` draws New similar; `restore` draws Restore
- * package original (a flow the base's pair overrides).
+ * package's flow); `newSimilar` draws New similar.
  */
-export function FlowItemMoreMenu({ name, label, locale, disabled, onDelete, newSimilar, restore }: {
+export function FlowItemMoreMenu({ name, label, locale, disabled, onDelete, newSimilar }: {
   name: string;
   label: string;
   locale: string;
   disabled?: boolean;
   onDelete?: () => void;
   newSimilar?: FlowNewSimilarProps;
-  restore?: { disabled?: boolean; onSelect: () => void };
 }): React.ReactElement {
   const [confirming, setConfirming] = React.useState(false);
   const [copy, setCopy] = React.useState<NewSimilarDraft | null>(null);
@@ -218,9 +215,6 @@ export function FlowItemMoreMenu({ name, label, locale, disabled, onDelete, newS
               {t('engine.studio.auto.deleteFlow', locale)}
             </DropdownMenuItem>
           )}
-          {restore && (
-            <StudioRestoreOriginalItem disabled={disabled || restore.disabled} locale={locale} onSelect={restore.onSelect} />
-          )}
         </DropdownMenuContent>
       </DropdownMenu>
       {onDelete && (
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.tsx b/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.tsx
index 7e92dfb4d42..e0d004151c7 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.tsx
@@ -58,7 +58,6 @@ import {
   StudioCustomizeButton,
   StudioOverrideChip,
   StudioRestoreOriginalDialog,
-  StudioRestoreOriginalItem,
   overrideDraftBody,
   useServedOverride,
   type CustomizeBlock,
@@ -375,7 +374,14 @@ export function StudioBundleItemEditor({
           </span>
         )}
         {customizing && served.declaration && (
-          <StudioOverrideChip baseLabel={baseLabel} basedOn={served.declaration.basedOn} locale={locale} />
+          <StudioOverrideChip
+            baseLabel={baseLabel}
+            basedOn={served.declaration.basedOn}
+            locale={locale}
+            // objectstack#29692 — Restore lives on the mark that names the customization.
+            onRestore={inPair ? () => setRestoreOpen(true) : undefined}
+            restoreDisabled={restoring || saving || (customization?.pairId == null && pairRef.current === null)}
+          />
         )}
         {status && (
           <span data-testid="studio-bundle-editor-status" className="shrink-0 text-xs text-muted-foreground">
@@ -418,13 +424,6 @@ export function StudioBundleItemEditor({
               <History className="mr-2 h-3.5 w-3.5" aria-hidden="true" />
               {t('engine.edit.history', locale)}
             </DropdownMenuItem>
-            {customizing && inPair && (
-              <StudioRestoreOriginalItem
-                disabled={restoring || saving || (customization?.pairId == null && pairRef.current === null)}
-                locale={locale}
-                onSelect={() => setRestoreOpen(true)}
-              />
-            )}
           </DropdownMenuContent>
         </DropdownMenu>
       </div>
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
index 858d0663ee9..ad0f6c04dd5 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
@@ -20,8 +20,8 @@
  *    reads it, ⛔ never a computation (no diff, no `.custom` spelling);
  *  - whether the ensure door refuses this caller
  *    ({@link customizeDoorWalled}), from the two facts the server publishes;
- *  - the header's Customize button, the override badge and the item menu's
- *    Restore entry with its confirmation.
+ *  - the header's Customize button, and the override mark, whose popover
+ *    offers Restore, with its confirmation (objectstack#29692).
  *
  * The pair's id for a write is the ensure door's answer
  * (`packages-io.ts#ensureCustomizationPackage`); the pillar asks it.
@@ -37,8 +37,9 @@ import {
   AlertDialogFooter,
   AlertDialogHeader,
   AlertDialogTitle,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
   cn,
 } from '@object-ui/components';
 import { useAuth } from '@object-ui/auth';
@@ -267,58 +268,86 @@ export function StudioCustomizeButton({
 }
 
 /**
- * The header's badge: the item overrides the base. Drawn from a served
- * declaration ({@link useServedOverride}); `basedOn` is the version it names.
+ * The header's override mark: the item overrides the base. Drawn from a
+ * served declaration ({@link useServedOverride}); `basedOn` is the version it
+ * names.
+ *
+ * objectstack#29692 (ADR-0146 D2) — the mark is where a customization is
+ * named, so it is where it is undone: pressing it opens a small popover that
+ * says what the item overrides and the version it was taken from and, for an
+ * item the pair holds (`onRestore`), offers "Restore package original". That
+ * button only asks: the host opens its confirmation
+ * ({@link StudioRestoreOriginalDialog}), held outside any menu. Restore is
+ * never a header action of its own, so Customize keeps the primary slot.
+ *
+ * Folded into the header's ⋯ menu (objectstack#29693), the mark is a control
+ * inside a menu item: its own click does not reach the item (one press, one
+ * toggle), and the item activates it by `data-studio-chip-control` when it
+ * is chosen by the keys (`StudioItemHeaderFoldedItems`).
  */
 export function StudioOverrideChip({
   baseLabel,
   basedOn,
   locale,
+  onRestore,
+  restoreDisabled = false,
 }: {
   baseLabel: string;
   basedOn: string;
   locale: string;
+  /** Opens the host's Restore confirmation; omitted, the popover states the facts alone. */
+  onRestore?: () => void;
+  restoreDisabled?: boolean;
 }): React.ReactElement {
+  const [open, setOpen] = React.useState(false);
   return (
-    <span
-      data-testid="studio-override-chip"
-      title={tFormat('engine.studio.customize.overridesTitle', locale, { package: baseLabel, basedOn })}
-      className="inline-flex h-[22px] shrink-0 items-center gap-1 rounded-[5px] bg-sky-500/10 px-2 text-[11px] font-medium text-sky-700 dark:text-sky-300"
-    >
-      <Layers className="h-3 w-3 shrink-0" aria-hidden="true" />
-      {tFormat('engine.studio.customize.overrides', locale, { package: baseLabel })}
-    </span>
-  );
-}
-
-/**
- * "Restore package original" on the item's ⋯ menu. The confirmation is
- * {@link StudioRestoreOriginalDialog}, held by the host outside the menu: a
- * menu's content unmounts as the menu closes on select, and a dialog inside it
- * would close with it.
- */
-export function StudioRestoreOriginalItem({
-  disabled,
-  locale,
-  onSelect,
-}: {
-  disabled?: boolean;
-  locale: string;
-  onSelect: () => void;
-}): React.ReactElement {
-  return (
-    <>
-      <DropdownMenuSeparator />
-      <DropdownMenuItem data-testid="studio-restore-original" disabled={disabled} onSelect={onSelect}>
-        <RotateCcw className="mr-2 h-3.5 w-3.5" aria-hidden="true" />
-        {t('engine.studio.customize.restore', locale)}
-      </DropdownMenuItem>
-    </>
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          data-testid="studio-override-chip"
+          data-studio-chip-control=""
+          onClick={(event) => event.stopPropagation()}
+          className="inline-flex h-[22px] shrink-0 items-center gap-1 rounded-[5px] bg-sky-500/10 px-2 text-[11px] font-medium text-sky-700 hover:bg-sky-500/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=open]:bg-sky-500/20 dark:text-sky-300"
+        >
+          <Layers className="h-3 w-3 shrink-0" aria-hidden="true" />
+          {tFormat('engine.studio.customize.overrides', locale, { package: baseLabel })}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="start" className="w-72 p-3 text-xs" data-testid="studio-override-popover">
+        <p className="flex items-center gap-1.5 text-sm font-medium text-foreground">
+          <Layers className="h-3.5 w-3.5 shrink-0 text-sky-700 dark:text-sky-300" aria-hidden="true" />
+          {tFormat('engine.studio.customize.overrides', locale, { package: baseLabel })}
+        </p>
+        <p className="mt-1.5 text-muted-foreground" data-testid="studio-override-popover-facts">
+          {tFormat('engine.studio.customize.overridesTitle', locale, { package: baseLabel, basedOn })}
+        </p>
+        {onRestore && (
+          <button
+            type="button"
+            data-testid="studio-override-restore"
+            disabled={restoreDisabled}
+            onClick={() => {
+              setOpen(false);
+              onRestore();
+            }}
+            className={cn(
+              'mt-3 inline-flex h-7 items-center gap-1.5 rounded-md border bg-background px-2.5 text-xs font-medium text-foreground hover:bg-muted',
+              'disabled:pointer-events-none disabled:opacity-50',
+            )}
+          >
+            <RotateCcw className="h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true" />
+            {t('engine.studio.customize.restore', locale)}
+          </button>
+        )}
+      </PopoverContent>
+    </Popover>
   );
 }
 
 /**
- * The confirmation of "Restore package original": it says what goes, the
+ * The confirmation of "Restore package original", opened from the override
+ * mark's popover ({@link StudioOverrideChip}): it says what goes, the
  * customization, and its unpublished draft when one is pending. `onConfirm`
  * sends both deletes; nothing is sent on Cancel. objectstack#28570 — a flow's
  * (`kind: 'flow'`) says the base's flow runs again, under the same switch.
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
index b64b795dae8..b60585e131b 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
@@ -417,7 +417,6 @@ import {
   StudioCustomizeButton,
   StudioOverrideChip,
   StudioRestoreOriginalDialog,
-  StudioRestoreOriginalItem,
   isStudioCustomizeType,
   overrideDraftBody,
   useCustomizeDoorWalled,
@@ -6223,8 +6222,8 @@ export function InterfacesPillar({
   );
   // objectui#12725 — the item's ⋯ menu: its definition, and its document as
   // JSON. Rename and delete are not offered here: this header has neither
-  // today (a nav entry is renamed and removed in nav editing).
-  // objectstack#28562 — and, for an item customized into the pair, Restore.
+  // today (a nav entry is renamed and removed in nav editing). Restore is
+  // the override mark's (objectstack#29692), not this menu's.
   const itemMoreEl =
     current && draftLoaded ? (
       <DropdownMenu>
@@ -6250,13 +6249,6 @@ export function InterfacesPillar({
             <Copy className="mr-2 h-3.5 w-3.5" aria-hidden="true" />
             {t('engine.studio.if.copyJson', locale)}
           </DropdownMenuItem>
-          {headerCustomize?.inPair && (
-            <StudioRestoreOriginalItem
-              disabled={restoring || headerCustomize.busy || (customizePair === null && !pairsByItemRef.current.has(headerCustomize.key))}
-              locale={locale}
-              onSelect={() => setRestoreFor(headerCustomize)}
-            />
-          )}
         </DropdownMenuContent>
       </DropdownMenu>
     ) : null;
@@ -6345,6 +6337,13 @@ export function InterfacesPillar({
                 baseLabel={customizeBaseLabel}
                 basedOn={headerCustomize.declaration.basedOn}
                 locale={locale}
+                // objectstack#29692 — Restore lives on the mark that names the customization.
+                onRestore={headerCustomize.inPair ? () => setRestoreFor(headerCustomize) : undefined}
+                restoreDisabled={
+                  restoring ||
+                  headerCustomize.busy ||
+                  (customizePair === null && !pairsByItemRef.current.has(headerCustomize.key))
+                }
               />
             )}
             {/* objectstack#28572 — an item the pair adds names the pair it lives in. */}
@@ -11293,6 +11292,9 @@ export function AutomationsPillar({
                   baseLabel={customizeBaseLabel}
                   basedOn={flowServed.declaration.basedOn}
                   locale={locale}
+                  // objectstack#29692 — Restore lives on the mark that names the customization.
+                  onRestore={flowInPair ? () => setRestoreOpen(true) : undefined}
+                  restoreDisabled={restoring || !!saving}
                 />
               ) : undefined
             }
@@ -11351,15 +11353,6 @@ export function AutomationsPillar({
                     locale={locale}
                     disabled={!!saving}
                     onDelete={readOnly ? undefined : () => void deleteOpenFlow()}
-                    // objectstack#28570 — for a flow the pair overrides, read from the served declaration.
-                    restore={
-                      flowInPair
-                        ? {
-                            disabled: restoring,
-                            onSelect: () => setRestoreOpen(true),
-                          }
-                        : undefined
-                    }
                     newSimilar={{
                       target: readOnly ? undefined : packageId,
                       blocked: canAuthorFlows ? null : t('engine.edit.capabilityReadOnly', locale),
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
index efd94077c9e..965d21a6e85 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
@@ -426,11 +426,19 @@ export function StudioItemHeaderFoldedItems({ separator = true }: { separator?:
     <>
       {/* One menu entry, reachable by the keys like the others; choosing it
           keeps the menu open, so a chip with its own control (the override
-          chip) is used from here as from the row. */}
+          chip) is used from here as from the row. objectstack#29692 — a menu
+          holds the focus on its items, so choosing the entry by the keys
+          presses the chip's control (`data-studio-chip-control`); the control
+          keeps its own click from reaching the entry, so a pointer press
+          toggles it once. */}
       {hasChips && (
         <DropdownMenuItem
           data-testid="studio-item-header-folded-chips"
-          onSelect={(event) => event.preventDefault()}
+          onSelect={(event) => {
+            event.preventDefault();
+            const target = event.currentTarget instanceof HTMLElement ? event.currentTarget : null;
+            target?.querySelector<HTMLElement>('[data-studio-chip-control]')?.click();
+          }}
           className="flex flex-wrap items-center gap-1.5"
         >
           {fold.apiName && <StudioApiChip apiName={fold.apiName} />}

From 2aac813835852263b2de4c74548ff6061f259a36 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 05:22:22 +0000
Subject: [PATCH 09/12] test(studio): Restore is asked from the override mark;
 folded-menu, label and one-door pins

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUNJci3hxdpiN6RFQ1
---
 .changeset/29692-override-chip-restore.md     | 10 ++++
 ui/e2e/live/studio-customize-journey.spec.ts  | 12 +++-
 ...mationsPillar.customizeFlow-28570.test.tsx | 37 ++++++++++--
 .../InterfacesPillar.customize-28562.test.tsx | 57 ++++++++++++++++---
 ...oBundleItemEditor.customize-28569.test.tsx | 13 ++++-
 ...CustomizeControls.customize-28562.test.tsx | 38 +++++++++++--
 ...udioItemHeader.titleRowFold-12897.test.tsx | 57 ++++++++++++++++++-
 7 files changed, 199 insertions(+), 25 deletions(-)
 create mode 100644 .changeset/29692-override-chip-restore.md

diff --git a/.changeset/29692-override-chip-restore.md b/.changeset/29692-override-chip-restore.md
new file mode 100644
index 00000000000..f36c8e44d30
--- /dev/null
+++ b/.changeset/29692-override-chip-restore.md
@@ -0,0 +1,10 @@
+---
+'@object-ui/app-shell': patch
+---
+
+feat(app-shell): Studio's override mark opens a popover that names the customization and offers Restore package original
+
+Clause-②: no
+Metadata-protocol: none
+
+In Studio, the mark on an item customized into the base's pair ("Overrides HotCRM") used to tell you nothing more, and you had to find "Restore package original" in the item's ⋯ menu. The mark is now a button. Pressing it opens a small popover that says which package the item overrides and which version of it the customization was taken from, with a "Restore package original" button. That button asks through the same confirmation dialog as before, and confirming sends the same two deletes at the pair: its draft, then its row. Customize keeps the header's primary slot, and Restore is never a header button of its own. The ⋯ menus of the Interfaces item, the flow and the All-metadata form editor no longer list Restore, so the mark is the one place to find it. On a narrow header, where the mark folds into the ⋯ menu, it opens the same popover there. Choosing the folded entry with the keyboard opens it too.
diff --git a/ui/e2e/live/studio-customize-journey.spec.ts b/ui/e2e/live/studio-customize-journey.spec.ts
index f1cfceb4e81..3b1eba7bc0b 100644
--- a/ui/e2e/live/studio-customize-journey.spec.ts
+++ b/ui/e2e/live/studio-customize-journey.spec.ts
@@ -166,8 +166,16 @@ test('a read-only base is customized, restored and extended through Studio, and
         if (r.request().method() === 'DELETE' && r.url().includes(`/api/v1/meta/view/${VIEW}`)) deletes.push(`${r.status()} ${r.url()}`);
       };
       page.on('response', onResponse);
-      await page.getByTestId('if-item-more').click();
-      await page.getByTestId('studio-restore-original').click();
+      // objectstack#29692 — Restore is on the override chip's popover: the chip in
+      // the row, or in the item's ⋯ menu while the header is folded.
+      const rowChip = page.getByTestId('if-item-header').getByTestId('studio-override-chip');
+      if (await rowChip.isVisible()) {
+        await rowChip.click();
+      } else {
+        await page.getByTestId('if-item-more').click();
+        await page.getByTestId('studio-item-header-folded-chips').getByTestId('studio-override-chip').click();
+      }
+      await page.getByTestId('studio-override-popover').getByTestId('studio-override-restore').click();
       await page.getByTestId('studio-restore-original-confirm').click();
       await expect(page.getByTestId('studio-customize')).toBeVisible();
       await expect.poll(() => deletes.length).toBe(2);
diff --git a/ui/packages/app-shell/src/views/studio-design/AutomationsPillar.customizeFlow-28570.test.tsx b/ui/packages/app-shell/src/views/studio-design/AutomationsPillar.customizeFlow-28570.test.tsx
index 2f6b8215e0c..e110b6bdae3 100644
--- a/ui/packages/app-shell/src/views/studio-design/AutomationsPillar.customizeFlow-28570.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/AutomationsPillar.customizeFlow-28570.test.tsx
@@ -282,6 +282,15 @@ async function openMenu(): Promise<void> {
   await screen.findByTestId('auto-item-new-similar');
 }
 
+/**
+ * objectstack#29692 — Restore is asked from the override mark's popover, and
+ * confirmed in the same dialog the flow's menu opened before.
+ */
+async function openRestorePopover(): Promise<HTMLElement> {
+  fireEvent.click(await within(header()).findByTestId('studio-override-chip', undefined, { timeout: 8000 }));
+  return screen.findByTestId('studio-override-popover');
+}
+
 /** The one switch drawn in the header is the ledger's: no definition switch beside it. */
 async function expectLedgerSwitchAlone(): Promise<void> {
   const ledger = await within(header()).findByTestId('auto-ledger-switch', undefined, { timeout: 8000 });
@@ -327,7 +336,13 @@ describe('Customize a read-only base’s flow into its pair (objectstack#28570)'
     // The badge reads the declaration the pair's draft now serves.
     const chip = await within(header()).findByTestId('studio-override-chip', undefined, { timeout: 8000 });
     expect(chip).toHaveTextContent(tFormat('engine.studio.customize.overrides', 'en', { package: 'HotCRM' }));
-    expect(chip).toHaveAttribute('title', tFormat('engine.studio.customize.overridesTitle', 'en', { package: 'HotCRM', basedOn: '4.0.0' }));
+    // objectstack#29692 — pressed, the mark says the version it was taken from.
+    fireEvent.click(chip);
+    expect(await screen.findByTestId('studio-override-popover-facts')).toHaveTextContent(
+      tFormat('engine.studio.customize.overridesTitle', 'en', { package: 'HotCRM', basedOn: '4.0.0' }),
+    );
+    fireEvent.keyDown(document.activeElement ?? document.body, { key: 'Escape' });
+    await waitFor(() => expect(screen.queryByTestId('studio-override-popover')).toBeNull());
     await expectLedgerSwitchAlone();
 
     // A later edit asks the door no more, and is pinned to the version it was answered.
@@ -350,10 +365,14 @@ describe('Customize a read-only base’s flow into its pair (objectstack#28570)'
     await expectLedgerSwitchAlone();
 
     // The layered envelope says `deletable: false`; the declared row decides.
+    const popover = await openRestorePopover();
+    expect(within(popover).getByTestId('studio-override-restore')).toBeEnabled();
+    fireEvent.keyDown(document.activeElement ?? document.body, { key: 'Escape' });
+    await waitFor(() => expect(screen.queryByTestId('studio-override-popover')).toBeNull());
+    // Delete flow stays a writable package's own; Restore is the mark's, not the menu's (objectstack#29692).
     await openMenu();
-    expect(screen.getByTestId('studio-restore-original')).not.toHaveAttribute('data-disabled');
-    // Delete flow stays a writable package's own.
     expect(screen.queryByTestId('auto-item-delete')).toBeNull();
+    expect(screen.queryByTestId('studio-restore-original')).toBeNull();
 
     // Its editors are open: an edit is saved into the pair, keeping the declaration.
     fireEvent.keyDown(document.activeElement ?? document.body, { key: 'Escape' });
@@ -371,10 +390,16 @@ describe('Customize a read-only base’s flow into its pair (objectstack#28570)'
     mount({ listedPair: PAIR });
     await openFlow(/^Notify owner and manager v2$/);
 
-    await openMenu();
-    fireEvent.click(screen.getByTestId('studio-restore-original'));
+    // objectstack#29692 — the dialog names the flow as its rail row does.
+    const railText = within(screen.getByTestId('studio-rail-automations'))
+      .getByRole('button', { name: /^Notify owner/ })
+      // The row's label, without the switch reading the row prints after it.
+      .querySelector('.flex-1')
+      ?.textContent?.trim();
+    expect(railText).toBe('Notify owner');
+    fireEvent.click(within(await openRestorePopover()).getByTestId('studio-override-restore'));
     const dialog = await screen.findByTestId('studio-restore-original-dialog');
-    const vars = { item: 'Notify owner', package: 'HotCRM' };
+    const vars = { item: railText!, package: 'HotCRM' };
     expect(dialog).toHaveTextContent(tFormat('engine.studio.customize.restoreConfirm', 'en', vars));
     expect(dialog).toHaveTextContent(tFormat('engine.studio.customize.restoreFlowBody', 'en', vars));
     expect(dialog).toHaveTextContent(t('engine.studio.customize.restoreDraft', 'en'));
diff --git a/ui/packages/app-shell/src/views/studio-design/InterfacesPillar.customize-28562.test.tsx b/ui/packages/app-shell/src/views/studio-design/InterfacesPillar.customize-28562.test.tsx
index 9e00cc6da7d..7540b44b656 100644
--- a/ui/packages/app-shell/src/views/studio-design/InterfacesPillar.customize-28562.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/InterfacesPillar.customize-28562.test.tsx
@@ -307,11 +307,20 @@ async function customize(): Promise<void> {
   await waitFor(() => expect(within(header()).queryByTestId('studio-customize')).toBeNull());
 }
 
+/**
+ * objectstack#29692 — Restore is asked from the override mark's popover, and
+ * confirmed in the same dialog the item menu opened before.
+ */
+async function openRestoreDialog(): Promise<HTMLElement> {
+  fireEvent.click(await within(header()).findByTestId('studio-override-chip', undefined, { timeout: 8000 }));
+  const popover = await screen.findByTestId('studio-override-popover');
+  await waitFor(() => expect(within(popover).getByTestId('studio-override-restore')).toBeEnabled(), { timeout: 8000 });
+  fireEvent.click(within(popover).getByTestId('studio-override-restore'));
+  return screen.findByTestId('studio-restore-original-dialog');
+}
+
 async function restore(): Promise<void> {
-  fireEvent.pointerDown(await screen.findByTestId('if-item-more', undefined, { timeout: 8000 }), { button: 0, ctrlKey: false });
-  fireEvent.click(await screen.findByTestId('studio-restore-original'));
-  const dialog = await screen.findByTestId('studio-restore-original-dialog');
-  fireEvent.click(within(dialog).getByTestId('studio-restore-original-confirm'));
+  fireEvent.click(within(await openRestoreDialog()).getByTestId('studio-restore-original-confirm'));
 }
 
 describe('Customize a read-only base’s dashboard into its pair (objectstack#28562)', () => {
@@ -351,7 +360,13 @@ describe('Customize a read-only base’s dashboard into its pair (objectstack#28
     // The badge reads the declaration the pair's draft now serves.
     const chip = await within(header()).findByTestId('studio-override-chip', undefined, { timeout: 8000 });
     expect(chip).toHaveTextContent(tFormat('engine.studio.customize.overrides', 'en', { package: 'HotCRM' }));
-    expect(chip).toHaveAttribute('title', tFormat('engine.studio.customize.overridesTitle', 'en', { package: 'HotCRM', basedOn: '4.0.0' }));
+    // objectstack#29692 — pressed, the mark says the version it was taken from.
+    fireEvent.click(chip);
+    expect(await screen.findByTestId('studio-override-popover-facts')).toHaveTextContent(
+      tFormat('engine.studio.customize.overridesTitle', 'en', { package: 'HotCRM', basedOn: '4.0.0' }),
+    );
+    fireEvent.keyDown(document.activeElement ?? document.body, { key: 'Escape' });
+    await waitFor(() => expect(screen.queryByTestId('studio-override-popover')).toBeNull());
 
     // A later edit of the same item asks the door no more.
     patchBoard();
@@ -480,13 +495,37 @@ describe('Restore package original (objectstack#28562)', () => {
       overrides: { package: BASE, basedOn: '4.0.0' },
     });
     mount({ listedPair: PAIR });
-    await within(header()).findByTestId('studio-override-chip', undefined, { timeout: 8000 });
-    fireEvent.pointerDown(screen.getByTestId('if-item-more'), { button: 0, ctrlKey: false });
-    fireEvent.click(await screen.findByTestId('studio-restore-original'));
-    fireEvent.click(within(await screen.findByTestId('studio-restore-original-dialog')).getByTestId('studio-restore-original-cancel'));
+    fireEvent.click(within(await openRestoreDialog()).getByTestId('studio-restore-original-cancel'));
     await sleep(300);
     expect(srv.resets).toEqual([]);
   });
+
+  it('objectstack#29692 — one door: the item’s ⋯ menu offers no Restore, and the dialog names the item as its rail row does', async () => {
+    srv.pairExists = true;
+    srv.pairActive.set('dashboard/pipeline', {
+      name: 'pipeline',
+      label: 'Pipeline (ours)',
+      widgets: [],
+      overrides: { package: BASE, basedOn: '4.0.0' },
+    });
+    mount({ listedPair: PAIR });
+    await within(header()).findByTestId('studio-override-chip', undefined, { timeout: 8000 });
+    fireEvent.pointerDown(screen.getByTestId('if-item-more'), { button: 0, ctrlKey: false });
+    await screen.findByTestId('if-item-view-definition');
+    expect(screen.queryByTestId('studio-restore-original')).toBeNull();
+    fireEvent.keyDown(screen.getByTestId('if-item-view-definition'), { key: 'Escape' });
+    await waitFor(() => expect(screen.queryByTestId('if-item-view-definition')).toBeNull());
+
+    const railRow = within(screen.getByTestId('studio-rail-interfaces')).getByRole('button', { name: /Pipeline/ });
+    // The row's label, without the kind word the row prints after it.
+    const railText = railRow.querySelector('.flex-1')?.textContent?.trim() ?? '';
+    expect(railText).toBe('Pipeline');
+    const dialog = await openRestoreDialog();
+    expect(within(dialog).getByRole('heading')).toHaveTextContent(
+      tFormat('engine.studio.customize.restoreConfirm', 'en', { package: 'HotCRM', item: railText }),
+    );
+    fireEvent.click(within(dialog).getByTestId('studio-restore-original-cancel'));
+  });
 });
 
 /** The calendar setting `key` of the list-view panel. */
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.customize-28569.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.customize-28569.test.tsx
index cd94b5347a8..189fbf2ec9c 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.customize-28569.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioBundleItemEditor.customize-28569.test.tsx
@@ -253,9 +253,12 @@ async function customize(): Promise<void> {
   await waitFor(() => expect(screen.queryByTestId('studio-customize')).toBeNull());
 }
 
+/** objectstack#29692 — Restore is asked from the override mark's popover. */
 async function restore(): Promise<void> {
-  fireEvent.pointerDown(await screen.findByTestId('studio-bundle-editor-more'), { button: 0, ctrlKey: false });
-  fireEvent.click(await screen.findByTestId('studio-restore-original'));
+  fireEvent.click(await screen.findByTestId('studio-override-chip', undefined, { timeout: 8000 }));
+  const popover = await screen.findByTestId('studio-override-popover');
+  await waitFor(() => expect(within(popover).getByTestId('studio-override-restore')).toBeEnabled(), { timeout: 8000 });
+  fireEvent.click(within(popover).getByTestId('studio-override-restore'));
   const dialog = await screen.findByTestId('studio-restore-original-dialog');
   fireEvent.click(within(dialog).getByTestId('studio-restore-original-confirm'));
 }
@@ -371,6 +374,12 @@ describe('Customize a read-only base’s email template, one locale (objectstack
     mount({ type: 'email_template', name: 'welcome', member: 'zh-CN', listedPair: PAIR });
     expect(await field('Subject')).toHaveValue('欢迎回来');
     expect(await screen.findByTestId('studio-override-chip')).toBeInTheDocument();
+    // objectstack#29692 — one door: the editor's ⋯ menu offers no Restore.
+    fireEvent.pointerDown(screen.getByTestId('studio-bundle-editor-more'), { button: 0, ctrlKey: false });
+    await screen.findByTestId('studio-bundle-editor-history');
+    expect(screen.queryByTestId('studio-restore-original')).toBeNull();
+    fireEvent.keyDown(screen.getByTestId('studio-bundle-editor-history'), { key: 'Escape' });
+    await waitFor(() => expect(screen.queryByTestId('studio-bundle-editor-history')).toBeNull());
 
     await restore();
     await waitFor(() => expect(srv.resets).toHaveLength(2));
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.customize-28562.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.customize-28562.test.tsx
index 454ffcf25b5..9ed934a3c64 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.customize-28562.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.customize-28562.test.tsx
@@ -22,7 +22,7 @@
 import '@testing-library/jest-dom/vitest';
 import * as React from 'react';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { cleanup, render, screen } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
 
 import {
   StudioCustomizeButton,
@@ -224,13 +224,43 @@ describe('the Customize button and the override badge (objectstack#28562)', () =
     expect(document.getElementById(button.getAttribute('aria-describedby')!)).toHaveTextContent(reason);
   });
 
-  it('the badge names the base, and its title the version the override is based on', () => {
+  it('the badge names the base; pressed, its popover says the version the override is based on', () => {
     render(<StudioOverrideChip baseLabel="HotCRM" basedOn="4.0.0" locale="en" />);
     const chip = screen.getByTestId('studio-override-chip');
     expect(chip).toHaveTextContent(tFormat('engine.studio.customize.overrides', 'en', { package: 'HotCRM' }));
-    expect(chip).toHaveAttribute(
-      'title',
+    fireEvent.click(chip);
+    expect(screen.getByTestId('studio-override-popover-facts')).toHaveTextContent(
       tFormat('engine.studio.customize.overridesTitle', 'en', { package: 'HotCRM', basedOn: '4.0.0' }),
     );
   });
 });
+
+describe('the override mark is where Restore is asked (objectstack#29692)', () => {
+  it('its popover offers Restore package original; pressing it asks the host once and closes the popover', () => {
+    const onRestore = vi.fn();
+    render(<StudioOverrideChip baseLabel="HotCRM" basedOn="4.0.0" locale="en" onRestore={onRestore} />);
+    fireEvent.click(screen.getByTestId('studio-override-chip'));
+    const restore = screen.getByTestId('studio-override-restore');
+    expect(restore).toHaveTextContent(t('engine.studio.customize.restore', 'en'));
+    fireEvent.click(restore);
+    expect(onRestore).toHaveBeenCalledTimes(1);
+    expect(screen.queryByTestId('studio-override-popover')).toBeNull();
+  });
+
+  it('disabled while the host cannot restore: pressing it asks nothing', () => {
+    const onRestore = vi.fn();
+    render(<StudioOverrideChip baseLabel="HotCRM" basedOn="4.0.0" locale="en" onRestore={onRestore} restoreDisabled />);
+    fireEvent.click(screen.getByTestId('studio-override-chip'));
+    const restore = screen.getByTestId('studio-override-restore');
+    expect(restore).toBeDisabled();
+    fireEvent.click(restore);
+    expect(onRestore).not.toHaveBeenCalled();
+  });
+
+  it('CONTROL: without onRestore the popover states the facts and offers no Restore', () => {
+    render(<StudioOverrideChip baseLabel="HotCRM" basedOn="4.0.0" locale="en" />);
+    fireEvent.click(screen.getByTestId('studio-override-chip'));
+    expect(screen.getByTestId('studio-override-popover')).toBeInTheDocument();
+    expect(screen.queryByTestId('studio-override-restore')).toBeNull();
+  });
+});
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
index 3ccf9447d9e..d6f9d4c75a8 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
@@ -29,7 +29,7 @@ import { act, cleanup, fireEvent, render, screen, within } from '@testing-librar
 import { Workflow } from 'lucide-react';
 import { StudioItemHeader, useStudioItemHeaderFold, useStudioTabRowFold, type StudioFoldedTool } from './StudioItemHeader';
 import { STUDIO_FOLD_LABEL, STUDIO_KIND_CHIP } from './studio-tokens';
-import { StudioCustomizeButton } from './StudioCustomizeControls';
+import { StudioCustomizeButton, StudioOverrideChip } from './StudioCustomizeControls';
 import { FlowLedgerSwitch } from './FlowLedgerSwitch';
 import { t } from '../metadata-admin/i18n';
 
@@ -243,7 +243,10 @@ function FoldingLeaf({
   labelled = false,
   onCustomize = () => {},
   onToggle = () => {},
+  kind = 'View',
 }: {
+  /** What the kind chip holds: its word, or (objectstack#29692) the override mark. */
+  kind?: React.ReactNode;
   onOpen?: (id: string) => void;
   foldMenu?: boolean;
   /** The labelled actions a pillar draws: the Customize button and a flow's ledger switch. */
@@ -258,7 +261,7 @@ function FoldingLeaf({
       titleProps={{ 'data-testid': 'hdr-title', title: INTERNAL_ID }}
       chips={
         <span className={STUDIO_KIND_CHIP} data-testid="hdr-kind-chip">
-          View
+          {kind}
         </span>
       }
       foldMenu={foldMenu ? { label: 'More', testId: 'hdr-more' } : undefined}
@@ -438,3 +441,53 @@ describe('the fold order: chips and tools, then labels, then the title (objectst
     expect(screen.getByRole('menu')).toBeInTheDocument();
   });
 });
+
+describe('the override mark folded into the ⋯ menu (objectstack#29692)', () => {
+  let rangeSpy: { mockRestore: () => void } | null = null;
+  beforeEach(() => {
+    rangeSpy = vi.spyOn(Range.prototype, 'getBoundingClientRect').mockImplementation(() => rect(READABLE));
+  });
+  afterEach(() => {
+    rangeSpy?.mockRestore();
+    rangeSpy = null;
+  });
+
+  function foldedMark(onRestore = vi.fn()) {
+    layout.row = 330;
+    render(<FoldingLeaf kind={<StudioOverrideChip baseLabel="HotCRM" basedOn="4.0.0" locale="en" onRestore={onRestore} />} />);
+    const menu = openOwnMore();
+    const entry = within(menu).getByTestId('studio-item-header-folded-chips');
+    return { menu, entry, chip: within(entry).getByTestId('studio-override-chip'), onRestore };
+  }
+
+  it('a press on the mark opens its popover once, and the menu stays open under it', () => {
+    const { chip } = foldedMark();
+    fireEvent.click(chip);
+    // One press, one toggle: the entry's own select does not press the mark again.
+    expect(chip).toHaveAttribute('data-state', 'open');
+    expect(screen.getAllByTestId('studio-override-popover')).toHaveLength(1);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    // A second press closes it, and the menu is still there.
+    fireEvent.click(chip);
+    expect(chip).toHaveAttribute('data-state', 'closed');
+    expect(screen.queryByTestId('studio-override-popover')).toBeNull();
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+  });
+
+  it('chosen by the keys, the folded entry presses the mark: its popover opens and the menu stays open', () => {
+    const { entry, chip } = foldedMark();
+    act(() => entry.focus());
+    fireEvent.keyDown(entry, { key: 'Enter' });
+    expect(chip).toHaveAttribute('data-state', 'open');
+    expect(screen.getAllByTestId('studio-override-popover')).toHaveLength(1);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+  });
+
+  it('Restore in the popover asks the host once and closes the popover', () => {
+    const { chip, onRestore } = foldedMark();
+    fireEvent.click(chip);
+    fireEvent.click(screen.getByTestId('studio-override-restore'));
+    expect(onRestore).toHaveBeenCalledTimes(1);
+    expect(screen.queryByTestId('studio-override-popover')).toBeNull();
+  });
+});

From 5de32e80c08b4adaa04a66b8192f4754d70d247f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 06:09:08 +0000
Subject: [PATCH 10/12] fix(studio): the override popover stays open under the
 pointer, and Restore closes the folded menu

Folded into the header's more menu, the popover is a child of a menu item in
React's tree: a pointer moving over it focused the item and closed it, and
after Restore the menu stayed open behind the confirmation. Events inside the
popover now stop at it, and Restore closes the folded menu before it asks.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUNJci3hxdpiN6RFQ1
---
 .../studio-design/StudioCustomizeControls.tsx | 25 ++++++++++++--
 ...udioItemHeader.titleRowFold-12897.test.tsx | 23 ++++++++++++-
 .../views/studio-design/StudioItemHeader.tsx  | 34 ++++++++++++++++++-
 3 files changed, 77 insertions(+), 5 deletions(-)

diff --git a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
index ad0f6c04dd5..4f6eeb50899 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioCustomizeControls.tsx
@@ -60,6 +60,7 @@ import { Layers, Pencil, RotateCcw } from 'lucide-react';
 import { postureHasOrgWall, useTenancyPosture } from '../../hooks/useTenancyPosture.js';
 import { t, tFormat } from '../metadata-admin/i18n.js';
 import { STUDIO_FOLD_LABEL } from './studio-tokens.js';
+import { useStudioFoldedMenuClose } from './StudioItemHeader.js';
 import { readFields, writeFields, type FieldEntry } from '../metadata-admin/previews/object-fields-io.js';
 
 /**
@@ -283,7 +284,10 @@ export function StudioCustomizeButton({
  * Folded into the header's ⋯ menu (objectstack#29693), the mark is a control
  * inside a menu item: its own click does not reach the item (one press, one
  * toggle), and the item activates it by `data-studio-chip-control` when it
- * is chosen by the keys (`StudioItemHeaderFoldedItems`).
+ * is chosen by the keys (`StudioItemHeaderFoldedItems`). The popover is a
+ * child of that item in React's tree, so what happens in it never reaches
+ * the item: a pointer moving over it would focus the item (and the focus
+ * leaving the popover closes it), a click or Enter would choose the item.
  */
 export function StudioOverrideChip({
   baseLabel,
@@ -300,6 +304,9 @@ export function StudioOverrideChip({
   restoreDisabled?: boolean;
 }): React.ReactElement {
   const [open, setOpen] = React.useState(false);
+  // Folded into the header's ⋯ menu, Restore closes that menu too: the dialog it opens replaces both.
+  const closeMenu = useStudioFoldedMenuClose();
+  const keepInside = (event: React.SyntheticEvent) => event.stopPropagation();
   return (
     <Popover open={open} onOpenChange={setOpen}>
       <PopoverTrigger asChild>
@@ -307,14 +314,25 @@ export function StudioOverrideChip({
           type="button"
           data-testid="studio-override-chip"
           data-studio-chip-control=""
-          onClick={(event) => event.stopPropagation()}
+          onClick={keepInside}
+          // Open, a pointer over the mark does not move the focus to an enclosing menu item.
+          onPointerMove={open ? keepInside : undefined}
           className="inline-flex h-[22px] shrink-0 items-center gap-1 rounded-[5px] bg-sky-500/10 px-2 text-[11px] font-medium text-sky-700 hover:bg-sky-500/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=open]:bg-sky-500/20 dark:text-sky-300"
         >
           <Layers className="h-3 w-3 shrink-0" aria-hidden="true" />
           {tFormat('engine.studio.customize.overrides', locale, { package: baseLabel })}
         </button>
       </PopoverTrigger>
-      <PopoverContent align="start" className="w-72 p-3 text-xs" data-testid="studio-override-popover">
+      <PopoverContent
+        align="start"
+        className="w-72 p-3 text-xs"
+        data-testid="studio-override-popover"
+        onClick={keepInside}
+        onPointerDown={keepInside}
+        onPointerUp={keepInside}
+        onPointerMove={keepInside}
+        onKeyDown={keepInside}
+      >
         <p className="flex items-center gap-1.5 text-sm font-medium text-foreground">
           <Layers className="h-3.5 w-3.5 shrink-0 text-sky-700 dark:text-sky-300" aria-hidden="true" />
           {tFormat('engine.studio.customize.overrides', locale, { package: baseLabel })}
@@ -329,6 +347,7 @@ export function StudioOverrideChip({
             disabled={restoreDisabled}
             onClick={() => {
               setOpen(false);
+              closeMenu?.();
               onRestore();
             }}
             className={cn(
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
index d6f9d4c75a8..7069967d46e 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
@@ -483,11 +483,32 @@ describe('the override mark folded into the ⋯ menu (objectstack#29692)', () =>
     expect(screen.getByRole('menu')).toBeInTheDocument();
   });
 
-  it('Restore in the popover asks the host once and closes the popover', () => {
+  it('Restore in the popover asks the host once and closes the popover and the menu with it', () => {
     const { chip, onRestore } = foldedMark();
     fireEvent.click(chip);
     fireEvent.click(screen.getByTestId('studio-override-restore'));
     expect(onRestore).toHaveBeenCalledTimes(1);
     expect(screen.queryByTestId('studio-override-popover')).toBeNull();
+    // The confirmation replaces both: no menu is left open (hidden) behind it to take the next Enter.
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
+
+  it('a pointer moving over the open popover and pressing in it neither focuses the menu entry nor closes the popover', () => {
+    const { entry, chip, onRestore } = foldedMark();
+    fireEvent.click(chip);
+    const popover = screen.getByTestId('studio-override-popover');
+    const facts = within(popover).getByTestId('studio-override-popover-facts');
+    // Over the mark, then into the popover: the entry would take the focus from it on a pointer move.
+    fireEvent.pointerMove(chip, { pointerType: 'mouse' });
+    fireEvent.pointerMove(facts, { pointerType: 'mouse' });
+    fireEvent.pointerDown(facts, { button: 0, pointerType: 'mouse' });
+    fireEvent.pointerUp(facts, { button: 0, pointerType: 'mouse' });
+    fireEvent.click(facts);
+    fireEvent.keyDown(facts, { key: 'Enter' });
+    expect(document.activeElement).not.toBe(entry);
+    expect(chip).toHaveAttribute('data-state', 'open');
+    expect(screen.getAllByTestId('studio-override-popover')).toHaveLength(1);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    expect(onRestore).not.toHaveBeenCalled();
   });
 });
diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
index 965d21a6e85..96d9bf0deba 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.tsx
@@ -410,6 +410,23 @@ export function useStudioItemHeaderFold(): Pick<StudioItemHeaderFoldValue, 'fold
   return React.useContext(StudioItemHeaderFoldContext);
 }
 
+/** objectstack#29692 — what a control inside the folded chips entry may ask of the ⋯ menu around it. */
+interface StudioFoldedEntryValue {
+  /** Closes the ⋯ menu, as choosing an ordinary entry does. */
+  closeMenu: () => void;
+}
+const StudioFoldedEntryContext = React.createContext<StudioFoldedEntryValue | null>(null);
+
+/**
+ * objectstack#29692 — for a chip's own control (the override mark's Restore):
+ * closes the ⋯ menu the chip is folded into, before the control opens
+ * something of its own (a confirmation). `null` while the chip sits in the
+ * row, where there is no menu to close.
+ */
+export function useStudioFoldedMenuClose(): (() => void) | null {
+  return React.useContext(StudioFoldedEntryContext)?.closeMenu ?? null;
+}
+
 /**
  * objectstack#29693 — what the title row folded away, at the top of a ⋯
  * menu: the identity chips as they read in the row (one entry), then the item
@@ -419,6 +436,15 @@ export function useStudioItemHeaderFold(): Pick<StudioItemHeaderFoldValue, 'fold
  */
 export function StudioItemHeaderFoldedItems({ separator = true }: { separator?: boolean }): React.ReactElement | null {
   const fold = React.useContext(StudioItemHeaderFoldContext);
+  const entryRef = React.useRef<HTMLDivElement | null>(null);
+  /** The next choice of the entry closes the menu: a control inside it asked to. */
+  const closingRef = React.useRef(false);
+  const [entryValue] = React.useState<StudioFoldedEntryValue>(() => ({
+    closeMenu: () => {
+      closingRef.current = true;
+      entryRef.current?.click();
+    },
+  }));
   if (!fold?.folded) return null;
   const hasChips = !!fold.apiName || !!fold.chips;
   if (!hasChips && fold.tools.length === 0) return null;
@@ -433,8 +459,14 @@ export function StudioItemHeaderFoldedItems({ separator = true }: { separator?:
           toggles it once. */}
       {hasChips && (
         <DropdownMenuItem
+          ref={entryRef}
           data-testid="studio-item-header-folded-chips"
           onSelect={(event) => {
+            if (closingRef.current) {
+              // A control inside asked: this choice closes the menu.
+              closingRef.current = false;
+              return;
+            }
             event.preventDefault();
             const target = event.currentTarget instanceof HTMLElement ? event.currentTarget : null;
             target?.querySelector<HTMLElement>('[data-studio-chip-control]')?.click();
@@ -442,7 +474,7 @@ export function StudioItemHeaderFoldedItems({ separator = true }: { separator?:
           className="flex flex-wrap items-center gap-1.5"
         >
           {fold.apiName && <StudioApiChip apiName={fold.apiName} />}
-          {fold.chips}
+          <StudioFoldedEntryContext.Provider value={entryValue}>{fold.chips}</StudioFoldedEntryContext.Provider>
         </DropdownMenuItem>
       )}
       {fold.tools.map(({ id, label, icon: Icon, count, onSelect }) => (

From 25aaa0605ae1d4303b10a8a3f28ab77417569f55 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 06:10:01 +0000
Subject: [PATCH 11/12] docs(changeset): the folded override popover stays open
 and Restore closes the menu

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUNJci3hxdpiN6RFQ1
---
 .changeset/29692-override-chip-restore.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/29692-override-chip-restore.md b/.changeset/29692-override-chip-restore.md
index f36c8e44d30..d1da170ca66 100644
--- a/.changeset/29692-override-chip-restore.md
+++ b/.changeset/29692-override-chip-restore.md
@@ -7,4 +7,4 @@ feat(app-shell): Studio's override mark opens a popover that names the customiza
 Clause-②: no
 Metadata-protocol: none
 
-In Studio, the mark on an item customized into the base's pair ("Overrides HotCRM") used to tell you nothing more, and you had to find "Restore package original" in the item's ⋯ menu. The mark is now a button. Pressing it opens a small popover that says which package the item overrides and which version of it the customization was taken from, with a "Restore package original" button. That button asks through the same confirmation dialog as before, and confirming sends the same two deletes at the pair: its draft, then its row. Customize keeps the header's primary slot, and Restore is never a header button of its own. The ⋯ menus of the Interfaces item, the flow and the All-metadata form editor no longer list Restore, so the mark is the one place to find it. On a narrow header, where the mark folds into the ⋯ menu, it opens the same popover there. Choosing the folded entry with the keyboard opens it too.
+In Studio, the mark on an item customized into the base's pair ("Overrides HotCRM") used to tell you nothing more, and you had to find "Restore package original" in the item's ⋯ menu. The mark is now a button. Pressing it opens a small popover that says which package the item overrides and which version of it the customization was taken from, with a "Restore package original" button. That button asks through the same confirmation dialog as before, and confirming sends the same two deletes at the pair: its draft, then its row. Customize keeps the header's primary slot, and Restore is never a header button of its own. The ⋯ menus of the Interfaces item, the flow and the All-metadata form editor no longer list Restore, so the mark is the one place to find it. On a narrow header, where the mark folds into the ⋯ menu, it opens the same popover there. Choosing the folded entry with the keyboard opens it too. The popover stays open while the pointer moves over it, and Restore there closes the ⋯ menu before the confirmation opens.

From 42a3115d579376fdb179b1296985d951ef5e26b5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 3 Nov 2026 07:53:37 +0000
Subject: [PATCH 12/12] test(studio): the folded override mark keeps working
 with the header's note line

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QsR2jUNJci3hxdpiN6RFQ1
---
 ...udioItemHeader.titleRowFold-12897.test.tsx | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
index 3aa18e93d38..0d3a5ff4f18 100644
--- a/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
+++ b/ui/packages/app-shell/src/views/studio-design/StudioItemHeader.titleRowFold-12897.test.tsx
@@ -530,6 +530,27 @@ describe('the override mark folded into the ⋯ menu (objectstack#29692)', () =>
     expect(screen.getByRole('menu')).toBeInTheDocument();
     expect(onRestore).not.toHaveBeenCalled();
   });
+
+  it('with the note line under the title row (objectstack#29691), the folded mark opens once and Restore closes the menu', () => {
+    layout.row = 330;
+    const onRestore = vi.fn();
+    render(
+      <FoldingLeaf
+        note="Saved to HotCRM’s customizations"
+        kind={<StudioOverrideChip baseLabel="HotCRM" basedOn="4.0.0" locale="en" onRestore={onRestore} />}
+      />,
+    );
+    expect(document.querySelector('[data-slot="item-note"]')).toHaveTextContent('Saved to HotCRM’s customizations');
+    const entry = within(openOwnMore()).getByTestId('studio-item-header-folded-chips');
+    const chip = within(entry).getByTestId('studio-override-chip');
+    fireEvent.click(chip);
+    expect(screen.getAllByTestId('studio-override-popover')).toHaveLength(1);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    fireEvent.click(screen.getByTestId('studio-override-restore'));
+    expect(onRestore).toHaveBeenCalledTimes(1);
+    expect(screen.queryByTestId('studio-override-popover')).toBeNull();
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
 });
 
 describe('the note line sits under the title row, outside the fold (objectstack#29691)', () => {