@estiva-app/ui 0.22.0 → 0.24.0

package/src/AppShell.mdx

@@ -75,6 +75,16 @@ import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
 - In the floating manner the card owns `overflow-hidden` — your content
   manages its own scrolling inside it.
 - Desktop only for now — no narrow-screen behaviour is provided.
+- In the Signal theme the floating frame draws the control-room dot grid on
+  its ground, behind the card. Nothing to add: the preset makes it.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Scrolls the page's content column, in a ScrollArea | `overflow-auto` on the page or on `main` |  |
 
 ## Props
 

package/src/AppShell.test.tsx

@@ -36,4 +36,20 @@ describe('AppShell', () => {
     expect(main.className).toContain('overflow-hidden')
     expect(main.closest('[style*="overflow: scroll"]')).toBeNull()
   })
+
+  it('carries the Signal canvas on the floating frame, and only there', () => {
+    const { container, unmount } = render(
+      <AppShell variant="floating" nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    expect((container.firstElementChild as HTMLElement).className).toContain('signal-canvas')
+    unmount()
+    const solid = render(
+      <AppShell nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    expect(solid.container.querySelector('.signal-canvas')).toBeNull()
+  })
 })

package/src/AppShell.tsx

@@ -45,7 +45,10 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
 
   if (variant === 'floating') {
     return (
-      <div className="relative h-full min-h-0 overflow-hidden bg-bg-base">
+      // `signal-canvas`: in the Signal theme, the preset draws the control-room dot
+      // grid behind everything in the frame (Peek's, moved here with the frame:
+      // UIG-14, Katerina, 19 September — the canvas is the theme's, not an app's).
+      <div className="signal-canvas relative h-full min-h-0 overflow-hidden bg-bg-base">
         {bar}
         <div className="flex h-full pb-4 pr-4 pt-[52px]">
           {nav}

package/src/AttachmentCard.mdx

@@ -57,6 +57,15 @@ import { AttachmentCard } from '@estiva-app/ui'
   on Base UI's `Button` like InputChip's ✕ — not an `IconButton`, the 24px
   square that fills on hover.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Stops the clicks on its picture, its download and its remove control, so they never also click the card or row around it | `stopPropagation` |  |
+| Shows the full name on hover when the name is cut off | a tooltip of your own |  |
+
 ## Props
 
 <Controls of={AttachmentCardStories.Document} />

package/src/AttachmentCard.test.tsx

@@ -169,4 +169,14 @@ describe('AttachmentCard', () => {
     expect(onRemove).toHaveBeenCalledTimes(1)
     expect(outside).not.toHaveBeenCalled()
   })
+
+  it('the ✕ shows when the keyboard reaches it, not only on hover (C4)', async () => {
+    render(<AttachmentCard pending name="a.png" size={1} onRemove={() => {}} />)
+    const remove = screen.getByRole('button', { name: 'Remove a.png' })
+    // Hidden at rest; each of these reveals it. jsdom draws nothing, so the classes are the contract.
+    expect(remove.className).toContain('opacity-0')
+    for (const reveal of ['group-hover:opacity-100', 'group-focus-within:opacity-100', 'focus-visible:opacity-100']) expect(remove.className).toContain(reveal)
+    await userEvent.tab()
+    expect(document.activeElement).toBe(remove)
+  })
 })

package/src/AttachmentCard.tsx

@@ -20,7 +20,7 @@ import {
 import { Card } from './Card'
 import { IconButton } from './IconButton'
 import { Link } from './Link'
-import { WithTooltip } from './Tooltip'
+import { WithTooltip, type WithTooltipProps } from './Tooltip'
 import { cn } from './cn'
 
 /**
@@ -98,7 +98,7 @@ function TypeIcon({ name }: { name: string }) {
  * the fallback face can fit and then not, in a line whose box never changes. The wrapper is `flex-col` so the
  * text stretches across it, as wide as it is without one.
  */
-function Truncating({ text, hint, className, wrapperClassName }: { text: string; hint?: string; className: string; wrapperClassName?: string }) {
+function Truncating({ text, hint, className, wrapperClassName, placement }: { text: string; hint?: string; className: string; wrapperClassName?: string; placement?: WithTooltipProps['placement'] }) {
   const ref = useRef<HTMLSpanElement>(null)
   const [cut, setCut] = useState(false)
   useLayoutEffect(() => {
@@ -127,7 +127,7 @@ function Truncating({ text, hint, className, wrapperClassName }: { text: string;
   )
   if (!hint && !cut) return line
   return (
-    <WithTooltip label={hint ?? text} wrapperClassName={cn('min-w-0 flex-col', wrapperClassName)}>
+    <WithTooltip label={hint ?? text} placement={placement} wrapperClassName={cn('min-w-0 flex-col', wrapperClassName)}>
       {line}
     </WithTooltip>
   )
@@ -206,7 +206,8 @@ export function AttachmentCard({
           )}
         </div>
         <div className="flex flex-col gap-[1px] min-w-0">
-          <Truncating text={name} className={NAME_CLASSES} />
+          {/* Below, not above: above, a cut name's tooltip covered the ✕ on the corner (UIG-14, C4). */}
+          <Truncating text={name} className={NAME_CLASSES} placement={onRemove ? 'bottom' : undefined} />
           <Truncating
             text={(failed || warning ? note : state === 'uploading' ? (note ?? 'Uploading…') : (note ?? sizeText)) ?? ''}
             hint={noteHint}
@@ -219,7 +220,9 @@ export function AttachmentCard({
           <BaseButton
             type="button"
             aria-label={`Remove ${name}`}
-            className="absolute -top-1.5 -right-1.5 size-5 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary opacity-0 group-hover:opacity-100 transition-opacity"
+            // Shows with the card's hover and with keyboard focus, as Download does: hover-only left it invisible to
+            // the keyboard that had reached it (UIG-14, C4, Katerina 19 September).
+            className="absolute -top-1.5 -right-1.5 size-5 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 focus-visible:opacity-100 transition-opacity"
             onClick={(event) => {
               event.stopPropagation()
               onRemove()

package/src/Avatar.mdx

@@ -13,13 +13,15 @@ theirs, or — when there is no name to take initials from — a silhouette.
 ## When
 
 - Anywhere a person appears at a glance: a row, a card, a picker, a byline.
-- The scale is 16 · 24 · 32 · 36 (default) — pick from it rather than
-  inventing sizes.
+- The scale is 16 · 18 · 20 · 24 · 32 · 36 (default): 18 in a group's reply
+  row, 20 in a **Person**. Pick from it rather than inventing sizes.
 
 ## When not
 
 - Several people at once → **AvatarGroup**.
-- The face beside the name → **Person**.
+- The face beside a name, with nothing else on the line → **Person**. A byline
+  that sets the name its own way — bold, with a time — is an Avatar beside its
+  own text.
 - The face as a button that opens a menu → **PersonTrigger**.
 
 ## How
@@ -66,6 +68,14 @@ a stack of members — and the tile becomes one image with one name.
 
 <Canvas of={AvatarStories.Palette} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Shows initials from the name when there is no picture, or when it fails to load | an `onError`, or initials of your own |  |
+
 ## Props
 
 <Controls of={AvatarStories.Initials} />

package/src/AvatarGroup.mdx

@@ -34,6 +34,10 @@ import { AvatarGroup } from '@estiva-app/ui'
 - The ring rides on the Avatar itself (one box); don't wrap each face in a
   clipping window — a window minus a border crops the initials.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={AvatarGroupStories.ThreeMembers} />

package/src/Banner.mdx

@@ -12,8 +12,8 @@ line, one of four tones, gone when there is nothing to say.
 
 ## When
 
-- The outcome or state of the whole surface: "Public key copied.", the
-  reason the last read failed, a read-only notice.
+- The state of the whole surface: the reason the last read failed, a read-only
+  notice.
 - **`ok`** confirms, **`info`** informs, **`warning`** cautions,
   **`error`** reports a failure — and only `error` announces itself
   (`role="alert"`); the others are polite (`role="status"`).
@@ -22,14 +22,15 @@ line, one of four tones, gone when there is nothing to say.
 
 ## When not
 
-- Feedback about one action, briefly → **Toast**.
+- Feedback about one action, briefly → **Toast**. A failure is the exception:
+  it stays, in the Banner, until the person acts on it.
 - Something that floats over the page and must **not** fade → still
   **Toast**, with `durationMs: 0` and an action. A banner is the strip
   under the header at the app's full width; a floating pill is not one, even
   a permanent one (Katerina, D21).
 - A standing property of one thing → **Chip** on that thing.
-- A notice inside the content flow with its own action — that is a
-  different component (not in the package yet).
+- More than one action, or a second line of text — that is a different
+  component (not in the package yet).
 
 ## How
 
@@ -41,13 +42,35 @@ import { Banner } from '@estiva-app/ui'
 
 - Render it only while there is something to say — an empty strip is not
   a state.
-- One line of plain text, `body-2`. If it needs a **second line or an
-  action of its own**, it has outgrown this component.
+- One line of text, `body-2`. If it needs a **second line**, it has outgrown
+  this component.
+- `icon` puts a 16px icon before the line and `action` one small muted Button
+  at the end of it, both in the tone (Katerina, 2026-09-18: Peek's strip above
+  the composer became a Banner, `info`). With either, the banner is one line
+  and the text truncates. One action at most.
+
+<Canvas of={BannerStories.WithIconAndAction} />
+
+```tsx
+<Banner tone="info" icon={<IconUserPlus size={16} stroke={1.5} />} action={{ label: 'Join', onClick: join }}>
+  You are not in <span className="font-medium">{title}</span> yet
+</Banner>
+```
+
 - `onDismiss` adds an ✕ at the right-hand end (Katerina, D21). Use it where
   the reader decides the notice is done with, rather than the app. The row
   is 40px rather than 36px with it, because the button is taller than the
   line of text; without it, nothing about the strip changes.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: an alert for an error, a status for the rest | `role="alert"` or `role="status"` | ✓ |
+| Draws its own ✕ when you pass `onDismiss`, and its one small action when you pass `action` | a close button or an action button of your own |  |
+
 ## Props
 
 <Controls of={BannerStories.Ok} />

package/src/Banner.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconPencilMinus, IconUserPlus } from '@tabler/icons-react'
 import { Banner } from './Banner'
 
 const meta = {
@@ -34,6 +35,27 @@ export const Dismissible: Story = {
   args: { tone: 'warning', children: 'This workspace is read-only until sign-in.', onDismiss: () => {} },
 }
 
+/**
+ * With an icon and one action (Katerina, 2026-09-18). One line: the text
+ * truncates, and the Button stays at the end.
+ */
+export const WithIconAndAction: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-full max-w-xl flex-col gap-2">
+      <Banner tone="info" icon={<IconPencilMinus size={16} stroke={1.5} />} action={{ label: 'Invite people', onClick: () => {} }}>
+        This is the start of the conversation in <span className="font-medium">Project Alpha</span>
+      </Banner>
+      <Banner tone="info" icon={<IconPencilMinus size={16} stroke={1.5} />}>
+        This is the start of your conversation with <span className="font-medium">Sam Lee</span>
+      </Banner>
+      <Banner tone="info" icon={<IconUserPlus size={16} stroke={1.5} />} action={{ label: 'Join', onClick: () => {} }}>
+        You are not in <span className="font-medium">Project Alpha</span> yet — join to take part in the conversation
+      </Banner>
+    </div>
+  ),
+}
+
 /** All four tones, stacked. */
 export const AllTones: Story = {
   parameters: { controls: { disable: true } },

package/src/Banner.test.tsx

@@ -57,4 +57,39 @@ describe('Banner', () => {
     )
     expect(container.firstElementChild!.getAttribute('role')).toBe('alert')
   })
+
+  it('puts an icon before the line and one small muted action after it, on one line (Katerina, 2026-09-18)', async () => {
+    const onClick = vi.fn()
+    const { container } = render(
+      <Banner tone="info" icon={<svg data-testid="icon" />} action={{ label: 'Join', onClick }}>
+        You are not in <b>Alpha</b> yet
+      </Banner>,
+    )
+    const row = container.firstElementChild!
+    expect(row.getAttribute('role')).toBe('status')
+    expect(row.firstElementChild!.querySelector('[data-testid="icon"]')).not.toBeNull()
+    const line = screen.getByText(/You are not in/)
+    expect(line.className).toContain('truncate')
+    const button = screen.getByRole('button', { name: 'Join' })
+    expect(line.nextElementSibling).toBe(button)
+    await userEvent.click(button)
+    expect(onClick).toHaveBeenCalledOnce()
+    // No dismiss unless asked for.
+    expect(screen.queryByRole('button', { name: 'Dismiss' })).toBeNull()
+  })
+
+  it('an icon alone still keeps the line on one line, and a dismiss alone still wraps', () => {
+    const { rerender } = render(
+      <Banner tone="info" icon={<svg />}>
+        One line
+      </Banner>,
+    )
+    expect(screen.getByText('One line').className).toContain('truncate')
+    rerender(
+      <Banner tone="info" onDismiss={() => {}}>
+        One line
+      </Banner>,
+    )
+    expect(screen.getByText('One line').className).not.toContain('truncate')
+  })
 })

package/src/Banner.tsx

@@ -1,4 +1,6 @@
+import type { ReactNode } from 'react'
 import { IconX } from '@tabler/icons-react'
+import { Button } from './Button'
 import { cn } from './cn'
 import { IconButton } from './IconButton'
 
@@ -13,6 +15,11 @@ import { IconButton } from './IconButton'
  * An `error` announces itself (`role="alert"`); the other tones are
  * polite (`role="status"`).
  *
+ * `icon` and `action` put a 16px icon before the line and one small muted
+ * Button after it (Katerina, 2026-09-18, UIG-13: Peek's composer strip became
+ * a Banner in the `info` tone). With either, the banner is one line and the
+ * text truncates.
+ *
  * `onDismiss` adds an `✕` at the right-hand end (Katerina, D21,
  * 2026-09-07). Without it the strip is exactly what it was — a banner an
  * app removes by not rendering it. With it the row is 40px rather than
@@ -28,7 +35,16 @@ export type BannerTone = 'ok' | 'error' | 'info' | 'warning'
 
 export interface BannerProps {
   tone: BannerTone
-  children: string
+  /** The one line. Text, or text with a name in `font-medium`. */
+  children: ReactNode
+  /**
+   * A 16px icon before the line, in the tone's colour (Katerina, 2026-09-18:
+   * Peek's composer strip became a Banner). With an icon or an action the
+   * banner is one line, and the text truncates.
+   */
+  icon?: ReactNode
+  /** The one thing to do: the package's Button, muted and small, at the end of the line. */
+  action?: { label: string; onClick?: () => void }
   /** Adds an `✕` at the right-hand end. Absent: the app removes the banner. */
   onDismiss?: () => void
   /** The dismiss button's accessible name. Defaults to "Dismiss". */
@@ -43,25 +59,34 @@ const TONE_STYLES: Record<BannerTone, string> = {
   warning: 'bg-warning-muted text-warning-default',
 }
 
-export function Banner({ tone, children, onDismiss, dismissLabel = 'Dismiss', className }: BannerProps) {
+export function Banner({ tone, children, icon, action, onDismiss, dismissLabel = 'Dismiss', className }: BannerProps) {
   const role = tone === 'error' ? 'alert' : 'status'
-  // No dismiss, no row: every banner that predates the prop keeps the DOM and
-  // the height it had.
-  if (!onDismiss) {
+  // Nothing beside the line, no row: every banner that predates the props keeps
+  // the DOM and the height it had.
+  if (!onDismiss && !icon && !action) {
     return (
       <div role={role} className={cn('px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
         {children}
       </div>
     )
   }
+  const oneLine = Boolean(icon || action)
   return (
     <div role={role} className={cn('flex items-center gap-3 px-4 py-2 text-body-2', TONE_STYLES[tone], className)}>
-      <span className="min-w-0 flex-1">{children}</span>
+      {icon && <span className="flex shrink-0">{icon}</span>}
+      <span className={cn('min-w-0 flex-1', oneLine && 'truncate')}>{children}</span>
+      {action && (
+        <Button variant="muted" size="small" className="shrink-0" onClick={action.onClick}>
+          {action.label}
+        </Button>
+      )}
       {/* `current` so the ✕ takes the tone's colour rather than the
           muted grey an IconButton wears on a neutral surface. */}
-      <IconButton variant="current" aria-label={dismissLabel} onClick={onDismiss} className="-mr-1 shrink-0">
-        <IconX size={16} stroke={1.5} />
-      </IconButton>
+      {onDismiss && (
+        <IconButton variant="current" aria-label={dismissLabel} onClick={onDismiss} className="-mr-1 shrink-0">
+          <IconX size={16} stroke={1.5} />
+        </IconButton>
+      )}
     </div>
   )
 }

package/src/Breadcrumb.mdx

@@ -56,6 +56,16 @@ import { Breadcrumb } from '@estiva-app/ui'
   `min-w-0` container so it can truncate at all.
 - The separators are `aria-hidden` — the trail reads as its places.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Shortens a trail that does not fit, and shows a cut crumb in full on hover | truncation code, or a tooltip |  |
+| Names itself as a navigation, and marks the last crumb as the current page | `<nav>`, `aria-label` or `aria-current` |  |
+| Hides the separators from screen readers, so the trail reads as its places | `aria-hidden` on each separator |  |
+
 ## Props
 
 <Controls of={BreadcrumbStories.OnAnItem} />

package/src/Button.mdx

@@ -27,12 +27,13 @@ The push-button for an action: a verb, clicked once — "Create", "Save",
 ## When not
 
 - An icon with no label → **IconButton**.
-- Going somewhere rather than doing something → **Tabs**, **Breadcrumb**,
-  or a plain link.
+- Going somewhere rather than doing something → **Link**; **Tabs** or
+  **Breadcrumb** when it is a view or a trail.
 - Choosing a value → **Select**. Acting from a popover list → **MenuItem**.
 - A control the person may never be allowed to use is **absent, not
   disabled**. `disabled` is for *momentarily* unavailable — and it says why,
-  with `disabledReason` ("Available after sign-in").
+  with `disabledReason` ("Available after sign-in"). A send button waiting for
+  its fields needs no reason.
 
 ## How
 
@@ -68,6 +69,16 @@ import { IconPlus } from '@tabler/icons-react'
   flex and grid, and position; a colour, a text size, a border, a corner or a
   shadow is refused by the lint (`estiva/no-restyled-part`, UIG-9).
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a button | `role="button"` | ✓ |
+| Is reachable with Tab, also when it is disabled with a reason | a `tabIndex` | ✓ |
+| Presses on Enter and Space, and does nothing while disabled | a key handler |  |
+
 ## Keys
 
 | Key | Does |

package/src/Card.mdx

@@ -76,6 +76,15 @@ import { Card } from '@estiva-app/ui'
   shadow is refused by the lint (`estiva/no-restyled-part`, UIG-9). What is inside the card is yours: its padding and its words go on
   your own element inside.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| With `href`, becomes a link: Link's anchor, with a real address | an anchor around the card |  |
+| Without `href`, shows it can be clicked when you pass `onClick` | `cursor-pointer` |  |
+
 ## Props
 
 <Controls of={CardStories.Surface} />

package/src/Checkbox.mdx

@@ -79,6 +79,16 @@ import { Checkbox } from '@estiva-app/ui'
 - It does not move when it toggles: the tick is always in the box, hidden
   when unchecked, so both states hang on a line of text the same way.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Says what it is to assistive technology: a checkbox, ticked or not | `role="checkbox"` or `aria-checked` | ✓ |
+| Toggles on Space and on a click; Enter is left to the form | a click or key handler |  |
+| Is one Tab stop, in a `row` too | a `tabIndex` on the row |  |
+
 ## Keys
 
 | Key | Does |

package/src/Chip.mdx

@@ -38,6 +38,10 @@ import { Chip } from '@estiva-app/ui'
   it never rides the text baseline.
 - A count alone works too — `label="3"`, no icon.
 
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
 ## Props
 
 <Controls of={ChipStories.Neutral} />

package/src/ChipInput.mdx

@@ -74,6 +74,18 @@ import { ChipInput } from '@estiva-app/ui'
 
 <Canvas of={ChipInputStories.ALongLabelCut} />
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page: its suggestions | a portal, or a `z-index` to win | ✓ |
+| Moves through its items with the arrow keys, through the suggestions | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a combobox and its options | `role="combobox"`, `listbox` or `option` | ✓ |
+| Filters as you type; Enter adds the highlighted entry, Backspace on an empty query removes the last chip | a filter, or key handlers |  |
+| Escape clears the query first, and only then lets the surface around it act | an Escape handler |  |
+
 ## Keys
 
 | Input | What happens |

package/src/CollapsibleSection.mdx

@@ -60,6 +60,15 @@ import { CollapsibleSection, NavItem } from '@estiva-app/ui'
   with `open`.
 - A browser that blocks storage still gets a working section; it forgets.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Opens and closes from its title, on a click, Enter or Space | open state, or a key handler |  |
+| Tells assistive technology whether it is open | `aria-expanded` |  |
+
 ## Keys
 
 | Key | Does |

package/src/CommandPalette.mdx

@@ -49,8 +49,8 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
     onQueryChange={setQuery}
     placeholder="Search, or choose a place"
     groups={[
-      { label: 'Recent', rows: [{ id: 'item-one', label: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: open, onForget: forget }] },
-      { label: 'Places', rows: [{ id: 'place-one', label: 'Place one', icon, onSelect: goIn, onGoIn: goIn }] },
+      { label: 'Recent', rows: [{ id: 'item-one', label: 'Item one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: openItem, onForget: forget }] },
+      { label: 'Places', rows: [{ id: 'place-one', label: 'Place one', icon: <IconSquareRounded size={16} stroke={1.5} />, onSelect: goIn, onGoIn: goIn }] },
     ]}
   />
 </CommandPalette>
@@ -102,6 +102,18 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 - **Focus never falls out of a level.** When the element that had it goes — a
   row picked, a level swapped — focus goes to the level's first control.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Holds focus inside while open, and gives it back to whatever opened it | focus code, or a Tab handler | ✓ |
+| Moves through its items with the arrow keys, through the rows, stopping at the ends | an arrow-key handler | ✓ |
+| Says what it is to assistive technology: a list of options you search | `role="combobox"`, `listbox` or `option` | ✓ |
+| Closes on Esc or a click outside; Esc closes an open list first | close handlers |  |
+
 ## Keys
 
 | Where | Input | What happens |

package/src/ConfirmDialog.mdx

@@ -53,6 +53,17 @@ import { ConfirmDialog } from '@estiva-app/ui'
 - Focus is trapped in the card and returns to whatever opened it, as for
   every dialog since stage 3.
 
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page | a portal, or a `z-index` to win | ✓ |
+| Says what it is to assistive technology: a dialog that must be answered | `role="alertdialog"` | ✓ |
+| Keeps focus inside while open, as DialogShell does, and gives it back to whatever opened it | focus code |  |
+| Ignores a press outside, because the question has to be answered; Escape cancels | a backdrop handler |  |
+
 ## Keys
 
 Different from `DialogShell`'s in one row, and it is the row that matters.

package/src/ContainerHeader.mdx

@@ -0,0 +1,60 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ContainerHeaderStories from './ContainerHeader.stories'
+
+<Meta of={ContainerHeaderStories} />
+
+# ContainerHeader
+
+The bar across the top of a column — a list, a thread, a side panel: its
+title, and the buttons that act on the whole column at the right edge. 48px,
+with a hairline under it. Peek's ContainerHeader, moved into the package as it
+looks (Katerina, 2026-09-18).
+
+<Canvas of={ContainerHeaderStories.WithActions} />
+
+## When
+
+- The top of a column in a frame: the list beside the conversation, the
+  thread, a side panel. One per column.
+- The column's own actions — new, sort, close — as IconButtons with tooltips
+  in `actions`.
+
+## When not
+
+- One section inside a column → **SectionHeader**, the 32px row with a
+  SectionLabel.
+- The top of the whole app → **TopBar**.
+- A dialog's title → **DialogShell** draws its own.
+
+## How
+
+```tsx
+import { ContainerHeader, IconButton } from '@estiva-app/ui'
+
+<ContainerHeader
+  title="All items"
+  chevron
+  actions={
+    <IconButton tooltip="New item" aria-label="New item" onClick={openNew}>
+      <IconEdit size={16} stroke={1.5} />
+    </IconButton>
+  }
+/>
+```
+
+- A string title is one line in `body-2-strong` and keeps its width. Anything
+  else — an EditableText, a title over a caption — takes the room left and is
+  drawn as given.
+
+<Canvas of={ContainerHeaderStories.WithRichTitle} />
+
+- Only offer a button that does something: a button with nothing behind it is
+  a promise the column cannot keep.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Props
+
+<Controls of={ContainerHeaderStories.Default} />