@estiva-app/ui 0.59.0 → 0.60.1

package/src/SearchInput.tsx

@@ -13,9 +13,9 @@ import { BARE_INPUT_CLASSES, FIELD_SHELL_CLASSES } from './looks'
  * The one product string — Peek's default placeholder "Search Peek..." —
  * stays in Peek; the default here says only "Search…".
  *
- * In Peek's top bar this is a launcher affordance rather than a live field:
- * the input is `pointer-events-none` and clicking the surround opens the
- * command launcher. The component is the same either way.
+ * The top bar's way into a launcher is not this: `TopBar`'s `onSearch` draws
+ * this look as a button and answers Ctrl+K itself (8 October). Peek used to
+ * make this field inert and catch the click around it.
  *
  * On Base UI's `Input` since stage 3 of the migration (2026-09-07), so a
  * search field inside a `Field` is labelled by it without the caller wiring

package/src/Sidebar.mdx

@@ -48,8 +48,8 @@ import { Sidebar, NavItem, CollapsibleSection, SectionHeader } from '@estiva-app
 ```
 
 **Every row is a plain anchor, so in a router app each click would reload
-the page.** Keep NavItem's rule: a thin wrapper computes `active` from the
-location, intercepts the click and navigates in place — see **NavItem**.
+the page** — unless the app gives **AppProvider**'s `navigate`, which
+changes page in place. See **NavItem**.
 
 Anything you place directly in the column needs `shrink-0` (both headings
 above take it in `className`):

package/src/TopBar.mdx

@@ -5,7 +5,7 @@ import * as TopBarStories from './TopBar.stories'
 
 # TopBar
 
-The 52px top bar: `menu` and `logo` on the left, a `search` slot in the
+The 52px top bar: `menu` and `logo` on the left, the search field in the
 centre, the identity cluster on the right. Three manners — **`solid`**,
 in flow with a hairline and a surface; **`inset`**, in flow with neither,
 standing on the ground; and **`floating`**, an overlay with neither, whose
@@ -27,8 +27,12 @@ bar ignores the pointer so the content underneath stays reachable.
 - `menu` is the menu button, in an app whose navigation collapses — the
   collapsing itself stays the caller's. `logo` sits beside it: the app's
   name as text, or a mark.
-- The `search` slot holds its place even while empty, so a search field
-  drops in later without moving anything.
+- `onSearch` is what searching opens — your command launcher. With it the
+  bar draws the search field itself: **SearchInput**'s look, 290px, as a
+  button showing `searchPlaceholder` ("Search…") and the shortcut. A click on
+  it, and Ctrl+K (Cmd+K on a Mac) anywhere on the page, call `onSearch`.
+- The centre holds its place even while empty, so search drops in later
+  without moving anything.
 
 <Canvas of={TopBarStories.FloatingNoSearch} />
 
@@ -37,25 +41,31 @@ bar ignores the pointer so the content underneath stays reachable.
 - Page-level headers inside the content → not this; this is the frame's
   bar, once per app. The top of a column is **ContainerHeader**.
 - Anything the bar would need to know — who you are, what is searched —
-  stays outside: pass composed slots.
+  stays outside: pass composed slots, and what searching opens as `onSearch`.
+- A search field of your own in the centre → only for something the bar's
+  does not do; pass it as `search`, which takes the centre (`onSearch` still
+  answers Ctrl+K). A field that filters a list sits above that list:
+  **SearchInput**.
 
 ## How
 
 ```tsx
-import { TopBar, IdentityMenu, SearchInput } from '@estiva-app/ui'
+import { TopBar, IdentityMenu } from '@estiva-app/ui'
 
 <TopBar
   logo="Estiva"
-  search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />}
+  onSearch={openLauncher}
+  searchPlaceholder="Search Estiva…"
   right={<IdentityMenu me={me} signedIn={signedIn} />}
 />
 ```
 
 - Geometry is fixed: 52px, `pl-5 pr-[26px]`, right cluster `gap-[6px]` —
   don't restyle it per app.
-- In `floating`, a launcher-affordance search is the caller's trick: keep
-  the input `pointer-events-none` and open the launcher from a wrapper's
-  `mousedown` (see SearchInput's page).
+- `onSearch` is called on every Ctrl+K, open or not: to close the launcher
+  on a second Ctrl+K, toggle in your handler.
+- A click on the field leaves focus where it was, so a launcher can act on the
+  text box and the selection you were in. Tab still reaches the field.
 - The frame is desktop-only for now — there is no narrow-screen
   behaviour; the menu button collapses panels, it does not open a drawer.
 
@@ -69,6 +79,7 @@ It does these by itself. Write none of them around it.
 | It does | So you never write | Refused when written by hand |
 |---|---|---|
 | Keeps its 52px in a scrolling column | `shrink-0` |  |
+| Answers Ctrl+K (Cmd+K) anywhere on the page, given `onSearch` | a `keydown` listener on the window |  |
 
 ## Props
 

package/src/TopBar.stories.tsx

@@ -1,9 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconMenu2 } from '@tabler/icons-react'
-import type { ReactNode } from 'react'
+import { useState, type ReactNode } from 'react'
 import { IconButton } from './IconButton'
 import { PersonTrigger } from './PersonTrigger'
-import { SearchInput } from './SearchInput'
 import { TopBar } from './TopBar'
 
 /**
@@ -26,6 +25,7 @@ const meta = {
     menu: { control: false },
     logo: { control: false },
     search: { control: false },
+    onSearch: { control: false },
     right: { control: false },
   },
 } satisfies Meta<typeof TopBar>
@@ -60,11 +60,29 @@ const Behind = ({ children }: { children: ReactNode }) => (
 export const Solid: Story = {
   render: (args) => (
     <Below>
-      <TopBar {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} right={face} />
+      <TopBar {...args} logo="Estiva" onSearch={() => {}} right={face} />
     </Below>
   ),
 }
 
+/**
+ * The bar's own search field: a click on it, or Ctrl+K (Cmd+K on a Mac)
+ * anywhere, calls `onSearch` — here it counts, where an app opens its launcher.
+ */
+export const Search: Story = {
+  render: function Search(args) {
+    const [opened, setOpened] = useState(0)
+    return (
+      <div className="flex h-40 flex-col overflow-hidden bg-bg-base">
+        <TopBar {...args} logo="Estiva" onSearch={() => setOpened((n) => n + 1)} searchPlaceholder="Search Estiva…" right={face} />
+        <div className="flex flex-1 items-center justify-center text-body-2 text-text-secondary">
+          {opened === 0 ? 'Click the field, or press Ctrl+K.' : `Search opened ${opened} ${opened === 1 ? 'time' : 'times'}.`}
+        </div>
+      </div>
+    )
+  },
+}
+
 /** No search yet: the centre slot holds its place, so it drops in later without moving anything. */
 export const SolidNoSearch: Story = {
   render: (args) => (
@@ -78,7 +96,7 @@ export const SolidNoSearch: Story = {
 export const Floating: Story = {
   render: (args) => (
     <Behind>
-      <TopBar {...args} variant="floating" menu={menuButton} search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} right={face} />
+      <TopBar {...args} variant="floating" menu={menuButton} onSearch={() => {}} right={face} />
     </Behind>
   ),
 }

package/src/TopBar.test.tsx

@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+/**
+ * The bar's own search field, pinned: given `onSearch` it draws a button with
+ * the words and the shortcut, a click and Ctrl+K or Cmd+K anywhere call it,
+ * a `search` of the caller's own still takes the centre, and without either
+ * the bar draws nothing there and leaves the keys alone.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { AppShell } from './AppShell'
+import { TopBar } from './TopBar'
+
+afterEach(cleanup)
+
+const press = (init: KeyboardEventInit) => {
+  const event = new KeyboardEvent('keydown', { bubbles: true, cancelable: true, ...init })
+  window.dispatchEvent(event)
+  return event
+}
+
+describe('TopBar search', () => {
+  it('draws a search field that opens the search', async () => {
+    const onSearch = vi.fn()
+    render(<TopBar onSearch={onSearch} searchPlaceholder="Search Peek..." />)
+    const field = screen.getByRole('button', { name: /Search Peek\.\.\./ })
+    expect(field.textContent).toMatch(/Ctrl\+K|Cmd\+K/)
+    await userEvent.click(field)
+    expect(onSearch).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves focus where it was on a click', async () => {
+    const onSearch = vi.fn()
+    render(
+      <>
+        <input aria-label="composer" />
+        <TopBar onSearch={onSearch} />
+      </>,
+    )
+    const composer = screen.getByRole('textbox', { name: 'composer' })
+    composer.focus()
+    await userEvent.click(screen.getByRole('button', { name: /Search…/ }))
+    expect(onSearch).toHaveBeenCalledTimes(1)
+    expect(document.activeElement).toBe(composer)
+  })
+
+  it('is reached with Tab and pressed with Enter', async () => {
+    const onSearch = vi.fn()
+    render(<TopBar onSearch={onSearch} />)
+    await userEvent.tab()
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: /Search…/ }))
+    await userEvent.keyboard('{Enter}')
+    expect(onSearch).toHaveBeenCalledTimes(1)
+  })
+
+  it('says "Search…" when given no words', () => {
+    render(<TopBar onSearch={() => {}} />)
+    expect(screen.getByRole('button', { name: /Search…/ })).toBeTruthy()
+  })
+
+  it.each([
+    ['Ctrl+K', { ctrlKey: true, key: 'k' }],
+    ['Cmd+K', { metaKey: true, key: 'k' }],
+    ['Ctrl+Shift+K', { ctrlKey: true, shiftKey: true, key: 'K' }],
+  ])('opens the search on %s anywhere', (_name, init) => {
+    const onSearch = vi.fn()
+    render(<TopBar onSearch={onSearch} />)
+    const event = press(init)
+    expect(onSearch).toHaveBeenCalledTimes(1)
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('calls the latest handler', () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    const { rerender } = render(<TopBar onSearch={first} />)
+    rerender(<TopBar onSearch={second} />)
+    press({ ctrlKey: true, key: 'k' })
+    expect(first).not.toHaveBeenCalled()
+    expect(second).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves K alone without a modifier, and the keys alone without onSearch', () => {
+    const onSearch = vi.fn()
+    const { unmount } = render(<TopBar onSearch={onSearch} />)
+    press({ key: 'k' })
+    expect(onSearch).not.toHaveBeenCalled()
+    unmount()
+    render(<TopBar />)
+    expect(press({ ctrlKey: true, key: 'k' }).defaultPrevented).toBe(false)
+    expect(screen.queryByRole('button')).toBeNull()
+  })
+
+  it('stops listening once it is gone', () => {
+    const onSearch = vi.fn()
+    const { unmount } = render(<TopBar onSearch={onSearch} />)
+    unmount()
+    press({ ctrlKey: true, key: 'k' })
+    expect(onSearch).not.toHaveBeenCalled()
+  })
+
+  it("draws the caller's own centre instead, and still answers the keys", () => {
+    const onSearch = vi.fn()
+    render(<TopBar onSearch={onSearch} search={<span>own</span>} />)
+    expect(screen.getByText('own')).toBeTruthy()
+    expect(screen.queryByRole('button')).toBeNull()
+    press({ ctrlKey: true, key: 'k' })
+    expect(onSearch).toHaveBeenCalledTimes(1)
+  })
+
+  it('reaches the bar through AppShell', async () => {
+    const onSearch = vi.fn()
+    render(
+      <AppShell variant="floating" nav={<nav />} onSearch={onSearch} searchPlaceholder="Search Peek...">
+        <p>page</p>
+      </AppShell>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: /Search Peek\.\.\./ }))
+    expect(onSearch).toHaveBeenCalledTimes(1)
+  })
+})

package/src/TopBar.tsx

@@ -1,5 +1,9 @@
-import type { ReactNode } from 'react'
+import { useEffect, useRef, type ReactNode } from 'react'
+import { Button as BaseButton } from '@base-ui/react/button'
 import { cn } from './cn'
+import { Kbd } from './Kbd'
+import { FIELD_SHELL_CLASSES } from './looks'
+import { shortcutLabel } from './shortcuts'
 
 /**
  * The 52px top bar, in three manners:
@@ -21,6 +25,18 @@ import { cn } from './cn'
  * collapses) and `logo` (the mark or name beside it; Katerina,
  * 2026-09-02). This component does not know who you are or what is being
  * searched; it only knows where those go.
+ *
+ * **Search** (Katerina, 8 October: "topbar has a variant with a search input,
+ * I assumed it would use it"). Given `onSearch`, the bar draws the search
+ * field itself — `SearchInput`'s look, 290px, as a button that opens what the
+ * app searches with — and Ctrl+K (Cmd+K on a Mac) presses it from anywhere.
+ * Before, every app drew its own field and listened for the keys itself.
+ * A `search` of the caller's own still takes the centre.
+ *
+ * **A click leaves focus where it was**, as Peek's field did: what searching
+ * opens often acts on what you were in — Peek's launcher reads the composer
+ * you were typing in and its selection — and taking focus would leave it
+ * nothing. Tab still reaches the field, and Enter or Space presses it.
  */
 export interface TopBarProps {
   variant?: 'solid' | 'floating' | 'inset'
@@ -28,15 +44,45 @@ export interface TopBarProps {
   menu?: ReactNode
   /** Beside the menu button: the app's logo mark, or its name as text. */
   logo?: ReactNode
-  /** The centre: a search field, or a launcher affordance — or nothing; the slot holds its place. */
+  /** The centre: something of the caller's own. Without it, and with `onSearch`, the bar draws its search field. */
   search?: ReactNode
+  /** What searching opens — the app's command launcher. Called on a click on the search field, and on Ctrl+K (Cmd+K) anywhere. */
+  onSearch?: () => void
+  /** The words in the bar's own search field. Default "Search…". */
+  searchPlaceholder?: string
   /** The right cluster — an `IdentityMenu` and its neighbours. */
   right?: ReactNode
   className?: string
 }
 
-export function TopBar({ variant = 'solid', menu, logo, search, right, className }: TopBarProps) {
+export function TopBar({ variant = 'solid', menu, logo, search, onSearch, searchPlaceholder = 'Search…', right, className }: TopBarProps) {
   const floating = variant === 'floating'
+  // The latest handler, so the key listener is set once rather than on every render.
+  const searchRef = useRef(onSearch)
+  useEffect(() => {
+    searchRef.current = onSearch
+  })
+  const searches = onSearch !== undefined
+  useEffect(() => {
+    if (!searches) return
+    const onKey = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+        event.preventDefault()
+        searchRef.current?.()
+      }
+    }
+    // @estiva-escape(no-hand-rolled-behaviour): Ctrl+K opens search from anywhere on the page, which is a page-wide shortcut and not a floating part; no part listens for a key across the page
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [searches])
+  const centre =
+    search ??
+    (onSearch && (
+      <BaseButton type="button" onMouseDown={(event) => event.preventDefault()} onClick={onSearch} className={cn('flex w-[290px] cursor-pointer items-center gap-2 px-3 py-2', FIELD_SHELL_CLASSES)}>
+        <span className="min-w-0 flex-1 truncate text-left text-input-value text-text-muted">{searchPlaceholder}</span>
+        <Kbd>{shortcutLabel('Mod-K')}</Kbd>
+      </BaseButton>
+    ))
   return (
     <header
       className={cn(
@@ -53,7 +99,7 @@ export function TopBar({ variant = 'solid', menu, logo, search, right, className
           {logo && <div className="flex items-center text-body-2-strong text-text-primary">{logo}</div>}
         </div>
       )}
-      <div className={cn('flex min-w-0 flex-1 items-center justify-center', floating && 'pointer-events-auto')}>{search}</div>
+      <div className={cn('flex min-w-0 flex-1 items-center justify-center', floating && 'pointer-events-auto')}>{centre}</div>
       <div className={cn('flex shrink-0 items-center gap-[6px]', floating && 'pointer-events-auto')}>{right}</div>
     </header>
   )

package/src/index.ts

@@ -9,6 +9,7 @@
  * `src/` still ships in the tarball, so stepping into a component lands on the
  * TypeScript that produced it.
  */
+export { AppProvider, type AppProviderProps } from './AppProvider'
 export { AppShell, type AppShellProps } from './AppShell'
 export { AttachmentCard, type AttachmentCardProps, type AttachmentCardState } from './AttachmentCard'
 export { Avatar, hueFor, initialsFor, type AvatarProps } from './Avatar'

package/src/pages.test.ts

@@ -37,6 +37,8 @@ const NOT_A_ROW = ['base-ui']
 const WAITING: string[] = []
 
 const NOTHING = 'Nothing. It only draws. Clicks and keys are yours.'
+/** A part that draws nothing at all says so instead: it only holds what the parts below it ask for. */
+const HOLDS_ONLY: Record<string, string> = { AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.' }
 
 const dir = new URL('.', import.meta.url)
 const read = (file: string) => readFileSync(new URL(file, dir), 'utf8').replace(/\r\n/g, '\n')
@@ -134,7 +136,7 @@ describe('the page contract', () => {
         const body = (section(t, 'What it owns') ?? '').trim()
         if (!rows.length) {
           expect(owned, `${page} owns ${owned.join(', ')}; the page says nothing`).toEqual([])
-          expect(body).toBe(NOTHING)
+          expect(body).toBe(HOLDS_ONLY[page] ?? NOTHING)
           return
         }
         const said = rows.flatMap((r) => Object.entries(ROW).filter(([, re]) => re.test(r.does)).map(([id]) => ({ id, ticked: r.ticked, does: r.does })))

package/src/registry/app.test.ts

@@ -103,7 +103,10 @@ const FIXTURE: Record<string, string> = {
     '  return <li>{title}</li>',
     '}',
     '',
-    '/** A card that lists its rows and a button. */',
+    '/**',
+    ' * A card that lists its rows and a button.',
+    " * @registry namesake: the fixture's own card",
+    ' */',
     'export function Card({ title }: CardProps) {',
     '  return <ul><CardRow title={title} /><Button>Go</Button></ul>',
     '}',
@@ -128,7 +131,7 @@ const FIXTURE: Record<string, string> = {
   'src/components/Shown.tsx': '/** A part only its story uses. */\nexport function Shown() {\n  return <span />\n}\n',
   'src/components/Shown.stories.tsx': "import { Shown } from './Shown'\nconst meta = { title: 'Shown', component: Shown }\nexport default meta\nexport const Plain = {}\n",
   'src/components/Wide.tsx': '/**\n * A general strip of things.\n * @registry reusable: general; one screen uses it so far\n */\nexport function Wide() {\n  return <div />\n}\n',
-  'src/components/EmptyState.tsx': "import { EmptyState as Shared } from '@estiva-app/ui'\n\n/** The package's empty state, with this app's own default words. */\nexport function EmptyState() {\n  return <Shared message=\"Nothing here\" />\n}\n",
+  'src/components/EmptyState.tsx': "import { EmptyState as Shared } from '@estiva-app/ui'\n\n/**\n * The package's empty state, with this app's own default words.\n * @registry namesake: the words are this app's\n */\nexport function EmptyState() {\n  return <Shared message=\"Nothing here\" />\n}\n",
   'src/pages/Lazy.tsx': '/** A page loaded only when it is opened. */\nexport default function Lazy() {\n  return <main />\n}\n',
   'src/pages/HomePage.tsx': [
     "import { lazy } from 'react'",
@@ -287,7 +290,7 @@ describe('what the first descriptions found', () => {
   const faults = buildAppRegistry({
     root: app({
       // Peek's Skeleton.tsx: imported from the package, then exported on a line of its own.
-      'src/Skeleton.tsx': "import { SkeletonBar, SkeletonRow, SkeletonList as Shared } from '@estiva-app/ui'\n\n/** Grey rows in the shape of a list, while it loads. */\nexport function SkeletonList() {\n  return <div><SkeletonBar /><SkeletonRow /></div>\n}\n\n/** Peek's name for the package's list placeholder. */\nexport const SkeletonSidebarList = Shared\n\nexport { SkeletonBar, SkeletonRow }\n",
+      'src/Skeleton.tsx': "import { SkeletonBar, SkeletonRow, SkeletonList as Shared } from '@estiva-app/ui'\n\n/**\n * Grey rows in the shape of a list, while it loads.\n * @registry namesake: the fixture says so\n */\nexport function SkeletonList() {\n  return <div><SkeletonBar /><SkeletonRow /></div>\n}\n\n/** Peek's name for the package's list placeholder. */\nexport const SkeletonSidebarList = Shared\n\nexport { SkeletonBar, SkeletonRow }\n",
       // A file with its own description at the very top, and one on its part.
       'src/Row.tsx': "/**\n * Everything about rows.\n */\nimport { useState } from 'react'\n\n/** One row of a list, with a hover state of its own. */\nexport function Row() {\n  const [on] = useState(false)\n  return <li>{String(on)}</li>\n}\n",
       // A class, described above itself, with its props from what it extends.
@@ -397,10 +400,10 @@ describe('what the third review found', () => {
     root: app({
       'tsconfig.json': '{ "compilerOptions": { "baseUrl": "." } }\n',
       'src/Choice.tsx': "/** A choice, taken as text or as a number. */\nexport function Choice(props: { value: string }): JSX.Element\nexport function Choice(props: { value: number }): JSX.Element\nexport function Choice(props: { value: string | number }) {\n  return <span>{String(props.value)}</span>\n}\n",
-      'src/Kbd.tsx': '/** One key, drawn as a keycap. */\nexport function Kbd() {\n  return <kbd />\n}\n\n/** Keys in a row. */\nexport function KbdRow() {\n  return <span><Kbd /></span>\n}\n',
+      'src/Kbd.tsx': '/**\n * One key, drawn as a keycap.\n * @registry namesake: the fixture says so\n */\nexport function Kbd() {\n  return <kbd />\n}\n\n/** Keys in a row. */\nexport function KbdRow() {\n  return <span><Kbd /></span>\n}\n',
       'src/Guard.tsx': "import { Component } from 'react'\n\ninterface Props {\n  /** What it guards. */\n  label: string\n}\n\n/** Something else in the file. */\nexport function Other() {\n  return <i />\n}\n\n/** Catches what crashes below it. */\nexport default class extends Component<Props> {\n  render() {\n    return <div>{this.props.label}</div>\n  }\n}\n",
       'src/List.tsx': "import { memo } from 'react'\n\n/** One row of the list. */\nexport function Row() {\n  return <li />\n}\n\n/** The list, drawing its rows. */\nexport default memo(function List() {\n  return <ul><Row /></ul>\n})\n",
-      'src/parts/Card.tsx': '/** A card. */\nexport function Card() {\n  return <div />\n}\n',
+      'src/parts/Card.tsx': '/**\n * A card.\n * @registry namesake: the fixture says so\n */\nexport function Card() {\n  return <div />\n}\n',
       'src/parts/index.ts': "export * as Parts from './Card'\n",
       'src/UsesCard.tsx': "import { Parts } from './parts'\n\n/** Draws a card through a namespace. */\nexport function UsesCard() {\n  return <Parts.Card />\n}\n",
       'src/Badge.tsx': '/** A small badge. */\nexport function Badge() {\n  return <b />\n}\n',
@@ -414,7 +417,7 @@ describe('what the third review found', () => {
       // Found by the narrow pass on those fixes.
       'src/routesTable.ts': 'export const routes: unknown[] = []\n',
       'src/router.tsx': "import { createBrowserRouter } from 'react-router-dom'\nimport { routes } from './routesTable'\n\nexport default createBrowserRouter(routes)\n",
-      'src/Chip.tsx': "import { forwardRef, memo, type ComponentType } from 'react'\n\n/** A chip nothing uses. */\nexport function Chip() {\n  return <i />\n}\n\nexport default memo(forwardRef(Chip)) as ComponentType\n",
+      'src/Chip.tsx': "import { forwardRef, memo, type ComponentType } from 'react'\n\n/**\n * A chip nothing uses.\n * @registry namesake: the fixture says so\n */\nexport function Chip() {\n  return <i />\n}\n\nexport default memo(forwardRef(Chip)) as ComponentType\n",
     }),
     repo: 'third',
     packageRegistry,
@@ -513,6 +516,21 @@ describe('an app the catalogue refuses', () => {
     expect(refused({ 'src/One.tsx': '/**\n * One.\n * @registry unused: gone\n */\nexport function One() {\n  return <i />\n}\n' })).toMatch(/the kinds a person may write are reusable, one-off, promote-candidate/)
   })
 
+  it("a part with a package part's name and no reason it is kept", () => {
+    const pill = "import { Button } from '@estiva-app/ui'\n\n/** Who is in this. */\nexport function EmptyState() {\n  return <Button>3</Button>\n}\n"
+    expect(refused({ 'src/EmptyState.tsx': pill })).toContain(
+      `EmptyState in src/EmptyState.tsx has the name of the package's EmptyState. Use the package's, or write why this one is kept: "@registry namesake: <reason>" in its /** … */ comment.`,
+    )
+    // The reason, and nothing else, lets it through; a kind written beside it still counts.
+    const kept = pill.replace('/** Who is in this. */', '/**\n * Who is in this.\n * @registry reusable: general\n * @registry namesake: the words are this app\'s\n */')
+    expect(refused({ 'src/EmptyState.tsx': kept })).toBe('')
+    expect(refused({ 'src/EmptyState.tsx': pill.replace('Who is in this.', 'Who is in this. @registry namesake:') })).toMatch(/has the name of the package's EmptyState/)
+  })
+
+  it("not a pass-on of the package's own part", () => {
+    expect(refused({ 'src/EmptyState.tsx': "export { EmptyState } from '@estiva-app/ui'\n" })).toBe('')
+  })
+
   it('export * from a package, which hides what it hands on', () => {
     expect(refused({ 'src/All.tsx': "export * from '@estiva-app/ui'\n" })).toMatch(/hands on everything from '@estiva-app\/ui' with export \*/)
   })

package/src/registry/app.ts

@@ -31,6 +31,18 @@
  *      * @registry reusable: general; one screen uses it so far
  *      *\/
  *
+ * A part that shares its name with a package part is refused unless the reason
+ * it is kept is written beside it, the same way:
+ *
+ *     /**
+ *      * The package's `Avatar`, handed the picture this app knows about.
+ *      * @registry namesake: the package cannot know where pictures come from
+ *      *\/
+ *
+ * Peek's own MembersPill stayed in two headers for two days after the package
+ * gained one (0.58.0, 6 October) — built from the package's parts, so no rule
+ * saw it (Katerina, 8 October).
+ *
  * TypeScript is the app's own install, as it is for the package's builder.
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
@@ -54,7 +66,9 @@ export interface AppBuildOptions {
 
 /** The kinds a person may write beside a part. A pass-on is a fact about its file; so is being used nowhere. */
 const WRITABLE: EntryClass[] = ['reusable', 'one-off', 'promote-candidate']
-const WRITTEN = /^@registry\s+([a-z-]+)\s*:\s*(.+)$/m
+const WRITTEN = /^@registry\s+(?!namesake\b)([a-z-]+)\s*:\s*(.+)$/m
+/** Why a part with a package part's name is kept: `@registry namesake: <reason>`. */
+const NAMESAKE = /^@registry\s+namesake\s*:\s*\S/m
 
 const isStory = (file: string) => /\.stories\.[cm]?[jt]sx?$/.test(file)
 const isTest = (file: string) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(file) || /(^|\/)__(tests|mocks)__\//.test(file)
@@ -837,6 +851,11 @@ export function buildAppRegistry({ root = process.cwd(), repo, packageRegistry,
       reason = `Used in ${usedIn.length} places, and everything it uses is already in the package.`
     }
 
+    const namesake = namesakes.has(p.name) && !(pass && isPackageImport(pass.specifier) && pass.name === p.name) ? p.name : null
+    if (namesake && !(NAMESAKE.test(doc) || (onePart && NAMESAKE.test(header)))) {
+      problems.push(`${p.name} in ${p.file} has the name of the package's ${namesake}. Use the package's, or write why this one is kept: "@registry namesake: <reason>" in its /** … */ comment.`)
+    }
+
     const shape: Resolved = declared ? module!.resolve(declared.propsType) : { props: [], variants: [] }
     const facts_: AppFacts = {
       class: cls,
@@ -845,7 +864,7 @@ export function buildAppRegistry({ root = process.cwd(), repo, packageRegistry,
       handsOn: pass ? (isPackageImport(pass.specifier) ? pass.name : `${pass.name} from ${pass.specifier}`) : null,
       usedIn,
       tiedTo: ties,
-      packageNamesake: namesakes.has(p.name) && !(pass && isPackageImport(pass.specifier) && pass.name === p.name) ? p.name : null,
+      packageNamesake: namesake,
       defaultExport: p.defaultExport,
     }
     const found = pass ? { docsId: null, storyId: null } : storyOf(p)

package/src/registry/contract.test.ts

@@ -70,7 +70,7 @@ const PAGE = [
 ].join('\n')
 
 const part = (name: string, cls = 'reusable') =>
-  `/**\n * ${name}, for the fixture.\n * @registry ${cls}: the fixture says so\n */\nexport function ${name}() {\n  return <span>${name}</span>\n}\n`
+  `/**\n * ${name}, for the fixture.\n * @registry ${cls}: the fixture says so\n * @registry namesake: the fixture says so\n */\nexport function ${name}() {\n  return <span>${name}</span>\n}\n`
 
 describe('a usage page', () => {
   it('keeps the contract with an opening line and the four sections in order', () => {

package/src/registry/gated.test.ts

@@ -38,6 +38,7 @@ const find = (dir: string) => gatedFindings(buildAppRegistry({ root: dir, repo:
 const card = `/**
  * A card.
  * @registry reusable: the fixture says so
+ * @registry namesake: the fixture says so
  */
 export function Card({ title, onReply, onShare }: { title: string; onReply?: () => void; onShare?: () => void }) {
   return (

package/src/registry/registry.test.ts

@@ -48,19 +48,19 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 133 names over 72 files: 103 components, 29 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, and ShowMore on 7 October)', () => {
+  it('counts 134 names over 73 files: 104 components, 29 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, and AppProvider on 8 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The ten `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 103, helper: 29, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(72)
+    expect(kinds).toEqual({ component: 104, helper: 29, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(73)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(68)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(69)
     expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(65)
   })
 

package/stories/Choosing.mdx

@@ -122,10 +122,12 @@ the **floating** TopBar goes with the **Rail** and the content card.
 | The structured frame: solid bar, sidebar, content | **AppShell** `solid` |
 | The floating frame: bar over the content, rail, rounded card | **AppShell** `floating` |
 | The 52px bar alone | **TopBar** — `solid` in flow, or `floating` over the content |
+| A search field in the bar that opens your launcher, with Ctrl+K | the TopBar's `onSearch` — the bar draws the field |
 | A 240px navigation column | **Sidebar**, filled with **NavItem** rows |
 | Groups of rows in that column, rows under rows, from one nested list | **NavTree**, inside the **Sidebar** |
 | A 64px icon strip | **Rail**, filled with **RailItem** tiles |
 | The menu button and the logo | the TopBar's `menu` and `logo` slots — collapsing stays yours |
+| Where pictures come from, and how to change page without a reload, said once | **AppProvider**, around the whole app |
 | The list beside the thing that is open | **ListColumn** — 290px, its name in a **ContainerHeader**, the list under it scrolling |
 | A panel of a page that is not a list — details, a thread, what is open — with a body that must never be cut off | **Panel** — a header, a body that scrolls whenever it is taller, and a `footer` that stays put |